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

Parked opened this
Closed without merging

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

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +196 −1
docs/MCP.md +1
@@ -77,6 +77,7 @@ for a tunnel and a forge that sleeps.
7777 | `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 |
7878 | `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 | |
7979 | `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 |
8081 | `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 |
8182 | `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 |
8283 | `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";
@@ -1483,6 +1483,57 @@ const TOOLS: readonly Tool[] = [
14831483 );
14841484 },
14851485 },
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 },
14861537 {
14871538 name: "health",
14881539 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", () => {
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