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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Chris
+Copyright (c) 2024 Chris Cook
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,7 +2,7 @@
 
 # ai-tool-set
 
-<p align="center">AI SDK: Manage tool activation with type-safe, chainable tool sets</p>
+<p align="center">Conditional tool activation for the AI SDK, fully type-safe</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>
@@ -441,6 +441,28 @@ type MyInput = ActivationInput<MyUIMessage, { isAdmin: boolean }>;
 // { messages?: Array<MyUIMessage>; context?: { isAdmin: boolean } }
 ```
 
+### `ToolSet`
+
+Parameter type that accepts both immutable and mutable variants of an existing tool set. Use it for helpers that should work regardless of which flavor the caller is holding:
+
+```ts
+import { createToolSet, type ToolSet } from 'ai-tool-set';
+
+const toolSet = createToolSet({ tools }).deactivate(['cancel_order']);
+
+type MyToolSet = ToolSet<typeof toolSet>;
+
+// Accepts the immutable toolset AND the cloned mutable instance
+function activateTools(toolSet: MyToolSet) {
+  toolSet.activate(['cancel_order']);
+}
+
+activateTools(toolSet);
+
+const mutableToolSet = toolSet.clone({ mutable: true });
+activateTools(mutableToolSet);
+```
+
 ### `InferToolSet`
 
 Extract the raw tool record from a tool record or `ToolSet` instance:
@@ -467,35 +489,35 @@ type MyUIMessage = UIMessage<unknown, any, InferUIToolSet<typeof toolSet>>;
 // message.parts[0].output // typed as search tool's return type
 ```
 
-### `ActiveTools`
+### `InferActiveTools`
 
 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.
+> `InferActiveTools` 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';
+import type { InferActiveTools } from 'ai-tool-set';
 
 const toolSet = createToolSet({ tools }).deactivate(['cancel_order']);
 
-type Active = ActiveTools<typeof toolSet>;
+type Active = InferActiveTools<typeof toolSet>;
 // 'search' | 'list_orders'
 ```
 
-### `InactiveTools`
+### `InferInactiveTools`
 
 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.
+> `InferInactiveTools` 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';
+import type { InferInactiveTools } from 'ai-tool-set';
 
 const toolSet = createToolSet({ tools }).deactivate(['cancel_order']);
 
-type Inactive = InactiveTools<typeof toolSet>;
+type Inactive = InferInactiveTools<typeof toolSet>;
 // 'cancel_order'
 ```
 

package/dist/index.d.mts

@@ -8,19 +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 | AnyToolSet> = T extends ImmutableToolSet<infer TOOLS, any, any> ? TOOLS : T extends MutableToolSet<infer TOOLS, any, any> ? TOOLS : T;
+type InferToolSet<TOOLSET extends ToolRecord | AnyToolSet> = TOOLSET extends ImmutableToolSet<infer TOOLS, any, any> ? TOOLS : TOOLSET extends MutableToolSet<infer TOOLS, any, any> ? TOOLS : TOOLSET;
 /** Infer the UI tool types from a tool record or ToolSet instance. */
-type InferUIToolSet<T extends ToolRecord | AnyToolSet> = { [K in keyof InferToolSet<T> & string]: InferUITool<InferToolSet<T>[K]> };
+type InferUIToolSet<TOOLSET extends ToolRecord | AnyToolSet> = { [K in keyof InferToolSet<TOOLSET> & string]: InferUITool<InferToolSet<TOOLSET>[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;
+type InferActiveTools<TOOLSET extends AnyToolSet> = TOOLSET 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;
+type InferInactiveTools<TOOLSET extends AnyToolSet> = TOOLSET 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.
@@ -41,7 +41,31 @@ type ResolvedToolSet<TOOLS extends ToolRecord> = {
   activeTools: Array<keyof TOOLS & string>;
 };
 /** Union of both toolset classes for type utility constraints. */
-type AnyToolSet = ImmutableToolSet<any> | MutableToolSet<any>;
+type AnyToolSet = ImmutableToolSet<any, any, any> | MutableToolSet<any, any, any>;
+/**
+ * Derive a parameter type that accepts both immutable and mutable variants of an existing tool set.
+ *
+ * `createToolSet({ tools })` returns an `ImmutableToolSet`, while `.clone({ mutable: true })`
+ * returns a structurally distinct `MutableToolSet`. Helpers written against `typeof baseToolSet`
+ * directly cannot accept the cloned mutable instance — `ToolSet<typeof baseToolSet>` resolves
+ * to a union of both flavors and infers `TOOLS`, `MESSAGE`, and `CONTEXT` from the source.
+ *
+ * @example Accept either flavor in a helper function
+ * ```ts
+ * const baseToolSet = createToolSet({ tools }).deactivate(['cancel_order']);
+ *
+ * type MyToolSet = ToolSet<typeof baseToolSet>;
+ *
+ * // Accepts the immutable baseToolSet AND the cloned mutable instance
+ * function activateAdminTools(toolSet: MyToolSet) {
+ *   toolSet.activate(['cancel_order']);
+ * }
+ *
+ * activateAdminTools(baseToolSet);
+ * activateAdminTools(baseToolSet.clone({ mutable: true }));
+ * ```
+ */
+type ToolSet<TOOLSET extends AnyToolSet> = TOOLSET extends ImmutableToolSet<infer TOOLS, infer MESSAGE, infer CONTEXT, infer ACTIVATED, infer DEACTIVATED> ? ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, ACTIVATED, DEACTIVATED> | MutableToolSet<TOOLS, MESSAGE, CONTEXT> : TOOLSET extends MutableToolSet<infer TOOLS, infer MESSAGE, infer CONTEXT> ? ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, any, any> | MutableToolSet<TOOLS, MESSAGE, CONTEXT> : never;
 /**
  * Immutable state container for tool activation.
  *
@@ -152,4 +176,4 @@ declare function createToolSet<const TOOLS extends ToolRecord, MESSAGE extends M
   mutable?: false;
 }): ImmutableToolSet<TOOLS, MESSAGE, CONTEXT, keyof TOOLS & string>;
 //#endregion
-export { type ActivationInput, type ActiveTools, type InactiveTools, type InferToolSet, type InferUIToolSet, createToolSet };
+export { type ActivationInput, type InferActiveTools, type InferInactiveTools, type InferToolSet, type InferUIToolSet, type ToolSet, createToolSet };

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "ai-tool-set",
-  "version": "0.1.0-alpha.4",
-  "description": "Tool set utilities for the Vercel AI SDK",
-  "keywords": [],
+  "version": "1.1.0",
+  "description": "Conditional tool activation for the AI SDK, fully type-safe",
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "tools",
+    "toolset"
+  ],
   "license": "MIT",
   "author": "Chris Cook",
   "repository": {