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

package/README.md

@@ -9,16 +9,16 @@
 
 </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.
+This library provides a 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:
 
-- **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
+const tools = {
   search: tool({
     description: 'Search for products',
     inputSchema: z.object({ query: z.string() }),
     execute: async ({ query }) => searchProducts(query),
   }),
+  list_orders: tool({
+    description: 'List orders for a customer',
+    inputSchema: z.object({ customerId: z.string() }),
+    execute: async ({ customerId }) => listOrders(customerId),
+  }),
+  cancel_order: tool({
+    description: 'Cancel an order',
+    inputSchema: z.object({ orderId: z.string() }),
+    execute: async ({ orderId }) => cancelOrder(orderId),
+  }),
+};
 
-  // 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,
-  },
-
-  // 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 toolSet = createToolSet({ tools });
 ```
 
-### 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,10 @@ 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']);
+const { tools, activeTools } = toolSet.deactivate(['cancel_order']).activate(['list_orders']);
 
 const result = await generateText({
   model,
@@ -113,9 +92,24 @@ 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 toolSet = createToolSet({ tools }).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'),
+    ),
+  ),
+);
+```
 
-Use `inferTools()` to evaluate callback-based tools against the current conversation context:
+Use `.inferTools()` to evaluate predicates with the current messages and context. It returns `{ tools, activeTools }` that can be spread directly into `generateText()`:
 
 ```typescript
 const messages = [
@@ -133,8 +127,8 @@ const messages = [
         input: { customerId: 'cust-123' },
         output: {
           orders: [
-            { orderId: 'order-1', status: 'fulfilled' },
-            { orderId: 'order-2', status: 'pending' },
+            { orderId: '1000', status: 'fulfilled' },
+            { orderId: '1001', status: 'pending' },
           ],
         },
       },
@@ -142,87 +136,168 @@ const messages = [
   },
 ];
 
-// 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({ tools }).activateWhen({
+  list_orders: ({ context }) => context.isAuthenticated,
+  cancel_order: ({ messages }) => hasUnfulfilledOrders(messages),
 });
 ```
 
-### Immutable
+### Last-Call Wins
 
-All methods return new tool set instances, allowing you to maintain different tool states across different calls or steps without side effects:
+Each method appends to an internal list. For each tool, the **last entry** determines its state. This makes ordering explicit and predictable:
 
 ```typescript
-const toolSet1 = createToolSet({ ... });
-const toolSet2 = toolSet1.activateTools(['list_orders']);
-const toolSet3 = toolSet2.deactivateTools(['search', 'list_orders']);
+const toolSet = createToolSet({ tools })
+  .activate(['cancel_order']) // cancel_order: activated
+  .deactivate(['cancel_order']) // cancel_order: deactivated
+  .activateWhen(
+    'cancel_order',
+    (
+      { messages }, // cancel_order: conditional activation
+    ) => hasUnfulfilledOrders(messages),
+  );
+```
+
+### Immutable vs Mutable
+
+By default, `createToolSet()` returns an **immutable** tool set, that means every method returns a new instance and the original is never modified. This is ideal when the tool set is created once in the global scope and shared across requests:
+
+```typescript
+// Global scope: created once, shared across requests
+const toolSet = createToolSet({ tools }).deactivate(['list_order', 'cancel_order']);
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  // Activate list_orders only for this request
+  // myToolSet !== toolSet, original toolSet is unchanged for next request
+  const myToolSet = toolSet.activate(['list_orders']);
+
+  const { tools, activeTools } = myToolSet;
+
+  const result = await generateText({
+    model,
+    tools,
+    activeTools,
+    messages,
+  });
+}
+```
 
-toolSet1.activeTools; // ['search']
-toolSet2.activeTools; // ['search', 'list_orders']
-toolSet3.activeTools; // []
+Pass `mutable: true` to get a **mutable** tool set where each method mutates in-place and returns `this` for chaining. This is useful when the tool set is created per-request in a local scope:
+
+```typescript
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  // Local scope: created and mutated per request
+  const toolSet = createToolSet({ tools, mutable: true }).deactivate(['list_order', 'cancel_order']);
+
+  // Activate list_orders only for this request
+  // myToolSet === toolSet, original toolSet is mutated for this request
+  const myToolSet = toolSet.activate(['list_orders']);
+
+  const { tools, activeTools } = myToolSet;
+
+  const result = await generateText({
+    model,
+    tools,
+    activeTools,
+    messages,
+  });
+}
 ```
 
