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

A pull a pass handed to a person shows in "needs you" with the reason and a Give back to the crew button #6606

Parked opened this
Closed without merging

scout/forge:scout/6347-a-pull-a-pass-handed-to-a-person-shows-i → main 1 commit fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
10 files changed +215 −16
docs/ASKS.md +6
@@ -29,6 +29,12 @@ In the terminal the same line sits above the dashboard, `C` (or the palette's
2929 Decider) opens the rows, and `1`, `2`, `3` switch pile. Both are for the
3030 repositories you own only: a reader sees nothing.
3131
32 **Give back to the crew** is on a pull a pass gave up on and assigned to you
33 (finishing, requested, sweep, picker): its row says the pass's reason in one
34 line, and one press assigns the pull to the builder that last worked on it.
35 `POST /api/v1/asks/give-back` (`{"item": "assigned:<id>"}`), or the MCP tool
36 `asks_decide` with `give_back: true`.
37
3238 **Let the decider** answers a hand-over card (an issue the crew parked) when
3339 you would rather not: the third tap on the card, `POST /api/v1/asks/decide`
3440 (`{"item": "parked:<id>"}`), the MCP tool `asks_decide`, or `D` on the On you
docs/MCP.md +1
@@ -42,6 +42,7 @@ for a tunnel and a forge that sleeps.
4242 | `apps` | the apps you can see: live or not, where served, how each runs itself, what is working | |
4343 | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes |
4444 | `asked` | `{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write | |
45 | `asks_decide` | `{ item, give_back? }`: let the decider answer a parked hand-over (`parked:<id>`); with `give_back`, give a hand-over back to the crew instead (`handover:<id>`, or `assigned:<id>` for a pull a pass gave up on and assigned to you, whose ask carries the pass's reason): it is assigned to the builder that last worked on it and a comment says so; the same as the card's **Give back to the crew** and `POST /api/v1/asks/give-back` | yes |
4546 | `assign` | `{ repo, number, kind, assignee }`: assign an issue or pull (`kind` is `issue` or `pull`) to a user, or clear it with `null`, as `PUT …/assignee` and with its refusals | yes |
4647 | `assigned` | `{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned` | |
4748 | `attach_look` | `{ app, pull, width, says, image, dryRun? }`: attach a look to an open pull: a PNG or JPEG (at most 5 MB, base64 in `image`), `width` phone or desktop, one line in `says`; planned first (`dryRun` is true unless `false`) | yes |
src/actions/give_back.ts +27 −5
@@ -14,13 +14,13 @@ import { getIssue, getIssueById, type Issue } from "../core/issues.ts";
1414 import { closesFromBody } from "../core/pulls.ts";
1515 import { canWrite, getRepoById, type Repo } from "../core/repos.ts";
1616 import { getUserById, type User } from "../core/users.ts";
17 import { handoverOf } from "../crew/guard.ts";
17 import { handoverOf, passReasonOf } from "../crew/guard.ts";
1818 import { transact } from "../kernel/db.ts";
1919 import { err, ok, type Result } from "../kernel/result.ts";
2020 import type { FleetError } from "./fleet.ts";
2121 import { NO_LONGER_ASKS, SIGN_IN_TO_ACT } from "./asks_words.ts";
2222
23 const ITEM = /^handover:[A-Za-z0-9_-]{1,64}$/;
23 const ITEM = /^(?:handover|assigned):[A-Za-z0-9_-]{1,64}$/;
2424
2525 const fail = (code: FleetError["code"], message: string) =>
2626 err<FleetError>({ code, message });
@@ -37,6 +37,23 @@ export function builderOf(db: Database, repo: Repo, pull: Issue): User | undefin
3737 : undefined;
3838 }
3939
40 /**
41 * Who a pass handed a pull over from: the crew member whose agent run on it
42 * is the latest and who is still on the crew, else whoever opened it.
43 */
44 export function lastBuilderOf(db: Database, repo: Repo, pull: Issue): User | undefined {
45 const rows = db
46 .query<{ actor_id: string }, [string]>(
47 "SELECT actor_id FROM run WHERE kind = 'agent' AND issue_id = ?1 AND actor_id IS NOT NULL ORDER BY created_at DESC, id DESC LIMIT 5",
48 )
49 .all(pull.id);
50 for (const { actor_id } of rows) {
51 const agent = getUserById(db, actor_id);
52 if (agent !== undefined && agent.kind === "agent" && isCrew(db, repo.id, agent.id)) return agent;
53 }
54 return builderOf(db, repo, pull);
55 }
56
4057 export interface GivenBack {
4158 readonly pull: number;
4259 readonly builder: string;
@@ -56,9 +73,14 @@ export function giveBack(
5673 // A reader, or someone who cannot see it, is told nothing exists.
5774 if (pull === undefined || repo === undefined || !canWrite(app.db, repo, actor))
5875 return fail("not_found", NO_LONGER_ASKS);
59 if (pull.kind !== "pull" || pull.state !== "open" || handoverOf(app.db, repo, pull.id) === undefined)
60 return fail("not_found", NO_LONGER_ASKS);
61 const builder = builderOf(app.db, repo, pull);
76 if (pull.kind !== "pull" || pull.state !== "open") return fail("not_found", NO_LONGER_ASKS);
77 // Three reviews without an approval, or a pass that gave up and assigned it to a person.
78 const byPass = item.startsWith("assigned:");
79 const stillAsks = byPass
80 ? pull.assigneeId === actor.id && !pull.assigneeIsAgent && passReasonOf(app.db, pull.id) !== undefined
81 : handoverOf(app.db, repo, pull.id) !== undefined;
82 if (!stillAsks) return fail("not_found", NO_LONGER_ASKS);
83 const builder = byPass ? lastBuilderOf(app.db, repo, pull) : builderOf(app.db, repo, pull);
6284 if (builder === undefined)
6385 return fail("bad_action", "no builder on the crew opened this pull, so there is no one to give it back to");
6486 // All or nothing: the pull, the issue a person holds and the comment that
src/crew/guard.ts +20
@@ -259,6 +259,26 @@ export const HANDOVER_ROUNDS = 3;
259259 /** What the hand-over card starts with: the thread's own record of it, and what `handover` ignores as a person's word. */
260260 export const HANDOVER_NOTE = "Handed to a person by the crew:";
261261
262 /**
263 * Why a pass handed this pull to a person, in one line: the newest hand-over
264 * note on it, without its prefix or the forge's "posted under your name"
265 * aside. Undefined when no pass has handed it over.
266 */
267 export function passReasonOf(db: Database, pullId: string): string | undefined {
268 const row = db
269 .query<{ body: string }, [string, string]>(
270 "SELECT body FROM comment WHERE issue_id = ?1 AND body LIKE ?2 ORDER BY created_at DESC, id DESC LIMIT 1",
271 )
272 .get(pullId, `${HANDOVER_NOTE}%`);
273 if (row === null) return undefined;
274 const words = row.body
275 .slice(HANDOVER_NOTE.length)
276 .split(" (The forge posts")[0]!
277 .replace(/\s+/g, " ")
278 .trim();
279 return words.length > 200 ? `${words.slice(0, 199)}…` : words;
280 }
281
262282 export interface Handover {
263283 /** The crew reviewer's verdicts that asked for changes, oldest first. */
264284 readonly reviews: readonly { id: string; author: string; body: string; at: string }[];
src/http/feed.ts +11
@@ -31,6 +31,7 @@ import {
3131 parseCursor,
3232 readFeed,
3333 } from "../feed/feed.ts";
34 import { giveBack } from "../actions/give_back.ts";
3435 import { decideAsk, undoDecideAsk } from "../actions/asks_decide.ts";
3536 import { actOnProposal, isProposalVerb } from "../actions/proposals.ts";
3637 import { asksAnswer } from "../web/studio/asks.ts";
@@ -192,6 +193,16 @@ export function feedRoutes(router: Router<Handler>): void {
192193 return json(done.value, 201);
193194 });
194195
196 // Give a hand-over back to the crew's builder (`actions/give_back.ts`).
197 router.add("POST", "/api/v1/asks/give-back", async (ctx) => {
198 const denied = requireScope(ctx, "rw");
199 if (denied) return denied;
200 const input = await body(ctx.request);
201 const done = giveBack(ctx.app, ctx.auth.user, input.item);
202 if (!done.ok) return bulkError(done.error);
203 return json(done.value, 201);
204 });
205
195206 router.add("POST", "/api/v1/asks/decide/:id/undo", async (ctx) => {
196207 const denied = requireScope(ctx, "rw");
197208 if (denied) return denied;
src/http/mcp/tools/asks_decide.ts +8 −2
@@ -1,17 +1,23 @@
11 import { decideAsk } from "../../../actions/asks_decide.ts";
2 import { giveBack } from "../../../actions/give_back.ts";
23 import { good, bad, type Tool } from "../shared.ts";
34
45 export const tool: Tool = {
56 name: "asks_decide",
7 doc: "`{ item, give_back? }`: let the decider answer a parked hand-over (`parked:<id>`); with `give_back`, give a hand-over back to the crew instead (`handover:<id>`, or `assigned:<id>` for a pull a pass gave up on and assigned to you, whose ask carries the pass's reason): it is assigned to the builder that last worked on it and a comment says so; the same as the card's **Give back to the crew** and `POST /api/v1/asks/give-back`",
68 description:
7 "Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside clears.",
9 "Answer a hand-over: the decider (`parked:<id>`), or `give_back` to its builder (`handover:`/`assigned:<id>`)",
810 inputSchema: {
911 type: "object",
10 properties: { item: { type: "string", maxLength: 80 } },
12 properties: { item: { type: "string", maxLength: 80 }, give_back: { type: "boolean" } },
1113 required: ["item"],
1214 },
1315 writes: true,
1416 async run(ctx, user, args) {
17 if (args["give_back"] === true) {
18 const back = giveBack(ctx.app, user, args["item"]);
19 return back.ok ? good(back.value) : bad(back.error.code, back.error.message);
20 }
1521 const done = await decideAsk(ctx.app, user, args["item"]);
1622 return done.ok ? good(done.value) : bad(done.error.code, done.error.message);
1723 },
src/web/studio/asks.ts +11 −5
@@ -8,6 +8,7 @@
88 */
99
1010 import type { Database } from "bun:sqlite";
11 import { lastBuilderOf } from "../../actions/give_back.ts";
1112 import { forgeVitals, needLine } from "../../actions/health.ts";
1213 import { reviewSet } from "./review_set.ts";
1314 import type { Degraded } from "../../kernel/vitals.ts";
@@ -55,7 +56,7 @@ import {
5556 } from "../../crew/autonomy.ts";
5657 import { breakerParked, WAITING_NOTES } from "../../crew/breaker.ts";
5758 import { CHECK_FAILED_LIMIT } from "../../crew/dispatch.ts";
58 import { handoversOf, type Handover } from "../../crew/guard.ts";
59 import { handoversOf, passReasonOf, type Handover } from "../../crew/guard.ts";
5960 import { conflictsOf, isStalePull, mergesAgainSince, staleGreen } from "../../crew/stale_asks.ts";
6061 import { reviewWaitsFor, type ReviewWait } from "../../crew/review.ts";
6162 import type { Ctx } from "../../http/context.ts";
@@ -130,7 +131,7 @@ export interface Decision {
130131 readonly waiting: WaitingFor;
131132 readonly why?: string | undefined;
132133 readonly recommendation?: Recommendation | undefined;
133 /** For "handover": the builder the pull can be given back to, if any. */
134 /** For "handover" and a pass-assigned "assigned": the builder the pull can be given back to, if any. */
134135 readonly giveBack?: string | undefined;
135136 }
136137
@@ -280,9 +281,9 @@ interface AskCandidate {
280281 readonly decline?: { readonly runId: string; readonly words: string };
281282 /** For "handover": the reviews that asked for changes. */
282283 readonly handover?: Handover;
283 /** For "handover": the crew member that opened the pull, when it can be given back. */
284 /** For "handover" and a pass-assigned "assigned": the crew member that opened or last worked on the pull, when it can be given back. */
284285 readonly builder?: string;
285 /** For "handover" and "waiting": one sentence on why a person must decide. */
286 /** For "handover", "waiting" and a pass-assigned "assigned": one sentence on why a person must decide. */
286287 readonly why?: string;
287288 /** For "handover" and "waiting": what the crew advised, when it wrote one. */
288289 readonly recommendation?: Recommendation;
@@ -597,6 +598,9 @@ function askCandidatesFor(
597598 if (!mayView(db, repo, issue, user)) continue;
598599 const pull = joinedMine.get(issue.id);
599600 if (issue.kind === "pull" && pull === undefined) continue;
601 // A pull a pass gave up on and assigned to this person says why, and can go back.
602 const reason = pull === undefined || issue.assigneeIsAgent ? undefined : passReasonOf(db, issue.id);
603 const back = reason === undefined ? undefined : lastBuilderOf(db, repo, issue)?.username;
600604 out.push({
601605 kind: "assigned",
602606 id: `assigned:${issue.id}`,
@@ -605,6 +609,8 @@ function askCandidatesFor(
605609 ...(pull === undefined ? { issue } : { pull }),
606610 who: issue.authorName,
607611 authorIsAgent: issue.authorIsAgent,
612 ...(reason === undefined ? {} : { why: reason }),
613 ...(back === undefined ? {} : { builder: back }),
608614 });
609615 }
610616 return out;
@@ -948,7 +954,7 @@ export function recordAskLedger(db: Database, now = new Date()): void {
948954 function lineOf(c: AskCandidate): string {
949955 if (c.kind === "paused") return "is paused at its ceiling";
950956 if (c.kind === "assigned")
951 return `"${c.pull?.title ?? c.issue?.title ?? ""}" is assigned to you`;
957 return `"${c.pull?.title ?? c.issue?.title ?? ""}" is assigned to you${c.why === undefined ? "" : `: ${c.why}`}`;
952958 if (c.kind === "parked")
953959 return `the crew parked #${c.issue!.number} after three failed runs`;
954960 if (c.kind === "proposal")
src/web/studio/decisions.ts +9 −3
@@ -69,8 +69,10 @@ export function decisionsFor(
6969 repo: c.repo,
7070 ...(c.pull === undefined ? { issue: c.issue } : { pull: c.pull }),
7171 who: c.who,
72 says: `"${thing.title}" is assigned to you.`,
73 short: `assigned to you · updated ${thing.updatedAt.slice(0, 10)}`,
72 says: c.why === undefined ? `"${thing.title}" is assigned to you.` : `"${thing.title}" was handed to you by the crew: ${c.why}`,
73 short: c.why ?? `assigned to you · updated ${thing.updatedAt.slice(0, 10)}`,
74 ...(c.why === undefined ? {} : { why: c.why }),
75 ...(c.builder === undefined ? {} : { giveBack: c.builder }),
7476 };
7577 }
7678 if (c.kind === "proposal" && c.proposal)
@@ -216,6 +218,10 @@ export function decisionForm(d: Decision, back?: string): Html | null {
216218 if (pull === undefined) return null;
217219 const base = repoBase(d.repo);
218220 const where = back === undefined ? null : html`<input type="hidden" name="back" value="${back}" />`;
221 if (d.kind === "assigned" && d.giveBack !== undefined)
222 return html`<form id="${askFormId(d)}-back" method="post" hidden action="/asks/give-back">
223 <input type="hidden" name="ask" value="${d.id}" />${where}
224 </form>`;
219225 if (d.kind === "handover" && d.giveBack !== undefined)
220226 return html`<form ${own} action="${base}/pulls/${pull.number}/state">
221227 <input type="hidden" name="state" value="closed" />${where}
@@ -301,7 +307,7 @@ export function decisionButtons(ctx: Ctx, d: Decision): { primary: Html; others:
301307 size: "sm",
302308 variant: "primary",
303309 }),
304 others: [],
310 others: d.giveBack === undefined ? [] : [btn("Give back to the crew", { size: "sm", form: `${askFormId(d)}-back` })],
305311 };
306312 if (d.kind === "proposal" && d.proposal)
307313 return {
test/mcp-docs.test.ts −1
@@ -20,7 +20,6 @@ const undocumented = new Set<string>([
2020 "here",
2121 "asks",
2222 "asks_act",
23 "asks_decide",
2423 "asks_proposal",
2524 "asks_undecide",
2625 "issue_teams",
test/pass-handover-ask.test.ts added +122
@@ -0,0 +1,122 @@
1 /**
2 * A pull a pass handed to a person (the finishing pass's hand-over note) is
3 * in that person's asks with the pass's reason, and "Give back to the crew"
4 * re-assigns the builder that last worked on it.
5 */
6
7 import { afterAll, beforeAll, describe, 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 { giveBack } from "../src/actions/give_back.ts";
13 import { addCrew, createAgentRow } from "../src/core/agents.ts";
14 import { addComment } from "../src/actions/issues.ts";
15 import { getIssueById } from "../src/core/issues.ts";
16 import { createRepo, type Repo } from "../src/core/repos.ts";
17 import { createUser, type User } from "../src/core/users.ts";
18 import { HANDOVER_NOTE } from "../src/crew/guard.ts";
19 import { id } from "../src/kernel/id.ts";
20 import { askLinesFor } from "../src/web/studio/asks.ts";
21 import { decisionsFor } from "../src/web/studio/decisions.ts";
22 import type { Ctx } from "../src/http/context.ts";
23 import { promote } from "./helpers/members.ts";
24 import { quietLogs } from "./helpers/globals.ts";
25
26 quietLogs();
27
28 const ZERO = "0".repeat(40);
29
30 describe("a pull a pass handed to a person", () => {
31 let dir = "";
32 let app: App;
33 let owner: User;
34 let other: User;
35 let first: User;
36 let last: User;
37 let repo: Repo;
38 let n = 0;
39
40 const person = async (username: string) => {
41 const made = await createUser(app.db, { username, email: `${username}@forge.test`, password: "a-good-passphrase", origin: "seed", trusted: true });
42 if (!made.ok) throw new Error(made.error);
43 return made.value;
44 };
45 const agent = async (username: string) => {
46 const made = await createUser(app.db, { username, email: `${username}@forge.test`, agent: true, origin: "agent" });
47 if (!made.ok) throw new Error(made.error);
48 createAgentRow(app.db, { userId: made.value.id, brief: "b" });
49 addCrew(app.db, repo.id, made.value.id, owner.id);
50 return made.value;
51 };
52
53 /** An open pull `first` opened, with agent runs by both builders, assigned to `to`. */
54 const handed = (to: User | undefined): string => {
55 const pullId = id();
56 const number = ++n;
57 app.db.query(`INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state, assignee_id) VALUES (?1, ?2, ?3, 'pull', ?4, '', ?5, 'open', ?6)`)
58 .run(pullId, repo.id, number, `Pull ${number}`, first.id, to?.id ?? null);
59 app.db.query(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, head_repo_id) VALUES (?1, 'main', ?2, ?3, ?3, ?4)`)
60 .run(pullId, `b/${number}`, ZERO, repo.id);
61 for (const [who, at] of [[first, "2026-10-01T00:00:00.000Z"], [last, "2026-10-02T00:00:00.000Z"]] as const)
62 app.db.query(`INSERT INTO run (id, repo_id, kind, issue_id, env, commit_oid, branch, actor_id, reason, state, created_at) VALUES (?1, ?2, 'agent', ?3, 'preview', ?4, 'b', ?5, 'feedback', 'ok', ?6)`)
63 .run(id(), repo.id, pullId, ZERO, who.id, at);
64 return pullId;
65 };
66 const note = (pullId: string) =>
67 addComment(app, owner, repo, getIssueById(app.db, pullId)!, `${HANDOVER_NOTE} this pull is approved, but 2 runs to bring it up to date ended without a push. Conflicting files: a.ts. (The forge posts this under your name; you did not write it.)`);
68
69 beforeAll(async () => {
70 dir = await mkdtemp(join(tmpdir(), "forge-pass-ask-"));
71 app = createApp({ dataDir: dir, port: 0 });
72 owner = await person("alice");
73 promote(app.db, owner);
74 other = await person("bob");
75 const made = await createRepo(app.db, app.reposRoot, { ownerId: owner.id, name: "p", visibility: "public", description: "p" });
76 if (!made.ok) throw new Error(made.error);
77 repo = made.value;
78 first = await agent("first");
79 last = await agent("last");
80 }, 30_000);
81
82 afterAll(async () => {
83 app.close();
84 await rm(dir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
85 });
86
87 const asks = (u: User) => decisionsFor({ app, auth: { user: u } } as unknown as Ctx, [repo], { evenDismissed: true });
88
89 test("it is listed with the pass's reason, and a plain assignment has none", () => {
90 const pass = handed(owner);
91 note(pass);
92 const plain = handed(owner);
93 const mine = asks(owner);
94 const row = mine.find((d) => d.id === `assigned:${pass}`)!;
95 expect(row.why).toContain("2 runs to bring it up to date ended without a push");
96 expect(row.why).not.toContain("The forge posts");
97 expect(row.giveBack).toBe("last");
98 const bare = mine.find((d) => d.id === `assigned:${plain}`)!;
99 expect(bare.why).toBeUndefined();
100 expect(bare.giveBack).toBeUndefined();
101 expect(askLinesFor(app.db, owner).some((r) => r.items.includes(`assigned:${pass}`))).toBe(true);
102 });
103
104 test("giving it back assigns the builder that last worked on it and the ask leaves", () => {
105 const pass = handed(owner);
106 note(pass);
107 const done = giveBack(app, owner, `assigned:${pass}`);
108 expect(done.ok ? "" : done.error.message).toBe("");
109 expect(getIssueById(app.db, pass)!.assigneeId).toBe(last.id);
110 expect(asks(owner).some((d) => d.id === `assigned:${pass}`)).toBe(false);
111 });
112
113 test("a plain assignment, someone else's, or a pull no longer theirs is refused", () => {
114 const plain = handed(owner);
115 expect(giveBack(app, owner, `assigned:${plain}`).ok).toBe(false);
116 const pass = handed(owner);
117 note(pass);
118 expect(giveBack(app, other, `assigned:${pass}`).ok).toBe(false);
119 expect(getIssueById(app.db, pass)!.assigneeId).toBe(owner.id);
120 expect(giveBack(app, undefined, `assigned:${pass}`).ok).toBe(false);
121 });
122 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs