@ellyco/agentic 0.1.2 → 0.2.1

package/dist/nodes/model-node.js

@@ -9,71 +9,171 @@ const BaseModel_1 = require("../models/BaseModel");
  * @param {any} value - Value to check
  * @returns {boolean} True if value is a messages-returning function
  */
-function isMessagesFunction(value) {
+function isMessagesConstructed(value) {
+    return typeof value === "function";
+}
+/**
+ * Type guard to check if a value is a function that constructs output from the model response.
+ *
+ * @private
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is an output-constructing function
+ */
+function isOutputConstructed(value) {
+    return typeof value === "function";
+}
+/**
+ * Type guard to check if a value is a function that dynamically generates a system message.
+ *
+ * @private
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is a system message function
+ */
+function isSystemMessageDynamic(value) {
+    return typeof value === "function";
+}
+/**
+ * Type guard to check if a value is a function that dynamically generates tool definitions.
+ *
+ * @private
+ * @param {any} value - Value to check
+ * @returns {boolean} True if value is a tools function
+ */
+function isToolsDynamic(value) {
     return typeof value === "function";
 }
 /**
  * A node that invokes an AI model and stores the response in the state.
- * Can be configured to either construct messages dynamically or read from state.
+ *
+ * ModelNode provides flexible configuration for:
+ * - Message sources: read from state or construct dynamically
+ * - Output handling: store in state key or transform via function
+ * - System messages: static or dynamic based on state/context
+ * - Tool definitions: static or dynamic (ignored for StructuredOutputWrapper)
+ *
+ * Supports both regular BaseModel instances (returns messages) and StructuredOutputWrapper
+ * instances (returns structured data matching a Zod schema).
  *
  * @class ModelNode
  * @template T - The state type
- * @implements {NodeLike<T, Partial<T>>}
+ * @template M - The model type (BaseModel or StructuredOutputWrapper), defaults to BaseModel
+ * @implements {NodeLike<T>}
  *
  * @example
  * ```typescript
- * // With messages from a function
+ * // Basic usage with messages from state
  * const node = new ModelNode(model, {
- *   messages: (state, context) => [new UserMessage(state.input)],
+ *   messages: "conversationMessages",
  *   output: "modelResponse"
  * });
  *
- * // With messages from state
+ * // Dynamic message construction
  * const node = new ModelNode(model, {
- *   messages: "conversationMessages",
+ *   messages: (state, context) => [new UserMessage(state.input)],
  *   output: "modelResponse"
  * });
+ *
+ * // With structured output
+ * const structuredModel = model.withStructuredOutput(z.object({
+ *   name: z.string(),
+ *   age: z.number()
+ * }));
+ * const node = new ModelNode(structuredModel, {
+ *   messages: "userInput",
+ *   output: "extractedData"
+ * });
+ *
+ * // Dynamic output transformation
+ * const node = new ModelNode(model, {
+ *   messages: "messages",
+ *   output: (response, state, context) => ({
+ *     modelResponse: response.messages,
+ *     tokenUsage: response.usage,
+ *     timestamp: Date.now()
+ *   })
+ * });
  * ```
  */
 class ModelNode {
     model;
-    settings;
+    config;
     /**
      * Creates a new model node.
      *
-     * @param {BaseModel | StructuredOutputWrapper<any>} model - The model to invoke
-     * @param {ModelNodeSettings<T>} settings - Configuration for message source and output location
+     * @param {M} model - The model to invoke (BaseModel or StructuredOutputWrapper)
+     * @param {ModelNodeConfig<T, M>} config - Configuration for messages, output, system message, and tools
      */
-    constructor(model, settings) {
+    constructor(model, config) {
         this.model = model;
-        this.settings = settings;
+        this.config = config;
     }
     /**
      * Runs the model with configured messages and stores the response in state.
      *
+     * Execution flow:
+     * 1. Resolves messages from config (state key or function)
+     * 2. Applies system message if configured (static or dynamic)
+     * 3. Applies tools if configured and model is not StructuredOutputWrapper (static or dynamic)
+     * 4. Invokes the model with resolved messages
+     * 5. Transforms response based on output config (state key or function)
+     *
+     * For StructuredOutputWrapper: the response is the structured data directly.
+     * For BaseModel: the response contains messages array and usage information.
+     *
      * @param {T} state - The current state
      * @param {ContextLayer} context - The execution context
-     * @returns {Promise<Partial<T>>} Partial state containing the model's response
-     * @throws {Error} If messages path is specified but not found in state
+     * @returns {Promise<Partial<T>>} Partial state update containing the model's response
+     * @throws {Error} If messages key is specified but not found in state, or if the value is not an array
      */
     async run(state, context) {
-        let messages = [];
-        if (isMessagesFunction(this.settings.messages)) {
-            messages = this.settings.messages(state, context);
+        const { messages, output, systemMessage, tools } = this.config;
+        let inMessages = [];
+        if (isMessagesConstructed(messages)) {
+            inMessages = messages(state, context);
         }
         else {
-            const stateMessages = state[this.settings.messages];
+            const stateMessages = state[messages];
             if (!stateMessages || !Array.isArray(stateMessages)) {
-                throw new Error(`No Messages array found for key ${this.settings.messages}`);
+                throw new Error(`No Messages array found for key ${messages}`);
             }
-            messages = stateMessages;
+            inMessages = stateMessages;
+        }
+        if (systemMessage) {
+            let inSystemMessage;
+            if (isSystemMessageDynamic(systemMessage)) {
+                inSystemMessage = systemMessage(state, context);
+            }
+            else {
+                inSystemMessage = systemMessage;
+            }
+            this.model.withSystemMessage(inSystemMessage);
+        }
+        if (tools && !(this.model instanceof BaseModel_1.StructuredOutputWrapper)) {
+            let inTools;
+            if (isToolsDynamic(tools)) {
+                inTools = tools(state, context);
+            }
+            else {
+                inTools = tools;
+            }
+            this.model.withTools(inTools);
         }
         if (this.model instanceof BaseModel_1.StructuredOutputWrapper) {
-            const output = await this.model.invoke(messages);
-            return { [this.settings.output]: output };
+            const structuredOutput = await this.model.invoke(inMessages);
+            if (isOutputConstructed(output)) {
+                return output(structuredOutput, state, context);
+            }
+            else {
+                return { [output]: structuredOutput };
+            }
+        }
+        const response = await this.model.invoke(inMessages);
+        if (isOutputConstructed(output)) {
+            return output(response, state, context);
+        }
+        else {
+            return { [output]: response.messages };
         }
-        const response = await this.model.invoke(messages);
-        return { [this.settings.output]: response.messages };
     }
 }
 exports.ModelNode = ModelNode;

package/dist/nodes/model-node.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-node.js","sourceRoot":"","sources":["../../src/nodes/model-node.ts"],"names":[],"mappings":";;;AACA,mDAAyE;AAMzE;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAoC,KAAU;IACrE,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACvC,CAAC;AA4BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,SAAS;IAQG;IACA;IARrB;;;;;OAKG;IACH,YACqB,KAA+C,EAC/C,QAA8B;QAD9B,UAAK,GAAL,KAAK,CAA0C;QAC/C,aAAQ,GAAR,QAAQ,CAAsB;IAC/C,CAAC;IAEL;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAC,KAAQ,EAAE,OAAqB;QACrC,IAAI,QAAQ,GAAoB,EAAE,CAAC;QACnC,IAAI,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7C,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACJ,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAmB,CAAC,CAAC;YAC/D,IAAI,CAAC,aAAa,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;gBAClD,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,CAAC,QAAQ,CAAC,QAAkB,EAAE,CAAC,CAAC;YAC3F,CAAC;YACD,QAAQ,GAAG,aAAgC,CAAC;QAChD,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,YAAY,mCAAuB,EAAE,CAAC;YAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACjD,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAgB,CAAC;QAC5D,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnD,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,EAAgB,CAAC;IACvE,CAAC;CACJ;AAtCD,8BAsCC"}
+{"version":3,"file":"model-node.js","sourceRoot":"","sources":["../../src/nodes/model-node.ts"],"names":[],"mappings":"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"}

package/dist/nodes/state-transform.d.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { NodeLike } from "./types";
+import { ContextLayer } from "../graphs/runtime-context";
+import { Graph } from "../graphs/graph";
+/**
+ * A node that transforms state between different schemas, allowing nested nodes/graphs
+ * to operate on a different state structure than the parent graph.
+ *
+ * StateTransformNode wraps a node or graph that expects a different state schema.
+ * It handles:
+ * - Input transformation: converts parent state to child state schema
+ * - Schema validation: ensures transformed state matches the child schema
+ * - Output transformation: converts child state back to parent state updates
+ * - Interrupt handling: preserves wrapped state during interrupts for resumption
+ * - State isolation: child state is stored separately during execution
+ *
+ * This is useful when you need to:
+ * - Reuse nodes/graphs with different state schemas
+ * - Isolate state transformations within a workflow
+ * - Compose graphs with incompatible state structures
+ *
+ * @class StateTransformNode
+ * @template PS - Parent state type (the graph's state schema)
+ * @template N - Zod schema object for the child state
+ * @template NS - Child state type (inferred from N)
+ * @implements {NodeLike<PS>}
+ *
+ * @example
+ * ```typescript
+ * // Parent schema
+ * const parentSchema = z.object({
+ *   userId: z.string(),
+ *   userName: z.string(),
+ *   count: z.number()
+ * });
+ *
+ * // Child schema
+ * const childSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   value: z.number()
+ * });
+ *
+ * // Transform parent -> child
+ * const inputTransform = (state: ParentState): ChildState => ({
+ *   id: state.userId,
+ *   name: state.userName,
+ *   value: state.count
+ * });
+ *
+ * // Transform child -> parent
+ * const outputTransform = (state: ChildState): Partial<ParentState> => ({
+ *   count: state.value
+ * });
+ *
+ * // Create transform node wrapping a child node
+ * const childNode = makeNode<ChildState>((state) => ({
+ *   value: state.value + 1
+ * }));
+ *
+ * const transformNode = new StateTransformNode(
+ *   childSchema,
+ *   inputTransform,
+ *   childNode,
+ *   outputTransform
+ * );
+ * ```
+ */
+export declare class StateTransformNode<PS extends Record<string, unknown>, N extends z.ZodObject, NS extends Record<string, unknown> = z.infer<N>> implements NodeLike<PS> {
+    private readonly schema;
+    private readonly input;
+    private readonly node;
+    private readonly output;
+    /**
+     * Creates a new state transform node.
+     *
+     * @param {N} schema - Zod schema object that validates the child state structure
+     * @param {Function} input - Function that transforms parent state to child state
+     * @param {NodeLike<NS> | Graph<N, NS>} node - The node or graph to wrap (operates on child state)
+     * @param {Function} output - Function that transforms child state back to parent state updates
+     */
+    constructor(schema: N, input: (state: PS, context: ContextLayer) => NS, node: NodeLike<NS> | Graph<N, NS>, output: (state: NS, context: ContextLayer) => Partial<PS>);
+    /**
+     * Executes the wrapped node/graph with transformed state.
+     *
+     * Execution flow:
+     * 1. If resuming from interrupt: restores child state from parent state's wrapped key
+     * 2. If not resuming: transforms parent state to child state using input function
+     * 3. Validates transformed state against the child schema
+     * 4. Attaches parent state reference to child state (as __parentState)
+     * 5. Runs the wrapped node/graph with the child state
+     * 6. Merges results back into child state
+     * 7. If interrupted: stores child state in parent state under wrapped key and returns
+     * 8. If completed: transforms child state back to parent state using output function
+     * 9. Cleans up wrapped state key from parent state
+     *
+     * The wrapped state is stored under a key like `__wrappedState_{contextId}.{nodeName}`
+     * to allow resumption after interrupts. This key is automatically cleaned up on completion.
+     *
+     * @param {PS} state - The parent state
+     * @param {ContextLayer} context - The execution context
+     * @returns {Promise<Partial<PS>>} Partial parent state update
+     * @throws {Error} If input transformation doesn't match the child schema (wraps ZodError)
+     * @throws {Error} If the wrapped node/graph throws an error (re-thrown)
+     */
+    run(state: PS, context: ContextLayer): Promise<Partial<PS>>;
+}
+//# sourceMappingURL=state-transform.d.ts.map

package/dist/nodes/state-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-transform.d.ts","sourceRoot":"","sources":["../../src/nodes/state-transform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAGxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,qBAAa,kBAAkB,CAC3B,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,CAAC,SAAS,CAAC,CAAC,SAAS,EACrB,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CACjD,YAAW,QAAQ,CAAC,EAAE,CAAC;IAUjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZ3B;;;;;;;OAOG;gBAEkB,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,KAAK,EAAE,EAC/C,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EACjC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,EAAE,CAAC;IAG9E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;CAyBpE"}

package/dist/nodes/state-transform.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateTransformNode = void 0;
+const zod_1 = require("zod");
+const util_1 = require("../util");
+/**
+ * A node that transforms state between different schemas, allowing nested nodes/graphs
+ * to operate on a different state structure than the parent graph.
+ *
+ * StateTransformNode wraps a node or graph that expects a different state schema.
+ * It handles:
+ * - Input transformation: converts parent state to child state schema
+ * - Schema validation: ensures transformed state matches the child schema
+ * - Output transformation: converts child state back to parent state updates
+ * - Interrupt handling: preserves wrapped state during interrupts for resumption
+ * - State isolation: child state is stored separately during execution
+ *
+ * This is useful when you need to:
+ * - Reuse nodes/graphs with different state schemas
+ * - Isolate state transformations within a workflow
+ * - Compose graphs with incompatible state structures
+ *
+ * @class StateTransformNode
+ * @template PS - Parent state type (the graph's state schema)
+ * @template N - Zod schema object for the child state
+ * @template NS - Child state type (inferred from N)
+ * @implements {NodeLike<PS>}
+ *
+ * @example
+ * ```typescript
+ * // Parent schema
+ * const parentSchema = z.object({
+ *   userId: z.string(),
+ *   userName: z.string(),
+ *   count: z.number()
+ * });
+ *
+ * // Child schema
+ * const childSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   value: z.number()
+ * });
+ *
+ * // Transform parent -> child
+ * const inputTransform = (state: ParentState): ChildState => ({
+ *   id: state.userId,
+ *   name: state.userName,
+ *   value: state.count
+ * });
+ *
+ * // Transform child -> parent
+ * const outputTransform = (state: ChildState): Partial<ParentState> => ({
+ *   count: state.value
+ * });
+ *
+ * // Create transform node wrapping a child node
+ * const childNode = makeNode<ChildState>((state) => ({
+ *   value: state.value + 1
+ * }));
+ *
+ * const transformNode = new StateTransformNode(
+ *   childSchema,
+ *   inputTransform,
+ *   childNode,
+ *   outputTransform
+ * );
+ * ```
+ */
+class StateTransformNode {
+    schema;
+    input;
+    node;
+    output;
+    /**
+     * Creates a new state transform node.
+     *
+     * @param {N} schema - Zod schema object that validates the child state structure
+     * @param {Function} input - Function that transforms parent state to child state
+     * @param {NodeLike<NS> | Graph<N, NS>} node - The node or graph to wrap (operates on child state)
+     * @param {Function} output - Function that transforms child state back to parent state updates
+     */
+    constructor(schema, input, node, output) {
+        this.schema = schema;
+        this.input = input;
+        this.node = node;
+        this.output = output;
+    }
+    /**
+     * Executes the wrapped node/graph with transformed state.
+     *
+     * Execution flow:
+     * 1. If resuming from interrupt: restores child state from parent state's wrapped key
+     * 2. If not resuming: transforms parent state to child state using input function
+     * 3. Validates transformed state against the child schema
+     * 4. Attaches parent state reference to child state (as __parentState)
+     * 5. Runs the wrapped node/graph with the child state
+     * 6. Merges results back into child state
+     * 7. If interrupted: stores child state in parent state under wrapped key and returns
+     * 8. If completed: transforms child state back to parent state using output function
+     * 9. Cleans up wrapped state key from parent state
+     *
+     * The wrapped state is stored under a key like `__wrappedState_{contextId}.{nodeName}`
+     * to allow resumption after interrupts. This key is automatically cleaned up on completion.
+     *
+     * @param {PS} state - The parent state
+     * @param {ContextLayer} context - The execution context
+     * @returns {Promise<Partial<PS>>} Partial parent state update
+     * @throws {Error} If input transformation doesn't match the child schema (wraps ZodError)
+     * @throws {Error} If the wrapped node/graph throws an error (re-thrown)
+     */
+    async run(state, context) {
+        const wrappedStateKey = `__wrappedState_${context.id}.${context.currentNode}`;
+        try {
+            let nodeState;
+            if (context.runtime.resuming) {
+                nodeState = { ...state[wrappedStateKey], __parentState: state };
+            }
+            else {
+                const inputTransformed = this.input(state, context);
+                nodeState = { ...this.schema.parse(inputTransformed), __parentState: state };
+            }
+            const result = await this.node.run((0, util_1.cloneAware)(nodeState), context);
+            nodeState = { ...nodeState, ...result };
+            if (context.runtime.interrupted) {
+                const { __parentState, ...rest } = nodeState;
+                return { [wrappedStateKey]: rest };
+            }
+            const outState = this.output(nodeState, context);
+            return { ...outState, [wrappedStateKey]: undefined };
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                throw new Error(`Transformed input does not match schema: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}
+exports.StateTransformNode = StateTransformNode;
+//# sourceMappingURL=state-transform.js.map

package/dist/nodes/state-transform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-transform.js","sourceRoot":"","sources":["../../src/nodes/state-transform.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAIxB,kCAAqC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAa,kBAAkB;IAcN;IACA;IACA;IACA;IAZrB;;;;;;;OAOG;IACH,YACqB,MAAS,EACT,KAA+C,EAC/C,IAAiC,EACjC,MAAyD;QAHzD,WAAM,GAAN,MAAM,CAAG;QACT,UAAK,GAAL,KAAK,CAA0C;QAC/C,SAAI,GAAJ,IAAI,CAA6B;QACjC,WAAM,GAAN,MAAM,CAAmD;IAC1E,CAAC;IAEL;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,GAAG,CAAC,KAAS,EAAE,OAAqB;QACtC,MAAM,eAAe,GAAG,kBAAkB,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QAC9E,IAAI,CAAC;YACD,IAAI,SAAa,CAAC;YAClB,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBAC3B,SAAS,GAAG,EAAE,GAAG,KAAK,CAAC,eAAe,CAAO,EAAE,aAAa,EAAE,KAAK,EAAQ,CAAC;YAChF,CAAC;iBAAM,CAAC;gBACJ,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBACpD,SAAS,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,aAAa,EAAE,KAAK,EAAQ,CAAC;YACvF,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAA,iBAAU,EAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;YACnE,SAAS,GAAG,EAAE,GAAG,SAAS,EAAE,GAAG,MAAM,EAAQ,CAAC;YAC9C,IAAI,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;gBAC9B,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,CAAC;gBAC7C,OAAO,EAAE,CAAC,eAAe,CAAC,EAAE,IAAI,EAAiB,CAAC;YACtD,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACjD,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC,eAAe,CAAC,EAAE,SAAS,EAAiB,CAAC;QACxE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,KAAK,YAAY,OAAC,CAAC,QAAQ,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,4CAA4C,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACjF,CAAC;YACD,MAAM,KAAK,CAAC;QAChB,CAAC;IACL,CAAC;CACJ;AApED,gDAoEC"}

package/dist/tools.d.ts

@@ -7,10 +7,10 @@ import * as z from "zod";
  * @property {string} [description] - Human-readable description of what the tool does
  * @property {z.ZodSchema<T>} schema - Zod schema that validates the tool's input parameters
  */
-export interface ToolDefinition<T = object> {
+export interface ToolDefinition<T = z.ZodObject> {
     name: string;
     description?: string;
-    schema: z.ZodSchema<T>;
+    schema: T;
 }
 /**
  * Creates a tool definition with validation schema.
@@ -31,24 +31,26 @@ export interface ToolDefinition<T = object> {
  * );
  * ```
  */
-export declare function defineTool<T>(name: string, description: string, schema: z.ZodSchema<T>): ToolDefinition<T>;
+export declare function defineTool<T extends z.ZodObject>(name: string, description: string, schema: T): ToolDefinition<T>;
 /**
  * Internal interface extending ToolDefinition with the actual implementation function.
  *
  * @template T - The input type for the tool
  * @template K - The output type returned by the tool function
+ * @template A - The additional arguments type
  */
-interface ToolImplementation<T, K> extends ToolDefinition<T> {
-    func: (input: T) => K | Promise<K>;
+export interface ToolImplementation<T extends z.ZodObject, K, A extends Record<string, any>> extends ToolDefinition<T> {
+    func: (input: z.infer<T>, additionalArgs?: A) => K | Promise<K>;
 }
 /**
  * Creates a complete tool implementation by combining a tool definition with its function.
  *
  * @template T - The input parameter type
  * @template K - The return type of the tool function
+ * @template A - The additional arguments type
  * @param {ToolDefinition<T>} toolDefinition - The tool definition created with defineTool()
- * @param {(input: T) => K | Promise<K>} func - The function that implements the tool's behavior
- * @returns {ToolImplementation<T, K>} A complete tool with both definition and implementation
+ * @param {(input: T, additionalArgs?: Record<string, any>) => K | Promise<K>} func - The function that implements the tool's behavior
+ * @returns {ToolImplementation<T, K, A>} A complete tool with both definition and implementation
  *
  * @example
  * ```typescript
@@ -60,6 +62,5 @@ interface ToolImplementation<T, K> extends ToolDefinition<T> {
  * );
  * ```
  */
-export declare function tool<T, K>(toolDefinition: ToolDefinition<T>, func: (input: T) => K | Promise<K>): ToolImplementation<T, K>;
-export {};
+export declare function tool<T extends z.ZodObject, K, A extends Record<string, any>>(toolDefinition: ToolDefinition<T>, func: (input: z.infer<T>, additionalArgs?: A) => K | Promise<K>): ToolImplementation<T, K, A>;
 //# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,MAAM;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,CAAC,CAAC,CAMnB;AAED;;;;;GAKG;AACH,UAAU,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACxD,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EACrB,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACnC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAK1B"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,CAAC,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAC5C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,GACV,cAAc,CAAC,CAAC,CAAC,CAMnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IAClH,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxE,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAK7B"}

package/dist/tools.js

@@ -33,9 +33,10 @@ function defineTool(name, description, schema) {
  *
  * @template T - The input parameter type
  * @template K - The return type of the tool function
+ * @template A - The additional arguments type
  * @param {ToolDefinition<T>} toolDefinition - The tool definition created with defineTool()
- * @param {(input: T) => K | Promise<K>} func - The function that implements the tool's behavior
- * @returns {ToolImplementation<T, K>} A complete tool with both definition and implementation
+ * @param {(input: T, additionalArgs?: Record<string, any>) => K | Promise<K>} func - The function that implements the tool's behavior
+ * @returns {ToolImplementation<T, K, A>} A complete tool with both definition and implementation
  *
  * @example
  * ```typescript

package/dist/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":";;AAmCA,gCAUC;AA+BD,oBAQC;AApED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,UAAU,CACtB,IAAY,EACZ,WAAmB,EACnB,MAAsB;IAEtB,OAAO;QACH,IAAI;QACJ,WAAW;QACX,MAAM;KACT,CAAC;AACN,CAAC;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,IAAI,CAChB,cAAiC,EACjC,IAAkC;IAElC,OAAO;QACH,GAAG,cAAc;QACjB,IAAI;KACP,CAAC;AACN,CAAC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":";;AAmCA,gCAUC;AAiCD,oBAQC;AAtED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,UAAU,CACtB,IAAY,EACZ,WAAmB,EACnB,MAAS;IAET,OAAO;QACH,IAAI;QACJ,WAAW;QACX,MAAM;KACT,CAAC;AACN,CAAC;AAaD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,IAAI,CAChB,cAAiC,EACjC,IAA+D;IAE/D,OAAO;QACH,GAAG,cAAc;QACjB,IAAI;KACP,CAAC;AACN,CAAC"}

package/dist/util/clone-aware.d.ts

@@ -0,0 +1,2 @@
+export declare function cloneAware<T extends object | Array<unknown> | unknown>(value: T): T;
+//# sourceMappingURL=clone-aware.d.ts.map

package/dist/util/clone-aware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-aware.d.ts","sourceRoot":"","sources":["../../src/util/clone-aware.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAyBnF"}

package/dist/util/clone-aware.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneAware = cloneAware;
+const serializer_1 = require("./serializer");
+// this creates a deep clone of something - an object, array, or primitive - while being aware of the classes that can be serialized/deserialized
+function cloneAware(value) {
+    if (typeof value === "object" && value !== null) {
+        // The value is a class
+        if ('constructor' in value && !["Object", "Array"].includes(value.constructor.name)) {
+            return (0, serializer_1.deserialize)((0, serializer_1.serialize)(value));
+        }
+        // The value is an array
+        if (Array.isArray(value)) {
+            const newArr = [];
+            for (const item of value) {
+                newArr.push(cloneAware(item));
+            }
+            return newArr;
+        }
+        // The value is a plain object
+        const newObj = {};
+        for (const key in value) {
+            newObj[key] = cloneAware(value[key]);
+        }
+        return newObj;
+    }
+    return value;
+}
+//# sourceMappingURL=clone-aware.js.map

package/dist/util/clone-aware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-aware.js","sourceRoot":"","sources":["../../src/util/clone-aware.ts"],"names":[],"mappings":";;AAGA,gCAyBC;AA5BD,6CAAsD;AAEtD,iJAAiJ;AACjJ,SAAgB,UAAU,CAA8C,KAAQ;IAC5E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC9C,uBAAuB;QACvB,IAAI,aAAa,IAAI,KAAK,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YAClF,OAAO,IAAA,wBAAW,EAAC,IAAA,sBAAS,EAAC,KAAK,CAAC,CAAM,CAAC;QAC9C,CAAC;QAED,wBAAwB;QACxB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,EAAE,CAAC;YAClB,KAAK,MAAM,IAAI,IAAI,KAAuB,EAAE,CAAC;gBACzC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;YAClC,CAAC;YACD,OAAO,MAAW,CAAC;QACvB,CAAC;QAED,8BAA8B;QAC9B,MAAM,MAAM,GAAG,EAA6B,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,KAAgC,EAAE,CAAC;YACjD,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,MAAW,CAAC;IAEvB,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/util/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./clone-aware";
+export * from "./merge-state";
+export * from "./serializer";
+//# sourceMappingURL=index.d.ts.map

package/dist/util/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/util/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./clone-aware"), exports);
+__exportStar(require("./merge-state"), exports);
+__exportStar(require("./serializer"), exports);
+//# sourceMappingURL=index.js.map

package/dist/util/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,gDAA8B;AAC9B,+CAA6B"}