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 #5126

Parked opened this
Closed without merging

scout/forge:scout/4973-mcp-steer-say-a-sentence-to-a-running-ag → main 4 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +213 −1
docs/MCP.md +1
@@ -78,6 +78,7 @@ for a tunnel and a forge that sleeps.
7878 | `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 |
7979 | `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 | |
8080 | `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 | |
81 | `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 |
8182 | `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 |
8283 | `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 |
8384 | `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 {
8282 removePromptSource,
8383 runPromptSource,
8484 } from "../actions/prompts.ts";
85 import { cancelRepoRun, listRepoRuns } from "../actions/runs.ts";
85 import { cancelRepoRun, listRepoRuns, steerRepoRun } from "../actions/runs.ts";
8686 import { familyView } from "../spawn/family.ts";
8787 import { clientRows } from "../spawn/clients.ts";
8888 import { reissueDoor, spawnDoor } from "../spawn/door.ts";
@@ -1519,6 +1519,57 @@ const TOOLS: readonly Tool[] = [
15191519 );
15201520 },
15211521 },
1522 {
1523 name: "steer",
1524 description:
1525 "Say a sentence to a running agent run, as POST …/runs/:id/steer.",
1526 inputSchema: {
1527 type: "object",
1528 properties: {
1529 repo: REPO_ARG,
1530 run: { type: "string", maxLength: 80 },
1531 text: { type: "string", maxLength: 8000 },
1532 },
1533 required: ["repo", "run", "text"],
1534 },
1535 writes: true,
1536 run(ctx, user, args) {
1537 const { run, text } = args;
1538 if (
1539 typeof run !== "string" ||
1540 run.length === 0 ||
1541 run.length > 80 ||
1542 typeof text !== "string" ||
1543 text.length > 8000
1544 )
1545 return bad(
1546 "invalid",
1547 "`run` is a run id; `text` is a sentence of at most 8,000 characters",
1548 );
1549 const repo = repoArg(ctx, user, args);
1550 if (isAnswer(repo)) return repo;
1551 const steered = steerRepoRun(ctx.app, user, repo, run, text);
1552 if (steered.ok)
1553 return good({
1554 outcome: steered.value,
1555 says:
1556 steered.value === "sent"
1557 ? `Told run ${run}; it hears it at its next step.`
1558 : `Nobody is listening on run ${run}; your words are on the conversation for the next run.`,
1559 });
1560 const why = steered.error;
1561 return bad(
1562 why,
1563 why === "empty" || why === "not_agent"
1564 ? "say something, to an agent's run"
1565 : why === "not_found"
1566 ? "no such run here"
1567 : why === "unverified"
1568 ? UNVERIFIED_WORDS
1569 : "that is not yours to steer",

This fallback covers forbidden from the agent rule and from a non-writer alike, and that is fine. Pin it with the agent test in test/mcp-steer.test.ts so a later change to the action can't open this door to agents without a test failing.

1570 );
1571 },
1572 },
15221573 {
15231574 name: "health",
15241575 description:
test/mcp-steer.test.ts added +159
@@ -0,0 +1,159 @@
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 botRw: string;
22 let agentRun: string;
23 let checkRun: string;
24 let issueId: string;
25 let id = 1;
26
27 const tool = async (token: string, args: unknown) => {
28 const res = await fetch(`${servers.url}/mcp`, {
29 method: "POST",
30 headers: {
31 "content-type": "application/json",
32 accept: "application/json, text/event-stream",
33 authorization: `Bearer ${token}`,
34 },
35 body: JSON.stringify({
36 jsonrpc: "2.0",
37 id: id++,
38 method: "tools/call",
39 params: { name: "steer", arguments: args },
40 }),
41 });
42 const body: any = await res.json();
43 const text: string = body.result.content[0].text;
44 return body.result.isError === true
45 ? { error: text }
46 : { value: JSON.parse(text) };
47 };
48 const commentBodies = () =>
49 JSON.stringify(listComments(app.db, issueId));
50
51 beforeAll(async () => {
52 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-steer-"));
53 app = createApp({ dataDir, port: 0 });
54 servers = await serve(app);
55 const mk = async (username: string, first = false) => {
56 const u = await createUser(app.db, {
57 origin: "seed",
58 trusted: true,
59 username,
60 email: `${username}@forge.local`,
61 password: "a-good-passphrase",
62 adminIfFirst: first,
63 });
64 if (!u.ok) throw new Error(u.error);
65 return u.value;
66 };
67 const alice = await mk("alice", true);
68 const bob = await mk("bob");
69 aliceRw = createToken(app.db, alice.id, "rw", "rw").token;
70 aliceRo = createToken(app.db, alice.id, "ro", "ro").token;
71 bobRw = createToken(app.db, bob.id, "rw", "rw").token;
72 const made = await createRepo(app, alice, { name: "square", visibility: "public" });
73 if (!made.ok) throw new Error(String(made.error));
74 const bot = await createUser(app.db, {
75 origin: "agent",
76 username: "bot",
77 email: "[email protected]",
78 agent: true,
79 });
80 if (!bot.ok) throw new Error(bot.error);
81 app.db
82 .query("INSERT INTO repo_crew (repo_id, user_id) VALUES (?1, ?2)")
83 .run(made.value.id, bot.value.id);
84 botRw = createToken(app.db, bot.value.id, "rw", "rw").token;
85 const issue = createIssue(app.db, {
86 repoId: made.value.id,
87 authorId: alice.id,
88 title: "Build it",
89 });
90 if (!issue.ok) throw new Error(issue.error);
91 issueId = issue.value.id;
92 agentRun = createRun(app.db, {
93 repoId: made.value.id,
94 kind: "agent",
95 issueId,
96 actorId: alice.id,
97 reason: "assigned",
98 }).id;
99 checkRun = createRun(app.db, {
100 repoId: made.value.id,
101 kind: "check",
102 actorId: alice.id,
103 reason: "push",
104 }).id;
105 }, 30_000);
106
107 afterAll(async () => {
108 servers.stop();
109 app.close();
110 await rm(dataDir, { recursive: true, force: true });
111 });
112
outdated

High (missing test of the security rule on the agents' door): add an agent caller here. An agent's rw token on a repository it writes to must be refused (forbidden, "that is not yours to steer") and must leave no comment. Also assert the refusal words rather than toBeDefined(), so this test fails if the refusal comes from the wrong place.

113 test("a writer's words reach the run, or its conversation when nobody listens", async () => {
114 const r = await tool(aliceRw, {
115 repo: "alice/square",
116 run: agentRun,
117 text: " prefer the small fix ",
118 });
119 expect(r.value.says).toBeString();
120 expect(r.value.outcome).toBe("commented");
121 expect(commentBodies()).toContain("prefer the small fix");
122 });
123
124 test("a stranger and a read-only token are refused as the route refuses them", async () => {
125 const say = { repo: "alice/square", run: agentRun, text: "hello there" };
126 expect((await tool(bobRw, say)).error).toContain("that is not yours to steer");
127 expect((await tool(aliceRo, say)).error).toContain("this token may read, not act");
128 expect(commentBodies()).not.toContain("hello there");
129 });
130
131 test("an agent's write token is refused: a run costs money, so steering is a person's call", async () => {
132 const r = await tool(botRw, { repo: "alice/square", run: agentRun, text: "agent words" });
133 expect(r.error).toContain("that is not yours to steer");
134 expect(commentBodies()).not.toContain("agent words");
135 });
136
137 test("an empty text and a run that is not an agent's are refused in the route's words", async () => {
138 const empty = await tool(aliceRw, { repo: "alice/square", run: agentRun, text: " " });
139 expect(empty.error).toContain("say something, to an agent's run");
140 const notAgent = await tool(aliceRw, { repo: "alice/square", run: checkRun, text: "hi" });
141 expect(notAgent.error).toContain("say something, to an agent's run");
142 const unknown = await tool(aliceRw, { repo: "alice/square", run: "nope", text: "hi" });
143 expect(unknown.error).toContain("no such run here");
144 });
145
146 test("a bad argument is refused with a sentence", async () => {
147 const cases = [
148 { run: 5, text: "hi" },
149 { run: "", text: "hi" },
150 { run: agentRun, text: 5 },
151 { run: agentRun, text: "x".repeat(8001) },
152 { run: agentRun },
153 ];
154 for (const c of cases) {
155 const r = await tool(aliceRw, { repo: "alice/square", ...c });
156 expect(r.error).toBeDefined();
157 }
158 });
159 });
test/mcp.test.ts +1
@@ -196,6 +196,7 @@ describe("the forge over MCP", () => {
196196 "issue_teams",
197197 "now",
198198 "stop",
199 "steer",
199200 "health",
200201 "audit",
201202 "model_grant",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs