@assistant-ui/core 0.3.13 → 0.3.15

package/src/runtimes/remote-thread-list/empty-thread-core.ts

@@ -1,234 +1,45 @@
+import type { Unsubscribe } from "../../types/unsubscribe";
 import type { ThreadRuntimeCore } from "../../runtime/interfaces/thread-runtime-core";
+import {
+  InertThreadRuntimeCore,
+  createInertComposer,
+} from "../inert/InertThreadRuntimeCore";
 
 const EMPTY_THREAD_ERROR = new Error(
   "This is the empty thread, a placeholder for the main thread. You cannot perform any actions on this thread instance. This error is probably because you tried to call a thread method in your render function. Call the method inside a `useEffect` hook instead.",
 );
-export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
-  getMessageById() {
-    return undefined;
-  },
-
-  getBranches() {
-    return [];
-  },
-
-  switchToBranch() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  append() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  deleteMessage() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  startRun() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  resumeRun() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  cancelRun() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  addToolResult() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  resumeToolCall() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  respondToToolApproval() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  speak() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  stopSpeaking() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  connectVoice() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  disconnectVoice() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  getVoiceVolume: () => 0,
-  subscribeVoiceVolume: () => () => {},
-
-  muteVoice() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  unmuteVoice() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  submitFeedback() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  getModelContext() {
-    return {};
-  },
-
-  exportExternalState() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  importExternalState() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  composer: {
-    attachments: [],
-    attachmentAccept: "*",
-
-    async addAttachment() {
-      throw EMPTY_THREAD_ERROR;
-    },
-
-    async removeAttachment() {
-      throw EMPTY_THREAD_ERROR;
-    },
-
-    isEditing: true,
-
-    canCancel: false,
-    canSend: false,
-    isEmpty: true,
 
-    text: "",
+class EmptyThreadRuntimeCore extends InertThreadRuntimeCore {
+  protected get error() {
+    return EMPTY_THREAD_ERROR;
+  }
 
-    setText() {
-      throw EMPTY_THREAD_ERROR;
-    },
+  messages = [] as never[];
 
-    role: "user",
+  composer = createInertComposer(EMPTY_THREAD_ERROR, true);
 
-    setRole() {
-      throw EMPTY_THREAD_ERROR;
-    },
+  isLoading = true;
 
-    runConfig: {},
-
-    setRunConfig() {
-      throw EMPTY_THREAD_ERROR;
-    },
-
-    async reset() {
-      // noop
-    },
-
-    async clearAttachments() {
-      // noop
-    },
-
-    send() {
-      throw EMPTY_THREAD_ERROR;
-    },
-
-    cancel() {
-      // noop
-    },
-
-    queue: [] as never[],
-    moveQueueItem() {},
-    removeQueueItem() {},
-
-    dictation: undefined,
-
-    startDictation() {
-      throw EMPTY_THREAD_ERROR;
-    },
-
-    stopDictation() {
-      // noop
-    },
-
-    quote: undefined,
-
-    setQuote() {
-      throw EMPTY_THREAD_ERROR;
-    },
-
-    subscribe() {
-      return () => {};
-    },
-
-    unstable_on() {
-      return () => {};
-    },
-  },
-
-  getEditComposer() {
+  getMessageById() {
     return undefined;
-  },
+  }
 
-  beginEdit() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  speech: undefined,
-  voice: undefined,
-
-  capabilities: {
-    switchToBranch: false,
-    switchBranchDuringRun: false,
-    edit: false,
-    delete: false,
-    reload: false,
-    refetchThread: false,
-    cancel: false,
-    unstable_copy: false,
-    speech: false,
-    dictation: false,
-    voice: false,
-    attachments: false,
-    feedback: false,
-    queue: false,
-  },
-
-  isDisabled: false,
-  isSendDisabled: false,
-  isLoading: true,
-
-  messages: [],
-
-  state: null,
-
-  suggestions: [],
-
-  extras: undefined,
-
-  subscribe() {
-    return () => {};
-  },
-
-  import() {
-    throw EMPTY_THREAD_ERROR;
-  },
+  getBranches() {
+    return [];
+  }
 
   export() {
     return { messages: [] };
-  },
+  }
 
-  reset() {
-    throw EMPTY_THREAD_ERROR;
-  },
-
-  unstable_on() {
+  override subscribe(): Unsubscribe {
     return () => {};
-  },
-};
+  }
+
+  override waitForUpdate(): Promise<void> {
+    return Promise.reject(EMPTY_THREAD_ERROR);
+  }
+}
+
+export const EMPTY_THREAD_CORE: ThreadRuntimeCore =
+  new EmptyThreadRuntimeCore();

package/src/runtimes/remote-thread-list/optimistic-state.test.ts

@@ -60,4 +60,22 @@ describe("OptimisticState", () => {
 
     expect(state.value.title).toBe("Project Beta");
   });
+
+  it("drops an in-flight transform after reset", async () => {
+    const state = new OptimisticState({ title: "Untitled", extra: 0 });
+    const request = deferred();
+    const update = state.optimisticUpdate({
+      execute: () => request.promise,
+      optimistic: (value) => ({ ...value, title: "Pending" }),
+      then: (value) => ({ ...value, extra: 1 }),
+    });
+
+    expect(state.value.title).toBe("Pending");
+    state.reset({ title: "Fresh", extra: 0 });
+    expect(state.value).toEqual({ title: "Fresh", extra: 0 });
+
+    request.resolve();
+    await update;
+    expect(state.value).toEqual({ title: "Fresh", extra: 0 });
+  });
 });

package/src/runtimes/remote-thread-list/optimistic-state.ts

@@ -48,6 +48,7 @@ export class OptimisticState<TState> extends BaseSubscribable {
     [];
 
   private _nextTransformOrder = 0;
+  private _epoch = 0;
 
   private _baseValue: TState;
   private _cachedValue: TState;
@@ -95,9 +96,20 @@ export class OptimisticState<TState> extends BaseSubscribable {
     this._updateState();
   }
 
+  public reset(state: TState): void {
+    // In-flight optimisticUpdate calls must not write into the replacement state.
+    this._epoch++;
+    this._pendingTransforms.length = 0;
+    this._completedOptimistics.length = 0;
+    this._baseValue = state;
+    this._cachedValue = state;
+    this._notifySubscribers();
+  }
+
   public async optimisticUpdate<TResult>(
     transform: Transform<TState, TResult>,
   ): Promise<TResult> {
+    const epoch = this._epoch;
     const order = this._nextTransformOrder++;
     const task = transform.execute();
     const pendingTransform = {
@@ -110,6 +122,7 @@ export class OptimisticState<TState> extends BaseSubscribable {
       this._updateState();
 
       const result = await task;
+      if (epoch !== this._epoch) return result;
       this._baseValue = pipeTransforms(this._baseValue, result, [
         transform.optimistic,
         transform.then,

package/src/runtimes/remote-thread-list/types.ts

@@ -1,6 +1,9 @@
 import type { ThreadMessage } from "../../types/message";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type { AssistantStream } from "assistant-stream";
+import type { ThreadHistoryAdapter } from "../../adapters/thread-history";
+import type { AttachmentAdapter } from "../../adapters/attachment";
+import type { ModelContextProvider } from "../../model-context/types";
 
 /* oxlint-disable typescript/no-explicit-any -- structural stand-in for ComponentType without depending on react types */
 type RemoteThreadListProviderProps = { children?: any };
@@ -33,6 +36,12 @@ export type RemoteThreadListPageOptions = {
   after?: string | undefined;
 };
 
+export type RuntimeAdapters = {
+  modelContext?: ModelContextProvider | undefined;
+  history?: ThreadHistoryAdapter | undefined;
+  attachments?: AttachmentAdapter | undefined;
+};
+
 export type RemoteThreadListAdapter = {
   list(params?: RemoteThreadListPageOptions): Promise<RemoteThreadListResponse>;
 
@@ -56,16 +65,41 @@ export type RemoteThreadListAdapter = {
    * inject per-thread context such as a history or attachments adapter (see
    * `useCloudThreadListAdapter` for the canonical shape).
    *
+   * `useRemoteThreadListRuntime` renders this component when present. If it
+   * is omitted, that host synthesizes a `RuntimeAdapterProvider` from
+   * `unstable_useAdapters`. The `RemoteThreadList` store entry ignores it;
+   * expose `unstable_useAdapters` for that host.
+   *
    * The Provider must render `children` on its first commit; deferring them
    * behind a loading state, a Suspense boundary, or a `useEffect`-gated render
    * is unsupported and leaves thread context unavailable to downstream
    * consumers. Load data inside an always-mounted child instead.
    */
   unstable_Provider?: RemoteThreadListProviderComponent | undefined;
+
+  /**
+   * Hook the `RemoteThreadList` store entry calls once for the main-thread
+   * slot, then provides to the `thread` factory. This is not mounted per
+   * listed thread. `useRemoteThreadListRuntime` also calls it when
+   * `unstable_Provider` is omitted. Resolve `threadListItem` lazily on each
+   * adapter call; do not capture it at hook mount. The hook must keep a
+   * stable hook count across adapter swaps; a different count throws.
+   * Memoize the returned object.
+   *
+   * Per-thread history also requires the `thread` factory to be keyed by
+   * thread id (`withKey(id, thread(...))`). History loaders such as
+   * `useExternalHistory` run once per mount; an unkeyed factory keeps one
+   * instance across switches and the next thread's messages never load.
+   */
+  unstable_useAdapters?: (() => RuntimeAdapters | null | undefined) | undefined;
 };
 
 export type RemoteThreadListOptions = {
   runtimeHook: () => AssistantRuntime;
+
+  /**
+   * The adapter reference should remain stable across renders. Replacing it reloads the list and drops cached threads that are not in the replacement page. In-flight mutations from the previous adapter are cancelled.
+   */
   adapter: RemoteThreadListAdapter;
 
   /**

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

@@ -10,6 +10,9 @@ observe via `setState(snapshot)` and what the current behavior is.
 > 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.
+>
+> `reset()` starts a new execution boundary. A reused `toolCallId` in the
+> next boundary gets a new execution identity and may fire once there.
 
 This guarantees host-side side effects (the typical reason `streamCall` /
 `execute` exists at all) can't double-run. The cost: post-completion
@@ -65,7 +68,7 @@ The tracker calls `setResponse` on the active controller and closes it.
 The backend result is emitted before the args stream closes, so a stale
 args parse failure cannot replace it. `reader.response.get()` resolves.
 If the tool also had a frontend `execute`, the executor is short-circuited
-via `_skipExecuteStreamIds`. Single fire.
+via the entry's per-execution skip marker. Single fire.
 
 ### A.6. Previously-resolved tool's `result` is replaced
 Silently ignored — `entry.hasResult` short-circuits both the
@@ -153,15 +156,16 @@ tracker's view of "what we last observed". The next snapshot retries.
 
 ### 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.
+`Tool execution aborted`. Once they settle, the cleanup logic removes their
+execution identities from `_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`.
+`_pendingRestore`). Eventual cancellation `result` chunks for the aborted
+executions are dropped when their execution identity no longer matches the
+current entry.
 
 ### F.3. `resume(toolCallId, payload)` for an unknown id
 Silently no-ops. (The pre-class hook *threw*; the tracker softens this
@@ -175,6 +179,13 @@ 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.
 
+### F.5. Reset followed by same-id reuse
+The assistant-stream pipeline assigns each streamed tool part an opaque
+execution identity. Human-input callbacks, lifecycle callbacks, result chunks,
+and pending execution cleanup are accepted only when that identity is still
+current for the `toolCallId`. A late callback from before `reset()` is therefore
+dropped even when the next session reuses the id.
+
 ## Known limitations
 
 ### Host callback throws

package/src/runtimes/tool-invocations/ToolInvocationTracker.test.ts

@@ -1172,3 +1172,246 @@ describe("ToolInvocationTracker", () => {
     }
   });
 });
+
+describe("ToolInvocationTracker reset", () => {
+  const trackerWith = (tools: Record<string, Tool>) => {
+    let statuses: Record<string, ToolExecutionStatus> = {};
+    const tracker = new ToolInvocationTracker(() => tools, {
+      onResult: vi.fn(),
+      onStatusesChange: (s: ReadonlyMap<string, ToolExecutionStatus>) => {
+        statuses = Object.fromEntries(s);
+      },
+    });
+    return { tracker, statuses: () => statuses };
+  };
+
+  it("clears statuses for discarded executions that never settle", async () => {
+    const { tracker, statuses } = trackerWith({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute: vi.fn(() => new Promise(() => {})),
+      } satisfies Tool,
+    });
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage('{"query":"London"}', { query: "London" }),
+      ]),
+    );
+    await waitFor(() => {
+      expect(statuses()["tool-1"]?.type).toBe("executing");
+    });
+
+    tracker.reset();
+
+    expect(statuses()).toEqual({});
+
+    // A new-session snapshot restoring tool activity must not drag the
+    // discarded id back in through the whole-map republication. The first
+    // post-reset snapshot is the fresh session's empty state, consuming the
+    // pending-restore mark.
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage(
+          '{"query":"Paris"}',
+          { query: "Paris" },
+          { toolCallId: "tool-2" },
+        ),
+      ]),
+    );
+    await waitFor(() => {
+      expect(statuses()["tool-2"]?.type).toBe("executing");
+    });
+    expect(statuses()["tool-1"]).toBeUndefined();
+  });
+
+  it("does not republish sibling statuses when a discarded execution settles after reset", async () => {
+    const settled = Promise.withResolvers<void>();
+    const { tracker, statuses } = trackerWith({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute: vi.fn(
+          (_args, { abortSignal }: { abortSignal: AbortSignal }) =>
+            new Promise((resolve) => {
+              abortSignal.addEventListener("abort", () => {
+                resolve({ ok: true });
+                settled.resolve();
+              });
+            }),
+        ),
+      } satisfies Tool,
+      pressureSearch: {
+        parameters: { type: "object", properties: {} },
+        execute: vi.fn(() => new Promise(() => {})),
+      } satisfies Tool,
+    });
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage('{"query":"London"}', { query: "London" }),
+        createAssistantMessage(
+          '{"query":"London"}',
+          { query: "London" },
+          {
+            toolCallId: "tool-2",
+            toolName: "pressureSearch",
+          },
+        ),
+      ]),
+    );
+    await waitFor(() => {
+      expect(statuses()["tool-1"]?.type).toBe("executing");
+      expect(statuses()["tool-2"]?.type).toBe("executing");
+    });
+
+    tracker.reset();
+    expect(statuses()).toEqual({});
+
+    // The settle-after-abort of tool-1 is what could republish tool-2;
+    // await it deterministically instead of sleeping.
+    await settled.promise;
+    await new Promise((r) => setTimeout(r, 0));
+    expect(statuses()).toEqual({});
+  });
+
+  it("rejects a human-input request from a discarded execution without resurrecting its status", async () => {
+    let humanFn: ((payload: unknown) => Promise<unknown>) | undefined;
+    const { tracker, statuses } = trackerWith({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute: vi.fn(() => new Promise(() => {})),
+        streamCall: vi.fn((_reader, { human }) => {
+          humanFn = human;
+        }),
+      } satisfies Tool,
+    });
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage('{"query":"London"}', { query: "London" }),
+      ]),
+    );
+    await waitFor(() => {
+      expect(statuses()["tool-1"]?.type).toBe("executing");
+      expect(humanFn).toBeDefined();
+    });
+
+    tracker.reset();
+
+    await expect(humanFn!({ request: "approve" })).rejects.toThrow(
+      "Tool execution aborted",
+    );
+    expect(statuses()).toEqual({});
+  });
+
+  it("rejects a late human-input request when reset reuses the tool call id", async () => {
+    const humanFns: ((payload: unknown) => Promise<unknown>)[] = [];
+    const { tracker, statuses } = trackerWith({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute: vi.fn(() => new Promise(() => {})),
+        streamCall: vi.fn((_reader, { human }) => {
+          humanFns.push(human);
+        }),
+      } satisfies Tool,
+    });
+
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage('{"query":"London"}', { query: "London" }),
+      ]),
+    );
+    await waitFor(() => {
+      expect(humanFns).toHaveLength(1);
+      expect(statuses()["tool-1"]?.type).toBe("executing");
+    });
+
+    tracker.reset();
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage(
+          '{"query":"Paris"}',
+          { query: "Paris" },
+          { toolCallId: "tool-1" },
+        ),
+      ]),
+    );
+    await waitFor(() => expect(humanFns).toHaveLength(2));
+
+    await expect(humanFns[0]!({ stale: true })).rejects.toThrow(
+      "Tool execution aborted",
+    );
+    expect(statuses()["tool-1"]?.type).toBe("executing");
+
+    tracker.reset();
+  });
+
+  it("drops a late result when reset reuses the tool call id", async () => {
+    const executions: Array<{
+      resolve: (value: { session: string }) => void;
+      promise: Promise<{ session: string }>;
+    }> = [];
+    const onResult = vi.fn();
+    const tracker = new ToolInvocationTracker(
+      () => ({
+        weatherSearch: {
+          parameters: { type: "object", properties: {} },
+          execute: vi.fn(
+            (_args: unknown, { abortSignal }: { abortSignal: AbortSignal }) => {
+              let resolveExecution!: (value: { session: string }) => void;
+              const promise = new Promise<{ session: string }>((resolve) => {
+                resolveExecution = resolve;
+              });
+              const execution = { promise, resolve: resolveExecution };
+              abortSignal.addEventListener("abort", () => {
+                execution.resolve({ session: "old" });
+              });
+              executions.push(execution);
+              return promise;
+            },
+          ),
+        } satisfies Tool,
+      }),
+      { onResult, onStatusesChange: vi.fn() },
+    );
+
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage('{"query":"London"}', { query: "London" }),
+      ]),
+    );
+    await waitFor(() => expect(executions).toHaveLength(1));
+
+    tracker.reset();
+    tracker.setState(createState([]));
+    tracker.setState(
+      createState([
+        createAssistantMessage(
+          '{"query":"Paris"}',
+          { query: "Paris" },
+          { toolCallId: "tool-1" },
+        ),
+      ]),
+    );
+    await waitFor(() => expect(executions).toHaveLength(2));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(onResult).not.toHaveBeenCalled();
+
+    executions[1]!.resolve({ session: "new" });
+    await waitFor(() => {
+      expect(onResult).toHaveBeenCalledOnce();
+      expect(onResult).toHaveBeenCalledWith(
+        expect.objectContaining({
+          toolCallId: "tool-1",
+          result: { session: "new" },
+        }),
+      );
+    });
+
+    tracker.reset();
+  });
+});