@assistant-ui/core 0.3.16 → 0.3.17

package/src/react/runtimes/useRemoteThreadListRuntime.concurrent.test.tsx

@@ -0,0 +1,216 @@
+// @vitest-environment jsdom
+
+import { act, render } from "@testing-library/react";
+import { startTransition, Suspense, type ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import type { AppendMessage } from "../../types/message";
+import { makeAdapter } from "../../tests/remote-thread-list-test-helpers";
+import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
+import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+import { useRemoteThreadListRuntime } from "./useRemoteThreadListRuntime";
+
+const EMPTY_MESSAGES: readonly never[] = [];
+
+const userMessage = (text: string): AppendMessage => ({
+  parentId: null,
+  sourceId: null,
+  runConfig: {},
+  role: "user",
+  content: [{ type: "text", text }],
+  attachments: [],
+  metadata: { custom: {} },
+  createdAt: new Date(),
+  startRun: true,
+});
+
+const getThreadCore = (runtime: AssistantRuntime) =>
+  (
+    runtime.thread as unknown as {
+      __internal_threadBinding: {
+        getState(): { append(message: AppendMessage): Promise<void> };
+      };
+    }
+  ).__internal_threadBinding.getState();
+
+const createHarness = ({ stableHook = false } = {}) => {
+  const adapter = makeAdapter();
+  const onNewA = vi.fn(async () => {});
+  const onNewB = vi.fn(async () => {});
+  const renderB = vi.fn();
+  const renderThreadRuntime = vi.fn();
+  const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+  const pending = new Promise<never>(() => {});
+  let suspend = false;
+
+  const Blocker = () => {
+    if (suspend) throw pending;
+    return null;
+  };
+  // Every shipped adapter passes a fresh function expression, so a hoisted
+  // variant is the only way to exercise an unchanged published hook.
+  const useHoistedThreadRuntime = () => {
+    renderThreadRuntime();
+    return useExternalStoreRuntime({
+      messages: EMPTY_MESSAGES,
+      onNew: onNewA,
+    });
+  };
+  const App = ({
+    onNew,
+    children,
+  }: {
+    onNew: typeof onNewA;
+    children?: ReactNode;
+  }) => {
+    if (onNew === onNewB) renderB();
+    const useThreadRuntime = stableHook
+      ? useHoistedThreadRuntime
+      : () => {
+          renderThreadRuntime();
+          return useExternalStoreRuntime({ messages: EMPTY_MESSAGES, onNew });
+        };
+    const runtime = useRemoteThreadListRuntime({
+      adapter,
+      runtimeHook: useThreadRuntime,
+    });
+    runtimeRef.current = runtime;
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        {children ?? <Blocker />}
+      </AssistantRuntimeProvider>
+    );
+  };
+
+  return {
+    App,
+    onNewA,
+    onNewB,
+    renderB,
+    renderThreadRuntime,
+    runtimeRef,
+    suspend: () => {
+      suspend = true;
+    },
+  };
+};
+
+describe("useRemoteThreadListRuntime concurrent options", () => {
+  it("keeps new threads on the committed runtime hook", async () => {
+    const { App, onNewA, onNewB, renderB, runtimeRef, suspend } =
+      createHarness();
+    const view = render(
+      <Suspense fallback={null}>
+        <App onNew={onNewA} />
+      </Suspense>,
+    );
+
+    await act(async () => {
+      await getThreadCore(runtimeRef.current!).append(userMessage("first"));
+    });
+
+    act(() => {
+      suspend();
+      startTransition(() =>
+        view.rerender(
+          <Suspense fallback={null}>
+            <App onNew={onNewB} />
+          </Suspense>,
+        ),
+      );
+    });
+    expect(renderB).toHaveBeenCalled();
+
+    await act(async () => {
+      await runtimeRef.current!.threads.switchToNewThread();
+      await getThreadCore(runtimeRef.current!).append(userMessage("second"));
+    });
+
+    expect(onNewA).toHaveBeenCalledTimes(2);
+    expect(onNewB).not.toHaveBeenCalled();
+  });
+
+  it("publishes runtime hook changes after a committed render", async () => {
+    const { App, onNewA, onNewB, runtimeRef } = createHarness();
+    const view = render(<App onNew={onNewA} />);
+
+    await act(async () => {
+      await getThreadCore(runtimeRef.current!).append(userMessage("first"));
+    });
+
+    view.rerender(<App onNew={onNewB} />);
+    await act(async () => {
+      await getThreadCore(runtimeRef.current!).append(userMessage("second"));
+    });
+
+    expect(onNewA).toHaveBeenCalledTimes(1);
+    expect(onNewB).toHaveBeenCalledTimes(1);
+  });
+
+  it("costs two passes per provider commit in the documented shape", async () => {
+    // Fresh children on every render, as the AssistantRuntimeProvider JSDoc
+    // example does, so its memo does not block: the host renders once against
+    // the previously committed hook, then the publish adds the corrective pass.
+    const { App, onNewA, renderThreadRuntime } = createHarness();
+    const view = render(<App onNew={onNewA} />);
+
+    await act(async () => {});
+    renderThreadRuntime.mockClear();
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewA} />);
+    });
+
+    expect(renderThreadRuntime).toHaveBeenCalledTimes(2);
+  });
+
+  it("costs one pass when the provider memo blocks the host render", async () => {
+    const { App, onNewA, renderThreadRuntime } = createHarness();
+    const children = <div />;
+    const view = render(<App onNew={onNewA}>{children}</App>);
+
+    await act(async () => {});
+    renderThreadRuntime.mockClear();
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewA}>{children}</App>);
+    });
+
+    expect(renderThreadRuntime).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-run thread runtimes when the published hook is unchanged", async () => {
+    const { App, onNewA, renderThreadRuntime } = createHarness({
+      stableHook: true,
+    });
+    const children = <div />;
+    const view = render(<App onNew={onNewA}>{children}</App>);
+
+    await act(async () => {});
+    renderThreadRuntime.mockClear();
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewA}>{children}</App>);
+    });
+
+    expect(renderThreadRuntime).not.toHaveBeenCalled();
+  });
+
+  it("gives a thread created after an options change the committed hook", async () => {
+    const { App, onNewA, onNewB, runtimeRef } = createHarness();
+    const view = render(<App onNew={onNewA} />);
+    await act(async () => {});
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewB} />);
+    });
+
+    await act(async () => {
+      await runtimeRef.current!.threads.switchToNewThread();
+      await getThreadCore(runtimeRef.current!).append(userMessage("first"));
+    });
+
+    expect(onNewB).toHaveBeenCalledTimes(1);
+    expect(onNewA).not.toHaveBeenCalled();
+  });
+});

