@assistant-ui/core 0.3.15 → 0.3.17

package/src/tests/thread-switch-events.test.tsx

@@ -5,10 +5,14 @@ import { describe, expect, it, vi } from "vitest";
 import { AuiProvider, useAui, useAuiEvent } from "@assistant-ui/store";
 import { AssistantRuntimeProvider } from "../react/AssistantRuntimeProvider";
 import { useExternalStoreRuntime } from "../react/runtimes/useExternalStoreRuntime";
+import { useLocalRuntime } from "../react/runtimes/useLocalRuntime";
 import { useRemoteThreadListRuntime } from "../react/runtimes/useRemoteThreadListRuntime";
-import { makeAdapter } from "./remote-thread-list-test-helpers";
+import { deferred, makeAdapter } from "./remote-thread-list-test-helpers";
 import { RuntimeAdapter } from "../react/RuntimeAdapter";
-import { AssistantRuntimeImpl } from "../runtime/api/assistant-runtime";
+import {
+  AssistantRuntimeImpl,
+  type AssistantRuntime,
+} from "../runtime/api/assistant-runtime";
 import { ExternalStoreRuntimeCore } from "../runtimes/external-store/external-store-runtime-core";
 import type { ExternalStoreAdapter } from "../runtimes/external-store/external-store-adapter";
 
@@ -232,3 +236,394 @@ describe("thread switch events", () => {
     expect(payload.previousThreadId).toMatch(/^__LOCALID_/);
   });
 });
