toolroll 0.9.63 → 0.9.67

package/dist/server/terminals.d.ts

@@ -0,0 +1,31 @@
+import { type IncomingMessage, type Server } from "node:http";
+import type { Duplex } from "node:stream";
+import { TerminalHost } from "../live-terminal.js";
+import type { LiveBus } from "../live-bus.js";
+import type { Store } from "../store.js";
+import type { ServeOptions } from "./http.js";
+import type { ServerRuntime } from "./runtime.js";
+export type TerminalDeps = {
+    host: TerminalHost | null;
+    /** Why there is no host (no pty library on this install), in words. */
+    problem: string | null;
+    bus: LiveBus;
+    allowedHost: (host: string | undefined) => boolean;
+    /** serve.ts's: the source a loopback proxy forwarded for (`fwd:<hop>`), else the peer. */
+    forwardedSourceOf: (request: IncomingMessage) => string;
+    publicOrigin: URL | null;
+    /** The console's server: its upgrade event is answered here. */
+    server: Server;
+};
+/** The console's terminal host: on a machine that runs agents, when this install has a pty library; else why not. */
+export declare function terminalHostFor(store: Store, options: Pick<ServeOptions, "terminalHost" | "localRunner">): {
+    host: TerminalHost | null;
+    problem: string | null;
+};
+export declare function createTerminalHandlers(runtime: ServerRuntime, deps: TerminalDeps): {
+    registrations: import("./handler-registry.js").Registration[];
+    upgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+    /** Shutdown: no more attaches, every socket dropped, every program ended (bounded by the host's grace). The problem,
+     * when a terminal's processes couldn't be proved stopped. */
+    close(): Promise<Error | null>;
+};

package/dist/server/terminals.js

