@assistant-ui/core 0.2.8 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Framework-agnostic core runtime for assistant-ui",
   "keywords": [
     "assistant",
@@ -59,7 +59,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.18",
+    "assistant-stream": "^0.3.20",
     "nanoid": "^5.1.11"
   },
   "peerDependencies": {
@@ -67,7 +67,7 @@
     "@assistant-ui/tap": "^0.5.14",
     "@types/react": "*",
     "react": "^18 || ^19",
-    "assistant-cloud": "^0.1.30",
+    "assistant-cloud": "^0.1.31",
     "zustand": "^5.0.11"
   },
   "peerDependenciesMeta": {
@@ -91,8 +91,8 @@
     "zustand": "^5.0.14",
     "@assistant-ui/store": "0.2.13",
     "@assistant-ui/tap": "0.5.14",
-    "@assistant-ui/x-buildutils": "0.0.10",
-    "assistant-cloud": "0.1.30"
+    "@assistant-ui/x-buildutils": "0.0.11",
+    "assistant-cloud": "0.1.31"
   },
   "publishConfig": {
     "access": "public",

package/src/model-context/tool.ts

@@ -7,7 +7,7 @@ import type { Tool } from "assistant-stream";
  * optional model-output conversion.
  *
  * This helper keeps reusable tool definitions type-checked and convenient to
- * export for a {@link Toolkit}, {@link Tools}, or {@link useAssistantTool}.
+ * 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.
  *

package/src/model-context/types.ts

@@ -55,7 +55,10 @@ export const mergeModelContexts = (
     .map((c) => c.getModelContext())
     .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 
+  const toolPriorities: Record<string, number> = {};
+
   return configs.reduce((acc, config) => {
+    const priority = config.priority ?? 0;
     if (config.system) {
       if (acc.system) {
         acc.system += `\n\n${config.system}`;
@@ -67,13 +70,28 @@ export const mergeModelContexts = (
       for (const [name, tool] of Object.entries(config.tools)) {
         const existing = acc.tools?.[name];
         if (existing && existing !== tool) {
-          throw new Error(
-            `You tried to define a tool with the name ${name}, but it already exists.`,
-          );
+          const existingPriority = toolPriorities[name]!;
+          if (existingPriority === priority) {
+            throw new Error(
+              `You tried to define a tool with the name ${name}, but it already exists.`,
+            );
+          }
+
+          const higherPriorityTool =
+            existingPriority > priority ? existing : tool;
+          const lowerPriorityTool =
+            existingPriority > priority ? tool : existing;
+          acc.tools![name] = {
+            ...lowerPriorityTool,
+            ...higherPriorityTool,
+          } as Tool<any, any>;
+          toolPriorities[name] = Math.max(existingPriority, priority);
+          continue;
         }
 
         if (!acc.tools) acc.tools = {};
         acc.tools[name] = tool;
+        toolPriorities[name] ??= priority;
       }
     }
     if (config.config) {

package/src/react/adapters/LocalStorageThreadListAdapter.tsx

@@ -28,13 +28,12 @@ type LocalStorageAdapterOptions = {
   titleGenerator?: TitleGenerationAdapter | undefined;
 };
 
-// `RemoteThreadMetadata.custom` is intentionally not persisted; consumers that
-// need it across reloads should fork this adapter or use a remote backend.
 type StoredThreadMetadata = {
   remoteId: string;
   externalId?: string;
   status: "regular" | "archived";
   title?: string;
+  custom?: Record<string, unknown> | undefined;
 };
 
 class AsyncStorageHistoryAdapter implements ThreadHistoryAdapter {
@@ -131,6 +130,7 @@ export const createLocalStorageAdapter = (
           externalId: t.externalId,
           status: t.status,
           title: t.title,
+          custom: t.custom,
         })),
       };
     },
@@ -162,6 +162,18 @@ export const createLocalStorageAdapter = (
       }
     },
 
+    async updateCustom(
+      remoteId: string,
+      custom: Record<string, unknown> | undefined,
+    ): Promise<void> {
+      const threads = await loadThreadMetadata();
+      const thread = threads.find((t) => t.remoteId === remoteId);
+      if (thread) {
+        thread.custom = custom;
+        await saveThreadMetadata(threads);
+      }
+    },
+
     async archive(remoteId: string): Promise<void> {
       const threads = await loadThreadMetadata();
       const thread = threads.find((t) => t.remoteId === remoteId);
@@ -196,6 +208,7 @@ export const createLocalStorageAdapter = (
         externalId: thread.externalId,
         status: thread.status,
         title: thread.title,
+        custom: thread.custom,
       };
     },
 

package/src/react/client/Tools.ts

@@ -17,6 +17,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";
@@ -106,22 +107,36 @@ export const Tools = resource(
 
       // Register tool UIs (exclude symbols)
       for (const [toolName, tool] of Object.entries(toolkit)) {
-        if (tool.render) {
+        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, tool.render, {
+            setToolUI(toolName, render, {
               standalone: isStandaloneToolDisplay(tool),
             }),
           );
         }
       }
 
-      // Register tools with model context (exclude symbols). `render` and
-      // `display` are client-only presentation concerns and never reach the
-      // model.
+      // 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]) => {
-          const { render, display, ...rest } = tool;
-          acc[name] = rest;
+          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>>,

package/src/react/index.ts

@@ -35,9 +35,22 @@ 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 { stubTool } from "./model-context/stub-tool";
+export { useAuiToolOverrides } from "./model-context/useAuiToolOverrides";
+export { hitl, hitlTool } from "./model-context/hitl";
+export {
+  providerTool,
+  type ProviderToolConfig,
+} from "./model-context/provider-tool";
+export {
+  defineMcpToolkit,
+  type McpToolkitDefinition,
+} from "./model-context/define-mcp-toolkit";
 export {
   useAssistantInteractable,
   type AssistantInteractableProps,

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

@@ -0,0 +1,101 @@
+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 { providerTool } from "./provider-tool";
+import { stubTool } from "./stub-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("hitlTool throws at runtime — it must be stripped by the compiler, never called", () => {
+    expect(() => hitlTool()).toThrow(/no runtime implementation/);
+  });
+
+  it("hitl remains a compatibility alias", () => {
+    expect(hitl).toBe(hitlTool);
+  });
+
+  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/);
+  });
+});

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

@@ -0,0 +1,41 @@
+import type {
+  Toolkit,
+  ToolkitDefinition,
+  ToolkitDefinitionEntryWithParameters,
+} 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}.
+ *
+ * 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.
+ */
+export function defineToolkit<
+  TArgsByName extends {
+    [K in keyof TArgsByName]: Record<string, unknown>;
+  },
+  TResultByName extends { [K in keyof TArgsByName]: unknown } = {
+    [K in keyof TArgsByName]: unknown;
+  },
+>(_definition: {
+  [K in keyof TArgsByName]: ToolkitDefinitionEntryWithParameters<
+    TArgsByName[K],
+    TResultByName[K]
+  >;
+}): Toolkit;
+export function defineToolkit(_definition: ToolkitDefinition): Toolkit;
+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.',
+  );
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 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: hitlTool(), render: (props) => <Confirm {...props} /> }
+ * ```
+ *
+ * Like {@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"`.
+ * Reaching it at runtime means the module wasn't compiled (used outside a
+ * `"use generative"` file), so it throws.
+ */
+export function hitlTool(): never {
+  throw new Error(
+    "[assistant-ui] hitlTool() 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).',
+  );
+}
+
+/**
+ * @deprecated Use {@link hitlTool}.
+ */
+export const hitl = hitlTool;

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".',
+  );
+}

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

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+import { makeToolCallTextComponent } from "./toolbox";
+
+describe("makeToolCallTextComponent", () => {
+  it("renders static running and complete text", () => {
+    const Render = makeToolCallTextComponent({
+      running: "Searching...",
+      complete: "Done searching",
+    });
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: {},
+        argsText: "{}",
+        status: { type: "running" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBe("Searching...");
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: {},
+        argsText: "{}",
+        result: "ok",
+        status: { type: "complete" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBe("Done searching");
+  });
+
+  it("passes args and result to dynamic text functions", () => {
+    const Render = makeToolCallTextComponent<
+      { query: string },
+      { count: number }
+    >({
+      running: ({ args }) => `Searching ${args.query}...`,
+      complete: ({ args, result }) =>
+        `Found ${result?.count ?? 0} results for ${args.query}`,
+    });
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: { query: "docs" },
+        argsText: '{"query":"docs"}',
+        status: { type: "running" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBe("Searching docs...");
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: { query: "docs" },
+        argsText: '{"query":"docs"}',
+        result: { count: 3 },
+        status: { type: "complete" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBe("Found 3 results for docs");
+  });
+
+  it("treats missing status as complete", () => {
+    const Render = makeToolCallTextComponent({
+      running: "Running",
+      complete: "Complete",
+    });
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: {},
+        argsText: "{}",
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBe("Complete");
+  });
+
+  it("treats incomplete status as a terminal state", () => {
+    const Render = makeToolCallTextComponent({
+      running: "Searching...",
+      complete: "Finished",
+    });
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: {},
+        argsText: "{}",
+        status: { type: "incomplete", reason: "error" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBe("Finished");
+  });
+
+  it("treats requires-action status as running", () => {
+    const Render = makeToolCallTextComponent({
+      running: "Waiting for approval...",
+      complete: "Done",
+    });
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "confirm",
+        args: {},
+        argsText: "{}",
+        status: { type: "requires-action", reason: "interrupt" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBe("Waiting for approval...");
+  });
+
+  it("renders null for terminal status when only running text is provided", () => {
+    const Render = makeToolCallTextComponent({
+      running: "Searching...",
+    });
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: {},
+        argsText: "{}",
+        status: { type: "complete" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBeNull();
+  });
+
+  it("renders null for running status when only complete text is provided", () => {
+    const Render = makeToolCallTextComponent({
+      complete: "Done",
+    });
+
+    expect(
+      Render({
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "search",
+        args: {},
+        argsText: "{}",
+        status: { type: "running" },
+        addResult: () => {},
+        resume: () => {},
+        respondToApproval: () => {},
+      }),
+    ).toBeNull();
+  });
+});