@assistant-ui/core 0.2.22 → 0.3.0

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) : [];
@@ -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.
@@ -565,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;
@@ -643,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);
     }
   }
 
@@ -721,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/tool-invocations/ToolInvocationTracker.test.ts

@@ -3,7 +3,6 @@ import { describe, expect, it, vi } from "vitest";
 import {
   ToolInvocationTracker,
   type ToolExecutionStatus,
-  type ToolInvocationTrackerSnapshot,
 } from "./ToolInvocationTracker";
 import type {
   ThreadAssistantMessage,
@@ -34,7 +33,7 @@ async function waitFor(
 const createState = (
   messages: ThreadAssistantMessage[],
   isRunning: boolean = true,
-): ToolInvocationTrackerSnapshot => ({
+): ToolInvocationTracker.Snapshot => ({
   messages: messages as readonly ThreadMessage[],
   isRunning,
 });
@@ -152,13 +151,13 @@ 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.
+  it("does not auto-submit a parse-error result when divergent argsText closes without a backend result", async () => {
+    // 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.
@@ -236,7 +235,7 @@ describe("ToolInvocationTracker", () => {
     }
   });
 
-  it("does not auto-submit a parse-error result for a non-executable tool whose divergent argsText closes (#5130)", async () => {
+  it("does not auto-submit a parse-error result for a non-executable tool whose divergent argsText closes", 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

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

@@ -35,34 +35,6 @@ export type AddToolResultCommand = {
   readonly modelContent?: readonly ToolModelContentPart[];
 };
 
-export type ToolInvocationTrackerSnapshot = {
-  readonly messages: readonly ThreadMessage[];
-  /** Whether the producing runtime is currently streaming new output. */
-  readonly isRunning: boolean;
-  /**
-   * Whether the producing runtime is still loading historical state.
-   * When `true`, every snapshot is treated as historical (no `streamCall` /
-   * `execute` fires). When `false`, processing resumes as live.
-   */
-  readonly isLoading?: boolean;
-};
-
-export type ToolInvocationTrackerCallbacks = {
-  /**
-   * Invoked when a client-side `execute()` returns a result and the runtime
-   * needs to feed it back into the conversation.
-   */
-  onResult: (command: AddToolResultCommand) => void;
-  /**
-   * Invoked whenever the per-tool-call status map changes (executing /
-   * interrupt / cleared). The callback receives a fresh map; mutating the
-   * argument is not supported.
-   */
-  onStatusesChange: (
-    statuses: ReadonlyMap<string, ToolExecutionStatus>,
-  ) => void;
-};
-
 type ToolCallEntry = {
   toolName: string;
   argsText: string;
@@ -123,10 +95,12 @@ const isEquivalentCompleteArgsText = (previous: string, next: string) => {
  * the hot message-processing path, so a malformed snapshot must never crash
  * the host runtime. See ./EDGE_CASES.md for the known non-trivial state
  * transitions and what each does today.
+ *
+ * @deprecated Internal — for framework bindings; not a public API. May change without notice.
  */
 export class ToolInvocationTracker {
   private readonly _getTools: () => Record<string, Tool> | undefined;
-  private readonly _callbacks: ToolInvocationTrackerCallbacks;
+  private readonly _callbacks: ToolInvocationTracker.Callbacks;
 
   private readonly _entries = new Map<string, ToolCallEntry>();
   /**
@@ -157,7 +131,7 @@ export class ToolInvocationTracker {
   private _pendingRestore = true;
 
   /** Cached last snapshot, used to skip processing on identical re-renders. */
-  private _lastSnapshot: ToolInvocationTrackerSnapshot | null = null;
+  private _lastSnapshot: ToolInvocationTracker.Snapshot | null = null;
   private _isRunning = false;
 
   private _controller!: ReturnType<typeof createAssistantStreamController>[1];
@@ -175,7 +149,7 @@ export class ToolInvocationTracker {
 
   constructor(
     getTools: () => Record<string, Tool> | undefined,
-    callbacks: ToolInvocationTrackerCallbacks,
+    callbacks: ToolInvocationTracker.Callbacks,
   ) {
     this._getTools = getTools;
     this._callbacks = callbacks;
@@ -235,7 +209,7 @@ export class ToolInvocationTracker {
    * Feed the next observed snapshot into the tracker. Called from the host
    * runtime whenever its message list / running state changes.
    */
-  public setState(snapshot: ToolInvocationTrackerSnapshot): void {
+  public setState(snapshot: ToolInvocationTracker.Snapshot): void {
     try {
       // Recover from a dead pipeline before processing anything. We demote
       // all active entries to "restored" so the rebuilt pipeline does not
@@ -782,3 +756,35 @@ export class ToolInvocationTracker {
     }
   }
 }
+
+export namespace ToolInvocationTracker {
+  export type ExecutionStatus = ToolExecutionStatus;
+
+  export type Snapshot = {
+    readonly messages: readonly ThreadMessage[];
+    /** Whether the producing runtime is currently streaming new output. */
+    readonly isRunning: boolean;
+    /**
+     * Whether the producing runtime is still loading historical state.
+     * When `true`, every snapshot is treated as historical (no `streamCall` /
+     * `execute` fires). When `false`, processing resumes as live.
+     */
+    readonly isLoading?: boolean;
+  };
+
+  export type Callbacks = {
+    /**
+     * Invoked when a client-side `execute()` returns a result and the runtime
+     * needs to feed it back into the conversation.
+     */
+    onResult: (command: AddToolResultCommand) => void;
+    /**
+     * Invoked whenever the per-tool-call status map changes (executing /
+     * interrupt / cleared). The callback receives a fresh map; mutating the
+     * argument is not supported.
+     */
+    onStatusesChange: (
+      statuses: ReadonlyMap<string, ToolExecutionStatus>,
+    ) => void;
+  };
+}

package/src/store/clients/model-context-client.test.ts

@@ -149,7 +149,7 @@ describe("mergeModelContexts", () => {
     });
   });
 
-  it("still rejects duplicate tools at the same priority", () => {
+  it("rejects duplicate tools at the same priority", () => {
     expect(() =>
       mergeModelContexts(
         new Set([
@@ -160,6 +160,26 @@ describe("mergeModelContexts", () => {
     ).toThrow(/already exists/);
   });
 
+  it("silently replaces a same-priority tool when the later registration sets overwrite", () => {
+    const merged = mergeModelContexts(
+      new Set([
+        provider({ tools: { duplicate: toolFixture() } }),
+        provider({
+          tools: {
+            duplicate: {
+              ...toolFixture(),
+              description: "latest",
+              overwrite: true,
+            } as Tool<any, any>,
+          },
+        }),
+      ]),
+    );
+
+    expect(merged.tools?.duplicate?.description).toBe("latest");
+    expect(merged.tools?.duplicate?.overwrite).toBeUndefined();
+  });
+
   it("preserves the highest priority when a lower-priority provider reuses the same tool object", () => {
     const shared = {
       ...toolFixture(),

package/src/store/clients/runtime-adapter.ts

@@ -13,17 +13,17 @@ export const baseRuntimeAdapterTransformScopes = (
   scopes.thread ??= Derived({
     source: "threads",
     query: { type: "main" },
-    get: (aui) => aui.threads().thread("main"),
+    get: (aui) => aui.threads.thread("main"),
   });
   scopes.threadListItem ??= Derived({
     source: "threads",
     query: { type: "main" },
-    get: (aui) => aui.threads().item("main"),
+    get: (aui) => aui.threads.item("main"),
   });
   scopes.composer ??= Derived({
     source: "thread",
     query: {},
-    get: (aui) => aui.threads().thread("main").composer(),
+    get: (aui) => aui.threads.thread("main").composer(),
   });
 
   if (!scopes.modelContext && parent.modelContext.source === null) {

package/src/store/runtime-clients/thread-runtime-client.ts

@@ -1,7 +1,7 @@
 import type { Unsubscribe } from "../../types/unsubscribe";
 import type { ThreadRuntimeEventType } from "../../runtime/interfaces/thread-runtime-core";
 import type { ThreadRuntime } from "../../runtime/api/thread-runtime";
-import { useMemo, useEffect, RefObject } from "react";
+import { useMemo, useEffect, type RefObject } from "react";
 import { useResource, resource, withKey } from "@assistant-ui/tap";
 import { liveRef } from "./liveRef";
 import {
@@ -113,6 +113,7 @@ const useThreadClient = ({
     deleteMessage: runtime.deleteMessage,
     startRun: runtime.startRun,
     resumeRun: runtime.resumeRun,
+    importExternalState: runtime.importExternalState,
     cancelRun: runtime.cancelRun,
     getModelContext: runtime.getModelContext,
     export: runtime.export,

package/src/store/scopes/thread.ts

@@ -108,6 +108,7 @@ export type ThreadMethods = {
    * @param initialMessages - Optional array of initial messages to populate the thread
    */
   reset(initialMessages?: readonly ThreadMessageLike[]): void;
+  importExternalState?(state: unknown): void;
   message(selector: { id: string } | { index: number }): MessageMethods;
   /** @deprecated This API is still under active development and might change without notice. */
   stopSpeaking(): void;

package/src/subscribable/subscribable.ts

@@ -141,10 +141,11 @@ export class ShallowMemoizeSubject<TState extends object, TPath>
     return this.binding.path;
   }
 
-  constructor(
-    private binding: SubscribableWithState<TState | SKIP_UPDATE, TPath>,
-  ) {
+  private binding: SubscribableWithState<TState | SKIP_UPDATE, TPath>;
+
+  constructor(binding: SubscribableWithState<TState | SKIP_UPDATE, TPath>) {
     super();
+    this.binding = binding;
     const state = binding.getState();
     if (state === SKIP_UPDATE)
       throw new Error("Entry not available in the store");
@@ -184,10 +185,11 @@ export class LazyMemoizeSubject<TState extends object, TPath>
     return this.binding.path;
   }
 
-  constructor(
-    private binding: SubscribableWithState<TState | SKIP_UPDATE, TPath>,
-  ) {
+  private binding: SubscribableWithState<TState | SKIP_UPDATE, TPath>;
+
+  constructor(binding: SubscribableWithState<TState | SKIP_UPDATE, TPath>) {
     super();
+    this.binding = binding;
   }
 
   private _previousStateDirty = true;
@@ -228,8 +230,11 @@ export class NestedSubscriptionSubject<
     return this.binding.path;
   }
 
-  constructor(private binding: NestedSubscribable<TState, TPath>) {
+  private binding: NestedSubscribable<TState, TPath>;
+
+  constructor(binding: NestedSubscribable<TState, TPath>) {
     super();
+    this.binding = binding;
   }
 
   public getState() {
@@ -269,8 +274,11 @@ export class NestedSubscriptionSubject<
 export class EventSubscriptionSubject<
   TEvent extends string,
 > extends BaseSubject {
-  constructor(private config: EventSubscribable<TEvent>) {
+  private config: EventSubscribable<TEvent>;
+
+  constructor(config: EventSubscribable<TEvent>) {
     super();
+    this.config = config;
   }
 
   public getState() {

package/src/tests/MessageRepository.test.ts

@@ -110,6 +110,18 @@ describe("MessageRepository", () => {
       }).toThrow(/Parent message not found/);
     });
 
+    it("should throw when a message would be linked under an ancestor with the same id", () => {
+      const message = createTestMessage({ id: "message-id" });
+      repository.addOrUpdateMessage(null, message);
+
+      expect(() => {
+        repository.addOrUpdateMessage(
+          "message-id",
+          createTestMessage({ id: "message-id" }),
+        );
+      }).toThrow(/same id already exists in the parent tree/);
+    });
+
     it("should retrieve all messages in the current branch", () => {
       const parent = createTestMessage({ id: "parent-id" });
       const child = createTestMessage({ id: "child-id" });