Public: anyone can read this; the crew can change it.
Every MCP tool refusal says the one next thing to do #12454
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/12421-every-mcp-tool-refusal-says-the-one-next → main 5 commits fork 3 threads · 3 unresolved
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`. | ||
| 676 | 676 | ## `hint` on a refused REST call (#10950) |
| 677 | 677 | |
| 678 | 678 | 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 | ||
| 42 | 42 | import { type Args, alreadyDone, notAdminTool, visible, plansOnly, str, REPO_ARG, lean, fenceAnswer, heldWrite, askedFirst, readThrough } from "./mcp/shared.ts"; |
| 43 | 43 | import { CONVERSATION_BRIEF } from "../crew/conversation_brief.ts"; |
| 44 | 44 | import { TOOLS } from "./mcp/tools.ts"; |
| 45 | import { READ_ONLY_REFUSAL, noToolNamed, withNextStep } from "./mcp/hints.ts"; | |
| 45 | 46 | import { DEFAULT_TOOLS, wantsAll } from "./mcp/catalog.ts"; |
| 46 | 47 | |
| 47 | 48 | const PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"] as const; |
| @@ -220,11 +221,11 @@ function rpcOne( | ||
| 220 | 221 | tool === undefined ? undefined : (askedFirst(ctx, user, tool, args) ?? heldWrite(ctx, user, tool, args)); |
| 221 | 222 | if (held !== undefined) return reply(held); |
| 222 | 223 | 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"]))); | |
| 224 | 225 | if (tool.writes && !plansOnly(tool, args) && !scopeAllows(ctx.auth.scope ?? "ro", "rw")) |
| 225 | 226 | return reply({ |
| 226 | 227 | content: [ |
| 227 | { type: "text", text: "forbidden: this token may read, not act" }, | |
| 228 | { type: "text", text: READ_ONLY_REFUSAL }, | |
| 228 | 229 | ], |
| 229 | 230 | isError: true, |
| 230 | 231 | }); |
| @@ -256,7 +257,10 @@ function rpcOne( | ||
| 256 | 257 | } |
| 257 | 258 | : { |
| 258 | 259 | content: [ |
| 259 | { type: "text", text: `${answer.error}: ${answer.message}` }, | |
| 260 | { | |
| 261 | type: "text", | |
| 262 | text: `${answer.error}: ${withNextStep(tool, answer.error, answer.message)}`, | |
| 263 | }, | |
| 260 | 264 | ], |
| 261 | 265 | isError: true, |
| 262 | 266 | }, |
| @@ -358,6 +362,8 @@ function reportCall(ctx: Ctx, message: unknown): unknown | undefined { | ||
| 358 | 362 | return handler(ctx, m["id"], args); |
| 359 | 363 | } |
| 360 | 364 | |
| 365 | const REPORT_NEXT = "Next: call `report` with `repo` as owner/name of a public repository and a `title`."; | |
| 366 | ||
| 361 | 367 | function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown { |
| 362 | 368 | const text = (t: string, isError = false) => ({ |
| 363 | 369 | jsonrpc: "2.0", |
| @@ -370,7 +376,7 @@ function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown { | ||
| 370 | 376 | ? getRepo(ctx.app.db, owner, name) |
| 371 | 377 | : undefined; |
| 372 | 378 | 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); | |
| 374 | 380 | const filed = fileReport( |
| 375 | 381 | ctx.app, |
| 376 | 382 | repo, |
| @@ -387,12 +393,12 @@ function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown { | ||
| 387 | 393 | const e = filed.error; |
| 388 | 394 | return text( |
| 389 | 395 | e.error === "not_found" |
| 390 | ? "not_found: no such public repository (owner/name)" | |
| 396 | ? `not_found: no such public repository. ${REPORT_NEXT}` | |
| 391 | 397 | : 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." | |
| 393 | 399 | : 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.`, | |
| 396 | 402 | true, |
| 397 | 403 | ); |
| 398 | 404 | } |
| @@ -416,16 +422,16 @@ async function startAnswer(ctx: Ctx, id: unknown, args: Args): Promise<unknown> | ||
| 416 | 422 | if (made.ok) return text(JSON.stringify(made.value)); |
| 417 | 423 | const said = CONTRIBUTE_TOKEN_WORDS[made.error.error]; |
| 418 | 424 | 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}`, | |
| 420 | 426 | true, |
| 421 | 427 | ); |
| 422 | 428 | } |
| 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); | |
| 424 | 430 | const started = await startBuilding(ctx.app, args, clientBucket(ctx.request), ctx.url.origin); |
| 425 | 431 | if (started.ok) return text(JSON.stringify(started.value)); |
| 426 | 432 | const e = started.error; |
| 427 | 433 | 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}`, | |
| 429 | 435 | true, |
| 430 | 436 | ); |
| 431 | 437 | } |
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."; | |
| 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", () => { | ||
| 66 | 66 | expect(r.body).toMatchObject({ error: "not_allowed", message: ADMIN_WORDS.selfSuspend }); |
| 67 | 67 | const m = await mcp(admin, "account_suspend", { username: "alice", suspended: true }); |
| 68 | 68 | 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}`); | |
| 70 | 70 | }); |
| 71 | 71 | |
| 72 | 72 | // 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", () => { | ||
| 82 | 82 | expect(r.body).toMatchObject({ error: "not_admin", message: ADMIN_WORDS.signIn }); |
| 83 | 83 | const m = await mcp(person, "front_page", { pinned: [], hidden: [] }); |
| 84 | 84 | expect(m.error).toBe(true); |
| 85 | expect(m.text).toBe(`forbidden: ${ADMIN_WORDS.frontPage}`); | |
| 85 | expect(m.text).toStartWith(`forbidden: ${ADMIN_WORDS.frontPage}`); | |
| 86 | 86 | }); |
| 87 | 87 | }); |
test/deadends.test.ts +1 −1
| @@ -209,7 +209,7 @@ test("the findings are the known ones, and every known one still happens", async | ||
| 209 | 209 | const KNOWN_WORDS: readonly string[] = [ |
| 210 | 210 | // The scan reads "the MCP tool spawn" and "the one tool open without a token" as a tool called "the" and "one". |
| 211 | 211 | "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", | |
| 213 | 213 | // Dead: a preview's sample app runs a file its repository does not hold. |
| 214 | 214 | "script src/server.ts at src/spawn/preview-seed.ts:816", |
| 215 | 215 | ]; |
test/explore-unknown-words.test.ts +3 −3
| @@ -164,9 +164,9 @@ describe("the page and the API", () => { | ||
| 164 | 164 | const fine = await call("sort:forks"); |
| 165 | 165 | expect(fine.isError).toBe(false); |
| 166 | 166 | 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") }); | |
| 170 | 170 | }); |
| 171 | 171 | }); |
| 172 | 172 |
test/explorer-make-it-yours.test.ts +2 −2
| @@ -132,7 +132,7 @@ describe("explorer: make it yours", () => { | ||
| 132 | 132 | expect(undone.says).toBe("bob/kiln is removed. The original was not touched."); |
| 133 | 133 | expect(getRepo(app.db, "bob", "kiln")).toBeUndefined(); |
| 134 | 134 | // 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( | |
| 136 | 136 | "not_found: nothing of yours was made from that app", |
| 137 | 137 | ); |
| 138 | 138 | }); |
| @@ -186,7 +186,7 @@ describe("explorer: make it yours", () => { | ||
| 186 | 186 | |
| 187 | 187 | test("the MCP undo answers `changed` for a copy with commits of its own, and keeps it", async () => { |
| 188 | 188 | // 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( | |
| 190 | 190 | "changed: bob/garden has changes of your own, so it is kept. Delete it in its settings if you mean to.", |
| 191 | 191 | ); |
| 192 | 192 | 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 | ||
| 67 | 67 | expect(res.status).toBe(404); |
| 68 | 68 | expect(await res.json()).toMatchObject({ error: "not_following", message: FAMILY_WORDS.not_following }); |
| 69 | 69 | 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}`); | |
| 71 | 71 | }); |
| 72 | 72 | |
| 73 | 73 | 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 | ||
| 75 | 75 | expect(res.status).toBe(422); |
| 76 | 76 | expect(await res.json()).toMatchObject({ error: "no_provenance", message: FAMILY_WORDS.no_provenance }); |
| 77 | 77 | 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}`); | |
| 79 | 79 | }); |
| 80 | 80 | |
| 81 | 81 | 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", () => { | ||
| 178 | 178 | const tool = await mcp(input); |
| 179 | 179 | expect({ input, code: web.error }).toEqual({ input, code }); |
| 180 | 180 | 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}`) }); | |
| 182 | 182 | } |
| 183 | 183 | }); |
| 184 | 184 | |
| @@ -188,7 +188,7 @@ describe("the route and MCP feed_dismiss refuse the same things", () => { | ||
| 188 | 188 | const tool = await mcp(input); |
| 189 | 189 | expect(web.status).toBe(422); |
| 190 | 190 | 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") }); | |
| 192 | 192 | // The route records every act a card reports; the tool only dismisses or mutes. |
| 193 | 193 | expect((await route({ item: openEvent, kind: "opened" })).status).toBe(201); |
| 194 | 194 | expect((await mcp({ item: openEvent, kind: "opened" })).text).toStartWith("invalid_kind:"); |
test/limbs.test.ts +1 −1
| @@ -696,7 +696,7 @@ describe("limb actions", () => { | ||
| 696 | 696 | expect( |
| 697 | 697 | (await tool(admin, { app: "alice/engine", action: "undo", operation: receipt["id"] })) |
| 698 | 698 | .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"); | |
| 700 | 700 | }); |
| 701 | 701 | |
| 702 | 702 | 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", () => { | ||
| 127 | 127 | }); |
| 128 | 128 | expect(api.status).toBe(403); |
| 129 | 129 | const apiBody: any = await api.json(); |
| 130 | expect(got.error).toBe(`forbidden: ${apiBody.message}`); | |
| 130 | expect(got.error).toStartWith(`forbidden: ${apiBody.message}`); | |
| 131 | 131 | expect(assigneeOf()).toBeNull(); |
| 132 | 132 | }); |
| 133 | 133 | |
| @@ -141,13 +141,13 @@ describe("MCP assign", () => { | ||
| 141 | 141 | |
| 142 | 142 | test("an assignee who cannot read the repository is refused, and the assignee stays", async () => { |
| 143 | 143 | 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"); | |
| 145 | 145 | expect(getIssue(app.db, hiddenId, 1)!.assigneeId).toBeNull(); |
| 146 | 146 | }); |
| 147 | 147 | |
| 148 | 148 | test("an agent off the crew is refused as the API refuses it", async () => { |
| 149 | 149 | 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"); | |
| 151 | 151 | expect(assigneeOf()).toBeNull(); |
| 152 | 152 | }); |
| 153 | 153 |
test/mcp-chapters-act.test.ts +2 −1
| @@ -1,4 +1,5 @@ | ||
| 1 | 1 | /** `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"; | |
| 2 | 3 | import { afterAll, beforeAll, expect, test } from "bun:test"; |
| 3 | 4 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 5 | import { tmpdir } from "node:os"; |
| @@ -96,7 +97,7 @@ test("a non-owner is refused in the page's words, confirmed or not", async () => | ||
| 96 | 97 | expect((await call(bob, { repo: "alice/pub", action: "close", chapter: "v1" })).error).toContain(CHAPTER_WORDS.forbidden); |
| 97 | 98 | expect(listChapters(app.db, repo().id)[0]!.state).toBe("draft"); |
| 98 | 99 | 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); | |
| 100 | 101 | expect(listChapters(app.db, repo().id)[0]!.state).toBe("draft"); |
| 101 | 102 | }); |
| 102 | 103 |
test/mcp-labels-update.test.ts +6 −5
| @@ -1,4 +1,5 @@ | ||
| 1 | 1 | /** `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"; | |
| 2 | 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 3 | 4 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 5 | import { tmpdir } from "node:os"; |
| @@ -90,13 +91,13 @@ describe("MCP repo_labels update", () => { | ||
| 90 | 91 | await call(admin, { repo: R, action: "create", name: "ui", color: "6b7280" }); |
| 91 | 92 | const [defect, ui] = await listed(); |
| 92 | 93 | 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}`); | |
| 94 | 95 | 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}`); | |
| 96 | 97 | 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}`); | |
| 98 | 99 | 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}`); | |
| 100 | 101 | expect((await call(admin, { repo: R, action: "update", id: ui.id })).error).toContain("invalid"); |
| 101 | 102 | expect((await call(admin, { repo: R, action: "update", name: "x" })).error).toContain("invalid"); |
| 102 | 103 | expect(await listed()).toEqual([defect, ui]); |
| @@ -106,7 +107,7 @@ describe("MCP repo_labels update", () => { | ||
| 106 | 107 | const before = await listed(); |
| 107 | 108 | const id = before[0].id; |
| 108 | 109 | 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, | |
| 110 | 111 | ); |
| 111 | 112 | expect((await call(adminRw, { repo: R, action: "update", id, name: "x" })).error).toContain("admin token"); |
| 112 | 113 | 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", () => { | ||
| 162 | 162 | test("a writer is told the parent is unreachable and nothing is recorded", async () => { |
| 163 | 163 | const r = await call(writer); |
| 164 | 164 | 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"); | |
| 166 | 166 | expect(proposals()).toBe(0); |
| 167 | 167 | }); |
| 168 | 168 |
test/mcp-preview.test.ts +1 −1
| @@ -218,7 +218,7 @@ describe("MCP preview", () => { | ||
| 218 | 218 | const hidden = await tool(bobRw, { url: host(`hello--${sealedPull}`) }); |
| 219 | 219 | expect(hidden.error).toContain(`no pull #${sealedPull}`); |
| 220 | 220 | 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]); | |
| 222 | 222 | }); |
| 223 | 223 | |
| 224 | 224 | 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 |
||
| 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 @@ | ||
| 1 | 1 | /** `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"; | |
| 2 | 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 3 | 4 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 5 | import { tmpdir } from "node:os"; |
| @@ -125,9 +126,9 @@ describe("MCP repo_labels", () => { | ||
| 125 | 126 | expect(Array.isArray((await call(ro, { repo: R })).value.items)).toBe(true); |
| 126 | 127 | expect(Array.isArray((await call(ro, { repo: R, action: "list" })).value.items)).toBe(true); |
| 127 | 128 | 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); | |
| 129 | 130 | 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); | |
| 131 | 132 | }); |
| 132 | 133 | |
| 133 | 134 | test("bad arguments are one-sentence refusals", async () => { |
test/mcp-ro-refuses-writes.test.ts +3 −2
| @@ -18,6 +18,7 @@ | ||
| 18 | 18 | * admin-scope tools are not listed to an `ro` token at all; the last test |
| 19 | 19 | * holds that each is refused by name. |
| 20 | 20 | */ |
| 21 | import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts"; | |
| 21 | 22 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 22 | 23 | import { mkdtemp, rm } from "node:fs/promises"; |
| 23 | 24 | import { tmpdir } from "node:os"; |
| @@ -30,8 +31,8 @@ import { plansOnly } from "../src/http/mcp/shared.ts"; | ||
| 30 | 31 | import { TOOLS } from "../src/http/mcp/tools.ts"; |
| 31 | 32 | import { serve, type Servers } from "../src/http/server.ts"; |
| 32 | 33 | import { listAt } from "./mcp-list.ts"; |
| 34 | const REFUSAL = READ_ONLY_REFUSAL; | |
| 33 | 35 | |
| 34 | const REFUSAL = "forbidden: this token may read, not act"; | |
| 35 | 36 | const REPO = "alice/game"; |
| 36 | 37 | /** |
| 37 | 38 | * 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", () => { | ||
| 178 | 179 | expect({ name: t.name, isError: got.isError, text: got.text }).toEqual({ |
| 179 | 180 | name: t.name, |
| 180 | 181 | isError: true, |
| 181 | text: `no tool named ${t.name}`, | |
| 182 | text: expect.stringContaining(`no tool named ${t.name}. Next:`), | |
| 182 | 183 | }); |
| 183 | 184 | expect(moved(before, rows())).toEqual([]); |
| 184 | 185 | } |
test/mcp-take-back.test.ts +8 −7
| @@ -1,4 +1,5 @@ | ||
| 1 | 1 | /** 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"; | |
| 2 | 3 | import { afterAll, beforeAll, expect, test } from "bun:test"; |
| 3 | 4 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 5 | import { tmpdir } from "node:os"; |
| @@ -97,27 +98,27 @@ const dir = () => repoDir(app.reposRoot, repo.ownerName, repo.name); | ||
| 97 | 98 | |
| 98 | 99 | test("an agent token is refused in the page's words, and nothing is made", async () => { |
| 99 | 100 | 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")}.`); | |
| 101 | 102 | expect(await resolveOid(dir(), `refs/heads/revert-${shipped.number}`)).toBeUndefined(); |
| 102 | 103 | expect(revertOf(app.db, repo.id, shipped.id)).toBeUndefined(); |
| 103 | 104 | }); |
| 104 | 105 | |
| 105 | 106 | test("a read-only token cannot take a pull back", async () => { |
| 106 | 107 | 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); | |
| 108 | 109 | expect(revertOf(app.db, repo.id, shipped.id)).toBeUndefined(); |
| 109 | 110 | }); |
| 110 | 111 | |
| 111 | 112 | test("an open pull has not shipped", async () => { |
| 112 | 113 | 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")}.`); | |
| 114 | 115 | }); |
| 115 | 116 | |
| 116 | 117 | test("a pull the caller cannot see, or no pull at all, is not found", async () => { |
| 117 | 118 | expect((await takeBack(tok["sam"]!, { repo: "ada/svc", number: shipped.number })).error).toStartWith("not_found:"); |
| 118 | 119 | 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( | |
| 121 | 122 | `not_found: That could not be taken back: ${takeBackWords("not_found")}.`, |
| 122 | 123 | ); |
| 123 | 124 | }); |
| @@ -137,7 +138,7 @@ test("a shipped pull opens the pull that undoes it; a second call is already tak | ||
| 137 | 138 | expect(revert.state).toBe("open"); |
| 138 | 139 | |
| 139 | 140 | 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")}.`); | |
| 141 | 142 | }); |
| 142 | 143 | |
| 143 | 144 | 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", | ||
| 150 | 151 | const earlier = await ship("gamma", "alpha\nGAMMA\n"); |
| 151 | 152 | await ship("delta", "alpha\nDELTA\n"); |
| 152 | 153 | 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."); | |
| 154 | 155 | expect(await resolveOid(dir(), `refs/heads/revert-${earlier.number}`)).toBeUndefined(); |
| 155 | 156 | expect(revertOf(app.db, repo.id, earlier.id)).toBeUndefined(); |
| 156 | 157 | }); |
test/mcp-upstream.test.ts +1 −1
| @@ -187,7 +187,7 @@ describe("MCP proposes to the parent forge and lists proposals", () => { | ||
| 187 | 187 | const writer = createToken(child.db, kid.id, "rw", "rw").token; |
| 188 | 188 | const none = await call(writer, "propose_to_parent_forge"); |
| 189 | 189 | 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"); | |
| 191 | 191 | expect(JSON.parse((await call(writer, "forge_proposals")).text).items).toEqual([]); |
| 192 | 192 | }); |
| 193 | 193 |
test/mcp-wait-for.test.ts +1 −1
| @@ -116,7 +116,7 @@ describe("wait_for over MCP", () => { | ||
| 116 | 116 | const a2 = (await tool(rw, "tell", { repo: "alice/open", text: "x" })).value.issue; |
| 117 | 117 | const b2 = (await tool(rw, "tell", { repo: "alice/open", text: "y" })).value.issue; |
| 118 | 118 | 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."); | |
| 120 | 120 | const map = (await tool(ro, "map", { app: "alice/game" })).value; |
| 121 | 121 | expect(map.edges).not.toContainEqual({ issue: b, blockedBy: a }); |
| 122 | 122 | }); |
test/mcp-write-file.test.ts +3 −2
| @@ -1,4 +1,5 @@ | ||
| 1 | 1 | /** 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"; | |
| 2 | 3 | import { afterAll, beforeAll, expect, test } from "bun:test"; |
| 3 | 4 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 5 | import { tmpdir } from "node:os"; |
| @@ -83,12 +84,12 @@ test("a writer commits and read_file reads it back", async () => { | ||
| 83 | 84 | |
| 84 | 85 | test("a read-only token is refused in the dispatcher's words", async () => { |
| 85 | 86 | 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); | |
| 87 | 88 | }); |
| 88 | 89 | |
| 89 | 90 | test("a path with .. is refused, and so is a branch that does not exist", async () => { |
| 90 | 91 | 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"); | |
| 92 | 93 | expect((await call(tok["rw"]!, "write_file", args({ branch: "nope" }))).error).toContain("not_found"); |
| 93 | 94 | }); |
| 94 | 95 |
test/mcp-write-scope.test.ts +2 −1
| @@ -4,6 +4,7 @@ | ||
| 4 | 4 | * `rw` one. The event log, every table's row count and every counter row |
| 5 | 5 | * outside `/mcp` stay as they were (see test/helpers/write-snapshot.ts). |
| 6 | 6 | */ |
| 7 | import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts"; | |
| 7 | 8 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 8 | 9 | import { mkdtemp, rm } from "node:fs/promises"; |
| 9 | 10 | import { tmpdir } from "node:os"; |
| @@ -135,7 +136,7 @@ describe("a token that may only read cannot write through any tool", () => { | ||
| 135 | 136 | const text: string | undefined = body.result?.content?.[0]?.text; |
| 136 | 137 | const refused = t.needsAdminScope |
| 137 | 138 | ? notListed(body) |
| 138 | : body.result?.isError === true && text === "forbidden: this token may read, not act"; | |
| 139 | : body.result?.isError === true && text === READ_ONLY_REFUSAL; | |
| 139 | 140 | if (!refused) unrefused.push(t.name); |
| 140 | 141 | } |
| 141 | 142 | // 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 @@ | ||
| 4 | 4 | * action the pages call — so what a person may not do on a page they may |
| 5 | 5 | * not do here. |
| 6 | 6 | */ |
| 7 | import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts"; | |
| 7 | 8 | import { seatAs } from "./helpers/seat.ts"; |
| 8 | 9 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 9 | 10 | import { chmodSync, writeFileSync } from "node:fs"; |
| @@ -658,7 +659,7 @@ describe("the forge over MCP", () => { | ||
| 658 | 659 | expect((await tool(rw, "close", { repo: "alice/game", number: own.number, state: "x" })).error).toContain("invalid_state"); |
| 659 | 660 | expect((await tool(rw, "close", { repo: "alice/game", number: own.number, reason: "x" })).error).toContain("invalid_reason"); |
| 660 | 661 | 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); | |
| 662 | 663 | }); |
| 663 | 664 | |
| 664 | 665 | 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", () => { | ||
| 982 | 983 | expect( |
| 983 | 984 | (await tool(rw, "wait_for", { app: "alice/game", issue: a, blockedBy: b })) |
| 984 | 985 | .error, |
| 985 | ).toBe("cycle: that would make a loop"); | |
| 986 | ).toStartWith("cycle: that would make a loop"); | |
| 986 | 987 | expect( |
| 987 | 988 | (await tool(rw, "wait_for", { app: "alice/game", issue: a, blockedBy: 999 })) |
| 988 | 989 | .error, |
| 989 | ).toBe("no_such_issue: no issue #999"); | |
| 990 | ).toStartWith("no_such_issue: no issue #999"); | |
| 990 | 991 | expect( |
| 991 | 992 | (await tool(ro, "wait_for", { app: "alice/game", issue: a, blockedBy: b })) |
| 992 | 993 | .error, |
| @@ -1179,7 +1180,7 @@ describe("the forge over MCP", () => { | ||
| 1179 | 1180 | body: JSON.stringify({ destination: dest }), |
| 1180 | 1181 | }); |
| 1181 | 1182 | 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}`); | |
| 1183 | 1184 | |
| 1184 | 1185 | // An agent, even one marked site admin, may not change a grant. |
| 1185 | 1186 | const bot = await createAgent(app, alice, { username: "egressbot", brief: "x" }); |
test/milestones.test.ts +1 −1
| @@ -501,7 +501,7 @@ describe("milestones", () => { | ||
| 501 | 501 | ).toBe(404); |
| 502 | 502 | expect( |
| 503 | 503 | (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"); | |
| 505 | 505 | // A reader's token gets the numbers without spend or names. |
| 506 | 506 | const reader = createToken( |
| 507 | 507 | app.db, |
test/spawn-api.test.ts +2 −1
| @@ -3,6 +3,7 @@ | ||
| 3 | 3 | * tool. Dry-run is the default, an ro token plans and never makes, and a |
| 4 | 4 | * fake placement stands in for where the child lives. |
| 5 | 5 | */ |
| 6 | import { READ_ONLY_REFUSAL } from "../src/http/mcp/hints.ts"; | |
| 6 | 7 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 7 | 8 | import { mkdir, mkdtemp, readdir, rm } from "node:fs/promises"; |
| 8 | 9 | import { tmpdir } from "node:os"; |
| @@ -199,7 +200,7 @@ describe("spawn over the API and MCP", () => { | ||
| 199 | 200 | expect(plan.error).toBe(false); |
| 200 | 201 | expect(JSON.parse(plan.text)).toMatchObject({ dryRun: true, says: expect.stringContaining("nothing was made") }); |
| 201 | 202 | 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 }); | |
| 203 | 204 | // A non-admin person's rw token may plan via MCP (empty apps — no private reads). |
| 204 | 205 | const asBob = await mcp(bobRw, { name: "bobs-kid2", apps: [] }); |
| 205 | 206 | 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", | ||
| 67 | 67 | const viaApi = await api("/api/v1/admin/accounts/bob/model-grant", { usdPerMonth: 20000 }); |
| 68 | 68 | expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.usdPerMonth } }); |
| 69 | 69 | 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}`) }); | |
| 71 | 71 | }); |
| 72 | 72 | |
| 73 | 73 | test("a role's allowance out of range answers the module's sentence from the API and MCP", async () => { |
| 74 | 74 | const viaApi = await api("/api/v1/admin/accounts/bob/role", { role: "member", usdPerMonth: 20000 }); |
| 75 | 75 | expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.usdPerMonth } }); |
| 76 | 76 | 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}`) }); | |
| 78 | 78 | }); |
| 79 | 79 | |
| 80 | 80 | test("a ceiling out of range answers the module's sentence from the API and MCP", async () => { |
| 81 | 81 | const viaApi = await api("/api/v1/admin/accounts/bob/ceiling", { dailyUsd: 20000, perRunUsd: 1 }); |
| 82 | 82 | expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.ceilings } }); |
| 83 | 83 | 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}`) }); | |
| 85 | 85 | }); |
| 86 | 86 | |
| 87 | 87 | test("an invite's days out of range answers the module's sentence from the API and MCP", async () => { |
| 88 | 88 | const viaApi = await api("/api/v1/admin/invites", { days: 31 }); |
| 89 | 89 | expect(viaApi).toMatchObject({ status: 422, body: { error: "invalid", message: SPEND_WORDS.inviteDays } }); |
| 90 | 90 | 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}`) }); | |
| 92 | 92 | }); |
| 93 | 93 | |
| 94 | 94 | 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", () => { | ||
| 151 | 151 | number: first, |
| 152 | 152 | labels: ["nope"], |
| 153 | 153 | }), |
| 154 | ).toBe(`unknown_label: ${THREAD_SAYS.unknownLabel}`); | |
| 154 | ).toStartWith(`unknown_label: ${THREAD_SAYS.unknownLabel}`); | |
| 155 | 155 | }); |
| 156 | 156 | |
| 157 | 157 | test("a reader changing labels", async () => { |
| @@ -166,7 +166,7 @@ describe("label and plan refusals on a thread", () => { | ||
| 166 | 166 | number: first, |
| 167 | 167 | labels: ["bug"], |
| 168 | 168 | }), |
| 169 | ).toBe(`forbidden: ${THREAD_SAYS.labelsForbidden}`); | |
| 169 | ).toStartWith(`forbidden: ${THREAD_SAYS.labelsForbidden}`); | |
| 170 | 170 | }); |
| 171 | 171 | |
| 172 | 172 | test("a reader planning", async () => { |
| @@ -181,6 +181,6 @@ describe("label and plan refusals on a thread", () => { | ||
| 181 | 181 | issue: second, |
| 182 | 182 | blockedBy: first, |
| 183 | 183 | }), |
| 184 | ).toBe(`forbidden: ${THREAD_SAYS.planForbidden}`); | |
| 184 | ).toStartWith(`forbidden: ${THREAD_SAYS.planForbidden}`); | |
| 185 | 185 | }); |
| 186 | 186 | }); |
new above
offline
The
tokenstool 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.