@ocis/myagent-cli 0.2.0

package/dist/agent/turn.js

@@ -0,0 +1,1253 @@
+// ---------------------------------------------------------------------------
+// The turn loop over the AG-UI run line.
+//
+// One turn = one run stream (POST /v1/runs): AG-UI events arrive verbatim and
+// the stream STAYS OPEN through client-tool waits, so the whole loop —
+// content, tool calls, approval waits, result submission, continuation — is
+// driven by events on a single connection. `CUSTOM_TOOL_CALL` events collected
+// in one tick form an execution round; `sendRunMessages` delivers the results
+// (user/system messages steer, tool-role messages resume) and the agent's
+// continuation keeps streaming here.
+//
+// Release detection is state-based, never timing-based: a call is released
+// when a TOOL_CALL_RESULT arrives for an id still awaiting submission — the
+// server dropped it (isError) or another client answered it — or when a run
+// segment ends with calls still pending. Our own submissions are removed from
+// that pending set BEFORE the request goes out, so their echoes can never be
+// misread.
+//
+// The session events channel is a fallback only: when the run stream drops
+// with calls still owed, the runner reconciles over REST and subscribes to the
+// channel while it finishes the round (no request stream is attached then).
+// ---------------------------------------------------------------------------
+import { IntegrationApiError } from "../protocol/client.js";
+import { isMutatingCall } from "../tools/types.js";
+import { toolRequestOutsideWorkspace } from "../tools/paths.js";
+import { DEFAULT_MODE, modeMarker } from "./modes.js";
+/** Error `code` the integration API uses for a submission whose call was released. */
+const TOOL_CALL_EXPIRED_CODE = "tool_call_expired";
+/** Error `code` for a steer whose run already ended (recover as a new turn). */
+const NO_ACTIVE_RUN_CODE = "no_active_run";
+/** Delay between session-event-channel reconnect attempts (fallback watcher). */
+const EVENT_RECONNECT_DELAY_MS = 5_000;
+/** Delay before the single retry of a transiently failed tool-result submission. */
+const SUBMIT_RETRY_DELAY_MS = 1_000;
+/**
+ * Reconnect attempts per recovery. Bounded on purpose: a reconnect wakes a
+ * paused sandbox (integration traffic auto-wakes), so an unbounded loop would
+ * fight the platform's idle pause. The loop also stops as soon as the
+ * outstanding call is known to be released.
+ */
+const MAX_EVENT_RECONNECTS = 12;
+/**
+ * Canonical form of a tool call's raw JSON arguments for retry matching:
+ * parse + stable key order, so `{"a":1,"b":2}` and `{"b":2,"a":1}` compare
+ * equal. Unparseable input falls back to a trimmed string.
+ */
+function canonicalToolArgs(raw) {
+    try {
+        return JSON.stringify(sortJson(JSON.parse(raw)));
+    }
+    catch {
+        return raw.trim();
+    }
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortJson(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Find a pending call the model re-issued for the same action (same tool name
+ * and canonically-equal arguments) — the retry that follows an abandoned call.
+ * Adopting it lets the already-executed result be delivered as a native tool
+ * result on the same run, without executing the side effect twice.
+ */
+function findAdoptableCall(call, pending) {
+    const wanted = canonicalToolArgs(call.arguments);
+    return pending.find((p) => p.name === call.name && canonicalToolArgs(p.arguments) === wanted);
+}
+/** True when an error means "the call was released before the result arrived". */
+function isToolCallExpired(err) {
+    return err instanceof IntegrationApiError && err.code === TOOL_CALL_EXPIRED_CODE;
+}
+/** True when a steer raced the end of its run — the message must be re-sent as a new turn. */
+function isNoActiveRun(err) {
+    return err instanceof IntegrationApiError && err.code === NO_ACTIVE_RUN_CODE;
+}
+/** Expired call ids reported by a pre-stream rejection (`details.expiredIds`). */
+function readExpiredIds(err) {
+    if (!(err instanceof IntegrationApiError))
+        return [];
+    const ids = err.details?.expiredIds;
+    return Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
+}
+/** True for event-channel failures retrying cannot fix (bad key, deleted session). */
+export function isPermanentEventChannelError(err) {
+    return err instanceof IntegrationApiError && (err.status === 401 || err.status === 404);
+}
+/** Map the tool-execution output shape onto the AG-UI input message shape. */
+function toAguiToolResult(output) {
+    return {
+        role: "tool",
+        toolCallId: output.tool_call_id,
+        content: output.output,
+        ...(output.isError ? { isError: true } : {}),
+        ...(output.images?.length ? { images: output.images } : {}),
+    };
+}
+/** Drop the nulls `executeOne` returns for cancelled calls. */
+const isToolOutput = (output) => output !== null;
+export class AgentRunner {
+    opts;
+    threadId;
+    mode = DEFAULT_MODE;
+    /** undefined = omit thinkingLevel (provider default). */
+    thinkingLevel;
+    /**
+     * The model the user picked for the next new thread (null = client-choice
+     * default). Sent only on a new thread's first run: the server pins the
+     * thread's model on its first run, and a later request naming a different
+     * model on the same thread is rejected with 400.
+     */
+    selectedModel = null;
+    /**
+     * Effective model of the current/resumed thread, as reported by the server.
+     * Display only — selection goes through `selectedModel`.
+     */
+    model = null;
+    usage = null;
+    state = "idle";
+    abort = null;
+    /**
+     * True from stop() until the next run starts — the cancelled-approval
+     * wording keys off it (the AbortController is nulled by run()'s finally
+     * before an in-flight round resumes, so it cannot be used there).
+     */
+    stopped = false;
+    followUps = [];
+    /**
+     * Chain of fire-and-forget follow-up turns (user follow-ups).
+     * `waitForIdle()` awaits it so headless runs don't exit before a queued
+     * turn has been delivered.
+     */
+    followUpChain = Promise.resolve();
+    /**
+     * Tool calls already reported as released — populated from the run stream's
+     * `TOOL_CALL_RESULT(isError)` echoes, `RUN_FINISHED` with calls still
+     * pending, and the fallback event channel. Also the client-side idempotency
+     * filter: a replayed CUSTOM_TOOL_CALL for an abandoned call is never
+     * executed again.
+     */
+    abandonedToolCalls = new Set();
+    /**
+     * Every CUSTOM_TOOL_CALL id received this session. The replay guard: an id
+     * seen once is never enqueued again, whatever the delivery path (run stream,
+     * event-channel replay) — a duplicate would execute a side-effecting tool
+     * twice. Cumulative like abandonedToolCalls: ids are unique per call, so
+     * there is nothing to reset.
+     */
+    seenToolCallIds = new Set();
+    /**
+     * Unix ms of a server-reported interruption of the previous run (restart /
+     * idle scale-down) — wording only: released calls are explained as an
+     * interruption instead of an ordinary no-response release.
+     */
+    lastRunInterruptedAt = null;
+    /**
+     * Calls received from the agent but not yet submitted: the release filter.
+     * An id is removed BEFORE its submission request goes out, so the server's
+     * echo of our own result can never be misread as a release.
+     */
+    pendingSubmission = new Set();
+    /**
+     * Steers acked but not yet injected into the run, keyed by the persisted
+     * message id (from INPUT_ACCEPTED). The ack only means "persisted + queued
+     * for injection" — the float stays up until QUEUED_MESSAGE_DELIVERED (the
+     * agent actually put the message into the conversation) releases it. The
+     * turn-end sweep releases whatever is left: unconsumed steers are re-issued
+     * as a fresh prompt by the manager, and the message is in the session
+     * either way, so the float must not linger.
+     */
+    pendingSteerDeliveries = new Map();
+    /**
+     * Tool rounds scheduled or executing (debounce included). The turn drains
+     * them before it settles, so a round is never raced by the followUps drain.
+     */
+    roundsInFlight = 0;
+    roundsDrained = [];
+    /**
+     * True once the current run segment ended (RUN_FINISHED/RUN_ERROR) — a
+     * stream that closes without this observed a drop, not a settle.
+     */
+    runSettled = false;
+    /**
+     * True while a channel-loss notice is outstanding (cleared when events flow
+     * again) — keeps "lost the event channel" to one notice per outage.
+     */
+    eventChannelDown = false;
+    /** Fallback event-channel subscription (reconcile window only). */
+    eventsAbort = null;
+    /**
+     * Mode last announced to the server. null = unknown (new/resumed thread), so
+     * the next message carries `[mode: x]`. Kept in sync by the send paths.
+     */
+    announcedMode = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.threadId = null;
+    }
+    get busy() {
+        return this.state !== "idle";
+    }
+    setMode(mode) {
+        this.mode = mode;
+    }
+    /** Forget the announced mode (new thread or resume) — re-announce on next send. */
+    resetModeAnnouncement() {
+        this.announcedMode = null;
+    }
+    setThinkingLevel(level) {
+        this.thinkingLevel = level;
+    }
+    /** Select the model for the next new thread (null = server default). */
+    setModel(model) {
+        this.selectedModel = model;
+    }
+    /** Advertised tools are mode-independent: a stable schema keeps the prompt cache warm. */
+    toolDefs() {
+        return this.opts.registry.allDefinitions();
+    }
+    /** Tool definitions in AG-UI protocol shape (name/description/parameters). */
+    aguiToolDefs() {
+        return this.toolDefs().map((def) => ({
+            name: def.function.name,
+            description: def.function.description,
+            parameters: def.function.parameters,
+        }));
+    }
+    /**
+     * The user text to send, prefixed with `[mode: x]` when the mode changed
+     * since the last send (or was never announced). Also returns the mode being
+     * announced so the caller can record it after a successful send. The marker
+     * is the only mode signal the model gets — the system prompt describes both
+     * modes statically.
+     */
+    announcedText(text) {
+        const mode = this.mode;
+        const message = this.announcedMode === mode ? text : `${modeMarker(mode)}\n\n${text}`;
+        return { message, mode };
+    }
+    toolContext(signal) {
+        return {
+            workspace: this.opts.workspace,
+            allowOutside: this.opts.allowOutside,
+            skillDirs: this.opts.skillDirs,
+            signal,
+            todos: this.opts.todos,
+            client: this.opts.client,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Sending
+    // -------------------------------------------------------------------------
+    /**
+     * Compose a send's input messages: the per-request system block (when one is
+     * built) plus the user message with its `[mode: x]` marker applied. Shared by
+     * the steer and run paths so their mode-announcement semantics cannot drift.
+     */
+    async composeInput(text) {
+        const system = await this.opts.buildSystemPrompt();
+        const { message, mode } = this.announcedText(text);
+        return {
+            messages: [
+                ...(system ? [{ role: "system", content: system }] : []),
+                { role: "user", content: message },
+            ],
+            mode,
+        };
+    }
+    /**
+     * Send a user message. While a run is active:
+     *  - default: steered into the in-flight run (POST .../messages)
+     *  - `followUp`: queued locally and delivered after the run settles
+     */
+    async send(text, opts = {}) {
+        const cb = this.opts.callbacks;
+        if (this.state !== "idle") {
+            // Not part of the conversation yet — float it above the prompt until the
+            // agent actually injects it (QUEUED_MESSAGE_DELIVERED → onSteerAccepted)
+            // or it is delivered as a fresh turn (onUserMessage releases the float).
+            cb.onSteerQueued?.(text);
+            if (opts.followUp || !this.threadId) {
+                // No thread id yet (the first stream hasn't reported one) — a steer
+                // would have nowhere to go, so queue it instead of dropping it.
+                this.followUps.push(text);
+                cb.onNotice(opts.followUp ? "Queued as a follow-up." : "Queued (session still starting).", "info");
+                return;
+            }
+            const { messages, mode } = await this.composeInput(text);
+            try {
+                const messageId = await this.opts.client.sendRunMessages(this.threadId, messages, { tools: this.aguiToolDefs() });
+                this.announcedMode = mode;
+                if (messageId) {
+                    // The ack only means persisted + queued for injection — hold the
+                    // float until the agent consumes it (QUEUED_MESSAGE_DELIVERED).
+                    this.pendingSteerDeliveries.set(messageId, text);
+                }
+                else {
+                    // No id to correlate with (older server) — release at the ack so
+                    // the float can never get stuck.
+                    cb.onSteerAccepted?.(text);
+                }
+            }
+            catch (err) {
+                if (isNoActiveRun(err)) {
+                    // The run ended between the user's send and this request. Nothing
+                    // was persisted server-side (the server rolls the race-window row
+                    // back) — deliver it as a fresh turn instead of leaving it stranded.
+                    // The float stays: run()'s onUserMessage releases it when the
+                    // follow-up turn actually starts.
+                    this.followUps.push(text);
+                    cb.onNotice("The run had already ended — sending as a new turn.", "warn");
+                    return;
+                }
+                // Undelivered — the float stays up (the message never entered the
+                // conversation); the notice says why.
+                cb.onNotice(`Could not steer: ${err instanceof Error ? err.message : String(err)}`, "error");
+            }
+            return;
+        }
+        await this.run(text);
+    }
+    /** Force-stop the run (used by Esc and /stop). */
+    async stop() {
+        if (this.state === "idle")
+            return;
+        this.state = "stopping";
+        this.stopped = true;
+        this.opts.callbacks.onRunState("stopping");
+        // A pending approval must not outlive the run — the tool never runs.
+        this.opts.approval.cancelPending();
+        this.abort?.abort();
+        if (this.threadId) {
+            await this.opts.client.stopSession(this.threadId).catch(() => { });
+        }
+    }
+    /** Manually compact the remote session history. */
+    async compact() {
+        if (!this.threadId)
+            throw new Error("No active session to compact.");
+        await this.opts.client.compactSession(this.threadId);
+        await this.refreshSession();
+    }
+    /** Refresh model/usage/thinking metadata from the server. */
+    async refreshSession(includeHistory = false) {
+        if (!this.threadId)
+            return null;
+        try {
+            const detail = await this.opts.client.getSession(this.threadId, { history: includeHistory });
+            this.model = detail.model ?? this.model;
+            if (detail.usage)
+                this.usage = usageFromSession(detail.usage);
+            this.opts.callbacks.onSession(detail);
+            return detail;
+        }
+        catch {
+            return null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // The run
+    // -------------------------------------------------------------------------
+    async run(text) {
+        const cb = this.opts.callbacks;
+        const abort = new AbortController();
+        this.abort = abort;
+        this.stopped = false;
+        this.state = "running";
+        // Wording state is per turn — an older turn's interruption is stale news.
+        this.lastRunInterruptedAt = null;
+        this.runSettled = false;
+        cb.onRunState("running");
+        try {
+            cb.onUserMessage(text, false);
+            const { messages, mode } = await this.composeInput(text);
+            const request = {
+                ...(this.threadId ? { threadId: this.threadId } : {}),
+                messages,
+                tools: this.aguiToolDefs(),
+                ...(this.thinkingLevel !== undefined ? { thinkingLevel: this.thinkingLevel } : {}),
+                ...(!this.threadId && this.selectedModel ? { model: this.selectedModel } : {}),
+            };
+            const result = await this.streamRun(request, cb, abort.signal);
+            this.announcedMode = mode;
+            // A stream that ends without a terminal run event (network error, or a
+            // silent close) dropped before the run settled.
+            const dropped = Boolean(result.error) || !this.runSettled;
+            // The stream is gone but a round is still owed results: the fallback
+            // channel is the release watcher for this window (no run stream attached).
+            if (dropped && this.roundsInFlight > 0) {
+                this.startEventSubscription();
+            }
+            // Let in-flight tool rounds finish (execution, submission) before
+            // judging the turn's outcome — a round may still be waiting on an
+            // approval even though the run already ended.
+            await this.drainRounds(abort.signal);
+            if (abort.signal.aborted) {
+                cb.onNotice("Stopped.", "warn");
+                return;
+            }
+            if (dropped) {
+                // Recover against the durable session.
+                await this.reconcile(cb, abort.signal);
+                return;
+            }
+            // The run settled cleanly; any call still awaiting submission was released.
+            if (this.pendingSubmission.size > 0)
+                this.markAbandoned([...this.pendingSubmission.keys()]);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                cb.onNotice("Stopped.", "warn");
+            }
+            else {
+                cb.onNotice(err instanceof Error ? err.message : String(err), "error");
+            }
+        }
+        finally {
+            this.stopEventSubscription();
+            this.pendingSubmission.clear();
+            // Catch-all: any steer still floating when the turn ends can no longer
+            // be confirmed by this connection (settled, dropped, stopped, errored).
+            // The message is persisted in the session either way, so release it
+            // rather than leaving the float hanging.
+            this.releasePendingSteers();
+            this.abort = null;
+            this.state = "idle";
+            cb.onRunState("idle");
+            await this.refreshSession();
+            const next = this.followUps.shift();
+            if (next && !abort.signal.aborted) {
+                this.followUpChain = this.followUpChain.then(() => this.run(next));
+            }
+        }
+    }
+    /**
+     * Wait for every in-flight tool round (or an abort, so /stop never hangs on
+     * a pending approval).
+     */
+    async drainRounds(signal) {
+        const aborted = new Promise((resolve) => {
+            if (signal.aborted)
+                return resolve();
+            signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+        while (this.roundsInFlight > 0 && !signal.aborted) {
+            await Promise.race([
+                new Promise((resolve) => this.roundsDrained.push(resolve)),
+                aborted,
+            ]);
+        }
+    }
+    /**
+     * Open the run stream and dispatch its events until it closes. Returns when
+     * the stream ended; `runSettled` distinguishes a clean settle from a drop.
+     */
+    async streamRun(request, cb, 
+    /**
+     * This run's signal, captured by every round it starts. `this.abort` is
+     * nulled by run()'s finally, so a round that outlives the run (stopped
+     * while an approval was pending — drainRounds returns on abort) would
+     * otherwise read "not aborted" and submit results into the next run's
+     * bookkeeping.
+     */
+    signal) {
+        // Parallel custom tool calls arrive in one tick — debounce them into a
+        // single execution round (the same batching the server applies to the
+        // OpenAI surface's tool_calls frame).
+        let batch = [];
+        let flushTimer = null;
+        const runBatch = () => {
+            const calls = batch;
+            batch = [];
+            void this.executeAndSubmit(calls, cb, signal)
+                .catch((err) => {
+                cb.onNotice(`Tool round failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+            })
+                .finally(() => {
+                this.roundsInFlight--;
+                if (this.roundsInFlight === 0) {
+                    for (const resolve of this.roundsDrained.splice(0))
+                        resolve();
+                }
+            });
+        };
+        const scheduleFlush = () => {
+            if (flushTimer)
+                return;
+            this.roundsInFlight++;
+            flushTimer = setTimeout(() => {
+                flushTimer = null;
+                runBatch();
+            }, 0);
+        };
+        // Server (non-registry) tool bookkeeping for the informational rendering.
+        const serverToolIds = new Set();
+        const serverToolArgs = new Map();
+        const toolState = {
+            serverToolIds,
+            serverToolArgs,
+            enqueue: (call) => { batch.push(call); scheduleFlush(); },
+        };
+        const result = await this.opts.client.startRun(request, {
+            signal,
+            onThreadId: (id) => this.latchThread(id, cb),
+            onEvent: (event) => this.handleRunEvent(event, cb, toolState),
+        });
+        // The stream can close before the debounce tick fires (a run may end in
+        // the same tick as its tool call): flush the batch now instead of dropping
+        // it — the round must still execute and deliver its results.
+        if (flushTimer) {
+            clearTimeout(flushTimer);
+            flushTimer = null;
+            runBatch();
+        }
+        return result;
+    }
+    /**
+     * One AG-UI event from the run stream. Terminal events drive release
+     * detection and the settle flag; `CUSTOM_TOOL_CALL` events feed the
+     * debounced execution round.
+     */
+    handleRunEvent(event, cb, toolState) {
+        switch (event.type) {
+            case "TEXT_MESSAGE_CONTENT":
+                cb.onContent(String(event.delta ?? ""), typeof event.messageId === "string" ? event.messageId : undefined);
+                break;
+            case "THINKING_CONTENT":
+                cb.onReasoning(String(event.delta ?? ""));
+                break;
+            case "RUN_USAGE":
+                this.applyUsage(event, cb);
+                break;
+            case "TOOL_CALL_START": {
+                const id = String(event.toolCallId ?? "");
+                const name = String(event.toolName ?? "");
+                // Client tools are driven by CUSTOM_TOOL_CALL — only server tools
+                // render as informational activity.
+                if (this.opts.registry.get(name))
+                    break;
+                toolState.serverToolIds.add(id);
+                cb.onServerTool({ id, name, phase: "start" });
+                break;
+            }
+            case "TOOL_CALL_ARGS": {
+                const id = String(event.toolCallId ?? "");
+                if (!toolState.serverToolIds.has(id))
+                    break;
+                toolState.serverToolArgs.set(id, (toolState.serverToolArgs.get(id) ?? "") + String(event.delta ?? ""));
+                break;
+            }
+            case "TOOL_CALL_RESULT": {
+                const id = String(event.toolCallId ?? "");
+                const name = String(event.toolName ?? "");
+                if (toolState.serverToolIds.has(id) || !this.opts.registry.get(name)) {
+                    cb.onServerTool({
+                        id, name, phase: "result",
+                        arguments: toolState.serverToolArgs.get(id) ?? "",
+                        result: event.result,
+                        isError: event.isError === true,
+                    });
+                    toolState.serverToolIds.delete(id);
+                    toolState.serverToolArgs.delete(id);
+                    break;
+                }
+                // A client-tool result for a call we have NOT submitted yet means the
+                // server released it (isError) or another client answered it — either
+                // way the call is consumed server-side and submitting would be
+                // rejected as expired. Our own submissions leave `pendingSubmission`
+                // before their request goes out, so their echoes never land here.
+                if (this.pendingSubmission.has(id))
+                    this.markAbandoned([id]);
+                break;
+            }
+            case "CUSTOM_TOOL_CALL": {
+                const id = String(event.toolCallId ?? "");
+                // Replay guard: never execute a tool twice. An id already seen this
+                // session — answered, abandoned, or still in flight (batched /
+                // executing / submitted) — is a replayed event, not a new call.
+                if (this.abandonedToolCalls.has(id) || this.seenToolCallIds.has(id))
+                    break;
+                this.seenToolCallIds.add(id);
+                toolState.enqueue({
+                    id,
+                    name: String(event.toolName ?? ""),
+                    arguments: String(event.arguments ?? "{}"),
+                });
+                break;
+            }
+            case "QUEUED_MESSAGE_DELIVERED": {
+                // The agent injected a steered message into the run — it is part of
+                // the conversation now: release its float into the transcript.
+                const id = String(event.messageId ?? "");
+                if (id)
+                    this.releaseSteer(id);
+                break;
+            }
+            case "RUN_FINISHED": {
+                this.runSettled = true;
+                this.releasePending();
+                this.releasePendingSteers();
+                break;
+            }
+            case "RUN_ERROR": {
+                this.runSettled = true;
+                this.releasePending();
+                this.releasePendingSteers();
+                cb.onNotice(String(event.message ?? "The agent run failed."), "error", typeof event.code === "string" ? event.code : undefined);
+                break;
+            }
+            default:
+                // FILE_CHANGED, STEP_*, MESSAGES_SNAPSHOT (never emitted to
+                // integration listeners), … — not rendered (parity).
+                break;
+        }
+    }
+    applyUsage(event, cb) {
+        const u = event.usage;
+        if (!u)
+            return;
+        this.usage = {
+            input: u.input ?? 0,
+            output: u.output ?? 0,
+            cacheRead: u.cacheRead ?? 0,
+            cacheWrite: u.cacheWrite ?? 0,
+            totalTokens: u.totalTokens ?? 0,
+            turns: u.turns ?? 0,
+            ...(u.cost ? { cost: u.cost } : {}),
+            contextTokens: Number(event.contextTokens ?? 0),
+            contextWindow: Number(event.contextWindow ?? 0),
+        };
+        cb.onUsage(this.usage);
+    }
+    /** Report every call still awaiting submission as released (run ended). */
+    releasePending() {
+        if (this.pendingSubmission.size === 0)
+            return;
+        this.markAbandoned([...this.pendingSubmission.keys()]);
+    }
+    /** Release the float for a steer the agent actually injected (swap to a
+     *  transcript bubble). Unknown ids (another client's steer) are ignored. */
+    releaseSteer(messageId) {
+        const text = this.pendingSteerDeliveries.get(messageId);
+        if (text === undefined)
+            return;
+        this.pendingSteerDeliveries.delete(messageId);
+        this.opts.callbacks.onSteerAccepted?.(text);
+    }
+    /** Release every float still pending — the turn ended before the agent
+     *  injected the message (settled, dropped, stopped, errored). The message
+     *  is persisted in the session either way, so the float must not linger. */
+    releasePendingSteers() {
+        if (this.pendingSteerDeliveries.size === 0)
+            return;
+        const texts = [...this.pendingSteerDeliveries.values()];
+        this.pendingSteerDeliveries.clear();
+        for (const text of texts)
+            this.opts.callbacks.onSteerAccepted?.(text);
+    }
+    /**
+     * Execute a round's client tool calls (approval + plan-mode refusal) and
+     * deliver the results. Runs off the event dispatcher: the run stream stays
+     * attached throughout, so release/continuation events keep flowing while a
+     * human decides.
+     */
+    async executeAndSubmit(calls, cb, signal) {
+        if (calls.length === 0)
+            return;
+        for (const call of calls)
+            this.pendingSubmission.add(call.id);
+        const outputs = await this.executeToolCalls(calls, signal);
+        if (signal.aborted)
+            return;
+        await this.submitRound(calls, outputs, cb, signal);
+    }
+    /**
+     * Resolve once the runner is idle and every queued follow-up turn has been
+     * delivered. Headless runs await this before exiting so a queued turn is
+     * never cut off by process exit.
+     */
+    async waitForIdle() {
+        let chain;
+        do {
+            chain = this.followUpChain;
+            await chain;
+        } while (chain !== this.followUpChain);
+    }
+    /**
+     * Deliver a round's tool results, reconciling against the server's truth
+     * first when it advertises `toolCallExpiry`:
+     *
+     *  - still pending (exact id) → submit as-is (native tool result, same run);
+     *  - the model retried the same action (same name + canonical args) → adopt
+     *    the retry's id and submit the already-executed result (no double side
+     *    effect);
+     *  - other pending calls the client never executed → run them through the
+     *    normal approval+execution path and submit their results too;
+     *  - outputs with no matching pending call → the server already released
+     *    the call; the result is discarded (the agent moved on when the call
+     *    was released — a follow-up message would only confuse it).
+     *
+     * A submission that still races a release (pre-stream 400 or the
+     * INPUT_REJECTED frame) re-reconciles once.
+     */
+    async submitRound(calls, outputs, cb, signal) {
+        let remaining = outputs;
+        const released = [];
+        // Separate budgets for the two recoveries: an expiry re-reconcile and a
+        // transient-delivery retry are different failures, and a shared bound let
+        // the compound case (transient blip, then an expiry race on the retry)
+        // exit the loop before the re-reconcile ran — discarding results for ids
+        // the server still held pending (all-or-nothing rejection).
+        let transientRetriesLeft = 1;
+        let expiryReconcilesLeft = 2;
+        while (remaining.length > 0) {
+            // No thread to submit to (unreachable in practice — the run stream
+            // latches the id before any event): the post-loop pass discards them.
+            if (!this.threadId)
+                break;
+            const reconciled = await this.reconcileRound(calls, remaining, cb, signal);
+            remaining = reconciled.live;
+            // Released results leave the pending set: they are discarded, not
+            // submitted — keeping them pending would double-announce the release
+            // after the round.
+            for (const output of reconciled.released) {
+                released.push(output);
+                this.pendingSubmission.delete(output.tool_call_id);
+            }
+            if (remaining.length === 0)
+                break;
+            // Optimistic removal: the server echoes our own TOOL_CALL_RESULT events
+            // on the run stream, and they must never be read as a release.
+            for (const output of remaining)
+                this.pendingSubmission.delete(output.tool_call_id);
+            try {
+                // Tool-result submissions carry no `tools` — the server ignores the
+                // field on the resume path (the paused run keeps the tools it started
+                // with), so sending them is pure payload.
+                await this.opts.client.sendRunMessages(this.threadId, remaining.map(toAguiToolResult), {
+                    signal,
+                });
+                return;
+            }
+            catch (err) {
+                if (isToolCallExpired(err)) {
+                    // Released between the reconcile and the submission — re-reconcile;
+                    // the reported ids are the ones the server already dropped (forced:
+                    // the ids left the pending set when their request went out). The
+                    // next pass separates them from siblings that are still pending:
+                    // those must be re-submitted, not dropped with the expired ones.
+                    const expiredIds = readExpiredIds(err);
+                    if (expiredIds.length > 0)
+                        this.markAbandoned(expiredIds, true);
+                    if (expiryReconcilesLeft-- > 0)
+                        continue;
+                    // The server keeps refusing these ids despite the reconcile — as
+                    // far as it is concerned they are released; discard like the
+                    // post-loop pass would.
+                    break;
+                }
+                // Aborted: no retry or fallback — the stop path releases the calls.
+                if (signal.aborted) {
+                    for (const output of remaining)
+                        this.pendingSubmission.add(output.tool_call_id);
+                    throw err;
+                }
+                // A non-expired failure (network blip, 5xx) must not silently drop
+                // executed results — the agent is still waiting on the call. Retry
+                // once after a short delay; the loop's reconcile re-validates the
+                // pending set before the retry.
+                if (transientRetriesLeft-- > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, SUBMIT_RETRY_DELAY_MS));
+                    continue;
+                }
+                // Persistent failure: the results can no longer be delivered as tool
+                // results, but leaving the call unanswered would hang the run until
+                // the server's 30-min lease releases it. Unblock the agent with an
+                // error result — the tool DID run, its outcome is unknown.
+                const undeliverable = remaining.map((output) => ({
+                    ...output,
+                    output: "Error: the client could not deliver this tool's result (delivery failed twice). " +
+                        "The tool DID execute on the user's machine, but its output is unavailable. " +
+                        "Treat the outcome as unknown and proceed accordingly.",
+                    isError: true,
+                }));
+                try {
+                    await this.opts.client.sendRunMessages(this.threadId, undeliverable.map(toAguiToolResult), {
+                        signal,
+                    });
+                    cb.onNotice(`Failed to deliver ${remaining.length} tool result(s) — the agent was told their outcome is unknown.`, "error");
+                    return;
+                }
+                catch {
+                    // Even the error result failed (the connection is gone): restore
+                    // the ids so the release detection stays consistent (a later
+                    // TOOL_CALL_RESULT / RUN_FINISHED can still mark them), then
+                    // surface the original failure — the dropped-stream reconcile
+                    // path takes over from here.
+                    for (const output of remaining)
+                        this.pendingSubmission.add(output.tool_call_id);
+                    throw err;
+                }
+            }
+        }
+        // Results that never became submittable (no thread, or released on every
+        // reconcile attempt): the server already answered those calls — discard.
+        released.push(...remaining);
+        this.discardReleasedResults(released, cb);
+    }
+    /**
+     * Compare a round's outputs against the server's pending list. Returns the
+     * outputs that can still be delivered (exact ids + adopted retries + newly
+     * executed pending calls) and the ones whose calls the server already
+     * released (discarded by the caller).
+     */
+    async reconcileRound(calls, outputs, cb, signal) {
+        if (!this.threadId)
+            return { live: outputs, released: [] };
+        let detail = null;
+        try {
+            // Also the wake trigger when the sandbox was paused (integration traffic
+            // auto-wakes; the client retries 503/504 at the transport layer).
+            detail = await this.opts.client.getSession(this.threadId);
+        }
+        catch {
+            // Can't verify — submit as-is and let the typed error path recover.
+            return { live: outputs, released: [] };
+        }
+        if (detail.last_run_interrupted_at)
+            this.lastRunInterruptedAt = detail.last_run_interrupted_at;
+        const pending = detail.pending_tool_calls ?? [];
+        const unmatched = new Map(pending.map((p) => [p.id, p]));
+        const live = [];
+        const released = [];
+        for (const output of outputs) {
+            if (unmatched.has(output.tool_call_id)) {
+                live.push(output);
+                unmatched.delete(output.tool_call_id);
+                continue;
+            }
+            const call = calls.find((c) => c.id === output.tool_call_id);
+            const adopted = call ? findAdoptableCall(call, [...unmatched.values()]) : undefined;
+            if (adopted) {
+                live.push({ ...output, tool_call_id: adopted.id });
+                unmatched.delete(adopted.id);
+                cb.onNotice(`Re-attached the result of ${call?.name ?? "a tool call"} to the agent's retry.`, "info");
+                continue;
+            }
+            released.push(output);
+        }
+        // Pending calls this client never executed (e.g. the model retried with
+        // different arguments): execute them through the normal approval path so
+        // the run isn't left waiting on a call nobody will answer.
+        if (unmatched.size > 0) {
+            const extraCalls = [...unmatched.values()].map((p) => ({
+                id: p.id,
+                name: p.name,
+                arguments: p.arguments,
+            }));
+            // Register before execution (same as event-driven calls via
+            // executeAndSubmit) so a release arriving mid-execution is surfaced by
+            // the release filter instead of only surfacing at submission time.
+            for (const call of extraCalls)
+                this.pendingSubmission.add(call.id);
+            live.push(...await this.executeToolCalls(extraCalls, signal));
+        }
+        return { live, released };
+    }
+    /**
+     * Discard results whose calls the server already released. The agent
+     * answered those calls when they were released — delivering the result now
+     * (as a follow-up message) would only confuse it. The release itself was
+     * usually already surfaced (run stream / channel); only announce the
+     * discard when this is the first the user hears of it.
+     */
+    discardReleasedResults(released, cb) {
+        if (released.length === 0)
+            return;
+        if (!released.every((output) => this.abandonedToolCalls.has(output.tool_call_id))) {
+            cb.onNotice(`The server had released ${released.length} tool call(s) (${this.releaseReason()}); the result(s) were discarded.`, "warn");
+        }
+    }
+    /** Human reason for a released call, preferring a known server restart. */
+    releaseReason() {
+        return this.lastRunInterruptedAt
+            ? "the run was interrupted by a server restart"
+            : "no response in time";
+    }
+    /**
+     * Mark calls as released and tell the user once. Only calls this turn is
+     * actually waiting on are surfaced (a result for an older call arriving on
+     * the stream/channel is not actionable) — `force` is for ids the server
+     * itself reported as expired, which have already left the pending set.
+     */
+    markAbandoned(toolCallIds, force = false) {
+        const newly = toolCallIds.filter((id) => (force || this.pendingSubmission.has(id)) && !this.abandonedToolCalls.has(id));
+        for (const id of newly)
+            this.abandonedToolCalls.add(id);
+        if (newly.length === 0)
+            return;
+        // A released call must never run — cancel an approval waiting on it.
+        this.opts.approval.cancelPending(newly);
+        this.opts.callbacks.onNotice(`The server released ${newly.length} tool call(s) (${this.releaseReason()}).`, "warn");
+    }
+    latchThread(threadId, cb) {
+        if (threadId && threadId !== this.threadId) {
+            this.threadId = threadId;
+            cb.onThread(threadId);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Fallback event channel (reconcile window only — no run stream attached)
+    // -------------------------------------------------------------------------
+    /** Open the session event subscription for the recovery window (capability-gated). */
+    startEventSubscription() {
+        if (!this.threadId)
+            return;
+        this.stopEventSubscription();
+        this.eventChannelDown = false;
+        const abort = new AbortController();
+        this.eventsAbort = abort;
+        void this.runEventSubscription(abort.signal);
+    }
+    stopEventSubscription() {
+        this.eventsAbort?.abort();
+        this.eventsAbort = null;
+    }
+    /**
+     * Subscribe → reconnect loop. Bounded (see MAX_EVENT_RECONNECTS) and stopped
+     * as soon as the outstanding call is known to be released, so a paused
+     * sandbox is woken at most a few times and never kept awake by the channel.
+     *
+     * Loss and exhaustion are surfaced (once each, state change only): a long
+     * approval wait can outlive the sandbox, and the user staring at the
+     * approval card deserves to know the channel went away.
+     */
+    async runEventSubscription(signal) {
+        for (let attempt = 0; attempt < MAX_EVENT_RECONNECTS && !signal.aborted; attempt++) {
+            try {
+                await this.opts.client.openSessionEvents(this.threadId, {
+                    signal,
+                    onEvent: (event) => this.handleSessionEvent(event),
+                });
+            }
+            catch (err) {
+                if (signal.aborted || (err instanceof Error && err.name === "AbortError"))
+                    return;
+                // Retrying cannot fix a bad key or a deleted session — and every retry
+                // wakes a paused sandbox, so stop instead of looping. Say so: the
+                // approval wait just lost its safety net.
+                if (isPermanentEventChannelError(err)) {
+                    this.opts.callbacks.onNotice("Session event channel unavailable — a release while you decide will only surface when the result is submitted.", "warn");
+                    return;
+                }
+                // Network drop / wake 503 — retry after a delay.
+            }
+            if (signal.aborted)
+                return;
+            // Nothing left to watch: stop instead of re-waking a paused sandbox.
+            if (this.pendingSubmission.size === 0)
+                return;
+            // The channel ended while a result is still owed — announce the outage
+            // once, not per attempt.
+            if (!this.eventChannelDown) {
+                this.eventChannelDown = true;
+                this.opts.callbacks.onNotice("Lost the session event channel — retrying (the sandbox may be waking)…", "warn");
+            }
+            if (attempt === MAX_EVENT_RECONNECTS - 1) {
+                this.opts.callbacks.onNotice("Stopped watching the session — a release while you decide will only surface when the result is submitted.", "warn");
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, this.opts.eventReconnectDelayMs ?? EVENT_RECONNECT_DELAY_MS));
+        }
+    }
+    /**
+     * Handle one fallback-channel event. The channel is subscribed only when no
+     * run stream is attached (the recovery window), so an idle snapshot or a
+     * terminal run event means the calls still awaiting submission were
+     * released. Echoes of our own submissions are already out of
+     * `pendingSubmission` and can never be read as releases.
+     */
+    handleSessionEvent(event) {
+        if (this.eventChannelDown) {
+            this.eventChannelDown = false;
+            this.opts.callbacks.onNotice("Session event channel reconnected.", "info");
+        }
+        if (event.type === "MESSAGES_SNAPSHOT") {
+            if (typeof event.lastRunInterruptedAt === "number")
+                this.lastRunInterruptedAt = event.lastRunInterruptedAt;
+            // The channel's initial snapshot always carries a status; an explicit
+            // non-running status with results still owed means the run is gone.
+            if (typeof event.status === "string" && event.status !== "running" && this.pendingSubmission.size > 0) {
+                this.markAbandoned([...this.pendingSubmission.keys()]);
+                this.stopEventSubscription();
+            }
+            return;
+        }
+        if (event.type === "QUEUED_MESSAGE_DELIVERED") {
+            // Delivery can land while the run stream is down — the fallback channel
+            // replays it (same release as the run-stream handler).
+            const id = typeof event.messageId === "string" ? event.messageId : "";
+            if (id)
+                this.releaseSteer(id);
+            return;
+        }
+        if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") {
+            this.releasePendingSteers();
+            if (this.pendingSubmission.size > 0) {
+                this.markAbandoned([...this.pendingSubmission.keys()]);
+                this.stopEventSubscription();
+            }
+            return;
+        }
+        // Any result for a still-pending id is a release: the server dropped the
+        // call (isError) or another client answered it. Same state-based rule as
+        // the run stream — our own echoes can't be pending here (ids leave the
+        // set before their submission request goes out).
+        if (event.type === "TOOL_CALL_RESULT") {
+            const id = typeof event.toolCallId === "string" ? event.toolCallId : "";
+            if (this.pendingSubmission.has(id))
+                this.markAbandoned([id]);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Tool execution
+    // -------------------------------------------------------------------------
+    parseCall(call) {
+        const raw = call.arguments?.trim() || "{}";
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return { call, args: {}, parseError: "arguments must be a JSON object" };
+            }
+            return { call, args: parsed };
+        }
+        catch (err) {
+            return { call, args: {}, parseError: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /** Read-only calls run concurrently; mutating and unknown calls serialize. */
+    async executeToolCalls(calls, signal) {
+        const outputs = [];
+        let index = 0;
+        while (index < calls.length && !signal.aborted) {
+            // Batch consecutive read-only calls; anything mutating (per-call) or
+            // unknown serializes for approval and ordering.
+            const batch = [];
+            while (index < calls.length) {
+                const candidate = this.parseCall(calls[index]);
+                if (isMutatingCall(this.opts.registry.get(candidate.call.name), candidate.args))
+                    break;
+                batch.push(candidate);
+                index++;
+            }
+            if (batch.length > 0) {
+                const results = await Promise.all(batch.map((parsed) => this.executeOne(parsed, signal)));
+                outputs.push(...results.filter(isToolOutput));
+                continue;
+            }
+            const result = await this.executeOne(this.parseCall(calls[index]), signal);
+            if (result !== null)
+                outputs.push(result);
+            index++;
+        }
+        return outputs;
+    }
+    /**
+     * Execute one client tool call. Returns null when the call was cancelled
+     * (server released it, or the run was stopped while the user decided): the
+     * tool never ran and nothing may be submitted for it.
+     */
+    async executeOne(parsed, signal) {
+        const cb = this.opts.callbacks;
+        const { call, args } = parsed;
+        if (parsed.parseError) {
+            const output = `Error: invalid JSON arguments (${parsed.parseError}).`;
+            cb.onToolStart(call, `${call.name} (invalid args)`);
+            cb.onToolEnd(call, output, true);
+            return { tool_call_id: call.id, output, isError: true };
+        }
+        const handler = this.opts.registry.get(call.name);
+        if (!handler) {
+            const output = `Error: unknown tool "${call.name}". Available: ${this.opts.registry.all().map((t) => t.definition.function.name).join(", ")}.`;
+            cb.onToolStart(call, call.name);
+            cb.onToolEnd(call, output, true);
+            return { tool_call_id: call.id, output, isError: true };
+        }
+        let summary;
+        try {
+            summary = handler.summarize(args);
+        }
+        catch {
+            summary = call.name;
+        }
+        cb.onToolStart(call, summary);
+        try {
+            // Mode is enforced here rather than by hiding tools: the advertised tool
+            // set stays constant (prompt-cache stable) and plan mode refuses any
+            // mutating call with a model-readable error. Checked before approval —
+            // plan mode is not an ASK/AUTO question. Mutation is per-call for tools
+            // whose direction decides it (transfer get vs put/list).
+            const mutating = isMutatingCall(handler, args);
+            if (mutating && this.mode === "plan") {
+                const output = `Error: cannot use ${call.name} in plan mode — it changes your machine. Switch to Coding mode (Tab) and retry.`;
+                cb.onToolEnd(call, output, true);
+                return { tool_call_id: call.id, output, isError: true };
+            }
+            // Outside-workspace calls are asked about even in AUTO: a pre-resolve
+            // check (symlink-aware) routes them through approval before the tool runs.
+            // In-workspace read-only calls skip approval entirely (the policy would
+            // wave them through anyway), which also keeps bookkeeping tools like
+            // local_update_todo usable in plan mode.
+            const outside = !this.opts.allowOutside
+                && await toolRequestOutsideWorkspace(call.name, args, this.opts.workspace);
+            if (mutating || outside) {
+                const outcome = await this.opts.approval.approve({
+                    tool: call.name, summary, outsideWorkspace: outside, callId: call.id, mutating,
+                });
+                if (outcome === "cancelled") {
+                    // The server released the call (or the run was stopped) while the
+                    // user was deciding — the tool must not run, and there is nothing
+                    // to submit: the server already answered the call.
+                    this.pendingSubmission.delete(call.id);
+                    const reason = this.stopped ? "the run was stopped" : "the server released this call";
+                    cb.onToolEnd(call, `Cancelled — ${reason}.`, true);
+                    return null;
+                }
+                if (outcome !== "approved") {
+                    const output = outcome === "timeout"
+                        ? this.opts.approval.timeoutMessage
+                        : this.opts.approval.deniedMessage;
+                    cb.onToolEnd(call, output, true);
+                    return { tool_call_id: call.id, output, isError: true };
+                }
+            }
+            // An approved outside call runs with the confinement check lifted for
+            // this invocation only.
+            const ctx = outside ? { ...this.toolContext(signal), allowOutside: true } : this.toolContext(signal);
+            const output = await handler.run(args, ctx);
+            cb.onToolEnd(call, output, false);
+            return { tool_call_id: call.id, output };
+        }
+        catch (err) {
+            const output = `Error: ${err instanceof Error ? err.message : String(err)}`;
+            cb.onToolEnd(call, output, true);
+            return { tool_call_id: call.id, output, isError: true };
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Recovery
+    // -------------------------------------------------------------------------
+    /**
+     * The run stream died before the run settled. Reconcile against the durable
+     * session: if the backend is waiting on tool calls, re-run READ-ONLY ones
+     * (safe) and fail mutating ones rather than re-applying side effects
+     * silently. The event channel watches for a release while the round is
+     * finished (no request stream is attached in this window).
+     */
+    async reconcile(cb, signal) {
+        if (!this.threadId) {
+            cb.onNotice("Connection dropped before a session id was assigned.", "error");
+            return;
+        }
+        cb.onNotice("Connection dropped — reconciling session state…", "warn");
+        let detail = null;
+        try {
+            detail = await this.opts.client.getSession(this.threadId);
+        }
+        catch {
+            cb.onNotice("Could not reach the server to reconcile.", "error");
+            return;
+        }
+        if (detail.last_run_interrupted_at)
+            this.lastRunInterruptedAt = detail.last_run_interrupted_at;
+        const pending = detail.pending_tool_calls ?? [];
+        if (pending.length > 0) {
+            this.startEventSubscription();
+            const calls = [];
+            const outputs = [];
+            for (const item of pending) {
+                // A stop pressed mid-reconcile must not keep re-executing calls —
+                // same rule as executeToolCalls' loop guard.
+                if (signal.aborted)
+                    break;
+                const call = { id: item.id, name: item.name, arguments: item.arguments };
+                calls.push(call);
+                // Register before execution (same as executeAndSubmit/reconcileRound):
+                // a release arriving while an approval is pending must cancel it via
+                // the release filter, not wait out the approval timeout.
+                this.pendingSubmission.add(item.id);
+                const handler = this.opts.registry.get(item.name);
+                const parsed = this.parseCall(call);
+                if (!isMutatingCall(handler, parsed.args)) {
+                    const result = await this.executeOne(parsed, signal);
+                    if (result !== null)
+                        outputs.push(result);
+                }
+                else {
+                    const output = "Error: tool was not re-executed after the CLI reconnected (mutating tools are never replayed automatically). Re-run it if needed.";
+                    cb.onToolStart(call, item.name);
+                    cb.onToolEnd(call, output, true);
+                    outputs.push({ tool_call_id: item.id, output, isError: true });
+                }
+            }
+            if (signal.aborted) {
+                // Abandoned mid-round: the server releases the un-answered calls when
+                // the lease expires — submitting partial output under an aborted
+                // signal would only surface a confusing AbortError.
+                this.stopEventSubscription();
+                return;
+            }
+            try {
+                // Same delivery path as an event-driven round: reconcile against the
+                // server's pending list, retry a transient failure, and drop only the
+                // ids the server reports as expired. A raw batch send would discard
+                // every result when one id raced a release.
+                await this.submitRound(calls, outputs, cb, signal);
+                cb.onNotice("Session resumed after reconnect.", "info");
+            }
+            catch (err) {
+                cb.onNotice(`Failed to resume: ${err instanceof Error ? err.message : String(err)}`, "error");
+            }
+            finally {
+                this.stopEventSubscription();
+            }
+            return;
+        }
+        cb.onNotice(`Run state on the server: ${detail.status}. Use /sessions to inspect it.`, "warn");
+    }
+}
+/** Convert persisted session usage into the live-usage shape the UI renders. */
+export function usageFromSession(usage) {
+    if (!usage)
+        return null;
+    return {
+        input: usage.tokenUsage.input,
+        output: usage.tokenUsage.output,
+        cacheRead: usage.tokenUsage.cacheRead ?? 0,
+        cacheWrite: usage.tokenUsage.cacheWrite ?? 0,
+        totalTokens: usage.tokenUsage.totalTokens,
+        turns: usage.tokenUsage.turns,
+        ...(usage.tokenUsage.cost ? { cost: usage.tokenUsage.cost } : {}),
+        contextTokens: usage.contextTokens,
+        contextWindow: usage.contextWindow,
+    };
+}