-### 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';
+import type { InferUIToolSet } from 'ai-tool-set';
 
-const tools = {
-  search: tool({ ... }),
-  list_orders: {
-    tool: tool({ ... }),
-    active: false,
-  },
-  cancel_order: {
-    tool: tool({ ... }),
-    active: ({ messages }) => /* callback logic */,
-  },
-} satisfies ToolSetConfig;
+const tools = { search, list_orders, cancel_order };
+const toolSet = createToolSet({ tools });
 
-const toolSet = createToolSet(tools);
+// From the tools record
+type MyToolSet = InferUIToolSet<typeof tools>;
 
-// Use tool set config
-type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof tools>>;
+// Or from the ToolSet instance
+type MyToolSet = InferUIToolSet<typeof toolSet>;
 
-// Or use ToolSet instance
-type MyUIMessage = UIMessage<unknown, any, 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>({ tools: 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, context: {} });
+```
+
+### 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>({ tools: 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(options)`
 
-- `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`)
+- `options.tools`, a plain `Record<string, Tool>` of AI SDK tools
+- `options.mutable` (optional), set to `true` for a mutable tool set (default: `false`)
 
-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({ tools: { search, list_orders, cancel_order } });
+
+// Mutable mode — methods mutate in-place and return `this`
+const toolSet = createToolSet({ tools: { search, list_orders, cancel_order }, mutable: true });
 ```
 
 #### `.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 +305,95 @@ 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 instance (immutable) or `this` (mutable).
 
 ```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 instance (immutable) or `this` (mutable).
 
 ```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 `{ tools, activeTools }` — directly spreadable into `generateText()` or `streamText()`. This is a terminal operation: messages and context are consumed but not stored.
+
+- `input`:
+  - `messages`, the current conversation messages
+  - `context`, arbitrary values passed to predicates
+
+```ts
+const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+
+const result = await generateText({ model, tools, activeTools, messages });
 ```
 
 ## 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/dist/index.d.mts

@@ -8,9 +8,19 @@ 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;
+type InferToolSet<T extends ToolRecord | AnyToolSet> = T extends ImmutableToolSet<infer TOOLS, any, any> ? TOOLS : T extends MutableToolSet<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]> };
+type InferUIToolSet<T extends ToolRecord | AnyToolSet> = { [K in keyof InferToolSet<T> & string]: InferUITool<InferToolSet<T>[K]> };
+/**
+ * Extract tool names tracked as active from an ImmutableToolSet instance.
+ * Returns `never` for MutableToolSet (cannot be determined at compile time).
+ */
+type ActiveTools<T extends AnyToolSet> = T extends ImmutableToolSet<any, any, any, infer A, any> ? A : never;
+/**
+ * Extract tool names tracked as inactive from an ImmutableToolSet instance.
+ * Returns `never` for MutableToolSet (cannot be determined at compile time).
+ */
+type InactiveTools<T extends AnyToolSet> = T extends ImmutableToolSet<any, any, any, any, infer D> ? D : never;
 /**
  * Input passed to activation predicates.
  * Use `ActivationInput<MyMsg>` to get per-tool narrowing in callbacks.
@@ -25,28 +35,42 @@ type ActivationEntry = {
   toolName: string;
   resolve: (input: ActivationInput<any, any>) => boolean;
 };
-type ToolSetState<TOOLS extends ToolRecord, MESSAGE extends MessageType, CONTEXT extends Record<string, unknown>> = {
+/** Resolved tools and active tool names returned by `inferTools()`. */
+type ResolvedToolSet<TOOLS extends ToolRecord> = {
   tools: TOOLS;
-  entries: Array<ActivationEntry>;
-  input: ActivationInput<MESSAGE, CONTEXT>;
+  activeTools: Array<keyof TOOLS & string>;
 };
+/** Union of both toolset classes for type utility constraints. */
+type AnyToolSet = ImmutableToolSet<any> | MutableToolSet<any>;
+/**
+ * Immutable state container for tool activation.
+ *
+ * All mutation methods return a new ToolSetState instance.
+ * Resolution follows "last-call wins": each method appends entries,
+ * and the last entry for each tool determines its state.
+ */
+declare class ToolSetState<TOOLS extends ToolRecord, MESSAGE extends MessageType = UIMessage, CONTEXT extends Record<string, unknown> = Record<string, unknown>> {
+  #private;
+  constructor(tools: TOOLS, entries: Array<ActivationEntry>);
+  /** All tools as a standard AI SDK tool record. */
+  get tools(): TOOLS;
+  /** Resolved list of active tool names based on current entries (no predicates, default input). */
+  get activeTools(): Array<keyof TOOLS & string>;
+  activate(names: Array<string>): ToolSetState<TOOLS, MESSAGE, CONTEXT>;
+  deactivate(names: Array<string>): ToolSetState<TOOLS, MESSAGE, CONTEXT>;
+  activateWhen(nameOrPredicates: string | Partial<Record<string, ActivationPredicate<MESSAGE, CONTEXT>>>, predicate?: ActivationPredicate<MESSAGE, CONTEXT>): ToolSetState<TOOLS, MESSAGE, CONTEXT>;
+  deactivateWhen(nameOrPredicates: string | Partial<Record<string, ActivationPredicate<MESSAGE, CONTEXT>>>, predicate?: ActivationPredicate<MESSAGE, CONTEXT>): ToolSetState<TOOLS, MESSAGE, CONTEXT>;
+  /** Evaluate all predicates with the provided input and return resolved tools + activeTools. */
+  inferTools(input: ActivationInput<MESSAGE, CONTEXT>): ResolvedToolSet<TOOLS>;
+}
 /**
  * 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> {
+declare class ImmutableToolSet<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;
@@ -54,36 +78,70 @@ declare class ToolSet<TOOLS extends ToolRecord, MESSAGE extends MessageType = UI
   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>;
+  activate<NAMES extends keyof TOOLS & string>(names: Array<NAMES>): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED | NAMES, Exclude<DEACTIVATED, NAMES>>;
+  /** Statically deactivate tools by name. */
+  deactivate<NAMES extends keyof TOOLS & string>(names: Array<NAMES>): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, Exclude<ACTIVATED, NAMES>, DEACTIVATED | NAMES>;
+  /**
+   * Conditionally activate a tool — inactive by default, becomes active when predicate returns true.
+   * Tracks names in DEACTIVATED since the tool starts inactive.
+   */
+  activateWhen<NAME extends keyof TOOLS & string>(name: NAME, predicate: ActivationPredicate<MESSAGE, CONTEXT>): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, Exclude<ACTIVATED, NAME>, DEACTIVATED | NAME>;
+  activateWhen<NAMES extends keyof TOOLS & string>(predicates: Partial<Record<NAMES, ActivationPredicate<MESSAGE, CONTEXT>>>): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, Exclude<ACTIVATED, NAMES>, DEACTIVATED | NAMES>;
+  /**
+   * Conditionally deactivate a tool — active by default, becomes inactive when predicate returns true.
+   * Tracks names in ACTIVATED since the tool starts active.
+   */
+  deactivateWhen<NAME extends keyof TOOLS & string>(name: NAME, predicate: ActivationPredicate<MESSAGE, CONTEXT>): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED | NAME, Exclude<DEACTIVATED, NAME>>;
+  deactivateWhen<NAMES extends keyof TOOLS & string>(predicates: Partial<Record<NAMES, ActivationPredicate<MESSAGE, CONTEXT>>>): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED | NAMES, Exclude<DEACTIVATED, NAMES>>;
+  /** Evaluate all predicates with the provided input. Returns resolved `{ tools, activeTools }`. */
+  inferTools(input: ActivationInput<MESSAGE, CONTEXT>): ResolvedToolSet<TOOLS>;
+}
+/**
+ * A mutable tool set with chainable activation methods.
+ *
+ * Same resolution semantics as ImmutableToolSet, but methods mutate
+ * in-place and return `this` instead of creating new instances.
+ */
+declare class MutableToolSet<TOOLS extends ToolRecord, MESSAGE extends MessageType = UIMessage, CONTEXT extends Record<string, unknown> = Record<string, unknown>> {
+  #private;
+  /** All tools as a standard AI SDK tool record. */
+  readonly tools: TOOLS;
+  /** Resolved list of active tool names based on current state. */
+  activeTools: Array<keyof TOOLS & string>;
+  constructor(state: ToolSetState<TOOLS, MESSAGE, CONTEXT>);
+  /** Statically activate tools by name. */
+  activate(names: Array<keyof TOOLS & string>): this;
   /** Statically deactivate tools by name. */
-  deactivate<NAMES extends ((keyof TOOLS & string) | ACTIVATED) & string>(names: Array<NAMES>): ToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED | NAMES>;
+  deactivate(names: Array<keyof TOOLS & string>): this;
   /**
-   * Conditionally activate a tool — becomes active when predicate returns true.
-   *
-   * - `.activateWhen('tool_name', (input) => ...)`
-   * - `.activateWhen({ tool_name: (input) => ... })`
+   * Conditionally activate a tool — inactive by default, becomes active when predicate returns true.
    */
-  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>;
+  activateWhen(name: keyof TOOLS & string, predicate: ActivationPredicate<MESSAGE, CONTEXT>): this;
+  activateWhen(predicates: Partial<Record<keyof TOOLS & string, ActivationPredicate<MESSAGE, CONTEXT>>>): this;
   /**
-   * 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) => ... })`
+   * Conditionally deactivate a tool — active by default, becomes inactive when predicate returns true.
    */
-  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>;
+  deactivateWhen(name: keyof TOOLS & string, predicate: ActivationPredicate<MESSAGE, CONTEXT>): this;
+  deactivateWhen(predicates: Partial<Record<keyof TOOLS & string, ActivationPredicate<MESSAGE, CONTEXT>>>): this;
+  /** Evaluate all predicates with the provided input. Returns resolved `{ tools, activeTools }`. */
+  inferTools(input: ActivationInput<MESSAGE, CONTEXT>): ResolvedToolSet<TOOLS>;
 }
