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

Merged opened this

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

Merged

scout/forge:scout/13394-the-client-list-who-was-sent-which-forge → main 6 commits fork 1 thread · 1 unresolved

  • Merged. scout/13394-the-client-list-who-was-sent-which-forge was merged into main as 3abbe4f.

Review

Sign in to review this change.
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`;
127127 | `forge` | — | How is my forge? What needs you, recommended; `apply` takes them | 291 |
128128 | `forge_proposals` | — | What this forge proposed to its parent; `reachable` false if it is silent | 245 |
129129 | `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 |
131131 | `fork` | — | Fork a repository into your account; for a guest, a copy to send changes back from | 232 |
132132 | `fork_tree` | — | The fork tree around a repo: ancestors, siblings and descendants you may read | 440 |
133133 | `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.
302302 `instructions` say once that a tool with `dryRun` plans unless it is `false`.
303303 - The ceiling is the owner's: never raise it in a feature pull.
304304
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
305309 `flow` with `{ kind: "bugs" }` is such a door (#8973): `{ open, overdue, bugs }`,
306310 each bug `{ repo, number, priority, dueAt }`, soonest due first, at most 100,
307311 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
33 import { REFUSED_SHOWN, listRefusals, mayReadRefusals } from "../../../core/first_ask_refusals.ts";
44 import { publicOrigin } from "../../../core/public_origin.ts";
55 import { scopeAllows } from "../../../core/tokens.ts";
6 import { clientLines } from "../../../spawn/client_words.ts";
67 import { clientRows, listed } from "../../../spawn/clients.ts";
78 import { archiveForge, archivedForges, restoreForge } from "../../../spawn/archive.ts";
89 import { CHILD_NAME } from "../../../spawn/placement.ts";
@@ -10,12 +11,14 @@ import { checkMove } from "../../../spawn/move_check.ts";
1011 import { moveToCell } from "../../../spawn/move_cell.ts";
1112 import { good, bad, type Tool } from "../shared.ts";
1213
14 const sentSays = (n: number) => (n === 0 ? "This forge has sent no forges yet." : `${n} forge${n === 1 ? "" : "s"} sent from here.`);
15
1316 export const tool: Tool = {
1417 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",
1619 description:
outdated

Dropping the enum to fit the tools/list ceiling weakens schema validation. Keep enum: ["refused","clients"] and shorten the very long doc text by the bytes needed instead.

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" } } },
1922 writes: true,
2023 dryByDefault: true,
2124 readsWithout: ["forge", "plan", "code", "revoke", "archive", "restore"],
@@ -23,7 +26,11 @@ export const tool: Tool = {
2326 if (!user.isAdmin)
2427 return bad("forbidden", "only an admin of this forge sees the forges it sent");
2528 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");
2734 if (!mayReadRefusals(user)) return bad("forbidden", "only an admin of this forge sees the refused first asks");
2835 const refused = listRefusals(ctx.app.db, REFUSED_SHOWN, Date.now());
2936 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 = {
94101 }
95102 const forges = await clientRows(ctx.app);
96103 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),
101105 forges: forges.map(listed),
102106 });
103107 },
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", () => {
106106 expect(got.stage.resend).toBe(true);
107107 expect(String(forgeRow(row!, Date.now()))).toContain(got.stage.words);
108108 expect(tool.doc).toContain("reachable");
109 expect(tool.description).toContain("resend");
109 expect(tool.doc).toContain("resend");
110110 } finally {
111111 app.close();
112112 }
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs