@jini-ai/chat 0.6.6 → 0.6.10

package/dist/core/assistant-client/transport.js

@@ -1,3 +1,4 @@
+import { readAgentPluginChatState, captureAgentPluginUsage } from '../agent-plugin-chat-state.js';
 import { buildTranscript, latestUserPromptFromHistory } from "../transcript.js";
 import * as runEvents from "../run-events/entry.js";
 /** Bind transport effects once; in-flight controllers belong to this client, never the package.
@@ -34,8 +35,6 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
      * accumulated here) — chat-core's own `ChatMessage.events` array is what concatenates them into one
      * growing message, so accumulating twice would double the text.
      */
-    const RUNS_URL = ports.runsUrl;
-    const BYOK_TURN_URL = ports.byokTurnUrl;
     /** Distinguishes a BYOK-run id (client-minted, no server-side run record) from a daemon-run id
      *  (server-minted, reattachable) wherever a bare `runId` string is all a `ChatTransport` method
      *  receives — see `stopRun`/`fetchRunStatus`/`reattachRun` below for why the distinction matters. */
@@ -73,11 +72,18 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
      * Bounded deliberately: each run is billed, and an unbounded transcript grows the input cost of
      * every subsequent turn in a conversation that has no natural end. {@link MAX_TRANSCRIPT_TURNS}
      * keeps a long-running chat from silently becoming the most expensive thing in the product.
+     * Failed turns are labeled outcomes so another agent can explain and recover from them.
      */
     function runPrompt(history) {
-        // `historyForTranscript` first, THEN the cap: dropping failed rows before slicing means the 40
-        // turns that survive are 40 real ones, not 40 slots some of which are rows the agent never wrote.
-        const recent = historyForTranscript(history).slice(-MAX_TRANSCRIPT_TURNS);
+        const recent = history.slice(-MAX_TRANSCRIPT_TURNS).map(message => {
+            if (message.role !== 'assistant' || isAnsweredAssistantTurn(message))
+                return message;
+            const detail = message.events?.filter(event => event.kind === 'status')
+                .map(event => [event.label, event.detail].filter(Boolean).join(': ')).join('\n').slice(-4000);
+            // Reserve space for the failure reason even when partial output fills the transcript cap.
+            const outcome = [message.content.slice(0, 6000), detail].filter(Boolean).join('\n\n');
+            return { ...message, content: `[${message.agentName ?? message.agentId ?? 'Assistant'} run ${message.runStatus}; not a completed answer]\n${outcome || 'No assistant reply was produced.'}` };
+        });
         return buildTranscript({ history: recent });
     }
     /**
@@ -97,7 +103,9 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
      * `events_json` is the sole durable record of why a run died (exit code, signal, the CLI's own
      * stderr) once the daemon's in-memory event log is gone, and the pane renders it on reload — so
      * dropping the row trades a history bug for a forensics hole. The skip belongs here, on the read
-     * side. See {@link historyForTranscript} and `assistant-chats.ts`'s `persistableMessages`.
+     * side. The transcript's hidden-tool mode likewise filters only recovered tool failures and keeps
+     * unrecovered failures behind a compact disclosure; it never deletes this durable evidence.
+     * See {@link historyForTranscript} and `assistant-chats.ts`'s `persistableMessages`.
      */
     function isAnsweredAssistantTurn(message) {
         return message.runStatus === undefined || message.runStatus === "succeeded";
@@ -205,7 +213,49 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
     /** The durable message owns recovery and terminal state; this subscription follows replacement
      * attempts without writing a browser-inferred failure into history. */
     function subscribeToRun(runId, handlers, signal) {
-        ports.followRun({ runId, handlers, ...(signal === undefined ? {} : { signal }) }, {});
+        ports.followRun({ runId, handlers: capturePluginUsage(handlers), ...(signal === undefined ? {} : { signal }) }, {});
+    }
+    /** The well-formed plugin usage an `agent_plugins` extension event carries, or `undefined` for any
+     * other event — the one validity rule both live events and checkpoint replays are captured by. */
+    function pluginUsageOf({ event }, _optional) {
+        if (event.kind !== 'ext' || event.name !== 'agent_plugins')
+            return undefined;
+        const usage = event.data;
+        return typeof usage?.conversationId === 'string' && usage.state && Array.isArray(usage.state.excluded) ? usage : undefined;
+    }
+    /** Capture before notifying the UI so answers received after reload persist for the next turn.
+     * Checkpoint panes skip live deltas to avoid duplicate text, so capture their saved events here
+     * too. Keep this wrapper as the single capture owner for both delivery contracts.
+     * @complexity O(e + s) per checkpoint; O(s) per live event, in saved events and plugin-state size.
+     */
+    function capturePluginUsage(handlers) {
+        const captured = new Map();
+        const capture = (event) => {
+            const usage = pluginUsageOf({ event }, {});
+            if (!usage)
+                return;
+            const state = JSON.stringify(usage.state);
+            if (captured.get(usage.conversationId) === state)
+                return;
+            captured.set(usage.conversationId, state);
+            captureAgentPluginUsage({ event });
+        };
+        return {
+            ...handlers,
+            onEvent: event => { capture(event); handlers.onEvent(event); },
+            ...(handlers.onCheckpoint ? { onCheckpoint: (message) => {
+                    // Historical answers must not roll the current state backwards on every poll.
+                    const latest = new Map();
+                    for (const event of message.events ?? []) {
+                        const usage = pluginUsageOf({ event }, {});
+                        if (usage)
+                            latest.set(usage.conversationId, event);
+                    }
+                    for (const event of latest.values())
+                        capture(event);
+                    handlers.onCheckpoint(message);
+                } } : {}),
+        };
     }
     /** Client-minted, not server-minted — see module doc's path-2 section: a BYOK run has no server-side
      *  run record to name it. Prefixed so `stopRun`/`fetchRunStatus`/`reattachRun` below can tell a
@@ -293,6 +343,56 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
             ctx.finish();
         }
     }
+    /**
+     * The provider-bound history of one BYOK turn: only turns the agent actually answered, never an
+     * empty one, each carrying its redaction signal.
+     */
+    function byokMessages({ history }, _optional) {
+        // `historyForTranscript` first (Defect 3, 2026-09-11): the empty-content filter below already
+        // hides a failed run that produced nothing, but NOT one that emitted a few tokens before dying —
+        // that partial output would be sent to the provider as if it were the assistant's answer. This is
+        // the same defect as on the Local CLI path, reachable by a second route.
+        return historyForTranscript(history)
+            .filter((message) => message.content.trim().length > 0)
+            .map((message) => ({ role: message.role, content: message.content,
+            ...(message.secretRedaction?.secretRedacted ? { secretRedacted: true } : {}),
+        }));
+    }
+    /** The credential block of a BYOK turn; an empty base URL and an unset token cap are omitted. */
+    function byokCredentials({ byok }, _optional) {
+        return {
+            protocol: byok.protocol,
+            apiKey: byok.apiKey,
+            ...(byok.baseUrl ? { baseUrl: byok.baseUrl } : {}),
+            model: byok.model,
+            ...(byok.maxTokens !== undefined ? { maxTokens: byok.maxTokens } : {}),
+        };
+    }
+    /** The JSON body `POST byokTurnUrl` carries for one turn. */
+    function byokTurnBody({ input, byok }, _optional) {
+        return {
+            messages: byokMessages({ history: input.history }, {}),
+            ...attachmentIdsField(input),
+            ...conversationIdField(input),
+            agentPluginState: input.context?.["agentPluginState"],
+            userPrompt: input.context?.["userPrompt"],
+            ...pluginRefIdsField(input),
+            // The admin screen, as on the Local CLI path (`buildLocalCliContextRef`): the server puts it
+            // in front of the newest message so a BYOK turn knows the open page and where drawings go.
+            ...pageContextField(input),
+            byok: byokCredentials({ byok }, {}),
+        };
+    }
+    /**
+     * The error for a refused request: `<action> (<status>)`, plus up to 300 characters of the
+     * response body when it has one — shared by the BYOK start, Local CLI start and cancel refusals.
+     */
+    async function refusalError({ action, response }, _optional) {
+        // A response whose body stream errors out (e.g. a dropped connection) must not turn "the server
+        // rejected the request" into "the client crashed reading the rejection".
+        const detail = await response.text().catch(() => "");
+        return new Error(`${action} (${response.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`);
+    }
     /**
      * The BYOK run path (2026-08-04) — one held-open `POST` to `assistant-byok.ts`, no separate
      * `EventSource`/reattach. See module doc's path-2 section for why this shape differs from
@@ -307,35 +407,13 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
         const controller = new AbortController();
         byokAbortControllers.set(runId, controller);
         input.signal?.addEventListener("abort", () => controller.abort());
-        // `historyForTranscript` first (Defect 3, 2026-09-11): the empty-content filter below already
-        // hides a failed run that produced nothing, but NOT one that emitted a few tokens before dying —
-        // that partial output would be sent to the provider as if it were the assistant's answer. This is
-        // the same defect as on the Local CLI path, reachable by a second route.
-        const messages = historyForTranscript(input.history)
-            .filter((message) => message.content.trim().length > 0)
-            .map((message) => ({ role: message.role, content: message.content,
-            ...(message.secretRedaction?.secretRedacted ? { secretRedacted: true } : {}),
-        }));
         let response;
         try {
-            response = await ports.fetch(BYOK_TURN_URL, {
+            response = await ports.fetch(ports.byokTurnUrl, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 credentials: "same-origin",
-                body: JSON.stringify({
-                    messages,
-                    ...attachmentIdsField(input),
-                    // The admin screen, as on the Local CLI path (`buildLocalCliContextRef`): the server puts it
-                    // in front of the newest message so a BYOK turn knows the open page and where drawings go.
-                    ...pageContextField(input),
-                    byok: {
-                        protocol: byok.protocol,
-                        apiKey: byok.apiKey,
-                        ...(byok.baseUrl ? { baseUrl: byok.baseUrl } : {}),
-                        model: byok.model,
-                        ...(byok.maxTokens !== undefined ? { maxTokens: byok.maxTokens } : {}),
-                    },
-                }),
+                body: JSON.stringify(byokTurnBody({ input, byok }, {})),
                 signal: controller.signal,
             });
         }
@@ -345,8 +423,7 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
         }
         if (!response.ok || !response.body) {
             byokAbortControllers.delete(runId);
-            const detail = await response.text().catch(() => "");
-            throw new Error(`BYOK turn failed to start (${response.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`);
+            throw await refusalError({ action: "BYOK turn failed to start", response }, {});
         }
         const collected = [];
         let settled = false;
@@ -484,10 +561,14 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
      *   adopt a conversation because `input.context` named none (the first turn of a chat). Omitted by
      *   every caller that already has an id on `input.context`, and by this function's own unit tests —
      *   in which case the `context` field is read exactly as before.
+     * The bounded `coldStartContext` is the complete prompt, including the current request. The
+     * daemon selects it instead of the resume tail when native resume is unavailable.
      */
     function buildLocalCliContextRef(input, prompt, resolvedConversationId) {
         return {
             prompt: ports.projectPrompt({ prompt, context: input.context }, {}),
+            // Select one complete transcript after binding; concatenating it with the tail repeats turns.
+            coldStartContext: ports.projectPrompt({ prompt: runPrompt(input.history), context: input.context }, {}),
             // The transcript is already sanitized; retain its signal across the daemon JSON boundary.
             ...(input.history.some(message => message.role === "user" && message.secretRedaction?.secretRedacted) ? { secretRedacted: true } : {}),
             assistantMessageId: input.assistantMessageId,
@@ -496,6 +577,8 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
             ...reasoningField(input),
             ...attachmentIdsField(input),
             ...pluginRefIdsField(input),
+            agentPluginState: input.context?.["agentPluginState"],
+            userPrompt: input.context?.["userPrompt"],
             ...conversationIdField(input, resolvedConversationId),
             ...pageContextField(input),
         };
@@ -523,27 +606,28 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
         const adopted = await ensureConversationId({}, {}).catch(() => null);
         return typeof adopted === "string" && adopted.length > 0 ? adopted : undefined;
     }
-    /**
-     * Resolves the prompt string `startRun`'s Local CLI branch sends: the full rendered transcript
-     * ({@link runPrompt}) by default, or only what the agent has not already been given
-     * ({@link undeliveredUserPrompt}) when `input.agentId` is present in `resumeCapableAgentIds` — see
-     * `getResumeCapableAgentIds`'s own doc on {@link AssistantTransportOptions} for the full
-     * contract this mirrors. Pulled out of `startRun` (2026-09-04, complexity pass) as its own pure
-     * step. `options.getResumeCapableAgentIds?.({}, {})` is still called at the same point in `startRun` as
-     * before — only the "which agentIds carries own memory" branch itself moves here, so the "read fresh
-     * on every call" convention that doc argues for is unchanged.
+    /** Send a resumed agent only its unseen conversation tail, retaining other agents' outcomes.
+     * Legacy rows without agent identity retain the existing unanswered-user delivery contract.
+     * @complexity O(n) to find the last answered turn; transcript rendering is capped at 40 turns.
      */
     function resolveLocalCliPrompt(input, resumeCapableAgentIds) {
         const carriesOwnMemory = input.agentId !== undefined && resumeCapableAgentIds?.has(input.agentId) === true;
+        if (!carriesOwnMemory)
+            return runPrompt(input.history);
+        let lastOwnAnswer = -1;
+        input.history.forEach((message, index) => {
+            if (message.role === 'assistant' && (!message.agentId || message.agentId === input.agentId) && isAnsweredAssistantTurn(message))
+                lastOwnAnswer = index;
+        });
+        const unseen = input.history.slice(lastOwnAnswer + 1);
+        const crossedAgents = unseen.some(message => message.role === 'assistant' && message.agentId && message.agentId !== input.agentId);
         // BEHAVIOR CHANGE (2026-09-11, Defect 2): the resume-capable branch was `latestUserPrompt` — the
         // single newest user turn, on the assumption that everything before it is already inside the
         // CLI's own session. That assumption holds only for turns the agent actually answered; a turn
         // whose run died before the CLI read its prompt is in neither place, and nothing ever sent it
         // again. `undeliveredUserPrompt` returns the identical single string in the ordinary case and
-        // differs only when there is genuinely something unanswered to catch up on. The
-        // `latestUserPrompt` parameter this used to take went with it: `startRun` still computes that
-        // string for its own send guard, but this branch has no use for it any more.
-        return carriesOwnMemory ? undeliveredUserPrompt(input.history) : runPrompt(input.history);
+        // differs only when there is genuinely something unanswered to catch up on.
+        return crossedAgents ? runPrompt(unseen) : undeliveredUserPrompt(input.history);
     }
     /**
      * Writes the newest user turn to durable storage before its run is dispatched, and never fails the
@@ -562,44 +646,73 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
      * two, and a retry of the same content is free. `useAssistantChats`'s own `persistUserTurn` also
      * marks the id written, so in practice `flush` skips it entirely.
      *
-     * @param input - `startRun`'s own input; the newest `role: "user"` message in its history is what
-     *   gets written.
+     * @param message - The newest `role: "user"` message in `startRun`'s history — what gets written.
+     *   `startRun` has already refused a history without one, so it is always present here.
      * @param conversationId - The already-resolved conversation (see `resolveRunConversationId`), or
      *   `undefined` when adoption failed — there is no row to write into in that case.
      * @param persistUserTurn - `AssistantTransportOptions.persistUserTurn`, or `undefined`
      *   for a transport built without it (every test and any non-dock consumer).
      * @returns Nothing, always. The `.catch` keeps a failed browser PUT from refusing the user's turn;
      *   durable acceptance is now responsible for committing its copy before dispatch.
-     * @complexity O(n) in history length for the newest-user-turn scan, plus one PUT.
+     * @complexity O(1) plus one PUT.
      */
-    async function persistUserTurnBeforeDispatch(input, conversationId, persistUserTurn) {
-        if (conversationId === undefined || persistUserTurn === undefined)
-            return;
-        const history = input.history;
-        const message = [...history].reverse().find((candidate) => candidate.role === "user");
-        if (message === undefined)
+    async function persistUserTurnBeforeDispatch({ message, conversationId }, { persistUserTurn }) {
+        // Pending composer input is persisted by atomic run acceptance. An earlier PUT could save a
+        // rejected (409) draft as a user turn; confirmed/legacy callers retain their existing ordering.
+        if (message.inputPending || conversationId === undefined || persistUserTurn === undefined)
             return;
         await persistUserTurn({ conversationId, message }, {}).catch(() => undefined);
     }
+    /** The newest `role: "user"` message in a history, or `undefined` when it has none.
+     * @complexity O(n) in history length. */
+    function newestUserMessage({ history }, _optional) {
+        return [...history].reverse().find((message) => message.role === "user");
+    }
     /**
      * Turns `startRun`'s Local CLI `POST /api/runs` response into either a thrown, detailed error or a
      * subscribed run — the two outcomes once the request lands. Pulled out of `startRun` (2026-09-04,
      * complexity pass) as its own step: `response.ok` in, `{runId}` or a thrown `Error` out. The
-     * `.text().catch(() => "")` is load-bearing, not decorative — see the inline comment below.
+     * `.text().catch(() => "")` is load-bearing, not decorative — see {@link refusalError}'s inline comment.
      */
     async function finishLocalCliRun(response, handlers, signal) {
-        if (!response.ok) {
-            // A response whose body stream errors out (e.g. a dropped connection) must not turn "the server
-            // rejected the request" into "the client crashed reading the rejection".
-            const detail = await response.text().catch(() => "");
-            throw new Error(`agent run failed to start (${response.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`);
-        }
+        if (!response.ok)
+            throw await refusalError({ action: "agent run failed to start", response }, {});
         const { run, messageId, conversationId } = (await response.json());
         if (messageId && conversationId)
             ports.bindRun({ runId: run.id, binding: { messageId, conversationId } }, {});
         subscribeToRun(run.id, handlers, signal);
         return { runId: run.id };
     }
+    /**
+     * The Local CLI path of `startRun`: durable user turn, then acceptance, then the followed run.
+     *
+     * @param input - `startRun`'s input with its conversation identity already merged into `context`.
+     * @param userMessage - The newest user message; acceptance carries it verbatim.
+     * @param conversationId - The resolved conversation, or `undefined` when adoption failed.
+     */
+    async function startLocalCliRun({ input, handlers, userMessage, conversationId }, { options }) {
+        // Local CLI path below. `resolveLocalCliPrompt`'s own doc has the full contract for why an
+        // unresolved/absent agentId fails open to the full transcript rather than the bare message.
+        const prompt = resolveLocalCliPrompt(input, options.getResumeCapableAgentIds?.({}, {}));
+        // Also before the POST, and for the same reason it is awaited rather than fired off: the
+        // user's turn must be durable before a run that can fail to deliver it exists at all
+        // (Defect 2, 2026-09-11). Ordered after conversation adoption because it needs the id that
+        // adoption produces. BYOK and AG-UI share the identity above; neither writes a durable
+        // user turn ahead of dispatch; those transports retain their own persistence behavior.
+        await persistUserTurnBeforeDispatch({ message: userMessage, conversationId }, { persistUserTurn: options.persistUserTurn });
+        // Acceptance commits the question and stub together even if the separate browser PUT fails
+        // or the tab disappears. Carry the exact message ID/payload, never the rendered prompt.
+        const base = buildLocalCliContextRef(input, prompt, conversationId);
+        const contextRef = { ...base, userMessage };
+        const response = await ports.acceptRun({
+            ...(input.cancelSignal === undefined ? {} : { signal: input.cancelSignal }),
+            requestSignal: input.cancelSignal ?? input.signal,
+            body: { contextRef: JSON.stringify(contextRef), agentId: input.agentId, idempotencyKey: base.assistantMessageId },
+            messageId: base.assistantMessageId,
+            ...(conversationId === undefined ? {} : { conversationId }),
+        }, {});
+        return finishLocalCliRun(response, handlers, input.signal);
+    }
     function createAssistantTransport(options = {}) {
         return {
             async startRun(input, handlers) {
@@ -608,9 +721,13 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
                 // prompt asks the agent to reply to itself. Shared by both paths below, and reused (rather than
                 // recomputed) by the Local CLI branch's own resume-capable check further down.
                 const latestUserPrompt = latestUserPromptFromHistory({ history: input.history });
-                if (!latestUserPrompt) {
+                const userMessage = newestUserMessage({ history: input.history }, {});
+                if (!latestUserPrompt || userMessage === undefined) {
                     throw new Error("no user message to send");
                 }
+                // Adopt identity before either runtime branch so first-turn decisions survive a reload.
+                const conversationId = await resolveRunConversationId(input, options.ensureConversationId);
+                input = { ...input, context: { ...input.context, ...(conversationId ? { conversationId, agentPluginState: readAgentPluginChatState({ conversationId }) } : {}), userPrompt: latestUserPrompt } };
                 const executionConfig = options.getExecutionConfig?.({}, {});
                 // Dispatches on MODE alone, not on whether a key is typed in this browser right now
                 // (2026-08-05). `executionConfig.byok.apiKey` is write-only server-side — it is empty on
@@ -623,7 +740,7 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
                 // level down — the route's own 400 `"no usable BYOK credential..."` — which is a real,
                 // actionable answer instead of the mode picker silently refusing to try.
                 if (executionConfig?.mode === "byok") {
-                    return startByokRun(ports.projectInput({ input }, {}), handlers, executionConfig.byok);
+                    return startByokRun(ports.projectInput({ input }, {}), capturePluginUsage(handlers), executionConfig.byok);
                 }
                 // AG-UI canary path (ADR-059) — a host-supplied toggle, independent of `executionConfig.mode`
                 // (Jini's own closed union, never extended for this). Checked AFTER the byok branch above:
@@ -633,35 +750,9 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
                 if (options.getAgUiEnabled?.({}, {})) {
                     // `historyForTranscript` here rather than inside `startAgUiRun`: that module importing this
                     // one would be a cycle, and this is its only caller. Same rule as the BYOK and Local CLI paths.
-                    return ports.agUi.startAgUiRun({ input: ports.projectInput({ input: { ...input, history: historyForTranscript(input.history) } }, {}), handlers }, {});
+                    return ports.agUi.startAgUiRun({ input: ports.projectInput({ input: { ...input, history: historyForTranscript(input.history) } }, {}), handlers: capturePluginUsage(handlers) }, {});
                 }
-                // Local CLI path below. `resolveLocalCliPrompt`'s own doc has the full contract for why an
-                // unresolved/absent agentId fails open to the full transcript rather than the bare message.
-                const prompt = resolveLocalCliPrompt(input, options.getResumeCapableAgentIds?.({}, {}));
-                // Awaited BEFORE the POST, and only on this branch: session resume is a daemon-run concept, so
-                // neither the BYOK nor the AG-UI path above has anything to file a session id under. See
-                // `resolveRunConversationId` and `AssistantTransportOptions.ensureConversationId`.
-                const conversationId = await resolveRunConversationId(input, options.ensureConversationId);
-                // Also before the POST, and for the same reason it is awaited rather than fired off: the
-                // user's turn must be durable before a run that can fail to deliver it exists at all
-                // (Defect 2, 2026-09-11). Ordered after conversation adoption because it needs the id that
-                // adoption produces. Known gap, not an oversight: the BYOK and AG-UI branches above return
-                // before this point and resolve no conversation id of their own, so neither writes a durable
-                // user turn ahead of dispatch — closing that needs those paths to adopt a conversation first.
-                await persistUserTurnBeforeDispatch(input, conversationId, options.persistUserTurn);
-                const userMessage = [...input.history].reverse().find((message) => message.role === "user");
-                // Acceptance commits the question and stub together even if the separate browser PUT fails
-                // or the tab disappears. Carry the exact message ID/payload, never the rendered prompt.
-                const base = buildLocalCliContextRef(input, prompt, conversationId);
-                const contextRef = userMessage ? { ...base, userMessage } : base;
-                const response = await ports.acceptRun({
-                    ...(input.cancelSignal === undefined ? {} : { signal: input.cancelSignal }),
-                    requestSignal: input.cancelSignal ?? input.signal,
-                    body: { contextRef: JSON.stringify(contextRef), agentId: input.agentId, idempotencyKey: base.assistantMessageId },
-                    messageId: base.assistantMessageId,
-                    ...(conversationId === undefined ? {} : { conversationId }),
-                }, {});
-                return finishLocalCliRun(response, handlers, input.signal);
+                return startLocalCliRun({ input, handlers, userMessage, conversationId }, { options });
             },
             async reattachRun(runId, handlers, options) {
                 // A BYOK run has no server-side record to reattach to (module doc's path-2 section) — the
@@ -688,7 +779,7 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
                     return null;
                 if (ports.agUi.isAgUiRunId({ runId }, {}))
                     return ports.agUi.fetchAgUiRunStatus({}, {});
-                const response = await ports.fetch(`${RUNS_URL}/${encodeURIComponent(runId)}`, { credentials: "same-origin" });
+                const response = await ports.fetch(`${ports.runsUrl}/${encodeURIComponent(runId)}`, { credentials: "same-origin" });
                 if (!response.ok)
                     return null;
                 const { run } = (await response.json());
@@ -704,7 +795,7 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
                 if (ports.agUi.isAgUiRunId({ runId }, {})) {
                     return ports.agUi.stopAgUiRun({ runId }, {});
                 }
-                const response = await ports.fetch(`${RUNS_URL}/${encodeURIComponent(runId)}/cancel`, {
+                const response = await ports.fetch(`${ports.runsUrl}/${encodeURIComponent(runId)}/cancel`, {
                     method: "POST",
                     headers: { "Content-Type": "application/json" },
                     credentials: "same-origin",
@@ -715,10 +806,8 @@ export function createAssistantTransportClient({ ports }, _options = {}) {
                     return;
                 // `fetch` resolves on any status: without this a refused cancel (401/403/500) resolved exactly
                 // like a successful one while the run kept executing. `useRunStream` logs a rejection here.
-                if (!response.ok) {
-                    const detail = await response.text().catch(() => "");
-                    throw new Error(`cancelling agent run failed (${response.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`);
-                }
+                if (!response.ok)
+                    throw await refusalError({ action: "cancelling agent run failed", response }, {});
             },
         };
     }

package/dist/core/assistant-content.d.ts

@@ -19,9 +19,10 @@ import type { AgentEvent } from './events.js';
 export declare const ASSISTANT_STEP_SEPARATOR = "\n\n";
 /**
  * A turn's text, with a paragraph break between runs separated by a tool call or card.
+ * A replay of an already-seen tool ID is not a new step, matching the saved-event projection.
  *
  * @param events - The turn's events, in arrival order.
- * @complexity O(total text length).
+ * @complexity O(n + total text length) time and O(n) space for n events.
  */
 export declare function assistantContentFromEvents({ events }: {
     events: readonly AgentEvent[] | undefined;

package/dist/core/assistant-content.js

@@ -1,3 +1,4 @@
+import { dedupeToolUsesById } from './tool-events.js';
 /** What separates two text runs that a tool call or card sat between. */
 export const ASSISTANT_STEP_SEPARATOR = '\n\n';
 function separatorBefore(out, text) {
@@ -7,25 +8,22 @@ function separatorBefore(out, text) {
 }
 /**
  * A turn's text, with a paragraph break between runs separated by a tool call or card.
+ * A replay of an already-seen tool ID is not a new step, matching the saved-event projection.
  *
  * @param events - The turn's events, in arrival order.
- * @complexity O(total text length).
+ * @complexity O(n + total text length) time and O(n) space for n events.
  */
 export function assistantContentFromEvents({ events }) {
     let out = '';
     let stepBoundary = false;
-    for (const ev of events ?? []) {
-        if (ev.kind === 'text') {
-            if (ev.text.length === 0)
-                continue;
-            if (stepBoundary)
-                out += separatorBefore(out, ev.text);
-            out += ev.text;
-            stepBoundary = false;
-        }
-        else if (ev.kind === 'tool_use' || ev.kind === 'ext') {
+    for (const ev of dedupeToolUsesById({ events: events ? [...events] : undefined })) {
+        if (ev.kind === 'tool_use' || ev.kind === 'ext') {
             stepBoundary = true;
         }
+        else if (ev.kind === 'text' && ev.text.length > 0) {
+            out += (stepBoundary ? separatorBefore(out, ev.text) : '') + ev.text;
+            stepBoundary = false;
+        }
     }
     return out;
 }

package/dist/core/browser/page-actions.js

@@ -41,8 +41,10 @@ export function findTargetElement({ title, root, selection }) {
         return null;
     const candidates = Array.from(root.querySelectorAll(selection.candidateSelector))
         .filter(el => !el.closest(selection.excludedAncestorSelector));
-    return candidates.find(el => (el.textContent ?? '').trim() === needle)
-        ?? candidates.find(el => (el.textContent ?? '').trim().toLowerCase() === needle.toLowerCase()) ?? null;
+    // `textContent` is null only for documents and doctypes; every Element the selector yields has a string.
+    const text = (el) => el.textContent.trim();
+    return candidates.find(el => text(el) === needle)
+        ?? candidates.find(el => text(el).toLowerCase() === needle.toLowerCase()) ?? null;
 }
 /**
  * Creates page effects with injected DOM, navigation, URL policy, scroll and timers.

package/dist/core/composer-history.d.ts

@@ -7,11 +7,15 @@ export interface ComposerHistoryState {
 export interface ComposerHistoryStoragePort {
     read: (required: {
         scope: string;
-    }, optional: {}) => Promise<readonly string[]>;
+    }, optional: {
+        cap?: number;
+    }) => Promise<readonly string[]>;
     write: (required: {
         scope: string;
         entries: readonly string[];
-    }, optional: {}) => Promise<void>;
+    }, optional: {
+        cap?: number;
+    }) => Promise<void>;
 }
 export interface ComposerHistoryKeyInput {
     key: string;
@@ -40,15 +44,18 @@ export declare function mergeComposerHistory({ recent, current }: {
     cap?: number;
 }): string[];
 export declare function createComposerHistoryState(_required: {}, _optional?: {}): ComposerHistoryState;
-export declare function composerHistoryKeyAction(input: ComposerHistoryKeyInput, _optional?: {}): 'previous' | 'next' | 'restore' | null;
-export declare function transitionComposerHistory({ state, action, text, entries }: {
-    state: ComposerHistoryState;
-    action: 'previous' | 'next' | 'restore' | 'edit' | 'reset';
-    text: string;
-    entries: readonly string[];
-}, _optional?: {}): {
+type ComposerHistoryKeyAction = 'previous' | 'next' | 'restore';
+type ComposerHistoryTransition = {
     state: ComposerHistoryState;
     text: string;
     handled: boolean;
 };
+export declare function composerHistoryKeyAction(input: ComposerHistoryKeyInput, _optional?: {}): ComposerHistoryKeyAction | null;
+export declare function transitionComposerHistory({ state, action, text, entries }: {
+    state: ComposerHistoryState;
+    action: ComposerHistoryKeyAction | 'edit' | 'reset';
+    text: string;
+    entries: readonly string[];
+}, _optional?: {}): ComposerHistoryTransition;
+export {};
 //# sourceMappingURL=composer-history.d.ts.map

package/dist/core/composer-history.js

@@ -20,34 +20,46 @@ export function mergeComposerHistory({ recent, current }, { cap = 100 } = {}) {
 export function createComposerHistoryState(_required, _optional = {}) {
     return { entries: [], index: null, draft: null };
 }
+function hasModifierOrPopup({ input }, _optional = {}) {
+    return Boolean(input.shiftKey || input.ctrlKey || input.altKey || input.metaKey || input.isComposing || input.popupOpen);
+}
+/**
+ * Whether the selection sits on the first/last line. A selection spanning a newline is on
+ * neither, because text[0, end) and text[start, ∞) both contain the selected newline.
+ */
+function caretBoundaries({ input }, _optional = {}) {
+    const start = Math.min(input.selectionStart, input.selectionEnd);
+    const end = Math.max(input.selectionStart, input.selectionEnd);
+    return {
+        firstLine: !input.text.slice(0, end).includes('\n') && input.firstLine !== false,
+        lastLine: !input.text.slice(start).includes('\n') && input.lastLine !== false,
+    };
+}
 export function composerHistoryKeyAction(input, _optional = {}) {
-    if (input.shiftKey || input.ctrlKey || input.altKey || input.metaKey || input.isComposing || input.popupOpen)
+    if (hasModifierOrPopup({ input }))
         return null;
     if (input.key === 'Escape')
         return 'restore';
-    const start = Math.min(input.selectionStart, input.selectionEnd);
-    const end = Math.max(input.selectionStart, input.selectionEnd);
-    if (input.text.slice(start, end).includes('\n'))
-        return null;
-    const firstLine = !input.text.slice(0, end).includes('\n') && input.firstLine !== false;
-    const lastLine = !input.text.slice(start).includes('\n') && input.lastLine !== false;
-    if (input.key === 'ArrowUp' && firstLine)
+    const lines = caretBoundaries({ input });
+    if (input.key === 'ArrowUp' && lines.firstLine)
         return 'previous';
-    if (input.key === 'ArrowDown' && lastLine)
+    if (input.key === 'ArrowDown' && lines.lastLine)
         return 'next';
     return null;
 }
+function startBrowsing({ state, action, text, entries }, _optional = {}) {
+    if (action !== 'previous' || entries.length === 0)
+        return { state, text, handled: false };
+    const snapshot = [...entries];
+    const index = snapshot.length - 1;
+    return { state: { entries: snapshot, index, draft: text }, text: snapshot[index], handled: true };
+}
 export function transitionComposerHistory({ state, action, text, entries }, _optional = {}) {
     if (action === 'edit' || action === 'reset') {
         return { state: createComposerHistoryState({}), text, handled: false };
     }
-    if (state.index === null) {
-        if (action !== 'previous' || entries.length === 0)
-            return { state, text, handled: false };
-        const snapshot = [...entries];
-        const index = snapshot.length - 1;
-        return { state: { entries: snapshot, index, draft: text }, text: snapshot[index], handled: true };
-    }
+    if (state.index === null)
+        return startBrowsing({ state, action, text, entries });
     if (action === 'restore' || (action === 'next' && state.index === state.entries.length - 1)) {
         return { state: createComposerHistoryState({}), text: state.draft ?? '', handled: true };
     }

package/dist/core/conversation-title.d.ts

@@ -0,0 +1,3 @@
+/** Maximum length of a user-supplied conversation title, in UTF-16 code units (HTML maxLength). */
+export declare const MAX_CONVERSATION_TITLE_LENGTH = 50;
+//# sourceMappingURL=conversation-title.d.ts.map

package/dist/core/conversation-title.js

@@ -0,0 +1,3 @@
+/** Maximum length of a user-supplied conversation title, in UTF-16 code units (HTML maxLength). */
+export const MAX_CONVERSATION_TITLE_LENGTH = 50;
+//# sourceMappingURL=conversation-title.js.map