+type CreateToolSetOptions<TOOLS extends ToolRecord> = {
+  tools: TOOLS;
+  mutable?: boolean;
+};
 /**
- * Create a chainable, immutable tool set.
+ * Create a chainable 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>;
+declare function createToolSet<const TOOLS extends ToolRecord, MESSAGE extends MessageType = InferUIMessage<TOOLS>, CONTEXT extends Record<string, unknown> = Record<string, unknown>>(options: CreateToolSetOptions<TOOLS> & {
+  mutable: true;
+}): MutableToolSet<TOOLS, MESSAGE, CONTEXT>;
+declare function createToolSet<const TOOLS extends ToolRecord, MESSAGE extends MessageType = InferUIMessage<TOOLS>, CONTEXT extends Record<string, unknown> = Record<string, unknown>>(options: CreateToolSetOptions<TOOLS> & {
+  mutable?: false;
+}): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, keyof TOOLS & string>;
 //#endregion
-export { type ActivationInput, type InferToolSet, type InferUIToolSet, createToolSet };
+export { type ActivationInput, type ActiveTools, type InactiveTools, type InferToolSet, type InferUIToolSet, createToolSet };

package/dist/index.mjs

@@ -10,99 +10,151 @@ const toEntries = (nameOrPredicates, predicate) => {
 	}));
 };
 /**
-* An immutable tool set with chainable activation methods.
+* Immutable state container for tool activation.
 *
-* Resolution follows "last-call wins": each method appends an entry,
+* All mutation methods return a new ToolSetState instance.
+* Resolution follows "last-call wins": each method appends entries,
 * 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;
+var ToolSetState = class ToolSetState {
+	#tools;
+	#entries;
+	constructor(tools, entries) {
+		this.#tools = tools;
+		this.#entries = entries;
+	}
 	/** 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);
-		});
+	get tools() {
+		return this.#tools;
+	}
+	/** Resolved list of active tool names based on current entries (no predicates, default input). */
+	get activeTools() {
+		return this.inferTools({
+			messages: [],
+			context: {}
+		}).activeTools;
 	}
