Public: anyone can read this; the crew can change it.
The client list (who was sent which forge, and what happened) is readable through MCP with the page's words #13419
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13394-the-client-list-who-was-sent-which-forge → main 6 commits fork 1 thread · 1 unresolved
5 files
changed +124
−10
docs/MCP.md +5 −1
| @@ -127,7 +127,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`; | ||
| 127 | 127 | | `forge` | — | How is my forge? What needs you, recommended; `apply` takes them | 291 | |
| 128 | 128 | | `forge_proposals` | — | What this forge proposed to its parent; `reachable` false if it is silent | 245 | |
| 129 | 129 | | `forge_view` | — | The forge as one picture: counts, apps, runs with stations, health | 282 | |
| 130 | | `forges` | `refused` | Forges sent from here (admin; a stage says when to resend), or one forge's plan to read or grant | 629 | | |
| 130 | | `forges` | `refused`, `clients` | Forges sent from here (admin), the client list, or one forge's plan | 610 | | |
| 131 | 131 | | `fork` | — | Fork a repository into your account; for a guest, a copy to send changes back from | 232 | |
| 132 | 132 | | `fork_tree` | — | The fork tree around a repo: ancestors, siblings and descendants you may read | 440 | |
| 133 | 133 | | `forks` | `chain` | A repo's forks you may see, paged by limit and cursor (next_cursor), each with commits ahead and behind | 480 | |
| @@ -302,6 +302,10 @@ a failure names the bytes over and the longest descriptions. | ||
| 302 | 302 | `instructions` say once that a tool with `dryRun` plans unless it is `false`. |
| 303 | 303 | - The ceiling is the owner's: never raise it in a feature pull. |
| 304 | 304 | |
| 305 | `forges` with `{ kind: "clients" }` (#13394) is another: an admin's client list in the | |
| 306 | /forges page's words, `{ says, clients }`, each `{ name, for, apps, claimed, attention, seen, stage, next }` | |
| 307 | (`src/spawn/client_words.ts`); anyone else is refused `forbidden`. | |
| 308 | ||
| 305 | 309 | `flow` with `{ kind: "bugs" }` is such a door (#8973): `{ open, overdue, bugs }`, |
| 306 | 310 | each bug `{ repo, number, priority, dueAt }`, soonest due first, at most 100, |
| 307 | 311 | from `src/flow/bugs.ts`. An admin sees every repository; anyone else only |
src/http/mcp/tools/forges.ts +12 −8
| @@ -3,6 +3,7 @@ import { CODE_ERRORS, makeCode, planCode, readCodes, revoke } from "../../../act | ||
| 3 | 3 | import { REFUSED_SHOWN, listRefusals, mayReadRefusals } from "../../../core/first_ask_refusals.ts"; |
| 4 | 4 | import { publicOrigin } from "../../../core/public_origin.ts"; |
| 5 | 5 | import { scopeAllows } from "../../../core/tokens.ts"; |
| 6 | import { clientLines } from "../../../spawn/client_words.ts"; | |
| 6 | 7 | import { clientRows, listed } from "../../../spawn/clients.ts"; |
| 7 | 8 | import { archiveForge, archivedForges, restoreForge } from "../../../spawn/archive.ts"; |
| 8 | 9 | import { CHILD_NAME } from "../../../spawn/placement.ts"; |
| @@ -10,12 +11,14 @@ import { checkMove } from "../../../spawn/move_check.ts"; | ||
| 10 | 11 | import { moveToCell } from "../../../spawn/move_cell.ts"; |
| 11 | 12 | import { good, bad, type Tool } from "../shared.ts"; |
| 12 | 13 | |
| 14 | const sentSays = (n: number) => (n === 0 ? "This forge has sent no forges yet." : `${n} forge${n === 1 ? "" : "s"} sent from here.`); | |
| 15 | ||
| 13 | 16 | export const tool: Tool = { |
| 14 | 17 | name: "forges", |
| 15 | doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed, stage (sent/opened/signed in/last tell; resend true when unopened 3 days: claim_link), last activity (a person or the crew, never a heartbeat), who claimed it and when, what it costs to keep (keepBytes, use, credit), archive (why it is proposed for archive), reachable, size, use, madeFrom; `{ forge, plan?, dryRun? }` reads a forge's plan (small|medium|large, status, source, changes) or, with `plan`, grants it by hand; `{ forge, sandbox: true }` reads what moving a forge out of this forge's own process into a sandbox would meet (hooks and command-running config keys by name, size) and with `dryRun: false` moves it, proven and put back on any failure (`acknowledge: true` when it was held for what its repositories hold); each forge carries `placement` and `where`; gift codes: `codes` true lists, `code` {plan, uses?, note?, expires?} makes (shown once), `revoke` id; planned unless `dryRun` is false; `archive` a name or names stops each, writes its data and ledger as one file to the backup destination, then removes it; `restore` a name brings an archived one back; `kind` refused lists the last 20 refused first asks", | |
| 18 | doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed, stage (sent/opened/signed in/last tell; resend true when unopened 3 days: claim_link), last activity (a person or the crew, never a heartbeat), who claimed it and when, keep cost, archive reason, reachable, size, use, madeFrom; `{ forge, plan?, dryRun? }` reads a forge's plan (small|medium|large) or, with `plan`, grants it by hand; `{ forge, sandbox: true }` reads what moving a forge out of this forge's own process into a sandbox would meet (hooks, command-running keys, size) and with `dryRun: false` moves it, proven and put back on any failure (`acknowledge: true` when it was held for what its repositories hold); each forge carries `placement` and `where`; gift codes: `codes` true lists, `code` {plan, uses?, note?, expires?} makes (shown once), `revoke` id; planned unless `dryRun` is false; `archive` a name or names stops each, writes its data and ledger as one file to the backup destination, then removes it; `restore` a name brings an archived one back; `kind` refused lists the last 20 refused first asks; `kind` clients lists each client in the page's words", | |
| 16 | 19 | description: |
| 17 | "Forges sent from here (admin; a stage says when to resend), or one forge's plan to read or grant.", | |
| 18 | inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["refused"] }, forge: { type: "string" }, plan: { type: "string" }, codes: { type: "boolean" }, code: { type: "object" }, revoke: { type: "string" }, archive: { type: ["string", "array"], items: { type: "string" } }, restore: { type: "string" }, sandbox: { type: "boolean" }, acknowledge: { type: "boolean" }, dryRun: { type: "boolean" } } }, | |
| 20 | "Forges sent from here (admin), the client list, or one forge's plan.", | |
| 21 | inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["refused", "clients"] }, forge: { type: "string" }, plan: { type: "string" }, codes: { type: "boolean" }, code: { type: "object" }, revoke: { type: "string" }, archive: { type: ["string", "array"], items: { type: "string" } }, restore: { type: "string" }, sandbox: { type: "boolean" }, acknowledge: { type: "boolean" }, dryRun: { type: "boolean" } } }, | |
| 19 | 22 | writes: true, |
| 20 | 23 | dryByDefault: true, |
| 21 | 24 | readsWithout: ["forge", "plan", "code", "revoke", "archive", "restore"], |
| @@ -23,7 +26,11 @@ export const tool: Tool = { | ||
| 23 | 26 | if (!user.isAdmin) |
| 24 | 27 | return bad("forbidden", "only an admin of this forge sees the forges it sent"); |
| 25 | 28 | if (args["kind"] !== undefined) { |
| 26 | if (args["kind"] !== "refused") return bad("invalid", "kind is refused"); | |
| 29 | if (args["kind"] === "clients") { | |
| 30 | const lines = clientLines(await clientRows(ctx.app)); | |
| 31 | return good({ says: sentSays(lines.length), clients: lines }); | |
| 32 | } | |
| 33 | if (args["kind"] !== "refused") return bad("invalid", "kind is refused or clients"); | |
| 27 | 34 | if (!mayReadRefusals(user)) return bad("forbidden", "only an admin of this forge sees the refused first asks"); |
| 28 | 35 | const refused = listRefusals(ctx.app.db, REFUSED_SHOWN, Date.now()); |
| 29 | 36 | return good({ says: refused.length === 0 ? "No first ask has been refused." : `The last ${refused.length} refused first asks, newest first.`, refused }); |
| @@ -94,10 +101,7 @@ export const tool: Tool = { | ||
| 94 | 101 | } |
| 95 | 102 | const forges = await clientRows(ctx.app); |
| 96 | 103 | return good({ |
| 97 | says: | |
| 98 | forges.length === 0 | |
| 99 | ? "This forge has sent no forges yet." | |
| 100 | : `${forges.length} forge${forges.length === 1 ? "" : "s"} sent from here.`, | |
| 104 | says: sentSays(forges.length), | |
| 101 | 105 | forges: forges.map(listed), |
| 102 | 106 | }); |
| 103 | 107 | }, |
src/spawn/client_words.ts added +33
| @@ -0,0 +1,33 @@ | ||
| 1 | /** | |
| 2 | * The client list as the /forges page says it, one plain object per row: who was sent which forge, | |
| 3 | * and what happened. | |
| 4 | */ | |
| 5 | import { ATTENTION_WORDS, CLAIM_WORDS, claimState, seenOf, seenParts, type ClientRow } from "./clients.ts"; | |
| 6 | ||
| 7 | export interface ClientLine { | |
| 8 | name: string; | |
| 9 | for: string | null; | |
| 10 | apps: readonly string[]; | |
| 11 | claimed: string; | |
| 12 | attention: string | null; | |
| 13 | /** "sent · opened · last seen", each with its time when it has one. */ | |
| 14 | seen: string | null; | |
| 15 | stage: string | null; | |
| 16 | next: string; | |
| 17 | } | |
| 18 | ||
| 19 | export function clientLines(rows: readonly ClientRow[]): ClientLine[] { | |
| 20 | return rows.map((r) => { | |
| 21 | const seen = seenOf(r); | |
| 22 | return { | |
| 23 | name: r.name, | |
| 24 | for: r.for, | |
| 25 | apps: r.apps, | |
| 26 | claimed: CLAIM_WORDS[claimState(r)], | |
| 27 | attention: r.attention === null ? null : ATTENTION_WORDS[r.attention], | |
| 28 | seen: seen === null ? null : seenParts(seen).map((p) => (p.at === null ? p.words : `${p.words} ${p.at}`)).join(" · "), | |
| 29 | stage: r.stage === null ? null : r.stage.words, | |
| 30 | next: r.nextStep.key === "going" && r.nextStep.lastTellAt ? `going: last tell ${r.nextStep.lastTellAt}` : r.nextStep.words, | |
| 31 | }; | |
| 32 | }); | |
| 33 | } |
test/client-states.test.ts +1 −1
| @@ -106,7 +106,7 @@ describe("client states", () => { | ||
| 106 | 106 | expect(got.stage.resend).toBe(true); |
| 107 | 107 | expect(String(forgeRow(row!, Date.now()))).toContain(got.stage.words); |
| 108 | 108 | expect(tool.doc).toContain("reachable"); |
| 109 | expect(tool.description).toContain("resend"); | |
| 109 | expect(tool.doc).toContain("resend"); | |
| 110 | 110 | } finally { |
| 111 | 111 | app.close(); |
| 112 | 112 | } |
test/mcp-clients.test.ts added +73
| @@ -0,0 +1,73 @@ | ||
| 1 | /** MCP `forges` `{ kind: "clients" }`: the client list in the page's words, for an admin only. */ | |
| 2 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 3 | import { mkdirSync, writeFileSync } from "node:fs"; | |
| 4 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 5 | import { tmpdir } from "node:os"; | |
| 6 | import { join } from "node:path"; | |
| 7 | import { createApp, type App } from "../src/app.ts"; | |
| 8 | import { createToken } from "../src/core/tokens.ts"; | |
| 9 | import { createUser } from "../src/core/users.ts"; | |
| 10 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 11 | import { useChildFetch } from "../src/spawn/clients.ts"; | |
| 12 | import { quietLogs } from "./helpers/globals.ts"; | |
| 13 | ||
| 14 | quietLogs(); | |
| 15 | let dataDir = ""; | |
| 16 | let app: App; | |
| 17 | let servers: Servers; | |
| 18 | let admin = ""; | |
| 19 | let bob = ""; | |
| 20 | const call = async (as: string, kind = "clients") => { | |
| 21 | const res = await fetch(`${servers.url}/mcp`, { | |
| 22 | method: "POST", | |
| 23 | headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${as}` }, | |
| 24 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "forges", arguments: { kind } } }), | |
| 25 | }); | |
| 26 | return ((await res.json()) as any).result; | |
| 27 | }; | |
| 28 | ||
| 29 | beforeAll(async () => { | |
| 30 | dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-clients-")); | |
| 31 | app = createApp({ dataDir, port: 0 }); | |
| 32 | mkdirSync(join(dataDir, "spawn"), { recursive: true }); | |
| 33 | writeFileSync(join(dataDir, "spawn", "alpha.json"), JSON.stringify({ name: "alpha", bodyId: "cell-alpha", done: true, placement: "hosted", size: "small", apps: [], forWhom: "Ann", createdAt: new Date(Date.now() - 86_400_000).toISOString() })); | |
| 34 | useChildFetch(app, async () => Response.json({ claimed: false, link: { state: "open", revokedAt: null, usedAt: null } })); | |
| 35 | servers = await serve(app); | |
| 36 | const make = async (n: string) => { | |
| 37 | const r = await createUser(app.db, { origin: "seed", trusted: true, username: n, email: `${n}@f.dev`, password: "a-good-passphrase", adminIfFirst: n === "alice" }); | |
| 38 | if (!r.ok) throw new Error("user"); | |
| 39 | return r.value; | |
| 40 | }; | |
| 41 | admin = createToken(app.db, (await make("alice")).id, "admin", "admin").token; | |
| 42 | bob = createToken(app.db, (await make("bob")).id, "bob", "ro").token; | |
| 43 | }, 60_000); | |
| 44 | afterAll(async () => { | |
| 45 | servers.stop(); | |
| 46 | app.close(); | |
| 47 | await rm(dataDir, { recursive: true, force: true }); | |
| 48 | }); | |
| 49 | ||
| 50 | test("the owner reads each client in the page's words", async () => { | |
| 51 | const ok = await call(admin); | |
| 52 | const body = ok.structuredContent ?? JSON.parse(ok.content[0].text); | |
| 53 | expect(ok.isError).toBeFalsy(); | |
| 54 | const c = body.clients; | |
| 55 | expect(body.says).toBe("1 forge sent from here."); | |
| 56 | expect(c[0].name).toBe("alpha"); | |
| 57 | expect(c[0].for).toBe("Ann"); | |
| 58 | expect(c[0].claimed).toBe("Not claimed yet"); | |
| 59 | expect(c[0].seen).toContain("not opened yet"); | |
| 60 | }); | |
| 61 | ||
| 62 | test("anyone else gets the usual refusal", async () => { | |
| 63 | const no = await call(bob); | |
| 64 | expect(no.isError).toBe(true); | |
| 65 | expect(JSON.stringify(no)).toContain("forbidden"); | |
| 66 | expect(no.structuredContent?.clients).toBeUndefined(); | |
| 67 | }); | |
| 68 | ||
| 69 | test("an unknown kind is invalid", async () => { | |
| 70 | const res = await call(admin, "nope"); | |
| 71 | expect(res.isError).toBe(true); | |
| 72 | expect(JSON.stringify(res)).toContain("invalid"); | |
| 73 | }); |
new above
offline
Dropping the enum to fit the tools/list ceiling weakens schema validation. Keep
enum: ["refused","clients"]and shorten the very longdoctext by the bytes needed instead.