@assistant-ui/core 0.3.20 → 0.3.21

package/src/adapters/voice.test.ts

@@ -44,6 +44,14 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
+const deferredControls = () => {
+  let resolve!: (controls: VoiceSessionControls) => void;
+  const promise = new Promise<VoiceSessionControls>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+};
+
 describe("createVoiceSession", () => {
   it("applies mute requested while setup is pending", async () => {
     const { controls, controlsPromise, resolveControls, session } =
@@ -182,6 +190,94 @@ describe("createVoiceSession", () => {
     expect(controls.disconnect).toHaveBeenCalledOnce();
   });
 
+  it.each([false, true])(
+    "tears down late controls once when cleanup throws: %s",
+    async (throws) => {
+      const abortController = new AbortController();
+      const pending = deferredControls();
+      const originalError = new Error("connection ended");
+      let helpers!: VoiceSessionHelpers;
+      const controls = {
+        disconnect: vi.fn(() => {
+          if (throws) throw new Error("cleanup failed");
+        }),
+        mute: vi.fn(),
+        unmute: vi.fn(),
+      };
+      const session = createVoiceSession(
+        { abortSignal: abortController.signal },
+        (value) => {
+          helpers = value;
+          return pending.promise;
+        },
+      );
+      helpers.end("error", originalError);
+      pending.resolve(controls);
+      await pending.promise;
+      expect(controls.disconnect).toHaveBeenCalledOnce();
+
+      if (!throws) abortController.abort();
+      expect(() => session.disconnect()).not.toThrow();
+      abortController.abort();
+
+      expect(controls.disconnect).toHaveBeenCalledOnce();
+      expect(session.status).toEqual({
+        type: "ended",
+        reason: "error",
+        error: originalError,
+      });
+      const transcript = vi.fn();
+      session.onTranscript(transcript);
+      helpers.emitTranscript({ role: "assistant", text: "late" });
+      expect(transcript).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(["abort", "disconnect"] as const)(
+    "releases controls that arrive after %s without skipping or repeating cleanup",
+    async (action) => {
+      const abortController = new AbortController();
+      const pending = deferredControls();
+      const controls = { disconnect: vi.fn(), mute: vi.fn(), unmute: vi.fn() };
+      const session = createVoiceSession(
+        { abortSignal: abortController.signal },
+        () => pending.promise,
+      );
+      if (action === "abort") abortController.abort();
+      else session.disconnect();
+      expect(controls.disconnect).not.toHaveBeenCalled();
+
+      pending.resolve(controls);
+      await pending.promise;
+      session.disconnect();
+      abortController.abort();
+
+      expect(controls.disconnect).toHaveBeenCalledOnce();
+      expect(session.status).toEqual({ type: "ended", reason: "cancelled" });
+    },
+  );
+
+  it("does not reenter late teardown when the adapter disconnects the session", async () => {
+    const pending = deferredControls();
+    let helpers!: VoiceSessionHelpers;
+    const session = createVoiceSession({}, (value) => {
+      helpers = value;
+      return pending.promise;
+    });
+    const disconnect = vi.fn(() => session.disconnect());
+    helpers.end("finished");
+
+    pending.resolve({ disconnect, mute: vi.fn(), unmute: vi.fn() });
+    await pending.promise;
+
+    expect(disconnect).toHaveBeenCalledOnce();
+    expect(session.status).toEqual({
+      type: "ended",
+      reason: "finished",
+      error: undefined,
+    });
+  });
+
   it("cleans up when the adapter disconnect throws", async () => {
     const disconnectError = new Error("disconnect failed");
     let helpers: VoiceSessionHelpers | undefined;
@@ -207,6 +303,79 @@ describe("createVoiceSession", () => {
     expect(transcriptListener).not.toHaveBeenCalled();
   });
 
+  it("exposes sendText once controls that take typed text resolve", async () => {
+    let helpers!: VoiceSessionHelpers;
+    const { promise, resolve } = deferredControls();
+    const session = createVoiceSession({}, (sessionHelpers) => {
+      helpers = sessionHelpers;
+      return promise;
+    });
+    const statusListener = vi.fn();
+    session.onStatusChange(statusListener);
+    helpers.setStatus({ type: "running" });
+    statusListener.mockClear();
+
+    expect(session.sendText).toBeUndefined();
+
+    const controls = {
+      disconnect: vi.fn(),
+      mute: vi.fn(),
+      unmute: vi.fn(),
+      sendText: vi.fn(function (this: unknown) {
+        expect(this).toBe(controls);
+      }),
+    };
+    resolve(controls);
+    await promise;
+
+    expect(statusListener).toHaveBeenCalledExactlyOnceWith({
+      type: "running",
+    });
+    session.sendText?.("hello");
+    expect(controls.sendText).toHaveBeenCalledExactlyOnceWith("hello");
+
+    session.disconnect();
+
+    expect(session.sendText).toBeUndefined();
+  });
+
+  it("leaves sendText undefined and stays quiet for controls without it", async () => {
+    let helpers!: VoiceSessionHelpers;
+    const { promise, resolve } = deferredControls();
+    const session = createVoiceSession({}, (sessionHelpers) => {
+      helpers = sessionHelpers;
+      return promise;
+    });
+    const statusListener = vi.fn();
+    session.onStatusChange(statusListener);
+    helpers.setStatus({ type: "running" });
+    statusListener.mockClear();
+
+    resolve({ disconnect: vi.fn(), mute: vi.fn(), unmute: vi.fn() });
+    await promise;
+
+    expect(session.sendText).toBeUndefined();
+    expect(statusListener).not.toHaveBeenCalled();
+  });
+
+  it("does not repeat a status that has not reached running when controls resolve", async () => {
+    const { promise, resolve } = deferredControls();
+    const session = createVoiceSession({}, () => promise);
+    const statusListener = vi.fn();
+    session.onStatusChange(statusListener);
+
+    resolve({
+      disconnect: vi.fn(),
+      mute: vi.fn(),
+      unmute: vi.fn(),
+      sendText: vi.fn(),
+    });
+    await promise;
+
+    expect(statusListener).not.toHaveBeenCalled();
+    expect(session.sendText).toBeDefined();
+  });
+
   it("continues notifying listeners when one throws", () => {
     const listenerError = new Error("listener failed");
     const consoleError = vi

package/src/adapters/voice.ts

@@ -27,6 +27,10 @@ export namespace RealtimeVoiceAdapter {
     disconnect: () => void;
     mute: () => void;
     unmute: () => void;
+    /**
+     * Delivers typed text into the connected session. The runtime records the typed turn in the thread itself, so the session must not echo it through `onTranscript`. A session without it takes audio only.
+     */
+    sendText?: ((text: string) => void | Promise<void>) | undefined;
 
     onStatusChange: (callback: (status: Status) => void) => Unsubscribe;
     onTranscript: (
@@ -47,6 +51,10 @@ export type VoiceSessionControls = {
   disconnect: () => void;
   mute: () => void;
   unmute: () => void;
+  /**
+   * Delivers typed text to the provider. The session exposes `sendText` once these controls resolve and repeats its running status when they land after it, so status listeners can re-read the session; the runtime records the typed turn itself.
+   */
+  sendText?: ((text: string) => void | Promise<void>) | undefined;
 };
 
 export type VoiceSessionHelpers = {
@@ -74,6 +82,7 @@ export function createVoiceSession(
   let disposed = false;
   let disconnected = false;
   let controls: VoiceSessionControls | null = null;
+  let controlsDisconnected = false;
   const abortSignal = options.abortSignal;
   let abortHandler: (() => void) | undefined;
 
@@ -92,6 +101,12 @@ export function createVoiceSession(
     volumeCbs.clear();
   };
 
+  const disconnectControls = () => {
+    if (!controls || controlsDisconnected) return;
+    controlsDisconnected = true;
+    controls.disconnect();
+  };
+
   const helpers: VoiceSessionHelpers = {
     setStatus: (status) => {
       if (disposed) return;
@@ -126,6 +141,10 @@ export function createVoiceSession(
     get isMuted() {
       return isMuted;
     },
+    get sendText() {
+      if (disposed || !controls?.sendText) return undefined;
+      return controls.sendText.bind(controls);
+    },
     disconnect: () => {
       if (disconnected) return;
       disconnected = true;
@@ -135,7 +154,7 @@ export function createVoiceSession(
         notifyEventListeners(statusCbs, currentStatus, "Voice session");
       }
       try {
-        controls?.disconnect();
+        disconnectControls();
       } finally {
         cleanup();
       }
@@ -180,10 +199,12 @@ export function createVoiceSession(
       if (disposed) return;
       controls = await setup(helpers);
       if (disposed) {
-        controls.disconnect();
-      } else if (isMuted) {
-        controls.mute();
+        disconnectControls();
+        return;
       }
+      if (isMuted) controls.mute();
+      if (controls.sendText && currentStatus.type === "running")
+        notifyEventListeners(statusCbs, currentStatus, "Voice session");
     } catch (error) {
       helpers.end("error", error);
     }

package/src/index.ts

@@ -1,6 +1,6 @@
 // @assistant-ui/core - Framework-agnostic core runtime (public API)
 
-/// <reference path="./store/scope-registration.ts" />
+/// <reference path="./store/scope-registration.ts" preserve="true" />
 
 import { checkDuplicateCore } from "./internal/duplicate-detection";
 
@@ -28,6 +28,9 @@ export type {
   ToolApprovalResponse,
   ToolCallMessagePart,
   ToolCallTiming,
+  Unstable_ToolInteraction,
+  Unstable_ToolInteractionInput,
+  Unstable_ToolInteractionLog,
   ToolCallMessagePartMcpMetadata,
   McpAppMetadata,
   ToolModelContentPart,
@@ -201,6 +204,7 @@ export type {
   ComposerRuntimeEventCallback,
   ComposerRuntimeEventPayload,
   ComposerRuntimeEventType,
+  ComposerSubmission,
   DictationState,
   EditComposerRuntimeCore,
   SendOptions,
@@ -221,6 +225,7 @@ export type {
   AddToolResultOptions,
   ResumeToolCallOptions,
   RespondToToolApprovalOptions,
+  Unstable_RecordToolInteractionOptions,
   SubmitFeedbackOptions,
   ThreadSuggestion,
   SpeechState,
@@ -250,6 +255,7 @@ export type {
   CreateResumeRunConfig,
   CreateAppendMessage,
   ThreadState,
+  ThreadRuntimeState,
   ThreadRuntime,
 } from "./runtime/api/thread-runtime";
 
@@ -266,10 +272,14 @@ export type {
   ThreadListItemRuntime,
 } from "./runtime/api/thread-list-item-runtime";
 
-export type { ThreadListItemState } from "./runtime/api/bindings";
+export type {
+  ThreadListItemState,
+  ThreadListItemRuntimeState,
+} from "./runtime/api/bindings";
 
 export type {
   MessageState,
+  MessageRuntimeState,
   MessageRuntime,
 } from "./runtime/api/message-runtime";
 export type {
@@ -281,6 +291,7 @@ export type {
   ThreadComposerState,
   EditComposerState,
   ComposerState,
+  ComposerRuntimeState,
   ComposerRuntime,
   ThreadComposerRuntime,
   EditComposerRuntime,
@@ -288,6 +299,7 @@ export type {
 
 export type {
   AttachmentState,
+  AttachmentRuntimeState,
   AttachmentRuntime,
 } from "./runtime/api/attachment-runtime";
 

package/src/internal.ts

@@ -35,6 +35,12 @@ export { getThreadMessageText } from "./utils/text";
 export { toMessagePartStatus } from "./utils/normalizePartStatus";
 export { notifyEventListeners } from "./utils/notify-event-listeners";
 export { resolveToolApprovalResponse } from "./runtime/utils/resolveToolApprovalResponse";
+export {
+  TOOL_INTERACTION_LIMITS,
+  appendToolInteraction,
+  createToolInteraction,
+  readToolInteractionLog,
+} from "./runtime/utils/tool-interactions";
 export { consumeSuggestionResult } from "./adapters/suggestion";
 
 // Composite context provider
@@ -55,6 +61,7 @@ export {
 // JSON type guards, reused by framework bindings so the depth-guarded
 // validation lives in one place.
 export { isJSONValue, isRecord } from "./utils/json/is-json";
+export { isJSONValueEqual } from "./utils/json/is-json-equal";
 
 // Data-URL decoder and http(s) matcher, reused by framework adapters so the
 // outbound part conversion lives in one place.

package/src/model-context/frame/host.test.ts

@@ -29,7 +29,7 @@ const createHost = (targetOrigin?: string) => {
   const host = new AssistantFrameHost(iframeWindow, targetOrigin);
 
   const dispatchMessage = (
-    message: FrameMessage,
+    message: unknown,
     origin = targetOrigin ?? DEFAULT_ORIGIN,
   ) =>
     handleMessage?.({
@@ -122,6 +122,56 @@ describe("AssistantFrameHost", () => {
     host.dispose();
   });
 
+  it.each([
+    null,
+    { type: "model-context-update" },
+    { type: "model-context-update", context: null },
+    {
+      type: "model-context-update",
+      context: { tools: { search: null } },
+    },
+    {
+      type: "model-context-update",
+      context: { tools: { search: {} } },
+    },
+  ])("ignores malformed frame messages", (message) => {
+    const { dispatchMessage, host } = createHost();
+    const context = host.getModelContext();
+
+    expect(() => dispatchMessage(message)).not.toThrow();
+
+    expect(host.getModelContext()).toBe(context);
+    host.dispose();
+  });
+
+  it("resolves tool results without a value", async () => {
+    const { dispatchMessage, execute, getToolCallId, host } = createHost();
+    const result = Promise.resolve(execute({}, executionContext));
+    const id = getToolCallId();
+
+    dispatchMessage({ type: "tool-result", id });
+
+    await expect(result).resolves.toBeUndefined();
+    host.dispose();
+  });
+
+  it("ignores tool results with an invalid error", async () => {
+    const { dispatchMessage, execute, getToolCallId, host } = createHost();
+    const result = Promise.resolve(execute({}, executionContext));
+    const settled = vi.fn();
+    void result.then(settled, settled);
+    const id = getToolCallId();
+
+    dispatchMessage({ type: "tool-result", id, error: 42 });
+    await Promise.resolve();
+
+    expect(settled).not.toHaveBeenCalled();
+
+    dispatchMessage({ type: "tool-result", id, result: "complete" });
+    await expect(result).resolves.toBe("complete");
+    host.dispose();
+  });
+
   it("allows an explicit wildcard origin", () => {
     const { dispatchMessage, host, postMessage } = createHost("*");
 

package/src/model-context/frame/host.ts

@@ -9,6 +9,7 @@ import {
   type SerializedModelContext,
   type SerializedTool,
 } from "./types";
+import { isFrameMessage } from "./validate";
 
 const getDefaultTargetOrigin = () => window.location.origin;
 
@@ -92,7 +93,8 @@ export class AssistantFrameHost implements ModelContextProvider {
     if (event.source !== this._iframeWindow) return;
     if (event.data?.channel !== FRAME_MESSAGE_CHANNEL) return;
 
-    const message = event.data.message as FrameMessage;
+    const message = event.data.message;
+    if (!isFrameMessage(message)) return;
 
     switch (message.type) {
       case "model-context-update": {

package/src/model-context/frame/provider.test.ts

@@ -84,6 +84,45 @@ describe("AssistantFrameProvider", () => {
     vi.spyOn(window, "removeEventListener").mockImplementation(() => {});
   });
 
+  it.each([
+    null,
+    {},
+    { type: "tool-call", id: null, toolName: "sensitiveTool", args: {} },
+    { type: "tool-call", id: "tool-call-1", toolName: null, args: {} },
+    { type: "tool-call", id: "tool-call-1", toolName: "sensitiveTool" },
+    { type: "tool-cancel", id: null },
+  ])("ignores malformed frame messages", async (message) => {
+    const execute = vi.fn(async () => "result");
+    AssistantFrameProvider.addModelContextProvider(
+      {
+        getModelContext: () => ({
+          tools: { sensitiveTool: createTool(execute) },
+        }),
+      },
+      "https://parent.example",
+    );
+
+    expect(() =>
+      messageHandler?.(
+        new MessageEvent("message", {
+          data: { channel: FRAME_MESSAGE_CHANNEL, message },
+          origin: "https://parent.example",
+          source: parentWindow,
+        }),
+      ),
+    ).not.toThrow();
+
+    await Promise.resolve();
+
+    expect(execute).not.toHaveBeenCalled();
+    expect(parentWindow.postMessage).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.objectContaining({ type: "tool-result" }),
+      }),
+      expect.anything(),
+    );
+  });
+
   afterEach(() => {
     AssistantFrameProvider.dispose();
     vi.restoreAllMocks();
@@ -329,6 +368,28 @@ describe("AssistantFrameProvider", () => {
     expect(signals[1]?.aborted).toBe(false);
   });
 
+  it("withdraws its context from the parent when disposed", () => {
+    AssistantFrameProvider.addModelContextProvider(
+      {
+        getModelContext: () => ({
+          tools: { sensitiveTool: createTool(vi.fn()) },
+        }),
+      },
+      "https://parent.example",
+    );
+    vi.mocked(parentWindow.postMessage).mockClear();
+
+    AssistantFrameProvider.dispose();
+
+    expect(parentWindow.postMessage).toHaveBeenCalledExactlyOnceWith(
+      {
+        channel: FRAME_MESSAGE_CHANNEL,
+        message: { type: "model-context-update", context: {} },
+      },
+      "https://parent.example",
+    );
+  });
+
   it("aborts in-flight tool calls when the provider is disposed", async () => {
     let toolSignal: AbortSignal | undefined;
     const execute = vi.fn(

package/src/model-context/frame/provider.ts

@@ -7,6 +7,7 @@ import {
   type SerializedModelContext,
   type SerializedTool,
 } from "./types";
+import { isFrameMessage } from "./validate";
 
 const serializeTool = (tool: Tool<any, any>): SerializedTool => ({
   ...(tool.description && { description: tool.description }),
@@ -100,7 +101,8 @@ export class AssistantFrameProvider {
     if (event.source !== window.parent) return;
     if (event.data?.channel !== FRAME_MESSAGE_CHANNEL) return;
 
-    const message = event.data.message as FrameMessage;
+    const message = event.data.message;
+    if (!isFrameMessage(message)) return;
 
     switch (message.type) {
       case "model-context-request":
@@ -269,6 +271,10 @@ export class AssistantFrameProvider {
 
   private broadcastUpdate() {
     if (this._disposed) return;
+    this.postModelContext();
+  }
+
+  private postModelContext() {
     if (window.parent && window.parent !== window) {
       const updateMessage: FrameMessage = {
         type: "model-context-update",
@@ -427,6 +433,7 @@ export class AssistantFrameProvider {
       });
       instance._providerUnsubscribes.clear();
       instance._providers.clear();
+      runCleanup(() => instance.postModelContext());
       instance._activeToolCalls.forEach(({ abortController, event }, id) => {
         runCleanup(() => {
           abortController.abort();

package/src/model-context/frame/validate.ts

@@ -0,0 +1,57 @@
+import type {
+  FrameMessage,
+  SerializedModelContext,
+  SerializedTool,
+} from "./types";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const hasOptionalPropertyType = (
+  value: Record<string, unknown>,
+  property: string,
+  type: "boolean" | "string",
+) => value[property] === undefined || typeof value[property] === type;
+
+const isSerializedTool = (value: unknown): value is SerializedTool =>
+  isRecord(value) &&
+  Object.hasOwn(value, "parameters") &&
+  hasOptionalPropertyType(value, "description", "string") &&
+  hasOptionalPropertyType(value, "disabled", "boolean") &&
+  hasOptionalPropertyType(value, "type", "string");
+
+const isSerializedModelContext = (
+  value: unknown,
+): value is SerializedModelContext => {
+  if (!isRecord(value)) return false;
+  if (!hasOptionalPropertyType(value, "system", "string")) return false;
+  if (value.tools === undefined) return true;
+  if (!isRecord(value.tools)) return false;
+  return Object.values(value.tools).every(isSerializedTool);
+};
+
+export const isFrameMessage = (value: unknown): value is FrameMessage => {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+
+  switch (value.type) {
+    case "model-context-request":
+      return true;
+    case "model-context-update":
+      return isSerializedModelContext(value.context);
+    case "tool-call":
+      return (
+        typeof value.id === "string" &&
+        typeof value.toolName === "string" &&
+        Object.hasOwn(value, "args")
+      );
+    case "tool-cancel":
+      return typeof value.id === "string";
+    case "tool-result":
+      return (
+        typeof value.id === "string" &&
+        (value.error == null || typeof value.error === "string")
+      );
+    default:
+      return false;
+  }
+};