@chrok/pi-braid 0.3.3 → 0.3.5

package/README.md

@@ -26,6 +26,8 @@ It registers:
 - `braid_cancel` — cancel a job with `{ "jobId": "..." }`.
 - `/braid [jobId]` — open a live flow panel in interactive Pi.
 - `/braid:review [target or focus]` — run a bounded parallel review/fix loop.
+- `/braid:clear` — clear the progress widget above the editor; run it again while
+  the widget is empty to restore what was cleared.
 
 Submission and completion reminders use short session handles such as `job-1`.
 Status, cancellation and the panel accept either that exact handle or the original
@@ -42,8 +44,10 @@ On completion, failure, or cancellation, the extension sends a custom
 Pi queues it as steering during streaming: it enters context after the current
 assistant response and its entire tool batch, before the next model step. It
 does not wait for the whole foreground task to finish or skip remaining tools.
-When idle, it starts a new agent turn automatically. The agent should wait for
-this reminder rather than poll.
+When idle, it starts a new agent turn automatically. Tool descriptions, the
+system prompt, and the submission receipt tell the agent to continue independent
+work, or end its turn if it needs the result, and not to sleep, use a timer, or
+poll in a loop to wait for the job.
 Stopping the foreground response does not stop background jobs.
 
 Jobs live in memory for the current Pi session. Quitting, reloading extensions,
@@ -105,9 +109,10 @@ All four types accept `model`, `notifyOnCompletion`, `pauseAfter`, and
 default to writable worktrees in Git; outside Git, all workers are read-only.
 The model-facing schema exposes these fields in one object with a `type` enum;
 core validation enforces the type-specific requirements before a submission or
-update takes effect. Submission/update replies echo the accepted node types,
-model overrides, policies, and edges without repeating prompts. If a definition
-problem repeats, inspect/report the mismatch instead of launching more probe jobs.
+update takes effect. The submission reply gives the job ID and how to wait for
+it; it does not repeat the graph the agent just sent. Update replies list the
+resulting graph without prompts. If a definition problem repeats,
+inspect/report the mismatch instead of launching more probe jobs.
 
 Edges use exact node IDs in `from` and `to`. `choice` is an exact label declared
 by the source decision; omitting it makes the edge unconditional. Pass `edges: []`
@@ -150,7 +155,7 @@ drops the queued message. Session shutdown suppresses delivery.
 
 Set `pauseAfter: true` to hold an execution's outgoing scheduling and receive a
 pause reminder. Independent branches continue. Fetch `braid_status` to obtain
-`execution.revision` and `execution.pausedExecutionIds`, then:
+the current graph revision and paused execution IDs, then:
 
 ```json
 {
@@ -176,9 +181,9 @@ Pause reminders describe the event when it occurred: check current status and
 paused IDs before attempting an update/resume, since the job can time out or be
 cancelled before the parent handles the reminder.
 
-Focused `braid_status` reads also include the current control fields; the
-returned `node.revision` is the revision captured when that invocation started.
-Use `execution.revision` for updates even when inspecting an older invocation.
+Focused `braid_status` reads also start with the current control fields: graph
+status, revision, and paused execution IDs. Use that current revision for
+updates even when inspecting an older invocation.
 After cancellation or finalization there are no resumable paused executions;
 the event log still records where pauses occurred.
 
@@ -212,7 +217,10 @@ Braid job-1 · running · 2/5 done · review
 The widget shows node progress, active node IDs, paused gates, and failures.
 It shows up to three active jobs, with an overflow count for the rest. When no
 jobs are active, the newest job's final completed/failed/cancelled status stays
-visible until another job is submitted or the session ends. Counts use the
+visible until another job is submitted or the session ends. Run `/braid:clear`
+to clear the widget: it clears every job submitted so far, including running
+ones, and jobs submitted afterwards still appear. Running it again while the widget
+is empty restores the most recently cleared jobs. Counts use the
 latest state of each current node definition; failed and skipped nodes count as
 done, and reruns or live edits can change progress and totals. RPC, JSON, and
 print modes do not create a terminal widget.
@@ -241,9 +249,51 @@ activity (see below)—stays pinned at the top while the session scrolls. The
 session follows the newest lines; scroll up to pause, and press End to follow again. Left/Right switch between
 invocations of the same node (for example loop iterations), and ctrl+o expands
 tool output. Escape steps back one level—session, then node selection, then the
-graph—and closes the panel from the graph; `q` closes it from anywhere. Sessions
-are read-only. Running invocations and the 20 most recently finished ones per
-job keep their session; older ones show the summary and activity history.
+graph—and closes the panel from the graph; `q` closes it from anywhere. Running
+invocations and the 20 most recently finished ones per job keep their session;
+older ones show the summary and activity history.
+
+### Assistant
+
+Press Tab to open an assistant and Tab again to hide it. While it is open,
+every key goes to it, including `q` and `c`; type a question and press Enter.
+Escape stops an answer in progress, or hides the assistant. PgUp/PgDn or the
+mouse wheel scroll the conversation. A panel at least 100 columns wide shows
+the assistant beside the graph or session; a narrower one shows it in their
+place.
+
+Conversations are scoped. On the graph, the assistant talks about the whole
+job. With a node selected (`v`) or its session open, it uses that node's own
+conversation, shared by all of the node's executions; each question says which
+execution is shown. Each scope keeps its history for the Pi session, including
+while the assistant or the panel is hidden.
+
+In fullscreen mode the mouse wheel also scrolls the left side: the graph, a
+node session, or a node's details and history. Scrolling a session up stops it
+following new output; scrolling back to the bottom resumes.
+
+The assistant uses the main session's current model. It does not see the main
+conversation; each question tells it what the panel shows (the graph, the
+selected node, or the open session), and it reads the job through its own
+tools: job status and graph, an execution's details and activity, and the
+latest messages of a worker's conversation. It cannot edit the graph, cancel,
+or resume; ask the main agent for that.
+
+To steer a running execution, tell the assistant what it should do. The
+assistant messages that execution for you, and only when you ask. The message
+waits, shown as pending in the execution's session, and is delivered before the
+worker's next model request. A tool batch that is running finishes first and is
+never interrupted. If it arrives while the worker is writing its final answer,
+the worker gets one more round to take it into account. The worker receives it
+labelled as a message from the supervising human, separate from the node prompt
+and predecessor outputs; it cannot lift tool, budget, workspace, or decision
+constraints (a decision node that has already called `decide` keeps its
+choice). Delivered messages appear in the session, in the activity history, in
+the event log, and in the execution's `humanInputs` in `braid_status` results,
+so it stays visible that the result did not come from the graph alone. Messages
+still pending when the execution ends are marked as not delivered and are not
+recorded as input. Finished executions, including those held by `pauseAfter`,
+cannot be messaged.
 
 Run `/braid <jobId> <nodeId>` to open that node's latest invocation directly in
 the session view, or `/braid <jobId> <executionId>` for an exact invocation such
@@ -270,9 +320,15 @@ counts, and the execution log. Active nodes are marked `▶ ACTIVE`. The status
 tool also renders a flowchart; expand its result to see more log events.
 When selecting `nodeId` or `executionId`, it instead shows that invocation's
 output/error and activity, with the full text and history available on expansion.
-The JSON includes `activity` with the latest 40 history entries; pass
+
+The Braid tools return plain-text documents to the model, not JSON. A
+whole-job read lists the control state, every execution, their outputs,
+workspaces, and the current graph without prompts. A focused read shows one
+execution's output and its activity with the latest 40 history entries; pass
 `activityBefore` with an entry sequence to page earlier ones. While the invocation
-runs, `activity` comes before `node` so it survives preview truncation.
+runs, the activity comes before the output so it survives preview truncation.
+Worker `git` results read like Pi's bash output, and `decide` returns
+`Recorded choice: <choice>`.
 
 `/braid` now opens this panel; it no longer arms the next prompt. To request
 Braid explicitly, ask the agent to analyze the task using Braid.
@@ -283,11 +339,9 @@ model lookup, credentials/OAuth, provider transport, filesystem tool execution,
 and token/cost accounting. The first
 whole-job `braid_status` retrieval of a finished job reports its accumulated Pi usage;
 subsequent retrievals do not count the same usage again.
-Use the status response's `usage` for Pi totals, including completed provider
-rounds from nodes that later fail or time out. Saved final result files expose
-the same accounting as `piUsage`; core `metadata.usage` only includes usage
-returned by runners. Large running status reads save a complete snapshot too,
-so truncation never requires waiting for job completion to inspect the graph.
+The whole-job status text reports Pi's totals as `Usage`, including completed
+provider rounds from nodes that later fail or time out; core `metadata.usage`
+only includes usage returned by runners.
 
 ## When Pi will use Braid
 
@@ -331,7 +385,7 @@ only the current source IDs and diagnoses missing, duplicate or unexpected IDs.
 
 ## Install from npm
 
-Requires Node.js 22.19+ and Pi 1.0.1 (the tested version):
+Requires Node.js 22.19+ and Pi 1.2.0 (the tested version):
 
 ```sh
 pi install npm:@chrok/pi-braid
@@ -342,7 +396,7 @@ The package depends on the exact matching `@chrok/braid` release; npm installs
 core automatically. It does not bundle core or depend on a source checkout.
 Pi supplies its core peer packages at runtime.
 Their wildcard ranges follow Pi's packaging convention, not universal version
-compatibility. Development and CI pin Pi 1.0.1.
+compatibility. Development and CI pin Pi 1.2.0.
 
 ## Install this local checkout in Pi
 
@@ -571,9 +625,9 @@ writes already made. Core waits for tracked writes, preserves checkpoints, and
 removes worker worktrees before completing cancellation.
 
 The tool output is capped at 50KB/2000 lines to protect Pi context. When exceeded,
-the adapter writes a full JSON result to a temporary file (mode 600 on POSIX;
-inherited ACLs on Windows) and includes
-its path in the tool output.
+the adapter writes the complete text to a temporary file (mode 600 on POSIX;
+inherited ACLs on Windows) and ends the preview with its path, for running jobs
+as well as finished ones.
 
 For a test of proactive selection, start a fresh Pi turn with a task such as:
 

package/dist/assistant.js

@@ -0,0 +1,345 @@
+import { Type, validateToolCall, } from "@earendil-works/pi-ai";
+import { truncateHead } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+/** Bounds a single answer, independently of how the model behaves. */
+const MAX_ROUNDS = 24;
+const ACTIVITY_ENTRIES = 40;
+const TRANSCRIPT_MESSAGES = 20;
+const MESSAGE_PREVIEW = 1500;
+const id = (description) => Type.String({ minLength: 1, description });
+const TOOLS = [
+    {
+        name: "job_status",
+        description: "Read this job's goal, status, revision, graph definition (node prompts and edges), the latest result per node, and every execution with its status.",
+        parameters: Type.Object({}, { additionalProperties: false }),
+    },
+    {
+        name: "execution_details",
+        description: "Read one execution: status, output or error, decision, workspace, usage, human inputs, and live activity (phase, model/tool waits, recent history). Pass executionId, or nodeId for the node's latest execution.",
+        parameters: Type.Object({
+            executionId: Type.Optional(id("Exact execution ID.")),
+            nodeId: Type.Optional(id("Node ID; reads its latest execution.")),
+            activityBefore: Type.Optional(Type.Integer({ minimum: 1, description: "Page activity entries before this sequence number." })),
+        }, { additionalProperties: false }),
+    },
+    {
+        name: "execution_transcript",
+        description: "Read the latest messages of one execution's worker conversation: assistant text, tool calls and results, and human messages. Available while it runs and for recently finished executions.",
+        parameters: Type.Object({
+            executionId: id("Exact execution ID."),
+            last: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, description: `Number of latest messages; default ${TRANSCRIPT_MESSAGES}.` })),
+        }, { additionalProperties: false }),
+    },
+    {
+        name: "message_execution",
+        description: "Send a message to a running execution's worker on the user's behalf. It is delivered before the worker's next model request (a running tool batch finishes first) and is recorded as human input on the execution. Use only when the user asks to guide, correct, or inform a running execution. Write a self-contained instruction the worker can act on; it cannot see this conversation.",
+        parameters: Type.Object({
+            executionId: id("Exact ID of a running execution."),
+            message: id("The instruction for the worker."),
+        }, { additionalProperties: false }),
+    },
+];
+const short = (value) => typeof value === "string" ? (value.length > 13 ? `${value.slice(0, 8)}…` : value) : "?";
+const target = (args) => args.executionId !== undefined ? `execution ${short(args.executionId)}` : args.nodeId !== undefined ? `node ${JSON.stringify(args.nodeId)}` : "";
+/** Compact tool cards: what was read or sent, with full results on ctrl+o. */
+function renderer(call) {
+    return {
+        renderCall: (args, theme) => new Text(call(args ?? {}, theme), 0, 0),
+        renderResult: (result, options, theme) => {
+            const text = textOf(result.content);
+            const first = text.split("\n").find(line => line.trim()) ?? "";
+            return new Text(options.expanded ? text : theme.fg("dim", first.length > 160 ? `${first.slice(0, 159)}…` : first), 0, 0);
+        },
+    };
+}
+const RENDERERS = new Map([
+    ["job_status", renderer((_args, theme) => theme.fg("toolTitle", theme.bold("Read job status")))],
+    ["execution_details", renderer((args, theme) => theme.fg("toolTitle", theme.bold("Read details")) + " " + theme.fg("muted", target(args)))],
+    ["execution_transcript", renderer((args, theme) => theme.fg("toolTitle", theme.bold("Read conversation")) + " " + theme.fg("muted", `of ${target(args)}`))],
+    ["message_execution", renderer((args, theme) => theme.fg("warning", theme.bold("✎ Message")) + " " + theme.fg("muted", `to ${target(args)}`) +
+            (typeof args.message === "string" ? `\n${args.message}` : ""))],
+]);
+const clip = (text, max = MESSAGE_PREVIEW) => text.length <= max ? text : `${text.slice(0, max)}… [${text.length - max} more characters]`;
+const textOf = (content) => content.flatMap(block => block.type === "text" && block.text ? [block.text] : []).join("\n");
+function describeTranscript(transcript, last) {
+    const lines = [];
+    const messages = transcript.messages.slice(-last);
+    if (messages.length < transcript.messages.length)
+        lines.push(`[${transcript.messages.length - messages.length} earlier messages omitted]`);
+    else
+        lines.push(`[node prompt] ${clip(transcript.intro.prompt)}`);
+    for (const message of messages) {
+        if (message.role === "human")
+            lines.push(`[human input · ${message.delivered ? "delivered" : "not delivered"}] ${clip(message.text)}`);
+        else if (message.role === "toolResult")
+            lines.push(`[${message.toolName} ${message.isError ? "error" : "result"}] ${clip(textOf(message.content), 800)}`);
+        else if (message.role === "assistant") {
+            for (const block of message.content) {
+                if (block.type === "text" && block.text.trim())
+                    lines.push(`[assistant] ${clip(block.text)}`);
+                else if (block.type === "toolCall")
+                    lines.push(`[tool call ${block.name}] ${clip(JSON.stringify(block.arguments), 400)}`);
+            }
+            if (message.stopReason === "error" || message.stopReason === "aborted")
+                lines.push(`[${message.stopReason}] ${message.errorMessage ?? ""}`);
+        }
+    }
+    if (transcript.streaming)
+        lines.push(`[assistant, streaming] ${clip(textOf(transcript.streaming.content))}`);
+    for (const callId of transcript.running.keys())
+        lines.push(`[tool running] ${callId}`);
+    lines.push(transcript.finished ? "[execution finished]" : "[execution running]");
+    return lines.join("\n");
+}
+/**
+ * A side conversation about one Braid job, or about one node of it. Each
+ * scope keeps its own history. It inspects the job through
+ * read-only tools and can message running executions; graph changes,
+ * cancellation, and resumption stay with the main agent.
+ */
+export class BraidAssistant {
+    jobs;
+    jobId;
+    onChange;
+    nodeId;
+    conversation;
+    history = [];
+    queued = [];
+    controller;
+    pending;
+    disposed = false;
+    constructor(jobs, jobId, cwd, onChange, 
+    /** The node this conversation is about; absent for the whole job. */
+    nodeId) {
+        this.jobs = jobs;
+        this.jobId = jobId;
+        this.onChange = onChange;
+        this.nodeId = nodeId;
+        this.conversation = { cwd, messages: [], running: new Map(), renderers: RENDERERS, version: 0 };
+    }
+    get busy() {
+        return this.controller !== undefined;
+    }
+    /** Ask a question or request an intervention. `view` describes what the panel shows. */
+    send(text, view, model) {
+        if (this.disposed || !text.trim())
+            return;
+        this.conversation.messages.push({ role: "user", content: text, timestamp: Date.now() });
+        this.queued.push({ text, view });
+        this.changed();
+        if (!this.controller)
+            void this.run(model);
+    }
+    /** Stop the current answer; queued questions are dropped. */
+    abort() {
+        this.queued = [];
+        this.controller?.abort();
+    }
+    dispose() {
+        this.disposed = true;
+        this.abort();
+        clearTimeout(this.pending);
+    }
+    systemPrompt() {
+        const job = this.jobs.get(this.jobId);
+        return "You are the Braid assistant inside the /braid panel of Pi. You help the user understand and steer one background Braid job " +
+            `(${job?.handle ?? this.jobId}: ${JSON.stringify(job?.goal ?? "")}). ` +
+            "A Braid job is a graph of nodes; each run of a node is an execution with its own isolated worker conversation. " +
+            "Use your tools to inspect the job instead of guessing, and cite node and execution IDs. " +
+            "When the user asks to guide, correct, or inform a running execution, use message_execution with a clear, self-contained instruction. " +
+            "If it is unclear which execution they mean, or none is running, say so instead of guessing. Never message an execution on your own initiative. " +
+            "Messages reach the worker before its next model request; they cannot change finished executions, the graph, or a decision already made. " +
+            "You cannot edit the graph, cancel, or resume; tell the user to ask the main Pi agent for that. " +
+            "You do not see the main conversation. Answer concisely, in the user's language." +
+            (this.nodeId === undefined
+                ? " This conversation is about the whole job; separate conversations exist for individual nodes."
+                : ` This conversation is about node ${JSON.stringify(this.nodeId)} and all of its executions; when the user says "it" or "this node", they mean this node. ` +
+                    "Each question says which execution the panel shows. You may still read other nodes for context, but message only this node's executions unless the user names another.");
+    }
+    async run(model) {
+        const controller = new AbortController();
+        this.controller = controller;
+        try {
+            while (this.queued.length && !controller.signal.aborted) {
+                for (const { text, view } of this.queued.splice(0)) {
+                    this.history.push({ role: "user", content: `[Panel view: ${view}]\n\n${text}`, timestamp: Date.now() });
+                }
+                await this.answer(model, controller.signal);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.closeToolCalls();
+            this.fail(controller.signal.aborted ? "aborted" : "error", controller.signal.aborted ? "Stopped" : message);
+        }
+        finally {
+            this.controller = undefined;
+            this.conversation.running.clear();
+            this.changed();
+        }
+    }
+    async answer(source, signal) {
+        const model = source.model;
+        if (!model)
+            throw new Error("Choose a Pi model with /model to use the Braid assistant");
+        for (let round = 0; round < MAX_ROUNDS; round++) {
+            signal.throwIfAborted();
+            const context = { systemPrompt: this.systemPrompt(), messages: this.history, tools: TOOLS };
+            const options = { signal, maxRetries: 0 };
+            let response;
+            if (source.registry.stream) {
+                const stream = source.registry.stream(model, context, options);
+                for await (const event of stream) {
+                    if (event.type === "done" || event.type === "error")
+                        continue;
+                    this.conversation.streaming = event.partial;
+                    this.changed(true);
+                }
+                response = await stream.result();
+            }
+            else {
+                response = await source.registry.complete(model, context, options);
+            }
+            delete this.conversation.streaming;
+            this.conversation.messages.push(response);
+            this.changed();
+            if (response.stopReason === "aborted")
+                signal.throwIfAborted();
+            // Failed responses are shown, but never sent back to the provider.
+            if (response.stopReason === "error" || response.stopReason === "aborted")
+                return;
+            this.history.push(response);
+            const calls = response.content.filter((block) => block.type === "toolCall");
+            if (!calls.length)
+                return;
+            for (const call of calls) {
+                signal.throwIfAborted();
+                this.conversation.running.set(call.id, undefined);
+                this.changed();
+                const result = this.execute(call);
+                this.conversation.running.delete(call.id);
+                this.history.push(result);
+                this.conversation.messages.push(result);
+                this.changed();
+            }
+        }
+        this.fail("error", `Stopped after ${MAX_ROUNDS} tool rounds`);
+    }
+    execute(call) {
+        let text;
+        let isError = false;
+        try {
+            const args = validateToolCall(TOOLS, call);
+            text = this.tool(call.name, args);
+        }
+        catch (error) {
+            text = error instanceof Error ? error.message : String(error);
+            isError = true;
+        }
+        return { role: "toolResult", toolCallId: call.id, toolName: call.name, content: [{ type: "text", text }], isError, timestamp: Date.now() };
+    }
+    tool(name, args) {
+        const job = this.jobs.get(this.jobId);
+        if (!job)
+            throw this.jobs.unknownJob(this.jobId);
+        const preview = (value) => {
+            const full = JSON.stringify(value, null, 2);
+            const result = truncateHead(full);
+            return result.truncated ? `${result.content}\n[Truncated; ask about a specific node or execution.]` : full;
+        };
+        switch (name) {
+            case "job_status": {
+                const state = job.result ?? job.execution;
+                return preview({
+                    handle: job.handle, goal: job.goal, status: job.status, error: job.error ?? state?.error,
+                    revision: job.execution?.revision, pausedExecutionIds: job.execution?.pausedExecutionIds,
+                    graph: job.execution?.graph,
+                    nodes: state?.nodes,
+                    executions: Object.values(state?.executions ?? {}).map(execution => ({
+                        executionId: execution.executionId, nodeId: execution.id, status: execution.status,
+                        ...(execution.iteration ? { iteration: execution.iteration } : {}),
+                        ...(execution.humanInputs?.length ? { humanInputs: execution.humanInputs.length } : {}),
+                    })),
+                });
+            }
+            case "execution_details": {
+                if (args.executionId === undefined && args.nodeId === undefined)
+                    throw new Error("Pass executionId or nodeId");
+                const node = this.jobs.getNode(this.jobId, args.nodeId, args.executionId);
+                const activity = node.executionId ? this.jobs.getActivity(this.jobId, node.executionId, {
+                    limit: ACTIVITY_ENTRIES, ...(args.activityBefore === undefined ? {} : { before: args.activityBefore }),
+                }) : undefined;
+                return preview({ node, ...(activity ? { activity } : {}) });
+            }
+            case "execution_transcript": {
+                const transcript = this.jobs.getTranscript(this.jobId, args.executionId);
+                if (!transcript)
+                    throw new Error("No live conversation is retained for this execution; use execution_details for its output and activity history.");
+                return describeTranscript(transcript, args.last ?? TRANSCRIPT_MESSAGES);
+            }
+            case "message_execution": {
+                this.jobs.sendInput(this.jobId, args.executionId, args.message);
+                return "Queued. The worker receives it before its next model request, after any running tool batch.";
+            }
+            default:
+                throw new Error(`Unknown tool ${name}`);
+        }
+    }
+    /** Answer tool calls interrupted by an abort, so the next request is well formed. */
+    closeToolCalls() {
+        let index = this.history.length - 1;
+        while (index >= 0 && this.history[index].role !== "assistant")
+            index--;
+        const last = this.history[index];
+        if (last?.role !== "assistant")
+            return;
+        const answered = new Set(this.history.slice(index + 1).flatMap(message => message.role === "toolResult" ? [message.toolCallId] : []));
+        for (const block of last.content) {
+            if (block.type !== "toolCall" || answered.has(block.id))
+                continue;
+            const result = {
+                role: "toolResult", toolCallId: block.id, toolName: block.name,
+                content: [{ type: "text", text: "Stopped by the user before this tool ran" }], isError: true, timestamp: Date.now(),
+            };
+            this.history.push(result);
+            this.conversation.messages.push(result);
+        }
+    }
+    fail(stopReason, errorMessage) {
+        const partial = this.conversation.streaming;
+        delete this.conversation.streaming;
+        const message = {
+            role: "assistant", api: partial?.api ?? "braid", provider: partial?.provider ?? "braid", model: partial?.model ?? "assistant",
+            content: partial?.content ?? [], stopReason, errorMessage, timestamp: Date.now(),
+            usage: partial?.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        };
+        // The model sees what was said, without a dangling unanswered tool call.
+        if (message.content.some(block => block.type === "toolCall"))
+            message.content = message.content.filter(block => block.type !== "toolCall");
+        this.conversation.messages.push(message);
+        if (message.content.length)
+            this.history.push({ ...message, stopReason: "stop" });
+        this.changed();
+    }
+    /** Token bursts coalesce into at most one notification per 100 ms. */
+    changed(burst = false) {
+        this.conversation.version++;
+        if (!burst) {
+            clearTimeout(this.pending);
+            this.pending = undefined;
+            this.emit();
+        }
+        else if (!this.pending) {
+            this.pending = setTimeout(() => { this.pending = undefined; this.emit(); }, 100);
+            this.pending.unref?.();
+        }
+    }
+    emit() {
+        if (this.disposed)
+            return;
+        try {
+            this.onChange();
+        }
+        catch { /* Observers cannot fail the assistant. */ }
+    }
+}