@@ -0,0 +1,365 @@
+/**
+ * Live terminals over the console (docs/plans/live-terminal.md): the Live page, its state, start/close/remove, and the
+ * WebSocket a page attaches with.
+ *
+ * A terminal is shell-equivalent on this computer, so every road is the coding workspace's: a browser sign-in of an
+ * installation-wide operator (codingActorAllowed), a project the coding workspace admits, and a fresh password to
+ * start one. The socket is not a route-table row (an upgrade never reaches the request handler); it re-checks
+ * everything the console's request path checks, and more, BEFORE the upgrade is accepted:
+ *
+ *   host allowlisted → HTTPS or a private path (this computer, the tailnet) → Origin exactly this page's own origin →
+ *   no token or Authorization → cookie session, re-proved against the database → operator of the same generation →
+ *   the terminal is theirs and its project still admitted → a viewer slot free.
+ *
+ * While open, the same proof runs before every input frame, before output once it is a second old, every 5 s, and at
+ * once on every database change (the live bus); a failure closes the socket with 4401.
+ */
+import { randomBytes } from "node:crypto";
+import { STATUS_CODES } from "node:http";
+import { dirname, join } from "node:path";
+import { WebSocketServer } from "ws";
+import { readForm, CONSOLE_FORMS } from "../contracts/console-api.js";
+import { html, htmlString } from "../html.js";
+import { openTerminalLedger } from "../terminal-catalog.js";
+import { loadPtySpawn, MAX_FRAME_BYTES, TerminalHost, MAX_VIEWERS, parseTerminalFrame, TERMINAL_PROGRAMS, TerminalError } from "../live-terminal.js";
+import { logEvent } from "../log.js";
+import { passwordlessOn } from "../passwordless.js";
+import { projectName, rowVisible } from "../project.js";
+import { transportOf } from "../public-access.js";
+import { handlersOf } from "./handler-registry.js";
+import { respond } from "./http.js";
+import { rereadBrowser } from "./live.js";
+const TERMINAL_ID = /^\/term\/([a-f0-9]{32})(?:\/(socket|close|remove))?$/;
+/** A viewer this far behind is dropped; its page reconnects and replays the scrollback. */
+const BEHIND_BYTES = 4 * 1024 * 1024;
+/** Typed input per socket: a burst of this many bytes, refilled at this many a second. */
+const INPUT_BURST = 256 * 1024;
+const INPUT_PER_SECOND = 256 * 1024;
+const REPROVE_MS = 1_000;
+const SWEEP_MS = 5_000;
+/** The console's terminal host: on a machine that runs agents, when this install has a pty library; else why not. */
+export function terminalHostFor(store, options) {
+    if (options.terminalHost !== undefined)
+        return { host: options.terminalHost, problem: options.terminalHost === null ? "Terminals are off on this console." : null };
+    const database = store.isDemo() ? null : store.databaseFile();
+    if (options.localRunner === undefined || database === null || database === "")
+        return { host: null, problem: "Terminals run on the computer that runs your agents. Open Toolroll there." };
+    const spawn = loadPtySpawn();
+    if (spawn === null)
+        return { host: null, problem: "This install has no terminal support (the optional @lydell/node-pty package didn't load). Reinstall Toolroll to add it." };
+    const ledger = openTerminalLedger(store.raw());
+    return { host: new TerminalHost({ spawn, worktreeRoot: join(dirname(database), "live-worktrees"), ...(ledger === null ? {} : { ledger }) }), problem: null };
+}
+export function createTerminalHandlers(runtime, deps) {
+    const { store, codingActorAllowed, codingProjectAllowed, liveCeiling } = runtime;
+    const transportOfRequest = (request) => transportOf({ peer: request.socket.remoteAddress, joinSource: deps.forwardedSourceOf(request),
+        forwardedProto: request.headers["x-forwarded-proto"], forwarded: request.headers["forwarded"] });
+    const sockets = new Set();
+    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES, perMessageDeflate: false });
+    /** An operator signed in with a browser, of the generation they signed in with; else null. */
+    const operatorOf = (who) => who?.via === "cookie" && who.role === "approver" && !store.isDemo() && codingActorAllowed({ name: who.name, generation: who.session.generation }) ? who : null;
+    /** The project a terminal works in is one the coding workspace admits for this person, now. */
+    const projectAllowed = (name, repo) => rowVisible(liveCeiling(), repo) && store.accountCanAccess(name, repo) && codingProjectAllowed(repo);
+    const owned = (who, terminal) => terminal !== null && terminal.owner === who.name && terminal.generation === who.session.generation;
+    const record = (event, who, terminal) => logEvent("info", `terminal.${event}`, { actor: who, terminal: terminal.id, repo: terminal.repo, program: terminal.program });
+    const json = (ctx, status, value) => respond(ctx.response, status, "application/json", JSON.stringify(value));
+    const refusal = (ctx) => {
+        if (operatorOf(ctx.who) === null)
+            return "Terminals are for installation-wide operators signed in with a browser.";
+        if (deps.host === null)
+            return deps.problem ?? "Terminals aren't available on this install.";
+        return null;
+    };
+    /** The Live page: its own small document and bundle. */
+    async function page(ctx) {
+        const { who, url, response, request } = ctx;
+        if (operatorOf(who) === null)
+            return respond(response, 403, "text/plain; charset=utf-8", "Terminals are for installation-wide operators signed in with a browser.");
+        const id = TERMINAL_ID.exec(url.pathname)?.[1] ?? "";
+        const nonce = randomBytes(16).toString("base64");
+        const host = request.headers.host ?? "";
+        const document = html `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content"><meta name="theme-color" content="#0C0E12"><meta name="apple-mobile-web-app-capable" content="yes"><title>Live — Toolroll</title><link rel="icon" href="/icon.svg"><link rel="manifest" href="/manifest.webmanifest"><link rel="stylesheet" href="/assets/terminal.css"></head><body><div id="so-term"></div><div id="so-term-boot" hidden data-csrf="${who.session.csrf}" data-session="${id}" data-passwordless="${passwordlessOn(store) ? "1" : ""}"></div><script type="module" src="/assets/terminal.js" nonce="${nonce}"></script></body></html>`;
+        response.writeHead(200, {
+            "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer",
+            // The socket is this page's own host: named outright, since older WebKit doesn't read 'self' as ws:/wss:.
+            "Content-Security-Policy": `default-src 'none'; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self'; manifest-src 'self'; script-src 'nonce-${nonce}'; connect-src 'self' ws://${host} wss://${host}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`,
+        });
+        response.end(htmlString(document));
+    }
+    async function state(ctx) {
+        const who = operatorOf(ctx.who);
+        if (who === null)
+            return json(ctx, 403, { error: "operator" });
+        const sessions = deps.host === null ? [] : deps.host.list(who.name).filter(one => owned(who, one) && projectAllowed(who.name, one.repo));
+        return json(ctx, 200, {
+            available: deps.host !== null, problem: deps.host === null ? deps.problem ?? "Terminals aren't available on this install." : null,
+            programs: TERMINAL_PROGRAMS,
+            projects: runtime.consoleProjects().filter(repo => projectAllowed(who.name, repo)).map(path => ({ path, name: projectName(path) })),
+            sessions: sessions.map(one => ({ id: one.id, repo: one.repo, project: projectName(one.repo), program: one.program, branch: one.branch, startedAt: one.startedAt, endedAt: one.endedAt, exit: one.exit, cleanup: one.cleanup })),
+        });
+    }
+    async function start(ctx) {
+        const refused = refusal(ctx);
+        if (refused !== null)
+            return json(ctx, 403, { ok: false, error: refused });
+        const who = ctx.who;
+        const body = readForm(ctx.posted, CONSOLE_FORMS.term);
+        if ([...new Set(body.keys())].some(key => body.sent.getAll(key).length !== 1))
+            return json(ctx, 400, { ok: false, error: "Submit one value for each field." });
+        const repo = body.get("repo") ?? "", program = body.get("program") ?? "";
+        if (!TERMINAL_PROGRAMS.includes(program))
+            return json(ctx, 400, { ok: false, error: "Choose Claude Code, Codex or a shell." });
+        if (!runtime.consoleProjects().includes(repo) || !projectAllowed(who.name, repo))
+            return json(ctx, 403, { ok: false, error: "Choose a project available to your account." });
+        // The organisation's policy decides whether this provider may run in a person's own session.
+        if (program !== "shell") {
+            const stopped = store.sessionPolicyRefusal(program, null, "live terminals");
+            if (stopped !== null)
+                return json(ctx, 403, { ok: false, error: stopped });
+        }
+        if (!runtime.authenticateApprover(who, body.get("password") ?? "").ok)
+            return json(ctx, 403, { ok: false, error: "Enter your Toolroll password to start a terminal." });
+        // The same session, still an operator of the same generation, and the project still theirs: asked right before the
+        // program starts (after the slow worktree work) and again once it has.
+        const stillAllowed = () => {
+            const again = rereadBrowser(runtime, ctx.request, who);
+            if (again === null || operatorOf(again) === null)
+                return "Your access changed. Sign in again.";
+            return projectAllowed(who.name, repo) && runtime.consoleProjects().includes(repo) ? null : "That project is no longer available to your account.";
+        };
+        try {
+            const terminal = await deps.host.start({ name: who.name, generation: who.session.generation }, repo, program, undefined, stillAllowed);
+            const after = stillAllowed();
+            if (after !== null) {
+                // Nothing of it stays: the program is swept, then its worktree removed (a sweep that can't prove itself keeps it).
+                await deps.host.close(terminal.id);
+                await deps.host.remove(terminal.id).catch(() => { });
+                return json(ctx, 403, { ok: false, error: after });
+            }
+            record("start", who.name, terminal);
+            return json(ctx, 200, { ok: true, id: terminal.id });
+        }
+        catch (error) {
+            return json(ctx, 409, { ok: false, error: error instanceof TerminalError ? error.message : "The terminal didn't start." });
+        }
+    }
+    const act = (verb) => async (ctx) => {
+        const refused = refusal(ctx);
+        if (refused !== null)
+            return json(ctx, 403, { ok: false, error: refused });
+        const who = ctx.who;
+        const terminal = deps.host.get(TERMINAL_ID.exec(ctx.url.pathname)?.[1] ?? "");
+        if (!owned(who, terminal) || !projectAllowed(who.name, terminal.repo))
+            return json(ctx, 404, { ok: false, error: "No such terminal." });
+        try {
+            if (verb === "close")
+                await deps.host.close(terminal.id);
+            else
+                await deps.host.remove(terminal.id);
+            record(verb, who.name, terminal);
+            return json(ctx, 200, { ok: true });
+        }
+        catch (error) {
+            return json(ctx, 409, { ok: false, error: error instanceof TerminalError ? error.message : `The terminal couldn't be ${verb === "close" ? "closed" : "removed"}.` });
+        }
+    };
+    /** A plain GET of the socket address: it only answers an upgrade. */
+    async function socketWithoutUpgrade(ctx) {
+        ctx.response.setHeader("Upgrade", "websocket");
+        return respond(ctx.response, 426, "text/plain; charset=utf-8", "This address answers a WebSocket upgrade only.");
+    }
+    // ---- the socket ------------------------------------------------------------------------------------------------
+    const reprovers = new Set();
+    const unsubscribe = deps.bus.subscribe(() => { for (const reprove of [...reprovers])
+        reprove(); });
+    const sweep = setInterval(() => { for (const reprove of [...reprovers])
+        reprove(); }, SWEEP_MS);
+    sweep.unref?.();
+    /** Answer a refused upgrade in plain HTTP and drop the connection. */
+    const refuseUpgrade = (socket, status, words) => {
+        const body = `${words}\n`;
+        try {
+            socket.end(`HTTP/1.1 ${status} ${STATUS_CODES[status] ?? ""}\r\nConnection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(body)}\r\nCache-Control: no-store\r\n\r\n${body}`);
+        }
+        catch { /* already gone */ }
+        socket.destroy();
+    };
+    /** True when this request was an upgrade for a terminal (answered or refused here); false leaves it to others. */
+    function upgrade(request, socket, head) {
+        let url;
+        try {
+            url = new URL(request.url ?? "/", "http://placeholder");
+        }
+        catch {
+            return false;
+        }
+        const match = TERMINAL_ID.exec(url.pathname);
+        if (match === null || match[2] !== "socket")
+            return false;
+        socket.on("error", () => socket.destroy());
+        const id = match[1];
+        if (request.method !== "GET") {
+            refuseUpgrade(socket, 405, "Only GET upgrades.");
+            return true;
+        }
+        if (url.search !== "") {
+            refuseUpgrade(socket, 400, "This address takes no query; credentials never travel in URLs.");
+            return true;
+        }
+        const host = request.headers.host;
+        if (!deps.allowedHost(host)) {
+            refuseUpgrade(socket, 421, "This console doesn't answer at that address.");
+            return true;
+        }
+        const transport = transportOfRequest(request);
+        if (!transport.https && !transport.privatePath) {
+            refuseUpgrade(socket, 403, "Open the console over HTTPS to use a terminal from here.");
+            return true;
+        }
+        // Exactly the origin of a page served at this host, over this transport (the public https origin for its host).
+        const expected = deps.publicOrigin !== null && host === deps.publicOrigin.host ? deps.publicOrigin.origin : `${transport.https ? "https" : "http"}://${host}`;
+        if (request.headers.origin !== expected) {
+            refuseUpgrade(socket, 403, "A terminal opens only from this console's own page.");
+            return true;
+        }
+        if (request.headers.authorization !== undefined) {
+            refuseUpgrade(socket, 403, "Terminals open with a browser sign-in only.");
+            return true;
+        }
+        // Read without touching: a session ended elsewhere is never written back by being seen (round 2, finding 1).
+        const who = operatorOf(runtime.identify(request, false));
+        if (who === null || rereadBrowser(runtime, request, who) === null) {
+            refuseUpgrade(socket, 401, "Sign in as an installation-wide operator.");
+            return true;
+        }
+        const terminal = deps.host?.get(id) ?? null;
+        if (!owned(who, terminal) || !projectAllowed(who.name, terminal.repo)) {
+            refuseUpgrade(socket, 404, "No such terminal.");
+            return true;
+        }
+        if (deps.host.viewerCount(id) >= MAX_VIEWERS) {
+            refuseUpgrade(socket, 429, `This terminal is open in ${MAX_VIEWERS} places already.`);
+            return true;
+        }
+        wss.handleUpgrade(request, socket, head, ws => attach(ws, request, who, terminal));
+        return true;
+    }
+    function attach(ws, request, who, terminal) {
+        const host = deps.host;
+        sockets.add(ws);
+        let provedAt = 0, closed = false, detach = null;
+        let budget = INPUT_BURST, filledAt = Date.now();
+        const shut = (code, reason) => {
+            if (closed)
+                return;
+            closed = true;
+            detach?.();
+            reprovers.delete(reprove);
+            try {
+                ws.close(code, reason);
+            }
+            catch {
+                ws.terminate();
+            }
+            // A peer that never answers the close is dropped outright.
+            setTimeout(() => ws.terminate(), 2_000).unref?.();
+        };
+        const prove = () => {
+            const again = rereadBrowser(runtime, request, who);
+            const ok = again !== null && operatorOf(again) !== null && owned(who, host.get(terminal.id)) && projectAllowed(who.name, terminal.repo);
+            if (ok)
+                provedAt = Date.now();
+            return ok;
+        };
+        const reprove = () => { if (!closed && !prove())
+            shut(4401, "signed out"); };
+        const stillProved = () => Date.now() - provedAt < REPROVE_MS || prove();
+        const viewer = {
+            output(data) {
+                if (closed)
+                    return;
+                if (!stillProved())
+                    return shut(4401, "signed out");
+                if (ws.bufferedAmount > BEHIND_BYTES)
+                    return shut(4008, "fell behind");
+                ws.send(data, { binary: true });
+            },
+            control(message) {
+                if (closed)
+                    return;
+                if (!stillProved())
+                    return shut(4401, "signed out");
+                ws.send(JSON.stringify(message));
+            },
+        };
+        ws.on("message", (data, isBinary) => {
+            if (closed)
+                return;
+            if (isBinary)
+                return shut(1003, "text frames only");
+            if (!prove())
+                return shut(4401, "signed out");
+            const text = Array.isArray(data) ? Buffer.concat(data).toString("utf8") : Buffer.from(data).toString("utf8");
+            const frame = parseTerminalFrame(text);
+            if (frame === null)
+                return shut(1003, "not a terminal frame");
+            if (frame.t === "resize")
+                return host.resize(terminal.id, frame.cols, frame.rows);
+            const now = Date.now();
+            budget = Math.min(INPUT_BURST, budget + ((now - filledAt) / 1000) * INPUT_PER_SECOND);
+            filledAt = now;
+            const size = Buffer.byteLength(frame.d);
+            if (size > budget)
+                return shut(1008, "typing faster than a terminal reads");
+            budget -= size;
+            // The program isn't reading: nothing more is queued for it until it does (round 2, finding 5).
+            if (!host.input(terminal.id, frame.d))
+                ws.send(JSON.stringify({ t: "input-full" }));
+        });
+        ws.on("close", () => { closed = true; detach?.(); reprovers.delete(reprove); sockets.delete(ws); });
+        ws.on("error", () => shut(1011, "socket error"));
+        if (!prove())
+            return shut(4401, "signed out");
+        try {
+            detach = host.attach(terminal.id, viewer);
+        }
+        catch (error) {
+            return shut(error instanceof TerminalError && /open in/.test(error.message) ? 4429 : 4404, "unavailable");
+        }
+        reprovers.add(reprove);
+        record("attach", who.name, terminal);
+    }
+    deps.server.on("upgrade", (request, socket, head) => {
+        if (!upgrade(request, socket, head))
+            socket.destroy();
+    });
+    return {
+        registrations: handlersOf("tasks", {
+            "term.page": page,
+            "term.session": async (ctx) => page(ctx),
+            "term.state": state,
+            "term.start": start,
+            "term.close": act("close"),
+            "term.remove": act("remove"),
+            "term.socket": socketWithoutUpgrade,
+        }),
+        upgrade,
+        /** Shutdown: no more attaches, every socket dropped, every program ended (bounded by the host's grace). The problem,
+         * when a terminal's processes couldn't be proved stopped. */
+        async close() {
+            unsubscribe();
+            clearInterval(sweep);
+            for (const ws of sockets)
+                ws.terminate();
+            sockets.clear();
+            wss.close();
+            const stopped = await deps.host?.stop();
+            if (stopped !== undefined && !stopped.clean) {
+                logEvent("error", "terminal.shutdown-uncertain", {});
+                // Reported, never thrown: the server still closes, and its close callback carries this (serve.ts).
+                return new Error("A live terminal's processes could not be proved stopped. Check for them before replacing Toolroll.");
+            }
+            return null;
+        },
+    };
+}

