@assistant-ui/core 0.3.16 → 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

@@ -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";
   };