package/src/react/runtimes/useRemoteThreadListRuntime.ts

@@ -12,6 +12,8 @@ import type { RemoteThreadListOptions } from "../../runtimes/remote-thread-list/
 import type { AssistantRuntimeCore } from "../../runtime/interfaces/assistant-runtime-core";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { RemoteThreadListThreadListRuntimeCore } from "./RemoteThreadListThreadListRuntimeCore";
+import { WritableSubscribable } from "../../subscribable/subscribable";
+import { useSubscribable } from "../../store/runtime-clients/useSubscribable";
 import { useAui } from "@assistant-ui/store";
 
 class RemoteThreadListRuntimeCore
@@ -48,14 +50,30 @@ const useRemoteThreadListRuntimeImpl = (
 export const useRemoteThreadListRuntime = (
   options: RemoteThreadListOptions,
 ): AssistantRuntime => {
-  const runtimeHookRef = useRef(options.runtimeHook);
-  runtimeHookRef.current = options.runtimeHook;
+  const [runtimeHookStore] = useState(
+    () => new WritableSubscribable(options.runtimeHook),
+  );
+  useEffect(() => {
+    runtimeHookStore.setState(options.runtimeHook);
+  }, [runtimeHookStore, options.runtimeHook]);
 
   const initialThreadIdRef = useRef(options.initialThreadId);
 
-  const stableRuntimeHook = useCallback(() => {
-    return runtimeHookRef.current();
-  }, []);
+  // Thread resources subscribe to the store rather than reading a ref, so a
+  // hook published at commit reaches exactly the resources that use it and an
+  // abandoned render publishes nothing. The store pins its server snapshot to
+  // the constructor value for hydration, which tap reads on any never-mounted
+  // fiber, so the live state serves as the server snapshot here.
+  const stableRuntimeHook = useCallback(
+    function useCommittedRuntimeHook() {
+      return useSubscribable({
+        subscribe: runtimeHookStore.subscribe,
+        getState: runtimeHookStore.getState,
+        getServerSnapshot: runtimeHookStore.getState,
+      })();
+    },
+    [runtimeHookStore],
+  );
 
   const onThreadIdChange = useEffectEvent((threadId: string | undefined) => {
     options.onThreadIdChange?.(threadId);
@@ -91,7 +109,7 @@ export const useRemoteThreadListRuntime = (
 
     // If allowNesting is true and already inside a thread list context,
     // just call the runtimeHook directly (no-op behavior)
-    return stableRuntimeHook();
+    return options.runtimeHook();
   }
 
   const runtime = useRemoteThreadListRuntimeImpl(stableOptions);

package/src/react/types/MessagePartComponentTypes.ts

@@ -83,10 +83,14 @@ export type ToolCallMessagePartProps<
     /**
      * Responds to a server-side tool approval gate. Only valid while
      * `approval` is set on the part, `approval.approved === undefined`, and
-     * no `approval.resolution` is recorded. Accepts a boolean decision or the
-     * id of one of `approval.options`; option kinds resolve to the boolean.
+     * no `approval.resolution` is recorded. Accepts a boolean decision, the
+     * id of one of `approval.options` (option kinds resolve to the boolean),
+     * or a free-form answer when the request accepts one.
+     *
+     * Resolves once the runtime has accepted the response, and rejects when
+     * it could not be recorded, so the controls can stay retryable.
      */
-    respondToApproval: (response: ToolApprovalResponse) => void;
+    respondToApproval: (response: ToolApprovalResponse) => Promise<void>;
   };
 
 /** Component used to render a tool-call message part. */

package/src/react/types/scopes/tools.ts

@@ -1,5 +1,6 @@
 import type { ToolCallMessagePartComponent } from "../MessagePartComponentTypes";
 import type { Unsubscribe } from "../../..";
+import type { ToolCallText } from "../../../model-context/tool-call-text";
 
 export type McpAppResourceOutput = {
   readonly render: ToolCallMessagePartComponent;
@@ -12,6 +13,7 @@ export type McpAppResourceOutput = {
  */
 type ToolRegistration = {
   readonly render: ToolCallMessagePartComponent;
+  readonly renderText?: ToolCallText<any, any, unknown> | undefined;
   /** Whether this UI renders standalone, outside the chain-of-thought trace. */
   readonly standalone: boolean;
 };

package/src/runtime/api/message-part-runtime.ts

@@ -28,7 +28,7 @@ type MessagePartSnapshotBinding = SubscribableWithState<
 export type MessagePartRuntime = {
   addToolResult(result: any | ToolResponse<any>): void;
   resumeToolCall(payload: unknown): void;
-  respondToToolApproval(response: ToolApprovalResponse): void;
+  respondToToolApproval(response: ToolApprovalResponse): Promise<void>;
 
   readonly path: MessagePartRuntimePath;
   getState(): MessagePartState;
@@ -113,7 +113,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
     });
   }
 
-  public respondToToolApproval(response: ToolApprovalResponse) {
+  public respondToToolApproval(response: ToolApprovalResponse): Promise<void> {
     const state = this.contentBinding.getState();
     if (!state) throw new Error("Message part is not available");
 
@@ -131,7 +131,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
 
     if (!this.threadApi) throw new Error("Thread API is not available");
 
-    this.threadApi
+    return this.threadApi
       .getState()
       .respondToToolApproval(
         resolveToolApprovalResponse(state.approval, response),

package/src/runtime/api/thread-list-runtime.ts

@@ -7,7 +7,10 @@ import {
   SKIP_UPDATE,
   ShallowMemoizeSubject,
 } from "../../subscribable/subscribable";
-import type { ThreadListRuntimeCore } from "../interfaces/thread-list-runtime-core";
+import type {
+  ThreadListRuntimeCore,
+  ThreadListRuntimeEvent,
+} from "../interfaces/thread-list-runtime-core";
 import {
   type ThreadListItemRuntime,
   ThreadListItemRuntimeImpl,
@@ -21,6 +24,7 @@ import {
 } from "./thread-runtime";
 
 const RESOLVED_PROMISE = Promise.resolve();
+const NOOP_UNSUBSCRIBE = () => {};
 
 export type ThreadListState = {
   readonly mainThreadId: string;
@@ -57,6 +61,16 @@ export type ThreadListRuntime = {
   ): Promise<void>;
   switchToNewThread(): Promise<void>;
 
+  /**
+   * Observes lifecycle events on every thread this list keeps alive, so an
+   * event that fires while its thread is not selected stays observable. Thread
+   * lists that mount only the main thread never emit; their main thread's
+   * runtime is observed directly.
+   */
+  unstable_subscribeThreadEvents(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe;
+
   getLoadThreadsPromise(): Promise<void>;
   reload(): Promise<void>;
   /**
@@ -171,6 +185,8 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
   protected __internal_bindMethods() {
     this.switchToThread = this.switchToThread.bind(this);
     this.switchToNewThread = this.switchToNewThread.bind(this);
+    this.unstable_subscribeThreadEvents =
+      this.unstable_subscribeThreadEvents.bind(this);
     this.getLoadThreadsPromise = this.getLoadThreadsPromise.bind(this);
     this.reload = this.reload.bind(this);
     this.reloadMainThread = this.reloadMainThread.bind(this);
@@ -194,6 +210,14 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     return this._core.switchToNewThread();
   }
 
+  public unstable_subscribeThreadEvents(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe {
+    return (
+      this._core.unstable_subscribeThreadEvents?.(callback) ?? NOOP_UNSUBSCRIBE
+    );
+  }
+
   public getLoadThreadsPromise(): Promise<void> {
     return this._core.getLoadThreadsPromise();
   }

package/src/runtime/base/base-thread-runtime-core.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { RealtimeVoiceAdapter } from "../../adapters/voice";
+import type { ModelContextProvider } from "../../model-context/types";
 import type { AppendMessage } from "../../types/message";
+import { CompositeContextProvider } from "../../utils/composite-context-provider";
 import type {
   AddToolResultOptions,
   ResumeRunConfig,
@@ -45,8 +47,11 @@ const createVoiceAdapter = () => {
 class TestRuntime extends BaseThreadRuntimeCore {
   private readonly voiceAdapter: ReturnType<typeof createVoiceAdapter>;
 
-  constructor(voiceAdapter: ReturnType<typeof createVoiceAdapter>) {
-    super({ getModelContext: () => ({}) });
+  constructor(
+    voiceAdapter: ReturnType<typeof createVoiceAdapter>,
+    contextProvider: ModelContextProvider = { getModelContext: () => ({}) },
+  ) {
+    super(contextProvider);
     this.voiceAdapter = voiceAdapter;
   }
 
@@ -99,7 +104,7 @@ class TestRuntime extends BaseThreadRuntimeCore {
   resumeRun(_config: ResumeRunConfig) {}
   addToolResult(_options: AddToolResultOptions) {}
   resumeToolCall(_options: ResumeToolCallOptions) {}
-  respondToToolApproval(_options: RespondToToolApprovalOptions) {}
+  async respondToToolApproval(_options: RespondToToolApprovalOptions) {}
   cancelRun() {}
   exportExternalState() {
     return {};
@@ -126,6 +131,92 @@ describe("BaseThreadRuntimeCore subscriptions", () => {
     expect(() => runtime.reset()).toThrow(error);
     expect(laterSubscriber).toHaveBeenCalledOnce();
   });
+
+  it("isolates initialize listener errors during late replay", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const runtime = new TestRuntime(createVoiceAdapter());
+    runtime.reset();
+
+    const syncError = new Error("sync listener failed");
+    const asyncError = new Error("async listener failed");
+    runtime.unstable_on("initialize", () => {
+      throw syncError;
+    });
+    runtime.unstable_on("initialize", async () => {
+      throw asyncError;
+    });
+
+    await vi.waitFor(() => {
+      expect(consoleError).toHaveBeenCalledTimes(2);
+      expect(consoleError).toHaveBeenCalledWith(
+        '[assistant-ui] Thread runtime "initialize" listener threw an error',
+        syncError,
+      );
+      expect(consoleError).toHaveBeenCalledWith(
+        '[assistant-ui] Thread runtime "initialize" listener threw an error',
+        asyncError,
+      );
+    });
+  });
+
+  it("isolates modelContextUpdate listener errors during context updates", () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const provider = new CompositeContextProvider();
+    const runtime = new TestRuntime(createVoiceAdapter(), provider);
+    const listenerError = new Error("model context listener failed");
+    const laterListener = vi.fn();
+
+    runtime.unstable_on("modelContextUpdate", () => {
+      throw listenerError;
+    });
+    runtime.unstable_on("modelContextUpdate", laterListener);
+
+    const unregister = provider.registerModelContextProvider({
+      getModelContext: () => ({}),
+    });
+
+    expect(laterListener).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenNthCalledWith(
+      1,
+      '[assistant-ui] Thread runtime "modelContextUpdate" listener threw an error',
+      listenerError,
+    );
+    expect(() => unregister()).not.toThrow();
+    expect(laterListener).toHaveBeenCalledTimes(2);
+    expect(consoleError).toHaveBeenNthCalledWith(
+      2,
+      '[assistant-ui] Thread runtime "modelContextUpdate" listener threw an error',
+      listenerError,
+    );
+  });
+
+  it("observes rejected modelContextUpdate listener promises", async () => {
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const provider = new CompositeContextProvider();
+    const runtime = new TestRuntime(createVoiceAdapter(), provider);
+    const listenerError = new Error("async model context listener failed");
+
+    runtime.unstable_on("modelContextUpdate", async () => {
+      throw listenerError;
+    });
+
+    expect(() =>
+      provider.registerModelContextProvider({ getModelContext: () => ({}) }),
+    ).not.toThrow();
+
+    await vi.waitFor(() => {
+      expect(consoleError).toHaveBeenCalledWith(
+        '[assistant-ui] Thread runtime "modelContextUpdate" listener threw an error',
+        listenerError,
+      );
+    });
+  });
 });
 
 describe("BaseThreadRuntimeCore voice volume subscriptions", () => {

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

@@ -51,7 +51,7 @@ export abstract class BaseThreadRuntimeCore
 {
   private _isInitialized = false;
 
-  protected readonly repository = new MessageRepository();
+  protected repository = new MessageRepository();
   public abstract get adapters(): BaseThreadAdapters | undefined;
   public abstract get isDisabled(): boolean;
   public abstract get isSendDisabled(): boolean;
@@ -68,7 +68,7 @@ export abstract class BaseThreadRuntimeCore
   public abstract resumeToolCall(options: ResumeToolCallOptions): void;
   public abstract respondToToolApproval(
     options: RespondToToolApprovalOptions,
-  ): void;
+  ): Promise<void>;
   public abstract cancelRun(): void;
   public abstract exportExternalState(): any;
   public abstract importExternalState(state: any): void;
@@ -518,7 +518,11 @@ export abstract class BaseThreadRuntimeCore
     const wrapped = callback as (payload?: unknown) => void;
     if (event === "modelContextUpdate") {
       // provider.subscribe is `() => void`; pump the typed empty payload to the user callback.
-      return this._contextProvider.subscribe?.(() => wrapped({})) ?? (() => {});
+      return (
+        this._contextProvider.subscribe?.(() =>
+          notifyEventListeners([wrapped], {}, `Thread runtime "${event}"`),
+        ) ?? (() => {})
+      );
     }
 
     let subscribers = this._eventSubscribers.get(event);
@@ -532,7 +536,9 @@ export abstract class BaseThreadRuntimeCore
     // after the thread already initialized, mirroring a BehaviorSubject.
     if (event === "initialize" && this._isInitialized) {
       queueMicrotask(() => {
-        if (subscribers.has(wrapped)) wrapped({});
+        if (subscribers.has(wrapped)) {
+          notifyEventListeners([wrapped], {}, `Thread runtime "${event}"`);
+        }
       });
     }
 

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

@@ -1,5 +1,8 @@
 import type { Unsubscribe } from "../../types/unsubscribe";
-import type { ThreadRuntimeCore } from "./thread-runtime-core";
+import type {
+  ThreadRuntimeCore,
+  ThreadRuntimeEventType,
+} from "./thread-runtime-core";
 
 export type ThreadListItemStatus = "archived" | "regular" | "new" | "deleted";
 
@@ -16,6 +19,11 @@ export type ThreadListItemCoreState = {
   readonly runtime?: ThreadRuntimeCore | undefined;
 };
 
+export type ThreadListRuntimeEvent = {
+  readonly threadId: string;
+  readonly type: ThreadRuntimeEventType;
+};
+
 export type ThreadListRuntimeCore = {
   readonly isLoading: boolean;
   readonly isLoadingMore?: boolean;
@@ -41,6 +49,17 @@ export type ThreadListRuntimeCore = {
    */
   unstable_isThreadRunning?(threadId: string): boolean;
 
+  /**
+   * Lifecycle events from every thread this list keeps alive, including
+   * threads that are not the main one. Implemented by thread lists that keep
+   * runtimes alive for non-main threads. A thread list that mounts only the
+   * main thread leaves this undefined: its other threads have no runtime and so
+   * emit nothing, and the main thread's runtime is observed directly.
+   */
+  unstable_subscribeThreadEvents?(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe;
+
   getItemById(threadId: string): ThreadListItemCoreState | undefined;
 
   switchToThread(

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

@@ -63,6 +63,8 @@ export type RespondToToolApprovalOptions = {
   approved: boolean;
   /** The approval option that produced this decision, when the request carried options. */
   optionId?: string;
+  /** The free-form answer, when the request asked for one. */
+  text?: string;
   reason?: string;
 };
 
@@ -165,7 +167,21 @@ export type ThreadRuntimeCore = Readonly<{
 
   addToolResult: (options: AddToolResultOptions) => void;
   resumeToolCall: (options: ResumeToolCallOptions) => void;
-  respondToToolApproval: (options: RespondToToolApprovalOptions) => void;
+  /**
+   * Records a decision on a tool approval gate. Resolves once the runtime has
+   * accepted the response and rejects when it could not be recorded, so a
+   * caller can leave the gate retryable rather than spending it. A capability
+   * or state precondition still throws synchronously; a failure to record
+   * arrives as a rejection, including one an adapter raises synchronously.
+   *
+   * Acceptance is as far as the runtime can see the response: one that records
+   * the decision locally settles on the record, while one that answers by
+   * resuming a run settles on the resume. A failure of the work the decision
+   * unblocks is reported through the runtime's own error channel, not here.
+   */
+  respondToToolApproval: (
+    options: RespondToToolApprovalOptions,
+  ) => Promise<void>;
 
   speak: (messageId: string) => void;
   stopSpeaking: () => void;

package/src/runtime/utils/auto-status.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { getAutoStatus } from "./auto-status";
+
+describe("getAutoStatus", () => {
+  it("reports a cancelled message as incomplete", () => {
+    expect(
+      getAutoStatus(true, false, false, false, undefined, true),
+    ).toMatchObject({ type: "incomplete", reason: "cancelled" });
+  });
+
+  it("keeps a cancelled message incomplete once a later message arrives", () => {
+    expect(
+      getAutoStatus(false, false, false, false, undefined, true),
+    ).toMatchObject({ type: "incomplete", reason: "cancelled" });
+  });
+
+  it("reports an uncancelled message as complete", () => {
+    expect(
+      getAutoStatus(true, false, false, false, undefined, false),
+    ).toMatchObject({ type: "complete", reason: "unknown" });
+  });
+
+  it.each([
+    ["running", { type: "running" }, true, false, false, undefined],
+    [
+      "an interrupted tool call",
+      { type: "requires-action", reason: "interrupt" },
+      false,
+      true,
+      true,
+      undefined,
+    ],
+    [
+      "a pending tool call",
+      { type: "requires-action", reason: "tool-calls" },
+      false,
+      false,
+      true,
+      undefined,
+    ],
+    [
+      "an error",
+      { type: "incomplete", reason: "error", error: "boom" },
+      false,
+      false,
+      false,
+      "boom",
+    ],
+  ])(
+    "keeps %s ahead of cancellation",
+    (_label, expected, isRunning, interrupted, pending, error) => {
+      expect(
+        getAutoStatus(true, isRunning, interrupted, pending, error, true),
+      ).toMatchObject(expected);
+    },
+  );
+});