toolroll 0.5.0

package/dist/slack-settings.js

@@ -0,0 +1,75 @@
+import { loadPrimary } from "./webhooks.js";
+import { loadSlackCredentials } from "./slack-api.js";
+import { SlackState } from "./slack-state.js";
+const escape = (text) => text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+export function slackSettingsHtml(store, dir, csrf, options = {}) {
+    const credentials = loadSlackCredentials(dir), state = new SlackState(store), bindings = credentials ? state.bindings(credentials.installation).filter(one => state.live(one)) : [], binding = options.who === undefined ? null : bindings.find(one => one.approver === options.who) ?? null, others = bindings.length - (binding === null ? 0 : 1);
+    const runtime = credentials
+        ? state.db
+            .prepare("SELECT connected,problem,lease_until FROM slack_runtime WHERE installation=?")
+            .get(credentials.installation)
+        : null;
+    const now = options.now ?? new Date(), live = runtime &&
+        typeof runtime.lease_until === "string" &&
+        runtime.lease_until > now.toISOString() &&
+        runtime.connected;
+    const hidden = `<input type="hidden" name="csrf" value="${escape(csrf)}">`;
+    const password = '<label>Your Toolroll password<input style="min-height:44px" type="password" name="password" autocomplete="current-password" required></label>';
+    const post = (action, content) => `<form method="post" action="/settings/slack/${action}" class="card">${hidden}${content}</form>`;
+    let content = "";
+    if (!credentials) {
+        content =
+            "<p>Manage projects and review results in a private Slack conversation.</p>" +
+                '<details open><summary>Create your Slack app</summary><ol><li>Download the <a href="/settings/slack/manifest">app manifest</a>, then <a href="https://api.slack.com/apps" target="_blank" rel="noopener noreferrer">create an app</a> in your workspace using that manifest.</li><li>Under Basic Information, create an app-level token with <code>connections:write</code>.</li><li>Under OAuth &amp; Permissions, install the app and copy its bot token.</li></ol></details>' +
+                post("connect", '<label>App token<input style="min-height:44px" type="password" name="app-token" autocomplete="off" placeholder="xapp-…" required></label><label>Bot token<input style="min-height:44px" type="password" name="bot-token" autocomplete="off" placeholder="xoxb-…" required></label>' +
+                    password +
+                    '<p class="meta">Tokens stay on this installation. Next, pair your own Slack account.</p><button type="submit">Connect Slack</button>');
+    }
+    else {
+        content = `<p><strong>${escape(credentials.workspace)}</strong> · ${live ? "Connected" : "Waiting for connection"}</p>`;
+        if (runtime?.problem)
+            content += `<p role="status">${escape(String(runtime.problem))}</p>`;
+        if (!live && !runtime?.problem)
+            content +=
+                "<p>Keep the Toolroll worker running to receive Slack messages.</p>";
+        if (options.code) {
+            content +=
+                "<h2>Pair your account</h2><p>Send this in a direct message to your Toolroll Slack app. It expires in 10 minutes.</p>" +
+                    `<label>Pairing message<input type="text" readonly value="pair ${escape(options.code)}" autocomplete="off" style="width:100%;max-width:100%;font-size:14px;min-height:44px"></label>` +
+                    '<a class="button-link" style="min-height:44px;white-space:nowrap" href="/settings/slack">Check connection</a>';
+        }
+        else if (binding && state.live(binding)) {
+            const pending = Number(state.db
+                .prepare("SELECT count(*) n FROM slack_part p JOIN slack_event e ON e.id=p.event WHERE e.binding=? AND p.state='pending'")
+                .get(binding.id)?.n ?? 0);
+            const failed = Number(state.db
+                .prepare("SELECT count(*) n FROM slack_part p JOIN slack_event e ON e.id=p.event WHERE e.binding=? AND p.state='dropped'")
+                .get(binding.id)?.n ?? 0);
+            content +=
+                `<p>Your Slack account is paired.${others ? ` ${others} teammate${others === 1 ? " is" : "s are"} paired too.` : ""}${pending ? ` ${pending} replies waiting to send.` : ""}${failed ? ` ${failed} replies could not be delivered. Open the saved chat to recover them.` : ""}</p>` +
+                    "<p>Try “What needs my attention?” or “Show the evidence for the latest result.”</p>" +
+                    '<p><a href="/chat">Open saved chat</a></p>' +
+                    (loadPrimary(process.env, dir) === "slack"
+                        ? "<p>Task updates are sent here.</p>"
+                        : post("alerts", '<button type="submit">Send task updates here</button>'));
+        }
+        else {
+            content += post("pair", "<h2>Pair your account</h2><p>Your paired Slack account can read your connected projects and confirm proposed changes. Password approvals still open in Toolroll." +
+                (others ? ` ${others} teammate${others === 1 ? " is" : "s are"} already paired.` : "") + "</p>" +
+                password +
+                '<button type="submit">Create pairing code</button>');
+        }
+        if (binding && state.live(binding) && !options.code)
+            content += post("unpair", password + '<p class="meta">Unpairing ends every open button in your chat. Teammates are unaffected.</p><button type="submit">Unpair my account</button>');
+        content +=
+            "<details><summary>Connection settings</summary>" +
+                post("disconnect", password + '<button type="submit">Disconnect Slack</button>') +
+                "</details>";
+    }
+    return `<section style="max-width:42rem;overflow-wrap:anywhere"><p><a href="/settings">Settings</a></p><h1>Slack</h1>${options.problem ? `<p class="problem" role="alert">${escape(options.problem)}</p>` : ""}${content}<details><summary>Access and setup</summary><p>Private messages and threads use your Toolroll permissions. Shared channels are not supported. Secure review links use this installation’s configured HTTPS console address.</p><p>Socket Mode connects out to Slack. It does not need a public webhook or a Tailscale account.</p></details></section>`;
+}

package/dist/slack-state.d.ts

@@ -0,0 +1,13 @@
+/** Slack compatibility names for the shared durable transport state. */
+import { ChatState } from "./chat-delivery-state.js";
+import type { Store } from "./store.js";
+export { chatHash as slackHash } from "./chat-delivery-state.js";
+export type { ChatBinding as SlackBinding, ChatEvent as SlackEvent, ChatPart as SlackPart, ChatContent as SlackContent, } from "./chat-delivery-state.js";
+import type { ChatIdentity } from "./chat-delivery-state.js";
+export type SlackIdentity = ChatIdentity & {
+    team: string;
+};
+export declare const SLACK_SCHEMA: string, SLACK_TABLES: string[];
+export declare class SlackState extends ChatState {
+    constructor(store: Store);
+}

package/dist/slack-state.js

@@ -0,0 +1,9 @@
+/** Slack compatibility names for the shared durable transport state. */
+import { ChatState, chatSchema, chatTables } from "./chat-delivery-state.js";
+export { chatHash as slackHash } from "./chat-delivery-state.js";
+export const SLACK_SCHEMA = chatSchema("slack"), SLACK_TABLES = chatTables("slack");
+export class SlackState extends ChatState {
+    constructor(store) {
+        super(store, "slack");
+    }
+}

package/dist/slack.d.ts

@@ -0,0 +1,13 @@
+import { SocketModeClient } from "@slack/socket-mode";
+import { type SlackChatOptions } from "./slack-chat.js";
+/** The bot and socket tokens must belong to the same app, including after reconnect. */
+export declare class ToolrollSlackSocket extends SocketModeClient {
+    expectedApp: string;
+    wrongApp: () => void;
+    protected onWebSocketMessage(data: string | ArrayBuffer, isBinary: boolean): Promise<void>;
+}
+export declare function followSlack(options: Omit<SlackChatOptions, "identity" | "api" | "owner" | "current"> & {
+    dir: string;
+    signal: AbortSignal;
+    notifications: () => boolean;
+}): Promise<void>;

package/dist/slack.js

@@ -0,0 +1,167 @@
+/** One leased Socket Mode connection, hosted by the ordinary worker. */
+import { randomBytes } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { SocketModeClient, LogLevel } from "@slack/socket-mode";
+import { loadSlackCredentials, slackApi } from "./slack-api.js";
+import { SlackState } from "./slack-state.js";
+import { receiveSlack, processSlackEvent, deliverSlackPart, planSlackNotifications, planSlackRooms, } from "./slack-chat.js";
+/** The bot and socket tokens must belong to the same app, including after reconnect. */
+export class ToolrollSlackSocket extends SocketModeClient {
+    expectedApp = "";
+    wrongApp = () => { };
+    async onWebSocketMessage(data, isBinary) {
+        let packet;
+        try {
+            packet = JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data));
+        }
+        catch {
+            return;
+        }
+        if (packet.type === "hello") {
+            const info = packet.connection_info;
+            if (info?.app_id !== this.expectedApp) {
+                this.wrongApp();
+                await this.disconnect();
+                return;
+            }
+        }
+        return super.onWebSocketMessage(data, isBinary);
+    }
+}
+export async function followSlack(options) {
+    const owner = randomBytes(16).toString("hex"), state = new SlackState(options.store);
+    const pause = async (ms) => {
+        try {
+            await sleep(ms, undefined, { signal: options.signal });
+        }
+        catch {
+            /* shutdown */
+        }
+    };
+    while (!options.signal.aborted) {
+        const credentials = loadSlackCredentials(options.dir);
+        if (!credentials ||
+            !state.lease(credentials.installation, owner, new Date())) {
+            await pause(2000);
+            continue;
+        }
+        let alive = true, connected = false;
+        const same = () => {
+            const current = loadSlackCredentials(options.dir);
+            return (alive &&
+                !options.signal.aborted &&
+                current?.installation === credentials.installation &&
+                current.botToken === credentials.botToken &&
+                current.appToken === credentials.appToken &&
+                state.owns(credentials.installation, owner));
+        };
+        const problem = (text) => state.db
+            .prepare("UPDATE slack_runtime SET problem=? WHERE installation=? AND owner=?")
+            .run(text, credentials.installation, owner);
+        // SDK log output can include envelopes/tokens. Only fixed status phrases are saved.
+        const client = new ToolrollSlackSocket({
+            appToken: credentials.appToken,
+            autoReconnectEnabled: true,
+            clientOptions: { retryConfig: { retries: 2 }, timeout: 15_000 },
+            logger: {
+                debug() { },
+                info() { },
+                warn() { },
+                error() {
+                    problem("Slack is reconnecting. Check the app tokens if this continues.");
+                },
+                setLevel() { },
+                getLevel() {
+                    return LogLevel.ERROR;
+                },
+                setName() { },
+            },
+        });
+        client.expectedApp = credentials.app;
+        client.wrongApp = () => {
+            alive = false;
+            problem("The app token and bot token belong to different Slack apps. Disconnect and use tokens from the same app.");
+        };
+        const stop = () => {
+            alive = false;
+            void client.disconnect().catch(() => { });
+        };
+        options.signal.addEventListener("abort", stop, { once: true });
+        const heartbeat = setInterval(() => {
+            if (!same() || !state.lease(credentials.installation, owner, new Date()))
+                stop();
+        }, 10_000);
+        client.on("connected", () => {
+            connected = true;
+            state.db
+                .prepare("UPDATE slack_runtime SET connected=?,problem=NULL WHERE installation=? AND owner=?")
+                .run(new Date().toISOString(), credentials.installation, owner);
+        });
+        client.on("disconnected", () => {
+            connected = false;
+            if (alive)
+                problem("Slack is disconnected; queued replies are saved.");
+        });
+        client.on("reconnecting", () => {
+            connected = false;
+            problem("Reconnecting to Slack…");
+        });
+        client.on("error", () => problem("Slack connection failed. Check the app tokens and reconnect."));
+        client.on("slack_event", (envelope) => {
+            if (!same())
+                return;
+            try {
+                receiveSlack(state, credentials, envelope.type, envelope.body, new Date());
+                void envelope
+                    .ack()
+                    .catch(() => problem("Slack acknowledgement was lost; a repeated event will be recognized."));
+            }
+            catch {
+                problem("Slack could not save an incoming message; it has not been acknowledged.");
+            }
+        });
+        const chat = {
+            ...options,
+            identity: credentials,
+            owner,
+            api: slackApi(credentials.botToken),
+            canNotify: options.notifications,
+            current: same,
+        };
+        try {
+            await client.start();
+            while (same()) {
+                const retry = state.db
+                    .prepare("SELECT retry_at FROM slack_runtime WHERE installation=?")
+                    .get(credentials.installation)?.retry_at;
+                if (!connected ||
+                    (typeof retry === "string" && retry > new Date().toISOString())) {
+                    await pause(1000);
+                    continue;
+                }
+                await processSlackEvent(chat);
+                if (same())
+                    await planSlackRooms(chat);
+                if (same())
+                    await deliverSlackPart(chat);
+                if (same() && options.notifications())
+                    await planSlackNotifications(chat);
+                await pause(1000);
+            }
+        }
+        catch {
+            if (alive)
+                problem("Slack connection is unavailable. Retrying shortly.");
+        }
+        finally {
+            clearInterval(heartbeat);
+            alive = false;
+            options.signal.removeEventListener("abort", stop);
+            await client.disconnect().catch(() => { });
+            state.db
+                .prepare("UPDATE slack_runtime SET owner=NULL,lease_until=NULL,connected=NULL WHERE installation=? AND owner=?")
+                .run(credentials.installation, owner);
+        }
+        await pause(5000);
+    }
+}

package/dist/spend-ui.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The Spend page (v105): what agent work cost this month, where it went, and
+ * the monthly budgets that alert at 50/80/100 % and (unless set to alert
+ * only) stop new work at 100 %. An instance operator's page; budgets change
+ * with a step-up.
+ */
+import { type BudgetState, type SpendItem } from "./spend.js";
+export declare const SPEND_CSS: string;
+export type SpendView = {
+    month: string;
+    previous: string;
+    next: string | null;
+    items: SpendItem[];
+    budgets: BudgetState[];
+    targets: {
+        value: string;
+        label: string;
+        group: "Everything" | "Projects" | "People" | "Teammates";
+    }[];
+    teammateNames: Map<number, string>;
+    csrf: string;
+};
+export declare function spendHtml(view: SpendView, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): string;
+/** One row per piece of spend, for a spreadsheet. */
+export declare function spendCsv(items: readonly SpendItem[], teammateNames: Map<number, string>): string;

package/dist/spend-ui.js

@@ -0,0 +1,95 @@
+/**
+ * The Spend page (v105): what agent work cost this month, where it went, and
+ * the monthly budgets that alert at 50/80/100 % and (unless set to alert
+ * only) stop new work at 100 %. An instance operator's page; budgets change
+ * with a step-up.
+ */
+import { budgetLabel, usd } from "./spend.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+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}` +
+    `.spend-month{display:flex;gap:10px;align-items:baseline;font-size:.875rem}.spend-total{font-size:1.5rem;font-weight:600;margin:12px 0 2px;font-variant-numeric:tabular-nums}` +
+    `.spend h2{font-size:.9375rem;margin:24px 0 8px}.spend table{width:100%;border-collapse:collapse;font-size:.8125rem}.spend th,.spend td{text-align:left;padding:6px 8px 6px 0;border-bottom:1px solid var(--border);overflow-wrap:anywhere}` +
+    `.spend th{font-weight:500;color:var(--muted-foreground)}.spend td.n{text-align:right;font-variant-numeric:tabular-nums;white-space:nowrap}.spend-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:0 24px}` +
+    `.budget{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:4px 12px;padding:10px 0;border-bottom:1px solid var(--border)}.budget .name{font-weight:500;font-size:.875rem}` +
+    `.budget .figures{font-size:.8125rem;font-variant-numeric:tabular-nums;text-align:right}.budget .bar{grid-column:1/-1;height:6px;border-radius:3px;background:var(--muted);overflow:hidden}` +
+    `.budget .bar span{display:block;height:100%;background:var(--foreground)}.budget.over .bar span{background:var(--danger)}.budget.over .figures{color:var(--danger)}.budget .meta{grid-column:1/-1}` +
+    `.budget details{grid-column:1/-1}.spend form.budget-form{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:8px 12px;align-items:end;margin:8px 0}` +
+    `.spend form.budget-form label{display:grid;gap:4px;font-size:.8125rem}.spend form.budget-form .choice{display:flex;gap:8px;align-items:center}.spend form.budget-form button{justify-self:start}`;
+/** The rows of a breakdown: spend and count by a key, biggest first. */
+function breakdown(items, keyOf, top = 12) {
+    const rows = new Map();
+    for (const item of items) {
+        const key = keyOf(item);
+        if (key === null)
+            continue;
+        const row = rows.get(key) ?? { key, microusd: 0, count: 0, unpriced: 0 };
+        row.microusd += item.microusd ?? 0;
+        row.count++;
+        if (item.microusd === null && item.source === "unpriced")
+            row.unpriced++;
+        rows.set(key, row);
+    }
+    return [...rows.values()].sort((a, b) => b.microusd - a.microusd || b.count - a.count).slice(0, top);
+}
+function table(title, rows, name) {
+    if (rows.length === 0)
+        return "";
+    return `<section><h2>${e(title)}</h2><table><tbody>${rows.map(row => `<tr><td>${e(name(row.key))}</td><td class="n">${row.count}</td><td class="n">${usd(row.microusd)}${row.unpriced > 0 ? ` <span class="meta">+${row.unpriced} unpriced</span>` : ""}</td></tr>`).join("")}</tbody></table></section>`;
+}
+export function spendHtml(view, notice) {
+    const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const total = view.items.reduce((sum, item) => sum + (item.microusd ?? 0), 0);
+    const unpriced = view.items.filter(item => item.microusd === null && (item.tokensIn !== null || item.kind !== "run")).length;
+    const counts = { run: view.items.filter(item => item.kind === "run").length, teammate: view.items.filter(item => item.kind === "teammate").length, chat: view.items.filter(item => item.kind === "chat").length, sort: view.items.filter(item => item.kind === "sort").length };
+    const parts = [`${counts.run} ${counts.run === 1 ? "run" : "runs"}`, ...(counts.teammate > 0 ? [`${counts.teammate} teammate turns`] : []), ...(counts.chat > 0 ? [`${counts.chat} chat turns`] : []), ...(counts.sort > 0 ? [`${counts.sort} ${counts.sort === 1 ? "sort" : "sorts"}`] : [])];
+    const nameOfTeammate = (key) => view.teammateNames.get(Number(key)) ?? `Teammate ${key}`;
+    const budgets = view.budgets.map(budget => {
+        const width = Math.min(100, Math.max(0, budget.percent));
+        const over = budget.spentMicrousd >= budget.limitMicrousd;
+        const label = budgetLabel(budget, budget.scope === "teammate" ? nameOfTeammate(budget.key) : undefined).replace(/'s$/, "");
+        return `<div class="budget${over ? " over" : ""}" data-budget="${budget.id}"><span class="name">${e(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><form method="post" action="/spend/budget" class="budget-form"><input type="hidden" name="csrf" value="${e(view.csrf)}"><input type="hidden" name="target" value="${e(`${budget.scope}:${budget.key}`)}">` +
+            `<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 ? " 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></form></details></div>`;
+    }).join("");
+    const groups = ["Everything", "Projects", "People", "Teammates"];
+    const options = groups.map(group => {
+        const members = view.targets.filter(one => one.group === group);
+        return members.length === 0 ? "" : `<optgroup label="${group}">${members.map(one => `<option value="${e(one.value)}">${e(one.label)}</option>`).join("")}</optgroup>`;
+    }).join("");
+    const add = `<details${view.budgets.length === 0 ? " open" : ""}><summary>Add a budget</summary><form method="post" action="/spend/budget" class="budget-form"><input type="hidden" name="csrf" value="${e(view.csrf)}">` +
+        `<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></form></details>`;
+    const csv = `/spend?month=${e(view.month)}&amp;format=csv`;
+    return `<article class="spend">` +
+        `<div class="spend-head"><h1>Spend</h1><p class="spend-month"><a href="/spend?month=${e(view.previous)}">← ${e(view.previous)}</a><strong>${e(view.month)}</strong>${view.next === null ? "" : `<a href="/spend?month=${e(view.next)}">${e(view.next)} →</a>`}<a href="${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 === "" ? `<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 teammate", breakdown(view.items, item => item.teammate === null ? null : String(item.teammate)), nameOfTeammate) +
+        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. */
+export function spendCsv(items, teammateNames) {
+    const cell = (value) => {
+        const text = value === null || value === undefined ? "" : String(value);
+        const safe = /^[=+\-@\t\r]/.test(text) ? `'${text}` : text;
+        return /[",\n\r]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
+    };
+    const head = ["time_utc", "kind", "project", "person", "teammate", "task", "run", "provider", "model", "tokens_in", "tokens_out", "cost_usd", "priced_by", "billing"];
+    const rows = items.map(item => [item.at, item.kind, item.project, item.person, item.teammate === null ? null : teammateNames.get(item.teammate) ?? item.teammate,
+        item.taskId, item.runId, item.provider, item.model, item.tokensIn, item.tokensOut, item.microusd === null ? null : (item.microusd / 1_000_000).toFixed(6), item.source, item.authMode].map(cell).join(","));
+    return `${head.join(",")}\r\n${rows.map(row => `${row}\r\n`).join("")}`;
+}

package/dist/spend.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Spend (v105): what agent work cost, priced for every provider, and who and
+ * what it counts toward. Work on a subscription (a Claude or Codex login)
+ * costs nothing extra and counts as $0 (its limits are what bind it; see
+ * provider-limits.ts). Work billed to an API key costs what its provider
+ * reported; otherwise its tokens at the model's catalogue price (Settings →
+ * Models), or at the provider's highest listed price when the model isn't
+ * listed; work with no tokens and no cost is "unpriced" and said so.
+ *
+ * Spend counts toward a project (a run's task, a teammate's, a project chat),
+ * a person (who filed the task, or had the chat), a teammate (its turns, and
+ * tasks it filed), and the whole installation. Budgets are per calendar
+ * month (UTC).
+ */
+import type { Database } from "./store.js";
+export type PriceSource = "reported" | "estimated" | "unpriced" | "subscription";
+export type Billing = "subscription" | "api-key";
+/** How a provider's work is billed right now: an API key when Toolroll is set to use one, or when the CLI
+ * itself was last seen billing a key (a key helper, a Console login, Bedrock or Vertex, `codex login --with-api-key`);
+ * otherwise its plan. `db` supplies what was seen (provider_account); without it, the setting alone. */
+export declare function billingOf(provider: string, db?: Database): Billing;
+/** How a provider's CLI was last seen billing (provider_account), or null. */
+export declare function seenBilling(db: Database, provider: string): Billing | null;
+/** How a Claude turn was really billed, from its own stream. Only a plan reports its usage windows (Claude Code 2.1
+ * does on every turn), so that is the one sign of the plan; a named key source or a cloud model id (Bedrock, Vertex)
+ * is a key, and so is "none" without windows (a gateway's bearer token or a cloud provider says "none" too). Null when
+ * the stream said nothing. */
+export declare function claudeBillingFrom(seen: {
+    keySource: string | null;
+    model: string | null;
+    planWindows: boolean;
+}): Billing | null;
+/** How Claude bills on this computer when Toolroll gives it no key (teammate turns, drafts): as its keyless runs
+ * were last seen, and its plan until one has been. */
+export declare function claudeMachineBilling(db: Database): Billing;
+/** Whether API work on this provider can be priced: it reports its cost, or the catalogue has its prices. */
+export declare function canPrice(db: Database, provider: string): boolean;
+export type Price = {
+    inputUsd: number;
+    outputUsd: number;
+    model: string;
+};
+/** A model's catalogue price (US dollars per million tokens), or null when the catalogue doesn't list one. A
+ * Claude short name ("sonnet") is priced as the newest of its family, as the Claude CLI runs it. */
+export declare function priceFor(db: Database, provider: string, model: string | null): Price | null;
+/** The provider's highest listed price, for API work whose model the catalogue doesn't list (or that ran the CLI's
+ * default): a budget that stops work must never see it as free. */
+export declare function ceilingPriceFor(db: Database, provider: string): Price | null;
+/** What a piece of work cost, in micro-dollars: nothing on a subscription; otherwise reported, or tokens at the
+ * catalogue price (usd per million tokens times tokens is micro-dollars), or unpriced. */
+export declare function priceWork(db: Database, work: {
+    provider: string;
+    model: string | null;
+    costUsd: number | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    billing: Billing;
+}): {
+    microusd: number | null;
+    source: PriceSource;
+    price: Price | null;
+};
+export declare const SPEND_SCHEMA = "\nCREATE TABLE IF NOT EXISTS run_spend (\n  run         INTEGER PRIMARY KEY,\n  microusd    INTEGER,\n  source      TEXT NOT NULL CHECK (source IN ('reported', 'estimated', 'unpriced', 'subscription')),\n  billing     TEXT NOT NULL CHECK (billing IN ('subscription', 'api-key')),\n  -- 1 once the run's own evidence set it (a key it was given, what its CLI said); a later turn can only make it a key.\n  billing_fixed INTEGER NOT NULL DEFAULT 0,\n  price_model TEXT,\n  input_usd   REAL,\n  output_usd  REAL,\n  priced_at   TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS budget (\n  id          INTEGER PRIMARY KEY AUTOINCREMENT,\n  scope_kind  TEXT NOT NULL CHECK (scope_kind IN ('installation', 'project', 'person', 'teammate')),\n  scope_key   TEXT NOT NULL,\n  limit_microusd INTEGER NOT NULL CHECK (limit_microusd > 0),\n  hard_stop   INTEGER NOT NULL DEFAULT 1,\n  created_by  TEXT NOT NULL,\n  created_at  TEXT NOT NULL,\n  updated_by  TEXT NOT NULL,\n  updated_at  TEXT NOT NULL,\n  removed_by  TEXT,\n  removed_at  TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS budget_live ON budget (scope_kind, scope_key) WHERE removed_at IS NULL;\nCREATE TABLE IF NOT EXISTS provider_limit (\n  provider       TEXT NOT NULL,\n  window         TEXT NOT NULL,\n  used_percent   REAL NOT NULL,\n  window_minutes INTEGER,\n  resets_at      TEXT,\n  reached        INTEGER NOT NULL DEFAULT 0,\n  plan           TEXT,\n  observed_at    TEXT NOT NULL,\n  PRIMARY KEY (provider, window)\n);\n-- Spend that isn't a run, a teammate turn or a chat: a flow's Claude draft.\nCREATE TABLE IF NOT EXISTS side_spend (\n  id        INTEGER PRIMARY KEY AUTOINCREMENT,\n  kind      TEXT NOT NULL CHECK (kind IN ('draft')),\n  repo      TEXT,\n  provider  TEXT NOT NULL,\n  model     TEXT,\n  cost_usd  REAL,\n  billing   TEXT NOT NULL CHECK (billing IN ('subscription', 'api-key')),\n  at        TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS side_spend_at ON side_spend (at);\nCREATE TABLE IF NOT EXISTS provider_account (\n  provider    TEXT PRIMARY KEY,\n  billing     TEXT NOT NULL CHECK (billing IN ('subscription', 'api-key')),\n  observed_at TEXT NOT NULL\n);\nCREATE INDEX IF NOT EXISTS chat_turn_created ON chat_turn (created_at);\nCREATE INDEX IF NOT EXISTS mate_turn_created ON mate_turn (created_at);\nCREATE INDEX IF NOT EXISTS teammate_turn_at ON teammate_turn (at);\n";
+export type BudgetScope = "installation" | "project" | "person" | "teammate";
+export type Budget = {
+    id: number;
+    scope: BudgetScope;
+    key: string;
+    limitMicrousd: number;
+    hardStop: boolean;
+    updatedBy: string;
+    updatedAt: string;
+};
+/** One piece of spend, whatever made it, with what it counts toward. */
+export type SpendItem = {
+    at: string;
+    kind: "run" | "teammate" | "chat" | "sort" | "draft";
+    microusd: number | null;
+    source: PriceSource;
+    project: string | null;
+    person: string | null;
+    teammate: number | null;
+    provider: string;
+    model: string | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    taskId: string | null;
+    runId: number | null;
+    authMode: string | null;
+};
+/** The calendar month (UTC) `at` falls in: [start, end) as ISO strings, and its name (YYYY-MM). */
+export declare function monthOf(at: Date): {
+    from: string;
+    to: string;
+    name: string;
+};
+/** A month by its name (YYYY-MM), or null. */
+export declare function monthNamed(name: string | null): {
+    from: string;
+    to: string;
+    name: string;
+} | null;
+/** Every teammate's name by id (its handle when its soul file names none). */
+export declare function teammateNames(db: Database): Map<number, string>;
+export declare function teammateFilers(db: Database): (repo: string | null, filedBy: string | null, kind: string | null) => number | null;
+/** Who a task's work counts toward: its own filer, or, for a revision filed by automation (an automatic repair), the
+ * filer of the task it revises, up its ancestry (bounded). */
+export declare function filersOf(db: Database): (taskRef: number) => {
+    repo: string | null;
+    filedBy: string | null;
+    kind: string | null;
+};
+/** Every piece of spend in [from, to): runs (by when they started), teammate turns and chat turns. `modeOf` says how
+ * a provider bills when a record doesn't (older rows): its current login or key. */
+export declare function spendItems(db: Database, from: string, to: string, modeOf?: (provider: string) => Billing): SpendItem[];
+/** Whether a piece of spend counts toward a budget. */
+export declare function countsToward(item: SpendItem, budget: Pick<Budget, "scope" | "key">): boolean;
+export type BudgetState = Budget & {
+    spentMicrousd: number;
+    unpriced: number;
+    percent: number;
+};
+/** A piece of work's agents as a budget sees them: which provider, billed how. */
+export type BudgetAgent = {
+    provider: string;
+    billing: Billing;
+};
+/** What a budget gate says: nothing holds it, or the budget it's over (used up), or the budget that covers API work it
+ * can't price (no reported cost, no catalogue prices yet: never counted as free). */
+export type BudgetHold = {
+    over: BudgetState | null;
+    why: "used-up" | "unpriced" | null;
+    unpricedProvider: string | null;
+    remainingMicrousd: number | null;
+};
+/** Why work waits on a budget, in words. */
+export declare function budgetHoldWords(hold: BudgetHold, month: string, teammateName?: string): string;
+/** Each budget's month so far: what counted toward it, and how many pieces of work had no price. */
+export declare function budgetStates(budgets: readonly Budget[], items: readonly SpendItem[]): BudgetState[];
+/** A budget in words: "The shop project's", "alex's", "Maya's (teammate)", "The whole installation's". */
+export declare function budgetLabel(budget: Pick<Budget, "scope" | "key">, teammateName?: string): string;
+export declare const usd: (microusd: number | null) => string;