package/dist/setup-guide.js

@@ -1,16 +1,17 @@
 /** Read-only suggestions for the shared desktop and browser setup flow. */
+import { withAcp } from "./acp-agents.js";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { validModelId } from "./provider.js";
 import { planInstall, applyInstall, skillContent, SKILL_DIR, SKILL_FILE } from "./skills.js";
-export const ASSISTANTS = {
+export const ASSISTANTS = withAcp({
     claude: { name: "Claude", description: "Use Claude Code for your tasks." },
     codex: { name: "Codex", description: "Use your OpenAI coding assistant." },
     gemini: { name: "Gemini", description: "Use Google's coding assistant." },
     openrouter: { name: "OpenRouter", description: "Use a model from your OpenRouter account." },
-};
+}, agent => ({ name: agent.name, description: `Use ${agent.name} for builds, once it's checked on this computer.` }));
 export function modelChoices(provider, configured, home = homedir()) {
     // Aliases documented at https://code.claude.com/docs/en/model-config.
     let choices = provider === "claude"

package/dist/slack-chat.js

@@ -4,7 +4,7 @@ import { chatQuestionButtons } from "./subagent-question.js";
 import { chatAskButtons } from "./chat-ask.js";
 import { channelInbox } from "./chat-inbox.js";
 import { roomCommand } from "./chat-rooms.js";
-import { processChatEvent, applyChatAction, planChatNotifications, channelAccess, planRoomMessages, } from "./chat-delivery.js";
+import { processChatEvent, applyChatAction, planChatNotifications, channelAccess, planRoomMessages, heldForWatch, } from "./chat-delivery.js";
 /** Slack is a transport for the same saved assistant and confirmation doors. */
 import { proposalPreview, proposalLink, proposalOutcomeText, armedCardText, armedYesLabel, } from "./chat-channel.js";
 import { LEAD_MESSAGE_MAX_CHARS } from "./lead.js";
@@ -404,6 +404,9 @@ export async function deliverSlackPart(options) {
             unfurl_links: false,
             unfurl_media: false,
         };
+        // The watch, at the last moment before the network (cockpit §3).
+        if (heldForWatch(state, store, row.id, event, binding.approver, content, now))
+            return true;
         const answer = target
             ? await options.api("chat.update", { ...args, ts: target })
             : await options.api("chat.postMessage", {

package/dist/spend-ui.js

@@ -4,7 +4,7 @@
  * only) stop new work at 100 %. An instance operator's page; budgets change
  * with a step-up.
  */
-import { html, postForm } from "./html.js";
+import { html, postForm, reauth } from "./html.js";
 import { budgetLabel, usd } from "./spend.js";
 const projectName = (repo) => repo.split("/").filter(Boolean).pop() ?? repo;
 export const SPEND_CSS = `.spend{max-width:960px;min-width:0}.spend-head{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.spend-head h1{margin:0}` +
@@ -48,14 +48,14 @@ export function spendHtml(view, notice) {
         const width = Math.min(100, Math.max(0, budget.percent));
         const over = budget.spentMicrousd >= budget.limitMicrousd;
         const label = budgetLabel(budget, budget.scope === "subagent" ? nameOfSubagent(budget.key) : undefined).replace(/'s$/, "");
-        return html `<div class="budget${over ? " over" : ""}" data-budget="${budget.id}"><span class="name">${label}</span><span class="figures">${usd(budget.spentMicrousd)} of ${usd(budget.limitMicrousd)} · ${budget.percent}%</span><span class="bar" aria-hidden="true"><span style="width:${width}%"></span></span><span class="meta">${over && budget.hardStop ? "Used up: new API work waits until next month or a higher budget." : budget.hardStop ? "Stops API work at 100%." : "Alerts only."}${budget.unpriced > 0 ? ` ${budget.unpriced} unpriced` : ""}</span><details><summary>Change</summary>${postForm("/spend/budget", html `<label>Monthly limit (US dollars)<input type="number" name="usd" min="1" step="1" value="${Math.round(budget.limitMicrousd / 1_000_000)}" required></label><label class="choice"><input type="checkbox" name="stop" value="1"${budget.hardStop ? html ` checked` : ""}> Stop new work at 100%</label><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label><button type="submit" name="action" value="save">Save</button> <button type="submit" name="action" value="remove">Remove</button>`, { attrs: { class: "budget-form" }, hidden: { target: `${budget.scope}:${budget.key}` } })}</details></div>`;
+        return html `<div class="budget${over ? " over" : ""}" data-budget="${budget.id}"><span class="name">${label}</span><span class="figures">${usd(budget.spentMicrousd)} of ${usd(budget.limitMicrousd)} · ${budget.percent}%</span><span class="bar" aria-hidden="true"><span style="width:${width}%"></span></span><span class="meta">${over && budget.hardStop ? "Used up: new API work waits until next month or a higher budget." : budget.hardStop ? "Stops API work at 100%." : "Alerts only."}${budget.unpriced > 0 ? ` ${budget.unpriced} unpriced` : ""}</span><details><summary>Change</summary>${postForm("/spend/budget", html `<label>Monthly limit (US dollars)<input type="number" name="usd" min="1" step="1" value="${Math.round(budget.limitMicrousd / 1_000_000)}" required></label><label class="choice"><input type="checkbox" name="stop" value="1"${budget.hardStop ? html ` checked` : ""}> Stop new work at 100%</label>${reauth(html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label>`)}<button type="submit" name="action" value="save">Save</button> <button type="submit" name="action" value="remove">Remove</button>`, { attrs: { class: "budget-form" }, hidden: { target: `${budget.scope}:${budget.key}` } })}</details></div>`;
     });
     const groups = ["Everything", "Projects", "People", "Subagents"];
     const options = groups.map(group => {
         const members = view.targets.filter(one => one.group === group);
         return members.length === 0 ? "" : html `<optgroup label="${group}">${members.map(one => html `<option value="${one.value}">${one.label}</option>`)}</optgroup>`;
     });
-    const add = html `<details${view.budgets.length === 0 ? html ` open` : ""}><summary>Add a budget</summary>${postForm("/spend/budget", html `<label>For<select name="target" required>${options}</select></label><label>Monthly limit (US dollars)<input type="number" name="usd" min="1" step="1" required></label><label class="choice"><input type="checkbox" name="stop" value="1" checked> Stop new work at 100%</label><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label><button type="submit" name="action" value="save">Add budget</button>`, { attrs: { class: "budget-form" } })}</details>`;
+    const add = html `<details${view.budgets.length === 0 ? html ` open` : ""}><summary>Add a budget</summary>${postForm("/spend/budget", html `<label>For<select name="target" required>${options}</select></label><label>Monthly limit (US dollars)<input type="number" name="usd" min="1" step="1" required></label><label class="choice"><input type="checkbox" name="stop" value="1" checked> Stop new work at 100%</label>${reauth(html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label>`)}<button type="submit" name="action" value="save">Add budget</button>`, { attrs: { class: "budget-form" } })}</details>`;
     return html `<article class="spend"><div class="spend-head"><h1>Spend</h1><p class="spend-month"><a href="/spend?month=${view.previous}">← ${view.previous}</a><strong>${view.month}</strong>${view.next === null ? "" : html `<a href="/spend?month=${view.next}">${view.next} →</a>`}<a href="/spend?month=${view.month}&amp;format=csv" download>CSV</a></p></div>${note}<p class="spend-total" data-spend-total="${total}">${usd(total)}</p><p class="meta">${parts.join(" · ")}${unpriced > 0 ? ` · ${unpriced} unpriced (no reported cost or catalogue price)` : ""} · UTC month</p><section><h2>Budgets</h2>${budgets.length === 0 ? html `<p class="meta">No budgets yet.</p>` : budgets}${add}</section><div class="spend-grid">${table("By project", breakdown(view.items, item => item.project), projectName)}${table("By person", breakdown(view.items, item => item.person), key => key)}${table("By subagent", breakdown(view.items, item => item.subagent === null ? null : String(item.subagent)), nameOfSubagent)}${table("By model", breakdown(view.items, item => `${item.provider}${item.model === null ? "" : ` · ${item.model}`}`), key => key)}</div><p class="meta">Subscription work is $0; its limits are on Tasks. API work is what the provider reported, or its tokens at the prices in Settings → Models.</p></article>`;
 }
 /** One row per piece of spend, for a spreadsheet. */

package/dist/spend.js

@@ -7,7 +7,8 @@ export function billingOf(provider, db) {
     if (provider.endsWith("-api"))
         return "api-key";
     const setting = provider.endsWith("-subscription") ? "subscription"
-        : Object.hasOwn(SUBSCRIPTION_CAPABLE, provider) ? readAuthMode(provider) : "api-key";
+        // An ACP agent's work is metered until its billing declaration says otherwise (that is per run, not here).
+        : Object.hasOwn(SUBSCRIPTION_CAPABLE, provider) ? (readAuthMode(provider) === "subscription" ? "subscription" : "api-key") : "api-key";
     if (setting === "api-key" || db === undefined)
         return setting;
     return seenBilling(db, base) ?? setting;

package/dist/steer-capabilities.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What a running attempt can be told and done to, in one place (docs/plans/agents-cockpit.md §4, R10): every live
+ * view of an attempt offers exactly these, and says plainly what is missing. Each answer is derived from the same facts
+ * the store's own gates read (steeringLiveBuild / liveInputRun for notes and pauses, requestRunStop's rules for Stop),
+ * so the view never offers what the store would refuse.
+ *
+ *   Builder with live input (Claude, on this computer's runner)  notes reach it at once · pause/resume · stop
+ *   Any other builder (Codex, OpenRouter, Gemini, ACP; another computer's runner relays)  notes by mailbox while it is
+ *     open, read at its next check; before it starts, in its brief · stop
+ *   A builder past its mailbox (finishing, or repairing its handoff)  no notes for this attempt
+ *   A protocol repair (a `repair` child of a builder), a planner's correction  no notes · Stop stops the owning attempt
+ *   Planner, scout, reviewer  no notes (none reads a mailbox) · stop
+ *
+ * A repair *task* (a task filed to fix a result) runs as a builder, so it is the builder row.
+ */
+import type { Store } from "./store.js";
+export type SteerSend = "live" | "mailbox";
+export type SteerCapability = {
+    /** How a note reaches this attempt; null: it takes none now. */
+    send: SteerSend | null;
+    /** Pause, resume, and pause-and-steer (live input only). */
+    pause: boolean;
+    /** The run a Stop names (the owning attempt for a child), and what the button says; null: the store would refuse. */
+    stop: {
+        run: number;
+        label: string;
+    } | null;
+    /** One plain sentence for the composer: how a note travels, or why there is none. */
+    words: string;
+};
+/** The capability of this exact run, now. Null when it is not running. */
+export declare function steerCapabilityOf(store: Store, runId: number, now: Date): SteerCapability | null;

package/dist/steer-capabilities.js

@@ -0,0 +1,60 @@
+const ROLE_WORDS = { planner: "planner", scout: "scout", reviewer: "reviewer" };
+/** The attempt a run belongs to: up its parents while they share its claim (a protocol repair, a planner's correction). */
+function ownerOf(store, runId) {
+    let at = store.getRun(runId);
+    for (let depth = 0; at !== null && at.parentRun !== null && depth < 16; depth++) {
+        const parent = store.getRun(at.parentRun);
+        if (parent === null || parent.leaseId !== at.leaseId)
+            break;
+        at = parent;
+    }
+    return at?.id ?? runId;
+}
+/** Whether a Stop of this run would be accepted now — requestRunStop's own rules, read without writing. */
+function stoppable(store, runId, now) {
+    const run = store.getRun(runId);
+    if (run === null)
+        return false;
+    if (store.stopOf(runId) !== null)
+        return true; // asking again is the same stop
+    if (run.outcome !== null)
+        return false;
+    if (run.role !== "reviewer" && store.currentLiveLease(run.taskRef, now) !== run.leaseId)
+        return false;
+    return store.publicationForRun(runId) === null;
+}
+/** The capability of this exact run, now. Null when it is not running. */
+export function steerCapabilityOf(store, runId, now) {
+    const run = store.getRun(runId);
+    if (run === null || run.outcome !== null || run.finishedAt !== null)
+        return null;
+    const owner = ownerOf(store, run.id);
+    const stopOf = (label) => stoppable(store, owner, now) ? { run: owner, label } : null;
+    // A child of an attempt (a protocol repair, a planner's correction) is part of it: no notes, and Stop names the owner.
+    if (owner !== run.id) {
+        return { send: null, pause: false, stop: stopOf("Stop this attempt"),
+            words: run.role === "repair" ? "It's repairing its handoff and reads no notes now. Stop this attempt to change its course."
+                : "It's part of a larger attempt and reads no notes. Stop this attempt to change its course." };
+    }
+    const role = ROLE_WORDS[run.role];
+    if (role !== undefined)
+        return { send: null, pause: false, stop: stopOf("Stop"), words: `This ${role} can't take notes; stop it to change its course.` };
+    if (run.role !== "builder")
+        return null;
+    const repairing = store.handle.prepare("SELECT 1 AS hit FROM run WHERE parent_run = ? AND role = 'repair' AND outcome IS NULL").get(run.id) !== undefined;
+    if (repairing)
+        return { send: null, pause: false, stop: stopOf("Stop this attempt"), words: "It's repairing its handoff and reads no notes now. Stop this attempt to change its course." };
+    if (store.liveInputRun(run.taskRef, now) === run.id)
+        return { send: "live", pause: true, stop: stopOf("Stop"), words: "Notes reach the agent right away." };
+    if (store.steeringLiveBuild(run.taskRef, now) === run.id)
+        return { send: "mailbox", pause: false, stop: stopOf("Stop"), words: "It reads notes at its next check." };
+    // Not yet at work: a note filed now is in its brief when it starts. Past its mailbox: none reaches this attempt.
+    const state = store.handle.prepare("SELECT phase, steer_opened_at FROM run WHERE id = ?").get(run.id);
+    const starting = state !== undefined && state["phase"] == null && state["steer_opened_at"] == null && store.currentLiveLease(run.taskRef, now) === run.leaseId;
+    if (starting)
+        return { send: "mailbox", pause: false, stop: stopOf("Stop"), words: "It reads notes when it starts working." };
+    // Never given a mailbox (steering off for it), or past it.
+    if (state?.["steer_opened_at"] == null)
+        return { send: null, pause: false, stop: stopOf("Stop"), words: "It doesn't read notes; anything you send waits for the next attempt." };
+    return { send: null, pause: false, stop: stopOf("Stop"), words: "It has stopped reading notes; anything you send now waits for the next attempt." };
+}

package/dist/steer-controls.d.ts

@@ -0,0 +1,14 @@
+import type { BrowserAgentControls } from "./browser-workspace.js";
+import type { Store } from "./store.js";
+/** The attempt running for a task now: one under the task's live claim (any role; a child shows as its owner's own),
+ * or a review, which runs under its own claim (requestRunStop exempts it from the task's). */
+export declare function liveAttemptOf(store: Store, taskRef: number, now: Date): number | null;
+/** One running attempt's composer: the note's target (null: it takes none now) and its controls. Null when it is not
+ * running, or this person may not act on it (a viewer, the demo). */
+export declare function steerControlsFor(store: Store, taskId: string, runId: number, now: Date, canAct: boolean): {
+    steer: {
+        action: string;
+        run: number;
+    } | null;
+    controls: BrowserAgentControls;
+} | null;

package/dist/steer-controls.js

@@ -0,0 +1,36 @@
+/**
+ * The composer's facts for one running attempt, for whichever surface shows it (the Agents board, a task page, a flow
+ * card's task): what the attempt takes (steer-capabilities.ts), and the exact run each form names. One helper, so every
+ * surface offers the same acts for the same attempt (docs/plans/agents-cockpit.md §4).
+ */
+import { randomUUID } from "node:crypto";
+import { steerCapabilityOf } from "./steer-capabilities.js";
+const taskHrefOf = (taskId) => `/t/${encodeURIComponent(taskId)}`;
+/** The attempt running for a task now: one under the task's live claim (any role; a child shows as its owner's own),
+ * or a review, which runs under its own claim (requestRunStop exempts it from the task's). */
+export function liveAttemptOf(store, taskRef, now) {
+    const lease = store.currentLiveLease(taskRef, now);
+    const row = store.handle.prepare(`SELECT id FROM run WHERE task_ref = ? AND outcome IS NULL AND finished_at IS NULL
+      AND (lease_id = ? OR role = 'reviewer') ORDER BY (lease_id = ?) DESC, id DESC LIMIT 1`).get(taskRef, lease ?? "", lease ?? "");
+    return row === undefined ? null : Number(row["id"]);
+}
+/** One running attempt's composer: the note's target (null: it takes none now) and its controls. Null when it is not
+ * running, or this person may not act on it (a viewer, the demo). */
+export function steerControlsFor(store, taskId, runId, now, canAct) {
+    if (!canAct || store.isDemo())
+        return null;
+    const capability = steerCapabilityOf(store, runId, now);
+    if (capability === null)
+        return null;
+    const href = taskHrefOf(taskId);
+    const pause = capability.pause ? (() => {
+        const state = store.livePauseOf(runId);
+        const until = state?.pausedAt == null || state.limitMs === null ? null : new Date(Date.parse(state.pausedAt) + state.limitMs).toISOString();
+        // Each form its own request id, so a repeated submit is the same request and two forms never collide.
+        return { action: `${href}/pause`, run: runId, state: state?.state ?? null, requests: [`web-${randomUUID()}`, `web-${randomUUID()}`, `web-${randomUUID()}`], until };
+    })() : null;
+    return {
+        steer: capability.send === null ? null : { action: `${href}/steer`, run: runId },
+        controls: { send: capability.send, words: capability.words, pause, stop: capability.stop === null ? null : { action: `${href}/stop`, ...capability.stop } },
+    };
+}