@assistant-ui/core 0.2.9 → 0.2.10

package/dist/store/runtime-clients/thread-list-item-runtime-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"thread-list-item-runtime-client.js","names":[],"sources":["../../../src/store/runtime-clients/thread-list-item-runtime-client.ts"],"sourcesContent":["import type { Unsubscribe } from \"../../types/unsubscribe\";\nimport { resource, tapEffect } from \"@assistant-ui/tap\";\nimport { type ClientOutput, tapAssistantEmit } from \"@assistant-ui/store\";\nimport type {\n  ThreadListItemEventType,\n  ThreadListItemRuntime,\n} from \"../../runtime/api/thread-list-item-runtime\";\nimport { tapSubscribable } from \"./tap-subscribable\";\n\nexport const ThreadListItemClient = resource(\n  ({\n    runtime,\n  }: {\n    runtime: ThreadListItemRuntime;\n  }): ClientOutput<\"threadListItem\"> => {\n    const state = tapSubscribable(runtime);\n    const emit = tapAssistantEmit();\n\n    // Bind thread list item events to event manager\n    tapEffect(() => {\n      const unsubscribers: Unsubscribe[] = [];\n\n      // Subscribe to thread list item events\n      const threadListItemEvents: ThreadListItemEventType[] = [\n        \"switchedTo\",\n        \"switchedAway\",\n      ];\n\n      for (const event of threadListItemEvents) {\n        const unsubscribe = runtime.unstable_on(event, () => {\n          emit(`threadListItem.${event}`, {\n            threadId: runtime.getState()!.id,\n          });\n        });\n        unsubscribers.push(unsubscribe);\n      }\n\n      return () => {\n        for (const unsub of unsubscribers) unsub();\n      };\n    }, [runtime, emit]);\n\n    return {\n      getState: () => state,\n      switchTo: runtime.switchTo,\n      rename: runtime.rename,\n      archive: runtime.archive,\n      unarchive: runtime.unarchive,\n      delete: runtime.delete,\n      generateTitle: runtime.generateTitle,\n      initialize: runtime.initialize,\n      detach: runtime.detach,\n      __internal_getRuntime: () => runtime,\n    };\n  },\n);\n"],"mappings":";;;;AASA,MAAa,uBAAuB,UACjC,EACC,cAGoC;CACpC,MAAM,QAAQ,gBAAgB,OAAO;CACrC,MAAM,OAAO,iBAAiB;CAG9B,gBAAgB;EACd,MAAM,gBAA+B,CAAC;EAQtC,KAAK,MAAM,SAAS,CAJlB,cACA,cAGqC,GAAG;GACxC,MAAM,cAAc,QAAQ,YAAY,aAAa;IACnD,KAAK,kBAAkB,SAAS,EAC9B,UAAU,QAAQ,SAAS,EAAG,GAChC,CAAC;GACH,CAAC;GACD,cAAc,KAAK,WAAW;EAChC;EAEA,aAAa;GACX,KAAK,MAAM,SAAS,eAAe,MAAM;EAC3C;CACF,GAAG,CAAC,SAAS,IAAI,CAAC;CAElB,OAAO;EACL,gBAAgB;EAChB,UAAU,QAAQ;EAClB,QAAQ,QAAQ;EAChB,SAAS,QAAQ;EACjB,WAAW,QAAQ;EACnB,QAAQ,QAAQ;EAChB,eAAe,QAAQ;EACvB,YAAY,QAAQ;EACpB,QAAQ,QAAQ;EAChB,6BAA6B;CAC/B;AACF,CACF"}
+{"version":3,"file":"thread-list-item-runtime-client.js","names":[],"sources":["../../../src/store/runtime-clients/thread-list-item-runtime-client.ts"],"sourcesContent":["import type { Unsubscribe } from \"../../types/unsubscribe\";\nimport { resource, tapEffect } from \"@assistant-ui/tap\";\nimport { type ClientOutput, tapAssistantEmit } from \"@assistant-ui/store\";\nimport type {\n  ThreadListItemEventType,\n  ThreadListItemRuntime,\n} from \"../../runtime/api/thread-list-item-runtime\";\nimport { tapSubscribable } from \"./tap-subscribable\";\n\nexport const ThreadListItemClient = resource(\n  ({\n    runtime,\n  }: {\n    runtime: ThreadListItemRuntime;\n  }): ClientOutput<\"threadListItem\"> => {\n    const state = tapSubscribable(runtime);\n    const emit = tapAssistantEmit();\n\n    // Bind thread list item events to event manager\n    tapEffect(() => {\n      const unsubscribers: Unsubscribe[] = [];\n\n      // Subscribe to thread list item events\n      const threadListItemEvents: ThreadListItemEventType[] = [\n        \"switchedTo\",\n        \"switchedAway\",\n      ];\n\n      for (const event of threadListItemEvents) {\n        const unsubscribe = runtime.unstable_on(event, () => {\n          emit(`threadListItem.${event}`, {\n            threadId: runtime.getState()!.id,\n          });\n        });\n        unsubscribers.push(unsubscribe);\n      }\n\n      return () => {\n        for (const unsub of unsubscribers) unsub();\n      };\n    }, [runtime, emit]);\n\n    return {\n      getState: () => state,\n      switchTo: runtime.switchTo,\n      rename: runtime.rename,\n      updateCustom: runtime.updateCustom,\n      archive: runtime.archive,\n      unarchive: runtime.unarchive,\n      delete: runtime.delete,\n      generateTitle: runtime.generateTitle,\n      initialize: runtime.initialize,\n      detach: runtime.detach,\n      __internal_getRuntime: () => runtime,\n    };\n  },\n);\n"],"mappings":";;;;AASA,MAAa,uBAAuB,UACjC,EACC,cAGoC;CACpC,MAAM,QAAQ,gBAAgB,OAAO;CACrC,MAAM,OAAO,iBAAiB;CAG9B,gBAAgB;EACd,MAAM,gBAA+B,CAAC;EAQtC,KAAK,MAAM,SAAS,CAJlB,cACA,cAGqC,GAAG;GACxC,MAAM,cAAc,QAAQ,YAAY,aAAa;IACnD,KAAK,kBAAkB,SAAS,EAC9B,UAAU,QAAQ,SAAS,EAAG,GAChC,CAAC;GACH,CAAC;GACD,cAAc,KAAK,WAAW;EAChC;EAEA,aAAa;GACX,KAAK,MAAM,SAAS,eAAe,MAAM;EAC3C;CACF,GAAG,CAAC,SAAS,IAAI,CAAC;CAElB,OAAO;EACL,gBAAgB;EAChB,UAAU,QAAQ;EAClB,QAAQ,QAAQ;EAChB,cAAc,QAAQ;EACtB,SAAS,QAAQ;EACjB,WAAW,QAAQ;EACnB,QAAQ,QAAQ;EAChB,eAAe,QAAQ;EACvB,YAAY,QAAQ;EACpB,QAAQ,QAAQ;EAChB,6BAA6B;CAC/B;AACF,CACF"}

package/dist/store/scopes/thread-list-item.d.ts

@@ -16,6 +16,7 @@ type ThreadListItemMethods = {
     unarchive?: boolean;
   }): void;
   rename(newTitle: string): void;
+  updateCustom(custom: Record<string, unknown> | undefined): void;
   archive(): void;
   unarchive(): void;
   delete(): void;

package/dist/store/scopes/thread-list-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread-list-item.d.ts","names":[],"sources":["../../../src/store/scopes/thread-list-item.ts"],"mappings":";;;;KAGY,mBAAA;EAAA,SACD,EAAA;EAAA,SACA,QAAA;EAAA,SACA,UAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA,EAAQ,oBAAA;EAAA,SACR,MAAA,GAAS,MAAM;AAAA;AAAA,KAGd,qBAAA;EACV,QAAA,IAAY,mBAAA;EACZ,QAAA,CAAS,OAAA;IAAY,SAAA;EAAA;EACrB,MAAA,CAAO,QAAA;EACP,OAAA;EACA,SAAA;EACA,MAAA;EACA,aAAA;EACA,UAAA,IAAc,OAAA;IAAU,QAAA;IAAkB,UAAA;EAAA;EAC1C,MAAA;EACA,qBAAA,KAA0B,qBAAA;AAAA;AAAA,KAGhB,kBAAA;EACV,MAAA;EACA,KAAA;IACM,IAAA;EAAA;IACA,IAAA;IAAY,EAAA;EAAA;IACZ,IAAA;IAAe,KAAA;IAAe,QAAA;EAAA;AAAA;AAAA,KAG1B,oBAAA;EAZV;;;;AAC+C;EAiB/C,2BAAA;IAA+B,QAAA;EAAA;EAdH;;;;;EAoB5B,6BAAA;IAAiC,QAAA;EAAA;AAAA;AAAA,KAGvB,0BAAA;EACV,OAAA,EAAS,qBAAA;EACT,IAAA,EAAM,kBAAA;EACN,MAAA,EAAQ,oBAAA;AAAA"}
+{"version":3,"file":"thread-list-item.d.ts","names":[],"sources":["../../../src/store/scopes/thread-list-item.ts"],"mappings":";;;;KAGY,mBAAA;EAAA,SACD,EAAA;EAAA,SACA,QAAA;EAAA,SACA,UAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA,EAAQ,oBAAA;EAAA,SACR,MAAA,GAAS,MAAM;AAAA;AAAA,KAGd,qBAAA;EACV,QAAA,IAAY,mBAAA;EACZ,QAAA,CAAS,OAAA;IAAY,SAAA;EAAA;EACrB,MAAA,CAAO,QAAA;EACP,YAAA,CAAa,MAAA,EAAQ,MAAA;EACrB,OAAA;EACA,SAAA;EACA,MAAA;EACA,aAAA;EACA,UAAA,IAAc,OAAA;IAAU,QAAA;IAAkB,UAAA;EAAA;EAC1C,MAAA;EACA,qBAAA,KAA0B,qBAAA;AAAA;AAAA,KAGhB,kBAAA;EACV,MAAA;EACA,KAAA;IACM,IAAA;EAAA;IACA,IAAA;IAAY,EAAA;EAAA;IACZ,IAAA;IAAe,KAAA;IAAe,QAAA;EAAA;AAAA;AAAA,KAG1B,oBAAA;EAbI;;;;;EAmBd,2BAAA;IAA+B,QAAA;EAAA;EAdrB;;;;;EAoBV,6BAAA;IAAiC,QAAA;EAAA;AAAA;AAAA,KAGvB,0BAAA;EACV,OAAA,EAAS,qBAAA;EACT,IAAA,EAAM,kBAAA;EACN,MAAA,EAAQ,oBAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.2.9",
+  "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.19",
+    "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,11 +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 { hitl } from "./model-context/hitl";
+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

@@ -1,13 +1,101 @@
-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 } 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("hitl throws at runtime — it must be stripped by the compiler, never called", () => {
-    expect(() => hitl()).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

@@ -1,8 +1,12 @@
-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`)
+ * {@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.
@@ -13,7 +17,21 @@ import type { Toolkit, ToolkitDeclaration } from "./toolbox";
  * outside a `"use generative"` file — which would ship a backend `execute` to the
  * client. So it throws instead of silently leaking.
  */
-export function defineToolkit(_declaration: ToolkitDeclaration): Toolkit {
+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 " +

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

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