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

MCP `approve_here`: a writer lets an origin fork's pull run here, its check and preview starting at its current head #5016

Parked opened this
Closed without merging

scout/forge:scout/5004-mcp-approve-here-a-writer-lets-an-origin → main 5 commits fork 4 threads · 4 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +315 −21
docs/MCP.md +1
@@ -78,6 +78,7 @@ for a tunnel and a forge that sleeps.
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 | |
8080 | `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 | `approve_here` | `{ repo, number }`: let an origin fork's pull run here: approve its current head so its check and preview start, through `POST …/pulls/:number/approve-here`'s action and refusals (a writer's, never an agent's, never your own pull); answers `says`, the `commit` approved and `url`; a later push needs approving again | 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 | |
8384 | `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes |
src/http/mcp.ts +68 −21
@@ -69,6 +69,7 @@ import {
6969 unlinkIssue,
7070 } from "../actions/dependencies.ts";
7171 import {
72 approveToRun,
7273 pullThreads,
7374 resolveReviewThread,
7475 submitReview,
@@ -619,7 +620,7 @@ const TOOLS: readonly Tool[] = [
619620 {
620621 name: "tell",
621622 description:
622 "Tell an app's crew what should change (first line is the title). Without `repo` it is only kept; answers a thought id.",
623 "Tell an app's crew what to change (first line is the title). Without `repo` it is kept; answers a thought id.",
623624 inputSchema: {
624625 type: "object",
625626 properties: {
@@ -757,7 +758,7 @@ const TOOLS: readonly Tool[] = [
757758 {
758759 name: "issue",
759760 description:
760 "Read one issue with its comments, `blockedBy` and `blocks`. A crew agent sees `untrusted: true` on text by non-writers.",
761 "One issue with comments, `blockedBy`, `blocks`. A crew agent sees `untrusted: true` on non-writers' text.",
761762 inputSchema: {
762763 type: "object",
763764 properties: {
@@ -1110,7 +1111,7 @@ const TOOLS: readonly Tool[] = [
11101111 {
11111112 name: "asks_act",
11121113 description:
1113 "Decide many asks: dismiss, decline, ship (never undone), close (`reason`), mute, replan. `items`: ids from `asks`, or `issue:<id>`.",
1114 "Decide many asks: dismiss, decline, ship (final), close (`reason`), mute, replan. `items`: `asks` ids/`issue:<id>`.",
11141115 inputSchema: {
11151116 type: "object",
11161117 properties: {
@@ -1134,7 +1135,7 @@ const TOOLS: readonly Tool[] = [
11341135 {
11351136 name: "asks_decide",
11361137 description:
1137 "Let the decider answer a hand-over (`item` is the row's `parked:<id>`). Only a sure set_aside (70%+) clears the card.",
1138 "Let the decider answer a hand-over (`item`: the row's `parked:<id>`). Only a sure set_aside (70%+) clears it.",
11381139 inputSchema: {
11391140 type: "object",
11401141 properties: { item: { type: "string", maxLength: 80 } },
@@ -1298,7 +1299,7 @@ const TOOLS: readonly Tool[] = [
12981299 {
12991300 name: "issue_teams",
13001301 description:
1301 "Name the crew teams (design, data-science, security, platform) on an issue: at most two; each reviews the closing pull.",
1302 "Name crew teams (design, data-science, security, platform) on an issue: at most two; each reviews its closing pull.",
13021303 inputSchema: {
13031304 type: "object",
13041305 properties: {
@@ -1371,7 +1372,7 @@ const TOOLS: readonly Tool[] = [
13711372 {
13721373 name: "now",
13731374 description:
1374 "What the crew is doing now across your apps: who, on what, since when, cost so far; what waits on your review first.",
1375 "What the crew is doing now across your apps: who, on what, since when, cost; what waits on your review first.",
13751376 inputSchema: { type: "object", properties: {} },
13761377 writes: false,
13771378 run(ctx, user) {
@@ -1542,7 +1543,7 @@ const TOOLS: readonly Tool[] = [
15421543 {
15431544 name: "model_grant",
15441545 description:
1545 "Give a person's account a capped monthly model grant in dollars (`usdPerMonth` 0 takes it back). Person admins only.",
1546 "Give a person a capped monthly model grant in dollars (`usdPerMonth` 0 takes it back). Person admins only.",
15461547 inputSchema: {
15471548 type: "object",
15481549 properties: {
@@ -1686,7 +1687,7 @@ const TOOLS: readonly Tool[] = [
16861687 {
16871688 name: "model_ceiling",
16881689 description:
1689 "Set an account's daily and per-run model spend ceilings in dollars; a run past either does not start.",
1690 "Set an account's daily and per-run model spend ceilings in dollars; a run past either won't start.",
16901691 inputSchema: {
16911692 type: "object",
16921693 properties: {
@@ -1750,7 +1751,7 @@ const TOOLS: readonly Tool[] = [
17501751 {
17511752 name: "outsiders",
17521753 description:
1753 "Whether people who cannot write an app may direct its crew (off by default). Without `on`, says which.",
1754 "Whether people who cannot write an app may direct its crew (off by default). Without `on`, reads it.",
17541755 inputSchema: {
17551756 type: "object",
17561757 properties: {
@@ -1827,7 +1828,7 @@ const TOOLS: readonly Tool[] = [
18271828 {
18281829 name: "decisions_by",
18291830 description:
1830 "The standing rule for a repository's parked hand-over cards: `me`, `decider`, or `decider_tell`. Without `by`, reads it.",
1831 "The rule for a repository's parked hand-over cards: `me`, `decider`, `decider_tell`. Without `by`, reads it.",
18311832 inputSchema: {
18321833 type: "object",
18331834 properties: {
@@ -2201,7 +2202,7 @@ const TOOLS: readonly Tool[] = [
22012202 {
22022203 name: "spawn",
22032204 description:
2204 "Spawn a child forge with the named apps and the crew's briefs. Plans first (dryRun false spawns).",
2205 "Spawn a child forge with the named apps and crew briefs. Plans first (dryRun false spawns).",
22052206 inputSchema: {
22062207 type: "object",
22072208 properties: {
@@ -2336,7 +2337,7 @@ const TOOLS: readonly Tool[] = [
23362337 {
23372338 name: "forges",
23382339 description:
2339 "The forges you sent from here (an admin's list): name, address, whom for, apps, claimed or not, last activity.",
2340 "The forges you sent from here (admin): name, address, whom for, apps, claimed or not, last activity.",
23402341 inputSchema: { type: "object", properties: {} },
23412342 writes: false,
23422343 async run(ctx, user) {
@@ -2355,7 +2356,7 @@ const TOOLS: readonly Tool[] = [
23552356 {
23562357 name: "claim_link",
23572358 description:
2358 "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one then stops at once. Nothing changes without it.",
2359 "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one stops. Else nothing changes.",
23592360 inputSchema: {
23602361 type: "object",
23612362 properties: {
@@ -2377,7 +2378,7 @@ const TOOLS: readonly Tool[] = [
23772378 {
23782379 name: "take_updates",
23792380 description:
2380 "Take the parent forge's updates into a fork: one pull on a spawned forge; otherwise a fast-forward or clean merge.",
2381 "Take the parent's updates into a fork: one pull on a spawned forge; else a fast-forward or clean merge.",
23812382 inputSchema: {
23822383 type: "object",
23832384 properties: { repo: REPO_ARG },
@@ -2597,7 +2598,7 @@ const TOOLS: readonly Tool[] = [
25972598 {
25982599 name: "asked",
25992600 description:
2600 "What people asked the crew for, in repositories you can write: by default what has nothing merged yet, oldest first.",
2601 "What people asked the crew for, in repositories you can write: by default nothing merged yet, oldest first.",
26012602 inputSchema: {
26022603 type: "object",
26032604 properties: {
@@ -2922,7 +2923,7 @@ const TOOLS: readonly Tool[] = [
29222923 {
29232924 name: "front_page",
29242925 description:
2925 "The forge's front page as a stranger sees it. A site admin also gets the picks and sets them with `pinned`, `hidden`, `weights`.",
2926 "The front page as a stranger sees it. A site admin also gets the picks and sets `pinned`, `hidden`, `weights`.",
29262927 inputSchema: {
29272928 type: "object",
29282929 properties: {
@@ -3001,7 +3002,7 @@ const TOOLS: readonly Tool[] = [
30013002 {
30023003 name: "milestones",
30033004 description:
3004 "How far each thing asked for is. With `app`: the plan's top-level limbs with done/total, building and recent merges.",
3005 "How far each thing asked for is. With `app`: the plan's top limbs with done/total, building and recent merges.",
30053006 inputSchema: {
30063007 type: "object",
30073008 properties: {
@@ -3161,7 +3162,7 @@ const TOOLS: readonly Tool[] = [
31613162 {
31623163 name: "limb",
31633164 description:
3164 "One action on a plan limb: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.",
3165 "A limb action: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.",
31653166 inputSchema: {
31663167 type: "object",
31673168 properties: {
@@ -3254,7 +3255,7 @@ const TOOLS: readonly Tool[] = [
32543255 {
32553256 name: "returns",
32563257 description:
3257 "What the crew's tokens bought over the last days (1–90, default 7): dollars, runs, changes landed, cost per change.",
3258 "What the crew's tokens bought over `days` (1–90, default 7): dollars, runs, changes landed, cost per change.",
32583259 inputSchema: {
32593260 type: "object",
32603261 properties: {
@@ -3332,6 +3333,52 @@ const TOOLS: readonly Tool[] = [
33323333 });
33333334 },
33343335 },
3336 {
3337 name: "approve_here",
3338 description:
3339 "Let an origin fork's pull run here, at its current head.",
3340 inputSchema: {
3341 type: "object",
3342 properties: {
3343 repo: REPO_ARG,
3344 number: { type: "integer", minimum: 1 },
3345 },
3346 required: ["repo", "number"],
3347 },
3348 writes: true,
3349 async run(ctx, user, args) {
3350 const repo = repoArg(ctx, user, args);
3351 if (isAnswer(repo)) return repo;
3352 const n = args["number"];
3353 const pull =
3354 typeof n === "number" && Number.isInteger(n) && n > 0
3355 ? getPull(ctx.app.db, repo.id, n)
3356 : undefined;
3357 if (pull === undefined || !mayView(ctx.app.db, repo, pull, user))
3358 return bad("no_such_pull", `no pull #${String(n)}`);
3359 const done = await approveToRun(ctx.app, user, repo, pull);
3360 if (!done.ok) {
3361 const error = done.error;
3362 return bad(
3363 "refused",
3364 error === "self_review"
3365 ? "You cannot approve your own pull request."
3366 : error === "not_foreign"
3367 ? "This pull needs no approval to run."
3368 : error === "not_open"
3369 ? "This pull is closed."
3370 : error === "forbidden"
3371 ? "Letting a pull run needs write access, and a person's."
3372 : "That pull could not be approved.",
3373 );
3374 }
3375 return good({
3376 says: `Approved to run at ${done.value.commitOid.slice(0, 7)}; a new push needs approving again.`,
3377 commit: done.value.commitOid,
3378 url: `/${repo.ownerName}/${repo.name}/pulls/${pull.number}`,
3379 });
3380 },
3381 },
33353382 {
33363383 name: "threads",
33373384 description:
@@ -3809,7 +3856,7 @@ const TOOLS: readonly Tool[] = [
38093856 {
38103857 name: "access",
38113858 description:
3812 "What outside agents tried: the redacted log of non-browser requests to public paths, newest first, max 500. Forge admin.",
3859 "What outside agents tried: redacted non-browser requests to public paths, newest first, max 500. Forge admin.",
38133860 inputSchema: {
38143861 type: "object",
38153862 properties: {
@@ -3888,7 +3935,7 @@ const TOOLS: readonly Tool[] = [
38883935 {
38893936 name: "flow",
38903937 description:
3891 "The forge's pipeline (forge admin): per stage counts, `oldestWaiting`, `capacity`, the bottleneck, merge `queue`, `reviewing` per reviewer.",
3938 "The pipeline (forge admin): stage counts, `oldestWaiting`, `capacity`, bottleneck, merge `queue`, `reviewing`.",
38923939 inputSchema: { type: "object", properties: {} },
38933940 writes: false,
38943941 run(ctx, user) {
test/mcp-approve-here.test.ts added +245
@@ -0,0 +1,245 @@
1 /**
2 * The `approve_here` tool over MCP: the route's action, rules and refusals —
3 * a writer approves an origin fork's pull at its head, a reader, an agent and
4 * a stranger are refused, a later push waits, and bad input stops at the edge.
5 */
6 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { openPull } from "../src/actions/pulls.ts";
11 import { addToCrew, createAgent } from "../src/actions/crew.ts";
12 import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
13 import { createApp, type App } from "../src/app.ts";
14 import { pullMayRun } from "../src/core/pull_trust.ts";
15 import { getPull } from "../src/core/pulls.ts";
16 import type { Repo } from "../src/core/repos.ts";
17 import { createToken } from "../src/core/tokens.ts";
18 import { createUser, type User } from "../src/core/users.ts";
19 import { serve, type Servers } from "../src/http/server.ts";
20 import { promote } from "./helpers/members.ts";
21
22 describe("the approve_here tool over MCP", () => {
23 let dataDir: string;
24 let app: App;
25 let servers: Servers;
26 let alice: User;
27 let carol: User;
28 let dave: User;
29 let lib: Repo;
30 let tokens: Record<string, string>;
31 let nextId = 1;
32
33 const call = async (token: string, name: string, args: unknown) => {
34 const res = await fetch(`${servers.url}/mcp`, {
35 method: "POST",
36 headers: {
37 "content-type": "application/json",
38 accept: "application/json, text/event-stream",
39 authorization: `Bearer ${token}`,
40 },
41 body: JSON.stringify({
42 jsonrpc: "2.0",
43 id: nextId++,
44 method: "tools/call",
45 params: { name, arguments: args },
46 }),
47 });
48 if (res.status === 401) return { error: "unauthorized" };
49 const body = (await res.json()) as any;
50 if (body.error) return { error: body.error.message as string };
51 const text: string = body.result.content[0].text;
52 return body.result.isError === true
53 ? { error: text }
54 : { value: JSON.parse(text) };
55 };
56 const tool = (token: string, args: unknown) =>
57 call(token, "approve_here", args);
58
59 let carolFork: Repo | undefined;
60 let n = 0;
61 async function originPull() {
62 const branch = `b${++n}`;
63 if (!carolFork) {
64 const forked = await forkRepo(app, carol, lib, "fork");
65 if (!forked.ok) throw new Error(String(forked.error));
66 carolFork = forked.value;
67 }
68 const committed = await commitToBranch(app, carol, carolFork, {
69 branch,
70 message: "From the origin's fork",
71 files: [{ path: `${branch}.md`, content: "hi\n" }],
72 });
73 if (!committed.ok) throw new Error(JSON.stringify(committed.error));
74 const opened = await openPull(app, carol, lib, {
75 title: "Theirs",
76 baseBranch: "main",
77 headBranch: branch,
78 headRepo: carolFork,
79 });
80 if (!opened.ok) throw new Error(String(opened.error));
81 app.db.run("UPDATE pull SET origin_head_repo = ?1 WHERE issue_id = ?2", [
82 "octo/lib",
83 opened.value.id,
84 ]);
85 return {
86 pull: getPull(app.db, lib.id, opened.value.number)!,
87 head: committed.value.commitOid,
88 };
89 }
90
91 beforeAll(async () => {
92 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-approve-here-"));
93 app = createApp({ dataDir, port: 0 });
94 servers = await serve(app);
95 const mk = async (username: string, first = false) => {
96 const made = await createUser(app.db, {
97 origin: "seed",
98 trusted: true,
99 username,
100 email: `${username}@forge.local`,
101 password: "a-good-passphrase",
102 adminIfFirst: first,
103 });
104 if (!made.ok) throw new Error(made.error);
105 return made.value;
106 };
107 alice = await mk("alice", true);
108 carol = await mk("carol");
109 dave = await mk("dave");
110 promote(app.db, alice, carol, dave);
111 const made = await createRepo(app, alice, {
112 name: "lib",
113 visibility: "public",
114 });
115 if (!made.ok) throw new Error(String(made.error));
116 lib = made.value;
117 await commitToBranch(app, alice, lib, {
118 message: "seed",
119 files: [{ path: "README.md", content: "# lib\n" }],
120 });
121 const bot = await createAgent(app, alice, { username: "bot" });
122 if (!bot.ok) throw new Error(String(bot.error));
123 expect(addToCrew(app, alice, lib, "bot").ok).toBe(true);
124 const botUser = bot.value.user;
125 tokens = {
126 alice: createToken(app.db, alice.id, "rw", "rw").token,
127 dave: createToken(app.db, dave.id, "rw", "rw").token,
128 bot: createToken(app.db, botUser.id, "rw", "rw").token,
129 };
130 }, 30_000);
131
132 afterAll(async () => {
133 servers.stop();
134 app.close();
135 await rm(dataDir, { recursive: true, force: true });
136 });
137
138 test("it is listed with a schema", async () => {
139 const res = await fetch(`${servers.url}/mcp`, {
140 method: "POST",
141 headers: {
142 "content-type": "application/json",
143 accept: "application/json, text/event-stream",
144 authorization: `Bearer ${tokens["alice"]}`,
145 },
146 body: JSON.stringify({ jsonrpc: "2.0", id: 999, method: "tools/list" }),
147 });
148 const body = (await res.json()) as any;
149 const t = body.result.tools.find((x: any) => x.name === "approve_here");
150 expect(t.inputSchema.required).toEqual(["repo", "number"]);
151 });
152
153 test("a writer approves the head, and a later push needs approving again", async () => {
154 const { pull, head } = await originPull();
155 expect(pullMayRun(app.db, lib, pull, head)).toBe(false);
156 const done = await tool(tokens["alice"]!, {
157 repo: "alice/lib",
158 number: pull.number,
159 });
160 expect(done.value.commit).toBe(head);
161 expect(done.value.says).toContain(head.slice(0, 7));
162 expect(done.value.url).toBe(`/alice/lib/pulls/${pull.number}`);
163 expect(pullMayRun(app.db, lib, pull, head)).toBe(true);
164
165 const again = await commitToBranch(app, carol, carolFork!, {
166 branch: pull.headBranch,
167 message: "Again",
168 files: [{ path: "again.md", content: "again\n" }],
169 });
170 if (!again.ok) throw new Error(JSON.stringify(again.error));
171 expect(pullMayRun(app.db, lib, pull, again.value.commitOid)).toBe(false);
172 }, 30_000);
173
174 test("a reader, an agent and a stranger are refused as the route refuses", async () => {
175 const { pull, head } = await originPull();
176 const args = { repo: "alice/lib", number: pull.number };
177 for (const who of ["dave", "bot"]) {
178 const refused = await tool(tokens[who]!, args);
179 expect(refused.error).toContain("needs write access, and a person's");
outdated

toBeString() passes for any refusal, so it does not show that dave and bot are refused "as the route refuses them". Assert toContain("write access"), and add a closed-pull case for not_open.

180 }
181 const stranger = await tool("nope", args);
182 expect(stranger.error).toBe("unauthorized");
183 expect(pullMayRun(app.db, lib, pull, head)).toBe(false);
184 }, 30_000);
185
186 test("your own pull and a closed pull are refused in their own words", async () => {
outdated

The title says "your own pull", but no test here opens one, so the self_review → "You cannot approve your own pull request." branch is never run. Add the case: alice opens an origin-fork pull, so originHeadRepo is set and originAuthor is null. Assert toContain("your own").

187 const mine = await originPull();
188 app.db.run("UPDATE issue SET author_id = ?1 WHERE id = ?2", [
189 alice.id,
190 mine.pull.id,
191 ]);
192 const own = await tool(tokens["alice"]!, {
193 repo: "alice/lib",
194 number: mine.pull.number,
195 });
196 expect(own.error).toContain("cannot approve your own");
197 expect(pullMayRun(app.db, lib, mine.pull, mine.head)).toBe(false);
198
199 const closed = await originPull();
200 app.db.run("UPDATE issue SET state = 'closed' WHERE id = ?1", [
201 closed.pull.id,
202 ]);
203 const shut = await tool(tokens["alice"]!, {
204 repo: "alice/lib",
205 number: closed.pull.number,
206 });
207 expect(shut.error).toContain("is closed");
208 }, 30_000);
209
210 test("a plain pull and bad arguments are refused in a sentence", async () => {
211 const plain = await openPlain();
212 const needsNone = await tool(tokens["alice"]!, {
213 repo: "alice/lib",
214 number: plain,
215 });
216 expect(needsNone.error).toContain("needs no approval");
217 for (const args of [
218 {},
219 { repo: "alice/lib" },
220 { repo: "alice/lib", number: 0 },
221 { repo: "alice/lib", number: "1" },
222 { repo: "alice/lib", number: 9999 },
223 { repo: "nobody/nothing", number: 1 },
224 ]) {
225 const refused = await tool(tokens["alice"]!, args);
226 expect(refused.error).toBeString();
227 }
228 }, 30_000);
229
230 async function openPlain() {
231 const made = await commitToBranch(app, alice, lib, {
232 branch: "plain",
233 message: "plain",
234 files: [{ path: "plain.txt", content: "p\n" }],
235 });
236 if (!made.ok) throw new Error(JSON.stringify(made.error));
237 const opened = await openPull(app, alice, lib, {
238 title: "plain",
239 baseBranch: "main",
240 headBranch: "plain",
241 });
242 if (!opened.ok) throw new Error(String(opened.error));
243 return opened.value.number;
244 }
245 });
test/mcp.test.ts +1
@@ -246,6 +246,7 @@ describe("the forge over MCP", () => {
246246 "limb",
247247 "returns",
248248 "review",
249 "approve_here",
249250 "threads",
250251 "spend",
251252 "usage",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs