@assistant-ui/core 0.2.6 → 0.2.7

package/src/internal/duplicate-detection.ts

@@ -0,0 +1,26 @@
+// Warns once if a second copy of @assistant-ui/core is loaded into the
+// same runtime. Mismatched transitive versions of core silently break
+// runtime behavior — tools registered via `makeAssistantTool` don't reach
+// the active runtime, context lookups resolve to the wrong provider,
+// `instanceof` checks fail (see issue #4101). The actual version diagnosis
+// lives in `npx assistant-ui doctor`.
+//
+// The caller is responsible for gating on `process.env.NODE_ENV` so this
+// module tree-shakes out of production bundles.
+
+const KEY = Symbol.for("@assistant-ui/core.loaded");
+
+export function checkDuplicateCore(): void {
+  const g = globalThis as unknown as Record<symbol, boolean | undefined>;
+  if (g[KEY]) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[@assistant-ui/core] Multiple copies of @assistant-ui/core are " +
+        "loaded into the same runtime. This causes subtle bugs (tools not " +
+        "reaching the runtime, context lookups returning the wrong " +
+        "provider, instanceof checks failing). Run " +
+        "`npx assistant-ui doctor` to diagnose.",
+    );
+  }
+  g[KEY] = true;
+}

package/src/react/AssistantProvider.tsx

@@ -10,9 +10,8 @@ import type { AssistantRuntimeCore } from "../runtime/interfaces/assistant-runti
 import { RuntimeAdapter } from "./RuntimeAdapter";
 
 export const getRenderComponent = (runtime: AssistantRuntime) => {
-  return (runtime as { _core?: AssistantRuntimeCore })._core?.RenderComponent as
-    | ComponentType
-    | undefined;
+  return (runtime as { _core?: AssistantRuntimeCore })._core
+    ?.RenderComponent as ComponentType | undefined;
 };
 
 export type AssistantProviderBaseProps = PropsWithChildren<{

package/src/react/index.ts

@@ -1,3 +1,4 @@
+/// <reference path="../store/scope-registration.ts" />
 /// <reference path="./types/store-augmentation.ts" />
 
 // model-context
@@ -129,12 +130,6 @@ export {
   useRuntimeAdapters,
   type RuntimeAdapters,
 } from "./runtimes/RuntimeAdapterProvider";
-export {
-  useToolInvocations,
-  type ToolExecutionStatus,
-  type AssistantTransportState,
-  type AddToolResultCommand,
-} from "./runtimes/useToolInvocations";
 export { useExternalStoreRuntime } from "./runtimes/useExternalStoreRuntime";
 export {
   useExternalMessageConverter,

package/src/react/primitives/chainOfThought/ChainOfThoughtParts.tsx

@@ -86,8 +86,7 @@ export const ChainOfThoughtPrimitiveParts: FC<
     );
   }
 
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
+  // oxlint-disable-next-line react-hooks/rules-of-hooks -- intentional conditional hook below the early return above
   const messageComponents = useMemo(
     () => ({
       Reasoning: components?.Reasoning,

package/src/react/primitives/message/MessageAttachments.test.tsx

@@ -4,7 +4,7 @@ import { MessagePrimitiveAttachments } from "./MessageAttachments";
 
 const mockUseAuiState = vi.fn();
 type UseAuiStateSelector = Parameters<
-  typeof import("@assistant-ui/store")["useAuiState"]
+  (typeof import("@assistant-ui/store"))["useAuiState"]
 >[0];
 type AttachmentsElement = ReactElement<{ children: () => null }>;
 

package/src/react/primitives/message/MessageGroupedParts.tsx

@@ -182,9 +182,9 @@ export const MessagePrimitiveGroupedParts = <TKey extends `group-${string}`>({
     GROUPBY_MEMO_KEY
   ];
   const memoDep = memoKey ?? groupBy;
-  // biome-ignore lint/correctness/useExhaustiveDependencies: groupBy is captured via memoDep — either as its identity (no memoKey) or as the helper's memoKey fingerprint. Listing groupBy directly would defeat the helper-tagged memo path.
   const tree = useMemo(
     () => buildGroupTree(parts.map((part) => groupBy(part) ?? [])),
+    // oxlint-disable-next-line tap-hooks/exhaustive-deps -- groupBy is captured via memoDep (either its identity or the helper's memoKey fingerprint); listing it directly would defeat the helper-tagged memo path
     [parts, memoDep],
   );
 

package/src/react/runtimes/external-message-converter.ts

@@ -12,7 +12,7 @@ import {
   type ThreadMessageLike,
 } from "../../runtime/utils/thread-message-like";
 import { getAutoStatus, isAutoStatus } from "../../runtime/utils/auto-status";
-import type { ToolExecutionStatus } from "./useToolInvocations";
+import type { ToolExecutionStatus } from "../../runtimes/tool-invocations/ToolInvocationTracker";
 import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import { generateErrorMessageId } from "../../utils/id";
 import type {

package/src/runtime/api/attachment-runtime.ts

@@ -42,8 +42,7 @@ export type AttachmentRuntime<
 
 export abstract class AttachmentRuntimeImpl<
   Source extends AttachmentRuntimeSource = AttachmentRuntimeSource,
-> implements AttachmentRuntime
-{
+> implements AttachmentRuntime {
   public get path() {
     return this._core.path;
   }

package/src/runtime/interfaces/thread-runtime-core.ts

@@ -1,3 +1,4 @@
+import type { ToolModelContentPart } from "assistant-stream";
 import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import type { ModelContext } from "../../model-context/types";
 import type { Unsubscribe } from "../../types/unsubscribe";
@@ -38,6 +39,13 @@ export type AddToolResultOptions = {
   result: ReadonlyJSONValue;
   isError: boolean;
   artifact?: ReadonlyJSONValue | undefined;
+  /**
+   * Optional model-content payload produced by the tool. Populated when a
+   * client-side `execute()` or `streamCall` returns a `ToolResponse` with
+   * `modelContent`. Forwarded through `adapter.onAddToolResult` so the
+   * adapter can include it when sending the result back to its backend.
+   */
+  modelContent?: readonly ToolModelContentPart[] | undefined;
 };
 
 export type ResumeToolCallOptions = {

package/src/runtime/internal.ts

@@ -18,10 +18,7 @@ export { DefaultEditComposerRuntimeCore } from "./base/default-edit-composer-run
 // Runtime Impl Classes
 export { AssistantRuntimeImpl } from "./api/assistant-runtime";
 
-export {
-  getThreadState,
-  ThreadRuntimeImpl,
-} from "./api/thread-runtime";
+export { getThreadState, ThreadRuntimeImpl } from "./api/thread-runtime";
 export type {
   ThreadRuntimeCoreBinding,
   ThreadListItemRuntimeBinding,

package/src/runtimes/external-store/external-store-adapter.ts

@@ -16,6 +16,7 @@ import type {
 } from "../../runtime/interfaces/thread-runtime-core";
 import type { ExportedMessageRepository } from "../../runtime/utils/message-repository";
 import type { ReadonlyJSONValue } from "assistant-stream/utils";
+import type { ToolExecutionStatus } from "../tool-invocations/ToolInvocationTracker";
 
 export type ExternalStoreThreadData<TState extends "regular" | "archived"> = {
   status: TState;
@@ -131,6 +132,38 @@ type ExternalStoreAdapterBase<T> = {
         copy?: boolean | undefined;
       }
     | undefined;
+  /**
+   * Opt in to the built-in client-side tool-invocations pipeline
+   * (`streamCall` / `execute` / tool-status tracking) for this thread.
+   *
+   * Defaults to `false` — the runtime does *not* drive client-side tool
+   * callbacks on its own. Set to `true` to have the runtime construct a
+   * `ToolInvocationTracker` and feed every snapshot through it, so tool
+   * callbacks fire automatically for tool-call parts in `messages`.
+   *
+   * Opt-in by default because most external-store runtimes either run
+   * tools entirely server-side, or already wire their own client-side
+   * dispatch path. Enabling the embedded tracker on top of an existing
+   * dispatch path would cause tool callbacks to run twice.
+   *
+   * When enabled, client-side tool results (from `execute()` returning,
+   * or from `streamCall` resolving) flow back through
+   * `adapter.onAddToolResult` like any other tool result, with
+   * `modelContent` populated when present.
+   */
+  unstable_enableToolInvocations?: boolean | undefined;
+  /**
+   * Receives the current per-tool-call execution status map whenever it
+   * changes. Only invoked when `unstable_enableToolInvocations` is `true`
+   * — the runtime maintains the map via the embedded tracker.
+   *
+   * Wire this into local React state and feed it into the converter's
+   * `metadata.toolStatuses` so the UI can render `executing` spinners
+   * and human-input prompts.
+   */
+  setToolStatuses?:
+    | ((statuses: Record<string, ToolExecutionStatus>) => void)
+    | undefined;
 };
 
 export type ExternalStoreAdapter<T = ThreadMessage> =

package/src/runtimes/external-store/external-store-thread-list-runtime-core.ts

@@ -22,9 +22,7 @@ const DEFAULT_THREAD_DATA = Object.freeze({
   [DEFAULT_THREAD_ID]: DEFAULT_THREAD,
 });
 
-export class ExternalStoreThreadListRuntimeCore
-  implements ThreadListRuntimeCore
-{
+export class ExternalStoreThreadListRuntimeCore implements ThreadListRuntimeCore {
   private _mainThreadId: string = DEFAULT_THREAD_ID;
   private _threads: readonly string[] = DEFAULT_THREADS;
   private _archivedThreads: readonly string[] = EMPTY_ARRAY;

package/src/runtimes/external-store/external-store-thread-runtime-core.ts

@@ -30,6 +30,7 @@ import {
   ExportedMessageRepository,
   MessageRepository,
 } from "../../runtime/utils/message-repository";
+import { ToolInvocationTracker } from "../tool-invocations/ToolInvocationTracker";
 
 const EMPTY_ARRAY: readonly ThreadSuggestion[] = Object.freeze([]);
 
@@ -105,6 +106,12 @@ export class ExternalStoreThreadRuntimeCore
 
   private _store!: ExternalStoreAdapter<any>;
 
+  /**
+   * Client-side tool-invocations pipeline. Constructed lazily on first
+   * snapshot — only when `adapter.unstable_enableToolInvocations === true`.
+   */
+  private _toolInvocations: ToolInvocationTracker | null = null;
+
   public override beginEdit(messageId: string) {
     if (!this._store.onEdit)
       throw new Error("Runtime does not support editing.");
@@ -273,9 +280,113 @@ export class ExternalStoreThreadRuntimeCore
     );
 
     this._messages = this.repository.getMessages();
+
+    this._driveToolInvocations();
+
     this._notifySubscribers();
   }
 
+  /**
+   * Feed the current message snapshot into the tool-invocations tracker.
+   * Opt-in via `adapter.unstable_enableToolInvocations: true`. The tracker
+   * itself is fail-silent — see ToolInvocationTracker for the
+   * state-transition contract.
+   */
+  private _driveToolInvocations(): void {
+    if (!this._store.unstable_enableToolInvocations) {
+      // Adapter did not opt in (default). If a tracker was previously
+      // constructed (e.g. the adapter just toggled the flag off via a
+      // dynamic swap), drop it so subsequent snapshots are no-ops.
+      if (this._toolInvocations) {
+        this._toolInvocations.reset();
+        this._toolInvocations = null;
+        this._store.setToolStatuses?.({});
+      }
+      return;
+    }
+
+    if (!this._toolInvocations) {
+      this._toolInvocations = new ToolInvocationTracker(
+        () => this.getModelContext().tools,
+        {
+          onResult: (command) => {
+            try {
+              const messageId = this._findMessageIdForToolCall(
+                command.toolCallId,
+              );
+              if (messageId === undefined) {
+                // The tool call no longer exists in the snapshot (e.g.
+                // rolled back). Drop the result.
+                return;
+              }
+              this._store.onAddToolResult?.({
+                messageId,
+                toolCallId: command.toolCallId,
+                toolName: command.toolName,
+                result: command.result,
+                isError: command.isError,
+                ...(command.artifact !== undefined && {
+                  artifact: command.artifact,
+                }),
+                ...(command.modelContent !== undefined && {
+                  modelContent: command.modelContent,
+                }),
+              });
+            } catch (err) {
+              console.error(
+                "[ExternalStoreThreadRuntimeCore] onAddToolResult dispatch failed",
+                err,
+              );
+            }
+          },
+          onStatusesChange: (statuses) => {
+            this._store.setToolStatuses?.(Object.fromEntries(statuses));
+          },
+        },
+      );
+    }
+
+    this._toolInvocations.setState({
+      messages: this._messages,
+      isRunning: this._store.isRunning ?? false,
+      ...(this._store.isLoading !== undefined && {
+        isLoading: this._store.isLoading,
+      }),
+    });
+  }
+
+  /**
+   * Lookup table from `toolCallId` to the owning assistant message's `id`,
+   * rebuilt lazily when `_messages` changes (see `_messagesForToolCallIndex`).
+   */
+  private _toolCallToMessageId = new Map<string, string>();
+  private _messagesForToolCallIndex: readonly ThreadMessage[] | null = null;
+
+  /**
+   * Look up the assistant message that owns a tool-call part. Lazily builds
+   * (and caches) a `toolCallId → messageId` map keyed off the current
+   * `_messages` reference, so onResult dispatches stay O(1) instead of
+   * walking the full thread on every result.
+   */
+  private _findMessageIdForToolCall(toolCallId: string): string | undefined {
+    if (this._messagesForToolCallIndex !== this._messages) {
+      this._toolCallToMessageId.clear();
+      const visit = (messages: readonly ThreadMessage[]): void => {
+        for (const message of messages) {
+          if (!Array.isArray(message.content)) continue;
+          for (const part of message.content) {
+            if (!part || part.type !== "tool-call") continue;
+            this._toolCallToMessageId.set(part.toolCallId, message.id);
+            if (part.messages) visit(part.messages);
+          }
+        }
+      };
+      visit(this._messages);
+      this._messagesForToolCallIndex = this._messages;
+    }
+    return this._toolCallToMessageId.get(toolCallId);
+  }
+
   public override switchToBranch(branchId: string): void {
     if (!this._store.setMessages)
       throw new Error("Runtime does not support switching branches.");
@@ -290,6 +401,16 @@ export class ExternalStoreThreadRuntimeCore
   }
 
   public async append(message: AppendMessage): Promise<void> {
+    // Auto-abort in-flight client-side tool executions when a new run is
+    // about to start. Without this, a tool that finishes after the new turn
+    // begins would feed a stale result into `onAddToolResult`, racing with
+    // the new turn the user just initiated. `startRun` defaults to true for
+    // user messages — matches the satellites' historical opt-in cancel
+    // behavior, which is now built in.
+    if (message.startRun ?? message.role === "user") {
+      await this._toolInvocations?.abort();
+    }
+
     if (message.parentId !== (this.messages.at(-1)?.id ?? null)) {
       if (!this._store.onEdit)
         throw new Error("Runtime does not support editing messages.");
@@ -303,6 +424,11 @@ export class ExternalStoreThreadRuntimeCore
     if (!this._store.onReload)
       throw new Error("Runtime does not support reloading messages.");
 
+    // Auto-abort in-flight client-side tool executions when a run reloads;
+    // any results that land afterward would target a turn that no longer
+    // exists. See `append` above for full rationale.
+    await this._toolInvocations?.abort();
+
     await this._store.onReload(config.parentId, config);
   }
 
@@ -324,6 +450,18 @@ export class ExternalStoreThreadRuntimeCore
     if (!this._store.onLoadExternalState)
       throw new Error("Runtime does not support importing external states.");
 
+    // Re-arm the tracker so the next adapter snapshot (containing the
+    // imported state) is treated as historical — no streamCall/execute
+    // fires for the loaded tool calls. The adapter is expected to update
+    // its messages in response to onLoadExternalState; that update flows
+    // back here via __internal_setAdapter. We only clear adapter-side
+    // tool statuses when the tracker is the source of truth — otherwise
+    // we'd wipe statuses the adapter is managing on its own.
+    if (this._toolInvocations) {
+      this._toolInvocations.reset();
+      this._store.setToolStatuses?.({});
+    }
+
     this._store.onLoadExternalState(state);
   }
 
@@ -331,6 +469,11 @@ export class ExternalStoreThreadRuntimeCore
     if (!this._store.onCancel)
       throw new Error("Runtime does not support cancelling runs.");
 
+    // Abort any in-flight client-side tool executions. Fire-and-forget —
+    // the abort resolves once executions settle, but we don't gate the
+    // cancel on it.
+    void this._toolInvocations?.abort();
+
     this._store.onCancel();
 
     if (this._assistantOptimisticId) {
@@ -362,15 +505,29 @@ export class ExternalStoreThreadRuntimeCore
   }
 
   public addToolResult(options: AddToolResultOptions) {
-    if (!this._store.onAddToolResult && !this._store.onAddToolResult)
+    if (!this._store.onAddToolResult)
       throw new Error("Runtime does not support tool results.");
     this._store.onAddToolResult?.(options);
   }
 
   public resumeToolCall(options: ResumeToolCallOptions) {
-    if (!this._store.onResumeToolCall)
-      throw new Error("Runtime does not support resuming tool calls.");
-    this._store.onResumeToolCall(options);
+    // Tracker owns its own human-input handlers — let it resume in-process
+    // tool calls without round-tripping through the adapter. Falls back to
+    // the adapter's onResumeToolCall (if any) for tool calls the tracker
+    // doesn't know about.
+    const handled =
+      this._toolInvocations?.resume(options.toolCallId, options.payload) ??
+      false;
+    if (handled) return;
+
+    if (this._store.onResumeToolCall) {
+      this._store.onResumeToolCall(options);
+      return;
+    }
+
+    throw new Error(
+      `Tool call ${options.toolCallId} is not waiting for resume.`,
+    );
   }
 
   public respondToToolApproval(options: RespondToToolApprovalOptions) {

package/src/runtimes/tool-invocations/EDGE_CASES.md

@@ -0,0 +1,194 @@
+# `ToolInvocationTracker` — known state-transition edge cases
+
+This document captures the non-trivial state transitions the tracker may
+observe via `setState(snapshot)` and what the current behavior is.
+
+## Hard contract
+
+> **`streamCall` (and `execute`) fires exactly once per logical
+> `toolCallId`.** No matter how the host's snapshot mutates after that
+> first observation — args regress, args change after first completion,
+> result is replaced, result is cleared, key order shuffles — the tracker
+> never invokes the host's tool callback a second time.
+
+This guarantees host-side side effects (the typical reason `streamCall` /
+`execute` exists at all) can't double-run. The cost: post-completion
+mutations are not surfaced to the host through the tool callback.
+Consumers that need to observe them will opt into the planned
+`reader.events()` API.
+
+The tracker also never throws. Every public method that observes runtime
+state (`setState`, `reset`, `abort`, `resume`) wraps its work in
+try/catch and logs to `console.error`. The tracker is built into the hot
+message-processing path; a malformed snapshot must never crash the host
+runtime.
+
+## A. Tool changes shape after first observation
+
+### A.1. Args grow (normal streaming case)
+Each snapshot's `argsText` is a longer prefix of the previous. The
+tracker appends the delta into the active controller's `argsText`
+stream. No re-fire.
+
+### A.2. Args regress mid-stream (snapshot regression)
+A later snapshot's `argsText` is shorter than what we already streamed,
+or otherwise *not* a prefix of it. Under the exactly-once contract, the
+tracker does **not** restart the stream. The controller keeps whatever
+prefix already streamed. The regression is logged in non-prod. The
+host's view diverges from the snapshot until `reader.events()` ships.
+
+Subsequent snapshots that *are* prefixes of the new (regressed) snapshot
+also won't be appended, because `entry.argsText` still points at the
+pre-regression value used for delta calculation.
+
+### A.3. Args complete then equivalent-JSON key reorder
+Both old and new `argsText` parse to equivalent JSON values (e.g. keys
+reordered by the backend). The tracker updates its tracked `argsText`
+silently. No re-fire.
+
+### A.4. Args complete then change to non-equivalent value
+The tracker does **not** restart the stream and does **not** invoke
+`streamCall` a second time. Logs the divergence in non-prod. The host's
+existing `streamCall` keeps its original args view.
+
+### A.5. First resolution (`result` becomes defined)
+The tracker calls `setResponse` on the active controller and closes it.
+`reader.response.get()` resolves. If the tool also had a frontend
+`execute`, the executor is short-circuited via `_skipExecuteStreamIds`.
+Single fire.
+
+### A.6. Previously-resolved tool's `result` is replaced
+Silently ignored — `entry.hasResult` short-circuits both the
+re-`setResponse` path and the downstream result-chunk handler. The host
+sees only the first result.
+
+### A.7. Previously-resolved tool loses its `result` (back to undefined)
+Silently ignored. The entry stays in the resolved phase internally.
+
+## B. Tool call disappears from snapshot
+
+### B.1. Tool call removed entirely (rollback, branch switch)
+The tracker does not auto-clean entries that disappear from the
+snapshot. The entry persists in `_entries` until the next `reset()`.
+
+Auto-cleanup is intentionally avoided: if the same `toolCallId` ever
+reappears in a later snapshot, treating it as new would re-fire
+`streamCall`, violating the exactly-once contract. The cost is a bounded
+memory accumulation across the tracker's lifetime; `reset()` clears it.
+
+## C. Initial snapshot vs. live snapshot
+
+### C.1. Tool call present in the initial snapshot
+While `_pendingRestore === true` (either by construction, or because
+`snapshot.isLoading === true`), tool calls are recorded as restored
+entries with no controller. `streamCall` / `execute` do not fire.
+
+### C.2. Restored entry observed in a live snapshot, unchanged
+Silently kept as restored. Recursion into `content.messages` still
+happens so any nested live tool calls are processed.
+
+### C.3. Restored entry observed in a live snapshot, signature changed
+The restored entry is deleted and a new active entry starts via
+`_startActiveEntry`. This is PR #4057's promotion path. `streamCall`
+fires once — its first and only fire for this `toolCallId`.
+
+### C.4. `isLoading` transitions `true → false` while messages are stable
+The next `setState` call sees `isLoading === false` and processes
+messages as live. Snapshots observed while `isLoading` was true seeded
+restored entries. The first live snapshot promotes any whose signature
+changed.
+
+### C.5. `isLoading` transitions `false → true` mid-session
+Treated as a return to the historical-loading window. Subsequent
+snapshots are recorded as restored. Tool calls observed live before the
+transition keep their active controllers — the tracker does not unwind
+them.
+
+## D. Nested tool calls (PTC sub-tools via `content.messages`)
+
+### D.1. Parent tool's nested messages are observed
+The tracker recurses via `_processMessages(content.messages)`. Nested
+tool calls go through the same restore / live / promotion logic as
+top-level ones, all under the same exactly-once contract.
+
+### D.2. Nested tool's parent gets a new `result`
+Handled like A.5 for the parent; the recursion into `content.messages`
+still runs in the same pass, so nested tool calls also get processed.
+
+### D.3. Nested tool's `content.messages` itself changes
+Identity is by `toolCallId`, not index. A different `toolCallId` at
+the same nested position is a fresh tool call. Same id with different
+shape goes through A.1–A.4.
+
+## E. Malformed snapshot
+
+### E.1. `message` is null/undefined or `message.content` is not an array
+Skipped silently. The rest of the snapshot still processes.
+
+### E.2. `content` item is null or not a tool-call part
+Skipped silently. Other parts in the same `message.content` still process.
+
+### E.3. Different `messages` reference, identical contents
+The tracker re-walks the array on every non-identity snapshot. The
+reference-equality fast path in `setState` rarely fires for class
+consumers (external-store rebuilds the array on every adapter update).
+
+### E.4. `setState` throws inside `_processMessages`
+The top-level try/catch in `setState` swallows the error and logs.
+`_lastSnapshot` and `_isRunning` mutations are deferred until *after*
+successful processing, so a transient failure does not corrupt the
+tracker's view of "what we last observed". The next snapshot retries.
+
+## F. Concurrency and lifecycle
+
+### F.1. `reset()` called while `execute()` invocations are in flight
+`abort()` is invoked, in-flight executions reject with
+`Tool execution aborted`. Once they settle, the cleanup logic clears
+`_executing`. The settled-resolver promises fire so the abort promise
+resolves.
+
+### F.2. `setState` called during `reset()`'s in-flight abort
+The new snapshot is processed against an empty `_entries`. Tool calls
+in it are seeded as restored (because `reset()` re-armed
+`_pendingRestore`). Eventual cancellation `result` chunks for the
+aborted executions are dropped via `_skipExecuteStreamIds`.
+
+### F.3. `resume(toolCallId, payload)` for an unknown id
+Silently no-ops. (The pre-class hook *threw*; the tracker softens this
+to match the never-throw guarantee.)
+
+### F.4. Assistant-stream pipeline itself errors
+The `.pipeTo(...).catch(...)` handler logs and flips `_pipelineDead`.
+The next `setState` call recreates the pipeline once per tracker
+lifetime: existing active entries are *demoted to restored* (so the
+rebuilt pipeline does not re-fire `streamCall` for them) and the
+snapshot is processed against the fresh pipeline. Repeated failures
+keep the tracker dead with a visible error to avoid restart loops.
+
+## Known limitations
+
+### Result delivery after args regression (A.2 + A.5 in the same snapshot)
+When a snapshot has both a regressed `argsText` *and* a backend result
+on the same tool call, `activeController.setResponse(result)` closes
+`argsText` before enqueueing the result chunk. The args-text-finish
+chunk reaches `ToolExecutionStream` first, attempts to parse the
+(stale) accumulated argsText, fails, and emits a parse-error result
+that beats the backend result to the reader's response promise.
+
+The tracker's `entry.hasResult` short-circuit *does* suppress both
+result chunks at the `onResult` callback level (no double-fire), but
+the reader's `response.get()` already resolved with the parse error.
+
+Fixable upstream in `ToolCallStreamControllerImpl.setResponse` by
+enqueueing the result chunk before closing argsText. Tracked separately;
+out of scope for the tracker layer.
+
+### Host callback throws
+`onResult` and `onStatusesChange` are invoked through wrappers that
+catch and log. The tracker continues to function; the host's bad
+callback is isolated.
+
+### Args-stream divergence after A.2 / A.4
+Documented in the corresponding sections. The host's `streamCall` may
+operate on stale args. The `reader.events()` follow-up gives consumers
+a way to observe and react to these post-completion transitions.