ai-tool-set 0.0.1 → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,366 @@
+<div align='center'>
+
 # ai-tool-set
 
-> **Work in progress** — this package is under active development and not yet ready for use.
+<p align="center">AI SDK: Manage tool activation with type-safe, chainable tool sets</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/ai-tool-set" alt="ai-tool-set"><img src="https://img.shields.io/npm/dt/ai-tool-set?label=ai-tool-set"></a> <a href="https://github.com/zirkelc/ai-tool-set/actions/workflows/ci.yml" alt="CI"><img src="https://img.shields.io/github/actions/workflow/status/zirkelc/ai-tool-set/ci.yml?branch=main"></a>
+</p>
+
+</div>
+
+This library provides an immutable and type-safe API to manage [`activeTools`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#active-tools) for [`generateText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text) and [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text) in the AI SDK.
+
+### Why?
+
+The AI SDK provides an `activeTools` parameter to control which tools the model can use at any given time. However, managing tool activation becomes complex when you need to:
+
+- **Statically activate/deactivate tools**: Some tools should be inactive by default and only available after being explicitly activated
+- **Dynamically infer tool activation**: Some tools should be activated based on runtime context like the conversation history
+
+This library wraps standard AI SDK `tool()` definitions with chainable activation methods and resolves `tools` and `activeTools` for any AI SDK function.
+
+### Installation
+
+```bash
+npm install ai-tool-set
+```
+
+## Usage
+
+### Creating a Tool Set
+
+Pass a plain record of AI SDK `tool()` definitions to `createToolSet()`. All tools are active by default.
+
+```typescript
+import { tool } from 'ai';
+import { z } from 'zod';
+import { createToolSet } from 'ai-tool-set';
+
+const search = tool({
+  description: 'Search for products',
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => searchProducts(query),
+});
+
+const list_orders = tool({
+  description: 'List orders for a customer',
+  inputSchema: z.object({ customerId: z.string() }),
+  execute: async ({ customerId }) => listOrders(customerId),
+});
+
+const cancel_order = tool({
+  description: 'Cancel an order',
+  inputSchema: z.object({ orderId: z.string() }),
+  execute: async ({ orderId }) => cancelOrder(orderId),
+});
+
+const toolSet = createToolSet({ search, list_orders, cancel_order });
+```
+
+### Use with `generateText` / `streamText`
+
+The tool set exposes `tools` and `activeTools` as properties that can be used directly:
+
+```typescript
+import { generateText } from 'ai';
+
+const { tools, activeTools } = toolSet;
+
+const result = await generateText({
+  model,
+  tools,
+  activeTools,
+  // Or spread tool set directly:
+  // ...toolSet,
+  prompt: 'Hello',
+});
+```
+
+### Activate and Deactivate Tools
+
+Use `.activate()` and `.deactivate()` to statically control which tools are available:
+
+```typescript
+const { tools, activeTools } = toolSet
+  .deactivate(['cancel_order'])
+  .activate(['list_orders']);
+
+const result = await generateText({
+  model,
+  tools,
+  activeTools,
+  prompt: 'Show me my orders',
+});
+```
+
+### Conditional Activation
+
+Use `.activateWhen()` and `.deactivateWhen()` to conditionally control tools based on messages and context. The predicate receives an `ActivationInput` with `messages` and `context`.
+
+```typescript
+const { tools, activeTools } = toolSet
+  .activateWhen('cancel_order', ({ messages }) =>
+    messages.some((m) =>
+      m.parts.some(
+        (p) =>
+          p.type === 'tool-list_orders' &&
+          p.state === 'output-available' &&
+          p.output.orders?.some((order) => order.status !== 'fulfilled'),
+      ),
+    ),
+  );
+
+const result = await generateText({
+  model,
+  tools,
+  activeTools,
+  prompt: 'Cancel my order #1001',
+});
+```
+
+Use `.inferTools()` to evaluate predicates with the current messages and context:
+
+```typescript
+const messages = [
+  {
+    role: 'user',
+    parts: [{ type: 'text', text: 'Show me my orders' }],
+  },
+  {
+    role: 'assistant',
+    parts: [{
+      type: 'tool-list_orders',
+      state: 'output-available',
+      toolCallId: 'call-1',
+      input: { customerId: 'cust-123' },
+      output: {
+        orders: [
+          { orderId: '1000', status: 'fulfilled' },
+          { orderId: '1001', status: 'pending' },
+        ],
+      },
+    }],
+  },
+];
+
+// cancel_order is now active because list_orders returned unfulfilled orders
+const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+
+const result = await generateText({ model, tools, activeTools, messages });
+```
+
+You can also activate multiple tools at once:
+
+```typescript
+const toolSet = createToolSet({ search, list_orders, cancel_order })
+  .activateWhen({
+    list_orders: ({ context }) => context.isAuthenticated,
+    cancel_order: ({ messages }) => hasUnfulfilledOrders(messages),
+  });
+```
+
+### Last-Call Wins
+
+Each method appends to an internal list. For each tool, the **last entry** determines its state. This makes ordering explicit and predictable:
+
+```typescript
+const toolSet = createToolSet({ search, list_orders, cancel_order })
+  .activate(['cancel_order'])                    // cancel_order: activated
+  .deactivate(['cancel_order'])                  // cancel_order: deactivated
+  .activateWhen('cancel_order', ({ messages }) =>  // cancel_order: conditional activation
+    hasUnfulfilledOrders(messages),
+  );
+```
+
+### Immutable
+
+All methods return new tool set instances. The original is never modified:
+
+```typescript
+const base = createToolSet({ search, list_orders, cancel_order });
+const withoutCancel = base.deactivate(['cancel_order']);
+const withCancel = withoutCancel.activate(['cancel_order']);
+
+base.activeTools;          // ['search', 'list_orders', 'cancel_order']
+withoutCancel.activeTools; // ['search', 'list_orders']
+withCancel.activeTools;    // ['search', 'list_orders', 'cancel_order']
+```
+
+### Typed UI Tool Set
+
+Use `InferUIToolSet` to get fully typed UI messages from your tool set:
+
+```typescript
+import type { UIMessage } from 'ai';
+import type { InferUIToolSet } from 'ai-tool-set';
+
+const tools = { search, list_orders, cancel_order };
+const toolSet = createToolSet(tools);
+
+// From the tools record
+type MyToolSet = InferUIToolSet<typeof tools>;
+
+// Or from the ToolSet instance
+type MyToolSet = InferUIToolSet<typeof toolSet>;
+
+// Use MyToolSet in your UIMessage type for type-safe access to tool invocation parts:
+type MyUIMessage = UIMessage<unknown, any, MyToolSet>;
+```
+
+### Custom UIMessage
+
+If you already have a custom `UIMessage` type, you can pass it as `MESSAGE` generic to `createToolSet()` and it will be used in predicates and `inferTools`:
+
+```typescript
+import { myTools } from './my-tools.js';
+import { MyUIMessage } from './my-ui-message.js';
+
+const toolSet = createToolSet<typeof myTools, MyUIMessage>(myTools)
+  .activateWhen('cancel_order', ({ messages }) => hasUnfulfilledOrders(messages));
+  //                               ~~~~~~~~
+  // Messages are now typed as MyUIMessage, so you get type safety and autocompletion in predicates!
+
+const { tools, activeTools } = toolSet.inferTools({ messages });
+```
+
+### Custom Context
+
+Pass a `CONTEXT` generic to `createToolSet()` to type the `context` field in predicates and `inferTools`:
+
+```typescript
+import { myTools } from './my-tools.js';
+import { MyUIMessage } from './my-ui-message.js';
+
+type MyContext = { userId: string; isAdmin: boolean };
+
+const toolSet = createToolSet<typeof myTools, MyUIMessage, MyContext>(myTools)
+  .activateWhen('cancel_order', ({ context }) => context.isAdmin);
+  //                               ~~~~~~~~
+  // Context is now typed as MyContext, so you get type safety and autocompletion
+
+const { tools, activeTools } = toolSet.inferTools({
+  messages,
+  context: { isAdmin: true },
+});
+```
+
+## API
+
+## `createToolSet(tools)`
+
+- `tools`, a plain `Record<string, Tool>` of AI SDK tools
+
+Returns a `ToolSet` instance. All tools are active by default.
+
+```ts
+const toolSet = createToolSet({ search, list_orders, cancel_order });
+```
+
+#### `.tools`
+
+All tools as a standard AI SDK tool record, regardless of activation state.
+
+```ts
+const { tools } = toolSet;
+```
+
+#### `.activeTools`
+
+Resolved array of active tool names based on the current state.
+
+```ts
+const { activeTools } = toolSet;
+```
+
+#### `.activate(names)`
+
+Statically activate tools by name. Returns a new `ToolSet`.
+
+```ts
+toolSet.activate(['cancel_order']);
+```
+
+#### `.deactivate(names)`
+
+Statically deactivate tools by name. Returns a new `ToolSet`.
+
+```ts
+toolSet.deactivate(['search']);
+```
+
+#### `.activateWhen(name, predicate)` / `.activateWhen(predicates)`
+
+Conditionally activate tools. The predicate receives `{ messages, context }` and returns `true` to activate.
+
+```ts
+toolSet.activateWhen('cancel_order', ({ messages }) => hasOrders(messages));
+
+toolSet.activateWhen({
+  cancel_order: ({ messages }) => hasOrders(messages),
+  list_orders: ({ context }) => context.isAuthenticated,
+});
+```
+
+#### `.deactivateWhen(name, predicate)` / `.deactivateWhen(predicates)`
+
+Conditionally deactivate tools. The predicate receives `{ messages, context }` and returns `true` to deactivate.
+
+```ts
+toolSet.deactivateWhen('search', ({ messages }) => messages.length > 10);
+```
+
+#### `.inferTools(input)`
+
+Evaluate all predicates with the provided messages and context. Returns a new `ToolSet`.
+
+- `input`:
+  - `messages`, the current conversation messages
+  - `context`, arbitrary values passed to predicates
+
+```ts
+toolSet.inferTools({ messages, context: {} });
+```
+
+## Types
+
+### `ActivationInput`
+
+Input passed to activation predicates. Generic over `MESSAGE` and `CONTEXT`:
+
+```ts
+import type { ActivationInput } from 'ai-tool-set';
+
+type MyInput = ActivationInput<MyUIMessage, { isAdmin: boolean }>;
+// { messages: Array<MyUIMessage>; context: { isAdmin: boolean } }
+```
+
+### `InferToolSet`
+
+Extract the raw tool record from a tool record or `ToolSet` instance:
+
+```ts
+import type { InferToolSet } from 'ai-tool-set';
+
+type Tools = InferToolSet<typeof toolSet>;
+// { search: Tool<...>, list_orders: Tool<...>, cancel_order: Tool<...> }
+```
+
+### `InferUIToolSet`
+
+Derive typed UI tool parts from a tool record or `ToolSet` instance. Use with `UIMessage` for type-safe access to tool invocation parts:
+
+```ts
+import type { UIMessage } from 'ai';
+import type { InferUIToolSet } from 'ai-tool-set';
+
+type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof toolSet>>;
+
+// Parts are now typed per tool:
+// message.parts[0].type === 'tool-search'
+// message.parts[0].output // typed as search tool's return type
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,89 @@
+import { InferUITool, ModelMessage, Tool, UIMessage } from "ai";
+
+//#region src/tool-set.d.ts
+/** A plain record of tools. */
+type ToolRecord = Record<string, Tool>;
+/** Supported message types for activation callbacks. */
+type MessageType = UIMessage | ModelMessage;
+/** The fully-typed UIMessage for a given tool record. */
+type InferUIMessage<TOOLS extends ToolRecord> = UIMessage<unknown, any, InferUIToolSet<TOOLS>>;
+/** Infer the raw tool record from a ToolRecord or ToolSet instance. */
+type InferToolSet<T extends ToolRecord | ToolSet<any>> = T extends ToolSet<infer TOOLS, any, any> ? TOOLS : T;
+/** Infer the UI tool types from a tool record or ToolSet instance. */
+type InferUIToolSet<T extends ToolRecord | ToolSet<any>> = { [K in keyof InferToolSet<T> & string]: InferUITool<InferToolSet<T>[K]> };
+/**
+ * Input passed to activation predicates.
+ * Use `ActivationInput<MyMsg>` to get per-tool narrowing in callbacks.
+ */
+type ActivationInput<MESSAGE extends MessageType = UIMessage, CONTEXT extends Record<string, unknown> = Record<string, unknown>> = {
+  messages: Array<MESSAGE>;
+  context: CONTEXT;
+};
+/** Activation predicate — returns true if tool should be active. */
+type ActivationPredicate<MESSAGE extends MessageType = UIMessage, CONTEXT extends Record<string, unknown> = Record<string, unknown>> = (input: ActivationInput<MESSAGE, CONTEXT>) => boolean;
+type ActivationEntry = {
+  toolName: string;
+  resolve: (input: ActivationInput<any, any>) => boolean;
+};
+type ToolSetState<TOOLS extends ToolRecord, MESSAGE extends MessageType, CONTEXT extends Record<string, unknown>> = {
+  tools: TOOLS;
+  entries: Array<ActivationEntry>;
+  input: ActivationInput<MESSAGE, CONTEXT>;
+};
+/**
+ * An immutable tool set with chainable activation methods.
+ *
+ * Resolution follows "last-call wins": each method appends an entry,
+ * and the last entry for each tool determines its state.
+ * Default (no entry) is active.
+ *
+ * @example
+ * ```typescript
+ * const toolSet = createToolSet({ search, list_orders, cancel_order })
+ *   .deactivate(['cancel_order'])
+ *   .activateWhen('cancel_order', ({ messages }) => hasUnfulfilledOrders(messages));
+ *
+ * const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+ * ```
+ */
+declare class ToolSet<TOOLS extends ToolRecord, MESSAGE extends MessageType = UIMessage, CONTEXT extends Record<string, unknown> = Record<string, unknown>, ACTIVATED extends string = never, DEACTIVATED extends string = never> {
+  #private;
+  /** All tools as a standard AI SDK tool record. */
+  readonly tools: TOOLS;
+  /** Resolved list of active tool names based on current state. */
+  readonly activeTools: Array<keyof TOOLS & string>;
+  constructor(state: ToolSetState<TOOLS, MESSAGE, CONTEXT>);
+  /** Statically activate tools by name. */
+  activate<NAMES extends (Exclude<keyof TOOLS & string, ACTIVATED> | DEACTIVATED) & string>(names: Array<NAMES>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED | NAMES, DEACTIVATED>;
+  /** Statically deactivate tools by name. */
+  deactivate<NAMES extends ((keyof TOOLS & string) | ACTIVATED) & string>(names: Array<NAMES>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED | NAMES>;
+  /**
+   * Conditionally activate a tool — becomes active when predicate returns true.
+   *
+   * - `.activateWhen('tool_name', (input) => ...)`
+   * - `.activateWhen({ tool_name: (input) => ... })`
+   */
+  activateWhen<NAME extends keyof TOOLS & string>(name: NAME, predicate: ActivationPredicate<MESSAGE, CONTEXT>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED>;
+  activateWhen(predicates: Partial<Record<keyof TOOLS & string, ActivationPredicate<MESSAGE, CONTEXT>>>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED>;
+  /**
+   * Conditionally deactivate a tool — becomes inactive when predicate returns true.
+   * Internally wraps with negation so resolve returns true (active) when pred is false.
+   *
+   * - `.deactivateWhen('tool_name', (input) => ...)`
+   * - `.deactivateWhen({ tool_name: (input) => ... })`
+   */
+  deactivateWhen<NAME extends keyof TOOLS & string>(name: NAME, predicate: ActivationPredicate<MESSAGE, CONTEXT>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED>;
+  deactivateWhen(predicates: Partial<Record<keyof TOOLS & string, ActivationPredicate<MESSAGE, CONTEXT>>>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED>;
+  /** Provide messages and context for predicate-based tools. Returns a new ToolSet. */
+  inferTools(input: ActivationInput<MESSAGE, CONTEXT>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED>;
+}
+/**
+ * Create a chainable, immutable tool set.
+ *
+ * @typeParam TOOLS — inferred from the argument
+ * @typeParam MESSAGE — defaults to the fully-typed UIMessage derived from TOOLS
+ * @typeParam CONTEXT — defaults to Record<string, unknown>
+ */
+declare const createToolSet: <const TOOLS extends ToolRecord, MESSAGE extends MessageType = InferUIMessage<TOOLS>, CONTEXT extends Record<string, unknown> = Record<string, unknown>>(tools: TOOLS) => ToolSet<TOOLS, MESSAGE, CONTEXT>;
+//#endregion
+export { type ActivationInput, type InferToolSet, type InferUIToolSet, createToolSet };

package/dist/index.mjs

@@ -0,0 +1,108 @@
+//#region src/tool-set.ts
+const toEntries = (nameOrPredicates, predicate) => {
+	if (typeof nameOrPredicates === "string") return [{
+		toolName: nameOrPredicates,
+		resolve: predicate
+	}];
+	return Object.entries(nameOrPredicates).filter(([, pred]) => pred != null).map(([name, pred]) => ({
+		toolName: name,
+		resolve: pred
+	}));
+};
+/**
+* An immutable tool set with chainable activation methods.
+*
+* Resolution follows "last-call wins": each method appends an entry,
+* and the last entry for each tool determines its state.
+* Default (no entry) is active.
+*
+* @example
+* ```typescript
+* const toolSet = createToolSet({ search, list_orders, cancel_order })
+*   .deactivate(['cancel_order'])
+*   .activateWhen('cancel_order', ({ messages }) => hasUnfulfilledOrders(messages));
+*
+* const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+* ```
+*/
+var ToolSet = class ToolSet {
+	#state;
+	/** All tools as a standard AI SDK tool record. */
+	tools;
+	/** Resolved list of active tool names based on current state. */
+	activeTools;
+	constructor(state) {
+		this.#state = state;
+		this.tools = state.tools;
+		this.activeTools = Object.keys(state.tools).filter((name) => {
+			const lastEntry = state.entries.findLast((e) => e.toolName === name);
+			if (!lastEntry) return true;
+			return lastEntry.resolve(state.input);
+		});
+	}
+	/** Statically activate tools by name. */
+	activate(names) {
+		const newEntries = names.map((name) => ({
+			toolName: name,
+			resolve: () => true
+		}));
+		return new ToolSet({
+			...this.#state,
+			entries: [...this.#state.entries, ...newEntries]
+		});
+	}
+	/** Statically deactivate tools by name. */
+	deactivate(names) {
+		const newEntries = names.map((name) => ({
+			toolName: name,
+			resolve: () => false
+		}));
+		return new ToolSet({
+			...this.#state,
+			entries: [...this.#state.entries, ...newEntries]
+		});
+	}
+	activateWhen(nameOrPredicates, predicate) {
+		const newEntries = toEntries(nameOrPredicates, predicate);
+		return new ToolSet({
+			...this.#state,
+			entries: [...this.#state.entries, ...newEntries]
+		});
+	}
+	deactivateWhen(nameOrPredicates, predicate) {
+		const newEntries = toEntries(nameOrPredicates, predicate).map((e) => ({
+			...e,
+			resolve: (input) => !e.resolve(input)
+		}));
+		return new ToolSet({
+			...this.#state,
+			entries: [...this.#state.entries, ...newEntries]
+		});
+	}
+	/** Provide messages and context for predicate-based tools. Returns a new ToolSet. */
+	inferTools(input) {
+		return new ToolSet({
+			...this.#state,
+			input
+		});
+	}
+};
+/**
+* Create a chainable, immutable tool set.
+*
+* @typeParam TOOLS — inferred from the argument
+* @typeParam MESSAGE — defaults to the fully-typed UIMessage derived from TOOLS
+* @typeParam CONTEXT — defaults to Record<string, unknown>
+*/
+const createToolSet = (tools) => {
+	return new ToolSet({
+		tools,
+		entries: [],
+		input: {
+			messages: [],
+			context: {}
+		}
+	});
+};
+//#endregion
+export { createToolSet };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-tool-set",
-  "version": "0.0.1",
+  "version": "0.1.0-alpha.1",
   "description": "Tool set utilities for the Vercel AI SDK",
   "keywords": [],
   "license": "MIT",
@@ -21,21 +21,24 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@total-typescript/tsconfig": "^1.0.4",
-    "@types/node": "^25.2.3",
-    "ai": "^6.0.141",
+    "@types/node": "^25.5.2",
+    "ai": "^6.0.153",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
-    "oxfmt": "^0.30.0",
-    "oxlint": "^1.45.0",
-    "oxlint-tsgolint": "^0.11.5",
-    "pkg-pr-new": "^0.0.63",
-    "publint": "^0.3.17",
-    "tsdown": "^0.20.3",
+    "lint-staged": "^16.4.0",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "oxlint-tsgolint": "^0.20.0",
+    "pkg-pr-new": "^0.0.66",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.7",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.3",
     "zod": "^4.3.6"
   },
+  "peerDependencies": {
+    "ai": "^6.0.141"
+  },
   "lint-staged": {
     "*.{js,ts,tsx,jsx}": [
       "pnpm lint",
@@ -45,9 +48,6 @@
       "pnpm format"
     ]
   },
-  "peerDependencies": {
-    "ai": "^6.0.141"
-  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest",