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

package/README.md

@@ -58,58 +58,53 @@ const tools = {
 const toolSet = createToolSet({ tools });
 ```
 
-### Use with `generateText` / `streamText`
+### Activate and Deactivate Tools
 
-The tool set exposes `tools` and `activeTools` as properties that can be used directly:
+Use `.activate()` and `.deactivate()` to statically control which tools are available. Call `.inferTools()` to resolve `activeTools` and pass into `generateText()` or `streamText()`:
 
 ```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:
+// Activate and deactivate tools
+const toolSet = createToolSet({ tools })
+  .deactivate(['cancel_order'])
+  .activate(['list_orders']);
 
-```typescript
-const { tools, activeTools } = toolSet.deactivate(['cancel_order']).activate(['list_orders']);
+// Infer active tools
+const { tools, activeTools } = toolSet.inferTools();
 
 const result = await generateText({
   model,
+  // Pass tools and activeTools:
   tools,
   activeTools,
+  // Or spread directly:
+  // ...toolSet.deactivate(['cancel_order']).activate(['list_orders']).inferTools(),
   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`.
+Use `.activateWhen()` and `.deactivateWhen()` to conditionally control tools based on messages and context. The predicate receives an input with `messages` and `context` (both can be `undefined` if not provided to `inferTools`) and should return a boolean (or undefined) to determine whether the tool should be activated/deactivated.
 
 ```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'),
+// Conditional activation with a predicate that checks for unfulfilled orders in the messages
+const toolSet = createToolSet({ tools })
+  .activateWhen('list_orders', ({ context }) => context?.isAuthenticated)
+  .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 predicates with the current messages and context. It returns `{ tools, activeTools }` that can be spread directly into `generateText()`:
+Call `.inferTools()` with messages and/or context to evaluate activation predicates and resolve `activeTools`:
 
 ```typescript
 const messages = [
@@ -136,8 +131,10 @@ const messages = [
   },
 ];
 
+const context = { isAuthenticated: true };
+
 // cancel_order is now active because list_orders returned unfulfilled orders
-const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+const { tools, activeTools } = toolSet.inferTools({ messages, context });
 
 const result = await generateText({ model, tools, activeTools, messages });
 ```
@@ -145,26 +142,53 @@ 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),
-});
+const toolSet = createToolSet({ tools })
+  .activateWhen({
+    list_orders: ({ context }) => context?.isAuthenticated,
+    cancel_order: ({ messages }) => hasUnfulfilledOrders(messages),
+  });
+```
+
+### Activation Defaults
+
+`.activateWhen()` marks a tool as **inactive by default**. It only becomes active when the predicate returns `true`. If the predicate returns `undefined` or `false`, the tool stays inactive:
+
+```typescript
+const toolSet = createToolSet({ tools })
+  // undefined when messages is not provided → tool stays inactive
+  // false when no orders found → tool stays inactive
+  // true when orders found → tool becomes active
+  .activateWhen('cancel_order', ({ messages }) => messages?.some((m) => hasOrders(m)));
+
+toolSet.inferTools().activeTools; // cancel_order is inactive (predicate received undefined)
+toolSet.inferTools({ messages: [] }).activeTools; // cancel_order is inactive (no orders)
+```
+
+`.deactivateWhen()` marks a tool as **active by default**. It only becomes inactive when the predicate returns `true`. If the predicate returns `undefined` or `false`, the tool stays active:
+
+```typescript
+const toolSet = createToolSet({ tools })
+  // undefined when messages is not provided → tool stays active
+  // false when few messages → tool stays active
+  // true when too many messages → tool becomes inactive
+  .deactivateWhen('search', ({ messages }) => messages && messages.length > 10);
+
+toolSet.inferTools().activeTools; // search is active (predicate received undefined)
+toolSet.inferTools({ messages: [] }).activeTools; // search is active (few 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:
+Each activation 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({ tools })
-  .activate(['cancel_order']) // cancel_order: activated
-  .deactivate(['cancel_order']) // cancel_order: deactivated
-  .activateWhen(
-    'cancel_order',
-    (
-      { messages }, // cancel_order: conditional activation
-    ) => hasUnfulfilledOrders(messages),
-  );
+  // cancel_order: activated
+  .activate(['cancel_order']) 
+  // cancel_order: deactivated
+  .deactivate(['cancel_order']) 
+  // cancel_order: deactivated with conditional activation
+  .activateWhen('cancel_order', ({ messages }) => hasUnfulfilledOrders(messages)); 
 ```
 
 ### Immutable vs Mutable
@@ -182,42 +206,36 @@ export async function POST(req: 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,
+    ...myToolSet.inferTools({ messages }),
     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:
+Use `createToolSet({ 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 toolSet = createToolSet({ tools, mutable: true })
+    .deactivate(['list_order', 'cancel_order'])
+    .activate(['list_orders']);
 
   const result = await generateText({
     model,
-    tools,
-    activeTools,
+    ...toolSet.inferTools({ messages }),
     messages,
   });
 }
 ```
 
-Use `.clone()` to convert between immutable and mutable, preserving all activation entries:
+### Cloning
+
+Use `.clone({ mutable?: boolean })` to convert between immutable and mutable, preserving all activation entries:
 
 ```typescript
 // Convert an immutable toolset to mutable
@@ -227,6 +245,29 @@ const mutableToolSet = toolSet.clone({ mutable: true });
 const immutableToolSet = mutableToolSet.clone();
 ```
 
+This is useful when you want to create a base tool set in the global scope and clone it per request to add request-specific activation:
+
+```typescript
+// Global scope: base tool set
+const baseToolSet = createToolSet({ tools }).deactivate(['list_order', 'cancel_order']);
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  // Clone the base tool set into a mutable instance for this request
+  const toolSet = baseToolSet.clone({ mutable: true });
+
+  // Activate list_orders only for this request
+  toolSet.activate(['list_orders']);
+
+  const result = await generateText({
+    model,
+    ...toolSet.inferTools({ messages }),
+    messages,
+  });
+}
+```
+
 ### Typed UI Tool Set
 
 Use `InferUIToolSet` to get fully typed UI messages from your tool set:
@@ -256,14 +297,16 @@ 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>({ tools: 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 Array<MyUIMessage> | undefined  
+  );
 
-const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+
+const { tools, activeTools } = toolSet.inferTools({ messages });
 ```
 
 ### Custom Context
@@ -276,16 +319,18 @@ 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 toolSet = createToolSet<typeof myTools, MyUIMessage, MyContext>({ tools: myTools })
+  .activateWhen(
+    'cancel_order',
+    ({ context }) => context?.isAdmin,
+    // ~~~~~~~
+    // Context is typed as MyContext | undefined
+  );
+
 
 const { tools, activeTools } = toolSet.inferTools({
   messages,
-  context: { isAdmin: true },
+  context: { userId: '1', isAdmin: true },
 });
 ```
 
@@ -313,14 +358,6 @@ All tools as a standard AI SDK tool record, regardless of activation state.
 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 instance (immutable) or `this` (mutable).
@@ -339,35 +376,45 @@ toolSet.deactivate(['search']);
 
 #### `.activateWhen(name, predicate)` / `.activateWhen(predicates)`
 
-Conditionally activate tools. The predicate receives `{ messages, context }` and returns `true` to activate.
+Conditionally activate tools. The predicate receives `{ messages, context }` and returns `true` to activate. Both `messages` and `context` can be `undefined` if not provided to `inferTools`. Returning `undefined` is treated as `false`.
 
 ```ts
-toolSet.activateWhen('cancel_order', ({ messages }) => hasOrders(messages));
+toolSet.activateWhen('cancel_order', ({ messages }) => messages?.some((m) => hasOrders(m)));
 
 toolSet.activateWhen({
-  cancel_order: ({ messages }) => hasOrders(messages),
-  list_orders: ({ context }) => context.isAuthenticated,
+  cancel_order: ({ messages }) => messages?.some((m) => hasOrders(m)),
+  list_orders: ({ context }) => context?.isAuthenticated,
 });
 ```
 
 #### `.deactivateWhen(name, predicate)` / `.deactivateWhen(predicates)`
 
-Conditionally deactivate tools. The predicate receives `{ messages, context }` and returns `true` to deactivate.
+Conditionally deactivate tools. The predicate receives `{ messages, context }` and returns `true` to deactivate. Both `messages` and `context` can be `undefined` if not provided to `inferTools`. Returning `undefined` is treated as `false` (tool stays active).
 
 ```ts
-toolSet.deactivateWhen('search', ({ messages }) => messages.length > 10);
+toolSet.deactivateWhen('search', ({ messages }) => messages && messages.length > 10);
 ```
 
-#### `.inferTools(input)`
+#### `.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.
+Evaluate all predicates and return `{ tools, activeTools }`, directly spreadable into `generateText()` or `streamText()`. The input is optional; all fields are optional. Predicates receive `undefined` for fields not provided.
 
-- `input`:
-  - `messages`, the current conversation messages
-  - `context`, arbitrary values passed to predicates
+- `input` (optional):
+  - `messages` (optional), the current conversation messages
+  - `context` (optional), arbitrary values passed to predicates
 
 ```ts
-const { tools, activeTools } = toolSet.inferTools({ messages, context: {} });
+// Static-only (no predicates)
+const { tools, activeTools } = toolSet.inferTools();
+
+// With messages
+const { tools, activeTools } = toolSet.inferTools({ messages });
+
+// With context
+const { tools, activeTools } = toolSet.inferTools({ context: { isAdmin: true } });
+
+// With both
+const { tools, activeTools } = toolSet.inferTools({ messages, context });
 
 const result = await generateText({ model, tools, activeTools, messages });
 ```
@@ -385,13 +432,13 @@ const immutableClone = toolSet.clone();
 
 ### `ActivationInput`
 
-Input passed to activation predicates. Generic over `MESSAGE` and `CONTEXT`:
+Input passed to activation predicates. Generic over `MESSAGE` and `CONTEXT`. Both `messages` and `context` are optional since they may not be provided to `inferTools`:
 
 ```ts
 import type { ActivationInput } from 'ai-tool-set';
 
 type MyInput = ActivationInput<MyUIMessage, { isAdmin: boolean }>;
-// { messages: Array<MyUIMessage>; context: { isAdmin: boolean } }
+// { messages?: Array<MyUIMessage>; context?: { isAdmin: boolean } }
 ```
 
 ### `InferToolSet`

package/dist/index.d.mts

@@ -26,14 +26,14 @@ type InactiveTools<T extends AnyToolSet> = T extends ImmutableToolSet<any, any,
  * 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;
+  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;
+/** Activation predicate — returns true if tool should be active. Undefined is treated as false. */
+type ActivationPredicate<MESSAGE extends MessageType = UIMessage, CONTEXT extends Record<string, unknown> = Record<string, unknown>> = (input: ActivationInput<MESSAGE, CONTEXT>) => boolean | undefined;
 type ActivationEntry = {
   toolName: string;
-  resolve: (input: ActivationInput<any, any>) => boolean;
+  resolve: (input: ActivationInput<any, any>) => boolean | undefined;
 };
 /** Resolved tools and active tool names returned by `inferTools()`. */
 type ResolvedToolSet<TOOLS extends ToolRecord> = {
@@ -54,14 +54,12 @@ declare class ToolSetState<TOOLS extends ToolRecord, MESSAGE extends MessageType
   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>;
+  inferTools(input?: ActivationInput<MESSAGE, CONTEXT>): ResolvedToolSet<TOOLS>;
 }
 /**
  * An immutable tool set with chainable activation methods.
@@ -74,8 +72,6 @@ declare class ImmutableToolSet<TOOLS extends ToolRecord, MESSAGE extends Message
   #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 keyof TOOLS & string>(names: Array<NAMES>): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED | NAMES, Exclude<DEACTIVATED, NAMES>>;
@@ -94,7 +90,7 @@ declare class ImmutableToolSet<TOOLS extends ToolRecord, MESSAGE extends Message
   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>;
+  inferTools(input?: ActivationInput<MESSAGE, CONTEXT>): ResolvedToolSet<TOOLS>;
   /** Clone this toolset, optionally switching between immutable and mutable. */
   clone(options: {
     mutable: true;
@@ -113,8 +109,6 @@ declare class MutableToolSet<TOOLS extends ToolRecord, MESSAGE extends MessageTy
   #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;
@@ -131,7 +125,7 @@ declare class MutableToolSet<TOOLS extends ToolRecord, MESSAGE extends MessageTy
   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>;
+  inferTools(input?: ActivationInput<MESSAGE, CONTEXT>): ResolvedToolSet<TOOLS>;
   /** Clone this toolset, optionally switching between immutable and mutable. */
   clone(options: {
     mutable: true;

package/dist/index.mjs

@@ -27,13 +27,6 @@ var ToolSetState = class ToolSetState {
 	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;
-	}
 	activate(names) {
 		const newEntries = names.map((name) => ({
 			toolName: name,
@@ -63,7 +56,7 @@ var ToolSetState = class ToolSetState {
 		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 lastEntry.resolve(input ?? {});
 		});
 		return {
 			tools: this.#tools,
@@ -82,12 +75,9 @@ 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) {
@@ -121,33 +111,26 @@ 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));
+		this.#state = this.#state.activate(names);
 		return this;
 	}
 	/** Statically deactivate tools by name. */
 	deactivate(names) {
-		this.#apply(this.#state.deactivate(names));
+		this.#state = this.#state.deactivate(names);
 		return this;
 	}
 	activateWhen(nameOrPredicates, predicate) {
-		this.#apply(this.#state.activateWhen(nameOrPredicates, predicate));
+		this.#state = this.#state.activateWhen(nameOrPredicates, predicate);
 		return this;
 	}
 	deactivateWhen(nameOrPredicates, predicate) {
-		this.#apply(this.#state.deactivateWhen(nameOrPredicates, predicate));
+		this.#state = this.#state.deactivateWhen(nameOrPredicates, predicate);
 		return this;
 	}
 	/** Evaluate all predicates with the provided input. Returns resolved `{ tools, activeTools }`. */

package/package.json

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