@assistant-ui/react-ai-sdk 1.3.30 → 1.3.32

package/src/generativeTools.ts

@@ -0,0 +1,310 @@
+import { jsonSchema, type ToolSet } from "ai";
+import type { MCPClient, MCPClientConfig } from "@ai-sdk/mcp";
+import { createMCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+import {
+  toJSONSchema,
+  type Tool,
+  type McpServerConfig,
+  type ToolJSONSchema,
+  type ToolModelOutputFunction,
+} from "assistant-stream";
+import type { Toolkit, ToolkitDefinition } from "@assistant-ui/core/react";
+import { frontendTools } from "./frontendTools";
+import { toAISDKContent, toAISDKDefaultOutput } from "./toolOutputConversion";
+import {
+  unwrapModelContentEnvelope,
+  type ModelContentEnvelope,
+} from "./modelContentEnvelope";
+
+const EMPTY_SCHEMA = { type: "object" as const, properties: {} };
+
+const humanNotSupported = (): never => {
+  throw new Error(
+    "`human()` is not available during server-side tool execution.",
+  );
+};
+
+// AI SDK leaves `abortSignal` optional; assistant-ui's execute requires one.
+const neverAbort = new AbortController().signal;
+
+const parametersToInputSchema = (parameters: Tool["parameters"] | undefined) =>
+  jsonSchema(parameters ? toJSONSchema(parameters) : EMPTY_SCHEMA);
+
+export interface GenerativeToolsOptions {
+  /**
+   * The server build of a generative toolkit (schema + server `execute`). Typed
+   * as the canonical {@link Toolkit} so callers don't need to cast; the server
+   * build carries `execute`, recovered internally as {@link ToolkitDefinition}.
+   */
+  toolkit: Toolkit;
+  /**
+   * Tools uploaded by the frontend (the request body's `tools`). Merged in
+   * alongside the `toolkit`; a server `execute` from `toolkit` takes precedence
+   * over an uploaded entry of the same name.
+   */
+  frontendTools?: Record<string, ToolJSONSchema>;
+}
+
+export type AISDKToolkitOptions = {
+  toolkit: Toolkit;
+};
+
+export type AISDKToolkitToolsOptions = {
+  /**
+   * Tools uploaded by the frontend request body.
+   */
+  frontend?: Record<string, ToolJSONSchema>;
+};
+
+/**
+ * Builds an AI SDK `ToolSet` for server-side use with `streamText` /
+ * `generateText` from a generative `toolkit` and the frontend-uploaded tools.
+ *
+ * Each toolkit tool's `execute` runs on the server. Pair this with the
+ * `"use generative"` compiler: import the toolkit in a server route (where it
+ * resolves to the server build — schema + `execute`, with `render` stripped) and
+ * pass it here. Tools without an `execute` are still exposed to the model but
+ * left for the client to fulfill. `frontendTools` lets the client contribute
+ * tools that aren't in the static toolkit. Use {@link AISDKToolkit} when the
+ * toolkit contains MCP entries.
+ *
+ * @example
+ * ```ts
+ * const { tools } = await req.json();
+ * streamText({
+ *   model,
+ *   messages,
+ *   tools: generativeTools({ toolkit: docsToolkit, frontendTools: tools }),
+ * });
+ * ```
+ */
+export const generativeTools = (options: GenerativeToolsOptions): ToolSet => {
+  assertNoMcpToolkitTools(options.toolkit);
+  return {
+    ...(options.frontendTools ? frontendTools(options.frontendTools) : {}),
+    // `toolkit` last so its server-side `execute` wins over an uploaded entry of
+    // the same name. The cast recovers the declaration shape — the server build
+    // carries `execute`, which the canonical `Toolkit` type erases.
+    ...toProviderToolSet(options.toolkit),
+    ...toServerToolSet(options.toolkit as ToolkitDefinition),
+  };
+};
+
+export class AISDKToolkit {
+  readonly #toolkit: Toolkit;
+  readonly #mcpClients = new Map<string, Promise<MCPClient>>();
+
+  constructor(options: AISDKToolkitOptions) {
+    this.#toolkit = options.toolkit;
+  }
+
+  async tools(options: AISDKToolkitToolsOptions = {}): Promise<ToolSet> {
+    return {
+      ...(options.frontend ? frontendTools(options.frontend) : {}),
+      ...(await this.#mcpTools()),
+      ...toProviderToolSet(this.#toolkit),
+      ...toServerToolSet(this.#toolkit as ToolkitDefinition),
+    };
+  }
+
+  async close(): Promise<void> {
+    const clientPromises = [...this.#mcpClients.values()];
+    this.#mcpClients.clear();
+    const results = await Promise.allSettled(clientPromises);
+    const clients = results.flatMap((result) =>
+      result.status === "fulfilled" ? [result.value] : [],
+    );
+    const closeResults = await Promise.allSettled(
+      clients.map((client) => client.close()),
+    );
+    const errors = [
+      ...results.flatMap((result) =>
+        result.status === "rejected" ? [result.reason] : [],
+      ),
+      ...closeResults.flatMap((result) =>
+        result.status === "rejected" ? [result.reason] : [],
+      ),
+    ];
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) {
+      throw new AggregateError(
+        errors,
+        "Failed to close one or more MCP clients",
+      );
+    }
+  }
+
+  async #mcpTools(): Promise<ToolSet> {
+    const toolSets = await Promise.all(
+      Object.entries(this.#toolkit)
+        .filter((entry): entry is [string, McpToolkitTool] =>
+          isMcpToolkitTool(entry[1]),
+        )
+        .map(async ([name, tool]) => {
+          const client = await this.#mcpClient(name, tool.server);
+          return [name, await client.tools()] as const;
+        }),
+    );
+
+    const tools: ToolSet = {};
+    const toolSources = new Map<string, string>();
+    for (const [serverName, toolSet] of toolSets) {
+      for (const [toolName, tool] of Object.entries(toolSet)) {
+        const existingServerName = toolSources.get(toolName);
+        if (existingServerName) {
+          throw new Error(
+            `MCP tool name collision: "${toolName}" is exposed by both "${existingServerName}" and "${serverName}". Rename one of the toolkit entries or expose distinct MCP tool names.`,
+          );
+        }
+        toolSources.set(toolName, serverName);
+        tools[toolName] = tool;
+      }
+    }
+    return tools;
+  }
+
+  #mcpClient(name: string, config: McpServerConfig): Promise<MCPClient> {
+    const existing = this.#mcpClients.get(name);
+    if (existing) return existing;
+    let next: Promise<MCPClient>;
+    next = createMCPClient(toMCPClientConfig(config)).catch((error) => {
+      if (this.#mcpClients.get(name) === next) {
+        this.#mcpClients.delete(name);
+      }
+      throw error;
+    });
+    this.#mcpClients.set(name, next);
+    return next;
+  }
+}
+
+const toMCPClientConfig = (config: McpServerConfig): MCPClientConfig => {
+  if (config.type === "stdio") {
+    return {
+      transport: new Experimental_StdioMCPTransport({
+        command: config.command,
+        ...(config.args && { args: [...config.args] }),
+        ...(config.env && { env: config.env }),
+        ...(config.cwd && { cwd: config.cwd }),
+      }),
+    };
+  }
+
+  return {
+    transport: {
+      type: config.type,
+      url: config.url,
+      ...(config.headers && { headers: config.headers }),
+      ...(config.redirect && { redirect: config.redirect }),
+    },
+  };
+};
+
+type ToolkitTool = Toolkit[string];
+
+type McpToolkitTool = ToolkitTool & {
+  type: "mcp";
+  server: McpServerConfig;
+};
+
+const isMcpToolkitTool = (tool: ToolkitTool): tool is McpToolkitTool =>
+  tool.type === "mcp" && !tool.disabled;
+
+const assertNoMcpToolkitTools = (toolkit: Toolkit): void => {
+  const mcpToolName = Object.entries(toolkit).find(([, tool]) =>
+    isMcpToolkitTool(tool),
+  )?.[0];
+  if (!mcpToolName) return;
+
+  throw new Error(
+    `MCP toolkit entry "${mcpToolName}" requires AISDKToolkit. Use new AISDKToolkit({ toolkit }).tools(...) instead of generativeTools(...).`,
+  );
+};
+
+type AISDKToModelOutputOptions<TArgs, TResult> = Omit<
+  Parameters<ToolModelOutputFunction<TArgs, TResult>>[0],
+  "output"
+> & {
+  output: TResult | ModelContentEnvelope<TResult>;
+};
+
+const toAISDKToModelOutput =
+  <TArgs, TResult>(toModelOutput?: ToolModelOutputFunction<TArgs, TResult>) =>
+  async (options: AISDKToModelOutputOptions<TArgs, TResult>) => {
+    const { result, modelContent } = unwrapModelContentEnvelope(options.output);
+
+    if (modelContent !== undefined) {
+      return toAISDKContent(modelContent);
+    }
+
+    if (!toModelOutput) {
+      return toAISDKDefaultOutput(result);
+    }
+
+    const parts = await toModelOutput({
+      ...options,
+      output: result,
+    });
+    return toAISDKContent(parts);
+  };
+
+const toServerToolSet = (toolkit: ToolkitDefinition): ToolSet =>
+  Object.fromEntries(
+    Object.entries(toolkit)
+      .filter(
+        ([, t]) => t.type !== "mcp" && t.type !== "provider" && !t.disabled,
+      )
+      .map(([name, t]) => {
+        const execute = t.execute;
+        return [
+          name,
+          {
+            ...(t.description !== undefined && { description: t.description }),
+            inputSchema: parametersToInputSchema(t.parameters),
+            toModelOutput: toAISDKToModelOutput(t.toModelOutput),
+            ...(t.providerOptions && { providerOptions: t.providerOptions }),
+            ...(execute && {
+              execute: (
+                args: unknown,
+                callOptions: { toolCallId: string; abortSignal?: AbortSignal },
+              ) =>
+                execute(args as never, {
+                  toolCallId: callOptions.toolCallId,
+                  abortSignal: callOptions.abortSignal ?? neverAbort,
+                  human: humanNotSupported,
+                }),
+            }),
+          },
+        ];
+      }),
+  ) as ToolSet;
+
+const toProviderToolSet = (toolkit: Toolkit): ToolSet =>
+  Object.fromEntries(
+    Object.entries(toolkit)
+      .filter((entry): entry is [string, ProviderToolkitTool] =>
+        isProviderToolkitTool(entry[1]),
+      )
+      .map(([name, t]) => [
+        name,
+        {
+          type: "provider",
+          id: t.providerId,
+          args: t.args,
+          ...(t.parameters && {
+            inputSchema: parametersToInputSchema(t.parameters),
+          }),
+          ...(t.providerOptions && { providerOptions: t.providerOptions }),
+          ...(t.supportsDeferredResults !== undefined && {
+            supportsDeferredResults: t.supportsDeferredResults,
+          }),
+        },
+      ]),
+  ) as ToolSet;
+
+type ProviderToolkitTool = Extract<Toolkit[string], { type: "provider" }>;
+
+const isProviderToolkitTool = (
+  tool: Toolkit[string],
+): tool is ProviderToolkitTool => tool.type === "provider" && !tool.disabled;

package/src/index.ts

@@ -13,6 +13,13 @@ export type {
   ResumableClientStorage,
 } from "./ui/resumable";
 export { frontendTools } from "./frontendTools";
+export {
+  AISDKToolkit,
+  generativeTools,
+  type AISDKToolkitOptions,
+  type AISDKToolkitToolsOptions,
+  type GenerativeToolsOptions,
+} from "./generativeTools";
 export { injectQuoteContext } from "./injectQuoteContext";
 export type { ThreadTokenUsage, TokenUsageExtractableMessage } from "./usage";
 export { getThreadMessageTokenUsage, useThreadTokenUsage } from "./usage";

package/src/modelContentEnvelope.ts

@@ -7,9 +7,9 @@ export type ModelContentEnvelope<TResult = unknown> = {
   readonly value: TResult;
 };
 
-export function isModelContentEnvelope(
-  value: unknown,
-): value is ModelContentEnvelope {
+export function isModelContentEnvelope<TResult = unknown>(
+  value: TResult | ModelContentEnvelope<TResult>,
+): value is ModelContentEnvelope<TResult> {
   return (
     value != null &&
     typeof value === "object" &&
@@ -25,8 +25,10 @@ export function wrapModelContentEnvelope<TResult>(
   return { [ENVELOPE_KEY]: modelContent, value: result };
 }
 
-export function unwrapModelContentEnvelope(output: unknown): {
-  result: unknown;
+export function unwrapModelContentEnvelope<TResult>(
+  output: TResult | ModelContentEnvelope<TResult>,
+): {
+  result: TResult;
   modelContent?: readonly ToolModelContentPart[];
 } {
   if (isModelContentEnvelope(output)) {

package/src/toolOutputConversion.ts

@@ -0,0 +1,29 @@
+import type { JSONValue } from "ai";
+import type { ToolModelContentPart } from "assistant-stream";
+
+export const toAISDKContent = (parts: readonly ToolModelContentPart[]) => ({
+  type: "content" as const,
+  value: parts.map((part) => {
+    if (part.type === "text") {
+      return { type: "text" as const, text: part.text };
+    }
+    const isImage = part.mediaType.startsWith("image/");
+    return isImage
+      ? {
+          type: "image-data" as const,
+          data: part.data,
+          mediaType: part.mediaType,
+        }
+      : {
+          type: "file-data" as const,
+          data: part.data,
+          mediaType: part.mediaType,
+          ...(part.filename !== undefined && { filename: part.filename }),
+        };
+  }),
+});
+
+export const toAISDKDefaultOutput = (output: unknown) =>
+  typeof output === "string"
+    ? { type: "text" as const, value: output }
+    : { type: "json" as const, value: (output ?? null) as JSONValue };

package/src/ui/use-chat/useAISDKRuntime.test.ts

@@ -2,6 +2,7 @@
 
 import { act, renderHook, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { validateUIMessages } from "ai";
 
 // Mock only the sibling module that requires AUI store context (not available
 // in isolation). Every other dependency — useExternalStoreRuntime,
@@ -140,6 +141,54 @@ describe("useAISDKRuntime", () => {
     expect(chat.messages[0].parts[1].state).toBe("output-available");
   });
 
+  it("strips stale approval when cancelling a tool pending approval so history stays valid (#4195)", async () => {
+    const chat = createChatHelpers([
+      {
+        id: "a1",
+        role: "assistant",
+        parts: [
+          {
+            type: "dynamic-tool",
+            toolName: "mcp_search",
+            toolCallId: "tc-1",
+            state: "approval-requested",
+            input: { q: "hi" },
+            approval: { id: "appr-1" },
+          },
+        ],
+      },
+    ]);
+
+    const { result } = renderHook(() => useAISDKRuntime(chat));
+
+    await waitFor(() => {
+      expect(result.current.thread.getState().messages.length).toBeGreaterThan(
+        0,
+      );
+    });
+
+    act(() => {
+      result.current.thread.append({
+        role: "user",
+        content: [{ type: "text", text: "what" }],
+      });
+    });
+
+    await waitFor(() => {
+      expect(chat.sendMessage).toHaveBeenCalledTimes(1);
+    });
+
+    const part = chat.messages[0].parts[0];
+    expect(part.state).toBe("output-error");
+    // The pending-approval object must not survive into the terminal state,
+    // otherwise AI SDK's validateUIMessages rejects the next request.
+    expect(part.approval).toBeUndefined();
+
+    await expect(
+      validateUIMessages({ messages: chat.messages }),
+    ).resolves.toBeDefined();
+  });
+
   it("appends a new user message without sending when startRun is false", async () => {
     const chat = createChatHelpers([
       { id: "u1", role: "user", parts: [{ type: "text", text: "earlier" }] },
@@ -354,4 +403,40 @@ describe("useAISDKRuntime", () => {
       metadata: { custom: { maxTokens: 100 } },
     });
   });
+
+  it("forwards isDisabled to thread state", () => {
+    const chat = createChatHelpers();
+    const { result } = renderHook(() =>
+      useAISDKRuntime(chat, { isDisabled: true }),
+    );
+    expect(result.current.thread.getState().isDisabled).toBe(true);
+  });
+
+  it("forwards isSendDisabled to the composer canSend gate", () => {
+    const chat = createChatHelpers();
+    const { result } = renderHook(() =>
+      useAISDKRuntime(chat, { isSendDisabled: true }),
+    );
+    act(() => {
+      result.current.thread.composer.setText("hello");
+    });
+    expect(result.current.thread.composer.getState().canSend).toBe(false);
+  });
+
+  it("forwards unstable_capabilities to thread capabilities", () => {
+    const chat = createChatHelpers();
+    const { result } = renderHook(() =>
+      useAISDKRuntime(chat, { unstable_capabilities: { copy: false } }),
+    );
+    expect(result.current.thread.getState().capabilities.unstable_copy).toBe(
+      false,
+    );
+  });
+
+  it("forwards suggestions to thread state", () => {
+    const chat = createChatHelpers();
+    const suggestions = [{ prompt: "tell me a joke" }];
+    const { result } = renderHook(() => useAISDKRuntime(chat, { suggestions }));
+    expect(result.current.thread.getState().suggestions).toEqual(suggestions);
+  });
 });

package/src/ui/use-chat/useAISDKRuntime.ts

@@ -10,10 +10,10 @@ import {
 import type { ToolExecutionStatus } from "@assistant-ui/core";
 import type {
   ExternalStoreAdapter,
+  ExternalStoreSharedOptions,
   ThreadHistoryAdapter,
   AssistantRuntime,
   ThreadMessage,
-  ThreadSuggestion,
   MessageFormatAdapter,
   MessageFormatItem,
   MessageFormatRepository,
@@ -21,7 +21,10 @@ import type {
   RunConfig,
   McpAppMetadata,
 } from "@assistant-ui/core";
-import { getExternalStoreMessages } from "@assistant-ui/core";
+import {
+  getExternalStoreMessages,
+  pickExternalStoreSharedOptions,
+} from "@assistant-ui/core";
 import type { ReadonlyJSONObject } from "assistant-stream/utils";
 import { sliceMessagesUntil } from "../utils/sliceMessagesUntil";
 import { toCreateMessage } from "../utils/toCreateMessage";
@@ -55,7 +58,7 @@ const toUIMessage = <UI_MESSAGE extends UIMessage>(
     role: createMessage.role ?? fallbackRole,
   }) as UI_MESSAGE;
 
-export type AISDKRuntimeAdapter = {
+export type AISDKRuntimeAdapter = ExternalStoreSharedOptions & {
   adapters?:
     | (NonNullable<ExternalStoreAdapter["adapters"]> & {
         history?: ThreadHistoryAdapter | undefined;
@@ -79,25 +82,18 @@ export type AISDKRuntimeAdapter = {
    * (for example, an SSE reconnect endpoint keyed by turn id).
    */
   onResume?: ExternalStoreAdapter["onResume"];
-  /**
-   * Follow up suggestions to surface on the thread. Use this to drive
-   * dynamic suggestions from application state, tool results, or backend
-   * responses; flows into `thread.suggestions` and is rendered by
-   * components that read it (such as the shadcn `ThreadFollowupSuggestions`).
-   */
-  suggestions?: readonly ThreadSuggestion[] | undefined;
 };
 
 export const useAISDKRuntime = <UI_MESSAGE extends UIMessage = UIMessage>(
   chatHelpers: ReturnType<typeof useChat<UI_MESSAGE>>,
-  {
+  adapter: AISDKRuntimeAdapter = {},
+) => {
+  const {
     adapters,
     toCreateMessage: customToCreateMessage,
     cancelPendingToolCallsOnSend = true,
     onResume,
-    suggestions,
-  }: AISDKRuntimeAdapter = {},
-) => {
+  } = adapter;
   const contextAdapters = useRuntimeAdapters();
   const [toolStatuses, setToolStatuses] = useState<
     Record<string, ToolExecutionStatus>
@@ -121,6 +117,12 @@ export const useAISDKRuntime = <UI_MESSAGE extends UIMessage = UIMessage>(
 
   const messageTiming = useStreamingTiming(chatHelpers.messages, isRunning);
 
+  // Flag the streaming message optimistic: its id can be swapped for a server
+  // id mid-run, and the repository then drops the orphaned pre-swap id (#4037).
+  const lastMessage = chatHelpers.messages.at(-1);
+  const optimisticMessageId =
+    isRunning && lastMessage?.role === "assistant" ? lastMessage.id : undefined;
+
   const messages = AISDKMessageConverter.useThreadMessages({
     isRunning,
     messages: chatHelpers.messages,
@@ -131,9 +133,10 @@ export const useAISDKRuntime = <UI_MESSAGE extends UIMessage = UIMessage>(
         toolArgsKeyOrderCache: toolArgsKeyOrderCacheRef.current,
         toolLastInputCache: toolLastInputCacheRef.current,
         mcpAppMetadataCache: mcpAppMetadataCacheRef.current,
+        ...(optimisticMessageId && { optimisticMessageId }),
         ...(chatHelpers.error && { error: chatHelpers.error.message }),
       }),
-      [toolStatuses, messageTiming, chatHelpers.error],
+      [toolStatuses, messageTiming, optimisticMessageId, chatHelpers.error],
     ),
   });
 
@@ -177,8 +180,9 @@ export const useAISDKRuntime = <UI_MESSAGE extends UIMessage = UIMessage>(
           return part;
 
         hasChanges = true;
+        const { approval: _approval, ...rest } = part;
         return {
-          ...part,
+          ...rest,
           state: "output-error" as const,
           errorText: "User cancelled tool call by sending a new message.",
         };
@@ -344,8 +348,8 @@ export const useAISDKRuntime = <UI_MESSAGE extends UIMessage = UIMessage>(
         options: { metadata: lastRunConfigRef.current },
       });
     },
+    ...pickExternalStoreSharedOptions(adapter),
     ...(onResume && { onResume }),
-    ...(suggestions && { suggestions }),
     adapters: {
       attachments: vercelAttachmentAdapter,
       ...contextAdapters,

package/src/ui/use-chat/useChatRuntime.ts

@@ -2,7 +2,11 @@
 
 import { useChat, type UIMessage } from "@ai-sdk/react";
 import type { AssistantCloud } from "assistant-cloud";
-import type { AssistantRuntime } from "@assistant-ui/core";
+import {
+  pickExternalStoreSharedOptions,
+  type AssistantRuntime,
+  type ExternalStoreSharedOptions,
+} from "@assistant-ui/core";
 import {
   useCloudThreadListAdapter,
   useRemoteThreadListRuntime,
@@ -19,24 +23,21 @@ import type { AssistantChatResumableOptions } from "../resumable";
 import { useEffect, useMemo, useRef } from "react";
 
 export type UseChatRuntimeOptions<UI_MESSAGE extends UIMessage = UIMessage> =
-  ChatInit<UI_MESSAGE> & {
-    cloud?: AssistantCloud | undefined;
-    adapters?: AISDKRuntimeAdapter["adapters"] | undefined;
-    toCreateMessage?: CustomToCreateMessageFunction;
-    onResume?: AISDKRuntimeAdapter["onResume"];
-    suggestions?: AISDKRuntimeAdapter["suggestions"];
-  };
+  ChatInit<UI_MESSAGE> &
+    ExternalStoreSharedOptions & {
+      cloud?: AssistantCloud | undefined;
+      adapters?: AISDKRuntimeAdapter["adapters"] | undefined;
+      toCreateMessage?: CustomToCreateMessageFunction;
+      onResume?: AISDKRuntimeAdapter["onResume"];
+    };
 
 const useDynamicChatTransport = <UI_MESSAGE extends UIMessage = UIMessage>(
   transport: ChatTransport<UI_MESSAGE>,
 ): ChatTransport<UI_MESSAGE> => {
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const transportRef = useRef<ChatTransport<UI_MESSAGE>>(transport);
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     transportRef.current = transport;
   });
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const dynamicTransport = useMemo(
     () =>
       new Proxy(transportRef.current, {
@@ -72,33 +73,36 @@ const useChatThreadRuntime = <UI_MESSAGE extends UIMessage = UIMessage>(
     adapters,
     transport: transportOptions,
     toCreateMessage,
+    isDisabled: _isDisabled,
+    isSendDisabled: _isSendDisabled,
+    unstable_capabilities: _unstable_capabilities,
+    suggestions: _suggestions,
     onResume,
-    suggestions,
     ...chatOptions
   } = options ?? {};
+  // peel guard: any shared key left in `chatOptions` collapses this to `never`
+  true satisfies keyof typeof chatOptions &
+    keyof ExternalStoreSharedOptions extends never
+    ? true
+    : never;
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const transport = useDynamicChatTransport(
     transportOptions ?? new AssistantChatTransport(),
   );
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const id = useAuiState((s) => s.threadListItem.id);
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const aui = useAui();
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const chat = useChat({
     ...chatOptions,
     id,
     transport,
   });
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const runtime = useAISDKRuntime(chat, {
     adapters,
+    ...pickExternalStoreSharedOptions(options ?? {}),
     ...(toCreateMessage && { toCreateMessage }),
     ...(onResume && { onResume }),
-    ...(suggestions && { suggestions }),
   });
 
   if (transport instanceof AssistantChatTransport) {
@@ -108,9 +112,7 @@ const useChatThreadRuntime = <UI_MESSAGE extends UIMessage = UIMessage>(
     );
   }
 
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   const resumeFiredRef = useRef(false);
-  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
   useEffect(() => {
     if (resumeFiredRef.current) return;
     const adapter = getResumableAdapter(transport);
@@ -137,7 +139,6 @@ export const useChatRuntime = <UI_MESSAGE extends UIMessage = UIMessage>({
   const cloudAdapter = useCloudThreadListAdapter({ cloud });
   return useRemoteThreadListRuntime({
     runtimeHook: function RuntimeHook() {
-      // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
       return useChatThreadRuntime(options);
     },
     adapter: cloudAdapter,