@assistant-ui/core 0.2.20 → 0.2.22

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

@@ -41,6 +41,15 @@ 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.
 
+The args stream closes only when the controller's *streamed* content
+(`entry.argsText`) is complete, not when a later snapshot is. A divergent
+snapshot can be complete while the controller still holds an incomplete
+stale prefix; closing on the snapshot would parse that stale prefix and
+auto-submit a bogus parse-error result (resuming the host graph and
+abandoning a pending interrupt). Gating the close on the streamed content
+leaves the stream open until the prefix itself completes, so no stale
+parse runs and no error result is fabricated from divergent args.
+
 ### 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`
@@ -53,9 +62,10 @@ 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.
+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.
 
 ### A.6. Previously-resolved tool's `result` is replaced
 Silently ignored — `entry.hasResult` short-circuits both the
@@ -167,22 +177,6 @@ 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

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

@@ -152,6 +152,131 @@ describe("ToolInvocationTracker", () => {
     }
   });
 
+  it("does not auto-submit a parse-error result when divergent argsText closes without a backend result (#5130)", async () => {
+    // Mirrors the #5098 production shape: a human-in-the-loop tool whose
+    // argsText diverges mid-stream and never re-converges, with no backend
+    // result at close time. The args stream must not close on the divergent
+    // snapshot (which holds a stale prefix the execution path would parse),
+    // so no bogus parse-error result is auto-submitted to resume the host
+    // graph and abandon the pending interrupt.
+    const execute = vi.fn(async () => ({ forecast: "ok" }));
+    const streamCall = vi.fn((_reader, { human }) => {
+      // Request human input immediately — sets up the pending interrupt.
+      void human({ request: "approve" });
+    });
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+        execute,
+        streamCall,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    let statuses: Record<string, ToolExecutionStatus> = {};
+    const onStatusesChange = (s: ReadonlyMap<string, ToolExecutionStatus>) => {
+      statuses = Object.fromEntries(s);
+    };
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const tracker = new ToolInvocationTracker(getTools, {
+        onResult,
+        onStatusesChange,
+      });
+      tracker.setState(createState([]));
+
+      tracker.setState(
+        createState([
+          createAssistantMessage('{"query":"London","longitude":0', {
+            query: "London",
+            longitude: 0,
+          }),
+        ]),
+      );
+
+      // The pending interrupt is set up via streamCall → human().
+      await waitFor(() => {
+        expect(statuses["tool-1"]?.type).toBe("interrupt");
+      });
+
+      // Divergent regression (not a prefix of the streamed text).
+      tracker.setState(
+        createState([
+          createAssistantMessage('{"query":"London","longitude":-0.125', {
+            query: "London",
+            longitude: -0.125,
+          }),
+        ]),
+      );
+
+      // Complete valid JSON, divergent from the streamed prefix, no backend
+      // result. Previously this closed the args stream on the snapshot's
+      // completeness, parsed the stale prefix, and auto-submitted an error.
+      tracker.setState(
+        createState([
+          createAssistantMessage(
+            '{"query":"London","longitude":-0.125,"latitude":51.5072}',
+            { query: "London", longitude: -0.125, latitude: 51.5072 },
+          ),
+        ]),
+      );
+
+      for (let i = 0; i < 5; i++) {
+        await new Promise((r) => setTimeout(r, 0));
+      }
+
+      // No bogus parse-error result is auto-submitted, so the host graph is
+      // not resumed with a fake tool failure and the pending interrupt is
+      // preserved.
+      expect(onResult).not.toHaveBeenCalled();
+      // The frontend execute never ran: the stale prefix was never parsed.
+      expect(execute).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("does not auto-submit a parse-error result for a non-executable tool whose divergent argsText closes (#5130)", async () => {
+    // Same close-gating mismatch as the executable case, but for a tool with
+    // no frontend execute. Closing on the divergent complete snapshot would
+    // still parse the incomplete stale prefix and fabricate a parse-error
+    // result, so the close must gate on the controller's streamed content.
+    const getTools = () => ({
+      weatherSearch: {
+        parameters: { type: "object", properties: {} },
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const onStatusesChange = () => {};
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const tracker = new ToolInvocationTracker(getTools, {
+        onResult,
+        onStatusesChange,
+      });
+      tracker.setState(createState([]));
+
+      // Incomplete prefix while the run is still streaming.
+      tracker.setState(
+        createState([createAssistantMessage('{"a":1', { a: 1 })], true),
+      );
+
+      // Run settles and the snapshot regresses to a complete divergent text.
+      tracker.setState(
+        createState([createAssistantMessage('{"a":2}', { a: 2 })], false),
+      );
+
+      for (let i = 0; i < 5; i++) {
+        await new Promise((r) => setTimeout(r, 0));
+      }
+
+      expect(onResult).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
   it("clears executing status under the logical toolCallId when reset() lands while execute is pending", async () => {
     // Tests the F.1 lifecycle: reset() aborts in-flight execute() invocations
     // and clears their executing status. The status key is the logical
@@ -948,12 +1073,8 @@ describe("ToolInvocationTracker", () => {
     // result replacement) and verifying streamCall fires exactly once.
     //
     // The pathological mid-stream regression case (A.2) is covered by
-    // the dedicated regression test above. Mixing A.2 with a backend
-    // result in the same snapshot exposes a separate issue inside
-    // assistant-stream's `ToolCallStreamController.setResponse` ordering
-    // (parse-failure result reaches the reader before the backend
-    // result); that's tracked separately and out of scope for the
-    // tracker-level contract.
+    // the assistant-stream ordering regression test in
+    // packages/assistant-stream/src/core/modules/tool-call.test.ts.
     const streamCall = vi.fn();
     const execute = vi.fn(async () => ({ forecast: "ok" }));
     const getTools = () => ({

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

@@ -687,14 +687,16 @@ export class ToolInvocationTracker {
     }
 
     if (!entry.argsComplete && entry.controller) {
+      // ToolExecutionStream parses the streamed prefix on close, so the close
+      // gates on the streamed content; a divergent snapshot (A.2) can be
+      // complete while the controller still holds an incomplete stale prefix.
       const shouldClose = this._shouldCloseArgsStream({
         toolName: content.toolName,
-        argsText: content.argsText,
+        argsText: entry.argsText,
         hasResult,
       });
       if (shouldClose) {
         entry.controller.argsText.close();
-        entry.argsText = content.argsText;
         entry.argsComplete = true;
       }
     }

package/src/subscribable/subscribable.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from "vitest";
+import type { SubscribableWithState } from "./subscribable";
+import { ShallowMemoizeSubject } from "./subscribable";
+
+type TestState = {
+  status: string;
+  error?: string;
+};
+
+const createBinding = (initialState: TestState) => {
+  let state = initialState;
+  const subscribers = new Set<() => void>();
+
+  const binding: SubscribableWithState<TestState, null> = {
+    path: null,
+    getState: () => state,
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => subscribers.delete(callback);
+    },
+  };
+
+  return {
+    binding,
+    update(nextState: TestState) {
+      state = nextState;
+      for (const callback of subscribers) callback();
+    },
+  };
+};
+
+describe("ShallowMemoizeSubject", () => {
+  it("notifies subscribers when a state key is removed", () => {
+    const source = createBinding({
+      status: "running",
+      error: "Connection failed",
+    });
+    const subject = new ShallowMemoizeSubject(source.binding);
+    const subscriber = vi.fn();
+    subject.subscribe(subscriber);
+
+    source.update({ status: "running" });
+
+    expect(subscriber).toHaveBeenCalledOnce();
+    expect(subject.getState()).toEqual({ status: "running" });
+  });
+
+  it("does not notify subscribers for a shallow-equal state", () => {
+    const source = createBinding({ status: "running" });
+    const subject = new ShallowMemoizeSubject(source.binding);
+    const subscriber = vi.fn();
+    subject.subscribe(subscriber);
+
+    source.update({ status: "running" });
+
+    expect(subscriber).not.toHaveBeenCalled();
+  });
+});

package/src/subscribable/subscribable.ts

@@ -1,4 +1,5 @@
 import type { Unsubscribe } from "../types/unsubscribe";
+import { notifyEventListeners } from "../utils/notify-event-listeners";
 
 export const SKIP_UPDATE = Symbol("skip-update");
 export type SKIP_UPDATE = typeof SKIP_UPDATE;
@@ -39,7 +40,10 @@ function shallowEqual<T extends object>(
   if (objA === undefined) return false;
   if (objB === undefined) return false;
 
-  for (const key of Object.keys(objA)) {
+  const keysA = Object.keys(objA);
+  if (keysA.length !== Object.keys(objB).length) return false;
+
+  for (const key of keysA) {
     const valueA = objA[key as keyof T];
     const valueB = objB[key as keyof T];
     if (!Object.is(valueA, valueB)) return false;
@@ -99,7 +103,12 @@ export abstract class BaseSubject {
 
   protected abstract _connect(): Unsubscribe;
 
-  protected notifySubscribers(payload?: unknown) {
+  protected notifySubscribers(payload?: unknown, errorContext?: string) {
+    if (errorContext) {
+      notifyEventListeners(this._subscriptions, payload, errorContext);
+      return;
+    }
+
     for (const callback of this._subscriptions) callback(payload);
   }
 
@@ -273,8 +282,9 @@ export class EventSubscriptionSubject<
   }
 
   protected _connect(): Unsubscribe {
+    const errorContext = `Runtime event "${this.config.event}"`;
     const callback = (payload?: unknown) => {
-      this.notifySubscribers(payload);
+      this.notifySubscribers(payload, errorContext);
     };
 
     let lastState = this.config.binding.getState();

package/src/tests/MessageRepository.test.ts

@@ -309,6 +309,32 @@ describe("MessageRepository", () => {
       expect(exported.headId).toBe("u");
     });
 
+    it("re-parents children of a skipped optimistic message in export()", () => {
+      repository.addOrUpdateMessage(null, createTestMessage({ id: "u1" }));
+      repository.addOrUpdateMessage("u1", optimistic({ id: "a1" }));
+      repository.addOrUpdateMessage(
+        "a1",
+        createTestMessage({ id: "u2", role: "user" }),
+      );
+      repository.addOrUpdateMessage("u2", createTestMessage({ id: "a2" }));
+      repository.resetHead("a2");
+
+      const exported = repository.export();
+      const byId = new Map(exported.messages.map((m) => [m.message.id, m]));
+
+      expect([...byId.keys()].sort()).toEqual(["a2", "u1", "u2"]);
+      expect(byId.get("u2")?.parentId).toBe("u1");
+      expect(byId.get("a2")?.parentId).toBe("u2");
+
+      const restored = new MessageRepository();
+      restored.import(exported);
+      expect(restored.getMessages().map((m) => m.id)).toEqual([
+        "u1",
+        "u2",
+        "a2",
+      ]);
+    });
+
     it("round-trips through export/import without resurrecting the placeholder", () => {
       const parent = createTestMessage({ id: "u" });
       const real = createTestMessage({ id: "a" });

package/src/tests/OptimisticState-list-race.test.ts

@@ -79,6 +79,39 @@ const applyListResult = (
 };
 
 describe("list + delete race condition", () => {
+  it("stale list() does not re-add a thread deleted before list started", async () => {
+    const state = new OptimisticState<RemoteThreadState>(
+      applyListResult(EMPTY_STATE, {
+        threads: [{ remoteId: "thread-A", status: "regular", title: "A" }],
+      }),
+    );
+    const deleteDeferred = deferred<void>();
+    const listDeferred = deferred<ListResult>();
+
+    const deletePromise = state.optimisticUpdate({
+      execute: () => deleteDeferred.promise,
+      optimistic: (s) => updateStatusReducer(s, "thread-A", "deleted"),
+    });
+    const listPromise = state.optimisticUpdate({
+      execute: () => listDeferred.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    deleteDeferred.resolve();
+    await deletePromise;
+
+    listDeferred.resolve({
+      threads: [{ remoteId: "thread-A", status: "regular", title: "A" }],
+    });
+    await listPromise;
+
+    expect(state.value.threadIds).not.toContain("thread-A");
+    expect(
+      state.value.threadData[createThreadMappingId("thread-A")],
+    ).toBeUndefined();
+  });
+
   it("stale list() does not re-add a thread deleted while list was in flight", async () => {
     const state = new OptimisticState<RemoteThreadState>(EMPTY_STATE);
 

package/src/tests/RemoteThreadListThreadListRuntimeCore-errors.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from "vitest";
+import { createCore, makeAdapter } from "./remote-thread-list-test-helpers";
+import { InMemoryThreadListAdapter } from "../runtimes/remote-thread-list/adapter/in-memory";
+
+describe("RemoteThreadListThreadListRuntimeCore errors", () => {
+  it("includes the requested thread id when a thread is missing", () => {
+    const core = createCore(makeAdapter());
+
+    expect(() => core.rename("missing-thread", "New title")).toThrow(
+      'Thread "missing-thread" not found while renaming it.',
+    );
+  });
+
+  it("includes the requested thread id and status when an operation is invalid", async () => {
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [
+          {
+            status: "archived" as const,
+            remoteId: "archived-thread",
+            externalId: "archived-thread",
+            title: "Archived",
+          },
+        ],
+      })),
+    });
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    await expect(core.archive("archived-thread")).rejects.toThrow(
+      'Thread "archived-thread" has status "archived", so it cannot be archived.',
+    );
+  });
+
+  it("includes the requested thread id when the in-memory adapter cannot fetch it", async () => {
+    const adapter = new InMemoryThreadListAdapter();
+
+    await expect(adapter.fetch("missing-thread")).rejects.toThrow(
+      'Thread "missing-thread" not found in in-memory thread list.',
+    );
+  });
+});

package/src/tests/RemoteThreadListThreadListRuntimeCore-switchToThread-order.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect, it, vi } from "vitest";
+import type { RemoteThreadMetadata } from "../runtimes/remote-thread-list/types";
+import {
+  createCore,
+  deferred,
+  makeAdapter,
+  setStartThreadRuntime,
+} from "./remote-thread-list-test-helpers";
+
+const thread = (id: string): RemoteThreadMetadata => ({
+  status: "regular",
+  remoteId: id,
+  externalId: id,
+  title: id,
+});
+
+describe("RemoteThreadListThreadListRuntimeCore.switchToThread order", () => {
+  it("preserves the latest switch when an earlier fetch resolves last", async () => {
+    const fetchB = deferred<RemoteThreadMetadata>();
+    const fetchC = deferred<RemoteThreadMetadata>();
+    const adapter = makeAdapter({
+      fetch: vi.fn((id: string) =>
+        id === "thread-b" ? fetchB.promise : fetchC.promise,
+      ),
+    });
+    const core = createCore(adapter);
+
+    const switchToB = core.switchToThread("thread-b");
+    const switchToC = core.switchToThread("thread-c");
+
+    fetchC.resolve(thread("thread-c"));
+    await switchToC;
+    fetchB.resolve(thread("thread-b"));
+    await switchToB;
+
+    expect(core.mainThreadId).toBe(core.getItemById("thread-c")?.id);
+  });
+
+  it("preserves the latest switch when an earlier runtime starts last", async () => {
+    const runtimeB = deferred<unknown>();
+    const runtimeC = deferred<unknown>();
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({
+        threads: [thread("thread-b"), thread("thread-c")],
+      })),
+    });
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    setStartThreadRuntime(core, (id) =>
+      id === core.getItemById("thread-b")?.id
+        ? runtimeB.promise
+        : runtimeC.promise,
+    );
+
+    const switchToB = core.switchToThread("thread-b");
+    const switchToC = core.switchToThread("thread-c");
+
+    runtimeC.resolve({});
+    await switchToC;
+    runtimeB.resolve({});
+    await switchToB;
+
+    expect(core.mainThreadId).toBe(core.getItemById("thread-c")?.id);
+  });
+
+  it("invalidates an earlier switch while a new thread request is pending", async () => {
+    const initializeThread = deferred<{
+      remoteId: string;
+      externalId: string;
+    }>();
+    const runtimeB = deferred<unknown>();
+    const adapter = makeAdapter({
+      initialize: vi.fn(() => initializeThread.promise),
+      list: vi.fn(async () => ({ threads: [thread("thread-b")] })),
+    });
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    const initialNewThreadId = core.newThreadId;
+    if (!initialNewThreadId) throw new Error("Expected an initial new thread");
+
+    const threadBId = core.getItemById("thread-b")?.id;
+    setStartThreadRuntime(core, (id) =>
+      id === threadBId ? runtimeB.promise : Promise.resolve({}),
+    );
+
+    const initialize = core.initialize(initialNewThreadId);
+    const switchToB = core.switchToThread("thread-b");
+    const switchToNewThread = core.switchToNewThread();
+
+    runtimeB.resolve({});
+    await switchToB;
+
+    expect(core.mainThreadId).not.toBe(threadBId);
+
+    initializeThread.resolve({
+      remoteId: "initialized-thread",
+      externalId: "initialized-thread",
+    });
+    await initialize;
+    await switchToNewThread;
+
+    expect(core.mainThreadId).toBe(core.getItemById(core.newThreadId!)?.id);
+  });
+
+  it("does not let a pending new thread request override a later switch", async () => {
+    const initializeThread = deferred<{
+      remoteId: string;
+      externalId: string;
+    }>();
+    const adapter = makeAdapter({
+      initialize: vi.fn(() => initializeThread.promise),
+      list: vi.fn(async () => ({ threads: [thread("thread-c")] })),
+    });
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+
+    const initialNewThreadId = core.newThreadId;
+    if (!initialNewThreadId) throw new Error("Expected an initial new thread");
+
+    const initialize = core.initialize(initialNewThreadId);
+    const switchToNewThread = core.switchToNewThread();
+    await core.switchToThread("thread-c");
+
+    initializeThread.resolve({
+      remoteId: "initialized-thread",
+      externalId: "initialized-thread",
+    });
+    await initialize;
+    await switchToNewThread;
+
+    expect(core.mainThreadId).toBe(core.getItemById("thread-c")?.id);
+  });
+
+  it("keeps mutations waiting when a newer switch fails", async () => {
+    const fetchB = deferred<RemoteThreadMetadata>();
+    const newThreadRuntime = deferred<unknown>();
+    const adapter = makeAdapter({
+      fetch: vi.fn(() => fetchB.promise),
+      list: vi.fn(async () => ({ threads: [thread("thread-a")] })),
+    });
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+    await core.switchToThread("thread-a");
+
+    const threadAId = core.getItemById("thread-a")?.id;
+    const newThreadId = core.newThreadId;
+    if (!newThreadId) throw new Error("Expected an initial new thread");
+
+    setStartThreadRuntime(core, (id) =>
+      id === core.getItemById(newThreadId)?.id
+        ? newThreadRuntime.promise
+        : Promise.resolve({}),
+    );
+
+    const deleteA = core.delete("thread-a");
+    const switchToB = core.switchToThread("thread-b");
+    const switchToBResult = expect(switchToB).rejects.toThrow("fetch failed");
+
+    newThreadRuntime.resolve({});
+    fetchB.reject(new Error("fetch failed"));
+
+    await switchToBResult;
+    await deleteA;
+
+    expect(core.mainThreadId).not.toBe(threadAId);
+    expect(core.mainThreadId).toBe(core.getItemById(core.newThreadId!)?.id);
+  });
+
+  it("lets a newer successful switch move the mutation target away", async () => {
+    const fetchB = deferred<RemoteThreadMetadata>();
+    const newThreadRuntime = deferred<unknown>();
+    const adapter = makeAdapter({
+      fetch: vi.fn(() => fetchB.promise),
+      list: vi.fn(async () => ({ threads: [thread("thread-a")] })),
+    });
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+    await core.switchToThread("thread-a");
+
+    const newThreadId = core.newThreadId;
+    if (!newThreadId) throw new Error("Expected an initial new thread");
+
+    setStartThreadRuntime(core, (id) =>
+      id === core.getItemById(newThreadId)?.id
+        ? newThreadRuntime.promise
+        : Promise.resolve({}),
+    );
+
+    const deleteA = core.delete("thread-a");
+    const switchToB = core.switchToThread("thread-b");
+
+    newThreadRuntime.resolve({});
+    fetchB.resolve(thread("thread-b"));
+
+    await switchToB;
+    await deleteA;
+
+    expect(core.mainThreadId).toBe(core.getItemById("thread-b")?.id);
+  });
+
+  it("does not let a mutation cancel an existing pending switch", async () => {
+    const fetchB = deferred<RemoteThreadMetadata>();
+    const adapter = makeAdapter({
+      fetch: vi.fn(() => fetchB.promise),
+      list: vi.fn(async () => ({ threads: [thread("thread-a")] })),
+    });
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+    await core.switchToThread("thread-a");
+
+    const switchToB = core.switchToThread("thread-b");
+    const deleteA = core.delete("thread-a");
+
+    fetchB.resolve(thread("thread-b"));
+
+    await switchToB;
+    await deleteA;
+
+    expect(core.mainThreadId).toBe(core.getItemById("thread-b")?.id);
+  });
+});