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

An issue's page and the issue MCP answer show what its runs cost, summed from the cost ledger #14075

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/forge:mason/14056-an-issue-s-page-and-the-issue-mcp-answer → main 5 commits fork 2 threads · 2 unresolved

  • Merged. mason/14056-an-issue-s-page-and-the-issue-mcp-answer was merged into main as 0902222.

Review

Sign in to review this change.
6 files changed +125 −40
docs/features/issue-cost.md +13 −8
@@ -5,13 +5,15 @@ its own agent runs spent plus the dollars spent on every pull whose
55 description closes it. It is for people who write to the repository and want
66 to know what a piece of work cost before they look at the whole ledger.
77
8 - **Web** (`/<owner>/<repo>/issues/<n>`): under the Runs card, a list of rows.
9 `Cost` is the total. When a closing pull spent anything, `This issue`
10 shows the issue's own runs and one `Pull` row per pull follows, with the
11 pull number linking to the pull. With no runs of its own but a closing pull
12 that spent something, the Runs card is left out and the cost rows stay.
13 - **Terminal** (open the issue): one line under the Crew card, for example
14 `Cost $0.75: this issue $0.50, #12 $0.25`.
8 - **Web** (`/<owner>/<repo>/issues/<n>`): under the Runs card, one line,
9 `Spent $0.75 over 3 runs`, the single statement of the total. When a
10 closing pull spent anything, rows follow: `This issue` for the issue's own
11 runs and one `Pull` row per pull, the pull number linking to the pull. With
12 no runs of its own but a closing pull that spent something, the Runs card
13 is left out and the line stays.
14 - **Terminal** (open the issue): the same sentence under the Crew card, with
15 the breakdown after it, for example
16 `Spent $0.75 over 3 runs: this issue $0.50, #12 $0.25`.
1517
1618 ## Rules
1719
@@ -22,6 +24,9 @@ to know what a piece of work cost before they look at the whole ledger.
2224 - A pull that closes two issues counts in both, so the issues' totals can add
2325 up to more than the repository spent. The repository's total is the usage
2426 ledger's.
27 - The run count is made by the query that sums the dollars (runs on the
28 issue and on each closing pull whose cost is above zero), so N always
29 belongs to the $X; a pull the viewer may not see counts in neither.
2530 - Nothing is shown when nothing was spent.
2631 - The same gate applies on both doors (`issueCostFor`,
2732 `src/core/issue_cost.ts`): the viewer must read the repository's runs, see
@@ -32,6 +37,6 @@ to know what a piece of work cost before they look at the whole ledger.
3237 ## API and MCP
3338
3439 `GET /api/v1/repos/:owner/:name/issues/:n` and the MCP `issue` tool carry
35 `cost: {usd, own, pulls: [{number, usd}]}`, the number the page prints, from
40 `cost: {usd, own, runs, pulls: [{number, usd}]}`, the number the page prints, from
3641 `issueCostFor`. The field is absent when nothing was spent, for a guest, and
3742 for a viewer who may not read the runs or see the owner's facts.
src/core/issue_cost.ts +41 −13
@@ -26,24 +26,32 @@ export interface PullCost {
2626 readonly id: string;
2727 readonly number: number;
2828 readonly usd: number;
29 /** Runs behind `usd`: those that spent money, counted by the query that sums. */
30 readonly runs: number;
2931 }
3032
3133 export interface IssueCost {
3234 /** Runs whose `issue_id` is the issue itself. */
3335 readonly ownUsd: number;
36 /** Runs on the issue that spent money. */
37 readonly ownRuns: number;
3438 /** Closing pulls (any state), oldest first, each with its own runs' cost. */
3539 readonly pulls: readonly PullCost[];
3640 /** `ownUsd` plus every pull. */
3741 readonly totalUsd: number;
42 /** `ownRuns` plus every pull's: the N of "Spent $X over N runs". */
43 readonly runs: number;
3844 }
3945
4046 const round4 = (n: number): number => Math.round(n * 1e4) / 1e4;
4147
4248 export function issueCost(db: Database, repoId: string, issueId: string, number: number): IssueCost {
43 const sum = db.query<{ usd: number }, [string]>(
44 "SELECT COALESCE(SUM(cost_usd), 0) AS usd FROM run WHERE issue_id = ?1",
49 // One query sums the dollars and counts the runs, so the two cannot disagree.
50 const sum = db.query<{ usd: number; n: number }, [string]>(
51 "SELECT COALESCE(SUM(cost_usd), 0) AS usd, COALESCE(SUM(cost_usd > 0), 0) AS n FROM run WHERE issue_id = ?1",
4552 );
46 const ownUsd = round4(sum.get(issueId)?.usd ?? 0);
53 const own = sum.get(issueId);
54 const ownUsd = round4(own?.usd ?? 0);
4755 // The LIKE only narrows; `closesFromBody` decides.
4856 const candidates = db
4957 .query<{ id: string; number: number; body: string }, [string, string, string]>(
@@ -56,9 +64,17 @@ export function issueCost(db: Database, repoId: string, issueId: string, number:
5664 const pulls: PullCost[] = [];
5765 for (const c of candidates) {
5866 if (!closesFromBody(c.body).includes(number)) continue;
59 pulls.push({ id: c.id, number: c.number, usd: round4(sum.get(c.id)?.usd ?? 0) });
67 const got = sum.get(c.id);
68 pulls.push({ id: c.id, number: c.number, usd: round4(got?.usd ?? 0), runs: got?.n ?? 0 });
6069 }
61 return { ownUsd, pulls, totalUsd: round4(ownUsd + pulls.reduce((s, p) => s + p.usd, 0)) };
70 const ownRuns = own?.n ?? 0;
71 return {
72 ownUsd,
73 ownRuns,
74 pulls,
75 totalUsd: round4(ownUsd + pulls.reduce((s, p) => s + p.usd, 0)),
76 runs: ownRuns + pulls.reduce((s, p) => s + p.runs, 0),
77 };
6278 }
6379
6480 /**
@@ -78,17 +94,26 @@ export function issueCostFor(
7894 const all = issueCost(db, repo.id, issue.id, issue.number);
7995 const pulls = all.pulls.filter((p) => mayViewId(db, repo, p.id, viewer));
8096 const totalUsd = round4(all.ownUsd + pulls.reduce((s, p) => s + p.usd, 0));
81 return totalUsd === 0 ? null : { ownUsd: all.ownUsd, pulls, totalUsd };
97 const runs = all.ownRuns + pulls.reduce((s, p) => s + p.runs, 0);
98 return totalUsd === 0 ? null : { ownUsd: all.ownUsd, ownRuns: all.ownRuns, pulls, totalUsd, runs };
8299 }
83100
84101 const usd2 = (n: number): string => `$${n.toFixed(2)}`;
85102
86 /** The cost in one plain line, for the terminal: "Cost $0.75: this issue $0.50, #12 $0.25". */
103 /** The one statement of the total, on every door: "Spent $0.75 over 3 runs". */
104 export function spentLine(cost: Pick<IssueCost, "totalUsd" | "runs">): string {
105 return `Spent ${usd2(cost.totalUsd)} over ${cost.runs} ${cost.runs === 1 ? "run" : "runs"}`;
106 }
107
108 /**
109 * The cost in one plain line, for the terminal: "Spent $0.75 over 3 runs: this issue $0.50, #12
110 * $0.25".
111 */
87112 export function costLine(cost: IssueCost): string {
88113 const spent = cost.pulls.filter((p) => p.usd > 0);
89 if (spent.length === 0) return `Cost ${usd2(cost.totalUsd)}`;
114 if (spent.length === 0) return spentLine(cost);
90115 const parts = [`this issue ${usd2(cost.ownUsd)}`, ...spent.map((p) => `#${p.number} ${usd2(p.usd)}`)];
91 return `Cost ${usd2(cost.totalUsd)}: ${parts.join(", ")}`;
116 return `${spentLine(cost)}: ${parts.join(", ")}`;
92117 }
93118
94119 /** One row of the cost: a label, the dollars, and the pull it is when it is one. */
@@ -99,13 +124,13 @@ export interface CostRow {
99124 }
100125
101126 /**
102 * The cost as rows both doors show: the total, then, when a pull spent
103 * anything, this issue's own runs and each pull that did.
127 * The breakdown under `spentLine`, which states the total: when a pull spent
128 * anything, this issue's own runs and each pull that did; otherwise nothing.
104129 */
105130 export function costRows(cost: IssueCost): CostRow[] {
106 const rows: CostRow[] = [{ label: "Cost", usd: cost.totalUsd }];
107131 const spent = cost.pulls.filter((p) => p.usd > 0);
108 if (spent.length === 0) return rows;
132 if (spent.length === 0) return [];
133 const rows: CostRow[] = [];
109134 rows.push({ label: "This issue", usd: cost.ownUsd });
110135 for (const p of spent) rows.push({ label: "Pull", usd: p.usd, pull: p.number });
111136 return rows;
@@ -119,6 +144,8 @@ export function costRows(cost: IssueCost): CostRow[] {
119144 export interface CostField {
120145 readonly usd: number;
121146 readonly own: number;
147 /** Runs that spent money, behind the line "Spent $X over N runs". */
148 readonly runs: number;
122149 readonly pulls: readonly { readonly number: number; readonly usd: number }[];
123150 }
124151
@@ -127,6 +154,7 @@ export function costField(cost: IssueCost | null): CostField | undefined {
127154 return {
128155 usd: cost.totalUsd,
129156 own: cost.ownUsd,
157 runs: cost.runs,
130158 pulls: cost.pulls.filter((p) => p.usd > 0).map((p) => ({ number: p.number, usd: p.usd })),
131159 };
132160 }
src/http/mcp/tools/issue.ts +1 −1
@@ -12,7 +12,7 @@ import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"
1212
1313 export const tool: Tool = {
1414 name: "issue",
15 doc: "`{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, the newest 50 comments (author, authorIsAgent, body, at), `commentsTotal` and `commentsNext` (older ones: `GET …/comments?cursor=`), `standing` (`{line, ready, before, after, more}`: the sentence saying whether it can start and what holds it now, the chain of what it waits for and what waits for it, each node `{number, title, badge, word, next, quiet, holding}`), blockedBy/blocks and `cost` (`{usd, own, pulls}`, absent when nothing was spent or it is not yours to see), as `GET …/issues/:number`; a sealed one you cannot see is not found; draws the `ui://forge/issue` card: title, state, assignee, labels and what it waits for, never the body or comments",
15 doc: "`{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, the newest 50 comments (author, authorIsAgent, body, at), `commentsTotal` and `commentsNext` (older ones: `GET …/comments?cursor=`), `standing` (`{line, ready, before, after, more}`: the sentence saying whether it can start and what holds it now, the chain of what it waits for and what waits for it, each node `{number, title, badge, word, next, quiet, holding}`), blockedBy/blocks and `cost` (`{usd, own, runs, pulls}`, absent when nothing was spent or it is not yours to see), as `GET …/issues/:number`; a sealed one you cannot see is not found; draws the `ui://forge/issue` card: title, state, assignee, labels and what it waits for, never the body or comments",
1616 description:
1717 "One issue with comments, `blockedBy`, `blocks`; non-writers' text is `untrusted`.",
1818 inputSchema: {
src/web/studio/tell.ts +10 −6
@@ -9,7 +9,7 @@ import type { Database } from "bun:sqlite";
99 * one closed Details section.
1010 */
1111
12 import { costRows, issueCostFor, type IssueCost } from "../../core/issue_cost.ts";
12 import { costRows, issueCostFor, spentLine, type IssueCost } from "../../core/issue_cost.ts";
1313 import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
1414 import { cardPath } from "../og/path.ts";
1515 import { mayEditIssue } from "../../actions/issues.ts";
@@ -375,11 +375,15 @@ async function tellRuns(
375375 */
376376 function costBlock(cost: IssueCost | null, base: string): Html | null {
377377 if (cost === null) return null;
378 return html`<dl class="status-rows" data-issue-cost>${costRows(cost).map(
379 (r) => html`<div class="status-row"><dt>${r.label}</dt><dd class="num">${
380 r.pull === undefined ? null : html`<a href="${base}/pulls/${r.pull}">#${r.pull}</a> `
381 }${costText(r.usd)}</dd></div>`,
382 )}</dl>`;
378 const rows = costRows(cost);
outdated

Principle 1: this line repeats the total the dl rows below it show. Make one the single statement. The line is also over-long: wrap it. This is a second DB query per render; compute runs once with the cost.

379 return html`<p class="muted" data-issue-spent>${spentLine(cost)}</p>${when(
380 rows.length > 0,
381 () => html`<dl class="status-rows" data-issue-cost>${rows.map(
382 (r) => html`<div class="status-row"><dt>${r.label}</dt><dd class="num">${
383 r.pull === undefined ? null : html`<a href="${base}/pulls/${r.pull}">#${r.pull}</a> `
384 }${costText(r.usd)}</dd></div>`,
385 )}</dl>`,
386 )}`;
383387 }
384388
385389 /** The pull that closes this tell, with its check and a way into its
test/issue-cost.test.ts +58 −10
@@ -12,7 +12,7 @@ import { join } from "node:path";
1212 import { openIssue } from "../src/actions/issues.ts";
1313 import { createRepo } from "../src/actions/repos.ts";
1414 import { createApp, type App } from "../src/app.ts";
15 import { costLine, costRows, issueCost, issueCostFor } from "../src/core/issue_cost.ts";
15 import { costLine, costRows, issueCost, issueCostFor, spentLine } from "../src/core/issue_cost.ts";
1616 import type { Repo } from "../src/core/repos.ts";
1717 import { createRun } from "../src/core/runs.ts";
1818 import { createToken } from "../src/core/tokens.ts";
@@ -84,12 +84,12 @@ describe("issue cost roll-up", () => {
8484 const cost = issueCost(app.db, repo.id, two.id, two.number);
8585 expect(cost.ownUsd).toBe(0.4);
8686 expect(cost.pulls).toEqual([
87 { id: p1.id, number: p1.number, usd: 1.25 },
88 { id: p2.id, number: p2.number, usd: 0.35 },
87 { id: p1.id, number: p1.number, usd: 1.25, runs: 1 },
88 { id: p2.id, number: p2.number, usd: 0.35, runs: 1 },
8989 ]);
9090 expect(cost.totalUsd).toBe(2);
9191 // One's own is its runs only: no pull closes it ("#1" is not "#191").
92 expect(issueCost(app.db, repo.id, one.id, one.number)).toEqual({ ownUsd: 0.4, pulls: [], totalUsd: 0.4 });
92 expect(issueCost(app.db, repo.id, one.id, one.number)).toEqual({ ownUsd: 0.4, ownRuns: 2, pulls: [], totalUsd: 0.4, runs: 2 });
9393 });
9494
9595 const signin = async (username: string, password: string) => {
@@ -117,11 +117,11 @@ describe("issue cost roll-up", () => {
117117 m[2]!.replace(/<a href="([^"]+)">(#\d+)<\/a>/g, "[$2 $1]").trim(),
118118 ]);
119119 expect(rows).toEqual([
120 ["Cost", "$0.75"],
121120 ["This issue", "$0.50"],
122121 ["Pull", `[#${p.number} /alice/shop/pulls/${p.number}] $0.25`],
123122 ]);
124123 expect(text).not.toContain("this tell");
124 expect(text).toContain("Spent $0.75 over 2 runs");
125125 });
126126
127127 test("with no runs of its own but a closing pull, the Runs card goes and the cost stays", async () => {
@@ -150,7 +150,7 @@ describe("issue cost roll-up", () => {
150150 expect(issueCostFor(app.db, repo, t, undefined)).toBeNull();
151151 expect(issueCostFor(app.db, repo, t, b.value)).toBeNull();
152152 const mine = issueCostFor(app.db, repo, t, alice);
153 expect(mine && costLine(mine)).toBe("Cost $0.90");
153 expect(mine && costLine(mine)).toBe("Spent $0.90 over 1 run");
154154 });
155155
156156 test("the terminal's line is the plain sentence", () => {
@@ -160,8 +160,8 @@ describe("issue cost roll-up", () => {
160160 asPull(p.id);
161161 spend(p.id, 0.25);
162162 const c = issueCostFor(app.db, repo, t, alice)!;
163 expect(costLine(c)).toBe(`Cost $0.75: this issue $0.50, #${p.number} $0.25`);
164 expect(costRows(c).map((r) => r.label)).toEqual(["Cost", "This issue", "Pull"]);
163 expect(costLine(c)).toBe(`Spent $0.75 over 2 runs: this issue $0.50, #${p.number} $0.25`);
164 expect(costRows(c).map((r) => r.label)).toEqual(["This issue", "Pull"]);
165165 });
166166
167167 test("the page, the API and the MCP print one number; a guest and a reader get none", async () => {
@@ -206,9 +206,9 @@ describe("issue cost roll-up", () => {
206206 const text = String(body.result.content[0].text);
207207 return (text.startsWith("{") ? JSON.parse(text) : {}) as { cost?: { usd: number } };
208208 };
209 const expected = { usd: 0.75, own: 0.5, pulls: [{ number: p.number, usd: 0.25 }] };
209 const expected = { usd: 0.75, own: 0.5, runs: 2, pulls: [{ number: p.number, usd: 0.25 }] };
210210 const html = await page(t.number, await signin("alice", "a-good-passphrase"));
211 expect(costDl(html)).toContain("$0.75");
211 expect(html).toContain("Spent $0.75 over 2 runs");
212212 expect((await getApi(mine)).cost).toEqual(expected);
213213 expect((await viaMcp(mine)).cost).toEqual(expected);
214214 expect((await getApi()).cost).toBeUndefined();
@@ -216,3 +216,51 @@ describe("issue cost roll-up", () => {
216216 expect((await viaMcp(hers)).cost).toBeUndefined();
217217 });
218218 });
219
220 describe("the spent line", () => {
221 test("one sentence: dollars and runs, singular for one", () => {
222 expect(spentLine({ totalUsd: 0.5, runs: 1 })).toBe("Spent $0.50 over 1 run");
223 expect(spentLine({ totalUsd: 2, runs: 3 })).toBe("Spent $2.00 over 3 runs");
224 });
225 test("counted from the ledger: none, one, several", async () => {
226 const dir = await mkdtemp(join(tmpdir(), "forge-spent-"));
227 const a = createApp({ dataDir: dir, port: 0 });
228 try {
229 const u = await createUser(a.db, { origin: "seed", trusted: true, username: "al", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
230 if (!u.ok) throw new Error(u.error);
231 const made = await createRepo(a, u.value, { name: "shop" });
232 if (!made.ok) throw new Error(String(made.error));
233 const r = openIssue(a, u.value, made.value, { title: "T", body: "" });
234 if (!r.ok) throw new Error(String(r.error));
235 const issue = r.value;
236 const line = () => {
237 const c = issueCostFor(a.db, made.value, issue, u.value);
238 return c === null ? null : spentLine(c);
239 };
240 expect(line()).toBeNull();
241 const run = (usd: number) => {
242 const x = createRun(a.db, { repoId: made.value.id, kind: "agent", issueId: issue.id });
243 a.db.query("UPDATE run SET cost_usd = ?1 WHERE id = ?2").run(usd, x.id);
244 };
245 run(0.5);
246 expect(line()).toBe("Spent $0.50 over 1 run");
247 run(0.25);
248 run(0.25);
249 expect(line()).toBe("Spent $1.00 over 3 runs");
250 // A run that has not spent anything (still going) and a closing pull
251 // whose runs spent nothing add dollars to neither the sum nor the count.
252 run(0);
253 const fix = openIssue(a, u.value, made.value, { title: "Fix", body: `Closes #${issue.number}` });
254 if (!fix.ok) throw new Error(String(fix.error));
255 a.db.query("UPDATE issue SET kind = 'pull' WHERE id = ?1").run(fix.value.id);
256 a.db
257 .query(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid) VALUES (?1, 'main', 'x', '', '')`)
258 .run(fix.value.id);
259 const idle = createRun(a.db, { repoId: made.value.id, kind: "agent", issueId: fix.value.id });
260 expect(idle.id).toBeTruthy();
261 expect(line()).toBe("Spent $1.00 over 3 runs");
262 } finally {
263 await rm(dir, { recursive: true, force: true });
264 }
265 });
266 });
test/tui-issue-cost.test.ts +2 −2
@@ -119,14 +119,14 @@ describe("the terminal's issue screen and its cost", () => {
119119 spend(pull, 0.25, true);
120120 const t = await open(alice, issue.number);
121121 try {
122 expect(t.text()).toContain(`Cost $0.75: this issue $0.50, #${pull.number} $0.25`);
122 expect(t.text()).toContain(`Spent $0.75 over 2 runs: this issue $0.50, #${pull.number} $0.25`);
123123 } finally {
124124 t.stop();
125125 }
126126 const r = await open(bob, issue.number);
127127 try {
128128 expect(r.text()).toContain("Prune");
129 expect(r.text()).not.toContain("Cost $");
129 expect(r.text()).not.toContain("Spent $");
130130 } finally {
131131 r.stop();
132132 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs