@assistant-ui/core 0.2.20 → 0.2.22

package/src/adapters/voice.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createVoiceSession,
+  type VoiceSessionControls,
+  type VoiceSessionHelpers,
+} from "./voice";
+
+const createTestSession = () => {
+  let helpers: VoiceSessionHelpers | undefined;
+  const session = createVoiceSession({}, async (sessionHelpers) => {
+    helpers = sessionHelpers;
+    return {
+      disconnect: vi.fn(),
+      mute: vi.fn(),
+      unmute: vi.fn(),
+    };
+  });
+
+  if (!helpers) throw new Error("Voice session setup did not start");
+  return { helpers, session };
+};
+
+const createPendingTestSession = () => {
+  let resolveControls!: (controls: VoiceSessionControls) => void;
+  const controlsPromise = new Promise<VoiceSessionControls>((resolve) => {
+    resolveControls = resolve;
+  });
+  const controls = {
+    disconnect: vi.fn(),
+    mute: vi.fn(),
+    unmute: vi.fn(),
+  };
+  const session = createVoiceSession({}, () => controlsPromise);
+
+  return {
+    controls,
+    controlsPromise,
+    resolveControls: () => resolveControls(controls),
+    session,
+  };
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("createVoiceSession", () => {
+  it("applies mute requested while setup is pending", async () => {
+    const { controls, controlsPromise, resolveControls, session } =
+      createPendingTestSession();
+
+    session.mute();
+
+    expect(session.isMuted).toBe(true);
+    expect(controls.mute).not.toHaveBeenCalled();
+
+    resolveControls();
+    await controlsPromise;
+
+    expect(controls.mute).toHaveBeenCalledOnce();
+  });
+
+  it("does not apply stale mute after unmuting during setup", async () => {
+    const { controls, controlsPromise, resolveControls, session } =
+      createPendingTestSession();
+
+    session.mute();
+    session.unmute();
+    resolveControls();
+    await controlsPromise;
+
+    expect(session.isMuted).toBe(false);
+    expect(controls.mute).not.toHaveBeenCalled();
+  });
+
+  it("continues notifying listeners when one throws", () => {
+    const listenerError = new Error("listener failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const { helpers, session } = createTestSession();
+
+    const transcriptListener = vi.fn();
+    session.onTranscript(() => {
+      throw listenerError;
+    });
+    session.onTranscript(transcriptListener);
+
+    const modeListener = vi.fn();
+    session.onModeChange(() => {
+      throw listenerError;
+    });
+    session.onModeChange(modeListener);
+
+    const volumeListener = vi.fn();
+    session.onVolumeChange(() => {
+      throw listenerError;
+    });
+    session.onVolumeChange(volumeListener);
+
+    const statusListener = vi.fn();
+    session.onStatusChange(() => {
+      throw listenerError;
+    });
+    session.onStatusChange(statusListener);
+
+    helpers.emitTranscript({ role: "assistant", text: "hello" });
+    helpers.emitMode("speaking");
+    helpers.emitVolume(0.5);
+    helpers.end("finished");
+
+    expect(transcriptListener).toHaveBeenCalledWith({
+      role: "assistant",
+      text: "hello",
+    });
+    expect(modeListener).toHaveBeenCalledWith("speaking");
+    expect(volumeListener).toHaveBeenCalledWith(0.5);
+    expect(statusListener).toHaveBeenCalledWith({
+      type: "ended",
+      reason: "finished",
+      error: undefined,
+    });
+    expect(helpers.isDisposed()).toBe(true);
+    expect(consoleError).toHaveBeenCalledTimes(4);
+    expect(consoleError).toHaveBeenCalledWith(
+      "[assistant-ui] Voice session listener threw an error",
+      listenerError,
+    );
+  });
+});

package/src/adapters/voice.ts

@@ -57,6 +57,22 @@ export type VoiceSessionHelpers = {
   isDisposed: () => boolean;
 };
 
+const notifyListeners = <T>(
+  listeners: ReadonlySet<(value: T) => void>,
+  value: T,
+) => {
+  for (const listener of listeners) {
+    try {
+      listener(value);
+    } catch (error) {
+      console.error(
+        "[assistant-ui] Voice session listener threw an error",
+        error,
+      );
+    }
+  }
+};
+
 export function createVoiceSession(
   options: { abortSignal?: AbortSignal },
   setup: (helpers: VoiceSessionHelpers) => Promise<VoiceSessionControls>,
@@ -85,25 +101,25 @@ export function createVoiceSession(
     setStatus: (status) => {
       if (disposed) return;
       currentStatus = status;
-      for (const cb of statusCbs) cb(status);
+      notifyListeners(statusCbs, status);
     },
     end: (reason, error?) => {
       if (disposed) return;
       currentStatus = { type: "ended", reason, error };
-      for (const cb of statusCbs) cb(currentStatus);
+      notifyListeners(statusCbs, currentStatus);
       cleanup();
     },
     emitTranscript: (item) => {
       if (disposed) return;
-      for (const cb of transcriptCbs) cb(item);
+      notifyListeners(transcriptCbs, item);
     },
     emitMode: (mode) => {
       if (disposed) return;
-      for (const cb of modeCbs) cb(mode);
+      notifyListeners(modeCbs, mode);
     },
     emitVolume: (volume) => {
       if (disposed) return;
-      for (const cb of volumeCbs) cb(volume);
+      notifyListeners(volumeCbs, volume);
     },
     isDisposed: () => disposed,
   };
@@ -155,7 +171,11 @@ export function createVoiceSession(
     try {
       if (disposed) return;
       controls = await setup(helpers);
-      if (disposed) controls.disconnect();
+      if (disposed) {
+        controls.disconnect();
+      } else if (isMuted) {
+        controls.mute();
+      }
     } catch (error) {
       helpers.end("error", error);
     }

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
   // Message parts
   TextMessagePart,
   ReasoningMessagePart,
+  PartProviderMetadata,
   SourceProviderMetadata,
   SourceMessagePart,
   ImageMessagePart,
@@ -149,7 +150,12 @@ export type {
 export type { FeedbackAdapter } from "./adapters/feedback";
 
 // Suggestion adapter
-export type { SuggestionAdapter } from "./adapters/suggestion";
+export type {
+  SuggestionAdapter,
+  SuggestionAdapterGenerateOptions,
+  CreateSuggestionAdapterOptions,
+} from "./adapters/suggestion";
+export { createSuggestionAdapter } from "./adapters/suggestion";
 
 // Directive formatter
 export { unstable_defaultDirectiveFormatter } from "./adapters/directive-formatter";
@@ -188,6 +194,14 @@ export type {
   ThreadComposerRuntimeCore,
 } from "./runtime/interfaces/composer-runtime-core";
 
+export type {
+  ErrorSeverity,
+  ErrorDisplay,
+  AssistantErrorCode,
+  AssistantError,
+} from "./types/error";
+export { toAssistantError, isAssistantError } from "./types/error";
+
 export type {
   RuntimeCapabilities,
   AddToolResultOptions,

package/src/internal.ts

@@ -33,10 +33,31 @@ export {
 // Message utilities
 export { getThreadMessageText } from "./utils/text";
 export { resolveToolApprovalResponse } from "./runtime/utils/resolveToolApprovalResponse";
+export { consumeSuggestionResult } from "./adapters/suggestion";
 
 // Composite context provider
 export { CompositeContextProvider } from "./utils/composite-context-provider";
 
+// Shared attachment data-URL encoder, reused by framework adapters so the
+// FileReader fallback lives in one place.
+export { getFileDataURL } from "./adapters/attachment";
+export { isCreateAttachment } from "./types/attachment";
+
+// Streaming-stable tool-args stringifier, reused by framework adapters so the
+// key-order stabilization lives in one place.
+export {
+  stableStringifyToolArgs,
+  trackToolArgsKeyOrder,
+} from "./utils/json/stable-stringify-tool-args";
+
+// JSON type guards, reused by framework bindings so the depth-guarded
+// validation lives in one place.
+export { isJSONValue, isRecord } from "./utils/json/is-json";
+
+// Data-URL decoder and http(s) matcher, reused by framework adapters so the
+// outbound part conversion lives in one place.
+export { httpUrlPattern, parseDataUrl } from "./utils/data-url";
+
 // Runtime extras helper for external-store adapters. Internal because the
 // tap-native runtime path replaces the `thread.extras` side-channel it wraps.
 export {

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

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AssistantFrameHost } from "./host";
+import { type FrameMessage, FRAME_MESSAGE_CHANNEL } from "./types";
+
+const executionContext = {
+  toolCallId: "tool-call",
+  abortSignal: new AbortController().signal,
+  human: async () => undefined,
+};
+
+const createHost = () => {
+  let handleMessage: ((event: MessageEvent) => void) | undefined;
+  const addEventListener = vi.fn(
+    (_type: string, listener: EventListenerOrEventListenerObject) => {
+      handleMessage = listener as (event: MessageEvent) => void;
+    },
+  );
+  const removeEventListener = vi.fn();
+  vi.stubGlobal("window", { addEventListener, removeEventListener });
+
+  const postMessage = vi.fn();
+  const iframeWindow = { postMessage } as unknown as Window;
+  const host = new AssistantFrameHost(iframeWindow);
+
+  const dispatchMessage = (message: FrameMessage) =>
+    handleMessage?.({
+      source: iframeWindow,
+      data: {
+        channel: FRAME_MESSAGE_CHANNEL,
+        message,
+      },
+    } as unknown as MessageEvent);
+
+  dispatchMessage({
+    type: "model-context-update",
+    context: {
+      tools: {
+        search: {
+          type: "frontend",
+          parameters: { type: "object", properties: {} },
+        },
+      },
+    },
+  });
+
+  const execute = host.getModelContext().tools?.search?.execute;
+  if (!execute) throw new Error("Expected the search tool to be available");
+
+  return { dispatchMessage, execute, host, postMessage };
+};
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("AssistantFrameHost", () => {
+  it("resolves tool calls from frame results", async () => {
+    const { dispatchMessage, execute, host } = createHost();
+    const result = Promise.resolve(
+      execute({ query: "weather" }, executionContext),
+    );
+
+    dispatchMessage({
+      type: "tool-result",
+      id: "tool-0",
+      result: "sunny",
+    });
+
+    await expect(result).resolves.toBe("sunny");
+    expect(vi.getTimerCount()).toBe(0);
+    host.dispose();
+  });
+
+  it("rejects pending tool calls when disposed", async () => {
+    const { execute, host } = createHost();
+    const result = Promise.resolve(execute({}, executionContext));
+
+    host.dispose();
+
+    await expect(result).rejects.toThrow(
+      "AssistantFrameHost has been disposed",
+    );
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("rejects tool calls made after disposal without posting a request", async () => {
+    const { execute, host, postMessage } = createHost();
+    host.dispose();
+
+    await expect(execute({}, executionContext)).rejects.toThrow(
+      "AssistantFrameHost has been disposed",
+    );
+    expect(postMessage).toHaveBeenCalledOnce();
+  });
+});

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

@@ -53,6 +53,7 @@ export class AssistantFrameHost implements ModelContextProvider {
   private _requestCounter = 0;
   private _iframeWindow: Window;
   private _targetOrigin: string;
+  private _disposed = false;
 
   constructor(iframeWindow: Window, targetOrigin: string = "*") {
     this._iframeWindow = iframeWindow;
@@ -130,6 +131,10 @@ export class AssistantFrameHost implements ModelContextProvider {
     timeout = 30000,
     timeoutMessage = "Request timed out",
   ): Promise<any> {
+    if (this._disposed) {
+      return Promise.reject(new Error("AssistantFrameHost has been disposed"));
+    }
+
     return new Promise((resolve, reject) => {
       this._pendingRequests.set(message.id, { resolve, reject });
 
@@ -188,8 +193,13 @@ export class AssistantFrameHost implements ModelContextProvider {
   }
 
   dispose() {
+    this._disposed = true;
     window.removeEventListener("message", this.handleMessage);
     this._subscribers.clear();
+    const error = new Error("AssistantFrameHost has been disposed");
+    for (const pending of this._pendingRequests.values()) {
+      pending.reject(error);
+    }
     this._pendingRequests.clear();
   }
 }

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

@@ -0,0 +1,83 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AssistantFrameProvider } from "./provider";
+import { FRAME_MESSAGE_CHANNEL } from "./types";
+
+describe("AssistantFrameProvider", () => {
+  let messageHandler: ((event: MessageEvent) => void) | undefined;
+  let parentWindow: Window;
+
+  beforeEach(() => {
+    parentWindow = {
+      postMessage: vi.fn(),
+    } as unknown as Window;
+
+    Object.defineProperty(window, "parent", {
+      value: parentWindow,
+      configurable: true,
+    });
+
+    vi.spyOn(window, "addEventListener").mockImplementation(
+      (event, listener) => {
+        if (event === "message" && typeof listener === "function") {
+          messageHandler = listener as (event: MessageEvent) => void;
+        }
+      },
+    );
+    vi.spyOn(window, "removeEventListener").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    AssistantFrameProvider.dispose();
+    vi.restoreAllMocks();
+  });
+
+  it("only accepts tool calls from the parent window", async () => {
+    const execute = vi.fn(async () => "result");
+    AssistantFrameProvider.addModelContextProvider(
+      {
+        getModelContext: () => ({
+          tools: {
+            sensitiveTool: { execute },
+          },
+        }),
+      },
+      "https://parent.example",
+    );
+
+    const toolCall = {
+      channel: FRAME_MESSAGE_CHANNEL,
+      message: {
+        type: "tool-call",
+        id: "tool-call-1",
+        toolName: "sensitiveTool",
+        args: {},
+      },
+    };
+    const otherWindow = {
+      postMessage: vi.fn(),
+    } as unknown as Window;
+
+    messageHandler?.(
+      new MessageEvent("message", {
+        data: toolCall,
+        origin: "https://parent.example",
+        source: otherWindow,
+      }),
+    );
+
+    expect(execute).not.toHaveBeenCalled();
+
+    messageHandler?.(
+      new MessageEvent("message", {
+        data: toolCall,
+        origin: "https://parent.example",
+        source: parentWindow,
+      }),
+    );
+
+    await vi.waitFor(() => expect(execute).toHaveBeenCalledOnce());
+  });
+});

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

@@ -59,6 +59,7 @@ export class AssistantFrameProvider {
   private handleMessage(event: MessageEvent) {
     if (this._targetOrigin !== "*" && event.origin !== this._targetOrigin)
       return;
+    if (event.source !== window.parent) return;
     if (event.data?.channel !== FRAME_MESSAGE_CHANNEL) return;
 
     const message = event.data.message as FrameMessage;

package/src/model-context/tool.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import type { Tool } from "assistant-stream";
+import type { AsyncIterableStream } from "assistant-stream/utils";
+import { tool } from "./tool";
+
+type TestStandardSchema<TInput> = {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: "test";
+    readonly types?: {
+      readonly input: TInput;
+      readonly output: TInput;
+    };
+    readonly validate: (value: unknown) => { readonly value: TInput };
+  };
+};
+
+const checkStandardSchemaInference = () => {
+  const weatherSchema = {} as TestStandardSchema<{
+    city: string;
+    unit?: "c" | "f";
+    tags: string[];
+  }>;
+
+  const getWeather = tool({
+    type: "frontend",
+    parameters: weatherSchema,
+    execute: async (args) => {
+      expectTypeOf(args.city).toEqualTypeOf<string>();
+      expectTypeOf(args.unit).toEqualTypeOf<"c" | "f" | undefined>();
+      expectTypeOf(args.tags).toEqualTypeOf<string[]>();
+      // @ts-expect-error unknown schema fields should not be accepted
+      void args.missing;
+
+      return `Weather in ${args.city}`;
+    },
+    streamCall: async (reader) => {
+      const city = await reader.args.get("city");
+      expectTypeOf(city).toEqualTypeOf<string>();
+      expectTypeOf(reader.args.forEach("tags")).toEqualTypeOf<
+        AsyncIterableStream<string>
+      >();
+      // @ts-expect-error unknown argument paths should not be accepted
+      reader.args.get("missing");
+    },
+    toModelOutput: ({ input }) => {
+      expectTypeOf(input.city).toEqualTypeOf<string>();
+      expectTypeOf(input.unit).toEqualTypeOf<"c" | "f" | undefined>();
+      return [{ type: "text", text: input.city }];
+    },
+  });
+
+  expectTypeOf(getWeather).toEqualTypeOf<
+    Tool<
+      {
+        city: string;
+        unit?: "c" | "f";
+        tags: string[];
+      },
+      string
+    >
+  >();
+};
+expectTypeOf(checkStandardSchemaInference).toEqualTypeOf<() => void>();
+
+const checkUnknownStandardSchemaInputFallsBackToRecord = () => {
+  const unknownSchema = {} as TestStandardSchema<unknown>;
+
+  const passthrough = tool({
+    type: "frontend",
+    parameters: unknownSchema,
+    execute: async (args) => {
+      expectTypeOf(args).toEqualTypeOf<Record<string, unknown>>();
+      return args;
+    },
+  });
+
+  expectTypeOf(passthrough).toEqualTypeOf<
+    Tool<Record<string, unknown>, Record<string, unknown>>
+  >();
+};
+expectTypeOf(checkUnknownStandardSchemaInputFallsBackToRecord).toEqualTypeOf<
+  () => void
+>();
+
+const checkExplicitJsonSchemaTypesStillWork = () => {
+  const getWeather = tool<{ city: string }, string>({
+    type: "frontend",
+    parameters: {
+      type: "object",
+      properties: { city: { type: "string" } },
+      required: ["city"],
+    },
+    execute: async ({ city }) => city,
+  });
+
+  expectTypeOf(getWeather).toEqualTypeOf<Tool<{ city: string }, string>>();
+};
+expectTypeOf(checkExplicitJsonSchemaTypesStillWork).toEqualTypeOf<() => void>();
+
+describe("tool", () => {
+  it("returns the tool definition at runtime", () => {
+    const definition = {
+      type: "frontend" as const,
+      parameters: { type: "object" as const, properties: {} },
+    };
+
+    expect(tool(definition)).toBe(definition);
+  });
+});

package/src/model-context/tool.ts

@@ -1,6 +1,19 @@
 import type { Tool } from "assistant-stream";
 
-// TODO re-add the inferrence of the parameters
+type StandardSchemaInput<TSchema> = TSchema extends {
+  readonly "~standard": {
+    readonly types?: { readonly input: infer TInput } | undefined;
+  };
+}
+  ? TInput extends Record<string, unknown>
+    ? TInput
+    : Record<string, unknown>
+  : Record<string, unknown>;
+
+type StandardSchemaParameters = Extract<
+  NonNullable<Extract<Tool<any>, { parameters: unknown }>["parameters"]>,
+  { readonly "~standard": unknown }
+>;
 
 /**
  * Defines a model tool with its argument schema, execution behavior, and
@@ -8,25 +21,34 @@ import type { Tool } from "assistant-stream";
  *
  * This helper keeps reusable tool definitions type-checked and convenient to
  * export for a {@link Toolkit} registered with {@link Tools}.
- * Inference from parameter schemas is currently limited, so provide generic
- * arguments when you need precise args or result types.
+ * When `parameters` is a Standard Schema (for example Zod v4), its input type
+ * is inferred for `execute`, `streamCall`, and model-output callbacks. Plain
+ * JSON Schema objects do not carry TypeScript input types, so provide generic
+ * arguments or annotate callbacks when you need precise args for JSON Schema.
  *
  * @param tool - Tool definition to expose to the assistant model.
  *
  * @example
  * ```ts
- * const getWeather = tool<{ city: string }, string>({
+ * import { z } from "zod";
+ *
+ * const getWeather = tool({
  *   type: "frontend",
  *   description: "Get the weather for a city.",
- *   parameters: {
- *     type: "object",
- *     properties: { city: { type: "string" } },
- *     required: ["city"],
- *   },
+ *   parameters: z.object({ city: z.string() }),
  *   execute: async ({ city }) => `Sunny in ${city}`,
  * });
  * ```
  */
+export function tool<
+  const TSchema extends StandardSchemaParameters,
+  TResult = any,
+>(
+  tool: Tool<StandardSchemaInput<TSchema>, TResult> & { parameters: TSchema },
+): Tool<StandardSchemaInput<TSchema>, TResult>;
+export function tool<TArgs extends Record<string, unknown>, TResult = any>(
+  tool: Tool<TArgs, TResult>,
+): Tool<TArgs, TResult>;
 export function tool<TArgs extends Record<string, unknown>, TResult = any>(
   tool: Tool<TArgs, TResult>,
 ): Tool<TArgs, TResult> {