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

package/README.md

@@ -9,7 +9,7 @@
 
 </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?
 
@@ -37,25 +37,25 @@ 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 });
+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),
+  }),
+};
+
+const toolSet = createToolSet({ tools });
 ```
 
 ### Use with `generateText` / `streamText`
@@ -82,9 +82,7 @@ const result = await generateText({
 Use `.activate()` and `.deactivate()` to statically control which tools are available:
 
 ```typescript
-const { tools, activeTools } = toolSet
-  .deactivate(['cancel_order'])
-  .activate(['list_orders']);
+const { tools, activeTools } = toolSet.deactivate(['cancel_order']).activate(['list_orders']);
 
 const result = await generateText({
   model,
@@ -99,27 +97,19 @@ const result = await generateText({
 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 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'),
     ),
-  );
-
-const result = await generateText({
-  model,
-  tools,
-  activeTools,
-  prompt: 'Cancel my order #1001',
-});
+  ),
+);
 ```
 
-Use `.inferTools()` to evaluate predicates with the current messages and 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 = [
@@ -129,18 +119,20 @@ const messages = [
   },
   {
     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' },
-        ],
+    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' },
+          ],
+        },
       },
-    }],
+    ],
   },
 ];
 
@@ -153,11 +145,10 @@ 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),
-  });
+const toolSet = createToolSet({ tools }).activateWhen({
+  list_orders: ({ context }) => context.isAuthenticated,
+  cancel_order: ({ messages }) => hasUnfulfilledOrders(messages),
+});
 ```
 
 ### Last-Call Wins
@@ -165,26 +156,75 @@ const toolSet = createToolSet({ search, list_orders, cancel_order })
 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),
+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
+### 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,
+  });
+}
+```
+
+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']);
 
-All methods return new tool set instances. The original is never modified:
+  const { tools, activeTools } = myToolSet;
+
+  const result = await generateText({
+    model,
+    tools,
+    activeTools,
+    messages,
+  });
+}
+```
+
+Use `.clone()` to convert between immutable and mutable, preserving all activation entries:
 
 ```typescript
-const base = createToolSet({ search, list_orders, cancel_order });
-const withoutCancel = base.deactivate(['cancel_order']);
-const withCancel = withoutCancel.activate(['cancel_order']);
+// Convert an immutable toolset to mutable
+const mutableToolSet = toolSet.clone({ mutable: true });
 
-base.activeTools;          // ['search', 'list_orders', 'cancel_order']
-withoutCancel.activeTools; // ['search', 'list_orders']
-withCancel.activeTools;    // ['search', 'list_orders', 'cancel_order']
+// Convert a mutable toolset back to immutable
+const immutableToolSet = mutableToolSet.clone();
 ```
 
 ### Typed UI Tool Set
@@ -196,7 +236,7 @@ import type { UIMessage } from 'ai';
 import type { InferUIToolSet } from 'ai-tool-set';
 
 const tools = { search, list_orders, cancel_order };
-const toolSet = createToolSet(tools);
+const toolSet = createToolSet({ tools });
 
 // From the tools record
 type MyToolSet = InferUIToolSet<typeof tools>;
@@ -216,12 +256,14 @@ If you already have a custom `UIMessage` type, you can pass it as `MESSAGE` gene
 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 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 });
+const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
 ```
 
 ### Custom Context
@@ -234,10 +276,12 @@ 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 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,
@@ -247,14 +291,18 @@ const { tools, activeTools } = toolSet.inferTools({
 
 ## API
 
-## `createToolSet(tools)`
+## `createToolSet(options)`
 
-- `tools`, a plain `Record<string, Tool>` of AI SDK tools
+- `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. All tools are active by default.
 
 ```ts
-const toolSet = createToolSet({ search, list_orders, cancel_order });
+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`
@@ -275,7 +323,7 @@ const { activeTools } = toolSet;
 
 #### `.activate(names)`
 
-Statically activate tools by name. Returns a new `ToolSet`.
+Statically activate tools by name. Returns a new instance (immutable) or `this` (mutable).
 
 ```ts
 toolSet.activate(['cancel_order']);
@@ -283,7 +331,7 @@ toolSet.activate(['cancel_order']);
 
 #### `.deactivate(names)`
 
-Statically deactivate tools by name. Returns a new `ToolSet`.
+Statically deactivate tools by name. Returns a new instance (immutable) or `this` (mutable).
 
 ```ts
 toolSet.deactivate(['search']);
@@ -312,14 +360,25 @@ toolSet.deactivateWhen('search', ({ messages }) => messages.length > 10);
 
 #### `.inferTools(input)`
 
-Evaluate all predicates with the provided messages and context. Returns a new `ToolSet`.
+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
-toolSet.inferTools({ messages, context: {} });
+const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+
+const result = await generateText({ model, tools, activeTools, messages });
+```
+
+#### `.clone(options?)`
+
+Clone the toolset, preserving all activation entries. Pass `{ mutable: true }` to get a mutable clone, or omit for an immutable clone. Defaults to immutable.
+
+```ts
+const mutableClone = toolSet.clone({ mutable: true });
+const immutableClone = toolSet.clone();
 ```
 
 ## Types
@@ -361,6 +420,38 @@ type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof toolSet>>;
 // message.parts[0].output // typed as search tool's return type
 ```
 
+### `ActiveTools`
+
+Extract the tool names tracked as active from an immutable `ToolSet` instance. Tracks tools from `.activate()` and `.deactivateWhen()`.
+
+> [!NOTE]
+> `ActiveTools` returns `never` for mutable toolsets, since TypeScript cannot track type changes on the same reference across method calls.
+
+```ts
+import type { ActiveTools } from 'ai-tool-set';
+
+const toolSet = createToolSet({ tools }).deactivate(['cancel_order']);
+
+type Active = ActiveTools<typeof toolSet>;
+// 'search' | 'list_orders'
+```
+
+### `InactiveTools`
+
+Extract the tool names tracked as inactive from an immutable `ToolSet` instance. Tracks tools from `.deactivate()` and `.activateWhen()`.
+
+> [!NOTE]
+> `InactiveTools` returns `never` for mutable toolsets, since TypeScript cannot track type changes on the same reference across method calls.
+
+```ts
+import type { InactiveTools } from 'ai-tool-set';
+
+const toolSet = createToolSet({ tools }).deactivate(['cancel_order']);
+
+type Inactive = InactiveTools<typeof toolSet>;
+// 'cancel_order'
+```
+
 ## License
 
 MIT

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,84 @@ 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>;
+  /** Clone this toolset, optionally switching between immutable and mutable. */
+  clone(options: {
+    mutable: true;
+  }): MutableToolSet<TOOLS, MESSAGE, CONTEXT>;
+  clone(options?: {
+    mutable?: false;
+  }): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED>;
+}
+/**
+ * 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>;
+  /** Clone this toolset, optionally switching between immutable and mutable. */
+  clone(options: {
+    mutable: true;
+  }): MutableToolSet<TOOLS, MESSAGE, CONTEXT>;
+  clone(options?: {
+    mutable?: false;
+  }): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, keyof TOOLS & string>;
 }
+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,157 @@ 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);
+	}
+	clone(options) {
+		return options?.mutable ? new MutableToolSet(this.#state) : new ImmutableToolSet(this.#state);
+	}
+};
+/**
+* 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 MutableToolSet {
+	#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);
+	}
+	clone(options) {
+		return options?.mutable ? new MutableToolSet(this.#state) : new ImmutableToolSet(this.#state);
+	}
 };
+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.1",
+  "version": "0.1.0-alpha.3",
   "description": "Tool set utilities for the Vercel AI SDK",
   "keywords": [],
   "license": "MIT",