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

MCP `fleet`: query and act with dry-run by default #10182

Parked opened this in answer to
Closed without merging

torque/forge:torque/450-mcp-fleet-query-and-act-with-dry-run-by → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +165 −4
docs/MCP.md +7
@@ -267,6 +267,13 @@ each bug `{ repo, number, priority, dueAt }`, soonest due first, at most 100,
267267 from `src/flow/bugs.ts`. An admin sees every repository; anyone else only
268268 public ones, as the terminal's bugs screen does.
269269
270 `flow` with `{ q, action, dryRun? }` is the fleet operation's door (#450):
271 the same `previewFleetOp` / `applyFleetOp` as `POST /api/v1/fleet/ops`, so
272 the same plan and receipt JSON plus a `says`. It plans unless `dryRun` is
273 `false`, on any token; applying takes an admin token as the API does, is
274 never an agent's, and the forge's own agent asks first. `limb` with
275 `action: "undo"` and the receipt's `id` reverts it for a day.
276
270277 `crew` with `{ kind: "week" }` is another (#10722), a forge admin's: `{ days, members }`,
271278 each member `{ username, merged, returned, spentUsd, idle }` over the last 7
272279 days, from `src/crew/week_card.ts` (spend from the usage ledger). The same
src/crew/conversation_confirm.ts +5
@@ -48,6 +48,11 @@ export const ASKING: Readonly<Record<string, Asking>> = {
4848 undo: (a) => `\`archive\` with \`archived: ${a["archived"] === false}\` turns it back`,
4949 },
5050 board_delete: { does: "delete a board" },
51 // A fleet operation applied over every row a query line selects; its plan and the rows ask nothing.
52 flow: {
53 does: "apply one fleet operation to every row a query selects",
54 undo: () => "`limb` with `action: \"undo\"` and the operation's id reverts it for a day",
55 },
5156 subscription_delete: { does: "remove a Claude subscription and its grants" },
5257 // Money: subscriptions, budgets, grants and limits.
5358 subscription_add: { does: "add a Claude login to the crew's pool", undo: () => "`subscription_delete` with its id removes it" },
src/http/mcp/tools/flow.ts +30 −3
@@ -9,7 +9,11 @@ import { COLUMNS, readSort, sortRows } from "../../../fleet/columns.ts";
99 import { viewFleet } from "../../../fleet/rows.ts";
1010 import { openBugs } from "../../../flow/bugs.ts";
1111 import { flowCached } from "../../../system/flow_cache.ts";
12 import { scopeAllows } from "../../../core/tokens.ts";
13 import { applyFleetOp, previewFleetOp, type FleetError } from "../../../actions/fleet.ts";
1214 import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
15 import type { User } from "../../../core/users.ts";
16 import type { Ctx } from "../../context.ts";
1317
1418 const number = (v: unknown): number | undefined =>
1519 typeof v === "number" && Number.isInteger(v) && v > 0 ? v : undefined;
@@ -23,28 +27,51 @@ const said = (subject: string, why: Why) =>
2327 ...(why.next === undefined ? {} : { next: why.next }),
2428 });
2529
30 const refused = (e: FleetError) => bad(e.code, e.message);
31
32 /** As `POST /api/v1/fleet/ops`: a plan by default on a read token; applying is an admin token's, the same JSON either way. */
33 async function fleetOp(ctx: Ctx, user: User, query: string, action: unknown, dryRun: unknown) {
34 if (dryRun !== undefined && typeof dryRun !== "boolean") return bad("invalid", "dryRun is true or false");
35 if (dryRun !== false) {
36 const plan = previewFleetOp(ctx.app, user, query, action);
37 return plan.ok
38 ? good({ dryRun: true, ...plan.value, says: "This is the plan; nothing changed. Send dryRun: false to do it." })
39 : refused(plan.error);
40 }
41 if (!scopeAllows(ctx.auth.scope ?? "ro", "admin")) return bad("forbidden", "applying a fleet operation takes an admin token");
42 const op = await applyFleetOp(ctx.app, user, query, action);
43 return op.ok
44 ? good({ dryRun: false, ...op.value, says: `Done. \`limb\` with action undo and operation ${op.value.id} reverts it for 24 hours.` })
45 : refused(op.error);
46 }
47
2648 export const tool: Tool = {
2749 name: "flow",
28 doc: "with no arguments, the forge's pipeline (a forge admin's, or an agent the owner granted `telemetry:read`; private repositories cut out): per stage counts, `oldestWaiting`, `capacity`, the bottleneck, the merge `queue` and what each reviewer has `reviewing`; with `{ q, sort? }`, the rows a fleet query line selects, as `/fleet` shows them: `{ kind, columns, items }`, only rows you may read, `sort` a column key led by `-` to reverse, a bad line answers its reason; with `{ kind: bugs }`, `{ open, overdue, bugs: [{ repo, number, priority, dueAt }] }` soonest due first, at most 100 (an admin sees all, anyone else public repositories); with `{ repo, issue? or pull? }` (a writer of the repository), why it is not moving: `{ subject, moving, state?, cause, says, clears, next? }`, the first of wall (a person decides new access), ceiling, hot_file, blocked_by, later_gate, no_builder, no_headroom, red_check, waiting_review that holds it (`flow/why.ts`); `repo` alone asks about the repository's builders",
50 doc: "with no arguments, the forge's pipeline (a forge admin's, or an agent the owner granted `telemetry:read`; private repositories cut out): per stage counts, `oldestWaiting`, `capacity`, the bottleneck, the merge `queue` and what each reviewer has `reviewing`; with `{ q, sort? }`, the rows a fleet query line selects, as `/fleet` shows them: `{ kind, columns, items }`, only rows you may read, `sort` a column key led by `-` to reverse, a bad line answers its reason; with `{ q, action, dryRun? }` (`action` a verb or `{ verb, value }`), the fleet operation `POST /api/v1/fleet/ops` answers: a plan of each row's before → after unless `dryRun` is false, then the receipt with its `id` (applying takes an admin token, never an agent's; `limb` undo reverts it for a day); with `{ kind: bugs }`, `{ open, overdue, bugs: [{ repo, number, priority, dueAt }] }` soonest due first, at most 100 (an admin sees all, anyone else public repositories); with `{ repo, issue? or pull? }` (a writer of the repository), why it is not moving: `{ subject, moving, state?, cause, says, clears, next? }`, the first of wall (a person decides new access), ceiling, hot_file, blocked_by, later_gate, no_builder, no_headroom, red_check, waiting_review that holds it (`flow/why.ts`); `repo` alone asks about the repository's builders",
2951 description:
30 "Pipeline (admin); `q`: `/fleet` rows; `kind:bugs`: bugs; `repo`+`issue`/`pull`: why stuck.",
52 "Pipeline (admin); `q`: `/fleet` rows, `action` plans/applies; `kind:bugs`: bugs; `repo`+`issue`/`pull`: why stuck.",
3153 inputSchema: {
3254 type: "object",
3355 properties: {
3456 kind: { type: "string", enum: ["bugs"] },
3557 q: { type: "string", maxLength: 500 },
3658 sort: { type: "string" },
59 action: { type: ["string", "object"] },
60 dryRun: { type: "boolean" },
3761 repo: REPO_ARG,
3862 issue: { type: "integer", minimum: 1 },
3963 pull: { type: "integer", minimum: 1 },
4064 },
4165 },
42 writes: false,
66 // Only `q` with `action` and `dryRun: false` writes; every other call reads.
67 writes: true,
68 readsWhen: (args) => args["action"] === undefined || args["dryRun"] !== false,
4369 async run(ctx, user, args) {
4470 if (args["q"] !== undefined) {
4571 const q = args["q"];
4672 if (typeof q !== "string" || q.trim() === "" || q.length > 500)
4773 return bad("invalid", "q is a fleet query line of at most 500 characters, like: repo autonomy:autonomous");
74 if (args["action"] !== undefined) return fleetOp(ctx, user, q, args["action"], args["dryRun"]);
4875 if (args["sort"] !== undefined && typeof args["sort"] !== "string") return bad("invalid", "sort is a column key");
4976 // As `/fleet`: the same `viewFleet`, so the same rows for the same viewer.
5077 const view = viewFleet(ctx.app.db, user, q);
test/conversation-confirm.test.ts +1 −1
@@ -137,7 +137,7 @@ describe("the one list of what asks first", () => {
137137 expect(listed || NOT_ASKED.has(t.name), `${t.name} writes: ask first (ASKING) or name it in NOT_ASKED`).toBe(true);
138138 expect(listed && NOT_ASKED.has(t.name), `${t.name} is on both lists`).toBe(false);
139139 }
140 for (const name of ["land_past_gate", "share", "invites", "egress_grants", "sever", "parent_unlink", "quotas", "spawn", "app_deploy", "stop", "converge", "origins", "cloud_account", "pinned_forge", "outsiders", "seal", "migrate"])
140 for (const name of ["land_past_gate", "share", "invites", "egress_grants", "sever", "parent_unlink", "quotas", "spawn", "app_deploy", "stop", "converge", "origins", "cloud_account", "pinned_forge", "outsiders", "seal", "migrate", "flow"])
141141 expect(ASKING[name], name).toBeDefined();
142142 });
143143
test/mcp-fleet-act.test.ts added +122
@@ -0,0 +1,122 @@
1 /**
2 * `flow` with `q` and `action` (#450): the fleet operation through MCP. It
3 * plans unless `dryRun` is false, answering the same JSON as
4 * `POST /api/v1/fleet/ops`; applying takes an admin token, as the API does,
5 * and is never an agent's.
6 */
7 import { afterAll, beforeAll, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { createAgent } from "../src/actions/crew.ts";
13 import { createRepo } from "../src/actions/repos.ts";
14 import { getRepoById, type Repo } from "../src/core/repos.ts";
15 import { createToken } from "../src/core/tokens.ts";
16 import { createUser } from "../src/core/users.ts";
17 import { serve, type Servers } from "../src/http/server.ts";
18 import { promote } from "./helpers/members.ts";
19
20 let dir: string;
21 let app: App;
22 let servers: Servers;
23 let ro: string;
24 let rw: string;
25 let admin: string;
26 let agentTok: string;
27 let engine: Repo;
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: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
34 body: JSON.stringify({ jsonrpc: "2.0", id: id++, method: "tools/call", params: { name: "flow", arguments: args } }),
35 });
36 const body: any = await res.json();
37 if (body.error) return { error: String(body.error.message) };
38 const text: string = body.result.content[0].text;
39 return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
40 };
41
42 const api = (token: string, input: unknown) =>
43 fetch(`${servers.url}/api/v1/fleet/ops`, {
44 method: "POST",
45 headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
46 body: JSON.stringify(input),
47 });
48
49 const ceiling = () => getRepoById(app.db, engine.id)!.autonomyCeilingUsd;
50
51 const query = "repo owner:alice";
52 const action = { verb: "ceiling", value: 7.5 };
53
54 beforeAll(async () => {
55 dir = await mkdtemp(join(tmpdir(), "forge-mcp-fleet-act-"));
56 app = createApp({ dataDir: dir, port: 0 });
57 servers = await serve(app);
58 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
59 if (!made.ok) throw new Error(made.error);
60 const alice = made.value;
61 promote(app.db, alice);
62 ro = createToken(app.db, alice.id, "ro", "ro").token;
63 rw = createToken(app.db, alice.id, "rw", "rw").token;
64 admin = createToken(app.db, alice.id, "admin", "admin").token;
65 const r = await createRepo(app, alice, { name: "engine", visibility: "public" });
66 if (!r.ok) throw new Error(String(r.error));
67 engine = r.value;
68 const agent = await createAgent(app, alice, { username: "looker", model: "", brief: "" });
69 if (!agent.ok) throw new Error(String(agent.error));
70 agentTok = createToken(app.db, agent.value.user.id, "agent", "admin").token;
71 }, 30_000);
72
73 afterAll(async () => {
74 servers.stop();
75 app.close();
76 await rm(dir, { recursive: true, force: true });
77 });
78
79 test("an action plans by default, on a read token, the API's dry-run JSON, and changes nothing", async () => {
80 const before = ceiling();
81 expect(before).not.toBe(7.5);
82 const plan = await call(ro, { q: query, action });
83 expect(plan.value.dryRun).toBe(true);
84 expect(plan.value.verb).toBe("ceiling");
85 expect(plan.value.rows).toHaveLength(1);
86 expect(plan.value.rows[0]).toMatchObject({ label: "alice/engine", outcome: "change" });
87 const { says, ...shape } = plan.value;
88 expect(says).toContain("nothing changed");
89 expect(shape).toEqual(await (await api(ro, { query, action })).json());
90 expect(ceiling()).toBe(before);
91 });
92
93 test("applying needs dryRun: false and an admin token; the receipt is the API's", async () => {
94 const before = ceiling();
95 expect((await call(ro, { q: query, action, dryRun: false })).error).toBeDefined();
96 expect((await call(rw, { q: query, action, dryRun: false })).error).toContain("admin token");
97 expect(ceiling()).toBe(before);
98
99 const done = await call(admin, { q: query, action, dryRun: false });
100 expect(done.value.dryRun).toBe(false);
101 expect(done.value.rows[0]).toMatchObject({ label: "alice/engine", outcome: "ok" });
102 expect(ceiling()).toBe(7.5);
103 const receipt: any = await (
104 await fetch(`${servers.url}/api/v1/fleet/ops/${done.value.id}`, { headers: { authorization: `Bearer ${ro}` } })
105 ).json();
106 expect(receipt.id).toBe(done.value.id);
107 expect(receipt.rows).toEqual(done.value.rows);
108 expect(done.value.says).toContain(done.value.id);
109 });
110
111 test("an agent may plan but never apply", async () => {
112 expect((await call(agentTok, { q: query, action: { verb: "ceiling", value: 3 } })).value?.dryRun).toBe(true);
113 const applied = await call(agentTok, { q: query, action: { verb: "ceiling", value: 3 }, dryRun: false });
114 expect(applied.error).toContain("person");
115 expect(ceiling()).toBe(7.5);
116 });
117
118 test("a bad action or dryRun answers its reason", async () => {
119 expect((await call(ro, { q: query, action: { verb: "nope" } })).error).toBeDefined();
120 expect((await call(ro, { q: query, action, dryRun: "yes" })).error).toContain("dryRun");
121 expect((await call(ro, { q: "repo cost:abc", action })).error).toBeDefined();
122 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs