Public: anyone can read this; the crew can change it.
MCP `fleet`: query and act with dry-run by default #10182
torque/forge:torque/450-mcp-fleet-query-and-act-with-dry-run-by → main 3 commits fork
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, | ||
| 267 | 267 | from `src/flow/bugs.ts`. An admin sees every repository; anyone else only |
| 268 | 268 | public ones, as the terminal's bugs screen does. |
| 269 | 269 | |
| 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 | ||
| 270 | 277 | `crew` with `{ kind: "week" }` is another (#10722), a forge admin's: `{ days, members }`, |
| 271 | 278 | each member `{ username, merged, returned, spentUsd, idle }` over the last 7 |
| 272 | 279 | 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>> = { | ||
| 48 | 48 | undo: (a) => `\`archive\` with \`archived: ${a["archived"] === false}\` turns it back`, |
| 49 | 49 | }, |
| 50 | 50 | 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 | }, | |
| 51 | 56 | subscription_delete: { does: "remove a Claude subscription and its grants" }, |
| 52 | 57 | // Money: subscriptions, budgets, grants and limits. |
| 53 | 58 | 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"; | ||
| 9 | 9 | import { viewFleet } from "../../../fleet/rows.ts"; |
| 10 | 10 | import { openBugs } from "../../../flow/bugs.ts"; |
| 11 | 11 | import { flowCached } from "../../../system/flow_cache.ts"; |
| 12 | import { scopeAllows } from "../../../core/tokens.ts"; | |
| 13 | import { applyFleetOp, previewFleetOp, type FleetError } from "../../../actions/fleet.ts"; | |
| 12 | 14 | 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"; | |
| 13 | 17 | |
| 14 | 18 | const number = (v: unknown): number | undefined => |
| 15 | 19 | typeof v === "number" && Number.isInteger(v) && v > 0 ? v : undefined; |
| @@ -23,28 +27,51 @@ const said = (subject: string, why: Why) => | ||
| 23 | 27 | ...(why.next === undefined ? {} : { next: why.next }), |
| 24 | 28 | }); |
| 25 | 29 | |
| 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 | ||
| 26 | 48 | export const tool: Tool = { |
| 27 | 49 | 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", | |
| 29 | 51 | 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.", | |
| 31 | 53 | inputSchema: { |
| 32 | 54 | type: "object", |
| 33 | 55 | properties: { |
| 34 | 56 | kind: { type: "string", enum: ["bugs"] }, |
| 35 | 57 | q: { type: "string", maxLength: 500 }, |
| 36 | 58 | sort: { type: "string" }, |
| 59 | action: { type: ["string", "object"] }, | |
| 60 | dryRun: { type: "boolean" }, | |
| 37 | 61 | repo: REPO_ARG, |
| 38 | 62 | issue: { type: "integer", minimum: 1 }, |
| 39 | 63 | pull: { type: "integer", minimum: 1 }, |
| 40 | 64 | }, |
| 41 | 65 | }, |
| 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, | |
| 43 | 69 | async run(ctx, user, args) { |
| 44 | 70 | if (args["q"] !== undefined) { |
| 45 | 71 | const q = args["q"]; |
| 46 | 72 | if (typeof q !== "string" || q.trim() === "" || q.length > 500) |
| 47 | 73 | 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"]); | |
| 48 | 75 | if (args["sort"] !== undefined && typeof args["sort"] !== "string") return bad("invalid", "sort is a column key"); |
| 49 | 76 | // As `/fleet`: the same `viewFleet`, so the same rows for the same viewer. |
| 50 | 77 | 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", () => { | ||
| 137 | 137 | expect(listed || NOT_ASKED.has(t.name), `${t.name} writes: ask first (ASKING) or name it in NOT_ASKED`).toBe(true); |
| 138 | 138 | expect(listed && NOT_ASKED.has(t.name), `${t.name} is on both lists`).toBe(false); |
| 139 | 139 | } |
| 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"]) | |
| 141 | 141 | expect(ASKING[name], name).toBeDefined(); |
| 142 | 142 | }); |
| 143 | 143 |
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 | }); |
new above
offline