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

package/README.md

@@ -15,10 +15,10 @@ This library provides an immutable and type-safe API to manage [`activeTools`](h
 
 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:
 
-- **Activate/deactivate tools**: Some tools should be inactive by default and should only be available after being explicitily activated
+- **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 activation metadata and provides a chainable API to resolve `tools` and `activeTools` for any AI SDK function.
+This library wraps standard AI SDK `tool()` definitions with chainable activation methods and resolves `tools` and `activeTools` for any AI SDK function.
 
 ### Installation
 
@@ -30,53 +30,35 @@ npm install ai-tool-set
 
 ### Creating a Tool Set
 
-Define your tools using the standard AI SDK `tool()` function and wrap them with `createToolSet()`. Each entry is either a plain `Tool` (always active) or a `{ tool, active }` object with explicit activation control.
+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 toolSet = createToolSet({
-  // Plain tool — always active
-  search: tool({
-    description: 'Search for products',
-    inputSchema: z.object({ query: z.string() }),
-    execute: async ({ query }) => searchProducts(query),
-  }),
-
-  // Explicitly inactive — must be activated manually
-  list_orders: {
-    tool: tool({
-      description: 'List orders for a customer',
-      inputSchema: z.object({ customerId: z.string() }),
-      execute: async ({ customerId }) => listOrders(customerId),
-    }),
-    active: false,
-  },
+const search = tool({
+  description: 'Search for products',
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => searchProducts(query),
+});
 
-  // Callback-based — activated dynamically based on messages
-  // Only available when list_orders was called and returned unfulfilled orders
-  cancel_order: {
-    tool: tool({
-      description: 'Cancel an order',
-      inputSchema: z.object({ orderId: z.string() }),
-      execute: async ({ orderId }) => cancelOrder(orderId),
-    }),
-    active: ({ 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 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` / `ToolLoopAgent`
+### Use with `generateText` / `streamText`
 
 The tool set exposes `tools` and `activeTools` as properties that can be used directly:
 
@@ -97,13 +79,12 @@ const result = await generateText({
 
 ### Activate and Deactivate Tools
 
-Use `activateTools()` and `deactivateTools()` to override static activation. Both methods are type-safe and only accept valid tool names:
+Use `.activate()` and `.deactivate()` to statically control which tools are available:
 
 ```typescript
-// Active tools will include 'list_orders' and exclude 'search'
 const { tools, activeTools } = toolSet
-  .activateTools(['list_orders'])
-  .deactivateTools(['search']);
+  .deactivate(['cancel_order'])
+  .activate(['list_orders']);
 
 const result = await generateText({
   model,
@@ -113,9 +94,32 @@ const result = await generateText({
 });
 ```
 
-### Infer Active Tools
+### 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 callback-based tools against the current conversation context:
+Use `.inferTools()` to evaluate predicates with the current messages and context:
 
 ```typescript
 const messages = [
@@ -125,104 +129,137 @@ const messages = [
   },
   {
     role: 'assistant',
-    parts: [
-      {
-        type: 'tool-list_orders',
-        state: 'output-available',
-        toolCallId: 'call-1',
-        input: { customerId: 'cust-123' },
-        output: {
-          orders: [
-            { orderId: 'order-1', status: 'fulfilled' },
-            { orderId: 'order-2', status: 'pending' },
-          ],
-        },
+    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' },
+        ],
       },
-    ],
+    }],
   },
 ];
 
-// Active tools will include 'cancel_order' based on the messages context
-const { tools, activeTools } = toolSet.inferTools({ messages });
+// 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,
-});
+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, allowing you to maintain different tool states across different calls or steps without side effects:
+All methods return new tool set instances. The original is never modified:
 
 ```typescript
-const toolSet1 = createToolSet({ ... });
-const toolSet2 = toolSet1.activateTools(['list_orders']);
-const toolSet3 = toolSet2.deactivateTools(['search', 'list_orders']);
+const base = createToolSet({ search, list_orders, cancel_order });
+const withoutCancel = base.deactivate(['cancel_order']);
+const withCancel = withoutCancel.activate(['cancel_order']);
 
-toolSet1.activeTools; // ['search']
-toolSet2.activeTools; // ['search', 'list_orders']
-toolSet3.activeTools; // []
+base.activeTools;          // ['search', 'list_orders', 'cancel_order']
+withoutCancel.activeTools; // ['search', 'list_orders']
+withCancel.activeTools;    // ['search', 'list_orders', 'cancel_order']
 ```
 
-### Typed UI Messages
+### 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, ToolSetConfig } from 'ai-tool-set';
-
-const tools = {
-  search: tool({ ... }),
-  list_orders: {
-    tool: tool({ ... }),
-    active: false,
-  },
-  cancel_order: {
-    tool: tool({ ... }),
-    active: ({ messages }) => /* callback logic */,
-  },
-} satisfies ToolSetConfig;
+import type { InferUIToolSet } from 'ai-tool-set';
 
+const tools = { search, list_orders, cancel_order };
 const toolSet = createToolSet(tools);
 
-// Use tool set config
-type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof tools>>;
+// From the tools record
+type MyToolSet = InferUIToolSet<typeof tools>;
 
-// Or use ToolSet instance
-type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof toolSet>>;
+// 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(config)`
+## `createToolSet(tools)`
 
-- `config`, a record where each key maps to either:
-  - a plain AI SDK `Tool` (always active), or
-  - a `{ tool, active }` object with activation control (`active` can be `boolean` or `(context) => boolean`)
+- `tools`, a plain `Record<string, Tool>` of AI SDK tools
 
-Returns a `ToolSet` instance.
+Returns a `ToolSet` instance. All tools are active by default.
 
 ```ts
-const toolSet = createToolSet({
-  search: tool({ ... }),
-  list_orders: {
-    tool: tool({ ... }),
-    active: false,
-  },
-  cancel_order: {
-    tool: tool({ ... }),
-    active: ({ messages }) => /* callback logic */,
-  },
-});
+const toolSet = createToolSet({ search, list_orders, cancel_order });
 ```
 
 #### `.tools`
 
-All tools as a standard AI SDK tool record (`Record<string, Tool>`), regardless of activation state.
+All tools as a standard AI SDK tool record, regardless of activation state.
 
 ```ts
 const { tools } = toolSet;
@@ -230,81 +267,93 @@ const { tools } = toolSet;
 
 #### `.activeTools`
 
-Resolved array of active tool names based on the current state. Accounts for static activation, explicit overrides, and callback evaluation.
+Resolved array of active tool names based on the current state.
 
 ```ts
 const { activeTools } = toolSet;
 ```
 
-#### `.activateTools(names)`
+#### `.activate(names)`
 
-Activate statically inactive tools by name. Returns a new `ToolSet` instance. Type-safe — only accepts names of tools with `active: false` or tools previously deactivated in the chain.
+Statically activate tools by name. Returns a new `ToolSet`.
 
 ```ts
-const toolSetWithOrders = toolSet.activateTools(['list_orders']);
+toolSet.activate(['cancel_order']);
 ```
 
-#### `.deactivateTools(names)`
+#### `.deactivate(names)`
 
-Deactivate statically active tools by name. Returns a new `ToolSet` instance. Type-safe — only accepts names of plain tools, tools with `active: true`, or tools previously activated in the chain.
+Statically deactivate tools by name. Returns a new `ToolSet`.
 
 ```ts
-const toolSetWithoutSearch = toolSet.deactivateTools(['search']);
+toolSet.deactivate(['search']);
 ```
 
-#### `.inferTools(context)`
+#### `.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,
+});
+```
 
-Evaluate callback-based tools against the provided context. Returns a new `ToolSet` instance.
+#### `.deactivateWhen(name, predicate)` / `.deactivateWhen(predicates)`
 
-- `context`:
-  - `messages`, `Array<UIMessage>`, the current conversation messages used by activation callbacks to determine tool availability
+Conditionally deactivate tools. The predicate receives `{ messages, context }` and returns `true` to deactivate.
 
 ```ts
-const toolSetInferred = toolSet.inferTools({ messages });
+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
 
-### `ToolSetConfig`
+### `ActivationInput`
 
-The config record type accepted by `createToolSet()`. Each key maps to a plain `Tool` or a `{ tool, active }` object. Use with `satisfies` to get contextual typing for activation callbacks:
+Input passed to activation predicates. Generic over `MESSAGE` and `CONTEXT`:
 
 ```ts
-import { type ToolSetConfig } from 'ai-tool-set';
+import type { ActivationInput } from 'ai-tool-set';
 
-const tools = {
-  search: tool({ ... }),
-  list_orders: { tool: tool({ ... }), active: false },
-  cancel_order: { tool: tool({ ... }), active: ({ messages }) => /* ... */ },
-} satisfies ToolSetConfig;
+type MyInput = ActivationInput<MyUIMessage, { isAdmin: boolean }>;
+// { messages: Array<MyUIMessage>; context: { isAdmin: boolean } }
 ```
 
 ### `InferToolSet`
 
-Extract a `Record<string, Tool>` from a `ToolSetConfig` object or `ToolSet` instance, stripping activation metadata:
+Extract the raw tool record from a tool record or `ToolSet` instance:
 
 ```ts
-import { type InferToolSet } from 'ai-tool-set';
+import type { InferToolSet } from 'ai-tool-set';
 
-type Tools = InferToolSet<typeof tools>;
-// { search: Tool<...>, list_orders: Tool<...>, cancel_order: Tool<...> }
-
-// Also works with a ToolSet instance
-const toolSet = createToolSet(tools);
 type Tools = InferToolSet<typeof toolSet>;
+// { search: Tool<...>, list_orders: Tool<...>, cancel_order: Tool<...> }
 ```
 
 ### `InferUIToolSet`
 
-Derive typed UI tool parts from a `ToolSetConfig` object or `ToolSet` instance. Use with `UIMessage` to get type-safe access to tool invocation parts in the conversation:
+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 tools>>;
+import type { InferUIToolSet } from 'ai-tool-set';
 
-// Also works with a ToolSet instance
 type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof toolSet>>;
 
 // Parts are now typed per tool:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-tool-set",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Tool set utilities for the Vercel AI SDK",
   "keywords": [],
   "license": "MIT",