toolroll 0.5.0

package/dist/control-setup.d.ts

@@ -0,0 +1,35 @@
+import type { Store } from "./store.js";
+export type SetupInputs = {
+    provider: string;
+    model: string;
+    command: string;
+    seconds: string;
+};
+export declare function previewSetup(store: Store, repo: string, inputs: SetupInputs): {
+    provider?: never;
+    model?: never;
+    ok: false;
+    message: string;
+    fingerprint?: never;
+    command?: never;
+    seconds?: never;
+} | {
+    message?: never;
+    ok: true;
+    fingerprint: string;
+    command: string;
+    seconds: number;
+    provider: import("./provider.js").ProviderId;
+    model: string;
+};
+export declare function approveSetup(store: Store, repo: string, inputs: SetupInputs, fingerprint: string, by: string, token: string, now: Date): {
+    provider?: never;
+    model?: never;
+    ok: false;
+    message: string;
+    fingerprint?: never;
+    command?: never;
+    seconds?: never;
+} | {
+    ok: true;
+};

package/dist/control-setup.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { hasDisguisedText } from "./decision.js";
+import { authenticateApprover } from "./scope.js";
+import { isProviderId, validateSpec } from "./provider.js";
+export function previewSetup(store, repo, inputs) {
+    if (!isProviderId(inputs.provider))
+        return { ok: false, message: "Choose an installed provider." };
+    if (inputs.model.trim() === "__custom__")
+        return { ok: false, message: "Choose an exact model before reviewing setup." };
+    const spec = validateSpec({ provider: inputs.provider, model: inputs.model.trim() });
+    if (!spec.ok)
+        return { ok: false, message: spec.problem };
+    const command = inputs.command.trim();
+    if (command.length > 2000 || hasDisguisedText(command))
+        return { ok: false, message: "Use a setup command under 2000 characters without control characters." };
+    if (/([A-Za-z0-9_-]*(?:token|secret|password|passwd|apikey|api_key|authorization|bearer|credential)[A-Za-z0-9_-]*\s*[=:]\s*)(?![$"']?\$)\S+/i.test(command) || /\/\/[^\s/@]+:[^\s/@]+@/.test(command))
+        return { ok: false, message: "Remove literal credentials from the setup command." };
+    const seconds = Number(inputs.seconds);
+    if (!/^[1-9][0-9]*$/.test(inputs.seconds) || !Number.isInteger(seconds) || seconds < 1 || seconds > 3600)
+        return { ok: false, message: "Setup timeout must be 1–3600 seconds." };
+    const fingerprint = createHash("sha256").update(JSON.stringify({ repo, inputs, beforeSetup: store.liveWorktreeSetup(repo), beforeConfig: store.phaseConfig(repo, "build") })).digest("hex");
+    return { ok: true, fingerprint, command, seconds, provider: inputs.provider, model: inputs.model.trim() };
+}
+export function approveSetup(store, repo, inputs, fingerprint, by, token, now) {
+    return store.transact(() => {
+        if (!authenticateApprover(store, by, token, repo).ok)
+            return { ok: false, message: "Your operator credential is required." };
+        const preview = previewSetup(store, repo, inputs);
+        if (!preview.ok)
+            return preview;
+        if (preview.fingerprint !== fingerprint)
+            return { ok: false, message: "Setup changed. Review it again." };
+        store.setPhaseConfig(repo, "build", preview.provider, preview.model, by, now);
+        if (preview.command === "")
+            store.clearWorktreeSetup(repo, by, now);
+        else
+            store.setWorktreeSetup({ repo, command: preview.command, timeoutMs: preview.seconds * 1000, approvedBy: by }, now);
+        return { ok: true };
+    });
+}

package/dist/control-ui.d.ts

@@ -0,0 +1,29 @@
+/** Shared setup views over the existing project configuration and approval doors. */
+import type { ProviderId } from "./provider.js";
+import type { ProviderConnection } from "./provider-connection.js";
+import { type ModelChoice } from "./setup-guide.js";
+import type { SetupInputs } from "./control-setup.js";
+import { type OpenRouterModels } from "./openrouter-models.js";
+export declare function hiddenFields(values: Record<string, string>): string;
+export declare function connectionWords(connection: ProviderConnection): string;
+export declare function connectionHtml(provider: ProviderId, connection: ProviderConnection, task?: string): string;
+export declare function controlSetupHtml(data: {
+    repo: string;
+    csrf: string;
+    provider: ProviderId;
+    inputs: SetupInputs;
+    models: ModelChoice[];
+    connection: ProviderConnection;
+    catalog: OpenRouterModels | null;
+    task?: string;
+    preparation: {
+        command: string;
+        label: string;
+        evidence: string;
+    } | null;
+    instructions: {
+        installed: boolean;
+        message?: string;
+    };
+}): string;
+export declare function setupPreviewHtml(inputs: SetupInputs, fields: Record<string, string>): string;

package/dist/control-ui.js

@@ -0,0 +1,53 @@
+import { ASSISTANTS } from "./setup-guide.js";
+import { openRouterPicker } from "./openrouter-models.js";
+const escape = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+export function hiddenFields(values) {
+    return Object.entries(values).map(([name, value]) => `<input type="hidden" name="${escape(name)}" value="${escape(value)}">`).join("");
+}
+export function connectionWords(connection) {
+    return {
+        connected: "Connected", "signed-out": "Not signed in", "not-installed": "CLI not installed",
+        unverified: "Not verified", "key-present": "API key saved · not verified", "key-works": "API key works", "key-refused": "API key refused", "missing-key": "API key needed",
+    }[connection.state];
+}
+export function connectionHtml(provider, connection, task = "") {
+    const query = new URLSearchParams({ provider, ...(task ? { task } : {}) });
+    return `<div class="card assistant-account"><p><strong>${escape(ASSISTANTS[provider].name)} · ${connectionWords(connection)}</strong></p>` +
+        `<p class="meta">${[connection.email, connection.plan, connection.method].filter(Boolean).map(one => escape(one)).join(" · ")}</p>` +
+        `<p class="meta">Checked ${escape(new Date(connection.checkedAt).toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit", timeZoneName: "short" }))} on the computer running this console. Sign-in does not prove model access or remaining quota.</p>` +
+        `<a class="button-link" href="/control/connection?${escape(query.toString())}">${connection.state === "connected" ? "Manage connection" : "Connect account"}</a> · ` +
+        `<a href="/control?${escape(query.toString())}&amp;check-connection=1">Check again</a></div>`;
+}
+export function controlSetupHtml(data) {
+    const { provider, inputs, task = "" } = data;
+    const query = new URLSearchParams({ provider, ...(task ? { task } : {}) });
+    const model = data.catalog !== null
+        ? openRouterPicker(data.catalog, inputs.model || null, `/control?${query}&refresh-models=1`)
+        : `<label>Model<input type="text" name="model" value="${escape(inputs.model)}" list="setup-models" required autocomplete="off" placeholder="Exact model id or supported alias"></label>` +
+            `<datalist id="setup-models">${data.models.map(one => `<option value="${escape(one.value)}">${escape(one.label)}</option>`).join("")}</datalist>`;
+    return `<h1>Project setup</h1><p>${escape(data.repo)}</p>` +
+        `<p class="meta">Choose the default builder for new tasks and the preparation command for this project.</p>` +
+        `<nav class="assistant-picker row" aria-label="Choose provider">${Object.keys(ASSISTANTS).map(id => `<a class="button-link" href="/control?${escape(new URLSearchParams({ provider: id, ...(task ? { task } : {}) }).toString())}"${id === provider ? ' aria-current="page"' : ""}>${ASSISTANTS[id].name}</a>`).join(" ")}</nav>` +
+        connectionHtml(provider, data.connection, task) +
+        `<form method="post" action="/control/setup-preview" class="card">${hiddenFields({ csrf: data.csrf, repo: data.repo, provider, task })}` + model +
+        `<details class="setup-advanced"><summary>Project preparation</summary>` +
+        (data.preparation === null ? "" : `<p class="meta">Suggested from ${escape(data.preparation.evidence)}: ${escape(data.preparation.label)} — <code>${escape(data.preparation.command)}</code>. Review before approving.</p>`) +
+        `<label>Preparation command<textarea name="command" rows="2" maxlength="2000">${escape(inputs.command)}</textarea></label>` +
+        `<label>Preparation timeout in seconds<input name="seconds" type="number" min="1" max="3600" value="${escape(inputs.seconds)}" required></label>` +
+        `<p class="meta">Preparation applies to subsequent runs, including already approved tasks. Saving setup does not execute it.</p></details>` +
+        `<button type="submit">Review project setup</button></form>` +
+        `<section class="card"><h2>Agent instructions</h2>` +
+        (data.instructions.message ? `<p>${escape(data.instructions.message)}</p>` : data.instructions.installed ? `<p>Current Toolroll instructions are installed.</p>` :
+            `<p>Give the agent the project's Toolroll handoff instructions.</p><form method="post" action="/control/instructions-preview">${hiddenFields({ csrf: data.csrf, repo: data.repo })}<button>Review instructions</button></form>`) +
+        `</section><p><a href="/fleet">Configure planning, repair, and review agents</a> · <a href="/tasks/new">Describe a task</a></p>`;
+}
+export function setupPreviewHtml(inputs, fields) {
+    return `<h1>Approve project setup</h1><div class="card"><p>${escape(fields.repo ?? "")}</p>` +
+        `<p><strong>Builder:</strong> ${escape(inputs.provider)} · ${escape(inputs.model)}</p>` +
+        `<p><strong>Preparation:</strong></p><pre class="recap">${escape(inputs.command || "No preparation command")}</pre>` +
+        `<p>Preparation timeout: ${escape(inputs.seconds)} seconds.</p>` +
+        `<p>The builder default applies to new tasks. Preparation applies to subsequent runs, including already approved tasks. Existing signed task settings and verification rules remain in force.</p>` +
+        `<form method="post" action="/control/setup-approve">${hiddenFields({ ...fields, ...inputs })}` +
+        `<label>Your password<input type="password" name="token" autocomplete="current-password" required></label>` +
+        `<button>Approve project setup</button></form></div>`;
+}

package/dist/controller-service.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/controller-service.js

@@ -0,0 +1,19 @@
+/** Service entry for CLI controllers; the engine remains the watch child. */
+import { superviseController } from "./controller-supervisor.js";
+const [file, ...argv] = process.argv.slice(2);
+if (!file)
+    throw new Error("Controller service needs an executable.");
+const stopping = new AbortController();
+const stop = () => stopping.abort();
+process.on("SIGTERM", stop);
+process.on("SIGINT", stop);
+try {
+    await superviseController({ file, argv, signal: stopping.signal, onState: state => {
+            if (state.phase === "backoff")
+                process.stderr.write(`Controller exited (${state.exit?.signal ?? state.exit?.code ?? "unknown"}); restart in ${state.retryMs} ms.\n`);
+        } });
+}
+finally {
+    process.off("SIGTERM", stop);
+    process.off("SIGINT", stop);
+}

package/dist/controller-supervisor.d.ts

@@ -0,0 +1,30 @@
+export type ControllerState = {
+    phase: "starting" | "running" | "backoff" | "stopped";
+    generation: number;
+    controllerPid: number | null;
+    exit?: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    };
+    retryMs?: number;
+};
+/** A service process supervises exactly one controller. It knows nothing
+ * about tasks, credentials, claims, or retries: those remain in `up`.
+ *
+ * This closes a Node-controller crash without depending on launchd starting
+ * another process. It does not claim to survive its own SIGKILL or bypass an
+ * OS policy that defers a LaunchAgent. Children share the service's process
+ * group so launchd can also clean up the controller when this process dies.
+ */
+export declare function superviseController(args: {
+    file: string;
+    argv: readonly string[];
+    signal: AbortSignal;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    onState?: (state: ControllerState) => void;
+    retryMs?: number;
+    maxRetryMs?: number;
+    stableMs?: number;
+    shutdownMs?: number;
+}): Promise<void>;

package/dist/controller-supervisor.js

@@ -0,0 +1,104 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { stopProcessTree } from "./process-tree.js";
+/** A service process supervises exactly one controller. It knows nothing
+ * about tasks, credentials, claims, or retries: those remain in `up`.
+ *
+ * This closes a Node-controller crash without depending on launchd starting
+ * another process. It does not claim to survive its own SIGKILL or bypass an
+ * OS policy that defers a LaunchAgent. Children share the service's process
+ * group so launchd can also clean up the controller when this process dies.
+ */
+export async function superviseController(args) {
+    const retryMs = args.retryMs ?? 1_000;
+    const maxRetryMs = args.maxRetryMs ?? 30_000;
+    const stableMs = args.stableMs ?? 30_000;
+    const shutdownMs = args.shutdownMs ?? 45_000;
+    for (const value of [retryMs, maxRetryMs, stableMs, shutdownMs]) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > 2_147_483_647)
+            throw new Error("Invalid controller supervision interval.");
+    }
+    if (maxRetryMs < retryMs)
+        throw new Error("Controller restart ceiling must cover its initial delay.");
+    let generation = 0;
+    let failures = 0;
+    let child = null;
+    let escalation = null;
+    const emit = (state) => {
+        // Telemetry cannot interrupt a graceful stop or orphan the owned child.
+        try {
+            args.onState?.(state);
+        }
+        catch {
+            process.stderr.write("Controller supervisor could not record its status.\n");
+        }
+    };
+    const stop = () => {
+        const owned = child;
+        if (owned === null || owned.exitCode !== null || owned.signalCode !== null)
+            return;
+        owned.kill("SIGTERM");
+        if (escalation !== null)
+            return;
+        escalation = setTimeout(() => {
+            // Signals come only from the still-owned ChildProcess, never status PIDs.
+            if (owned.exitCode === null && owned.signalCode === null && !stopProcessTree(owned))
+                owned.kill("SIGKILL");
+        }, shutdownMs);
+    };
+    args.signal.addEventListener("abort", stop);
+    try {
+        while (!args.signal.aborted) {
+            generation++;
+            const started = performance.now();
+            emit({ phase: "starting", generation, controllerPid: null });
+            // The callback above can synchronously cancel before the OS spawn.
+            if (args.signal.aborted)
+                break;
+            const exited = await new Promise(done => {
+                const owned = spawn(args.file, [...args.argv], {
+                    ...(args.cwd === undefined ? {} : { cwd: args.cwd }),
+                    ...(args.env === undefined ? {} : { env: args.env }),
+                    stdio: "inherit",
+                    windowsHide: true,
+                });
+                child = owned;
+                owned.once("spawn", () => {
+                    emit({ phase: "running", generation, controllerPid: owned.pid ?? null });
+                    if (args.signal.aborted)
+                        stop();
+                });
+                // `close` follows both a spawn error and ordinary exit; await it so
+                // the next generation cannot overlap the previous controller handle.
+                owned.once("error", () => { });
+                owned.once("close", (code, signal) => done({ code, signal }));
+                if (args.signal.aborted)
+                    stop();
+            });
+            child = null;
+            if (escalation !== null) {
+                clearTimeout(escalation);
+                escalation = null;
+            }
+            if (args.signal.aborted)
+                break;
+            failures = performance.now() - started >= stableMs ? 0 : Math.min(failures + 1, 20);
+            const delay = Math.min(maxRetryMs, retryMs * 2 ** Math.max(0, failures - 1));
+            emit({ phase: "backoff", generation, controllerPid: null, exit: exited, retryMs: delay });
+            await new Promise(done => {
+                let timer;
+                const finish = () => { clearTimeout(timer); args.signal.removeEventListener("abort", finish); done(); };
+                timer = setTimeout(finish, delay);
+                args.signal.addEventListener("abort", finish, { once: true });
+                if (args.signal.aborted)
+                    finish();
+            });
+        }
+    }
+    finally {
+        args.signal.removeEventListener("abort", stop);
+        if (escalation !== null)
+            clearTimeout(escalation);
+        emit({ phase: "stopped", generation, controllerPid: null });
+    }
+}

package/dist/converse.d.ts

@@ -0,0 +1,304 @@
+/**
+ * The converse engine (fleet chat v3) — a DIRECT no-tool API call.
+ *
+ * Chat never spawns a provider CLI: the boundary that matters (no tools,
+ * no filesystem, no inherited instructions, no hooks) is established by
+ * constructing the HTTP request ourselves and sending no tool surface at
+ * all. Zero dependencies — Node's fetch.
+ *
+ * Two-layer parsing, per the Codex v3 review (change 2): the PROVIDER
+ * WRAPPER (Anthropic / OpenRouter response JSON) is stream-capped,
+ * fatally UTF-8 decoded, and strictly parsed first — status, content
+ * type, exactly one textual assistant block, usage present, tool calls
+ * rejected. Only then is the extracted assistant text parsed AGAIN,
+ * independently, as the versioned chat envelope with model-only DTOs.
+ * Any violation at either layer yields a typed refusal and NO model text
+ * reaches a page (transport failures render a static line only).
+ *
+ * Money, per change 4: prices are PINNED here, versioned, in integer
+ * micro-dollars per token, rounded up. A model without a pinned price
+ * cannot be spoken to — the reservation math would be fiction.
+ */
+import { type AcceptanceCriterion } from "./scope.js";
+import type { ChatProviderId, DirectChatProviderId, SubscriptionChatProviderId } from "./store.js";
+export declare const WRAPPER_CAP_BYTES = 262144;
+export declare const ENVELOPE_CAP_BYTES = 65536;
+export declare const REPLY_CAP_BYTES = 32768;
+export declare const MAX_PROPOSALS = 3;
+export declare const MAX_DEPTH = 6;
+export declare const MAX_OUTPUT_TOKENS = 2048;
+export declare const TURN_WALL_CLOCK_MS = 120000;
+export declare const PRICE_VERSION = 1;
+export declare function priceOf(model: string): {
+    inMicrousd: number;
+    outMicrousd: number;
+} | null;
+/** For the config error message: what CAN be configured today. */
+export declare const PRICED_MODELS: readonly string[];
+export type ModelPrice = {
+    inMicrousd: number;
+    outMicrousd: number;
+};
+export type CatalogModel = {
+    id: string;
+    price: ModelPrice;
+};
+/**
+ * OpenRouter's own model catalog — the authority on what OpenRouter
+ * bills, read live so every selectable model arrives WITH the price the
+ * config will pin. Models with dynamic or unparseable pricing (the auto
+ * router advertises -1) are excluded rather than guessed: spend that
+ * cannot be bounded up front cannot be reserved, so it cannot run.
+ */
+export declare function fetchOpenRouterCatalog(key: string, fetcher?: typeof fetch, signal?: AbortSignal): Promise<{
+    ok: true;
+    models: CatalogModel[];
+} | {
+    ok: false;
+    problem: string;
+}>;
+/** The price a configured chat actually runs on: the pin when present,
+ * the compiled table for pre-v13b rows, nothing otherwise. */
+export declare function priceForConfig(config: {
+    model: string;
+    priceInMicrousd: number | null;
+    priceOutMicrousd: number | null;
+}): ModelPrice | null;
+export declare function worstCaseForPrice(price: ModelPrice, promptBytes: number): number;
+export declare function settleForPrice(price: ModelPrice, tokensIn: number, tokensOut: number): number;
+/** The worst a turn can cost, in integer micro-dollars: every prompt byte
+ * as a token-third (generous) plus the full output allowance. */
+export declare function worstCaseMicrousd(model: string, promptBytes: number): number | null;
+export declare function settleMicrousd(model: string, tokensIn: number, tokensOut: number): number | null;
+export declare const DIRECT_CHAT_PROVIDERS: readonly DirectChatProviderId[];
+export declare const SUBSCRIPTION_CHAT_PROVIDERS: readonly SubscriptionChatProviderId[];
+export declare function isDirectChatProvider(provider: ChatProviderId): provider is DirectChatProviderId;
+export declare function isSubscriptionChatProvider(provider: ChatProviderId): provider is SubscriptionChatProviderId;
+export declare const CHAT_KEY_ENV: Record<DirectChatProviderId, string>;
+/** Domain-separated, full-width, non-secret accounting identity for a
+ * credential (v3 open question 1: eight hex chars was refused). */
+export declare function credentialKeyOf(provider: ChatProviderId, key: string): string;
+/** Subscription usage has no API credential to fingerprint. The provider
+ * identity is sufficient because dollar latches do not apply to zero-cost
+ * ledger rows, while switching harnesses still invalidates a live session. */
+export declare function subscriptionCredentialKey(provider: SubscriptionChatProviderId): string;
+export declare function plausibleChatKey(provider: DirectChatProviderId, key: string): boolean;
+export type StrictParse = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * JSON.parse with the two properties it lacks: duplicate keys REJECTED at
+ * every nesting level, and depth bounded. The scanner walks the text
+ * once; JSON.parse then supplies the value only if the scan held.
+ */
+export declare function strictJsonParse(bytes: Buffer, maxBytes: number, maxDepth?: number): StrictParse;
+/** What the MODEL may say and nothing more (v3 change 3): opaque repoId,
+ * no provenance, no ceiling, no approval-shaped anything. */
+export type ChatTaskDraft = {
+    kind: "task";
+    repoId: string;
+    title: string;
+    goal: string;
+    outOfScope: string | null;
+    touches: string[];
+    /** v39: the signed rubric — mandatory, like every other scope-producing
+     * road. The model drafts it; the operator still confirms with a
+     * password before it becomes a real, unapproved scope. */
+    acceptance: AcceptanceCriterion[];
+};
+export type ChatRoutineDraft = {
+    kind: "routine";
+    repoId: string;
+    name: string;
+    goal: string;
+    outOfScope: string | null;
+    touches: string[];
+    acceptance: AcceptanceCriterion[];
+    schedule: string;
+};
+export type ChatDraft = ChatTaskDraft | ChatRoutineDraft;
+export type ParsedEnvelope = {
+    reply: string;
+    proposals: ChatDraft[];
+};
+/**
+ * The assistant envelope: exactly {chatEnvelope: 1, reply, proposals}.
+ * ANY violation — including one bad proposal — discards the whole batch;
+ * a bad proposal additionally keeps the (valid, escaped-elsewhere) reply,
+ * per the ruled atomicity: reply may render, proposals are all-or-nothing.
+ */
+export declare function parseAssistantEnvelope(text: string): {
+    ok: true;
+    envelope: ParsedEnvelope;
+    proposalsDiscarded: boolean;
+} | {
+    ok: false;
+    problem: string;
+};
+export type ProviderAnswer = {
+    text: string;
+    tokensIn: number;
+    tokensOut: number;
+    /** OpenRouter reports the actual charge; settlement takes the HIGHER of
+     * this and the pinned math — the ledger never undercounts. */
+    reportedCostMicrousd: number | null;
+};
+/** Strict parse of the PROVIDER response body (layer one). */
+/** A token count is a non-negative safe integer under a billion (mate arc,
+ * ruling 14): a negative, fractional, or absurd usage is a malformed reply,
+ * never a discount on the pinned settlement. */
+export declare function tokenCount(value: number): boolean;
+export declare const MATE_MAX_STEPS = 8;
+export declare const MATE_MAX_CALLS_PER_STEP = 4;
+/** A tool result, measured AS EMBEDDED — the JSON-encoded string, escapes included. */
+export declare const MATE_TOOL_RESULT_CAP_BYTES = 16384;
+/** A tool call, measured as the serialized `{id, name, args}` — the id counts. */
+export declare const MATE_TOOL_CALL_CAP_BYTES = 2048;
+export declare const MATE_TOOL_CALL_ID_CAP_BYTES = 64;
+/** One step's assistant text; over it the reply is malformed (review finding 7). */
+export declare const MATE_STEP_TEXT_CAP_BYTES = 8192;
+/**
+ * The triangular worst case (mate arc, ruling 6; slice-1 review finding 7):
+ * request s carries the base prompt plus every earlier step's calls,
+ * results, and assistant text. Calls and results are measured as
+ * embedded and may be JSON-escaped ONCE more on the wire (OpenRouter
+ * serializes arguments twice; a result string re-escapes inside the
+ * body), so each is budgeted at twice its cap — escaping at most doubles
+ * a string. Each step may answer with the full output allowance.
+ */
+export declare function mateWorstCaseForPrice(price: ModelPrice, baseBytes: number, caps?: {
+    steps?: number;
+    callsPerStep?: number;
+    resultCap?: number;
+    callCap?: number;
+    textCap?: number;
+}): number;
+/** The bytes a tool result costs on the wire: its JSON string form. */
+export declare function embeddedBytes(text: string): number;
+export type MateToolSchema = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+export type MateToolCall = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+/** A provider answer with tool calls allowed: text, calls, usage. */
+export type MateProviderAnswer = {
+    text: string;
+    calls: MateToolCall[];
+    tokensIn: number;
+    tokensOut: number;
+    reportedCostMicrousd: number | null;
+};
+/** One message of the mate's own history, provider-neutral. */
+export type MateHistoryMessage = {
+    role: "operator";
+    text: string;
+} | {
+    role: "assistant";
+    text: string;
+    calls: MateToolCall[];
+} | {
+    role: "tool";
+    callId: string;
+    name: string;
+    result: string;
+};
+/**
+ * The tool-capable wrapper parser (mate arc). Same caps and the same
+ * duplicate-key lexer as fleet chat's; tool calls are read, bounded (at
+ * most M per answer, each argument object under the call cap), and
+ * anything else about the shape is malformed.
+ */
+export declare function parseMateProviderWrapper(provider: DirectChatProviderId, bytes: Buffer): {
+    ok: true;
+    answer: MateProviderAnswer;
+} | {
+    ok: false;
+    problem: string;
+};
+/** The mate's request: system contract, the data document as the first
+ * operator message, the history in provider-native shape, the tools. */
+export declare function composeMateRequest(args: {
+    provider: DirectChatProviderId;
+    model: string;
+    key: string;
+    system: string;
+    dataDocument: string;
+    history: readonly MateHistoryMessage[];
+    tools: readonly MateToolSchema[];
+}): {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+};
+/** The mate's network call: the same transport posture as fleet chat's, the tool-capable parser at the end. */
+export declare function performMateRequest(request: {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}, provider: DirectChatProviderId, signal: AbortSignal, fetcher?: typeof fetch): Promise<{
+    ok: true;
+    answer: MateProviderAnswer;
+} | {
+    ok: false;
+    problem: string;
+}>;
+export declare function parseProviderWrapper(provider: DirectChatProviderId, bytes: Buffer): {
+    ok: true;
+    answer: ProviderAnswer;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare const DATA_DOCUMENT_BUDGET_BYTES = 24576;
+/**
+ * The snapshot, serialized for the model: repos as opaque ids only (no
+ * paths, no basenames — change 9), items shed WHOLE (never fields) until
+ * the byte budget holds, and every shed declared in-band so a trimmed
+ * list can never read as a complete one.
+ */
+export declare function buildDataDocument(snapshot: import("./store.js").ChatSnapshot, budgetBytes?: number): {
+    document: string;
+    shed: number;
+};
+export declare function composeRequest(args: {
+    provider: DirectChatProviderId;
+    model: string;
+    key: string;
+    dataDocument: string;
+    userMessage: string;
+}): {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+};
+/** Read a response body with the cap enforced WHILE streaming (v2 new
+ * finding 8): one byte over the cap aborts the read, not the memory. */
+export declare function readCappedBody(response: Response, cap: number): Promise<Buffer | null>;
+/**
+ * The one network call a turn may make. The caller owns the CAS that
+ * makes it at-most-once; this owns the transport posture: no redirects,
+ * wall clock, streamed cap, wrapper strictness.
+ */
+export declare function performChatRequest(args: {
+    provider: DirectChatProviderId;
+    model: string;
+    key: string;
+    dataDocument: string;
+    userMessage: string;
+    signal: AbortSignal;
+}, fetcher?: typeof fetch): Promise<{
+    ok: true;
+    answer: ProviderAnswer;
+} | {
+    ok: false;
+    problem: string;
+}>;