@assistant-ui/core 0.2.9 → 0.2.11

package/src/react/client/Tools.ts

@@ -1,15 +1,12 @@
+import { useState, useEffect, useCallback, useMemo } from "react";
 import {
+  useResources,
   resource,
-  tapState,
-  tapEffect,
-  tapCallback,
-  tapMemo,
-  tapResources,
   withKey,
   type ResourceElement,
 } from "@assistant-ui/tap";
 import {
-  tapAssistantClientRef,
+  useAssistantClientRef,
   type ClientOutput,
   attachTransformScopes,
 } from "@assistant-ui/store";
@@ -17,6 +14,7 @@ import type { McpAppResourceOutput, ToolsState } from "../types/scopes/tools";
 import type { Tool } from "assistant-stream";
 import {
   isStandaloneToolDisplay,
+  makeToolCallTextComponent,
   type Toolkit,
 } from "../model-context/toolbox";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
@@ -32,122 +30,132 @@ export type { McpAppResourceOutput };
  * context, while each tool renderer is registered with the tools scope for
  * message rendering.
  */
-export const Tools = resource(
-  ({
-    toolkit,
-    mcpApp,
-  }: {
-    /** Tools to expose to the model and optional renderers to install. */
-    toolkit?: Toolkit;
-    /** Optional MCP app resource whose tools should be merged into context. */
-    mcpApp?: ResourceElement<McpAppResourceOutput> | undefined;
-  }): ClientOutput<"tools"> => {
-    const mcpAppOutputs = tapResources(
-      () => (mcpApp ? [withKey("mcpApp", mcpApp)] : []),
-      [mcpApp],
-    );
-    const mcpAppOutput = mcpAppOutputs[0];
-
-    const [toolUIs, setToolUIs] = tapState<ToolsState["toolUIs"]>(() => ({}));
-
-    const state = tapMemo(
-      (): ToolsState => ({
-        toolUIs,
-        mcpApp: mcpAppOutput,
-        // Deprecated component-only view, derived from `toolUIs`. Removed in v0.15.
-        tools: Object.fromEntries(
-          Object.entries(toolUIs).map(([name, regs]) => [
-            name,
-            regs.map((r) => r.render),
-          ]),
-        ),
-      }),
-      [toolUIs, mcpAppOutput],
-    );
-
-    const clientRef = tapAssistantClientRef();
-
-    const setToolUI = tapCallback(
-      (
-        toolName: string,
-        render: ToolCallMessagePartComponent,
-        options?: { standalone?: boolean },
-      ) => {
-        // One registration object per call; identity is the removal key, so
-        // the per-name list stays correctly ref-counted across re-registers.
-        const registration = {
-          render,
-          standalone: options?.standalone ?? false,
-        };
-
-        setToolUIs((prev) => ({
-          ...prev,
-          [toolName]: [...(prev[toolName] ?? []), registration],
-        }));
-
-        return () => {
-          setToolUIs((prev) => {
-            const next =
-              prev[toolName]?.filter((r) => r !== registration) ?? [];
-            if (next.length > 0) return { ...prev, [toolName]: next };
-            // Drop the key entirely so repeatedly mounted/unmounted tools
-            // don't leave empty arrays accumulating across a long session.
-            const { [toolName]: _removed, ...rest } = prev;
-            return rest;
-          });
-        };
-      },
-      [],
-    );
-
-    tapEffect(() => {
-      if (!toolkit) return;
-      const unsubscribes: (() => void)[] = [];
-
-      // Register tool UIs (exclude symbols)
-      for (const [toolName, tool] of Object.entries(toolkit)) {
-        if (tool.render) {
-          unsubscribes.push(
-            setToolUI(toolName, tool.render, {
-              standalone: isStandaloneToolDisplay(tool),
-            }),
-          );
-        }
-      }
-
-      // Register tools with model context (exclude symbols). `render` and
-      // `display` are client-only presentation concerns and never reach the
-      // model.
-      const toolsWithoutRender = Object.entries(toolkit).reduce(
-        (acc, [name, tool]) => {
-          const { render, display, ...rest } = tool;
-          acc[name] = rest;
-          return acc;
-        },
-        {} as Record<string, Tool<any, any>>,
-      );
-
-      const modelContextProvider = {
-        getModelContext: () => ({
-          tools: toolsWithoutRender,
-        }),
+export const Tools = resource(function Tools({
+  toolkit,
+  mcpApp,
+}: {
+  /** Tools to expose to the model and optional renderers to install. */
+  toolkit?: Toolkit;
+  /** Optional MCP app resource whose tools should be merged into context. */
+  mcpApp?: ResourceElement<McpAppResourceOutput> | undefined;
+}): ClientOutput<"tools"> {
+  const mcpAppOutputs = useResources(
+    () => (mcpApp ? [withKey("mcpApp", mcpApp)] : []),
+    [mcpApp],
+  );
+  const mcpAppOutput = mcpAppOutputs[0];
+
+  const [toolUIs, setToolUIs] = useState<ToolsState["toolUIs"]>(() => ({}));
+
+  const state = useMemo(
+    (): ToolsState => ({
+      toolUIs,
+      mcpApp: mcpAppOutput,
+      // Deprecated component-only view, derived from `toolUIs`. Removed in v0.15.
+      tools: Object.fromEntries(
+        Object.entries(toolUIs).map(([name, regs]) => [
+          name,
+          regs.map((r) => r.render),
+        ]),
+      ),
+    }),
+    [toolUIs, mcpAppOutput],
+  );
+
+  const clientRef = useAssistantClientRef();
+
+  const setToolUI = useCallback(
+    (
+      toolName: string,
+      render: ToolCallMessagePartComponent,
+      options?: { standalone?: boolean },
+    ) => {
+      // One registration object per call; identity is the removal key, so
+      // the per-name list stays correctly ref-counted across re-registers.
+      const registration = {
+        render,
+        standalone: options?.standalone ?? false,
       };
 
-      unsubscribes.push(
-        clientRef.current!.modelContext().register(modelContextProvider),
-      );
+      setToolUIs((prev) => ({
+        ...prev,
+        [toolName]: [...(prev[toolName] ?? []), registration],
+      }));
 
       return () => {
-        unsubscribes.forEach((fn) => fn());
+        setToolUIs((prev) => {
+          const next = prev[toolName]?.filter((r) => r !== registration) ?? [];
+          if (next.length > 0) return { ...prev, [toolName]: next };
+          // Drop the key entirely so repeatedly mounted/unmounted tools
+          // don't leave empty arrays accumulating across a long session.
+          const { [toolName]: _removed, ...rest } = prev;
+          return rest;
+        });
       };
-    }, [toolkit, setToolUI, clientRef]);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    if (!toolkit) return;
+    const unsubscribes: (() => void)[] = [];
+
+    // Register tool UIs (exclude symbols)
+    for (const [toolName, tool] of Object.entries(toolkit)) {
+      const toolRender = "render" in tool ? tool.render : undefined;
+      const toolRenderText = "renderText" in tool ? tool.renderText : undefined;
+      const render =
+        toolRender ??
+        (toolRenderText
+          ? makeToolCallTextComponent(toolRenderText)
+          : undefined);
+      if (render) {
+        unsubscribes.push(
+          setToolUI(toolName, render, {
+            standalone: isStandaloneToolDisplay(tool),
+          }),
+        );
+      }
+    }
+
+    // Register tools with model context (exclude symbols). `render`,
+    // `renderText`, and `display` are client-only presentation concerns and
+    // never reach the model.
+    const toolsWithoutRender = Object.entries(toolkit).reduce(
+      (acc, [name, tool]) => {
+        if (tool.type === "mcp") return acc;
+        const {
+          display: _display,
+          render: _render,
+          renderText: _renderText,
+          ...rest
+        } = tool as typeof tool & { renderText?: unknown };
+        acc[name] = rest as Tool<any, any>;
+        return acc;
+      },
+      {} as Record<string, Tool<any, any>>,
+    );
 
-    return {
-      getState: () => state,
-      setToolUI,
+    const modelContextProvider = {
+      getModelContext: () => ({
+        tools: toolsWithoutRender,
+      }),
     };
-  },
-);
+
+    unsubscribes.push(
+      clientRef.current!.modelContext().register(modelContextProvider),
+    );
+
+    return () => {
+      unsubscribes.forEach((fn) => fn());
+    };
+  }, [toolkit, setToolUI, clientRef]);
+
+  return {
+    getState: () => state,
+    setToolUI,
+  };
+});
 
 attachTransformScopes(Tools, (scopes, parent) => {
   if (!scopes.modelContext && parent.modelContext.source === null) {

package/src/react/index.ts

@@ -35,11 +35,23 @@ export { useInlineRender } from "./model-context/useInlineRender";
 export {
   type Toolkit,
   type ToolDefinition,
-  type ToolkitDeclaration,
-  type ToolkitDeclarationDefinition,
+  type ToolkitDefinition,
+  type ToolkitDefinitionEntry,
+  type ToolCallText,
 } from "./model-context/toolbox";
 export { defineToolkit } from "./model-context/define-toolkit";
-export { hitl } from "./model-context/hitl";
+export { stubTool } from "./model-context/stub-tool";
+export { externalTool } from "./model-context/external-tool";
+export { useAuiToolOverrides } from "./model-context/useAuiToolOverrides";
+export { hitl, hitlTool, humanTool } from "./model-context/human-tool";
+export {
+  providerTool,
+  type ProviderToolConfig,
+} from "./model-context/provider-tool";
+export {
+  defineMcpToolkit,
+  type McpToolkitDefinition,
+} from "./model-context/define-mcp-toolkit";
 export {
   useAssistantInteractable,
   type AssistantInteractableProps,
@@ -143,6 +155,7 @@ export {
   useExternalMessageConverter,
   convertExternalMessages,
 } from "./runtimes/external-message-converter";
+export type { JoinStrategy } from "./runtimes/external-message-converter";
 export { createMessageConverter } from "./runtimes/createMessageConverter";
 export { RemoteThreadListHookInstanceManager } from "./runtimes/RemoteThreadListHookInstanceManager";
 export { RemoteThreadListThreadListRuntimeCore } from "./runtimes/RemoteThreadListThreadListRuntimeCore";

package/src/react/model-context/define-mcp-toolkit.ts

@@ -0,0 +1,16 @@
+import type { McpServerConfig } from "assistant-stream";
+import type { Toolkit } from "./toolbox";
+
+export type McpToolkitDefinition = Record<string, McpServerConfig>;
+
+/**
+ * Defines MCP server tools as a spreadable toolkit fragment.
+ */
+export function defineMcpToolkit(definition: McpToolkitDefinition): Toolkit {
+  return Object.fromEntries(
+    Object.entries(definition).map(([name, server]) => [
+      name,
+      { type: "mcp", server },
+    ]),
+  ) as Toolkit;
+}

package/src/react/model-context/define-toolkit.test.ts

@@ -1,13 +1,108 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, expectTypeOf } from "vitest";
+import type { AsyncIterableStream } from "assistant-stream/utils";
 import { defineToolkit } from "./define-toolkit";
-import { hitl } from "./hitl";
+import { hitl, hitlTool, humanTool } from "./human-tool";
+import { providerTool } from "./provider-tool";
+import { stubTool } from "./stub-tool";
+import { externalTool } from "./external-tool";
+import type { ToolkitDefinition } from "./toolbox";
+
+type TestStandardSchema<T> = {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: "test";
+    readonly types?: {
+      readonly input: T;
+      readonly output: T;
+    };
+    readonly validate: (value: unknown) => { readonly value: T };
+  };
+};
+
+const checkDefineToolkitTypes = () => {
+  defineToolkit({
+    search: {
+      parameters: {} as TestStandardSchema<{
+        query: string;
+        limit?: number;
+        tags: string[];
+      }>,
+      execute: async ({
+        query,
+        limit,
+      }: {
+        query: string;
+        limit?: number;
+        tags: string[];
+      }) => ({
+        ids: [query],
+        count: limit ?? 0,
+      }),
+      streamCall: async (reader) => {
+        const query = await reader.args.get("query");
+        expectTypeOf(query).toEqualTypeOf<string>();
+
+        expectTypeOf(reader.args.streamValues("query")).toEqualTypeOf<
+          AsyncIterableStream<string>
+        >();
+        expectTypeOf(reader.args.streamText("query")).toEqualTypeOf<
+          AsyncIterableStream<unknown>
+        >();
+        expectTypeOf(reader.args.forEach("tags")).toEqualTypeOf<
+          AsyncIterableStream<string>
+        >();
+
+        const response = await reader.response.get();
+        expectTypeOf(response.result).toEqualTypeOf<unknown>();
+
+        // @ts-expect-error unknown argument paths should not be accepted
+        reader.args.get("missing");
+      },
+    },
+  });
+};
+expectTypeOf(checkDefineToolkitTypes).toEqualTypeOf<() => void>();
+
+const checkToolkitDefinitionTypes = () => {
+  ({
+    invalidMcp: {
+      // @ts-expect-error MCP-shaped tools cannot also declare an execute callback
+      server: { type: "http", url: "https://example.com/mcp" },
+      execute: async () => "invalid",
+    },
+  }) satisfies ToolkitDefinition;
+};
+expectTypeOf(checkToolkitDefinitionTypes).toEqualTypeOf<() => void>();
 
 describe("use-generative markers", () => {
-  it("defineToolkit throws at runtime — it must be stripped by the compiler, never called", () => {
-    expect(() => defineToolkit({})).toThrow(/no runtime implementation/);
+  it("defineToolkit returns the toolkit at runtime", () => {
+    const toolkit = {};
+    expect(defineToolkit(toolkit)).toBe(toolkit);
+  });
+
+  it("humanTool throws at runtime — it must be stripped by the compiler, never called", () => {
+    expect(() => humanTool()).toThrow(/no runtime implementation/);
+  });
+
+  it("hitlTool and hitl remain compatibility aliases", () => {
+    expect(hitlTool).toBe(humanTool);
+    expect(hitl).toBe(humanTool);
+  });
+
+  it("providerTool throws at runtime — it must be stripped by the compiler, never called", () => {
+    expect(() =>
+      providerTool({
+        providerId: "openai.web_search_preview",
+        args: {},
+      }),
+    ).toThrow(/no runtime implementation/);
+  });
+
+  it("stubTool throws at runtime — it must be stripped by the compiler, never called", () => {
+    expect(() => stubTool()).toThrow(/no runtime implementation/);
   });
 
-  it("hitl throws at runtime — it must be stripped by the compiler, never called", () => {
-    expect(() => hitl()).toThrow(/no runtime implementation/);
+  it("externalTool throws at runtime — it must be stripped by the compiler, never called", () => {
+    expect(() => externalTool()).toThrow(/no runtime implementation/);
   });
 });

package/src/react/model-context/define-toolkit.ts

@@ -1,23 +1,40 @@
-import type { Toolkit, ToolkitDeclaration } from "./toolbox";
+import type {
+  Toolkit,
+  ToolkitDefinition,
+  ToolkitDefinitionEntryWithParameters,
+} from "./toolbox";
 
 /**
- * Authoring helper for a `"use generative"` toolkit. Accepts the permissive
- * {@link ToolkitDeclaration} (a `backend` tool may carry its server `execute`)
- * and types the result as the canonical {@link Toolkit}.
+ * Toolkit authoring helper. Accepts the permissive {@link ToolkitDefinition}
+ * (a generative `backend` tool may carry its server `execute`) and types the
+ * result as the canonical {@link Toolkit}.
  *
- * It has **no runtime implementation**. A `"use generative"` compiler (e.g.
- * `@assistant-ui/next` or `@assistant-ui/vite`) strips the `defineToolkit(...)`
- * wrapper (and its import) per build, so a correctly compiled
- * `export default defineToolkit({...})` never calls this. If it *does* run, the
- * module was not compiled by a use-generative loader — e.g. `defineToolkit` used
- * outside a `"use generative"` file — which would ship a backend `execute` to the
- * client. So it throws instead of silently leaking.
+ * In a `"use generative"` file, the compiler strips the wrapper per build so it
+ * can split schemas, renderers, and executors across the client/server boundary.
+ * Outside generative compilation, it returns the toolkit unchanged and can be
+ * used for plain frontend/backend/human toolkit objects.
  */
-export function defineToolkit(_declaration: ToolkitDeclaration): Toolkit {
-  throw new Error(
-    "[assistant-ui] defineToolkit() has no runtime implementation — it is " +
-      "stripped at build time by the use-generative compiler. Reaching it means " +
-      'this module was not compiled (e.g. defineToolkit used outside a "use ' +
-      'generative" file). Add the directive, or do not use defineToolkit here.',
-  );
+export function defineToolkit<
+  TArgsByName extends {
+    [K in keyof TArgsByName]: Record<string, unknown>;
+  },
+  TResultByName extends { [K in keyof TArgsByName]: unknown } = {
+    [K in keyof TArgsByName]: any;
+  },
+>(_definition: {
+  [K in keyof TArgsByName]: ToolkitDefinitionEntryWithParameters<
+    TArgsByName[K],
+    TResultByName[K]
+  >;
+}): Toolkit & {
+  [K in keyof TArgsByName]: ToolkitDefinitionEntryWithParameters<
+    TArgsByName[K],
+    TResultByName[K]
+  >;
+};
+export function defineToolkit<const TDefinition extends ToolkitDefinition>(
+  _definition: TDefinition,
+): Toolkit & TDefinition;
+export function defineToolkit(_definition: ToolkitDefinition): Toolkit {
+  return _definition as Toolkit;
 }

package/src/react/model-context/external-tool.ts

@@ -0,0 +1,16 @@
+/**
+ * Marks a generative toolkit entry as an externally executed backend tool.
+ *
+ * Use this when another system (for example a backend route or LangGraph node)
+ * already defines and executes the tool, but assistant-ui should render its
+ * tool calls. The use-generative compiler omits `execute: externalTool()`
+ * entries from the server build and keeps a `type: "backend"` renderer on the
+ * client build.
+ */
+export function externalTool(): never {
+  throw new Error(
+    "[assistant-ui] externalTool() has no runtime implementation - it marks a " +
+      "tool that executes outside assistant-ui and is stripped at build time " +
+      'by the use-generative compiler. Make sure this module is compiled as "use generative".',
+  );
+}

package/src/react/model-context/human-tool.ts

@@ -0,0 +1,32 @@
+/**
+ * Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)
+ * supplies the result instead of code. Use it as the tool's `execute`:
+ *
+ * ```tsx
+ * confirm: { execute: humanTool(), render: (props) => <Confirm {...props} /> }
+ * ```
+ *
+ * Unlike {@link defineToolkit}, it has **no runtime implementation**: a
+ * `"use generative"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)
+ * detects `execute: humanTool()`, drops it, and stamps the tool `type: "human"`.
+ * Reaching it at runtime means the module wasn't compiled (used outside a
+ * `"use generative"` file), so it throws.
+ */
+export function humanTool(): never {
+  throw new Error(
+    "[assistant-ui] humanTool() has no runtime implementation — it marks a " +
+      "human-in-the-loop tool and is stripped at build time by the " +
+      "use-generative compiler. Reaching it means this module was not compiled " +
+      '(e.g. humanTool() used outside a "use generative" file).',
+  );
+}
+
+/**
+ * @deprecated Use {@link humanTool}.
+ */
+export const hitlTool = humanTool;
+
+/**
+ * @deprecated Use {@link humanTool}.
+ */
+export const hitl = humanTool;

package/src/react/model-context/makeAssistantTool.ts

@@ -6,6 +6,10 @@ import { type AssistantToolProps, useAssistantTool } from "./useAssistantTool";
  *
  * Rendering the component registers its tool for the lifetime of that render
  * subtree.
+ *
+ * @deprecated Use a toolkit with `Tools({ toolkit })` and register it via
+ * `useAui({ tools: Tools({ toolkit }) })` instead. See
+ * https://assistant-ui.com/docs/migrations/toolkit-tools.
  */
 export type AssistantTool = FC & {
   /** Tool definition registered by this component. */
@@ -19,6 +23,10 @@ export type AssistantTool = FC & {
  * rather than calling {@link useAssistantTool} directly.
  *
  * @param tool - Tool definition and name to register.
+ *
+ * @deprecated Use a toolkit with `Tools({ toolkit })` and register it via
+ * `useAui({ tools: Tools({ toolkit }) })` instead. See
+ * https://assistant-ui.com/docs/migrations/toolkit-tools.
  */
 export const makeAssistantTool = <
   TArgs extends Record<string, unknown>,

package/src/react/model-context/makeAssistantToolUI.ts

@@ -9,6 +9,10 @@ import {
  *
  * Rendering the component registers a renderer for matching tool-call message
  * parts.
+ *
+ * @deprecated Put `render`/`renderText` on the matching toolkit entry, or use
+ * `MessagePrimitive.Parts` inline tool render overrides for per-message UI.
+ * See https://assistant-ui.com/docs/migrations/toolkit-tools.
  */
 export type AssistantToolUI = FC & {
   /** Tool renderer registered by this component. */
@@ -22,6 +26,10 @@ export type AssistantToolUI = FC & {
  * are registered elsewhere.
  *
  * @param tool - Tool renderer registration.
+ *
+ * @deprecated Put `render`/`renderText` on the matching toolkit entry, or use
+ * `MessagePrimitive.Parts` inline tool render overrides for per-message UI.
+ * See https://assistant-ui.com/docs/migrations/toolkit-tools.
  */
 export const makeAssistantToolUI = <TArgs, TResult>(
   tool: AssistantToolUIProps<TArgs, TResult>,

package/src/react/model-context/provider-tool.ts

@@ -0,0 +1,30 @@
+import type { Tool } from "assistant-stream";
+
+type ProviderToolDefinition<TArgs extends Record<string, unknown>> = Extract<
+  Tool<TArgs, unknown>,
+  { type: "provider" }
+>;
+
+export type ProviderToolConfig<
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+> = Pick<
+  ProviderToolDefinition<TArgs>,
+  | "providerId"
+  | "args"
+  | "parameters"
+  | "providerOptions"
+  | "supportsDeferredResults"
+>;
+
+/**
+ * Marks a tool as provider-executed. The use-generative compiler converts
+ * `execute: providerTool(...)` into a `type: "provider"` tool entry.
+ */
+export function providerTool(_config: ProviderToolConfig): never {
+  throw new Error(
+    "[assistant-ui] providerTool() has no runtime implementation — it marks a " +
+      "provider-executed tool and is stripped at build time by the " +
+      "use-generative compiler. Reaching it means this module was not compiled " +
+      '(e.g. providerTool() used outside a "use generative" file).',
+  );
+}

package/src/react/model-context/stub-tool.ts

@@ -0,0 +1,14 @@
+/**
+ * Marks a generative toolkit entry as a frontend tool whose executor will be
+ * supplied by `useAuiToolOverrides(...)`.
+ *
+ * `stubTool()` has no runtime implementation. It must be used inside a
+ * `"use generative"` toolkit file so the compiler can strip it.
+ */
+export function stubTool(): never {
+  throw new Error(
+    "[assistant-ui] stubTool() has no runtime implementation - it marks a " +
+      "tool executor that must be supplied via useAuiToolOverrides(...). Make " +
+      'sure this module is compiled as "use generative".',
+  );
+}