-	/** 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]
-		});
+		return new ToolSetState(this.#tools, [...this.#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]
-		});
+		return new ToolSetState(this.#tools, [...this.#entries, ...newEntries]);
 	}
 	activateWhen(nameOrPredicates, predicate) {
-		const newEntries = toEntries(nameOrPredicates, predicate);
-		return new ToolSet({
-			...this.#state,
-			entries: [...this.#state.entries, ...newEntries]
-		});
+		return new ToolSetState(this.#tools, [...this.#entries, ...toEntries(nameOrPredicates, predicate)]);
 	}
 	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]
-		});
+		return new ToolSetState(this.#tools, [...this.#entries, ...newEntries]);
 	}
-	/** Provide messages and context for predicate-based tools. Returns a new ToolSet. */
+	/** Evaluate all predicates with the provided input and return resolved tools + activeTools. */
 	inferTools(input) {
-		return new ToolSet({
-			...this.#state,
-			input
+		const activeTools = Object.keys(this.#tools).filter((name) => {
+			const lastEntry = this.#entries.findLast((e) => e.toolName === name);
+			if (!lastEntry) return true;
+			return lastEntry.resolve(input);
 		});
+		return {
+			tools: this.#tools,
+			activeTools
+		};
 	}
 };
 /**
-* Create a chainable, immutable tool set.
+* An immutable tool set with chainable activation methods.
 *
-* @typeParam TOOLS — inferred from the argument
-* @typeParam MESSAGE — defaults to the fully-typed UIMessage derived from TOOLS
-* @typeParam CONTEXT — defaults to Record<string, unknown>
+* 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.
 */
-const createToolSet = (tools) => {
-	return new ToolSet({
-		tools,
-		entries: [],
-		input: {
-			messages: [],
-			context: {}
-		}
-	});
+var ImmutableToolSet = class ImmutableToolSet {
+	#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 = state.activeTools;
+	}
+	/** Statically activate tools by name. */
+	activate(names) {
+		return new ImmutableToolSet(this.#state.activate(names));
+	}
+	/** Statically deactivate tools by name. */
+	deactivate(names) {
+		return new ImmutableToolSet(this.#state.deactivate(names));
+	}
+	activateWhen(nameOrPredicates, predicate) {
+		return new ImmutableToolSet(this.#state.activateWhen(nameOrPredicates, predicate));
+	}
+	deactivateWhen(nameOrPredicates, predicate) {
+		return new ImmutableToolSet(this.#state.deactivateWhen(nameOrPredicates, predicate));
+	}
+	/** Evaluate all predicates with the provided input. Returns resolved `{ tools, activeTools }`. */
+	inferTools(input) {
+		return this.#state.inferTools(input);
+	}
+};
+/**
+* A mutable tool set with chainable activation methods.
+*
+* Same resolution semantics as ImmutableToolSet, but methods mutate
+* in-place and return `this` instead of creating new instances.
+*/
+var MutableToolSet = class {
+	#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 = state.activeTools;
+	}
+	#apply(state) {
+		this.#state = state;
+		this.activeTools = state.activeTools;
+	}
+	/** Statically activate tools by name. */
+	activate(names) {
+		this.#apply(this.#state.activate(names));
+		return this;
+	}
+	/** Statically deactivate tools by name. */
+	deactivate(names) {
+		this.#apply(this.#state.deactivate(names));
+		return this;
+	}
+	activateWhen(nameOrPredicates, predicate) {
+		this.#apply(this.#state.activateWhen(nameOrPredicates, predicate));
+		return this;
+	}
+	deactivateWhen(nameOrPredicates, predicate) {
+		this.#apply(this.#state.deactivateWhen(nameOrPredicates, predicate));
+		return this;
+	}
+	/** Evaluate all predicates with the provided input. Returns resolved `{ tools, activeTools }`. */
+	inferTools(input) {
+		return this.#state.inferTools(input);
+	}
 };
+function createToolSet(options) {
+	const state = new ToolSetState(options.tools, []);
+	return options.mutable ? new MutableToolSet(state) : new ImmutableToolSet(state);
+}
 //#endregion
 export { createToolSet };

package/package.json

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