@assistant-ui/core 0.2.10 → 0.2.12

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";
@@ -33,136 +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)) {
-        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>>,
-      );
-
-      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

@@ -41,8 +41,9 @@ export {
 } from "./model-context/toolbox";
 export { defineToolkit } from "./model-context/define-toolkit";
 export { stubTool } from "./model-context/stub-tool";
+export { externalTool } from "./model-context/external-tool";
 export { useAuiToolOverrides } from "./model-context/useAuiToolOverrides";
-export { hitl, hitlTool } from "./model-context/hitl";
+export { hitl, hitlTool, humanTool } from "./model-context/human-tool";
 export {
   providerTool,
   type ProviderToolConfig,
@@ -154,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-toolkit.test.ts

@@ -1,9 +1,10 @@
 import { describe, it, expect, expectTypeOf } from "vitest";
 import type { AsyncIterableStream } from "assistant-stream/utils";
 import { defineToolkit } from "./define-toolkit";
-import { hitl, hitlTool } 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> = {
@@ -74,16 +75,18 @@ const checkToolkitDefinitionTypes = () => {
 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("hitlTool throws at runtime — it must be stripped by the compiler, never called", () => {
-    expect(() => hitlTool()).toThrow(/no runtime implementation/);
+  it("humanTool throws at runtime — it must be stripped by the compiler, never called", () => {
+    expect(() => humanTool()).toThrow(/no runtime implementation/);
   });
 
-  it("hitl remains a compatibility alias", () => {
-    expect(hitl).toBe(hitlTool);
+  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", () => {
@@ -98,4 +101,8 @@ describe("use-generative markers", () => {
   it("stubTool throws at runtime — it must be stripped by the compiler, never called", () => {
     expect(() => stubTool()).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

@@ -5,37 +5,36 @@ import type {
 } from "./toolbox";
 
 /**
- * Authoring helper for a `"use generative"` toolkit. Accepts the permissive
- * {@link ToolkitDefinition} (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<
   TArgsByName extends {
     [K in keyof TArgsByName]: Record<string, unknown>;
   },
   TResultByName extends { [K in keyof TArgsByName]: unknown } = {
-    [K in keyof TArgsByName]: unknown;
+    [K in keyof TArgsByName]: any;
   },
 >(_definition: {
   [K in keyof TArgsByName]: ToolkitDefinitionEntryWithParameters<
     TArgsByName[K],
     TResultByName[K]
   >;
-}): Toolkit;
-export function defineToolkit(_definition: ToolkitDefinition): Toolkit;
+}): 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 {
-  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.',
-  );
+  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/{hitl.ts → human-tool.ts}

@@ -3,25 +3,30 @@
  * supplies the result instead of code. Use it as the tool's `execute`:
  *
  * ```tsx
- * confirm: { execute: hitlTool(), render: (props) => <Confirm {...props} /> }
+ * confirm: { execute: humanTool(), render: (props) => <Confirm {...props} /> }
  * ```
  *
- * Like {@link defineToolkit}, it has **no runtime implementation**: a
+ * Unlike {@link defineToolkit}, it has **no runtime implementation**: a
  * `"use generative"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)
- * detects `execute: hitlTool()`, drops it, and stamps the tool `type: "human"`.
+ * 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 hitlTool(): never {
+export function humanTool(): never {
   throw new Error(
-    "[assistant-ui] hitlTool() has no runtime implementation — it marks a " +
+    "[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. hitlTool() used outside a "use generative" file).',
+      '(e.g. humanTool() used outside a "use generative" file).',
   );
 }
 
 /**
- * @deprecated Use {@link hitlTool}.
+ * @deprecated Use {@link humanTool}.
  */
-export const hitl = hitlTool;
+export const hitlTool = humanTool;
+
+/**
+ * @deprecated Use {@link humanTool}.
+ */
+export const hitl = humanTool;

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

@@ -128,7 +128,7 @@ export type ToolDefinition<
  *
  * @example
  * ```tsx
- * const toolkit = {
+ * const toolkit = defineToolkit({
  *   get_weather: {
  *     type: "frontend",
  *     description: "Get the weather for a city.",
@@ -136,7 +136,7 @@ export type ToolDefinition<
  *     execute: async ({ city }: { city: string }) => fetchWeather(city),
  *     render: WeatherToolUI,
  *   },
- * } satisfies Toolkit;
+ * });
  * ```
  */
 export type Toolkit = Record<string, ToolDefinition<any, any>>;
@@ -145,7 +145,7 @@ export type Toolkit = Record<string, ToolDefinition<any, any>>;
  * A tool as authored, before the build splits it: like {@link ToolDefinition}
  * but it may declare `description`, `parameters`, and a server-side `execute`
  * alongside its `render`. The `type` field is **not** authored — the
- * `"use generative"` compiler infers it (`execute: hitlTool()` → human;
+ * `"use generative"` compiler infers it (`execute: humanTool()` → human;
  * `execute: providerTool(...)` → provider; `execute` with a `"use client"`
  * directive → frontend; otherwise backend) and writes it back — so declaring it
  * here is a type error.

package/src/react/primitives/message/MessageGroupedParts.tsx

@@ -265,7 +265,7 @@ export const MessagePrimitiveGroupedParts = <TKey extends `group-${string}`>({
   const tree = useMemo(() => {
     const context: GroupByContext = { toolUIs };
     return buildGroupTree(parts.map((part) => groupBy(part, context) ?? []));
-    // oxlint-disable-next-line tap-hooks/exhaustive-deps -- groupBy is captured via memoDep (either its identity or the helper's memoKey fingerprint); listing it directly would defeat the helper-tagged memo path
+    // oxlint-disable-next-line react/exhaustive-deps -- groupBy is captured via memoDep (either its identity or the helper's memoKey fingerprint); listing it directly would defeat the helper-tagged memo path
   }, [parts, memoDep, toolUIs]);
 
   return (

package/src/react/primitives/part/PartMessages.tsx

@@ -34,7 +34,7 @@ const usePartMessages = (): readonly ThreadMessage[] | undefined => {
  *
  * @example
  * ```tsx
- * const toolkit = {
+ * const toolkit = defineToolkit({
  *   invoke_sub_agent: {
  *     type: "backend",
  *     render: () => (
@@ -46,7 +46,7 @@ const usePartMessages = (): readonly ThreadMessage[] | undefined => {
  *       </PartPrimitive.Messages>
  *     ),
  *   },
- * } satisfies Toolkit;
+ * });
  * ```
  */
 export const PartPrimitiveMessagesImpl: FC<PartPrimitiveMessages.Props> = ({

package/src/react/providers/TextMessagePartProvider.tsx

@@ -1,39 +1,38 @@
-import type { FC, PropsWithChildren } from "react";
+import { type FC, type PropsWithChildren, useMemo } from "react";
 import { useAui, AuiProvider, type ClientOutput } from "@assistant-ui/store";
 import type { PartState } from "../../store/scopes/part";
-import { resource, tapMemo } from "@assistant-ui/tap";
 
-const TextMessagePartClient = resource(
-  ({
-    text,
-    isRunning,
-  }: {
-    text: string;
-    isRunning: boolean;
-  }): ClientOutput<"part"> => {
-    const state = tapMemo<PartState>(
-      () => ({
-        type: "text",
-        text,
-        status: isRunning ? { type: "running" } : { type: "complete" },
-      }),
-      [text, isRunning],
-    );
+import { resource } from "@assistant-ui/tap";
+
+const TextMessagePartClient = resource(function TextMessagePartClient({
+  text,
+  isRunning,
+}: {
+  text: string;
+  isRunning: boolean;
+}): ClientOutput<"part"> {
+  const state = useMemo<PartState>(
+    () => ({
+      type: "text",
+      text,
+      status: isRunning ? { type: "running" } : { type: "complete" },
+    }),
+    [text, isRunning],
+  );
 
-    return {
-      getState: () => state,
-      addToolResult: () => {
-        throw new Error("Not supported");
-      },
-      resumeToolCall: () => {
-        throw new Error("Not supported");
-      },
-      respondToToolApproval: () => {
-        throw new Error("Not supported");
-      },
-    };
-  },
-);
+  return {
+    getState: () => state,
+    addToolResult: () => {
+      throw new Error("Not supported");
+    },
+    resumeToolCall: () => {
+      throw new Error("Not supported");
+    },
+    respondToToolApproval: () => {
+      throw new Error("Not supported");
+    },
+  };
+});
 
 export const TextMessagePartProvider: FC<
   PropsWithChildren<{

package/src/react/runtimes/createMessageConverter.ts

@@ -5,6 +5,7 @@ import { useAui, useAuiState } from "@assistant-ui/store";
 import {
   useExternalMessageConverter,
   convertExternalMessages,
+  type JoinStrategy,
 } from "./external-message-converter";
 import { getExternalStoreMessages } from "../../runtime/utils/external-store-message";
 
@@ -20,7 +21,7 @@ export const createMessageConverter = <T extends object>(
     }: {
       messages: T[];
       isRunning: boolean;
-      joinStrategy?: "concat-content" | "none" | undefined;
+      joinStrategy?: JoinStrategy | undefined;
       metadata?: useExternalMessageConverter.Metadata;
     }) => {
       return useExternalMessageConverter<T>({

package/src/react/runtimes/external-message-converter.ts

@@ -22,6 +22,8 @@ import type {
 } from "../../types/message";
 import type { MessageTiming } from "../../types/message";
 
+export type JoinStrategy = "concat-content" | "none";
+
 type ThreadMessageLikeContentItem = Exclude<
   ThreadMessageLike["content"],
   string
@@ -42,7 +44,7 @@ export namespace useExternalMessageConverter {
   export type Message =
     | (ThreadMessageLike & {
         readonly convertConfig?: {
-          readonly joinStrategy?: "concat-content" | "none";
+          readonly joinStrategy?: JoinStrategy;
         };
       })
     | {
@@ -264,7 +266,7 @@ const joinExternalMessages = (
 
 const chunkExternalMessages = <T>(
   callbackResults: CallbackResult<T>[],
-  joinStrategy?: "concat-content" | "none",
+  joinStrategy?: JoinStrategy,
 ) => {
   const results: ChunkResult<T>[] = [];
   let isAssistant = false;
@@ -397,7 +399,7 @@ export const useExternalMessageConverter = <T extends WeakKey>({
   callback: useExternalMessageConverter.Callback<T>;
   messages: T[];
   isRunning: boolean;
-  joinStrategy?: "concat-content" | "none" | undefined;
+  joinStrategy?: JoinStrategy | undefined;
   metadata?: useExternalMessageConverter.Metadata | undefined;
 }) => {
   const state = useMemo(

package/src/react/runtimes/useLocalRuntime.ts

@@ -71,6 +71,7 @@ export const splitLocalRuntimeOptions = <T extends LocalRuntimeOptions>(
     maxSteps,
     adapters,
     unstable_humanToolNames,
+    unstable_enableMessageQueue,
     ...rest
   } = options;
 
@@ -81,6 +82,7 @@ export const splitLocalRuntimeOptions = <T extends LocalRuntimeOptions>(
       maxSteps,
       adapters,
       unstable_humanToolNames,
+      unstable_enableMessageQueue,
     },
     otherOptions: rest,
   };