+
+const createExternalStoreRuntime = (
+  runningByThreadId: Map<string, boolean>,
+) => {
+  const threads = [
+    { id: "t1", title: "one" },
+    { id: "t2", title: "two" },
+  ];
+  let currentId = "t1";
+  const makeStoreAdapter = (): ExternalStoreAdapter<DemoMessage> => ({
+    messages: EMPTY_MESSAGES,
+    isRunning: runningByThreadId.get(currentId) ?? false,
+    convertMessage: (m) => ({
+      id: m.id,
+      role: m.role,
+      content: [{ type: "text", text: m.text }],
+    }),
+    onNew: async () => {},
+    adapters: {
+      threadList: {
+        threadId: currentId,
+        threads: threads.map((t) => ({
+          status: "regular" as const,
+          id: t.id,
+          title: t.title,
+        })),
+        onSwitchToThread: (threadId: string) => {
+          currentId = threadId;
+          sync();
+        },
+        onSwitchToNewThread: () => {},
+      },
+    },
+  });
+  const core = new ExternalStoreRuntimeCore(makeStoreAdapter());
+  const runtime = new AssistantRuntimeImpl(core);
+  const sync = () => core.setAdapter(makeStoreAdapter());
+  return { runtime, sync };
+};
+
+const listAdapter = () =>
+  makeAdapter({
+    list: vi.fn(async () => ({
+      threads: [
+        { status: "regular" as const, remoteId: "thread-a", title: "A" },
+        { status: "regular" as const, remoteId: "thread-b", title: "B" },
+      ],
+    })),
+  });
+
+const renderRemoteList = (
+  adapter: ReturnType<typeof makeAdapter>,
+  run: () => Promise<{ content: [] }>,
+) => {
+  const globalRunStart = vi.fn();
+  const globalRunEnd = vi.fn();
+  const globalInitialize = vi.fn();
+  const globalModelContextUpdate = vi.fn();
+  const selectedRunStart = vi.fn();
+  const selectedRunEnd = vi.fn();
+  const selectedInitialize = vi.fn();
+  const selectedModelContextUpdate = vi.fn();
+  let runtime!: AssistantRuntime;
+
+  const Listener = () => {
+    useAuiEvent({ scope: "*", event: "thread.runStart" }, globalRunStart);
+    useAuiEvent({ scope: "*", event: "thread.runEnd" }, globalRunEnd);
+    useAuiEvent({ scope: "*", event: "thread.initialize" }, globalInitialize);
+    useAuiEvent(
+      { scope: "*", event: "thread.modelContextUpdate" },
+      globalModelContextUpdate,
+    );
+    useAuiEvent("thread.runStart", selectedRunStart);
+    useAuiEvent("thread.runEnd", selectedRunEnd);
+    useAuiEvent("thread.initialize", selectedInitialize);
+    useAuiEvent("thread.modelContextUpdate", selectedModelContextUpdate);
+    return null;
+  };
+  const Harness = () => {
+    runtime = useRemoteThreadListRuntime({
+      adapter,
+      initialThreadId: "thread-a",
+      runtimeHook: function RuntimeHook() {
+        return useLocalRuntime({ run });
+      },
+    });
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        <Listener />
+      </AssistantRuntimeProvider>
+    );
+  };
+  render(<Harness />);
+
+  return {
+    getRuntime: () => runtime,
+    globalRunStart,
+    globalRunEnd,
+    globalInitialize,
+    globalModelContextUpdate,
+    selectedRunStart,
+    selectedRunEnd,
+    selectedInitialize,
+    selectedModelContextUpdate,
+  };
+};
+
+const switchTo = async (runtime: AssistantRuntime, remoteId: string) => {
+  await act(async () => {
+    await runtime.threads.switchToThread(remoteId);
+  });
+  await waitFor(() => {
+    expect(runtime.threads.mainItem.getState().remoteId).toBe(remoteId);
+  });
+};
+
+describe("background thread run events", () => {
+  it("delivers runEnd globally after the running thread is switched away", async () => {
+    const runA = deferred<{ content: [] }>();
+    const harness = renderRemoteList(listAdapter(), () => runA.promise);
+    const runtime = harness.getRuntime();
+
+    await waitFor(() => {
+      expect(runtime.threads.mainItem.getState().remoteId).toBe("thread-a");
+    });
+    const threadAId = runtime.threads.mainItem.getState().id;
+
+    await act(async () => {
+      runtime.thread.startRun({ parentId: null });
+    });
+    await waitFor(() => expect(runtime.thread.getState().isRunning).toBe(true));
+    await waitFor(() => {
+      expect(harness.globalRunStart).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadAId,
+      });
+      expect(harness.selectedRunStart).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadAId,
+      });
+    });
+
+    await switchTo(runtime, "thread-b");
+    await act(async () => {
+      runA.resolve({ content: [] });
+    });
+
+    await waitFor(() => {
+      expect(harness.globalRunEnd).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadAId,
+      });
+    });
+    expect(harness.selectedRunEnd).not.toHaveBeenCalled();
+  });
+
+  it("does not duplicate run events while the running thread is switched back and forth", async () => {
+    const runA = deferred<{ content: [] }>();
+    const harness = renderRemoteList(listAdapter(), () => runA.promise);
+    const runtime = harness.getRuntime();
+
+    await waitFor(() => {
+      expect(runtime.threads.mainItem.getState().remoteId).toBe("thread-a");
+    });
+    const threadAId = runtime.threads.mainItem.getState().id;
+
+    await act(async () => {
+      runtime.thread.startRun({ parentId: null });
+    });
+    await waitFor(() => expect(runtime.thread.getState().isRunning).toBe(true));
+
+    await switchTo(runtime, "thread-b");
+    await switchTo(runtime, "thread-a");
+    await switchTo(runtime, "thread-b");
+    await switchTo(runtime, "thread-a");
+    await switchTo(runtime, "thread-b");
+
+    await act(async () => {
+      runA.resolve({ content: [] });
+    });
+
+    await waitFor(() => {
+      expect(harness.globalRunEnd).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadAId,
+      });
+    });
+    expect(harness.globalRunStart).toHaveBeenCalledExactlyOnceWith({
+      threadId: threadAId,
+    });
+    expect(harness.selectedRunStart).toHaveBeenCalledExactlyOnceWith({
+      threadId: threadAId,
+    });
+    expect(harness.selectedRunEnd).not.toHaveBeenCalled();
+  });
+
+  it("leaves the run to the selected client when its thread is re-selected", async () => {
+    const runA = deferred<{ content: [] }>();
+    const harness = renderRemoteList(listAdapter(), () => runA.promise);
+    const runtime = harness.getRuntime();
+
+    await waitFor(() => {
+      expect(runtime.threads.mainItem.getState().remoteId).toBe("thread-a");
+    });
+    const threadAId = runtime.threads.mainItem.getState().id;
+
+    await act(async () => {
+      runtime.thread.startRun({ parentId: null });
+    });
+    await waitFor(() => expect(runtime.thread.getState().isRunning).toBe(true));
+
+    await switchTo(runtime, "thread-b");
+    await switchTo(runtime, "thread-a");
+
+    await act(async () => {
+      runA.resolve({ content: [] });
+    });
+
+    await waitFor(() => {
+      expect(harness.selectedRunEnd).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadAId,
+      });
+    });
+    expect(harness.globalRunEnd).toHaveBeenCalledExactlyOnceWith({
+      threadId: threadAId,
+    });
+    expect(harness.globalRunStart).toHaveBeenCalledExactlyOnceWith({
+      threadId: threadAId,
+    });
+    expect(harness.selectedRunStart).toHaveBeenCalledExactlyOnceWith({
+      threadId: threadAId,
+    });
+  });
+
+  it("reports the start and end of a run that is never selected", async () => {
+    const backgroundRun = deferred<{ content: [] }>();
+    const harness = renderRemoteList(
+      listAdapter(),
+      () => backgroundRun.promise,
+    );
+    const runtime = harness.getRuntime();
+
+    await waitFor(() => {
+      expect(runtime.threads.mainItem.getState().remoteId).toBe("thread-a");
+    });
+    await switchTo(runtime, "thread-b");
+    const threadBId = runtime.threads.mainItem.getState().id;
+    const threadB = runtime.threads.getById(threadBId);
+    await switchTo(runtime, "thread-a");
+
+    await act(async () => {
+      threadB.startRun({ parentId: null });
+    });
+    await waitFor(() => {
+      expect(harness.globalRunStart).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadBId,
+      });
+    });
+
+    await act(async () => {
+      backgroundRun.resolve({ content: [] });
+    });
+    await waitFor(() => {
+      expect(harness.globalRunEnd).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadBId,
+      });
+    });
+    expect(harness.selectedRunStart).not.toHaveBeenCalled();
+    expect(harness.selectedRunEnd).not.toHaveBeenCalled();
+  });
+
+  it("reports lifecycle events from a thread that is never selected", async () => {
+    const backgroundRun = deferred<{ content: [] }>();
+    const harness = renderRemoteList(
+      listAdapter(),
+      () => backgroundRun.promise,
+    );
+    const runtime = harness.getRuntime();
+
+    await waitFor(() => {
+      expect(runtime.threads.mainItem.getState().remoteId).toBe("thread-a");
+    });
+    await switchTo(runtime, "thread-b");
+    const threadBId = runtime.threads.mainItem.getState().id;
+    const threadB = runtime.threads.getById(threadBId);
+    await switchTo(runtime, "thread-a");
+
+    let updateModelContext!: () => void;
+    const unregisterModelContext = runtime.registerModelContextProvider({
+      getModelContext: () => ({}),
+      subscribe: (callback) => {
+        updateModelContext = callback;
+        return () => {};
+      },
+    });
+    vi.clearAllMocks();
+
+    await act(async () => {
+      threadB.startRun({ parentId: null });
+    });
+    await waitFor(() => {
+      expect(harness.globalInitialize).toHaveBeenCalledExactlyOnceWith({
+        threadId: threadBId,
+      });
+    });
+
+    await act(async () => {
+      updateModelContext();
+    });
+    await waitFor(() => {
+      expect(harness.globalModelContextUpdate).toHaveBeenCalledWith({
+        threadId: threadBId,
+      });
+    });
+
+    expect(harness.selectedInitialize).not.toHaveBeenCalled();
+    unregisterModelContext();
+
+    await act(async () => {
+      backgroundRun.resolve({ content: [] });
+    });
+  });
+
+  it.each([
+    { operation: "delete", state: "deleted" },
+    { operation: "detach", state: "detached" },
+  ] as const)(
+    "stops reporting a background run once its thread is $state",
+    async ({ operation }) => {
+      const runA = deferred<{ content: [] }>();
+      const runSettled = vi.fn();
+      const harness = renderRemoteList(listAdapter(), async () => {
+        const result = await runA.promise;
+        runSettled();
+        return result;
+      });
+      const runtime = harness.getRuntime();
+
+      await waitFor(() => {
+        expect(runtime.threads.mainItem.getState().remoteId).toBe("thread-a");
+      });
+      const threadAId = runtime.threads.mainItem.getState().id;
+
+      await act(async () => {
+        runtime.thread.startRun({ parentId: null });
+      });
+      await waitFor(() =>
+        expect(runtime.thread.getState().isRunning).toBe(true),
+      );
+      await switchTo(runtime, "thread-b");
+
+      await act(async () => {
+        const item = runtime.threads.getItemById(threadAId);
+        if (operation === "delete") await item.delete();
+        else item.detach();
+      });
+      await act(async () => {
+        runA.resolve({ content: [] });
+      });
+
+      await waitFor(() => expect(runSettled).toHaveBeenCalledExactlyOnceWith());
+      expect(harness.globalRunEnd).not.toHaveBeenCalled();
+    },
+  );
+
+  it("emits nothing for a thread list that keeps only the main runtime", async () => {
+    const runningByThreadId = new Map<string, boolean>();
+    const { runtime, sync } = createExternalStoreRuntime(runningByThreadId);
+    const globalRunEnd = vi.fn();
+    const Listener = () => {
+      useAuiEvent({ scope: "*", event: "thread.runEnd" }, globalRunEnd);
+      return null;
+    };
+    const Harness = () => {
+      const aui = useAui({ threads: RuntimeAdapter(runtime) } as never);
+      return (
+        <AuiProvider value={aui}>
+          <Listener />
+        </AuiProvider>
+      );
+    };
+    render(<Harness />);
+    await act(async () => {});
+
+    runningByThreadId.set("t1", true);
+    await act(async () => sync());
+    await waitFor(() => expect(runtime.thread.getState().isRunning).toBe(true));
+
+    await act(async () => {
+      await runtime.threads.switchToThread("t2");
+    });
+    expect(runtime.threads.getState().mainThreadId).toBe("t2");
+    expect(globalRunEnd).not.toHaveBeenCalled();
+  });
+});

package/src/types/message.ts

@@ -168,9 +168,9 @@ export type ToolApprovalOption = {
   readonly id: string;
   /**
    * Decision class. Drives approved-resolution and default rendering.
-   * Open union: `_`-prefixed custom kinds are never auto-resolved and the
-   * default kit skips them; they must be answered with an explicit
-   * `approved` value (optionally alongside the `optionId`).
+   * Open union: `_`-prefixed custom kinds are never auto-resolved; they must
+   * be answered with an explicit `approved` value (optionally alongside the
+   * `optionId`), which is what the default kit sends when one is chosen.
    */
   readonly kind: ToolApprovalOptionKind | (string & {});
   /** Human label. Renderers supply defaults per kind when omitted. */
@@ -182,12 +182,48 @@ export type ToolApprovalOption = {
   readonly confirm?: boolean | { title?: string; description?: string };
 };
 
+/**
+ * How an approval request should be presented, and which answers it accepts.
+ * Absent: `"decision"`.
+ *
+ * The approval seam carries a host-owned request addressed by its own id and
+ * resolved once; a request wanting an answer these modes cannot express stays
+ * on the `interrupt` seam, which hands the tool an arbitrary payload instead.
+ * Unlike {@link ToolApprovalOptionKind} the set is closed, because a renderer
+ * that cannot cover every mode exhaustively is back to guessing the affordance.
+ */
+export type ToolApprovalDisplay = "decision" | "select" | "text";
+
+/**
+ * Whether the request asks for a free-form answer, on its own or alongside its
+ * options. Renderers read this to decide whether to offer a text affordance,
+ * and the runtime reads it to reject a `text` response the host cannot record.
+ */
+export const toolApprovalAcceptsText = (approval: {
+  readonly display?: ToolApprovalDisplay;
+  readonly allowFreeform?: boolean;
+}): boolean => approval.display === "text" || approval.allowFreeform === true;
+
 export type ToolApprovalResponse =
-  | { readonly approved: boolean; readonly reason?: string }
-  | { readonly optionId: string; readonly reason?: string }
+  | {
+      readonly approved: boolean;
+      readonly text?: string;
+      readonly reason?: string;
+    }
+  | {
+      readonly optionId: string;
+      readonly text?: string;
+      readonly reason?: string;
+    }
   | {
       readonly approved: boolean;
       readonly optionId: string;
+      readonly text?: string;
+      readonly reason?: string;
+    }
+  | {
+      /** Answer to a request that asks a question rather than for a decision. */
+      readonly text: string;
       readonly reason?: string;
     };
 
@@ -228,6 +264,16 @@ export type ToolCallMessagePart<
   /** Server-side approval gate. `respondToApproval` may only be called while `approved` is undefined and no `resolution` is recorded. */
   readonly approval?: {
     readonly id: string;
+    /**
+     * The question put to the user. A request that asks for something other
+     * than permission carries it here, so a renderer can show the question
+     * rather than inferring a decision from the tool name.
+     */
+    readonly prompt?: string;
+    /** How the request should be presented. Absent: a plain decision. */
+    readonly display?: ToolApprovalDisplay;
+    /** Whether a free-form answer is accepted alongside the options. */
+    readonly allowFreeform?: boolean;
     readonly approved?: boolean;
     readonly reason?: string;
     readonly isAutomatic?: boolean;
@@ -235,6 +281,8 @@ export type ToolCallMessagePart<
     readonly options?: readonly ToolApprovalOption[];
     /** The option chosen at resolution, when options were present. */
     readonly optionId?: string;
+    /** The free-form answer recorded at resolution, when one was given. */
+    readonly text?: string;
     /** Terminal non-decision state: the request was cancelled or expired without a user decision. Set by the host. */
     readonly resolution?: "cancelled" | "expired";
   };
@@ -306,6 +354,11 @@ export type ToolCallMessagePartStatus =
       /** Reason the tool call requires action. */
       readonly reason: "tool-calls" | "interrupt";
     }
