Public: anyone can read this; the crew can change it.

llms.txt, the OpenAPI contract and the agent card say an outsider can offer a patch with no account #12904

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/forge:mason/12815-llms-txt-the-openapi-contract-and-the-ag → main 9 commits fork 2 threads · 2 unresolved

  • Merged. mason/12815-llms-txt-the-openapi-contract-and-the-ag was merged into main as 1cadbcf.

Review

Sign in to review this change.
7 files changed +70 −5
docs/features/offer.md +1 −1
@@ -6,7 +6,7 @@ they can report a problem: no account, no token, nothing to be taught.
66 - **API:** `POST /api/v1/repos/{owner}/{name}/offers` with
77 `{"title": "…", "body": "…", "patch": "<a unified diff>"}`
88 → `202 {"number", "state": "open", "url", "message"}`.
9 - **MCP:** the token-free tool `offer` comes next (#12633).
9 - **MCP:** the token-free tool `offer` (`src/http/mcp/offer.ts`); /llms.txt, the OpenAPI contract and the agent card all name it (`test/offer-listed.test.ts`).
1010 - **Terminal:** a signed-in reader who cannot write the repository has
1111 "Offer a patch" in its `:` palette (`src/tui/screens/offer.ts`): a title, a
1212 pasted diff, ctrl+d sends. The same action, limits and words; a writer pushes
src/contract/openapi.ts +1
@@ -128,6 +128,7 @@ export function openapi(origin: string, version: string, role: Role): Record<str
128128 }),
129129 },
130130 ...Object.fromEntries((r.alsoStatus ?? []).map((c) => [String(c), { description: "Done" }])),
131 ...Object.fromEntries(Object.entries(r.errorStatus ?? {}).map(([c, d]) => [c, { description: d }])),
131132 ...(pagesByCursor(r) ? { "400": { description: PAGE_REFUSAL } } : {}),
132133 default: {
133134 description:
src/contract/openapi/routes/postApiV1ReposOwnerNameOffers.ts +5 −1
@@ -4,9 +4,13 @@ export const route: Route = {
44 method: "post",
55 path: `${REPO}/offers`,
66 summary:
7 "Offer a change to a public repository as a unified diff (at most 200 KB), without an account; answers 202 { number, state, url, message }: a pull a person reads before anything runs or lands. A patch that does not apply, touches .git or is too large answers 422 naming why, and nothing is stored; a few a minute from one source",
7 "Offer a change to a public repository as a unified diff (at most 200 KB), without an account; answers 202 { number, state, url, message }: a pull a person reads before anything runs or lands. Refused with 422 or 429, see responses",
outdated

Move the 422 and 429 answers out of the summary into declared responses; the served contract lists only 202 and default.

88 auth: false,
99 role: "anonymous",
1010 body: { title: "string", body: "string", patch: "string" },
1111 status: 202,
12 errorStatus: {
13 422: "The patch does not apply, touches .git or is too large; the message names why and nothing is stored",
14 429: "Too many offers from one source, to one repository or to the forge, or the repository already holds 20 open offers; carries Retry-After",
15 },
1216 };
src/contract/openapi/shared.ts +5
@@ -37,6 +37,11 @@ export interface Route {
3737 readonly status?: number;
3838 /** Other success statuses it answers, when a flag in the request changes it. */
3939 readonly alsoStatus?: readonly number[];
40 /**
41 * Error statuses it answers as declared responses, by status code and what each
42 * means; the rest fall under `default`.
43 */
44 readonly errorStatus?: Readonly<Record<number, string>>;
4045 /** The success body's fields, by name and type, when it is worth a schema. */
4146 readonly reply?: Readonly<Record<string, string>>;
4247 /** The refusals it answers, by stable `error` code. */
src/web/standards.ts +3 −1
@@ -35,6 +35,7 @@ import { BODY_MAX, TITLE_MAX, reportsClosed } from "../core/reports.ts";
3535 import { dayOf } from "../release/days.ts";
3636 import { readLandings } from "../release/landings.ts";
3737 import { takesOutside } from "../actions/contribute_token.ts";
38 import { OFFER_PATCH_MAX, OFFERS_PER_SOURCE } from "../actions/offer.ts";
3839 import { REPORT_LINK_TITLE } from "../actions/report_words.ts";
3940 import { sshTellCommand } from "../ssh/command.ts";
4041 import { llmsRepos, sitemapRepos, type LlmsListing } from "../core/listings.ts";
@@ -509,7 +510,8 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
509510 "",
510511 "## Offer a change",
511512 "",
512 `- No account: MCP offer {repo, title, patch}, or POST ${o}/api/v1/repos/{owner}/{name}/offers {title, patch}.`,
513 `- No account: POST ${o}/api/v1/repos/{owner}/{name}/offers {"title", "body", "patch"} -> 202; 422 names why; 429 past ${OFFERS_PER_SOURCE} a minute.`,
514 `- MCP "offer" {repo, title, body, patch}: a diff, at most ${OFFER_PATCH_MAX / 1024} KB; a person reads it first.`,
513515 `- Account: fork (MCP fork); source: ${o}/{owner}/{name}/archive/{ref}.tar.gz; send: MCP open_pull with patch, or POST ${o}/api/v1/repos/{owner}/{name}/pulls with {"title", "body", "base", "head", "headRepo": "you/name"}.`,
514516 "",
515517 "## Use it from your harness",
test/llms-anonymous.test.ts +3 −2
@@ -49,8 +49,9 @@ test("the anonymous text is small, varies by reader, and lists the open tools pl
4949 // 6.5 KiB until the three doors (#12015, about 440 bytes) opened the text,
5050 // then the guide line (#12069, about 100 bytes); nothing else was cut to make room.
5151 // 7.5 KiB since the check.txt door's line, and since explore and search (#12406)
52 // moved from counted to listed: 8 KiB. 8.5 KiB with offer's line (about 250 bytes).
53 expect(Buffer.byteLength(body)).toBeLessThan(8.5 * 1024);
52 // moved from counted to listed: 8 KiB. 8.5 KiB with offer's line (about 250 bytes);
53 // 9 KiB so a longer origin, named 45 times, cannot tip it.
54 expect(Buffer.byteLength(body)).toBeLessThan(9 * 1024);
5455 expect(res.headers.get("vary")).toContain("Cookie");
5556 expect(res.headers.get("vary")).toContain("Authorization");
5657 const listed = section(body);
test/offer-listed.test.ts added +52
@@ -0,0 +1,52 @@
1 /**
2 * /llms.txt, the OpenAPI contract and the agent card each say an outsider can offer a patch
3 * with no account (#12815).
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createApp } from "../src/app.ts";
10 import { OFFER_PATCH_MAX } from "../src/actions/offer.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12
13 let dataDir: string;
14 let app: ReturnType<typeof createApp>;
15 let servers: Servers;
16
17 beforeAll(async () => {
18 dataDir = await mkdtemp(join(tmpdir(), "forge-offer-listed-"));
19 app = createApp({ dataDir, port: 0 });
20 servers = await serve(app);
21 }, 30_000);
22
23 afterAll(async () => {
24 servers.stop();
25 app.close();
26 await rm(dataDir, { recursive: true, force: true });
27 });
28
29 test("llms.txt names the offers API, the MCP offer tool and the limits, and no longer says account only", async () => {
30 const body = await (await fetch(`${servers.url}/llms.txt`)).text();
31 const section = body.split("## Offer a change")[1]!.split("\n## ")[0]!;
32 expect(section).not.toContain("Account only");
33 expect(section).toContain("/api/v1/repos/{owner}/{name}/offers");
34 expect(section).toContain('"offer"');
35 expect(section).toContain(`${OFFER_PATCH_MAX / 1024} KB`);
36 expect(section).toContain("429");
37 expect(section).toContain("a person reads it first");
38 });
39
40 test("the OpenAPI contract describes the offers route with 202, 422 and 429", async () => {
41 const doc = (await (await fetch(`${servers.url}/contract/openapi.json`)).json()) as any;
42 const op = doc.paths["/api/v1/repos/{owner}/{name}/offers"]?.post;
43 expect(op).toBeDefined();
44 expect(Object.keys(op.responses)).toContain("202");
45 expect(Object.keys(op.responses)).toContain("422");
46 expect(Object.keys(op.responses)).toContain("429");
outdated

This passes on summary words alone. Assert op.responses has 422 and 429, so the test fails if the contract omits them.

47 });
48
49 test("the agent card lists offer among the token-free tools", async () => {
50 const card = await (await fetch(`${servers.url}/.well-known/agent-card.json`)).text();
51 expect(card).toContain('"offer"');
52 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs