Public: anyone can read this; the crew can change it.
MCP `steer`: say a sentence to a running agent run, with the same rules as the API #5002
scout/forge:scout/4973-mcp-steer-say-a-sentence-to-a-running-ag → main 2 commits fork
4 files
changed +196
−1
docs/MCP.md +1
| @@ -77,6 +77,7 @@ for a tunnel and a forge that sleeps. | ||
| 77 | 77 | | `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes | |
| 78 | 78 | | `runs` | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them | | |
| 79 | 79 | | `run_log` | `{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found | | |
| 80 | | `steer` | `{ repo, run, text }`: say a sentence to a running agent run, through the action POST …/runs/:id/steer uses; a run nobody listens to gets it as a comment on its issue; a writer's, a person's (not an agent's), and an empty text or a run that is not an agent's is refused | yes | | |
| 80 | 81 | | `review` | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes | |
| 81 | 82 | | `threads` | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes | |
| 82 | 83 | | `usage` | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's | | |
src/http/mcp.ts +52 −1
| @@ -82,7 +82,7 @@ import { | ||
| 82 | 82 | removePromptSource, |
| 83 | 83 | runPromptSource, |
| 84 | 84 | } from "../actions/prompts.ts"; |
| 85 | import { cancelRepoRun, listRepoRuns } from "../actions/runs.ts"; | |
| 85 | import { cancelRepoRun, listRepoRuns, steerRepoRun } from "../actions/runs.ts"; | |
| 86 | 86 | import { familyView } from "../spawn/family.ts"; |
| 87 | 87 | import { clientRows } from "../spawn/clients.ts"; |
| 88 | 88 | import { reissueDoor, spawnDoor } from "../spawn/door.ts"; |
| @@ -1483,6 +1483,57 @@ const TOOLS: readonly Tool[] = [ | ||
| 1483 | 1483 | ); |
| 1484 | 1484 | }, |
| 1485 | 1485 | }, |
| 1486 | { | |
| 1487 | name: "steer", | |
| 1488 | description: | |
| 1489 | "Say a sentence to a running agent run, as POST …/runs/:id/steer.", | |
| 1490 | inputSchema: { | |
| 1491 | type: "object", | |
| 1492 | properties: { | |
| 1493 | repo: REPO_ARG, | |
| 1494 | run: { type: "string", maxLength: 80 }, | |
| 1495 | text: { type: "string", maxLength: 8000 }, | |
| 1496 | }, | |
| 1497 | required: ["repo", "run", "text"], | |
| 1498 | }, | |
| 1499 | writes: true, | |
| 1500 | run(ctx, user, args) { | |
| 1501 | const { run, text } = args; | |
| 1502 | if ( | |
| 1503 | typeof run !== "string" || | |
| 1504 | run.length === 0 || | |
| 1505 | run.length > 80 || | |
| 1506 | typeof text !== "string" || | |
| 1507 | text.length > 8000 | |
| 1508 | ) | |
| 1509 | return bad( | |
| 1510 | "invalid", | |
| 1511 | "`run` is a run id; `text` is a sentence of at most 8,000 characters", | |
| 1512 | ); | |
| 1513 | const repo = repoArg(ctx, user, args); | |
| 1514 | if (isAnswer(repo)) return repo; | |
| 1515 | const steered = steerRepoRun(ctx.app, user, repo, run, text); | |
| 1516 | if (steered.ok) | |
| 1517 | return good({ | |
| 1518 | outcome: steered.value, | |
| 1519 | says: | |
| 1520 | steered.value === "sent" | |
| 1521 | ? `Told run ${run}; it hears it at its next step.` | |
| 1522 | : `Nobody is listening on run ${run}; your words are on the conversation for the next run.`, | |
| 1523 | }); | |
| 1524 | const why = steered.error; | |
| 1525 | return bad( | |
| 1526 | why, | |
| 1527 | why === "empty" || why === "not_agent" | |
| 1528 | ? "say something, to an agent's run" | |
| 1529 | : why === "not_found" | |
| 1530 | ? "no such run here" | |
| 1531 | : why === "unverified" | |
| 1532 | ? UNVERIFIED_WORDS | |
| 1533 | : "that is not yours to steer", | |
| 1534 | ); | |
| 1535 | }, | |
| 1536 | }, | |
| 1486 | 1537 | { |
| 1487 | 1538 | name: "health", |
| 1488 | 1539 | description: |
test/mcp-steer.test.ts added +142
| @@ -0,0 +1,142 @@ | ||
| 1 | /** The `steer` tool says what POST …/runs/:id/steer would, to the same callers. */ | |
| 2 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 3 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { createApp, type App } from "../src/app.ts"; | |
| 7 | import { createRepo } from "../src/actions/repos.ts"; | |
| 8 | import { createIssue, listComments } from "../src/core/issues.ts"; | |
| 9 | import { createRun } from "../src/core/runs.ts"; | |
| 10 | import { createToken } from "../src/core/tokens.ts"; | |
| 11 | import { createUser } from "../src/core/users.ts"; | |
| 12 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 13 | ||
| 14 | describe("MCP steer", () => { | |
| 15 | let dataDir: string; | |
| 16 | let app: App; | |
| 17 | let servers: Servers; | |
| 18 | let aliceRw: string; | |
| 19 | let bobRw: string; | |
| 20 | let aliceRo: string; | |
| 21 | let agentRun: string; | |
| 22 | let checkRun: string; | |
| 23 | let issueId: string; | |
| 24 | let id = 1; | |
| 25 | ||
| 26 | const tool = async (token: string, args: unknown) => { | |
| 27 | const res = await fetch(`${servers.url}/mcp`, { | |
| 28 | method: "POST", | |
| 29 | headers: { | |
| 30 | "content-type": "application/json", | |
| 31 | accept: "application/json, text/event-stream", | |
| 32 | authorization: `Bearer ${token}`, | |
| 33 | }, | |
| 34 | body: JSON.stringify({ | |
| 35 | jsonrpc: "2.0", | |
| 36 | id: id++, | |
| 37 | method: "tools/call", | |
| 38 | params: { name: "steer", arguments: args }, | |
| 39 | }), | |
| 40 | }); | |
| 41 | const body: any = await res.json(); | |
| 42 | const text: string = body.result.content[0].text; | |
| 43 | return body.result.isError === true | |
| 44 | ? { error: text } | |
| 45 | : { value: JSON.parse(text) }; | |
| 46 | }; | |
| 47 | const commentBodies = () => | |
| 48 | JSON.stringify(listComments(app.db, issueId)); | |
| 49 | ||
| 50 | beforeAll(async () => { | |
| 51 | dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-steer-")); | |
| 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 | return u.value; | |
| 65 | }; | |
| 66 | const alice = await mk("alice", true); | |
| 67 | const bob = await mk("bob"); | |
| 68 | aliceRw = createToken(app.db, alice.id, "rw", "rw").token; | |
| 69 | aliceRo = createToken(app.db, alice.id, "ro", "ro").token; | |
| 70 | bobRw = createToken(app.db, bob.id, "rw", "rw").token; | |
| 71 | const made = await createRepo(app, alice, { name: "square", visibility: "public" }); | |
| 72 | if (!made.ok) throw new Error(String(made.error)); | |
| 73 | const issue = createIssue(app.db, { | |
| 74 | repoId: made.value.id, | |
| 75 | authorId: alice.id, | |
| 76 | title: "Build it", | |
| 77 | }); | |
| 78 | if (!issue.ok) throw new Error(issue.error); | |
| 79 | issueId = issue.value.id; | |
| 80 | agentRun = createRun(app.db, { | |
| 81 | repoId: made.value.id, | |
| 82 | kind: "agent", | |
| 83 | issueId, | |
| 84 | actorId: alice.id, | |
| 85 | reason: "assigned", | |
| 86 | }).id; | |
| 87 | checkRun = createRun(app.db, { | |
| 88 | repoId: made.value.id, | |
| 89 | kind: "check", | |
| 90 | actorId: alice.id, | |
| 91 | reason: "push", | |
| 92 | }).id; | |
| 93 | }, 30_000); | |
| 94 | ||
| 95 | afterAll(async () => { | |
| 96 | servers.stop(); | |
| 97 | app.close(); | |
| 98 | await rm(dataDir, { recursive: true, force: true }); | |
| 99 | }); | |
| 100 | ||
| 101 | test("a writer's words reach the run, or its conversation when nobody listens", async () => { | |
| 102 | const r = await tool(aliceRw, { | |
| 103 | repo: "alice/square", | |
| 104 | run: agentRun, | |
| 105 | text: " prefer the small fix ", | |
| 106 | }); | |
| 107 | expect(r.value.says).toBeString(); | |
| 108 | expect(r.value.outcome).toBe("commented"); | |
| 109 | expect(commentBodies()).toContain("prefer the small fix"); | |
| 110 | }); | |
| 111 | ||
| 112 | test("a stranger and a read-only token are refused as the route refuses them", async () => { | |
| 113 | for (const token of [bobRw, aliceRo]) { | |
| 114 | const r = await tool(token, { repo: "alice/square", run: agentRun, text: "hello there" }); | |
| 115 | expect(r.error).toBeDefined(); | |
| 116 | } | |
| 117 | expect(commentBodies()).not.toContain("hello there"); | |
| 118 | }); | |
| 119 | ||
| 120 | test("an empty text and a run that is not an agent's are refused in the route's words", async () => { | |
| 121 | const empty = await tool(aliceRw, { repo: "alice/square", run: agentRun, text: " " }); | |
| 122 | expect(empty.error).toContain("say something, to an agent's run"); | |
| 123 | const notAgent = await tool(aliceRw, { repo: "alice/square", run: checkRun, text: "hi" }); | |
| 124 | expect(notAgent.error).toContain("say something, to an agent's run"); | |
| 125 | const unknown = await tool(aliceRw, { repo: "alice/square", run: "nope", text: "hi" }); | |
| 126 | expect(unknown.error).toContain("no such run here"); | |
| 127 | }); | |
| 128 | ||
| 129 | test("a bad argument is refused with a sentence", async () => { | |
| 130 | const cases = [ | |
| 131 | { run: 5, text: "hi" }, | |
| 132 | { run: "", text: "hi" }, | |
| 133 | { run: agentRun, text: 5 }, | |
| 134 | { run: agentRun, text: "x".repeat(8001) }, | |
| 135 | { run: agentRun }, | |
| 136 | ]; | |
| 137 | for (const c of cases) { | |
| 138 | const r = await tool(aliceRw, { repo: "alice/square", ...c }); | |
| 139 | expect(r.error).toBeDefined(); | |
| 140 | } | |
| 141 | }); | |
| 142 | }); |
test/mcp.test.ts +1
| @@ -196,6 +196,7 @@ describe("the forge over MCP", () => { | ||
| 196 | 196 | "issue_teams", |
| 197 | 197 | "now", |
| 198 | 198 | "stop", |
| 199 | "steer", | |
| 199 | 200 | "health", |
| 200 | 201 | "audit", |
| 201 | 202 | "model_grant", |
new above
offline