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

Every MCP tool refusal says the one next thing to do #12454

Merged opened this

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

Merged

torque/forge:torque/12421-every-mcp-tool-refusal-says-the-one-next → main 5 commits fork 3 threads · 3 unresolved

  • Merged. torque/12421-every-mcp-tool-refusal-says-the-one-next was merged into main as c235449.

Review

Sign in to review this change.
28 files changed +256 −64
docs/MCP.md +4
@@ -676,3 +676,7 @@ closed, no agent, or tries used). `test/mcp-flow-drift-update.test.ts`.
676676 ## `hint` on a refused REST call (#10950)
677677
678678 Every 401, 403, 404, 409 and 422 JSON answer from `/api/v1` is `{ error, message, hint }`. `hint` is one fixed plain sentence saying what to do next. It never echoes request text, and a 404 `not_found` reads the same whether the resource is missing or private. `test/api-hints.test.ts` walks every OpenAPI route and fails when one lacks it.
679
680 ## "Next:" on a refused tool call (#12421)
681
682 Every refused `tools/call` text ends in `Next: …`, one step: which argument to fix, which sign-in to use, which tool to call first. A tool that has its own `Next:` keeps it; otherwise `withNextStep` (`src/http/mcp/hints.ts`) adds one from the error code and the tool's own schema, so a new tool is covered without editing. It never echoes arguments, tokens or another person's data. `test/mcp-refusal-hints.test.ts` calls every tool in `tools/list` (`all: true`, paged) with empty and bad arguments, as a member and as an admin, and the stranger's 401 and `report`/`start`.
src/http/mcp.ts +17 −11
@@ -42,6 +42,7 @@ import { claimDone, completeWrite, dropWrite, recordWrite } from "../core/conver
4242 import { type Args, alreadyDone, notAdminTool, visible, plansOnly, str, REPO_ARG, lean, fenceAnswer, heldWrite, askedFirst, readThrough } from "./mcp/shared.ts";
4343 import { CONVERSATION_BRIEF } from "../crew/conversation_brief.ts";
4444 import { TOOLS } from "./mcp/tools.ts";
45 import { READ_ONLY_REFUSAL, noToolNamed, withNextStep } from "./mcp/hints.ts";
4546 import { DEFAULT_TOOLS, wantsAll } from "./mcp/catalog.ts";
4647
4748 const PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"] as const;
@@ -220,11 +221,11 @@ function rpcOne(
220221 tool === undefined ? undefined : (askedFirst(ctx, user, tool, args) ?? heldWrite(ctx, user, tool, args));
221222 if (held !== undefined) return reply(held);
222223 if (tool === undefined || !visible(tool, ctx, user))
223 return refuse(-32602, `no tool named ${String(params["name"])}`);
224 return refuse(-32602, noToolNamed(String(params["name"])));
224225 if (tool.writes && !plansOnly(tool, args) && !scopeAllows(ctx.auth.scope ?? "ro", "rw"))
225226 return reply({
226227 content: [
227 { type: "text", text: "forbidden: this token may read, not act" },
228 { type: "text", text: READ_ONLY_REFUSAL },
228229 ],
229230 isError: true,
230231 });
@@ -256,7 +257,10 @@ function rpcOne(
256257 }
257258 : {
258259 content: [
259 { type: "text", text: `${answer.error}: ${answer.message}` },
260 {
261 type: "text",
262 text: `${answer.error}: ${withNextStep(tool, answer.error, answer.message)}`,
263 },
260264 ],
261265 isError: true,
262266 },
@@ -358,6 +362,8 @@ function reportCall(ctx: Ctx, message: unknown): unknown | undefined {
358362 return handler(ctx, m["id"], args);
359363 }
360364
365 const REPORT_NEXT = "Next: call `report` with `repo` as owner/name of a public repository and a `title`.";
366
361367 function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown {
362368 const text = (t: string, isError = false) => ({
363369 jsonrpc: "2.0",
@@ -370,7 +376,7 @@ function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown {
370376 ? getRepo(ctx.app.db, owner, name)
371377 : undefined;
372378 if (repo === undefined)
373 return text("not_found: no such public repository (owner/name)", true);
379 return text(`not_found: no such public repository. ${REPORT_NEXT}`, true);
374380 const filed = fileReport(
375381 ctx.app,
376382 repo,
@@ -387,12 +393,12 @@ function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown {
387393 const e = filed.error;
388394 return text(
389395 e.error === "not_found"
390 ? "not_found: no such public repository (owner/name)"
396 ? `not_found: no such public repository. ${REPORT_NEXT}`
391397 : e.error === "closed"
392 ? "reports_closed: the people who keep this repository have closed reports from outside"
398 ? "reports_closed: the people who keep this repository have closed reports from outside. Next: file nothing here; open the repository's page to reach its keepers."
393399 : e.error === "rate_limited"
394 ? `rate_limited: try again in ${e.retryAfter} seconds`
395 : `${e.error}: plain text, a title of 1-${TITLE_MAX} characters, a body of at most ${BODY_MAX}, agent a name of letters, digits, . _ -`,
400 ? `rate_limited: try again in ${e.retryAfter} seconds. Next: wait, then call \`report\` again.`
401 : `${e.error}: plain text, a title of 1-${TITLE_MAX} characters, a body of at most ${BODY_MAX}, agent a name of letters, digits, . _ -. Next: call \`report\` again with \`repo\` and \`title\` fixed.`,
396402 true,
397403 );
398404 }
@@ -416,16 +422,16 @@ async function startAnswer(ctx: Ctx, id: unknown, args: Args): Promise<unknown>
416422 if (made.ok) return text(JSON.stringify(made.value));
417423 const said = CONTRIBUTE_TOKEN_WORDS[made.error.error];
418424 return text(
419 `${made.error.error}: ${said}${made.error.retryAfter === undefined ? "" : ` (try again in ${made.error.retryAfter} seconds)`} ${CONTRIBUTE_TOKEN_HINT}`,
425 `${made.error.error}: ${said}${made.error.retryAfter === undefined ? "" : ` (try again in ${made.error.retryAfter} seconds)`} Next: ${CONTRIBUTE_TOKEN_HINT}`,
420426 true,
421427 );
422428 }
423 if (typeof args["name"] !== "string") return text(`invalid_name: ${START_WORDS.invalid_name} ${START_HINT}`, true);
429 if (typeof args["name"] !== "string") return text(`invalid_name: ${START_WORDS.invalid_name} Next: ${START_HINT}`, true);
424430 const started = await startBuilding(ctx.app, args, clientBucket(ctx.request), ctx.url.origin);
425431 if (started.ok) return text(JSON.stringify(started.value));
426432 const e = started.error;
427433 return text(
428 `${e.error}: ${START_WORDS[e.error]}${e.retryAfter === undefined ? "" : ` (try again in ${e.retryAfter} seconds)`} ${START_HINT}`,
434 `${e.error}: ${START_WORDS[e.error]}${e.retryAfter === undefined ? "" : ` (try again in ${e.retryAfter} seconds)`} Next: ${START_HINT}`,
429435 true,
430436 );
431437 }
src/http/mcp/hints.ts added +40
@@ -0,0 +1,40 @@
1 /**
2 * The one next step a refused tool call names (#12421). Built from the error code
3 * and the tool's own schema only, so it never repeats a secret or another person's data.
4 */
5
6 type Schema = { required?: readonly string[]; properties?: Record<string, unknown> };
7
8 /** The argument names a tool needs, or failing that the ones it takes. */
9 function argsOf(schema: unknown): string[] {
10 const s = (schema ?? {}) as Schema;
11 const names = s.required !== undefined && s.required.length > 0 ? s.required : Object.keys(s.properties ?? {});
12 return names.slice(0, 4);
13 }
14
15 /** `message` with a "Next:" step added unless it already carries one. */
16 export function withNextStep(tool: { name: string; inputSchema?: unknown }, code: string, message: string): string {
17 if (/\bnext:/i.test(message)) return message;
18 const name = `\`${tool.name}\``;
19 const args = argsOf(tool.inputSchema);
20 const list = args.length === 0 ? "" : ` (${args.map((a) => `\`${a}\``).join(", ")})`;
21 let step: string;
22 if (code === "forbidden" || code === "unauthorized")
23 step = "`whoami_can` says what this token and account may do; use one that may, or ask someone who can, and repeat the call.";
24 else if (code === "not_found")
25 step = `check the id or name against what a read of ${name} lists, or call \`find_tool\` for the tool that lists it, then repeat.`;
26 else if (code === "rate_limited" || code === "too_many")
27 step = `wait a few seconds and call ${name} again.`;
28 else if (code === "conflict" || code.startsWith("no_"))
29 step = `read the current state with ${name} or \`find_tool\` before trying again.`;
30 else step = `call ${name} again with its arguments${list} set as tools/list describes.`;
31 return `${message}${/[.!?]$/.test(message) ? "" : "."} Next: ${step}`;
32 }
33
34 /** What a read-only token is told when it tries to act. */
35 export const READ_ONLY_REFUSAL =
36 "forbidden: this token may read, not act. Next: mint a token with write scope in the account's token settings on the page (/settings/tokens), use it, and repeat the call.";
outdated

The tokens tool only lists tokens; it cannot mint one. Name a step that exists (mint a write-scope token in the account's token settings) and repeat the call.

37
38 /** What a name no tool answers to is told. */
39 export const noToolNamed = (name: string): string =>
40 `no tool named ${name}. Next: call tools/list, or \`find_tool\` with a word about what you want, for the names this token may call.`;
test/admin-words.test.ts +2 −2
@@ -66,7 +66,7 @@ describe("an admin's refusals, from every door", () => {
6666 expect(r.body).toMatchObject({ error: "not_allowed", message: ADMIN_WORDS.selfSuspend });
6767 const m = await mcp(admin, "account_suspend", { username: "alice", suspended: true });
6868 expect(m.error).toBe(true);
69 expect(m.text).toBe(`not_allowed: ${ADMIN_WORDS.selfSuspend}`);
69 expect(m.text).toStartWith(`not_allowed: ${ADMIN_WORDS.selfSuspend}`);
7070 });
7171
7272 // The API's admin rows meet the gate first (#12408): it names the admin sign-in.
@@ -82,6 +82,6 @@ describe("an admin's refusals, from every door", () => {
8282 expect(r.body).toMatchObject({ error: "not_admin", message: ADMIN_WORDS.signIn });
8383 const m = await mcp(person, "front_page", { pinned: [], hidden: [] });
8484 expect(m.error).toBe(true);
85 expect(m.text).toBe(`forbidden: ${ADMIN_WORDS.frontPage}`);
85 expect(m.text).toStartWith(`forbidden: ${ADMIN_WORDS.frontPage}`);
8686 });
8787 });
test/deadends.test.ts +1 −1
@@ -209,7 +209,7 @@ test("the findings are the known ones, and every known one still happens", async
209209 const KNOWN_WORDS: readonly string[] = [
210210 // The scan reads "the MCP tool spawn" and "the one tool open without a token" as a tool called "the" and "one".
211211 "tool the at src/core/roles.ts:53",
212 "tool one at src/http/mcp.ts:279",
212 "tool one at src/http/mcp.ts:283",
213213 // Dead: a preview's sample app runs a file its repository does not hold.
214214 "script src/server.ts at src/spawn/preview-seed.ts:816",
215215 ];
test/explore-unknown-words.test.ts +3 −3
@@ -164,9 +164,9 @@ describe("the page and the API", () => {
164164 const fine = await call("sort:forks");
165165 expect(fine.isError).toBe(false);
166166 expect(JSON.parse(fine.text)).toHaveProperty("items");
167 expect(await call("archived:maybe")).toEqual({ isError: true, text: "unknown_filter: archived:maybe is not an answer — use yes, no" });
168 expect(await call("updated:2y")).toEqual({ isError: true, text: "unknown_filter: updated:2y is not a window — use 1d, 7d, 30d" });
169 expect(await call("owner:a/b")).toEqual({ isError: true, text: "unknown_filter: owner:a/b is not a name" });
167 expect(await call("archived:maybe")).toEqual({ isError: true, text: expect.stringContaining("unknown_filter: archived:maybe is not an answer — use yes, no") });
168 expect(await call("updated:2y")).toEqual({ isError: true, text: expect.stringContaining("unknown_filter: updated:2y is not a window — use 1d, 7d, 30d") });
169 expect(await call("owner:a/b")).toEqual({ isError: true, text: expect.stringContaining("unknown_filter: owner:a/b is not a name") });
170170 });
171171 });
172172
test/explorer-make-it-yours.test.ts +2 −2
@@ -132,7 +132,7 @@ describe("explorer: make it yours", () => {
132132 expect(undone.says).toBe("bob/kiln is removed. The original was not touched.");
133133 expect(getRepo(app.db, "bob", "kiln")).toBeUndefined();
134134 // Nothing is left to undo.
135 expect(await said({ repo: "alice/kiln", undo: true })).toBe(
135 expect(await said({ repo: "alice/kiln", undo: true })).toStartWith(
136136 "not_found: nothing of yours was made from that app",
137137 );
138138 });
@@ -186,7 +186,7 @@ describe("explorer: make it yours", () => {
186186
187187 test("the MCP undo answers `changed` for a copy with commits of its own, and keeps it", async () => {
188188 // bob/garden has bob's own commit from the test above.
189 expect(await said({ repo: "alice/garden", undo: true })).toBe(
189 expect(await said({ repo: "alice/garden", undo: true })).toStartWith(
190190 "changed: bob/garden has changes of your own, so it is kept. Delete it in its settings if you mean to.",
191191 );
192192 expect(getRepo(app.db, "bob", "garden")).toBeDefined();
test/family-words.test.ts +2 −2
@@ -67,7 +67,7 @@ test("severing a repository that follows nothing answers the module's sentence a
6767 expect(res.status).toBe(404);
6868 expect(await res.json()).toMatchObject({ error: "not_following", message: FAMILY_WORDS.not_following });
6969 const mcp = await mcpTool(servers.url, token, "sever", { repo: "ada/lib" });
70 expect(mcp.error).toBe(`not_following: ${FAMILY_WORDS.not_following}`);
70 expect(mcp.error).toStartWith(`not_following: ${FAMILY_WORDS.not_following}`);
7171 });
7272
7373 test("showing a trail on a repository never migrated answers the module's sentence at both doors", async () => {
@@ -75,7 +75,7 @@ test("showing a trail on a repository never migrated answers the module's senten
7575 expect(res.status).toBe(422);
7676 expect(await res.json()).toMatchObject({ error: "no_provenance", message: FAMILY_WORDS.no_provenance });
7777 const mcp = await mcpTool(servers.url, token, "trail", { repo: "ada/lib", shown: true, dryRun: false });
78 expect(mcp.error).toBe(`no_provenance: ${FAMILY_WORDS.no_provenance}`);
78 expect(mcp.error).toStartWith(`no_provenance: ${FAMILY_WORDS.no_provenance}`);
7979 });
8080
8181 test("no file under src/ but the module types a family sentence", async () => {
test/feed-interact.test.ts +2 −2
@@ -178,7 +178,7 @@ describe("the route and MCP feed_dismiss refuse the same things", () => {
178178 const tool = await mcp(input);
179179 expect({ input, code: web.error }).toEqual({ input, code });
180180 expect(web.status).toBe(code === "not_found" ? 404 : 422);
181 expect(tool).toEqual({ isError: true, text: `${web.error}: ${web.message}` });
181 expect(tool).toEqual({ isError: true, text: expect.stringContaining(`${web.error}: ${web.message}`) });
182182 }
183183 });
184184
@@ -188,7 +188,7 @@ describe("the route and MCP feed_dismiss refuse the same things", () => {
188188 const tool = await mcp(input);
189189 expect(web.status).toBe(422);
190190 expect(web.error).toBe("invalid_kind");
191 expect(tool).toEqual({ isError: true, text: "invalid_kind: kind is one of dismissed, muted" });
191 expect(tool).toEqual({ isError: true, text: expect.stringContaining("invalid_kind: kind is one of dismissed, muted") });
192192 // The route records every act a card reports; the tool only dismisses or mutes.
193193 expect((await route({ item: openEvent, kind: "opened" })).status).toBe(201);
194194 expect((await mcp({ item: openEvent, kind: "opened" })).text).toStartWith("invalid_kind:");
test/limbs.test.ts +1 −1
@@ -696,7 +696,7 @@ describe("limb actions", () => {
696696 expect(
697697 (await tool(admin, { app: "alice/engine", action: "undo", operation: receipt["id"] }))
698698 .error,
699 ).toBe("invalid: undo is not a dry run: pass dryRun false");
699 ).toStartWith("invalid: undo is not a dry run: pass dryRun false");
700700 });
701701
702702 test("on the page: the actions for an admin only, a preview before anything is written, a receipt, and one undo", async () => {
test/mcp-assign.test.ts +3 −3
@@ -127,7 +127,7 @@ describe("MCP assign", () => {
127127 });
128128 expect(api.status).toBe(403);
129129 const apiBody: any = await api.json();
130 expect(got.error).toBe(`forbidden: ${apiBody.message}`);
130 expect(got.error).toStartWith(`forbidden: ${apiBody.message}`);
131131 expect(assigneeOf()).toBeNull();
132132 });
133133
@@ -141,13 +141,13 @@ describe("MCP assign", () => {
141141
142142 test("an assignee who cannot read the repository is refused, and the assignee stays", async () => {
143143 const got = await call(aliceTok, args("bob", { repo: "alice/hidden" }));
144 expect(got.error).toBe("assignee_cannot_read: the assignee cannot read this repository");
144 expect(got.error).toStartWith("assignee_cannot_read: the assignee cannot read this repository");
145145 expect(getIssue(app.db, hiddenId, 1)!.assigneeId).toBeNull();
146146 });
147147
148148 test("an agent off the crew is refused as the API refuses it", async () => {
149149 const got = await call(aliceTok, args("idle"));
150 expect(got.error).toBe("agent_not_on_crew: that agent is not on this repository's crew");
150 expect(got.error).toStartWith("agent_not_on_crew: that agent is not on this repository's crew");
151151 expect(assigneeOf()).toBeNull();
152152 });
153153
test/mcp-chapters-act.test.ts +2 −1
@@ -1,4 +1,5 @@
11 /** `repo` with `action`: open, fill and close a chapter through the MCP, previewed, receipted and refused in the page's words. */
2 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
23 import { afterAll, beforeAll, expect, test } from "bun:test";
34 import { mkdtemp, rm } from "node:fs/promises";
45 import { tmpdir } from "node:os";
@@ -96,7 +97,7 @@ test("a non-owner is refused in the page's words, confirmed or not", async () =>
9697 expect((await call(bob, { repo: "alice/pub", action: "close", chapter: "v1" })).error).toContain(CHAPTER_WORDS.forbidden);
9798 expect(listChapters(app.db, repo().id)[0]!.state).toBe("draft");
9899 const ro = await call(aliceRo, { repo: "alice/pub", action: "open", chapter: "v1", confirm: true });
99 expect(ro.error).toBe("forbidden: this token may read, not act");
100 expect(ro.error).toBe(READ_ONLY_REFUSAL);
100101 expect(listChapters(app.db, repo().id)[0]!.state).toBe("draft");
101102 });
102103
test/mcp-labels-update.test.ts +6 −5
@@ -1,4 +1,5 @@
11 /** `repo_labels` `action: "update"` renames and recolours a label as the labels page does, with its words. */
2 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
23 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
34 import { mkdtemp, rm } from "node:fs/promises";
45 import { tmpdir } from "node:os";
@@ -90,13 +91,13 @@ describe("MCP repo_labels update", () => {
9091 await call(admin, { repo: R, action: "create", name: "ui", color: "6b7280" });
9192 const [defect, ui] = await listed();
9293 const taken = await call(admin, { repo: R, action: "update", id: ui.id, name: "DEFECT" });
93 expect(taken.error).toBe(`taken: ${LABEL_WORDS.taken}`);
94 expect(taken.error).toStartWith(`taken: ${LABEL_WORDS.taken}`);
9495 const color = await call(admin, { repo: R, action: "update", id: ui.id, color: "red" });
95 expect(color.error).toBe(`invalid: ${LABEL_WORDS.shape}`);
96 expect(color.error).toStartWith(`invalid: ${LABEL_WORDS.shape}`);
9697 const blank = await call(admin, { repo: R, action: "update", id: ui.id, name: " " });
97 expect(blank.error).toBe(`invalid: ${LABEL_WORDS.shape}`);
98 expect(blank.error).toStartWith(`invalid: ${LABEL_WORDS.shape}`);
9899 const gone = await call(admin, { repo: R, action: "update", id: "nope", name: "x" });
99 expect(gone.error).toBe(`not_found: ${LABEL_WORDS.gone}`);
100 expect(gone.error).toStartWith(`not_found: ${LABEL_WORDS.gone}`);
100101 expect((await call(admin, { repo: R, action: "update", id: ui.id })).error).toContain("invalid");
101102 expect((await call(admin, { repo: R, action: "update", name: "x" })).error).toContain("invalid");
102103 expect(await listed()).toEqual([defect, ui]);
@@ -106,7 +107,7 @@ describe("MCP repo_labels update", () => {
106107 const before = await listed();
107108 const id = before[0].id;
108109 expect((await call(ro, { repo: R, action: "update", id, name: "x" })).error).toBe(
109 "forbidden: this token may read, not act",
110 READ_ONLY_REFUSAL,
110111 );
111112 expect((await call(adminRw, { repo: R, action: "update", id, name: "x" })).error).toContain("admin token");
112113 expect((await call(bob, { repo: R, action: "update", id, name: "x" })).error).toContain("not_found");
test/mcp-parent-unreachable.test.ts +1 −1
@@ -162,7 +162,7 @@ describe("MCP proposes to a parent forge that does not answer", () => {
162162 test("a writer is told the parent is unreachable and nothing is recorded", async () => {
163163 const r = await call(writer);
164164 expect(r.error).toBe(true);
165 expect(r.text).toBe("parent_unreachable: parent unreachable: nothing was proposed");
165 expect(r.text).toStartWith("parent_unreachable: parent unreachable: nothing was proposed");
166166 expect(proposals()).toBe(0);
167167 });
168168
test/mcp-preview.test.ts +1 −1
@@ -218,7 +218,7 @@ describe("MCP preview", () => {
218218 const hidden = await tool(bobRw, { url: host(`hello--${sealedPull}`) });
219219 expect(hidden.error).toContain(`no pull #${sealedPull}`);
220220 const viaPull = await call(bobRw, "pull", { repo: "alice/hello", number: sealedPull });
221 expect(viaPull.error).toBe(hidden.error);
221 expect(String(viaPull.error).split(". Next:")[0]).toBe(String(hidden.error).split(". Next:")[0]);
222222 });
223223
224224 test("it is listed in tools/list", async () => {
test/mcp-refusal-hints.test.ts added +133
@@ -0,0 +1,133 @@
1 /**
2 * Every MCP tool refusal names the one next step (#12421): called with an empty
3 * and with a bad argument object, as a stranger and as a signed-in member.
4 * The tools come from tools/list, so a new tool is covered without editing this.
5 */
6 import { afterAll, beforeAll, expect, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { createApp, type App } from "../src/app.ts";
11 import { createToken } from "../src/core/tokens.ts";
12 import { createUser } from "../src/core/users.ts";
13 import { serve, type Servers } from "../src/http/server.ts";
14 import { READ_ONLY_REFUSAL, withNextStep } from "../src/http/mcp/hints.ts";
15 import { quietLogs } from "./helpers/globals.ts";
16
17 quietLogs();
18 let dir: string, app: App, servers: Servers, member: string, admin: string;
19 const SECRET = "a-good-passphrase";
20
21 const rpc = async (tok: string | undefined, method: string, params: object = {}) => {
22 const res = await fetch(`${servers.url}/mcp`, {
23 method: "POST",
24 headers: {
25 "content-type": "application/json",
26 accept: "application/json, text/event-stream",
27 ...(tok === undefined ? {} : { authorization: `Bearer ${tok}` }),
28 },
29 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
30 });
31 return { status: res.status, body: (await res.json()) as any };
32 };
33 const names = async (tok: string): Promise<string[]> => {
34 const out: string[] = [];
35 let cursor: string | undefined;
36 do {
37 const { body } = await rpc(tok, "tools/list", { all: true, ...(cursor === undefined ? {} : { cursor }) });
outdated

STEP accepts Authorization: Bearer, so a tool refusal without Next: can pass. Require Next: for tool refusals.

38 out.push(...body.result.tools.map((t: any) => t.name));
39 cursor = body.result.nextCursor;
40 } while (cursor !== undefined);
41 return out;
42 };
43
44 // A tool refusal says "Next: ..."; only the stranger's 401 is judged by its sign-in hint.
45 const STEP = /Next:/;
46 beforeAll(async () => {
47 dir = await mkdtemp(join(tmpdir(), "forge-mcp-hints-"));
48 app = createApp({ dataDir: dir, port: 0 });
49 servers = await serve(app);
50 const a = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: SECRET, adminIfFirst: true });
51 const b = await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: SECRET });
52 if (!a.ok || !b.ok) throw new Error("users");
53 admin = createToken(app.db, a.value.id, "t", "admin").token;
54 member = createToken(app.db, b.value.id, "t", "admin").token;
55 });
56 afterAll(async () => {
57 await servers.stop();
58 await rm(dir, { recursive: true, force: true });
59 });
60
61 test("a stranger's refusal says which sign-in, and what they may call", async () => {
62 const r = await rpc(undefined, "tools/call", { name: "plan", arguments: {} });
63 expect(r.status).toBe(401);
64 expect(r.body.hint).toContain("Authorization: Bearer");
65 expect(r.body.hint).toContain("report");
66 });
67
68 test("a stranger calling every listed tool is refused with the sign-in, or answered by report and start", async () => {
69 const list = await names(member);
70 expect(list.length).toBeGreaterThan(20);
71 await Promise.all(
72 list.flatMap((name) =>
73 [{}, { nope: 1 }].map(async (args) => {
74 const r = await rpc(undefined, "tools/call", { name, arguments: args });
75 if (name === "report" || name === "start") {
76 const text = String(r.body.result?.content?.[0]?.text ?? "");
77 expect(r.body.result?.isError).toBe(true);
78 expect(text).toMatch(STEP);
79 return;
outdated

Non-error answers are skipped and the stranger runs only plan, report and start. Cover every listed tool as a stranger too (box 1).

80 }
81 expect(r.status).toBe(401);
82 expect(r.body.hint).toContain("Authorization: Bearer");
83 }),
84 ),
85 );
86 });
87
88 test("withNextStep gives each error code its own step, and keeps a step already there", () => {
89 const tool = { name: "widget", inputSchema: { required: ["id", "repo"] } };
90 const step = (code: string) => withNextStep(tool, code, "said");
91 expect(step("forbidden")).toContain("`whoami_can`");
92 expect(step("unauthorized")).toContain("`whoami_can`");
93 expect(step("not_found")).toContain("check the id or name");
94 expect(step("rate_limited")).toContain("wait a few seconds and call `widget` again");
95 expect(step("conflict")).toContain("read the current state with `widget`");
96 expect(step("no_agent")).toContain("read the current state with `widget`");
97 expect(step("invalid")).toContain("call `widget` again with its arguments (`id`, `repo`)");
98 for (const code of ["forbidden", "not_found", "rate_limited", "conflict", "invalid"]) expect(step(code)).toMatch(/^said\. Next: /);
99 expect(withNextStep(tool, "invalid", "bad. Next: do this.")).toBe("bad. Next: do this.");
100 expect(READ_ONLY_REFUSAL).toContain("/settings/tokens");
101 expect(READ_ONLY_REFUSAL).not.toContain("`tokens` tool");
102 });
103
104 const bad: object[] = [{}, { nope: 1 }, { repo: 42, kind: "zzz", id: -1, name: {}, q: [] }];
105
106 // One test per token, calls in parallel, so each stays inside the 2 s test budget.
107 const walk = async (label: string, tok: string): Promise<string[]> => {
108 const missing: string[] = [];
109 const list = await names(tok);
110 expect(list.length).toBeGreaterThan(20);
111 const calls = list.flatMap((name) => bad.map((args) => ({ name, args })));
112 for (let i = 0; i < calls.length; i += 40) {
113 await Promise.all(
114 calls.slice(i, i + 40).map(async ({ name, args }) => {
115 const r = await rpc(tok, "tools/call", { name, arguments: args });
116 const res = r.body.result;
117 const text = res === undefined ? String(r.body.error?.message ?? "") : String(res.content?.[0]?.text ?? "");
118 if (res !== undefined && res.isError !== true) return; // an answer, not a refusal
119 if (text.length < 25 || !STEP.test(text)) missing.push(`${label} ${name} ${JSON.stringify(args)} -> ${text}`);
120 for (const secret of [tok, SECRET, "[email protected]", "[email protected]"]) expect(text).not.toContain(secret);
121 }),
122 );
123 }
124 return missing;
125 };
126
127 test("a member's refusals name the next step, for every listed tool", async () => {
128 expect(await walk("member", member)).toEqual([]);
129 }, 120000);
130
131 test("an admin's refusals name the next step, for every listed tool", async () => {
132 expect(await walk("admin", admin)).toEqual([]);
133 }, 120000);
test/mcp-repo-labels.test.ts +3 −2
@@ -1,4 +1,5 @@
11 /** `repo_labels` is the labels routes over MCP: the same actions, so the same gates. */
2 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
23 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
34 import { mkdtemp, rm } from "node:fs/promises";
45 import { tmpdir } from "node:os";
@@ -125,9 +126,9 @@ describe("MCP repo_labels", () => {
125126 expect(Array.isArray((await call(ro, { repo: R })).value.items)).toBe(true);
126127 expect(Array.isArray((await call(ro, { repo: R, action: "list" })).value.items)).toBe(true);
127128 const c = await call(ro, { repo: R, action: "create", name: "x" });
128 expect(c.error).toBe("forbidden: this token may read, not act");
129 expect(c.error).toBe(READ_ONLY_REFUSAL);
129130 const r = await call(ro, { repo: R, action: "remove", id: "nope" });
130 expect(r.error).toBe("forbidden: this token may read, not act");
131 expect(r.error).toBe(READ_ONLY_REFUSAL);
131132 });
132133
133134 test("bad arguments are one-sentence refusals", async () => {
test/mcp-ro-refuses-writes.test.ts +3 −2
@@ -18,6 +18,7 @@
1818 * admin-scope tools are not listed to an `ro` token at all; the last test
1919 * holds that each is refused by name.
2020 */
21 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
2122 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
2223 import { mkdtemp, rm } from "node:fs/promises";
2324 import { tmpdir } from "node:os";
@@ -30,8 +31,8 @@ import { plansOnly } from "../src/http/mcp/shared.ts";
3031 import { TOOLS } from "../src/http/mcp/tools.ts";
3132 import { serve, type Servers } from "../src/http/server.ts";
3233 import { listAt } from "./mcp-list.ts";
34 const REFUSAL = READ_ONLY_REFUSAL;
3335
34 const REFUSAL = "forbidden: this token may read, not act";
3536 const REPO = "alice/game";
3637 /**
3738 * The forge's own traffic counts: every request adds to them, flushed by a
@@ -178,7 +179,7 @@ describe("every MCP tool that writes refuses a read-only token", () => {
178179 expect({ name: t.name, isError: got.isError, text: got.text }).toEqual({
179180 name: t.name,
180181 isError: true,
181 text: `no tool named ${t.name}`,
182 text: expect.stringContaining(`no tool named ${t.name}. Next:`),
182183 });
183184 expect(moved(before, rows())).toEqual([]);
184185 }
test/mcp-take-back.test.ts +8 −7
@@ -1,4 +1,5 @@
11 /** MCP `take_back` (#7211): the pull page's take it back, through `/mcp` with a real token, in the page's words. */
2 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
23 import { afterAll, beforeAll, expect, test } from "bun:test";
34 import { mkdtemp, rm } from "node:fs/promises";
45 import { tmpdir } from "node:os";
@@ -97,27 +98,27 @@ const dir = () => repoDir(app.reposRoot, repo.ownerName, repo.name);
9798
9899 test("an agent token is refused in the page's words, and nothing is made", async () => {
99100 const refused = await takeBack(tok["bot"]!, { repo: "ada/svc", number: shipped.number });
100 expect(refused.error).toBe(`forbidden: That could not be taken back: ${takeBackWords("forbidden")}.`);
101 expect(refused.error).toStartWith(`forbidden: That could not be taken back: ${takeBackWords("forbidden")}.`);
101102 expect(await resolveOid(dir(), `refs/heads/revert-${shipped.number}`)).toBeUndefined();
102103 expect(revertOf(app.db, repo.id, shipped.id)).toBeUndefined();
103104 });
104105
105106 test("a read-only token cannot take a pull back", async () => {
106107 const refused = await takeBack(tok["ada-ro"]!, { repo: "ada/svc", number: shipped.number });
107 expect(refused.error).toBe("forbidden: this token may read, not act");
108 expect(refused.error).toBe(READ_ONLY_REFUSAL);
108109 expect(revertOf(app.db, repo.id, shipped.id)).toBeUndefined();
109110 });
110111
111112 test("an open pull has not shipped", async () => {
112113 const refused = await takeBack(tok["ada"]!, { repo: "ada/svc", number: open.number });
113 expect(refused.error).toBe(`not_shipped: That could not be taken back: ${takeBackWords("not_shipped")}.`);
114 expect(refused.error).toStartWith(`not_shipped: That could not be taken back: ${takeBackWords("not_shipped")}.`);
114115 });
115116
116117 test("a pull the caller cannot see, or no pull at all, is not found", async () => {
117118 expect((await takeBack(tok["sam"]!, { repo: "ada/svc", number: shipped.number })).error).toStartWith("not_found:");
118119 const none = await takeBack(tok["ada"]!, { repo: "ada/svc", number: 999 });
119 expect(none.error).toBe(`not_found: That could not be taken back: ${takeBackWords("not_found")}.`);
120 expect((await takeBack(tok["ada"]!, { repo: "ada/svc", number: "1" })).error).toBe(
120 expect(none.error).toStartWith(`not_found: That could not be taken back: ${takeBackWords("not_found")}.`);
121 expect((await takeBack(tok["ada"]!, { repo: "ada/svc", number: "1" })).error).toStartWith(
121122 `not_found: That could not be taken back: ${takeBackWords("not_found")}.`,
122123 );
123124 });
@@ -137,7 +138,7 @@ test("a shipped pull opens the pull that undoes it; a second call is already tak
137138 expect(revert.state).toBe("open");
138139
139140 const again = await takeBack(tok["ada"]!, { repo: "ada/svc", number: shipped.number });
140 expect(again.error).toBe(`already_reverted: That could not be taken back: ${takeBackWords("already_reverted")}.`);
141 expect(again.error).toStartWith(`already_reverted: That could not be taken back: ${takeBackWords("already_reverted")}.`);
141142 });
142143
143144 test("a revert that no longer applies is a conflict, and leaves nothing behind", async () => {
@@ -150,7 +151,7 @@ test("a revert that no longer applies is a conflict, and leaves nothing behind",
150151 const earlier = await ship("gamma", "alpha\nGAMMA\n");
151152 await ship("delta", "alpha\nDELTA\n");
152153 const refused = await takeBack(tok["ada"]!, { repo: "ada/svc", number: earlier.number });
153 expect(refused.error).toBe("conflict: That could not be taken back: it conflicts with the current code in code.txt.");
154 expect(refused.error).toStartWith("conflict: That could not be taken back: it conflicts with the current code in code.txt.");
154155 expect(await resolveOid(dir(), `refs/heads/revert-${earlier.number}`)).toBeUndefined();
155156 expect(revertOf(app.db, repo.id, earlier.id)).toBeUndefined();
156157 });
test/mcp-upstream.test.ts +1 −1
@@ -187,7 +187,7 @@ describe("MCP proposes to the parent forge and lists proposals", () => {
187187 const writer = createToken(child.db, kid.id, "rw", "rw").token;
188188 const none = await call(writer, "propose_to_parent_forge");
189189 expect(none.error).toBe(true);
190 expect(none.text).toBe("nothing_to_propose: nothing here is ahead of the parent forge");
190 expect(none.text).toStartWith("nothing_to_propose: nothing here is ahead of the parent forge");
191191 expect(JSON.parse((await call(writer, "forge_proposals")).text).items).toEqual([]);
192192 });
193193
test/mcp-wait-for.test.ts +1 −1
@@ -116,7 +116,7 @@ describe("wait_for over MCP", () => {
116116 const a2 = (await tool(rw, "tell", { repo: "alice/open", text: "x" })).value.issue;
117117 const b2 = (await tool(rw, "tell", { repo: "alice/open", text: "y" })).value.issue;
118118 const stranger = await tool(bobRw, "wait_for", { app: "alice/open", issue: b2, blockedBy: a2 });
119 expect(stranger.error).toBe("forbidden: You need write access, or a place on the crew, to plan here.");
119 expect(stranger.error).toStartWith("forbidden: You need write access, or a place on the crew, to plan here.");
120120 const map = (await tool(ro, "map", { app: "alice/game" })).value;
121121 expect(map.edges).not.toContainEqual({ issue: b, blockedBy: a });
122122 });
test/mcp-write-file.test.ts +3 −2
@@ -1,4 +1,5 @@
11 /** MCP `write_file`: a writer commits one file and reads it back; a read-only token is refused in the dispatcher's words; a path with `..` is refused. */
2 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
23 import { afterAll, beforeAll, expect, test } from "bun:test";
34 import { mkdtemp, rm } from "node:fs/promises";
45 import { tmpdir } from "node:os";
@@ -83,12 +84,12 @@ test("a writer commits and read_file reads it back", async () => {
8384
8485 test("a read-only token is refused in the dispatcher's words", async () => {
8586 const r = await call(tok["ro"]!, "write_file", args({ path: "d.txt" }));
86 expect(r.error).toBe("forbidden: this token may read, not act");
87 expect(r.error).toBe(READ_ONLY_REFUSAL);
8788 });
8889
8990 test("a path with .. is refused, and so is a branch that does not exist", async () => {
9091 const r = await call(tok["rw"]!, "write_file", args({ path: "../x.txt" }));
91 expect(r.error).toBe("invalid_path: that path cannot be written; use a plain relative path with no .. or .git");
92 expect(r.error).toStartWith("invalid_path: that path cannot be written; use a plain relative path with no .. or .git");
9293 expect((await call(tok["rw"]!, "write_file", args({ branch: "nope" }))).error).toContain("not_found");
9394 });
9495
test/mcp-write-scope.test.ts +2 −1
@@ -4,6 +4,7 @@
44 * `rw` one. The event log, every table's row count and every counter row
55 * outside `/mcp` stay as they were (see test/helpers/write-snapshot.ts).
66 */
7 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
78 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
89 import { mkdtemp, rm } from "node:fs/promises";
910 import { tmpdir } from "node:os";
@@ -135,7 +136,7 @@ describe("a token that may only read cannot write through any tool", () => {
135136 const text: string | undefined = body.result?.content?.[0]?.text;
136137 const refused = t.needsAdminScope
137138 ? notListed(body)
138 : body.result?.isError === true && text === "forbidden: this token may read, not act";
139 : body.result?.isError === true && text === READ_ONLY_REFUSAL;
139140 if (!refused) unrefused.push(t.name);
140141 }
141142 // A tool named here needs valid arguments in WRITE_ARGS: the generic ones only plan or read.
test/mcp.test.ts +5 −4
@@ -4,6 +4,7 @@
44 * action the pages call — so what a person may not do on a page they may
55 * not do here.
66 */
7 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
78 import { seatAs } from "./helpers/seat.ts";
89 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
910 import { chmodSync, writeFileSync } from "node:fs";
@@ -658,7 +659,7 @@ describe("the forge over MCP", () => {
658659 expect((await tool(rw, "close", { repo: "alice/game", number: own.number, state: "x" })).error).toContain("invalid_state");
659660 expect((await tool(rw, "close", { repo: "alice/game", number: own.number, reason: "x" })).error).toContain("invalid_reason");
660661 expect((await tool(rw, "close", { repo: "alice/game", number: own.number, into: [0] })).error).toContain("invalid_reason");
661 expect((await tool(ro, "close", { repo: "alice/game", number: own.number })).error).toContain("forbidden: this token may read, not act");
662 expect((await tool(ro, "close", { repo: "alice/game", number: own.number })).error).toContain(READ_ONLY_REFUSAL);
662663 });
663664
664665 test("issue reads body, comments, labels and what it waits for; a sealed one is not found; a reader is marked untrusted", async () => {
@@ -982,11 +983,11 @@ describe("the forge over MCP", () => {
982983 expect(
983984 (await tool(rw, "wait_for", { app: "alice/game", issue: a, blockedBy: b }))
984985 .error,
985 ).toBe("cycle: that would make a loop");
986 ).toStartWith("cycle: that would make a loop");
986987 expect(
987988 (await tool(rw, "wait_for", { app: "alice/game", issue: a, blockedBy: 999 }))
988989 .error,
989 ).toBe("no_such_issue: no issue #999");
990 ).toStartWith("no_such_issue: no issue #999");
990991 expect(
991992 (await tool(ro, "wait_for", { app: "alice/game", issue: a, blockedBy: b }))
992993 .error,
@@ -1179,7 +1180,7 @@ describe("the forge over MCP", () => {
11791180 body: JSON.stringify({ destination: dest }),
11801181 });
11811182 expect(api.status).toBe(403);
1182 expect(refused.error).toBe(`forbidden: ${((await api.json()) as any).message}`);
1183 expect(refused.error).toStartWith(`forbidden: ${((await api.json()) as any).message}`);
11831184
11841185 // An agent, even one marked site admin, may not change a grant.
11851186 const bot = await createAgent(app, alice, { username: "egressbot", brief: "x" });
test/milestones.test.ts +1 −1
@@ -501,7 +501,7 @@ describe("milestones", () => {
501501 ).toBe(404);
502502 expect(
503503 (await tool({ app: "alice/engine", issue: names.number })).error,
504 ).toBe("not_a_milestone: no issue by that number waits for others here");
504 ).toStartWith("not_a_milestone: no issue by that number waits for others here");
505505 // A reader's token gets the numbers without spend or names.
506506 const reader = createToken(
507507 app.db,
test/spawn-api.test.ts +2 −1
@@ -3,6 +3,7 @@
33 * tool. Dry-run is the default, an ro token plans and never makes, and a
44 * fake placement stands in for where the child lives.
55 */
6 import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts";
67 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
78 import { mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
89 import { tmpdir } from "node:os";
@@ -199,7 +200,7 @@ describe("spawn over the API and MCP", () => {
199200 expect(plan.error).toBe(false);
200201 expect(JSON.parse(plan.text)).toMatchObject({ dryRun: true, says: expect.stringContaining("nothing was made") });
201202 const denied = await mcp(ro, { name: "kid2", apps: ["alice/notes"], dryRun: false });
202 expect(denied).toEqual({ error: true, text: "forbidden: this token may read, not act" });
203 expect(denied).toEqual({ error: true, text: READ_ONLY_REFUSAL });
203204 // A non-admin person's rw token may plan via MCP (empty apps — no private reads).
204205 const asBob = await mcp(bobRw, { name: "bobs-kid2", apps: [] });
205206 expect(asBob.error).toBe(false);
test/spend-words.test.ts +4 −4
@@ -67,28 +67,28 @@ test("a grant out of range answers the module's sentence from the API and MCP",
6767 const viaApi = await api("/api/v1/admin/accounts/bob/model-grant", { usdPerMonth: 20000 });
6868 expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.usdPerMonth } });
6969 const viaMcp = await tool("model_grant", { username: "bob", usdPerMonth: 20000, dryRun: false });
70 expect(viaMcp).toMatchObject({ error: true, text: `invalid: ${SPEND_WORDS.usdPerMonth}` });
70 expect(viaMcp).toMatchObject({ error: true, text: expect.stringContaining(`invalid: ${SPEND_WORDS.usdPerMonth}`) });
7171 });
7272
7373 test("a role's allowance out of range answers the module's sentence from the API and MCP", async () => {
7474 const viaApi = await api("/api/v1/admin/accounts/bob/role", { role: "member", usdPerMonth: 20000 });
7575 expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.usdPerMonth } });
7676 const viaMcp = await tool("account_role", { username: "bob", role: "member", usdPerMonth: 20000, dryRun: false });
77 expect(viaMcp).toMatchObject({ error: true, text: `invalid: ${SPEND_WORDS.usdPerMonth}` });
77 expect(viaMcp).toMatchObject({ error: true, text: expect.stringContaining(`invalid: ${SPEND_WORDS.usdPerMonth}`) });
7878 });
7979
8080 test("a ceiling out of range answers the module's sentence from the API and MCP", async () => {
8181 const viaApi = await api("/api/v1/admin/accounts/bob/ceiling", { dailyUsd: 20000, perRunUsd: 1 });
8282 expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.ceilings } });
8383 const viaMcp = await tool("model_ceiling", { username: "bob", dailyUsd: 20000, perRunUsd: 1, dryRun: false });
84 expect(viaMcp).toMatchObject({ error: true, text: `invalid: ${SPEND_WORDS.ceilings}` });
84 expect(viaMcp).toMatchObject({ error: true, text: expect.stringContaining(`invalid: ${SPEND_WORDS.ceilings}`) });
8585 });
8686
8787 test("an invite's days out of range answers the module's sentence from the API and MCP", async () => {
8888 const viaApi = await api("/api/v1/admin/invites", { days: 31 });
8989 expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.inviteDays } });
9090 const viaMcp = await tool("mint_invite", { days: 31 });
91 expect(viaMcp).toMatchObject({ error: true, text: `invalid: ${SPEND_WORDS.inviteDays}` });
91 expect(viaMcp).toMatchObject({ error: true, text: expect.stringContaining(`invalid: ${SPEND_WORDS.inviteDays}`) });
9292 });
9393
9494 test("no file under src/ but the module types the sentences out", async () => {
test/thread-words.test.ts +3 −3
@@ -151,7 +151,7 @@ describe("label and plan refusals on a thread", () => {
151151 number: first,
152152 labels: ["nope"],
153153 }),
154 ).toBe(`unknown_label: ${THREAD_SAYS.unknownLabel}`);
154 ).toStartWith(`unknown_label: ${THREAD_SAYS.unknownLabel}`);
155155 });
156156
157157 test("a reader changing labels", async () => {
@@ -166,7 +166,7 @@ describe("label and plan refusals on a thread", () => {
166166 number: first,
167167 labels: ["bug"],
168168 }),
169 ).toBe(`forbidden: ${THREAD_SAYS.labelsForbidden}`);
169 ).toStartWith(`forbidden: ${THREAD_SAYS.labelsForbidden}`);
170170 });
171171
172172 test("a reader planning", async () => {
@@ -181,6 +181,6 @@ describe("label and plan refusals on a thread", () => {
181181 issue: second,
182182 blockedBy: first,
183183 }),
184 ).toBe(`forbidden: ${THREAD_SAYS.planForbidden}`);
184 ).toStartWith(`forbidden: ${THREAD_SAYS.planForbidden}`);
185185 });
186186 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs