toolroll 0.5.0

package/dist/structured-output.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared structured-output recovery primitives for planner and reviewer.
+ *
+ * The normalizer is deliberately syntax-only. It may remove transport
+ * wrappers that carry no meaning; it never extracts a likely-looking object
+ * from prose, fills a field, truncates a note, changes an id, or chooses a
+ * judgement. Semantic repair belongs to the same agent session and remains
+ * subject to the phase's strict parser.
+ */
+import type { Store } from "./store.js";
+export declare const STRUCTURED_REPAIR_ATTEMPTS = 2;
+export declare const STRUCTURED_REPAIR_MAX_TURNS = 4;
+export declare const STRUCTURED_REPAIR_TIMEOUT_MS: number;
+/** Native parsing counts UTF-16 code units. A shorter writing target keeps
+ * notes concise without imposing a second, stricter transport contract. */
+export declare const REVIEW_OUTPUT_LIMITS: {
+    readonly comments: 40;
+    readonly criteria: 12;
+    readonly note: 500;
+    readonly path: 300;
+};
+export declare const REVIEW_NOTE_CODE_POINTS: number;
+export declare const REVIEW_NOTE_GUIDANCE: string;
+export type StructuredNormalization = {
+    text: string;
+    changed: boolean;
+    changes: readonly ("bom" | "whitespace" | "json-fence" | "json-string")[];
+};
+/** Strip only unambiguous, whole-payload wrappers. */
+export declare function normalizeStructuredJson(raw: string): StructuredNormalization;
+export type StructuredAttemptPhase = "planner" | "reviewer" | "builder-proof";
+/**
+ * Keep the exact emitted payload unless it contains a high-confidence secret
+ * shape, in which case the same line-redaction discipline as terminal diffs
+ * keeps the audit record useful without creating a second credential copy.
+ */
+export declare function storeStructuredAttempt(store: Store, root: string, logicalRunId: number, args: {
+    phase: StructuredAttemptPhase;
+    attempt: number;
+    authoredRunId: number;
+    raw: string | Buffer;
+    /** Exact source size when `raw` is an intentionally bounded prefix. */
+    sourceBytesOriginal?: number;
+    /**
+     * The exact bytes passed the phase parser and every eligibility gate the
+     * caller had checked when it captured them. This is never the workflow's
+     * final acceptance: custody, evidence bindings, or the atomic finalizer
+     * may still refuse them. The run's terminal outcome is that authority.
+     */
+    accepted: boolean;
+    normalized: boolean;
+    now: Date;
+}): number;
+/** JSON-quote parser errors so agent-authored ids/paths remain data. */
+export declare function validationErrorsJson(problems: readonly {
+    reason: string;
+    message?: string;
+}[]): string;

package/dist/structured-output.js

@@ -0,0 +1,103 @@
+/**
+ * Shared structured-output recovery primitives for planner and reviewer.
+ *
+ * The normalizer is deliberately syntax-only. It may remove transport
+ * wrappers that carry no meaning; it never extracts a likely-looking object
+ * from prose, fills a field, truncates a note, changes an id, or chooses a
+ * judgement. Semantic repair belongs to the same agent session and remains
+ * subject to the phase's strict parser.
+ */
+import { redactSecretLines, scanForSecrets, storeEvidence } from "./evidence.js";
+export const STRUCTURED_REPAIR_ATTEMPTS = 2;
+export const STRUCTURED_REPAIR_MAX_TURNS = 4;
+export const STRUCTURED_REPAIR_TIMEOUT_MS = 5 * 60_000;
+/** Native parsing counts UTF-16 code units. A shorter writing target keeps
+ * notes concise without imposing a second, stricter transport contract. */
+export const REVIEW_OUTPUT_LIMITS = { comments: 40, criteria: 12, note: 500, path: 300 };
+export const REVIEW_NOTE_CODE_POINTS = Math.floor(REVIEW_OUTPUT_LIMITS.note / 2);
+export const REVIEW_NOTE_GUIDANCE = `Keep each comment and criterion note to one concise finding and its evidence. Aim for ${REVIEW_NOTE_CODE_POINTS} characters or fewer; the hard limit is ${REVIEW_OUTPUT_LIMITS.note} UTF-16 units. Preserve the conclusion and any needed provenance; omit repeated rubric text.`;
+/** Strip only unambiguous, whole-payload wrappers. */
+export function normalizeStructuredJson(raw) {
+    let text = raw;
+    const changes = [];
+    if (text.startsWith("\uFEFF")) {
+        text = text.slice(1);
+        changes.push("bom");
+    }
+    const trimmed = text.trim();
+    const fenced = /^```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n```$/i.exec(trimmed);
+    // A pair of complete fenced blocks also matches the outer anchors above
+    // (the first opener and final closer). Never collapse that ambiguous
+    // payload into one: the strict phase parser should reject it and ask the
+    // author to emit one response. A fence marker inside JSON source cannot
+    // occur on its own line without making that JSON invalid, so this is a
+    // conservative false-negative rather than a semantic rewrite.
+    if (fenced !== null && !(fenced[1] ?? "").includes("```")) {
+        text = fenced[1] ?? "";
+        changes.push("json-fence");
+    }
+    else {
+        if (trimmed !== text)
+            changes.push("whitespace");
+        text = trimmed;
+    }
+    // Some harness/model pairs double-encode the complete JSON reply as one
+    // JSON string. Unwrap exactly one layer only when the decoded value is a
+    // string containing one object/array-shaped payload. No brace searching.
+    try {
+        const once = JSON.parse(text);
+        if (typeof once === "string") {
+            const candidate = once.trim();
+            // Shape alone is not enough: `"{not json}"` is content, not an
+            // unambiguous transport wrapper. Verify the decoded layer is itself a
+            // complete JSON object or array before removing the one string layer.
+            let decoded;
+            try {
+                decoded = JSON.parse(candidate);
+            }
+            catch {
+                decoded = null;
+            }
+            if (decoded !== null && typeof decoded === "object") {
+                text = candidate;
+                changes.push("json-string");
+            }
+        }
+    }
+    catch {
+        // The phase parser owns the useful error; normalization never guesses.
+    }
+    return { text, changed: changes.length > 0, changes };
+}
+/**
+ * Keep the exact emitted payload unless it contains a high-confidence secret
+ * shape, in which case the same line-redaction discipline as terminal diffs
+ * keeps the audit record useful without creating a second credential copy.
+ */
+export function storeStructuredAttempt(store, root, logicalRunId, args) {
+    const rawBytes = Buffer.isBuffer(args.raw) ? args.raw : Buffer.from(args.raw, "utf8");
+    const rawText = rawBytes.toString("utf8");
+    const hits = scanForSecrets(rawText);
+    const content = hits.length === 0 ? rawBytes : Buffer.from(redactSecretLines(rawText, hits), "utf8");
+    // `accepted: false` can mean strict validation, provider status, session
+    // identity, or another provenance gate rejected the bytes. Keep the
+    // evidence wording honest without pretending every refusal was a parser
+    // error; the run's typed reason records which gate failed.
+    // Do not call a pre-finalization candidate simply "accepted": this
+    // artifact must remain truthful if a later custody/binding transaction
+    // refuses it. Parser acceptance and final workflow acceptance are separate
+    // facts; the latter lives on the terminal run.
+    const normalization = args.normalized ? ", syntax normalized" : "";
+    const state = args.accepted
+        ? `parser accepted${normalization}; workflow pending`
+        : `not accepted${normalization}`;
+    return storeEvidence(store, root, logicalRunId, "structured-output", `${args.phase}-response-${args.attempt}.txt`, content, `${args.phase} response ${args.attempt} from run ${args.authoredRunId} (${state})`, args.now, {
+        redacted: hits.length > 0,
+        captureStatus: args.accepted ? "ok" : "failed",
+        sourceBytesOriginal: args.sourceBytesOriginal ?? rawBytes.length,
+    });
+}
+/** JSON-quote parser errors so agent-authored ids/paths remain data. */
+export function validationErrorsJson(problems) {
+    return JSON.stringify(problems.map(problem => ({ reason: problem.reason, ...(problem.message === undefined ? {} : { message: problem.message }) })), null, 2);
+}

package/dist/style-asset.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Only application-owned CSS belongs here. Never pass rendered HTML or
+ * session data: this asset is public, immutable and compressed. */
+export declare function styleAsset(css: string): {
+    path: string;
+    serve(request: IncomingMessage, response: ServerResponse): void;
+};

package/dist/style-asset.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { gzipSync } from "node:zlib";
+/** Only application-owned CSS belongs here. Never pass rendered HTML or
+ * session data: this asset is public, immutable and compressed. */
+export function styleAsset(css) {
+    const body = Buffer.from(css);
+    const digest = createHash("sha256").update(body).digest("hex");
+    const path = `/assets/workspace-${digest}.css`;
+    const zipped = gzipSync(body);
+    return {
+        path,
+        serve(request, response) {
+            const encodings = (request.headers["accept-encoding"] ?? "").split(",").map(value => {
+                const [name, ...params] = value.trim().toLowerCase().split(";");
+                const quality = params.find(p => p.trim().startsWith("q="));
+                return { name, q: quality === undefined ? 1 : Number(quality.trim().slice(2)) };
+            });
+            const gzip = encodings.find(e => e.name === "gzip") ?? encodings.find(e => e.name === "*");
+            const compressed = gzip !== undefined && gzip.q > 0 && gzip.q <= 1;
+            const bytes = compressed ? zipped : body;
+            const etag = `"${digest}${compressed ? "-gzip" : ""}"`;
+            const headers = {
+                "Content-Type": "text/css; charset=utf-8",
+                "Cache-Control": "public, max-age=31536000, immutable",
+                "Content-Security-Policy": "default-src 'none'",
+                "X-Content-Type-Options": "nosniff",
+                "Vary": "Accept-Encoding",
+                "ETag": etag,
+                ...(compressed ? { "Content-Encoding": "gzip" } : {}),
+            };
+            const matches = (request.headers["if-none-match"] ?? "").split(",").some(value => value.trim().replace(/^W\//, "") === etag || value.trim() === "*");
+            if (matches) {
+                response.writeHead(304, headers);
+                response.end();
+                return;
+            }
+            response.writeHead(200, { ...headers, "Content-Length": bytes.length });
+            response.end(request.method === "HEAD" ? undefined : bytes);
+        },
+    };
+}

package/dist/subscription-chat.d.ts

@@ -0,0 +1,46 @@
+import { type MateHistoryMessage, type MateProviderAnswer, type MateToolSchema } from "./converse.js";
+import { run, type ExecResult } from "./exec.js";
+import type { SubscriptionChatProviderId } from "./store.js";
+export type SubscriptionMateRequest = {
+    provider: SubscriptionChatProviderId;
+    /** `default` lets the authenticated harness choose its current default. */
+    model: string;
+    system: string;
+    dataDocument: string;
+    history: readonly MateHistoryMessage[];
+    tools: readonly MateToolSchema[];
+    timeoutMs: number;
+    /** The reply as it is written, cumulative, when the harness can stream it
+     * (Claude). Display only: the finished answer is still parsed whole. */
+    onText?: (text: string) => void;
+};
+export type SubscriptionMateRunner = (request: SubscriptionMateRequest) => Promise<{
+    ok: true;
+    answer: MateProviderAnswer;
+} | {
+    ok: false;
+    problem: string;
+}>;
+type CommandRunner = (file: string, args: readonly string[], options: Parameters<typeof run>[2]) => Promise<ExecResult>;
+/** The model-visible request. Tool results are already redacted by mateView. */
+export declare function composeSubscriptionMatePrompt(request: Omit<SubscriptionMateRequest, "provider" | "model" | "timeoutMs">): string;
+/** Strictly turn the harness's structured output into the provider-neutral answer. */
+export declare function parseSubscriptionMateAnswer(text: string, usage?: {
+    tokensIn?: unknown;
+    tokensOut?: unknown;
+}): {
+    ok: true;
+    answer: MateProviderAnswer;
+} | {
+    ok: false;
+    problem: string;
+};
+/** Production runner; injectable so tests never consume a subscription turn. */
+export declare function performSubscriptionMateRequest(request: SubscriptionMateRequest, runner?: CommandRunner): Promise<{
+    ok: true;
+    answer: MateProviderAnswer;
+} | {
+    ok: false;
+    problem: string;
+}>;
+export {};

package/dist/subscription-chat.js

@@ -0,0 +1,275 @@
+/**
+ * Subscription-backed transport for the mate.
+ *
+ * The direct API transport owns dollar reservations and native function
+ * calls. A cached Codex or Claude login has neither an API key nor a
+ * truthful dollar meter, so this adapter runs the local harness in a clean
+ * temporary directory and asks for the same tool-call envelope as strict
+ * structured JSON. The harness receives no repository path, no project
+ * instructions, no MCP servers, and no executable tool surface. Tool calls
+ * are still interpreted and executed by mate.ts, where every act remains a
+ * proposal that needs a human confirmation card.
+ */
+import { Buffer } from "node:buffer";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MATE_MAX_CALLS_PER_STEP, MATE_STEP_TEXT_CAP_BYTES, MATE_TOOL_CALL_CAP_BYTES, MATE_TOOL_CALL_ID_CAP_BYTES, strictJsonParse, tokenCount, } from "./converse.js";
+import { run } from "./exec.js";
+import { claudeStreamReader } from "./mate-progress.js";
+import { ALL_CREDENTIAL_ENV } from "./provider.js";
+import { claudeLimitsOf, noteLimits } from "./provider-limits.js";
+import { claudeBillingFrom } from "./spend.js";
+const RESPONSE_CAP_BYTES = 65_536;
+function outputSchema(tools) {
+    return {
+        type: "object",
+        properties: {
+            text: { type: "string", maxLength: MATE_STEP_TEXT_CAP_BYTES },
+            // With no tools offered there is nothing to name: an empty enum is not
+            // a valid schema, so the calls array is simply required to be empty.
+            calls: tools.length === 0 ? { type: "array", maxItems: 0 } : {
+                type: "array",
+                maxItems: MATE_MAX_CALLS_PER_STEP,
+                items: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", minLength: 1, maxLength: MATE_TOOL_CALL_ID_CAP_BYTES },
+                        name: { type: "string", enum: tools.map(tool => tool.name) },
+                        argumentsJson: { type: "string", maxLength: MATE_TOOL_CALL_CAP_BYTES },
+                    },
+                    required: ["id", "name", "argumentsJson"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["text", "calls"],
+        additionalProperties: false,
+    };
+}
+/** The model-visible request. Tool results are already redacted by mateView. */
+export function composeSubscriptionMatePrompt(request) {
+    return [
+        request.system,
+        "SUBSCRIPTION HARNESS PROTOCOL:",
+        "Do not use any harness tools or inspect the computer. The only current state is DATA and TOOL RESULTS below.",
+        "Return the required JSON object. To request a host tool, append {id, name, argumentsJson} to calls; argumentsJson is the JSON serialization of that tool's argument object.",
+        "The host validates and runs those calls, then gives you another step. When finished, return a non-empty text and an empty calls array.",
+        `AVAILABLE HOST TOOLS:\n${JSON.stringify(request.tools)}`,
+        `DATA:\n${request.dataDocument}`,
+        `CONVERSATION:\n${JSON.stringify(request.history)}`,
+    ].join("\n\n");
+}
+function exactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    return actual.length === keys.length && [...keys].sort().every((key, index) => actual[index] === key);
+}
+/** Strictly turn the harness's structured output into the provider-neutral answer. */
+export function parseSubscriptionMateAnswer(text, usage = {}) {
+    const parsed = strictJsonParse(Buffer.from(text, "utf8"), RESPONSE_CAP_BYTES, 8);
+    if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value)) {
+        return { ok: false, problem: parsed.ok ? "not-an-object" : parsed.problem };
+    }
+    const body = parsed.value;
+    if (!exactKeys(body, ["text", "calls"]) || typeof body["text"] !== "string" || !Array.isArray(body["calls"])) {
+        return { ok: false, problem: "wrong-shape" };
+    }
+    if (Buffer.byteLength(body["text"], "utf8") > MATE_STEP_TEXT_CAP_BYTES || body["calls"].length > MATE_MAX_CALLS_PER_STEP) {
+        return { ok: false, problem: "over-cap" };
+    }
+    const calls = [];
+    for (const raw of body["calls"]) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return { ok: false, problem: "bad-tool-call" };
+        const call = raw;
+        if (!exactKeys(call, ["id", "name", "argumentsJson"]))
+            return { ok: false, problem: "bad-tool-call" };
+        if (typeof call["id"] !== "string" || call["id"] === "" || Buffer.byteLength(call["id"], "utf8") > MATE_TOOL_CALL_ID_CAP_BYTES) {
+            return { ok: false, problem: "bad-tool-call" };
+        }
+        if (typeof call["name"] !== "string" || call["name"] === "" || call["name"].length > 64 || typeof call["argumentsJson"] !== "string") {
+            return { ok: false, problem: "bad-tool-call" };
+        }
+        const argumentsBytes = Buffer.from(call["argumentsJson"], "utf8");
+        if (argumentsBytes.byteLength > MATE_TOOL_CALL_CAP_BYTES)
+            return { ok: false, problem: "bad-tool-call" };
+        const args = strictJsonParse(argumentsBytes, MATE_TOOL_CALL_CAP_BYTES, 6);
+        if (!args.ok || typeof args.value !== "object" || args.value === null || Array.isArray(args.value))
+            return { ok: false, problem: "bad-tool-call" };
+        const normalized = { id: call["id"], name: call["name"], args: args.value };
+        if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > MATE_TOOL_CALL_CAP_BYTES)
+            return { ok: false, problem: "bad-tool-call" };
+        calls.push(normalized);
+    }
+    const tokensIn = typeof usage.tokensIn === "number" && tokenCount(usage.tokensIn) ? usage.tokensIn : 0;
+    const tokensOut = typeof usage.tokensOut === "number" && tokenCount(usage.tokensOut) ? usage.tokensOut : 0;
+    return { ok: true, answer: { text: body["text"], calls, tokensIn, tokensOut, reportedCostMicrousd: null } };
+}
+function codexOutput(stdout) {
+    let text = null;
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let completed = 0;
+    let invalid = false;
+    for (const line of stdout.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            invalid = true;
+            continue;
+        }
+        if (event === null || typeof event !== "object" || Array.isArray(event)) {
+            invalid = true;
+            continue;
+        }
+        if (event["type"] === "turn.failed")
+            invalid = true;
+        if (event["type"] === "item.completed") {
+            const item = event["item"];
+            if (item?.["type"] === "agent_message" && typeof item["text"] === "string") {
+                if (completed !== 0)
+                    invalid = true;
+                text = item["text"];
+            }
+        }
+        else if (event["type"] === "turn.completed") {
+            completed += 1;
+            const usage = event["usage"];
+            if (typeof usage?.["input_tokens"] === "number" && tokenCount(usage["input_tokens"]))
+                tokensIn = usage["input_tokens"];
+            if (typeof usage?.["output_tokens"] === "number" && tokenCount(usage["output_tokens"]))
+                tokensOut = usage["output_tokens"];
+        }
+    }
+    // A partial answer is not authority to run host tools. Process exit zero
+    // alone is insufficient; the harness must finish this one turn successfully.
+    return { text: !invalid && completed === 1 ? text : null, tokensIn, tokensOut };
+}
+function claudeOutput(stdout) {
+    const parsed = strictJsonParse(Buffer.from(stdout, "utf8"), RESPONSE_CAP_BYTES, 12);
+    if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value))
+        return { text: null, tokensIn: 0, tokensOut: 0 };
+    const body = parsed.value;
+    if (body["type"] !== "result" || body["subtype"] !== "success" || body["is_error"] !== false) {
+        return { text: null, tokensIn: 0, tokensOut: 0 };
+    }
+    const usage = body["usage"];
+    const tokensIn = typeof usage?.["input_tokens"] === "number" && tokenCount(usage["input_tokens"]) ? usage["input_tokens"] : 0;
+    const tokensOut = typeof usage?.["output_tokens"] === "number" && tokenCount(usage["output_tokens"]) ? usage["output_tokens"] : 0;
+    const structured = body["structured_output"];
+    if (typeof structured === "object" && structured !== null)
+        return { text: JSON.stringify(structured), tokensIn, tokensOut };
+    return { text: typeof body["result"] === "string" ? body["result"] : null, tokensIn, tokensOut };
+}
+/** The streamed run's closing `result` event: the same body the buffered
+ * `--output-format json` run prints. */
+function lastResultLine(stdout) {
+    const lines = stdout.split("\n");
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const line = lines[index].trim();
+        if (line === "")
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (typeof event === "object" && event !== null && event["type"] === "result")
+                return line;
+        }
+        catch { /* not an event line */ }
+    }
+    return "";
+}
+/** Production runner; injectable so tests never consume a subscription turn. */
+export async function performSubscriptionMateRequest(request, runner = run) {
+    const dir = mkdtempSync(join(tmpdir(), "standing-orders-mate-"));
+    try {
+        const prompt = composeSubscriptionMatePrompt(request);
+        const streaming = request.provider !== "codex-subscription" && request.onText !== undefined;
+        const schema = outputSchema(request.tools);
+        let command;
+        let args;
+        if (request.provider === "codex-subscription") {
+            const schemaFile = join(dir, "response-schema.json");
+            writeFileSync(schemaFile, JSON.stringify(schema), { mode: 0o600 });
+            command = "codex";
+            args = [
+                "exec", "--json", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--skip-git-repo-check",
+                "--sandbox", "read-only", "--output-schema", schemaFile,
+                "-c", 'approval_policy="never"', "-c", 'web_search="disabled"',
+                "-c", "features.shell_tool=false", "-c", "features.unified_exec=false",
+                "-c", "features.multi_agent=false", "-c", "features.skill_mcp_dependency_install=false",
+                "-c", "apps._default.enabled=false",
+                ...(request.model === "default" ? [] : ["--model", request.model]),
+                "-",
+            ];
+        }
+        else {
+            command = "claude";
+            args = [
+                // Streaming (someone is watching): the same answer, delivered as
+                // events whose final `result` line is the whole structured reply.
+                "-p", ...(streaming ? ["--output-format", "stream-json", "--verbose", "--include-partial-messages"] : ["--output-format", "json"]), "--json-schema", JSON.stringify(schema),
+                "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
+                "--permission-prompts", "none", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}',
+                ...(request.model === "default" ? [] : ["--model", request.model]),
+            ];
+        }
+        const result = await runner(command, args, {
+            cwd: dir,
+            stdin: prompt,
+            timeoutMs: request.timeoutMs,
+            // Events repeat the answer (deltas, the message, the result line).
+            maxBuffer: streaming ? RESPONSE_CAP_BYTES * 16 : RESPONSE_CAP_BYTES,
+            omitEnv: ALL_CREDENTIAL_ENV,
+            processGroup: true,
+            ...(streaming ? { onStdout: claudeStreamReader(request.onText) } : {}),
+        });
+        if (result.timedOut)
+            return { ok: false, problem: "timeout" };
+        if (result.notFound)
+            return { ok: false, problem: "not-found" };
+        // v105: a streamed Claude turn says its plan's usage windows, and (once it answered) how this computer's Claude bills
+        // with no key from us: the chat ran with every key left out.
+        if (command === "claude" && streaming) {
+            const seen = { keySource: null, model: null, planWindows: false };
+            let answered = false;
+            for (const line of result.stdout.split("\n")) {
+                if (!line.includes('"rate_limit_event"') && !line.includes('"apiKeySource"') && !line.includes('"type":"result"'))
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const reading = claudeLimitsOf(event);
+                if (reading !== null) {
+                    seen.planWindows = true;
+                    noteLimits(reading);
+                }
+                else if (event["type"] === "system" && event["subtype"] === "init") {
+                    seen.keySource = typeof event["apiKeySource"] === "string" ? event["apiKeySource"] : null;
+                    seen.model = typeof event["model"] === "string" ? event["model"] : null;
+                }
+                else if (event["type"] === "result")
+                    answered = true;
+            }
+            const billing = answered ? claudeBillingFrom(seen) : null;
+            if (billing !== null)
+                noteLimits({ provider: "claude", plan: null, windows: [], partial: true, billing });
+        }
+        if (result.code !== 0)
+            return { ok: false, problem: `status-${result.code}` };
+        const output = request.provider === "codex-subscription" ? codexOutput(result.stdout) : claudeOutput(streaming ? lastResultLine(result.stdout) : result.stdout);
+        if (output.text === null)
+            return { ok: false, problem: "malformed-reply" };
+        return parseSubscriptionMateAnswer(output.text, output);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/summary.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A window of runs, tallied — one arithmetic, shared by the CLI brief and
+ * the web console so the two can never disagree about what a stretch of
+ * unattended work cost.
+ *
+ * Economics are measured, never asserted: every provider spawn stamps its
+ * run before spending, so `invoked` is the complete population; `measured`
+ * is the subset whose envelopes actually reported cost, and the gap between
+ * them is named by callers instead of summed as zero.
+ */
+import type { Run } from "./store.js";
+export type RunTally<T extends Run> = {
+    built: T[];
+    failed: T[];
+    refused: T[];
+    /** Runs that never finished — the process died with them. Also an answer. */
+    cutDown: T[];
+    invoked: T[];
+    measured: T[];
+    spend: number;
+    tokens: number;
+};
+export declare function tally<T extends Run>(runs: T[]): RunTally<T>;
+/**
+ * Provider harnesses do not all mean the same thing when they report a
+ * dollar figure. Claude Code includes `total_cost_usd` in its result even
+ * when it authenticated with a paid membership. In that case the number is
+ * useful as an API-price equivalent for comparing work, but it is not API
+ * key spend and must never be presented as a separate charge.
+ */
+export declare function runCostWords(run: Pick<Run, "authMode" | "costUsd" | "tokensIn" | "tokensOut">, live?: boolean): string;
+/** The spend line, one wording everywhere. */
+export declare function spendLine(summary: RunTally<Run>): string;

package/dist/summary.js

@@ -0,0 +1,71 @@
+/**
+ * A window of runs, tallied — one arithmetic, shared by the CLI brief and
+ * the web console so the two can never disagree about what a stretch of
+ * unattended work cost.
+ *
+ * Economics are measured, never asserted: every provider spawn stamps its
+ * run before spending, so `invoked` is the complete population; `measured`
+ * is the subset whose envelopes actually reported cost, and the gap between
+ * them is named by callers instead of summed as zero.
+ */
+export function tally(runs) {
+    const invoked = runs.filter(one => one.providerStartedAt !== null);
+    const measured = invoked.filter(one => one.costUsd !== null);
+    return {
+        built: runs.filter(one => one.outcome === "built" || one.outcome === "no-change"),
+        failed: runs.filter(one => one.outcome === "failed"),
+        refused: runs.filter(one => one.outcome === "refused"),
+        cutDown: runs.filter(one => one.outcome === null),
+        invoked,
+        measured,
+        spend: measured.reduce((sum, one) => sum + (one.costUsd ?? 0), 0),
+        tokens: invoked
+            .filter(one => one.tokensOut !== null)
+            .reduce((sum, one) => sum + (one.tokensOut ?? 0) + (one.tokensIn ?? 0), 0),
+    };
+}
+/**
+ * Provider harnesses do not all mean the same thing when they report a
+ * dollar figure. Claude Code includes `total_cost_usd` in its result even
+ * when it authenticated with a paid membership. In that case the number is
+ * useful as an API-price equivalent for comparing work, but it is not API
+ * key spend and must never be presented as a separate charge.
+ */
+export function runCostWords(run, live = false) {
+    if (run.authMode === "subscription") {
+        return run.costUsd === null
+            ? live
+                ? "subscription usage in progress"
+                : "subscription · no API-key spend"
+            : `subscription · $${run.costUsd.toFixed(2)} API-price equivalent (not an API charge)`;
+    }
+    if (run.costUsd !== null) {
+        return run.authMode === "api-key" ? `$${run.costUsd.toFixed(2)} API-key usage` : `$${run.costUsd.toFixed(2)}`;
+    }
+    return run.tokensIn !== null || run.tokensOut !== null
+        ? "dollar cost unmeasured — this provider reports tokens, not prices"
+        : live
+            ? "usage in progress"
+            : "unmeasured";
+}
+/** The spend line, one wording everywhere. */
+export function spendLine(summary) {
+    if (summary.invoked.length === 0)
+        return "nothing — no provider was invoked";
+    const subscription = summary.measured.filter(one => one.authMode === "subscription");
+    const metered = summary.measured.filter(one => one.authMode !== "subscription");
+    const subscriptionEquivalent = subscription.reduce((sum, one) => sum + (one.costUsd ?? 0), 0);
+    const meteredSpend = metered.reduce((sum, one) => sum + (one.costUsd ?? 0), 0);
+    if (subscription.length > 0) {
+        const money = [
+            ...(metered.length > 0 ? [`$${meteredSpend.toFixed(4)} API-key usage`] : []),
+            `$${subscriptionEquivalent.toFixed(4)} API-price equivalent from ${subscription.length} subscription invocation(s) — not an API charge`,
+        ].join(" · ");
+        const unmeasured = summary.invoked.length - summary.measured.length;
+        return `${money} · ${summary.tokens.toLocaleString()} tokens${unmeasured === 0 ? "" : ` · ${unmeasured} invocation(s) unmeasured`}`;
+    }
+    const dollars = `$${summary.spend.toFixed(4)}`;
+    return summary.measured.length === summary.invoked.length
+        ? `${dollars} · ${summary.tokens.toLocaleString()} tokens, measured across all ${summary.invoked.length} invocation(s)`
+        : `${dollars} measured across ${summary.measured.length}/${summary.invoked.length} invocation(s) — ${summary.invoked.length - summary.measured.length} unmeasured`;
+}