+  | {
+      readonly type: "incomplete";
+      readonly reason: "tool-calls";
+      readonly error?: ReadonlyJSONValue;
+    }
   | MessagePartStatus;
 
 export type MessageStatus =

package/src/utils/data-url.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { httpUrlPattern, parseDataUrl } from "./data-url";
+import {
+  httpUrlPattern,
+  parseDataUrl,
+  resolveFilePartSource,
+} from "./data-url";
 
 describe("parseDataUrl", () => {
   it("parses a base64 data URL", () => {
@@ -72,3 +76,50 @@ describe("httpUrlPattern", () => {
     },
   );
 });
+
+describe("resolveFilePartSource", () => {
+  it("uses an explicit url source type for opaque values", () => {
+    expect(
+      resolveFilePartSource({
+        data: "provider-file-id",
+        mimeType: "application/pdf",
+        sourceType: "url",
+      }),
+    ).toEqual({ kind: "url", url: "provider-file-id" });
+  });
+
+  it("uses http URLs as url sources", () => {
+    expect(
+      resolveFilePartSource({
+        data: "https://example.com/file.pdf",
+        mimeType: "application/pdf",
+      }),
+    ).toEqual({ kind: "url", url: "https://example.com/file.pdf" });
+  });
+
+  it("decodes data URLs and uses their media type", () => {
+    expect(
+      resolveFilePartSource({
+        data: "data:image/png;base64,aGVsbG8=",
+        mimeType: "application/octet-stream",
+      }),
+    ).toEqual({
+      kind: "data",
+      data: "aGVsbG8=",
+      mimeType: "image/png",
+    });
+  });
+
+  it("passes through opaque data with its declared media type", () => {
+    expect(
+      resolveFilePartSource({
+        data: "provider-file-id",
+        mimeType: "application/pdf",
+      }),
+    ).toEqual({
+      kind: "data",
+      data: "provider-file-id",
+      mimeType: "application/pdf",
+    });
+  });
+});

package/src/utils/data-url.ts

@@ -1,5 +1,9 @@
 export const httpUrlPattern = /^https?:\/\//i;
 
+export type FilePartSource =
+  | { kind: "url"; url: string }
+  | { kind: "data"; data: string; mimeType: string };
+
 export function parseDataUrl(
   value: string,
 ): { mimeType: string; data: string } | null {
@@ -8,6 +12,23 @@ export function parseDataUrl(
   return { mimeType: match[1]!.toLowerCase(), data: match[2]! };
 }
 
+export const resolveFilePartSource = (part: {
+  data: string;
+  mimeType: string;
+  sourceType?: string | undefined;
+}): FilePartSource => {
+  if (part.sourceType === "url" || httpUrlPattern.test(part.data)) {
+    return { kind: "url", url: part.data };
+  }
+
+  const parsed = parseDataUrl(part.data);
+  return {
+    kind: "data",
+    data: parsed?.data ?? part.data,
+    mimeType: parsed?.mimeType ?? part.mimeType,
+  };
+};
+
 /**
  * Whether a payload is something `new URL()` accepts. Adapters that place a
  * `FileMessagePart` payload into a url-typed wire field use this to decide

package/src/utils/invoke-user-callback.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { invokeUserCallback } from "./invoke-user-callback";
+
+describe("invokeUserCallback", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("invokes a callback synchronously with its arguments", () => {
+    const callback = vi.fn((left: number, right: number) => left + right);
+
+    expect(invokeUserCallback("test", "onSuccess", callback, 2, 3)).toBe(
+      undefined,
+    );
+    expect(callback).toHaveBeenCalledOnce();
+    expect(callback).toHaveBeenCalledWith(2, 3);
+  });
+
+  it("reports and swallows a synchronous throw", () => {
+    const error = new Error("sync failure");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    expect(() =>
+      invokeUserCallback("test", "onError", () => {
+        throw error;
+      }),
+    ).not.toThrow();
+    expect(consoleError).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenCalledWith(
+      "[test] onError callback threw an error",
+      error,
+    );
+  });
+
+  it("reports an asynchronous rejection and resolves", async () => {
+    const error = new Error("async failure");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    await expect(
+      invokeUserCallback("test", "onError", async () => {
+        throw error;
+      }),
+    ).resolves.toBeUndefined();
+    expect(consoleError).toHaveBeenCalledOnce();
+    expect(consoleError).toHaveBeenCalledWith(
+      "[test] onError callback threw an error",
+      error,
+    );
+  });
+
+  it("resolves only after an asynchronous callback settles", async () => {
+    let settleCallback: (() => void) | undefined;
+    const callbackPromise = new Promise<void>((resolve) => {
+      settleCallback = resolve;
+    });
+    let settled = false;
+
+    const result = invokeUserCallback(
+      "test",
+      "onFinish",
+      () => callbackPromise,
+    );
+    void result?.then(() => {
+      settled = true;
+    });
+
+    await Promise.resolve();
+    expect(settled).toBe(false);
+
+    settleCallback?.();
+    await result;
+    expect(settled).toBe(true);
+  });
+
+  it("does nothing when the callback is undefined", () => {
+    expect(invokeUserCallback("test", "onMissing", undefined)).toBeUndefined();
+  });
+});