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

package/README.md

@@ -1,3 +1,317 @@
+<div align='center'>
+
 # ai-tool-set
 
-> **Work in progress** — this package is under active development and not yet ready for use.
+<p align="center">AI SDK: Manage tool activation with type-safe, chainable tool sets</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/ai-tool-set" alt="ai-tool-set"><img src="https://img.shields.io/npm/dt/ai-tool-set?label=ai-tool-set"></a> <a href="https://github.com/zirkelc/ai-tool-set/actions/workflows/ci.yml" alt="CI"><img src="https://img.shields.io/github/actions/workflow/status/zirkelc/ai-tool-set/ci.yml?branch=main"></a>
+</p>
+
+</div>
+
+This library provides an immutable and type-safe API to manage [`activeTools`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#active-tools) for [`generateText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text) and [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text) in the AI SDK.
+
+### Why?
+
+The AI SDK provides an `activeTools` parameter to control which tools the model can use at any given time. However, managing tool activation becomes complex when you need to:
+
+- **Activate/deactivate tools**: Some tools should be inactive by default and should only be available after being explicitily 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.
+
+### Installation
+
+```bash
+npm install ai-tool-set
+```
+
+## Usage
+
+### 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.
+
+```typescript
+import { tool } from 'ai';
+import { z } from 'zod';
+import { createToolSet } from 'ai-tool-set';
+
+const toolSet = createToolSet({
+  // Plain tool — always active
+  search: tool({
+    description: 'Search for products',
+    inputSchema: z.object({ query: z.string() }),
+    execute: async ({ query }) => searchProducts(query),
+  }),
+
+  // Explicitly inactive — must be activated manually
+  list_orders: {
+    tool: tool({
+      description: 'List orders for a customer',
+      inputSchema: z.object({ customerId: z.string() }),
+      execute: async ({ customerId }) => listOrders(customerId),
+    }),
+    active: false,
+  },
+
+  // 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'),
+        ),
+      ),
+  },
+});
+```
+
+### Use with `generateText` / `streamText` / `ToolLoopAgent`
+
+The tool set exposes `tools` and `activeTools` as properties that can be used directly:
+
+```typescript
+import { generateText } from 'ai';
+
+const { tools, activeTools } = toolSet;
+
+const result = await generateText({
+  model,
+  tools,
+  activeTools,
+  // Or spread tool set directly:
+  // ...toolSet,
+  prompt: 'Hello',
+});
+```
+
+### Activate and Deactivate Tools
+
+Use `activateTools()` and `deactivateTools()` to override static activation. Both methods are type-safe and only accept valid tool names:
+
+```typescript
+// Active tools will include 'list_orders' and exclude 'search'
+const { tools, activeTools } = toolSet
+  .activateTools(['list_orders'])
+  .deactivateTools(['search']);
+
+const result = await generateText({
+  model,
+  tools,
+  activeTools,
+  prompt: 'Show me my orders',
+});
+```
+
+### Infer Active Tools
+
+Use `inferTools()` to evaluate callback-based tools against the current conversation context:
+
+```typescript
+const messages = [
+  {
+    role: 'user',
+    parts: [{ type: 'text', text: 'Show me my orders' }],
+  },
+  {
+    role: 'assistant',
+    parts: [
+      {
+        type: 'tool-list_orders',
+        state: 'output-available',
+        toolCallId: 'call-1',
+        input: { customerId: 'cust-123' },
+        output: {
+          orders: [
+            { orderId: 'order-1', status: 'fulfilled' },
+            { orderId: 'order-2', status: 'pending' },
+          ],
+        },
+      },
+    ],
+  },
+];
+
+// Active tools will include 'cancel_order' based on the messages context
+const { tools, activeTools } = toolSet.inferTools({ messages });
+
+const result = await generateText({
+  model,
+  tools,
+  activeTools,
+  messages,
+});
+```
+
+### Immutable
+
+All methods return new tool set instances, allowing you to maintain different tool states across different calls or steps without side effects:
+
+```typescript
+const toolSet1 = createToolSet({ ... });
+const toolSet2 = toolSet1.activateTools(['list_orders']);
+const toolSet3 = toolSet2.deactivateTools(['search', 'list_orders']);
+
+toolSet1.activeTools; // ['search']
+toolSet2.activeTools; // ['search', 'list_orders']
+toolSet3.activeTools; // []
+```
+
+### Typed UI Messages
+
+Use `InferUIToolSet` to get fully typed UI messages from your tool set:
+
+```typescript
+import type { UIMessage } from 'ai';
+import type { InferUIToolSet, ToolSetConfig } from 'ai-tool-set';
+
+const tools = {
+  search: tool({ ... }),
+  list_orders: {
+    tool: tool({ ... }),
+    active: false,
+  },
+  cancel_order: {
+    tool: tool({ ... }),
+    active: ({ messages }) => /* callback logic */,
+  },
+} satisfies ToolSetConfig;
+
+const toolSet = createToolSet(tools);
+
+// Use tool set config
+type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof tools>>;
+
+// Or use ToolSet instance
+type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof toolSet>>;
+```
+
+## API
+
+## `createToolSet(config)`
+
+- `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`)
+
+Returns a `ToolSet` instance.
+
+```ts
+const toolSet = createToolSet({
+  search: tool({ ... }),
+  list_orders: {
+    tool: tool({ ... }),
+    active: false,
+  },
+  cancel_order: {
+    tool: tool({ ... }),
+    active: ({ messages }) => /* callback logic */,
+  },
+});
+```
+
+#### `.tools`
+
+All tools as a standard AI SDK tool record (`Record<string, Tool>`), regardless of activation state.
+
+```ts
+const { tools } = toolSet;
+```
+
+#### `.activeTools`
+
+Resolved array of active tool names based on the current state. Accounts for static activation, explicit overrides, and callback evaluation.
+
+```ts
+const { activeTools } = toolSet;
+```
+
+#### `.activateTools(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.
+
+```ts
+const toolSetWithOrders = toolSet.activateTools(['list_orders']);
+```
+
+#### `.deactivateTools(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.
+
+```ts
+const toolSetWithoutSearch = toolSet.deactivateTools(['search']);
+```
+
+#### `.inferTools(context)`
+
+Evaluate callback-based tools against the provided context. Returns a new `ToolSet` instance.
+
+- `context`:
+  - `messages`, `Array<UIMessage>`, the current conversation messages used by activation callbacks to determine tool availability
+
+```ts
+const toolSetInferred = toolSet.inferTools({ messages });
+```
+
+## Types
+
+### `ToolSetConfig`
+
+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:
+
+```ts
+import { type ToolSetConfig } from 'ai-tool-set';
+
+const tools = {
+  search: tool({ ... }),
+  list_orders: { tool: tool({ ... }), active: false },
+  cancel_order: { tool: tool({ ... }), active: ({ messages }) => /* ... */ },
+} satisfies ToolSetConfig;
+```
+
+### `InferToolSet`
+
+Extract a `Record<string, Tool>` from a `ToolSetConfig` object or `ToolSet` instance, stripping activation metadata:
+
+```ts
+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>;
+```
+
+### `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:
+
+```ts
+import type { UIMessage } from 'ai';
+import { type InferUIToolSet } from 'ai-tool-set';
+
+type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof tools>>;
+
+// Also works with a ToolSet instance
+type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof toolSet>>;
+
+// Parts are now typed per tool:
+// message.parts[0].type === 'tool-search'
+// message.parts[0].output // typed as search tool's return type
+```
+
+## License
+
+MIT

package/dist/index.d.mts

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

package/dist/index.mjs

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

package/package.json

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