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

Home's builders tile says why builders are idle: the ceiling, no ready issue, or no subscription with headroom #5819

Parked opened this
Closed without merging

scout/forge:scout/5799-home-s-builders-tile-says-why-builders-a → main 4 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
8 files changed +229 −12
src/crew/idle.ts added +49
@@ -0,0 +1,49 @@
1 /**
2 * Why the builders sit idle, asked of the scheduler's own checks. For each
3 * autonomous repository the questions are the ones `driveRepo` puts before it
4 * starts a run, in its order: spent today against the ceilings
5 * (`autonomyStatus`), the subscriptions' room (`repoPace`), the ready list
6 * after the holds (`heldBy`). Nothing here re-derives a rule.
7 */
8
9 import type { App } from "../app.ts";
10 import { listAutonomousRepos } from "../core/repos.ts";
11 import { listCrewRoles } from "../core/agents.ts";
12 import { readyNow, repoGraph } from "../core/dependencies.ts";
13 import { autonomyStatus, repoPace, slottedRuns } from "./autonomy.ts";
14 import { listActive } from "../core/runs.ts";
15 import { heldBy } from "./held.ts";
16
17 /** In the order the page names them: the first that holds wins. */
18 export const IDLE_REASONS = ["ceiling", "headroom", "nothing ready"] as const;
19 export type IdleReason = (typeof IDLE_REASONS)[number];
20
21 /**
22 * The first reason that holds across the repositories with a free slot, or
23 * null when some repository could start a run now (the next tick will) or no
24 * repository is in a state the three reasons name.
25 */
26 export function whyIdle(app: App, now: Date): IdleReason | null {
27 const active = listActive(app.db, "agent");
28 let best: number = IDLE_REASONS.length;
29 for (const repo of listAutonomousRepos(app.db)) {
30 const status = autonomyStatus(app, repo, now);
31 let at: number;
32 if (status.paused === "ceiling" || status.paused === "forge ceiling") at = 0;
33 else if (status.paused !== null) continue;
34 else {
35 const crew = listCrewRoles(app.db, repo.id);
36 const here = active.filter((r) => r.repoId === repo.id);
37 const paced = repoPace(app, repo, now);
38 if (slottedRuns(here, crew).length >= paced.slots && paced.slots > 0) continue;
39 if (paced.slots === 0) at = 1;
40 else {
41 const held = heldBy(app, repo, readyNow(repoGraph(app.db, repo.id, { sealed: true })), crew, here);
42 if (held.startable.length > 0) return null;
43 at = 2;
44 }
45 }
46 best = Math.min(best, at);
47 }
48 return IDLE_REASONS[best] ?? null;
49 }
src/flow/kpi_words.ts +30 −1
@@ -3,6 +3,7 @@
33 * must not depend on each other. Plain data in, plain strings out.
44 */
55
6 import type { IdleReason } from "../crew/idle.ts";
67 import type { Kpis } from "./kpis.ts";
78 import type { Reach } from "./reach.ts";
89
@@ -36,6 +37,34 @@ export function buildersValue(b: Kpis["builders"]): string {
3637 return b.slots === 0 ? "—" : `${b.running} of ${b.slots}`;
3738 }
3839
40 /** Why builders sit below their slots, in words; the first that holds (`crew/idle.ts`). */
41 export function idleWords(idle: IdleReason | null | undefined): string | null {
42 switch (idle) {
43 case "ceiling":
44 return "ceiling reached";
45 case "headroom":
46 return "no subscription with headroom";
47 case "nothing ready":
48 return "nothing ready";
49 default:
50 return null;
51 }
52 }
53
54 /** The page that fixes it: the ceiling is set on the crew page, the room is the subscriptions', the work is the map. */
55 export function idleLink(idle: IdleReason | null | undefined): string | null {
56 switch (idle) {
57 case "ceiling":
58 return "/settings/crew";
59 case "headroom":
60 return "/settings/subscriptions";
61 case "nothing ready":
62 return "/map";
63 default:
64 return null;
65 }
66 }
67
3968 /** Cents below ten dollars, so a small spend never reads `$0`; whole dollars above. */
4069 const whole = (n: number): string => (n < 10 ? `$${n.toFixed(2)}` : `$${Math.round(n)}`);
4170 const cents = (n: number): string => `$${n.toFixed(2)}`;
@@ -141,7 +170,7 @@ export function kpiLines(k: Kpis, live: { sha: string; since: string } | null, n
141170 `Shipped per hour ${(k.landed / k.landedHours.length).toFixed(1)} ${sparkText(k.landedHours)} ${k.landed} ${k.landed === 1 ? "change" : "changes"} in 24 h`,
142171 `Live version ${live === null ? "— nothing live yet" : `${live.sha.slice(0, 7)}, live ${live.since}`}`,
143172 `Median check time ${checkTime(k.medianCheckMs)}`,
144 `Builders running ${buildersValue(k.builders)}${k.builders.slots === 0 ? ", no slots set" : ""}`,
173 `Builders running ${buildersValue(k.builders)}${k.builders.slots === 0 ? ", no slots set" : ""}${idleWords(k.builders.idle) === null ? "" : `, ${idleWords(k.builders.idle)}`}`,
145174 `Crew spend today ${spendValue(k.spend)}${spendLineNote(k.spend)}`,
146175 `Last off-box backup ${backupAge(k.backupAt, now)}${backupOverdue(k.backupAt, now) ? ", overdue" : ""}`,
147176 `Visitors ${visitorsValue(k.reach)}, ${visitorsNote(k.reach)} ${trendText(k.reach.visitorDays)} 30 days`,
src/flow/kpis.ts +7 −3
@@ -14,7 +14,9 @@
1414 */
1515
1616 import type { Database } from "bun:sqlite";
17 import type { App } from "../app.ts";
1718 import { spentTodayEverywhere } from "../crew/autonomy.ts";
19 import { type IdleReason, whyIdle } from "../crew/idle.ts";
1820 import { ceilingHitAt, ceilingReached } from "./ceiling.ts";
1921 import { lastOffBox } from "../snapshot/off_box.ts";
2022 import { readReach, type Reach } from "./reach.ts";
@@ -32,7 +34,7 @@ export interface Kpis {
3234 /** Median check duration in milliseconds over checks that finished in 24 h; null for none. */
3335 readonly medianCheckMs: number | null;
3436 /** Crew builders running now, of the slots the autonomous repositories are set to. */
35 readonly builders: { readonly running: number; readonly slots: number };
37 readonly builders: { readonly running: number; readonly slots: number; readonly idle?: IdleReason | null };
3638 /** What the crew's runs cost since UTC midnight, and the forge's daily ceiling (null: none set). */
3739 readonly spend: { readonly todayUsd: number; readonly ceilingUsd: number | null; /** When the run that crossed the cap was created (ISO); null while under it. */ readonly hitAt?: string | null };
3840 /** When a snapshot was last known off the machine (a bucket destination or the mirror, `off_box.ts`); null when never. */
@@ -44,7 +46,7 @@ export interface Kpis {
4446 export function readKpis(
4547 db: Database,
4648 now: Date,
47 forge: { readonly ceilingUsd: number | null; readonly dataDir?: string } = { ceilingUsd: null },
49 forge: { readonly ceilingUsd: number | null; readonly dataDir?: string; readonly app?: App } = { ceilingUsd: null },
4850 ): Kpis {
4951 const end = now.getTime();
5052 const to = now.toISOString();
@@ -93,13 +95,15 @@ export function readKpis(
9395 )
9496 .get() ?? { running: 0, slots: 0 };
9597
98 const idle = forge.app !== undefined && builders.running < builders.slots ? whyIdle(forge.app, now) : null;
99
96100 const todayUsd = spentTodayEverywhere(db, now);
97101
98102 const backupAt = forge.dataDir === undefined ? null : lastOffBox(forge.dataDir);
99103
100104 return {
101105 backupAt,
102 builders,
106 builders: idle === null ? builders : { ...builders, idle },
103107 reach: readReach(db, now),
104108 spend: { todayUsd, ceilingUsd: forge.ceilingUsd, hitAt: ceilingReached(todayUsd, forge.ceilingUsd) ? ceilingHitAt(db, now, forge.ceilingUsd) : null },
105109 landedHours,
src/tui/screens/dashboard.ts +3 −1
@@ -96,6 +96,7 @@ import {
9696 plural,
9797 linkScreen,
9898 } from "./common.ts";
99 import type { App } from "../../app.ts";
99100 import { readVitals, vitalsLine } from "../../flow/vitals.ts";
100101 import { readKpis } from "../../flow/kpis.ts";
101102 import { kpiLines } from "../../flow/kpi_words.ts";
@@ -122,7 +123,8 @@ import { signInScreen } from "./signin.ts";
122123 const FIGURES_ROOM = 6;
123124
124125 /** The forge-wide daily ceiling, from config, for the spend figure; the data directory, for the backup's age. */
125 export const kpiForge = (app: { config: { crewCeilingUsd?: number; dataDir: string } }) => ({
126 export const kpiForge = (app: App) => ({
127 app,
126128 ceilingUsd: forgeCeiling(app.config),
127129 dataDir: app.config.dataDir,
128130 });
src/web/studio/home.ts +1 −1
@@ -285,7 +285,7 @@ export async function studioHome(
285285 const ask = firstSteps ?? everydayCard(ctx, user);
286286 const figures = user.isAdmin && steps === undefined;
287287 const ceilingUsd = forgeCeiling(ctx.app.config);
288 const kpiOpts = { dataDir: ctx.app.config.dataDir, ...(ceilingUsd === null ? {} : { ceilingUsd }) };
288 const kpiOpts = { app: ctx.app, dataDir: ctx.app.config.dataDir, ...(ceilingUsd === null ? {} : { ceilingUsd }) };
289289 const body = html`<h1 class="sr-only">Home</h1>
290290 ${ask} ${address} ${figures
291291 ? timePhase(ctx.request, "kpis", () => kpiRow(ctx.app.db, kpiOpts), () => kpiCache(ctx.app.db))
src/web/studio/home_cache.ts +2 −1
@@ -11,6 +11,7 @@ import type { Database } from "bun:sqlite";
1111 import type { Answer } from "../../boards/query.ts";
1212 import { writeStamp } from "../../core/write_clock.ts";
1313 import { readKpis, type Kpis } from "../../flow/kpis.ts";
14 import type { App } from "../../app.ts";
1415 import { readVitals, type Vitals } from "../../flow/vitals.ts";
1516 import { Stamped } from "../../kernel/stamped.ts";
1617
@@ -62,7 +63,7 @@ export function cachedWaiting(db: Database, viewerId: string, compute: () => Wai
6263 export function cachedKpis(
6364 db: Database,
6465 now: Date,
65 forge: { readonly ceilingUsd: number | null; readonly dataDir?: string },
66 forge: { readonly ceilingUsd: number | null; readonly dataDir?: string; readonly app?: App },
6667 ): Kpis {
6768 const stamp = writeStamp(db);
6869 if (stamp === undefined) return readKpis(db, now, forge);
src/web/studio/kpi_row.ts +6 −5
@@ -8,7 +8,8 @@
88 */
99
1010 import type { Database } from "bun:sqlite";
11 import { backupAge, backupFull, backupOverdue, buildersValue, checkTime, reactNote, speedWords, spendCeilingWords, spendFull, spendValue, usersValue, visitorsNote, visitorsValue, waitingWords } from "../../flow/kpi_words.ts";
11 import type { App } from "../../app.ts";
12 import { backupAge, backupFull, backupOverdue, buildersValue, checkTime, idleLink, idleWords, reactNote, speedWords, spendCeilingWords, spendFull, spendValue, usersValue, visitorsNote, visitorsValue, waitingWords } from "../../flow/kpi_words.ts";
1213 import type { Kpis } from "../../flow/kpis.ts";
1314 import { clogLines, readClog } from "../../flow/clog_read.ts";
1415 import { vitalsLine } from "../../flow/vitals.ts";
@@ -123,10 +124,10 @@ export function kpiRowFor(k: Kpis, live: { sha: string; at: string } | null, now
123124 )}
124125 ${tile(
125126 "Builders running",
126 "/settings/crew",
127 idleLink(k.builders.idle) ?? "/settings/crew",
127128 buildersValue(k.builders),
128129 buildersValue(k.builders),
129 k.builders.slots === 0 ? "No slots set" : "running now",
130 k.builders.slots === 0 ? "No slots set" : idleWords(k.builders.idle) ?? "running now",
130131 k.builders.slots === 0 ? "No slots set" : `Crew builders running now, of ${k.builders.slots} ${k.builders.slots === 1 ? "slot" : "slots"}`,
131132 )}
132133 ${tile(
@@ -163,9 +164,9 @@ export function kpiRowFor(k: Kpis, live: { sha: string; at: string } | null, now
163164 }
164165
165166 /** The figures count every repository, so the caller shows this to an admin only. */
166 export function kpiRow(db: Database, opts: { ceilingUsd?: number; dataDir?: string; now?: Date } = {}): Html {
167 export function kpiRow(db: Database, opts: { ceilingUsd?: number; dataDir?: string; app?: App; now?: Date } = {}): Html {
167168 const now = opts.now ?? new Date();
168 const forge = { ceilingUsd: opts.ceilingUsd ?? null, ...(opts.dataDir === undefined ? {} : { dataDir: opts.dataDir }) };
169 const forge = { ceilingUsd: opts.ceilingUsd ?? null, ...(opts.dataDir === undefined ? {} : { dataDir: opts.dataDir }), ...(opts.app === undefined ? {} : { app: opts.app }) };
169170 return kpiRowFor(cachedKpis(db, now, forge), liveNow(), now);
170171 }
171172
test/home-builders-idle.test.ts added +131
@@ -0,0 +1,131 @@
1 /** Why builders sit idle (#5799): the first reason that holds, on home and in the terminal, from the scheduler's own checks. */
2 import { afterAll, beforeAll, 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 { addToCrew, createAgent } from "../src/actions/crew.ts";
8 import { openIssue } from "../src/actions/issues.ts";
9 import { commitToBranch, createRepo, updateRepoSettings } from "../src/actions/repos.ts";
10 import { getUserByName } from "../src/core/users.ts";
11 import { claimRun, createRun, finishRun } from "../src/core/runs.ts";
12 import { createSession } from "../src/core/sessions.ts";
13 import { noteLimit } from "../src/core/standing.ts";
14 import { addSubscription, EVERYONE, setGrants } from "../src/core/subscriptions.ts";
15 import { type User } from "../src/core/users.ts";
16 import { serve, type Servers } from "../src/http/server.ts";
17 import { createForgeApp } from "../src/tui/forge.ts";
18 import { headlessTerminal } from "../src/tui/term/terminal.ts";
19 import { seedAdmin } from "./helpers/admin.ts";
20 import { quietLogs } from "./helpers/globals.ts";
21 import { settleApp } from "./helpers/tui.ts";
22 import type { Repo } from "../src/core/repos.ts";
23
24 quietLogs();
25
26 let dir: string;
27 let app: App;
28 let servers: Servers;
29 let admin: User;
30 let repo: Repo;
31 let builder: User;
32
33 beforeAll(async () => {
34 dir = await mkdtemp(join(tmpdir(), "forge-builders-idle-"));
35 app = createApp({ dataDir: dir, port: 0 });
36 servers = await serve(app);
37 const a = await seedAdmin(app, { username: "alice", email: "[email protected]", password: "a-long-passphrase" });
38 if (!a.ok) throw new Error("signup failed");
39 admin = a.value;
40 const made = await createRepo(app, admin, { name: "engine", visibility: "private" });
41 if (!made.ok) throw new Error(String(made.error));
42 repo = made.value;
43 const seeded = await commitToBranch(app, admin, repo, { message: "Start", files: [{ path: "README.md", content: "# engine\n" }] });
44 if (!seeded.ok) throw new Error(JSON.stringify(seeded.error));
45 const agent = await createAgent(app, admin, { username: "mason" });
46 if (!agent.ok) throw new Error(String(agent.error));
47 expect(addToCrew(app, admin, repo, "mason").ok).toBe(true);
48 builder = getUserByName(app.db, "mason")!;
49 const on = await updateRepoSettings(app, admin, repo, {
50 autonomy: "autonomous",
51 autonomyDirection: "Build.",
52 autonomyCeilingUsd: 10,
53 autonomySlots: 1,
54 autonomyBy: admin.id,
55 });
56 expect(on.ok).toBe(true);
57 });
58
59 afterAll(async () => {
60 servers.stop();
61 app.close();
62 await rm(dir, { recursive: true, force: true });
63 });
64
65 const home = async (): Promise<string> =>
66 (await fetch(`${servers.url}/`, { headers: { cookie: `forge_session=${createSession(app.db, admin.id).token}; forge_mode=studio` } })).text();
67
68 async function terminal(): Promise<string> {
69 const t = headlessTerminal(200, 40);
70 const { app: tui } = createForgeApp(
71 app,
72 { sshUsername: "alice", remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user: admin },
73 { terminal: t, exitHooks: false },
74 );
75 tui.start();
76 await settleApp(tui);
77 const text = tui.screen.toText();
78 tui.stop();
79 return text;
80 }
81
82 /** The builders tile's anchor on home. */
83 const tile = (page: string): string => /<a class="stat" href="[^"]*"[^>]*><span class="stat-label">Builders running.*?<\/a>/s.exec(page)?.[0] ?? "";
84
85 test("nothing ready: the map has nothing a builder may start", async () => {
86 const page = await home();
87 expect(tile(page)).toContain("nothing ready");
88 expect(tile(page)).toContain('href="/map"');
89 expect(await terminal()).toContain("Builders running 0 of 1, nothing ready");
90 });
91
92 test("a ready issue and a builder with room: no reason is named", async () => {
93 const opened = openIssue(app, admin, repo, { title: "Renderer" });
94 if (!opened.ok) throw new Error(String(opened.error));
95 const page = await home();
96 expect(tile(page)).not.toContain("nothing ready");
97 expect(tile(page)).toContain("running now");
98 expect(await terminal()).not.toMatch(/Builders running 0 of 1, (nothing|no sub|ceiling)/);
99 });
100
101 test("no subscription with headroom: the granted account's window is full", async () => {
102 const sub = addSubscription(app.db, dir, { name: "espo", token: "sk-ant-oat01-" + "x".repeat(24) });
103 if (!sub.ok) throw new Error(sub.error);
104 setGrants(app.db, repo.id, EVERYONE, [sub.value.id]);
105 const now = Date.now();
106 noteLimit(app.db, sub.value.id, { window: "5h", resetsAt: new Date(now + 3_600_000).toISOString(), observedAt: new Date(now).toISOString(), said: "limit" });
107 const page = await home();
108 expect(tile(page)).toContain("no subscription with headroom");
109 expect(tile(page)).toContain('href="/settings/subscriptions"');
110 expect(await terminal()).toContain("Builders running 0 of 1, no subscription with headroom");
111 });
112
113 test("ceiling reached outranks the others", async () => {
114 const spent = createRun(app.db, { repoId: repo.id, kind: "agent", actorId: builder.id, reason: "assigned" });
115 claimRun(app.db, spent.id);
116 finishRun(app.db, spent.id, { state: "ok", summary: "done", costUsd: 12 });
117 const page = await home();
118 expect(tile(page)).toContain("ceiling reached");
119 expect(tile(page)).toContain('href="/settings/crew"');
120 expect(await terminal()).toContain("Builders running 0 of 1, ceiling reached");
121 });
122
123 test("every slot busy: no reason is shown", async () => {
124 const run = createRun(app.db, { repoId: repo.id, kind: "agent", actorId: builder.id, reason: "assigned" });
125 claimRun(app.db, run.id);
126 const page = await home();
127 expect(tile(page)).toContain("1 of 1");
128 expect(tile(page)).not.toContain("ceiling reached");
129 expect(await terminal()).toContain("Builders running 1 of 1");
130 expect(await terminal()).not.toContain("ceiling reached");
131 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs