@assistant-ui/core 0.2.21 → 0.2.23

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -68,6 +68,45 @@ export class LocalThreadRuntimeCore
   private _queue: MessageQueueController | null = null;
   private _queueRunInFlight = false;
 
+  private _historyWrites = new Map<string, Promise<void>>();
+
+  // Writes for one message id must land in issue order; an earlier paused
+  // snapshot arriving after the terminal write would resurrect the pause.
+  private _chainHistoryWrite(
+    id: string,
+    write: () => Promise<void>,
+  ): Promise<void> {
+    const next = (this._historyWrites.get(id) ?? Promise.resolve()).then(
+      write,
+      write,
+    );
+    const stored = next.then(
+      () => {},
+      () => {},
+    );
+    this._historyWrites.set(id, stored);
+    void stored.then(() => {
+      if (this._historyWrites.get(id) === stored) {
+        this._historyWrites.delete(id);
+      }
+    });
+    return next;
+  }
+
+  // A decision recorded on a still-paused message must reach history before
+  // the run resumes, or a refresh would restore the message without it.
+  private _persistPausedMessage(
+    parentId: string | null,
+    message: ThreadAssistantMessage,
+  ) {
+    if (message.status?.type !== "requires-action") return;
+    const history = this._options.adapters.history;
+    if (!history?.update) return;
+    const update = history.update.bind(history);
+    const item = { parentId, message, runConfig: this._lastRunConfig };
+    this._chainHistoryWrite(message.id, () => update(item)).catch(() => {});
+  }
+
   public readonly isDisabled = false;
   public readonly isSendDisabled = false;
 
@@ -351,6 +390,12 @@ export class LocalThreadRuntimeCore
   ): Promise<void> {
     this._notifyEventSubscribers("runStart", {});
 
+    // A run entered on a requires-action message resumes a pause an
+    // update-capable adapter already holds (written at pause time or loaded).
+    const alreadyPersisted =
+      message.status?.type === "requires-action" &&
+      this._options.adapters.history?.update !== undefined;
+
     try {
       // mark busy for runs not started through the queue (regenerate, resume)
       this._queue?.notifyBusy();
@@ -364,6 +409,7 @@ export class LocalThreadRuntimeCore
           parentId,
           message,
           runConfig,
+          alreadyPersisted,
           runCallback,
         );
         runCallback = undefined;
@@ -406,6 +452,7 @@ export class LocalThreadRuntimeCore
     parentId: string | null,
     message: ThreadAssistantMessage,
     runConfig: RunConfig | undefined,
+    alreadyPersisted: boolean,
     runCallback?: ChatModelAdapter["run"],
   ) {
     const messages = parentId ? this.repository.getMessages(parentId) : [];
@@ -442,7 +489,7 @@ export class LocalThreadRuntimeCore
           ? {
               metadata: {
                 ...message.metadata,
-                ...(m.metadata.unstable_state
+                ...(m.metadata.unstable_state !== undefined
                   ? { unstable_state: m.metadata.unstable_state }
                   : undefined),
                 ...(annotations
@@ -471,17 +518,18 @@ export class LocalThreadRuntimeCore
 
     const maxSteps = this._options.maxSteps ?? 2;
 
-    const steps = message.metadata?.steps?.length ?? 0;
-    if (steps >= maxSteps) {
-      // reached max tool steps
-      updateMessage({
-        status: {
-          type: "incomplete",
-          reason: "tool-calls",
-        },
-      });
-      return message;
-    } else {
+    try {
+      const steps = message.metadata?.steps?.length ?? 0;
+      if (steps >= maxSteps) {
+        updateMessage({
+          status: {
+            type: "incomplete",
+            reason: "tool-calls",
+          },
+        });
+        return message;
+      }
+
       updateMessage({
         status: {
           type: "running",
@@ -491,9 +539,7 @@ export class LocalThreadRuntimeCore
       // Switch to the new message branch right after adding it for the first time
       this.repository.resetHead(message.id);
       this._notifySubscribers();
-    }
 
-    try {
       this._lastRunConfig = runConfig ?? {};
       // unstable_composerMetadata is composer-only (stamped onto the outgoing
       // message); never expose it to the chat-model adapter's run context.
@@ -537,7 +583,9 @@ export class LocalThreadRuntimeCore
 
       if (message.status.type === "running") {
         updateMessage({
-          status: { type: "complete", reason: "unknown" },
+          status: abortSignal.aborted
+            ? { type: "incomplete", reason: "cancelled" }
+            : { type: "complete", reason: "unknown" },
         });
       }
     } catch (e) {
@@ -563,15 +611,29 @@ export class LocalThreadRuntimeCore
     } finally {
       this.abortController = null;
 
-      if (
+      const history = this._options.adapters.history;
+      const item = {
+        parentId,
+        message,
+        runConfig: this._lastRunConfig,
+      };
+      const isTerminal =
         message.status.type === "complete" ||
-        message.status.type === "incomplete"
-      ) {
-        await this._options.adapters.history?.append({
-          parentId,
-          message: message,
-          runConfig: this._lastRunConfig,
-        });
+        message.status.type === "incomplete";
+      const isPausing =
+        message.status.type === "requires-action" &&
+        !shouldContinue(message, this._options.unstable_humanToolNames);
+
+      // Pauses are written only for adapters that can rewrite the entry later;
+      // an append-only adapter would strand a half-finished run in history.
+      if (isTerminal || (isPausing && history?.update)) {
+        const write =
+          alreadyPersisted && history?.update
+            ? history.update.bind(history)
+            : history?.append.bind(history);
+        if (write) {
+          await this._chainHistoryWrite(message.id, () => write(item));
+        }
       }
     }
     return message;
@@ -641,6 +703,8 @@ export class LocalThreadRuntimeCore
       shouldContinue(message, this._options.unstable_humanToolNames)
     ) {
       this._runLoop(parentId, message, this._lastRunConfig).catch(() => {});
+    } else if (added) {
+      this._persistPausedMessage(parentId, message);
     }
   }
 
@@ -719,6 +783,8 @@ export class LocalThreadRuntimeCore
       shouldContinue(message, this._options.unstable_humanToolNames)
     ) {
       this._runLoop(parentId, message, this._lastRunConfig).catch(() => {});
+    } else {
+      this._persistPausedMessage(parentId, message);
     }
   }
 }

package/src/runtimes/local/should-continue.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import type { ThreadAssistantMessage } from "../../types/message";
+import { shouldContinue } from "./should-continue";
+
+const makeMessage = (
+  overrides: Partial<ThreadAssistantMessage>,
+): ThreadAssistantMessage => ({
+  id: "msg-1",
+  role: "assistant",
+  createdAt: new Date(),
+  content: [],
+  status: { type: "complete", reason: "stop" },
+  metadata: {
+    unstable_state: null,
+    unstable_annotations: [],
+    unstable_data: [],
+    steps: [],
+    custom: {},
+  },
+  ...overrides,
+});
+
+const toolCall = (toolName: string, result?: unknown) => ({
+  type: "tool-call" as const,
+  toolCallId: `call-${toolName}`,
+  toolName,
+  args: {},
+  argsText: "{}",
+  ...(result !== undefined ? { result } : {}),
+});
+
+describe("shouldContinue", () => {
+  it("returns false when status is not requires-action", () => {
+    const msg = makeMessage({
+      status: { type: "complete", reason: "stop" },
+    });
+    expect(shouldContinue(msg, undefined)).toBe(false);
+  });
+
+  it("returns false when reason is not tool-calls", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "interrupt" },
+    });
+    expect(shouldContinue(msg, undefined)).toBe(false);
+  });
+
+  it("returns true when all tool calls have results (no humanToolNames)", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [toolCall("search", "found it"), toolCall("calculate", 42)],
+    });
+    expect(shouldContinue(msg, undefined)).toBe(true);
+  });
+
+  it("returns false when some tool calls have no result (no humanToolNames)", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [toolCall("search", "found it"), toolCall("calculate")],
+    });
+    expect(shouldContinue(msg, undefined)).toBe(false);
+  });
+
+  it("returns true when unresolved tool call is not a human tool", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [toolCall("auto-tool")],
+    });
+    expect(shouldContinue(msg, ["human-approval"])).toBe(true);
+  });
+
+  it("returns false when unresolved tool call IS a human tool", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [toolCall("human-approval")],
+    });
+    expect(shouldContinue(msg, ["human-approval"])).toBe(false);
+  });
+
+  it("returns true for non-tool-call content parts", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [
+        { type: "text", text: "Hello" } as any,
+        toolCall("search", "done"),
+      ],
+    });
+    expect(shouldContinue(msg, undefined)).toBe(true);
+  });
+
+  it("returns false while a tool call has a pending approval", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [{ ...toolCall("deploy"), approval: { id: "a1" } }],
+    });
+    expect(shouldContinue(msg, undefined)).toBe(false);
+    expect(shouldContinue(msg, ["human-approval"])).toBe(false);
+  });
+
+  it("returns true when a decided approval has no result", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [
+        { ...toolCall("deploy"), approval: { id: "a1", approved: true } },
+      ],
+    });
+    expect(shouldContinue(msg, undefined)).toBe(true);
+    expect(shouldContinue(msg, ["human-approval"])).toBe(true);
+  });
+
+  it("exempts approval-gated tool calls from the human tool result requirement", () => {
+    const msg = makeMessage({
+      status: { type: "requires-action", reason: "tool-calls" },
+      content: [
+        {
+          ...toolCall("human-approval"),
+          approval: { id: "a1", approved: true },
+        },
+      ],
+    });
+    expect(shouldContinue(msg, ["human-approval"])).toBe(true);
+  });
+});

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

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { OptimisticState } from "./optimistic-state";
+
+const deferred = () => {
+  let resolve!: () => void;
+  const promise = new Promise<void>((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+
+  return { promise, resolve };
+};
+
+describe("OptimisticState", () => {
+  it("preserves invocation order when optimistic updates resolve in order", async () => {
+    const state = new OptimisticState({ title: "Untitled" });
+    const firstRequest = deferred();
+    const secondRequest = deferred();
+
+    const firstUpdate = state.optimisticUpdate({
+      execute: () => firstRequest.promise,
+      optimistic: (value) => ({ ...value, title: "Project Alpha" }),
+    });
+    const secondUpdate = state.optimisticUpdate({
+      execute: () => secondRequest.promise,
+      optimistic: (value) => ({ ...value, title: "Project Beta" }),
+    });
+
+    expect(state.value.title).toBe("Project Beta");
+
+    firstRequest.resolve();
+    await firstUpdate;
+    expect(state.value.title).toBe("Project Beta");
+
+    secondRequest.resolve();
+    await secondUpdate;
+
+    expect(state.value.title).toBe("Project Beta");
+  });
+
+  it("preserves invocation order when optimistic updates resolve out of order", async () => {
+    const state = new OptimisticState({ title: "Untitled" });
+    const firstRequest = deferred();
+    const secondRequest = deferred();
+
+    const firstUpdate = state.optimisticUpdate({
+      execute: () => firstRequest.promise,
+      optimistic: (value) => ({ ...value, title: "Project Alpha" }),
+    });
+    const secondUpdate = state.optimisticUpdate({
+      execute: () => secondRequest.promise,
+      optimistic: (value) => ({ ...value, title: "Project Beta" }),
+    });
+
+    secondRequest.resolve();
+    await secondUpdate;
+    expect(state.value.title).toBe("Project Beta");
+
+    firstRequest.resolve();
+    await firstUpdate;
+
+    expect(state.value.title).toBe("Project Beta");
+  });
+});

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

@@ -14,9 +14,15 @@ type Transform<TState, TResult> = {
 };
 
 type PendingTransform<TState, TResult> = Transform<TState, TResult> & {
+  order: number;
   task: Promise<TResult>;
 };
 
+type CompletedOptimistic<TState> = {
+  order: number;
+  optimistic: (state: TState) => TState;
+};
+
 const pipeTransforms = <TState, TExtra>(
   initialState: TState,
   extraParam: TExtra,
@@ -32,14 +38,16 @@ export class OptimisticState<TState> extends BaseSubscribable {
     [];
 
   /**
-   * `optimistic` callbacks from transforms that have already resolved.
-   * Re-applied after every `then` callback so that a wholesale state
-   * replacement (e.g. list()) cannot erase earlier completed effects
-   * (e.g. delete). Cleared when no pending transforms remain.
+   * Completed optimistic callbacks remain active while any transform is
+   * pending, so later state replacements cannot erase them. Invocation order
+   * determines which overlapping optimistic update wins.
    *
    * Correctness requirement: `optimistic` callbacks must be idempotent.
    */
-  private readonly _completedOptimistics: Array<(state: TState) => TState> = [];
+  private readonly _completedOptimistics: Array<CompletedOptimistic<TState>> =
+    [];
+
+  private _nextTransformOrder = 0;
 
   private _baseValue: TState;
   private _cachedValue: TState;
@@ -51,12 +59,25 @@ export class OptimisticState<TState> extends BaseSubscribable {
   }
 
   private _updateState(): void {
-    this._cachedValue = this._pendingTransforms.reduce((state, transform) => {
-      return pipeTransforms(state, transform.task, [
-        transform.loading,
-        transform.optimistic,
-      ]);
-    }, this._baseValue);
+    const activeTransforms = [
+      ...this._pendingTransforms.map((transform) => ({
+        order: transform.order,
+        apply: (state: TState) =>
+          pipeTransforms(state, transform.task, [
+            transform.loading,
+            transform.optimistic,
+          ]),
+      })),
+      ...this._completedOptimistics.map(({ order, optimistic }) => ({
+        order,
+        apply: optimistic,
+      })),
+    ].sort((a, b) => a.order - b.order);
+
+    this._cachedValue = activeTransforms.reduce(
+      (state, transform) => transform.apply(state),
+      this._baseValue,
+    );
 
     this._notifySubscribers();
   }
@@ -77,8 +98,13 @@ export class OptimisticState<TState> extends BaseSubscribable {
   public async optimisticUpdate<TResult>(
     transform: Transform<TState, TResult>,
   ): Promise<TResult> {
+    const order = this._nextTransformOrder++;
     const task = transform.execute();
-    const pendingTransform = { ...transform, task };
+    const pendingTransform = {
+      ...transform,
+      order,
+      task,
+    };
     try {
       this._pendingTransforms.push(pendingTransform);
       this._updateState();
@@ -89,14 +115,20 @@ export class OptimisticState<TState> extends BaseSubscribable {
         transform.then,
       ]);
 
-      // Re-apply previously completed optimistic callbacks so that a
-      // then() that does wholesale replacement cannot erase their effects.
-      for (const fn of this._completedOptimistics) {
-        this._baseValue = fn(this._baseValue);
+      // `then` can replace state with a stale snapshot, so replay every
+      // completed effect; otherwise replay only newer overlapping effects.
+      for (const completed of this._completedOptimistics) {
+        if (transform.then || completed.order > pendingTransform.order) {
+          this._baseValue = completed.optimistic(this._baseValue);
+        }
       }
 
       if (transform.optimistic) {
-        this._completedOptimistics.push(transform.optimistic);
+        this._completedOptimistics.push({
+          order: pendingTransform.order,
+          optimistic: transform.optimistic,
+        });
+        this._completedOptimistics.sort((a, b) => a.order - b.order);
       }
 
       return result;

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

@@ -5,7 +5,7 @@ import type { AssistantStream } from "assistant-stream";
 
 export type RemoteThreadInitializeResponse = {
   remoteId: string;
-  externalId: string | undefined;
+  externalId?: string | undefined;
 };
 
 export type RemoteThreadMetadata = {

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