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

The map MCP tool answers `view: "space"` with the facts the space page shows, so an agent sees the forge's growth too #12781

Merged opened this

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

Merged

scout/forge:scout/12771-the-map-mcp-tool-answers-view-space-with → main 7 commits fork

  • Merged. scout/12771-the-map-mcp-tool-answers-view-space-with was merged into main as 5ac1d18.

Review

Sign in to review this change.
5 files changed +189 −3
docs/MCP.md +2 −1
@@ -142,7 +142,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
142142 | `limits` | — | Every limit the owner can hit | 1101 |
143143 | `maintenance` | `status`, `prepare`, `resume`, `pause-duty`, `resume-duty` | Prepare the forge for a power-off, check the drain, or end maintenance (admin) | 308 |
144144 | `make_it_yours` | — | Fork an app you can see: code and history, following the original | 337 |
145 | `map` | — | An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first | 416 |
145 | `map` | — | An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first | 465 |
146146 | `merge` | `land` | Land a pull, as its page's Merge button does; a person's only | 362 |
147147 | `migrate` | — | Bring a repo in by public `url` (`name`, `crew`), history and all | 269 |
148148 | `milestones` | — | How far each ask is | 439 |
@@ -664,6 +664,7 @@ answers
664664 becomes the "Told from" link on the issue; a bad one is refused. It differs
665665 from `context.page`, which is any http(s) address appended as context, not
666666 linked as the origin.
667 - **`map` with `view: "space"`** answers the same `spaceOf` as the space page and `space.json`, for the viewer's own scope (a guest sees what the page shows a guest); a junk `view` is an error naming `plan` and `space`; answers past 300 issues or 100 runs an actor are cut and say `truncated: true` with `total`; no tool was added and no ceiling moved.
667668 - **`ready` and `startable`.** `map` (and `GET …/map`) carries both. `ready` is
668669 every open issue with nothing open in front, held or working ones included,
669670 and the page's Ready now section reads it. `startable` is the numbers from
docs/features/space.md +2
@@ -12,6 +12,8 @@ is `/:owner/:name/space.json`, the same plane for an agent. In the terminal it i
1212 - **Crew.** Their avatars sit on the issue they are working; tap one (or its name in the bar) to see what they are on.
1313 - **Share.** The view is in the address hash: `#x=…&y=…&z=…` (centre in world units, zoom relative to Fit) and `&t=` (minutes since the epoch) when scrubbed back.
1414
15 The MCP `map` tool answers `view: "space"` with the same `spaceOf` result, scoped to the caller like the page.
16
1517 ## How it is built
1618
1719 - `src/web/space_model.ts` — pure placement: treemap of regions, grid of cells per cluster. Plain data in, compact arrays out.
src/http/mcp/map_space.ts added +18
@@ -0,0 +1,18 @@
1 /** What an agent's space answer carries: the page draws the rest, a reader's context cannot. */
2 export const SPACE_ISSUES_MAX = 300;
3 export const SPACE_RUNS_MAX = 100;
4
5 /** `spaceOf`, cut to the ceilings; `truncated` says so, `total` counts the issues there were. */
6 export function cappedSpace(space: Record<string, unknown>): Record<string, unknown> {
7 const issues = Array.isArray(space["issues"]) ? space["issues"] : [];
8 const crew = Array.isArray(space["crew"]) ? (space["crew"] as { runs?: unknown[] }[]) : [];
9 const runsCut = crew.some((c) => (c.runs?.length ?? 0) > SPACE_RUNS_MAX);
10 if (issues.length <= SPACE_ISSUES_MAX && !runsCut) return space;
11 return {
12 ...space,
13 issues: issues.slice(0, SPACE_ISSUES_MAX),
14 crew: crew.map((c) => ({ ...c, runs: (c.runs ?? []).slice(0, SPACE_RUNS_MAX) })),
15 truncated: true,
16 total: issues.length,
17 };
18 }
src/http/mcp/tools/map.ts +11 −2
@@ -4,19 +4,23 @@ import { mapHeldFor } from "../../../crew/held.ts";
44 import { pillarView } from "../../../core/pillars.ts";
55 import { askToLiveFor } from "../../../web/ask_to_live.ts";
66 import { listActiveRuns } from "../../../core/runs.ts";
7 import { spaceOf } from "../../../web/space_read.ts";
78 import { roadmapOf } from "../../../web/roadmap.ts";
89 import { mapJson, marksFor, withoutDone } from "../../../web/pages/map.ts";
910 import { putIssueFirst } from "../../../actions/first.ts";
11 import { cappedSpace } from "../map_space.ts";
1012 import { bad, good, type Tool, APP_ARG, planRepo, isAnswer, issueArg } from "../shared.ts";
1113
14 const VIEWS = ["plan", "space"];
15
1216 export const tool: Tool = {
1317 name: "map",
14 doc: "an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`, `done` to list closed issues too; `roadmap` for the pillars in order with ETAs; `first: <number>` puts that ready issue first, for writers: a reader is forbidden, a closed or blocked issue invalid); draws the `ui://forge/map` card",
18 doc: "an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`, `done` to list closed issues too; `roadmap` for the pillars in order with ETAs; `first: <number>` puts that ready issue first, for writers: a reader is forbidden, a closed or blocked issue invalid); `view: \"space\"` for the space page's facts; draws the `ui://forge/map` card",
1519 description:
1620 "An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first.",
1721 inputSchema: {
1822 type: "object",
19 properties: { app: APP_ARG, done: { type: "boolean" }, roadmap: { type: "boolean" }, first: { type: "integer", minimum: 1 } },
23 properties: { app: APP_ARG, done: { type: "boolean" }, roadmap: { type: "boolean" }, first: { type: "integer", minimum: 1 }, view: { type: "string", enum: VIEWS } },
2024 required: ["app"],
2125 },
2226 writes: true,
@@ -24,6 +28,11 @@ export const tool: Tool = {
2428 async run(ctx, user, args) {
2529 const repo = planRepo(ctx, user, args);
2630 if (isAnswer(repo)) return repo;
31 const view = args["view"];
32 if (view !== undefined && (typeof view !== "string" || !VIEWS.includes(view))) {
33 return bad("bad_view", `view is one of ${VIEWS.join(", ")}`);
34 }
35 if (view === "space") return good({ ...cappedSpace(spaceOf(ctx.app, repo, user)) });
2736 if (args["first"] !== undefined) {
2837 const issue = issueArg(ctx, repo, args, "first");
2938 if ("ok" in issue) return issue;
test/mcp-map-space.test.ts added +156
@@ -0,0 +1,156 @@
1 /**
2 * MCP `map` with `view: "space"` answers what `spaceOf` gives the caller;
3 * a junk view names the valid values.
4 */
5 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createApp, type App } from "../src/app.ts";
10 import { createRepo } from "../src/actions/repos.ts";
11 import { addDependency } from "../src/core/dependencies.ts";
12 import { createIssue } from "../src/core/issues.ts";
13 import { createToken } from "../src/core/tokens.ts";
14 import { createUser } from "../src/core/users.ts";
15 import { serve, type Servers } from "../src/http/server.ts";
16 import { SPACE_ISSUES_MAX } from "../src/http/mcp/map_space.ts";
17 import { spaceOf } from "../src/web/space_read.ts";
18 import { getRepo } from "../src/core/repos.ts";
19 const stable = (v: unknown) => ({ ...JSON.parse(JSON.stringify(v)), now: 0, weekStart: 0 });
20 import { promote } from "./helpers/members.ts";
21
22 describe("MCP map view space", () => {
23 let dataDir: string;
24 let app: App;
25 let servers: Servers;
26 let aliceTok: string;
27 let carolTok: string;
28 let id = 1;
29
30 const call = async (token: string, args: unknown) => {
31 const res = await fetch(`${servers.url}/mcp`, {
32 method: "POST",
33 headers: {
34 "content-type": "application/json",
35 accept: "application/json, text/event-stream",
36 authorization: `Bearer ${token}`,
37 },
38 body: JSON.stringify({
39 jsonrpc: "2.0",
40 id: id++,
41 method: "tools/call",
42 params: { name: "map", arguments: args },
43 }),
44 });
45 const body: any = await res.json();
46 const text: string = body.result.content[0].text;
47 return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
48 };
49
50 beforeAll(async () => {
51 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-map-space-"));
52 app = createApp({ dataDir, port: 0 });
53 servers = await serve(app);
54 const mk = async (username: string, first = false) => {
55 const u = await createUser(app.db, {
56 origin: "seed",
57 trusted: true,
58 username,
59 email: `${username}@forge.local`,
60 password: "a-good-passphrase",
61 adminIfFirst: first,
62 });
63 if (!u.ok) throw new Error(u.error);
64 promote(app.db, u.value);
65 return u.value;
66 };
67 const alice = await mk("alice", true);
68 const carol = await mk("carol");
69 aliceTok = createToken(app.db, alice.id, "rw", "rw").token;
70 carolTok = createToken(app.db, carol.id, "rw", "rw").token;
71 const made = await createRepo(app, alice, { name: "one", visibility: "public" });
72 if (!made.ok) throw new Error(String(made.error));
73 const repoId = made.value.id;
74 const open = (title: string) => {
75 const i = createIssue(app.db, { repoId, authorId: alice.id, title });
76 if (!i.ok) throw new Error(i.error);
77 return i.value;
78 };
79 open("one");
80 open("two");
81 open("three");
82 const blocked = open("four");
83 const blocker = open("five");
84 const dep = addDependency(app.db, blocked, blocker, alice.id);
85 if (!dep.ok) throw new Error(String(dep.error));
86 const closed = open("six");
87 app.db.query("UPDATE issue SET state = 'closed' WHERE id = ?1").run(closed.id);
88 }, 30_000);
89
90 afterAll(async () => {
91 servers.stop();
92 app.close();
93 await rm(dataDir, { recursive: true, force: true });
94 });
95
96 test("space is the spaceOf result for the caller", async () => {
97 const repo = getRepo(app.db, "alice", "one")!;
98 const alice = app.db.query("SELECT id FROM user WHERE username='alice'").get() as { id: string };
99 const got = await call(aliceTok, { app: "alice/one", view: "space" });
100 expect(got.error).toBeUndefined();
101 expect(stable(got.value)).toEqual(stable(spaceOf(app, repo, { id: alice.id } as any)));
102 expect(got.value.issues.length).toBeGreaterThan(0);
103 });
104
105 test("a junk view is an error naming the valid values", async () => {
106 const got = await call(aliceTok, { app: "alice/one", view: "bogus" });
107 expect(got.error).toContain("plan");
108 expect(got.error).toContain("space");
109 });
110
111 test("a private app is refused to one who may not read it, and open to its owner", async () => {
112 const alice = app.db.query("SELECT id FROM user WHERE username='alice'").get() as { id: string };
113 const made = await createRepo(app, alice as any, { name: "hidden", visibility: "private" });
114 if (!made.ok) throw new Error(String(made.error));
115 const issue = createIssue(app.db, { repoId: made.value.id, authorId: alice.id, title: "secret plan" });
116 if (!issue.ok) throw new Error(issue.error);
117 const mine = await call(aliceTok, { app: "alice/hidden", view: "space" });
118 expect(mine.error).toBeUndefined();
119 expect(JSON.stringify(mine.value)).toContain("secret plan");
120 const theirs = await call(carolTok, { app: "alice/hidden", view: "space" });
121 expect(theirs.value).toBeUndefined();
122 expect(theirs.error).toBeDefined();
123 expect(theirs.error).not.toContain("secret plan");
124 });
125
126 test("a public app reads the same for another caller as spaceOf gives that caller", async () => {
127 const repo = getRepo(app.db, "alice", "one")!;
128 const carol = app.db.query("SELECT id FROM user WHERE username='carol'").get() as { id: string };
129 const got = await call(carolTok, { app: "alice/one", view: "space" });
130 expect(got.error).toBeUndefined();
131 expect(stable(got.value)).toEqual(stable(spaceOf(app, repo, { id: carol.id } as any)));
132 });
133
134 test("a junk view with `first` set writes nothing", async () => {
135 const before = await call(aliceTok, { app: "alice/one" });
136 const order = JSON.stringify(before.value.ready);
137 const got = await call(aliceTok, { app: "alice/one", view: "bogus", first: 2 });
138 expect(got.error).toContain("space");
139 expect(JSON.stringify((await call(aliceTok, { app: "alice/one" })).value.ready)).toBe(order);
140 });
141
142 test("a large app's answer is cut and says so", async () => {
143 const alice = app.db.query("SELECT id FROM user WHERE username='alice'").get() as { id: string };
144 const made = await createRepo(app, alice as any, { name: "big", visibility: "public" });
145 if (!made.ok) throw new Error(String(made.error));
146 for (let n = 0; n < SPACE_ISSUES_MAX + 20; n++) {
147 createIssue(app.db, { repoId: made.value.id, authorId: alice.id, title: `t${n}` });
148 }
149 const got = await call(aliceTok, { app: "alice/big", view: "space" });
150 expect(got.value.issues.length).toBe(SPACE_ISSUES_MAX);
151 expect(got.value.truncated).toBe(true);
152 expect(got.value.total).toBe(SPACE_ISSUES_MAX + 20);
153 const small = await call(aliceTok, { app: "alice/one", view: "space" });
154 expect(small.value.truncated).toBeUndefined();
155 });
156 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs