toolroll 0.9.103 → 0.9.105

package/dist/slack-api.js

@@ -40,7 +40,6 @@ const errors = new Set([
     "file_not_found",
     "already_complete",
     "not_in_channel",
-    // The 👀 and edits of the live message: named, so they are told apart from a real failure.
     "already_reacted",
     "no_reaction",
     "cant_update_message",
@@ -189,7 +188,6 @@ export async function uploadSlackBytes(url, bytes, fetcher = fetch) {
         throw new SlackError("Slack did not confirm the file upload", 15_000, true);
     }
 }
-/** DM scopes plus channel history for rooms that follow a team conversation. */
 export const SLACK_MANIFEST = {
     display_information: {
         name: "Toolroll",
@@ -217,7 +215,6 @@ export const SLACK_MANIFEST = {
                 "users:read",
                 "files:read",
                 "files:write",
-                // The 👀 on a message when it arrives, and taking it off once the answer is delivered.
                 "reactions:write",
             ],
         },

package/dist/slack-chat.js

@@ -7,7 +7,6 @@ import { chatQuestionButtons } from "./subagent-question.js";
 import { chatAskButtons } from "./chat-ask.js";
 import { admitChatEvent } from "./chat-admission.js";
 import { processChatEvent, 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";
 import { renderReply } from "./reply-shape.js";
@@ -32,7 +31,6 @@ const split = (text, size = 2800) => {
     }
     return parts.length ? parts : ["No reply was recorded."];
 };
-/** Synchronous receipt before ACK. Never stores response_url, raw tokens, or a pairing code. */
 export function receiveSlack(state, identity, type, raw, now) {
     const body = object(raw);
     if (body.api_app_id !== identity.app)
@@ -80,7 +78,6 @@ export function receiveSlack(state, identity, type, raw, now) {
         if (!interaction.ok || interaction.value.container.type !== "message")
             return false;
         const { actions, container, user } = interaction.value;
-        // A link button opens its page itself: nothing to do, and nothing to say.
         if (actions.length === 1 && SLACK_LINK_ACTION.test(actions[0].action_id ?? ""))
             return false;
         member = user.id;
@@ -88,7 +85,6 @@ export function receiveSlack(state, identity, type, raw, now) {
         ts = container.message_ts;
         thread = interaction.value.message?.thread_ts ?? ts;
         kind = "action";
-        // A button that isn't one Toolroll made is answered with why, once the tap is proved to be the paired person's below.
         const button = readSlackButton(interaction.value);
         payload = button.ok ? { token: button.value.value } : { problem: button.issues.map(issue => issue.line).join("; ") };
         const tapped = actions[0];
@@ -102,8 +98,6 @@ export function receiveSlack(state, identity, type, raw, now) {
         !slackTs(thread) ||
         member === identity.bot)
         return false;
-    // A channel or private group is a room: accepted only while it follows a
-    // conversation, or for the `/team` words that make it follow one.
     const isRoom = !slackId(channel, "D");
     const admitted = admitChatEvent(state, "slack", identity.installation, { kind, member, channel, isRoom, payload });
     if (admitted === null)
@@ -127,7 +121,6 @@ const delivery = (options) => ({
     state: new ChatState(options.store, "slack"),
     label: "Slack",
     member: (member, channel) => slackMember(options.api, options.identity, member, channel),
-    // Slack shows bots no typing indicator; the 👀 goes at arrival (slackAckHooks) and the live message shows the rest.
     ...(options.liveReplies ? { live: (event) => slackLive(options, event, liveSpacingOf(options.liveReplies)) } : {}),
 });
 export const processSlackEvent = (options) => processChatEvent(delivery(options));
@@ -153,11 +146,9 @@ export function slackBlocks(text, buttons = []) {
         blocks.push({ type: "actions", elements: buttons });
     return blocks;
 }
-/** The lead's reply as mrkdwn sections: no header block, so its first line stays an ordinary line. */
 export function slackVoiceBlocks(mrkdwn, buttons = []) {
     const blocks = split(mrkdwn).map((part) => ({
         type: "section",
-        // verbatim: Slack never turns words of the reply into a mention, a channel or a link (renderReply escapes the rest).
         text: { type: "mrkdwn", text: part, verbatim: true },
     }));
     if (buttons.length)
@@ -223,7 +214,6 @@ export async function deliverSlackPart(options) {
             state.dropPart(row.id, "Connected projects changed");
             return true;
         }
-        // A screenshot sent with a result goes in that result's thread once its message is placed, and waits until then.
         const result = content.shot?.follows == null ? null : state.part(content.shot.follows);
         if (result !== null && !slackTs(result.message) && result.state === "pending") {
             state.holdPart(row.id, shotWaitsUntil(result.next_at, now));
@@ -263,7 +253,6 @@ export async function deliverSlackPart(options) {
                 if (!verifyResultImage(store, options.evidenceRoot, repos, content.image)
                     .ok)
                     throw new SlackError("Screenshot evidence changed before sharing");
-                // A lost completion response is reconciled against Slack's file receipt.
                 if (row.uncertain && file) {
                     const remote = object((await options.api("files.info", { file })).file), shares = object(object(remote.shares).private);
                     const receipts = Array.isArray(shares[destination])
@@ -349,7 +338,6 @@ export async function deliverSlackPart(options) {
         }
         else
             buttons = [
-                // A flow decision (v88): Approve / Edit / Send back, then the link.
                 ...(content.flow || content.choose || content.note
                     ? chatFlowButtons(state, row.id, now).map((one) => ({
                         type: "button",
@@ -359,7 +347,6 @@ export async function deliverSlackPart(options) {
                         ...(one.action === "approve" ? { style: "primary" } : {}),
                     }))
                     : []),
-                // A subagent's question (v93): its options, then "Answer in words".
                 ...(content.question
                     ? chatQuestionButtons(state, row.id, now).map((one) => ({
                         type: "button",
@@ -368,7 +355,6 @@ export async function deliverSlackPart(options) {
                         value: one.token,
                     }))
                     : []),
-                // The lead's question to its owner: its options, then "Something else".
                 ...(content.ask
                     ? chatAskButtons(state, row.id, now).map((one) => ({
                         type: "button",
@@ -377,16 +363,13 @@ export async function deliverSlackPart(options) {
                         value: one.token,
                     }))
                     : []),
-                // A result's, plan's, failure's or pull request's own buttons (chat-decide.ts): its acts, then its links.
                 ...(content.decide?.rows.flat() ?? []).flatMap((one, index) => "token" in one
                     ? [{ type: "button", text: { type: "plain_text", text: one.label }, action_id: `toolroll_decide_${index}`, value: one.token, ...(index === 0 ? { style: "primary" } : {}) }]
                     : linkButton(options.origin(), one.link).map(button => ({ ...button, action_id: `toolroll_link_${index + 10}` }))),
                 ...linkButton(options.origin(), content.link),
-                // [Look first] beside [Merge] or [Accept and finish]: each button's own action id.
                 ...(content.also ?? []).flatMap((one, index) => linkButton(options.origin(), one).map(button => ({ ...button, action_id: `toolroll_link_${index + 2}` }))),
             ];
         const target = content.edit ?? row.message;
-        // The lead's own reply goes out in Slack's mrkdwn (bold anchors, labelled links); everything else stays plain.
         const voiced = content.voice === true && !content.proposal && !content.image ? renderReply(text, "slack") : null;
         const args = {
             channel: destination,
@@ -401,7 +384,6 @@ 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
@@ -423,15 +405,12 @@ export async function deliverSlackPart(options) {
             state.dropPart(row.id, error.message);
             return true;
         }
-        // No permission to upload files here: one plain line instead of the result's screenshots.
         const saved = readChatPart(row.payload), content = saved.ok ? saved.value : null;
-        // The live message the reply was to replace is gone (deleted, or too old to edit): the reply goes out as a new one.
         if (content?.edit !== undefined && error instanceof SlackError && SLACK_UNEDITABLE.has(error.code) && isLiveMessage(state, row.event, content.edit)) {
             const { edit: _edit, ...asNew } = content;
             state.repaint(row.id, asNew);
             return true;
         }
-        // Slack refused the card's blocks: the part's own plain text goes instead, so the message is never lost.
         if (content?.rich && error instanceof SlackError && SLACK_REFUSED_BLOCKS.has(error.code)) {
             state.repaint(row.id, withoutCard(content));
             return true;
@@ -451,12 +430,9 @@ export async function deliverSlackPart(options) {
         return true;
     }
 }
-/** A live message's exact payload (§3.2): the rendered mrkdwn as the top-level text and as verbatim sections, every
- * field sent on every edit, nothing parsed, linked or unfurled, no buttons. */
 export function slackLivePayload(channel, mrkdwn) {
     return { channel, text: mrkdwn, blocks: slackVoiceBlocks(mrkdwn), mrkdwn: true, parse: "none", link_names: false, unfurl_links: false, unfurl_media: false };
 }
-/** The live message for one owner message, in its thread (where the reply goes). */
 export function slackLive(options, event, spacingMs) {
     return {
         platform: "slack",
@@ -477,7 +453,6 @@ export function slackLive(options, event, spacingMs) {
         uncertain: error => !(error instanceof SlackError) || error.uncertain,
     };
 }
-/** The 👀 on the owner's message (reactions:write). An install without that scope is asked at most once a minute, quietly. */
 export function slackAckHooks(options) {
     const code = (error) => error instanceof SlackError ? error.code : "";
     return {

package/dist/slack-settings.js

@@ -6,7 +6,6 @@ import { ACK_REFUSED_META } from "./chat-live.js";
 import { notice } from "./server/kit.js";
 export function slackSettingsHtml(store, dir, options = {}) {
     const credentials = loadSlackCredentials(dir);
-    // Slack answered "missing scope" to the 👀: an app installed before reactions:write needs one reinstall.
     const reinstall = credentials !== null && new ChatState(store, "slack").meta(credentials.installation, ACK_REFUSED_META) !== null;
     return chatSettingsHtml(store, dir, options, {
         provider: "slack",

package/dist/slack-socket.js

@@ -1,10 +1,5 @@
-/**
- * The Socket Mode client, apart from the follower so the Slack SDK loads only
- * once Slack is set up (slack.ts imports this when it finds credentials).
- */
 import { SocketModeClient } from "@slack/socket-mode";
 export { LogLevel } from "@slack/socket-mode";
-/** The bot and socket tokens must belong to the same app, including after reconnect. */
 export class ToolrollSlackSocket extends SocketModeClient {
     expectedApp = "";
     wrongApp = () => { };

package/dist/slack.js

@@ -1,4 +1,3 @@
-/** One leased Socket Mode connection, hosted by the ordinary worker. */
 import { randomBytes } from "node:crypto";
 import { abortablePause, workChatQueue } from "./chat-follow.js";
 import { loadSlackCredentials, slackApi } from "./slack-api.js";
@@ -26,9 +25,7 @@ export async function followSlack(options) {
                 state.owns(credentials.installation, owner));
         };
         const problem = (text) => state.setProblem(credentials.installation, owner, text);
-        // The SDK loads once Slack is set up, not with every command that could host the follower.
         const { ToolrollSlackSocket, LogLevel } = await import("./slack-socket.js");
-        // SDK log output can include envelopes/tokens. Only fixed status phrases are saved.
         const client = new ToolrollSlackSocket({
             appToken: credentials.appToken,
             autoReconnectEnabled: true,
@@ -75,7 +72,6 @@ export async function followSlack(options) {
             problem("Reconnecting to Slack…");
         });
         client.on("error", () => problem("Slack connection failed. Check the app tokens and reconnect."));
-        // The 👀 on each owner message as it arrives, beside the queue (a turn there can take a minute).
         const api = slackApi(credentials.botToken);
         const acks = runChatAcks({ state, installation: credentials.installation, owner, current: () => same() && connected,
             hooks: slackAckHooks({ api }), same, signal: options.signal });

package/dist/sleep.js

@@ -1,2 +1 @@
-/** Wait `ms` milliseconds on the global timer (so fake timers in tests still drive it). */
 export const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));

package/dist/source-key.js

@@ -1,17 +1,8 @@
-/**
- * The key a per-source budget counts under. One IPv6 subscriber is usually handed a whole /64, so keying by the full
- * address would give one caller 2^64 fresh budgets: a native IPv6 address counts as its /64 (`2001:db8:1:2::/64`),
- * however it is spelled. IPv4 stays exact, and an IPv4-mapped IPv6 address (`::ffff:203.0.113.5`) is that IPv4 address.
- * `::1` stays itself, so this computer is never pooled with anything else. The trusted proxy's `fwd:` marker is kept,
- * and anything that isn't an address ("unknown", a tenant id) is returned unchanged.
- */
 const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
-/** The eight 16-bit groups of an IPv6 address (brackets and a zone ignored), or null when it isn't one. */
 function ipv6Groups(text) {
     let bare = text.trim().replace(/^\[(.*)\]$/, "$1").replace(/%.*$/, "").toLowerCase();
     if (!bare.includes(":") || !/^[0-9a-f:.]+$/.test(bare))
         return null;
-    // An embedded IPv4 tail is two groups.
     const tail = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(bare);
     if (tail !== null) {
         if (!IPV4.test(tail[2]))
@@ -31,7 +22,6 @@ function ipv6Groups(text) {
         return null;
     return [...head, ...Array(halves.length === 2 ? missing : 0).fill("0"), ...rest].map(group => parseInt(group, 16));
 }
-/** The budget key for one address, as described above. */
 export function sourceKey(source) {
     if (source.startsWith("fwd:"))
         return `fwd:${sourceKey(source.slice(4))}`;

package/dist/spend-report.js

@@ -12,15 +12,11 @@ const usdMicro = (value) => {
     const usd = reportedCostUsdOf(typeof value === "number" ? value : value === null || value === undefined ? null : Number(value));
     return usd === null ? null : Math.round(usd * 1_000_000);
 };
-/** A charge on work that isn't measured API dollars must be a positive saved amount; a zero there proves nothing. */
 const chargeOf = (amount, microusd, basis) => microusd === null || (amount?.kind !== "api" && microusd <= 0) ? null : { microusd, basis };
-/** Every piece of work in [from, to), one row each. */
 export function spendRows(db, from, to) {
     const rows = [];
     const subagentOf = subagentFilers(db);
     const filerOf = filersOf(db);
-    // A task's project as its newest record names it. task_ref's index leads with its backend, so the lookup walks the
-    // few backends (each step an index seek) instead of scanning every task, once per task.
     const backends = db.prepare(`WITH RECURSIVE b(x) AS (SELECT (SELECT MIN(backend) FROM task_ref) UNION ALL SELECT (SELECT MIN(backend) FROM task_ref WHERE backend > b.x) FROM b WHERE b.x IS NOT NULL)
     SELECT x FROM b WHERE x IS NOT NULL`).all().map(row => String(row["x"]));
     const repoOfTask = backends.length === 0 ? null
@@ -31,7 +27,6 @@ export function spendRows(db, from, to) {
             taskRepos.set(taskId, repoOfTask === null ? null : text(repoOfTask.get(...backends, taskId)?.["repo"]));
         return taskRepos.get(taskId) ?? null;
     };
-    // Runs: the columns runAccounting reads, with their task's project and filer.
     for (const row of db.prepare(`SELECT run.id, run.task_ref, run.role, run.provider, run.model, run.model_reported, run.cost_usd, run.started_at, run.billing_basis, run.cost_unknown,
       r.external_id AS task, r.repo, r.filed_by, r.filed_by_kind, r.revision_of, s.microusd, s.source, s.billing
     FROM run JOIN task_ref r ON r.id = run.task_ref LEFT JOIN run_spend s ON s.run = run.id
@@ -40,13 +35,11 @@ export function spendRows(db, from, to) {
         const basis = row["billing_basis"] === "evidence" || row["billing_basis"] === "default" ? row["billing_basis"] : null;
         const costUnknown = Number(row["cost_unknown"] ?? 1) !== 0;
         const amount = runAmountOf({ billing: settledBilling, spendMicrousd: count(row["microusd"]), costUsd: count(row["cost_usd"]), basis, costUnknown });
-        // Only the run's own evidence proves its billing; a guess (`default`) or no basis at all is unproved.
         const billing = basis === "evidence" && settledBilling !== null ? settledBilling : "unproved";
         let charge = null;
         if (billing !== "subscription") {
             const settled = micro(row["microusd"]);
             if (settled !== null && (row["source"] === "reported" || row["source"] === "estimated")) {
-                // A run whose cost wasn't reported holds its cap in cost_usd, settled as "reported": that is a conservative estimate.
                 charge = chargeOf(amount, settled, billing === "unproved" || costUnknown || row["source"] === "estimated" ? "estimated" : "reported");
             }
             else {
@@ -63,7 +56,6 @@ export function spendRows(db, from, to) {
             provider: String(row["provider"]), modelChosen: text(row["model"]), modelReported: text(row["model_reported"]), billing, amount, charge,
         });
     }
-    // One chat request (fleet chat, or one request of a lead turn), as chatTurnAccounting reads it.
     const chatRequest = (row) => {
         const provider = String(row["provider"]);
         const reportedCostUsd = count(row["reported_cost_usd"]);
@@ -71,10 +63,8 @@ export function spendRows(db, from, to) {
         const unknownSpend = Number(row["unknown_spend"]) === 1;
         const amount = chatTurnAmountOf({ provider, settledMicrousd: count(row["settled_microusd"]), unknownSpend, reportedCostUsd, billingReported });
         if (DIRECT_CHAT.has(provider)) {
-            // Toolroll sent its own key: billed to it. The settlement is the charge (a held reservation when the cost is unknown).
             return { amount, billing: "api-key", charge: chargeOf(amount, micro(row["settled_microusd"]), unknownSpend ? "estimated" : "settled") };
         }
-        // A subscription harness settles at zero whatever it billed; its own events are the evidence.
         const billing = billingReported ?? "unproved";
         const reported = usdMicro(reportedCostUsd);
         return { amount, billing, charge: billing === "subscription" ? null : chargeOf(amount, reported, billing === "api-key" ? "reported" : "estimated") };
@@ -85,10 +75,7 @@ export function spendRows(db, from, to) {
         rows.push({ ref: `chat_turn:${Number(row["id"])}`, at: String(row["created_at"]), source: "chat", role: "chat", project: null, person: text(row["approver"]), subagent: null,
             taskId: null, runId: null, provider: String(row["provider"]), modelChosen: text(row["model"]), modelReported: text(row["model_reported"]), ...request });
     }
-    // A lead turn: each request at the turn's creation, and whatever the turn settled beyond its requests' charges (a held
-    // reservation) once, as an estimate attributed to the turn.
     const turns = new Map();
-    // The month's turns (mate_turn_created), each thread by its key; a task thread's project resolved once per task.
     let until = null;
     for (const row of db.prepare(`SELECT t.id, t.created_at, t.approver, t.settled_microusd, th.scope_kind, th.scope_key,
         MAX(t.deadline_at, COALESCE(t.finished_at, t.created_at), t.created_at) AS until
@@ -98,8 +85,6 @@ export function spendRows(db, from, to) {
         if (until === null || String(row["until"]) > until)
             until = String(row["until"]);
     }
-    // Their requests: written after their turn began and before it ended or ran out of time, so a bounded range of
-    // chat_turn_created (an hour's margin either side) holds every one; each is kept only when its turn is this month's.
     const stepsFrom = new Date(Date.parse(from) - 3_600_000).toISOString();
     const stepsUntil = until === null ? from : new Date(Date.parse(until) + 3_600_000).toISOString();
     for (const row of until === null ? [] : db.prepare(`SELECT c.id, c.mate_turn AS turn, c.provider, c.model, c.model_reported, c.settled_microusd, c.unknown_spend, c.reported_cost_usd, c.billing_reported
@@ -120,13 +105,10 @@ export function spendRows(db, from, to) {
         const held = turn.settled === null ? 0 : turn.settled - turn.charged;
         if (held <= 0)
             continue;
-        // The turn's uncertainty is counted once: by its unknown request when it has one, otherwise by this row.
         const amount = turn.unknown ? null : { kind: "unknown" };
         rows.push({ ref: `mate_turn:${id}`, at: turn.at, source: "lead", role: "lead", project: turn.project, person: turn.person, subagent: null, taskId: null, runId: null,
             provider: turn.provider ?? "lead", modelChosen: turn.model, modelReported: null, billing: "api-key", amount, charge: { microusd: held, basis: "estimated" } });
     }
-    // A subagent's turns and a flow's drafts run on this computer's Claude sign-in with no key from Toolroll: their billing
-    // stamp is a machine default, so it is unproved, and a cost they report is an estimate.
     for (const row of db.prepare(`SELECT t.id, t.at, t.subagent, t.model, t.cost_usd, m.repo FROM subagent_turn t JOIN subagent m ON m.id = t.subagent
       WHERE t.at >= ? AND t.at < ? ORDER BY t.id`).all(from, to)) {
         const amount = { kind: "unknown" };
@@ -140,7 +122,6 @@ export function spendRows(db, from, to) {
             taskId: null, runId: null, provider: String(row["provider"]), modelChosen: text(row["model"]), modelReported: null, billing: "unproved",
             amount, charge: chargeOf(amount, usdMicro(row["cost_usd"]), "estimated") });
     }
-    // A flow's Sort step asks Jev on OpenRouter with Toolroll's key: its reported cost, or unknown.
     for (const row of db.prepare(`SELECT fs.card, fs.entry, fs.stage, fs.started_at AS at, json_extract(fs.decision_json, '$.cost') AS cost, json_extract(fs.decision_json, '$.model') AS model, f.repo
       FROM flow_step_run fs JOIN flow_card c ON c.id = fs.card JOIN flow f ON f.id = c.flow
       WHERE fs.kind = 'sort' AND fs.decision_json IS NOT NULL AND fs.started_at >= ? AND fs.started_at < ? ORDER BY fs.started_at, fs.card, fs.entry`).all(from, to)) {
@@ -149,9 +130,6 @@ export function spendRows(db, from, to) {
         rows.push({ ref: `flow_step_run:${Number(row["card"])}:${Number(row["entry"])}:${String(row["stage"])}`, at: String(row["at"]), source: "sort", role: "flow", project: text(row["repo"]), person: null, subagent: null,
             taskId: null, runId: null, provider: "openrouter", modelChosen: text(row["model"]), modelReported: null, billing: "api-key", amount, charge: chargeOf(amount, cost, "reported") });
     }
-    // Evals, from their own records: one row per provider invocation, kinds kept apart; a campaign whose spending was
-    // left unknown adds one unknown. Never counted toward a limit, so never a charge.
-    // The month's attempts first, then each one's invocations through their (attempt, world_ref) key.
     for (const row of db.prepare(`SELECT i.id, i.amount, i.api_microusd, i.subscription_microusd, i.model_reported, a.started_at, a.model_pinned, c.started_by
       FROM eval_attempt a CROSS JOIN eval_invocation i ON i.attempt = a.id JOIN eval_campaign c ON c.id = a.campaign
       WHERE a.started_at >= ? AND a.started_at < ? ORDER BY i.id`).all(from, to)) {
@@ -187,10 +165,7 @@ function add(line, row) {
     if (amount?.kind === "unknown")
         line.unknown++;
 }
-/** A floating choice (an alias such as `opus`, or the CLI's default) names no version: it has no digit. */
 const floating = (model) => !/\d/.test(model);
-/** The model a row ran on, in words: the reported model; a floating choice beside what it ran as (no verdict); the
- * chosen model "not reported" when the provider said nothing. */
 export function modelLabel(row) {
     const chosen = row.modelChosen === null || row.modelChosen === "" ? null : row.modelChosen;
     if (row.modelReported === null)
@@ -199,9 +174,7 @@ export function modelLabel(row) {
         return row.modelReported;
     return floating(chosen) ? `floating choice ${chosen} → ${row.modelReported}` : `${row.modelReported} (chose ${chosen})`;
 }
-/** What a row ran on, for grouping: the reported model; the chosen one, "not reported", when the provider said nothing. */
 const ranOn = (row) => `${row.provider} · ${row.modelReported ?? `${row.modelChosen === null || row.modelChosen === "" ? "default" : row.modelChosen} (not reported)`}`;
-/** The model breakdown, grouped by the model the work ran on; how it was chosen is detail on the line. */
 function byModel(rows) {
     const lines = new Map();
     for (const row of rows) {
@@ -216,7 +189,6 @@ function byModel(rows) {
     return sortLines([...lines.values()]);
 }
 const sortLines = (lines) => lines.sort((a, b) => b.apiMicrousd - a.apiMicrousd || b.estimatedMicrousd - a.estimatedMicrousd || b.usageMicrousd - a.usageMicrousd || b.count - a.count || a.key.localeCompare(b.key));
-/** The month's totals, breakdowns and most expensive runs, from `spendRows`. Pure. */
 export function spendReport(rows, top = 10) {
     const totals = empty("");
     const by = (keyOf) => {
@@ -245,7 +217,6 @@ export function spendReport(rows, top = 10) {
         topRuns,
     };
 }
-/** One CSV row per piece of work, the same rows the page adds up. */
 export function spendReportCsv(rows, subagentNames) {
     const cell = (value) => {
         const value_ = value === null || value === undefined ? "" : String(value);

package/dist/spend-ui.js

@@ -1,10 +1,3 @@
-/**
- * The Spend page (docs/plans/spend-dashboard.md, slice 1), in the kit's Settings frame (group "spend"): the monthly
- * limits first (the one that needs you on top), then what agent work cost in a month, with API dollars, plan usage
- * and unknown cost kept apart and never added together, broken down by project and model (and, on demand, role,
- * person and the costliest runs), the plan windows, and what isn't recorded here. An instance operator's page.
- * A limit changes in place: Edit limit opens its form under the row (`?edit=<target>`), saved with a step-up.
- */
 import { html, postForm } from "./html.js";
 import { approvalAsk, termsOf } from "./design/kit.js";
 import { acts, btn, chip, disclose, dock, empty, field, input, note, notice, segLinks, settingsShell } from "./server/kit.js";
@@ -12,7 +5,6 @@ import { budgetLabel, usd } from "./spend.js";
 import { runHref, taskHref } from "./server/http.js";
 import { notEnoughWords, pricesWords, sideWords, SAVINGS_LABEL } from "./route-savings.js";
 const projectName = (repo) => repo.split("/").filter(Boolean).pop() ?? repo;
-/** The page's own layout: the limit rows and meters, the summary figures and the quiet bars. Colour from tokens only. */
 export const SPEND_CSS = `.spend{display:grid;gap:24px;min-width:0}.spend-sec{display:grid;gap:0}.spend-sec .k-secthead{margin-bottom:0}.spend-sec .k-secthead small{font-weight:400;color:var(--so-muted);font-size:12.5px}` +
     `.spend-lim{display:grid;gap:8px;padding:12px 0;border-bottom:1px solid var(--so-line)}.spend-lim-h{display:grid;grid-template-columns:minmax(0,1fr) auto 124px;gap:12px;align-items:center}` +
     `.spend-lim-l{display:grid;gap:2px;min-width:0}.spend-lim-t{font-weight:500;display:inline-flex;align-items:center;gap:8px;flex-wrap:wrap;overflow-wrap:anywhere}.spend-lim-x{font-size:12.5px;color:var(--so-muted)}` +
@@ -31,7 +23,6 @@ export const SPEND_CSS = `.spend{display:grid;gap:24px;min-width:0}.spend-sec{di
     `@media(max-width:760px){.spend-lim-h{grid-template-columns:minmax(0,1fr) auto}.spend-lim-a{grid-column:1/-1}.spend-lim-a .k-btn{width:100%}.spend-sum{grid-template-columns:minmax(0,1fr)}` +
     `.spend-sum>div+div{border-left:0;border-top:1px solid var(--so-line);padding-left:0}.spend-bar{grid-template-columns:minmax(0,120px) minmax(0,1fr) 68px;gap:8px;font-size:12.5px}` +
     `.spend-edit-row .k-field{flex:1 1 100%}.spend .k-btn.k-btn-primary.k-docked{display:none}}` +
-    // Suggestions and rules (results-routing slice 4): each rule's two sides, side by side; stacked on a phone.
     `.spend-rr{display:grid;gap:10px;padding:14px 0;border-bottom:1px solid var(--so-line);min-width:0}.spend-rr-h{display:flex;flex-wrap:wrap;align-items:center;gap:6px 10px;min-width:0}` +
     `.spend-rr-t{font-weight:500;overflow-wrap:anywhere;min-width:0}.spend-rr-x{font-size:12.5px;color:var(--so-muted);overflow-wrap:anywhere}` +
     `.spend-rr-g{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.spend-rr-s{display:grid;gap:4px;align-content:start;min-width:0;padding:12px;border:1px solid var(--so-line);border-radius:8px}` +
@@ -42,7 +33,6 @@ const ROLE_WORDS = {
     builder: "Builds", repair: "Repairs", planner: "Plans", reviewer: "Reviews", scout: "Scouting",
     lead: "Lead chat", chat: "Chat", subagent: "Subagents", flow: "Flows", evals: "Evals",
 };
-/** What this page doesn't record, in plain words (docs/plans/spend-dashboard.md §2.2). */
 export const NOT_COUNTED = [
     "Sizing a new task (Claude or OpenRouter)",
     "Memory checks that read finished chat sessions",
@@ -50,22 +40,17 @@ export const NOT_COUNTED = [
     "A flow draft that failed",
     "A Sort step that failed before saving its answer",
 ];
-/** Dollars for the page: a positive amount under a cent reads "<$0.01", never a false $0. */
 export const money = (microusd) => microusd > 0 && microusd < 10_000 ? "<$0.01" : usd(microusd);
 const each = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 const monthWords = (name, style = "long") => new Intl.DateTimeFormat("en-US", { month: style, year: "numeric", timeZone: "UTC" }).format(new Date(`${name}-01T00:00:00.000Z`));
-/** A limit Settings flags as Needs you: one that pauses work and is at or near its limit. */
 export const limitNeedsYou = (budget) => budget.hardStop && budget.percent >= 90;
-/** A line's plan usage in words: the reported usage, or that none was reported. Never $0 for unreported usage. */
 const usageWords = (line) => line.usageCount === 0 ? "—" : line.usageMicrousd > 0 ? `${money(line.usageMicrousd)}${line.usageUnreported > 0 ? ` + ${line.usageUnreported} not reported` : ""}` : "not reported";
-/** A line's unknown cost in words: how many, and a saved charge as an estimate. Never $0. */
 const unknownWords = (line) => {
     const counted = line.estimatedMicrousd > 0 ? `${money(line.estimatedMicrousd)} estimated` : "";
     return line.unknown > 0 ? `${line.unknown}${counted === "" ? "" : ` · ${counted}`}` : counted === "" ? "—" : counted;
 };
 const apiWords = (line) => line.apiMicrousd > 0 ? money(line.apiMicrousd) : "—";
 const sec = (id, title, state, body, attrs = "") => html `<section class="k-sec spend-sec" aria-labelledby="spend-${id}"${attrs}><div class="k-secthead"><h3 id="spend-${id}">${title}${state ? html ` <small>· ${state}</small>` : ""}</h3></div>${body}</section>`;
-/** A breakdown as quiet bars of API dollars; plan usage and unknown cost stay on the line, never added in. */
 function bars(head, lines, name, max, top = 12, detail = () => "") {
     const rows = lines.slice(0, top).map(line => {
         const sub = [detail(line), line.usageCount > 0 ? `plan usage ${usageWords(line)}` : "", line.unknown > 0 || line.estimatedMicrousd > 0 ? `unknown ${unknownWords(line)}` : ""].filter(Boolean).join(" · ");
@@ -78,8 +63,6 @@ function bars(head, lines, name, max, top = 12, detail = () => "") {
 <div class="spend-bar tot" role="row"><span role="cell">Total</span><span role="cell"></span><span class="spend-bar-v" role="cell">${total > 0 ? money(total) : "—"}</span></div></div>`;
 }
 const editHref = (target, month, current) => `/spend?${month === current ? "" : `month=${month}&`}edit=${encodeURIComponent(target)}`;
-/** The open limit form, under its row: amount and pause, validated next to the field before any password; saving
- * is a step-up (/spend/budget proves the password again, in the write). */
 function limitForm(row, edit, view, targets) {
     const id = `limit-${edit.target.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").slice(0, 60) || "new"}`;
     const facts = view.facts ?? { passwordless: false, remembered: false };
@@ -120,7 +103,6 @@ export function spendHtml(view, said) {
     const edit = view.edit ?? null;
     const saved = (view.budgets ?? []).map(budget => ({ target: `${budget.scope}:${budget.key}`, budget, spentMicrousd: budget.spentMicrousd,
         label: budget.scope === "installation" ? "Everything" : budget.scope === "project" ? projectName(budget.key) : budgetLabel(budget, budget.scope === "subagent" ? nameOfSubagent(budget.key) : undefined).replace(/'s$/, "") }));
-    // The limit Settings flags (Needs you) sits first; then the saved limits, then what has none yet.
     const rows = [...saved.filter(one => one.budget !== null && limitNeedsYou(one.budget)), ...saved.filter(one => one.budget === null || !limitNeedsYou(one.budget)), ...(view.unlimited ?? [])];
     const openFor = (row) => edit !== null && edit.target === row.target ? edit : null;
     const targets = view.targets ?? [];
@@ -163,8 +145,6 @@ export function spendHtml(view, said) {
 const sizeWords = (size) => size === "small" ? "Small tasks" : "Routine tasks";
 const dateWords = (iso) => new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", year: "numeric", timeZone: "UTC" }).format(new Date(iso));
 const STATUS_TONE = { active: "live", trialling: "live", paused: "needs" };
-/** One side of a rule's comparison: its model and window, the median API dollars a task (— when hidden), and the
- * completeness, plan usage, unknown cost and remediation counts, each on its own line. */
 function savingsSide(label, side) {
     const words = sideWords(side);
     const cap = (text) => text.charAt(0).toUpperCase() + text.slice(1);
@@ -182,9 +162,6 @@ function savingsRow(row) {
 ${row.enough ? "" : html `<p class="k-note" data-not-enough>${notEnoughWords(row)}</p>`}<p class="k-note" data-prices>${pricesWords(row)}</p>\
 <span><a class="k-link" href="${href}">${suggestion ? "Review in Models settings" : "Open Models settings"}</a></span></article>`;
 }
-/** Suggestions and rules (docs/plans/results-routing.md, slice 4): per project and size, each live or recently ended
- * rule or trial, and each standing suggestion, with what it observed over matched 90-day windows. Labelled "observed,
- * not a promise"; a median shows only from 5 API-priced results a side; unknown is "—", never $0. Read-only. */
 export function savingsSection(savings) {
     if (savings === null)
         return "";
@@ -199,8 +176,6 @@ export function savingsSection(savings) {
     const lead = html `<p class="k-note">Median API dollars a task, including revision and repair runs. Plan usage and unknown cost are counted apart, never added in. A median shows once each side has ${savings.minPriced} results priced in API dollars.</p>`;
     return sec("savings", "Suggestions and rules", state, html `${lead}${stale}${savings.rows.map(savingsRow)}`, html ` data-savings="rows"`);
 }
-/** Checks the amount next to its field before any password is asked or the form leaves the page; the server checks
- * it again. Remove skips it. */
 export function spendScript() {
     return `(function(){document.addEventListener("submit",function(e){var f=e.target;if(!f||!f.matches||!f.matches("form[data-spend-limit]"))return;
 var s=e.submitter;if(s&&s.hasAttribute("data-spend-remove"))return;var u=f.querySelector("[data-spend-usd]");if(!u)return;
@@ -208,7 +183,6 @@ var v=u.value.replace(/[$,\\s]/g,""),ok=/^\\d+$/.test(v)&&+v>=1&&+v<=10000000,er
 if(ok){u.removeAttribute("aria-invalid");if(err)err.textContent="";u.value=v;return;}
 e.preventDefault();u.setAttribute("aria-invalid","true");if(err)err.textContent="Use a whole number of dollars, at least $1, like 40. Nothing changed.";u.focus();},true);})();`;
 }
-/** One row per piece of spend, for a spreadsheet (the command line's `spend --csv`). */
 export function spendCsv(items, subagentNames) {
     const cell = (value) => {
         const text = value === null || value === undefined ? "" : String(value);