@ellyco/agentic 0.2.0 → 0.2.1

package/dist/graphs/graph.js

@@ -7,7 +7,7 @@ const zod_1 = require("zod");
 const merge_state_1 = require("../util/merge-state");
 const api_1 = require("@opentelemetry/api");
 const util_1 = require("../util");
-const tracer = api_1.trace.getTracer("@ellyco/agentic", "0.2.0");
+const tracer = api_1.trace.getTracer("@ellyco/agentic", "0.2.1");
 /**
  * Special node name indicating the start of graph execution
  */
@@ -309,7 +309,7 @@ class Graph {
                 runtime.unwrapCursor(load.cursor);
             }
             try {
-                const state = this.schema.parse(mergedState);
+                const state = this.schema.loose().parse(mergedState);
                 const result = await this.run(state, runtime);
                 const finalState = { ...state, ...result };
                 if (runtime.interrupted) {
@@ -348,7 +348,7 @@ class Graph {
                 runtime.unwrapCursor(config.resumeFrom);
             }
             try {
-                const state = this.schema.parse(fullInput);
+                const state = this.schema.loose().parse(fullInput);
                 const result = await this.run(state, runtime);
                 const finalState = { ...state, ...result };
                 if (runtime.interrupted) {

package/dist/graphs/graph.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/graphs/graph.ts"],"names":[],"mappings":";;;AAEA,uDAAiE;AAEjE,gDAAgD;AAChD,6BAAwB;AACxB,qDAAiD;AACjD,4CAAsD;AACtD,kCAAqC;AAErC,MAAM,MAAM,GAAG,WAAK,CAAC,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;AAO3D;;GAEG;AACU,QAAA,KAAK,GAAG,OAAO,CAAC;AAE7B;;GAEG;AACU,QAAA,GAAG,GAAG,KAAK,CAAC;AA4BzB;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,MAAmC;IAC1D,OAAO,OAAO,IAAI,MAAM,CAAC;AAC7B,CAAC;AAQD;;;;;;;;;;;;;GAaG;AACI,MAAM,wBAAwB,GAAG,CAAI,WAAuC,EAAmC,EAAE;IACpH,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,OAAO,WAA8C,CAAC;AAC1D,CAAC,CAAA;AAHY,QAAA,wBAAwB,4BAGpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAsB,KAAK;IA0DQ;IArD/B;;OAEG;IACa,OAAO,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACO,KAAK,GAAiC,EAAE,CAAC;IAEnD;;OAEG;IACO,KAAK,GAA2B,EAAE,CAAC;IAE7C;;OAEG;IACO,gBAAgB,GAA6B,EAAE,CAAC;IAE1D;;OAEG;IACO,gBAAgB,GAAiE,EAAE,CAAC;IAyB9F;;;;OAIG;IACH,YAA+B,MAAS;QAAT,WAAM,GAAN,MAAM,CAAG;IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACO,UAAU,CAAC,KAAQ,EAAE,OAAqB;QAChD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAY,CAAC;QACzC,IAAI,WAAW,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAE,CAAC;QACnD,CAAC;aAAM,IAAI,WAAW,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC9C,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAE,CAAC;YAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAE,CACjD,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,EACrC,OAAO,CACV,CAAC;YACF,IAAI,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBACvC,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACJ,MAAM,IAAI,KAAK,CACX,gCAAgC,WAAW,mBAAmB,SAAS,EAAE,CAC5E,CAAC;YACN,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,MAAM,IAAI,KAAK,CACX,oDAAoD,WAAW,EAAE,CACpE,CAAC;QACN,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACO,KAAK,CAAC,IAAI,CAAC,KAAQ,EAAE,OAAqB;QAChD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAY,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAE,CAAC;QACtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,QAAQ,WAAW,YAAY,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,MAAM,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE;YAC7C,UAAU,EAAE;gBACR,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK;gBAC5B,QAAQ,EAAE,WAAW;gBACrB,OAAO,EAAE,OAAO,CAAC,EAAE;aACtB;SACJ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACd,IAAI,CAAC;gBACD,MAAM,cAAc,GAAG,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAC7D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CACzB,IAAA,iBAAU,EAAC,cAAc,CAAC,EAC1B,OAAO,CACV,CAAC;gBACF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACnC,IAAI,CAAC,aAAa,CAAC;wBACf,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;wBAC3B,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;qBAClC,CAAC,CAAC;oBACH,OAAO,KAAK,CAAC;gBACjB,CAAC;gBACD,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBACvD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBACpD,IAAI,CAAC,aAAa,CAAC;oBACf,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;oBAChC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;iBACxC,CAAC,CAAC;gBACH,OAAO,WAAW,CAAC;YACvB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,iCAAiC,OAAO,CAAC,EAAE,IAAI,WAAW,EAAE,CAAC,CAAC;gBAC5E,IAAI,CAAC,eAAe,CAAC,KAA6B,CAAC,CAAC;gBACpD,MAAM,KAAK,CAAC;YAChB,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,IAAI,CAAC,CAAC,aAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,aAAK,IAAI,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CACX,uDAAuD,aAAK,EAAE,CACjE,CAAC;QACN,CAAC;QACD,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,EAAE,KAAK,WAAG,EAAE,CAAC;gBACb,QAAQ,GAAG,IAAI,CAAC;YACpB,CAAC;QACL,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3D,IAAI,EAAE,CAAC,QAAQ,CAAC,WAAG,CAAC,EAAE,CAAC;gBACnB,QAAQ,GAAG,IAAI,CAAC;YACpB,CAAC;QACL,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACX,qDAAqD,WAAG,EAAE,CAC7D,CAAC;QACN,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACO,KAAK,CAAC,WAAW,CAAC,KAAQ,EAAE,OAAqB;QACvD,IAAI,KAAK,GAAG,IAAA,iBAAU,EAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,cAAc,GAAG,IAAI,CAAC;QAC1B,OAAO,cAAc,EAAE,CAAC;YACpB,MAAM,WAAW,GAAG,OAAO,CAAC,WAAY,CAAC;YACzC,qEAAqE;YACrE,IAAI,WAAW,KAAK,WAAG,EAAE,CAAC;gBACtB,cAAc,GAAG,KAAK,CAAC;gBACvB,MAAM;YACV,CAAC;YACD,wEAAwE;YACxE,IAAI,WAAW,KAAK,aAAK,EAAE,CAAC;gBACxB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAChC,SAAS;YACb,CAAC;YAED,KAAK,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;YAE3D,IAAI,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;gBAC9B,cAAc,GAAG,KAAK,CAAC;gBACvB,MAAM;YACV,CAAC;YAED,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;OAOG;IACO,UAAU,CAAC,KAAQ,EAAE,OAAmB;QAC9C,OAAO,IAAA,wBAAU,EAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAC,KAAQ,EAAE,gBAA+C;QAC/D,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACpC,OAAO,CAAC,WAAW,GAAG,aAAK,CAAC;QAChC,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,MAAM,CAAC;IAClB,CAAC;IAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,MAAM,CAAC,KAAqB,EAAE,MAAoC;QACpE,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAA,gBAAQ,GAAE,CAAE,CAAC;QAEzE,IAAI,MAAM,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,MAAM,YAAY,GAAG,KAAmB,CAAC;YACzC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YACnD,MAAM,OAAO,GAAG,IAAI,gCAAc,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAErD,IAAI,WAAW,GAAM,YAAiB,CAAC;YACvC,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,CAAC;YAC7C,IAAI,WAAW,EAAE,CAAC;gBACd,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;gBACpC,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;gBACvD,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,CAAC;gBACD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAM,CAAC;gBAElD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAE9C,MAAM,UAAU,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,EAAE,CAAA;gBAC1C,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;oBACtB,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,UAAU,CAAC,CAAC;oBACvD,OAAO;wBACH,KAAK;wBACL,KAAK,EAAE,UAAU;wBACjB,UAAU,EAAE,WAAW;wBACvB,WAAW,EAAE,OAAO,CAAC,WAAW;wBAChC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;qBAC/B,CAAC;gBACN,CAAC;gBACD,IAAI,MAAM,EAAE,cAAc,EAAE,CAAC;oBACzB,MAAM,SAAS,CAAC,MAAM,EAAE,CAAC;gBAC7B,CAAC;qBAAM,CAAC;oBACJ,MAAM,SAAS,CAAC,IAAI,CAAC,WAAG,EAAE,UAAU,CAAC,CAAC;gBAC1C,CAAC;gBACD,OAAO;oBACH,KAAK;oBACL,KAAK,EAAE,UAAU;oBACjB,UAAU,EAAE,KAAK;iBACpB,CAAC;YACN,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,KAAK,YAAY,OAAC,CAAC,QAAQ,EAAE,CAAC;oBAC9B,MAAM,IAAI,KAAK,CAAC,gCAAgC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;gBACrE,CAAC;gBACD,MAAM,KAAK,CAAC;YAChB,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,MAAM,SAAS,GAAG,KAAU,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,gCAAc,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,MAAM,EAAE,UAAU,EAAE,CAAC;gBACrB,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC5C,CAAC;YACD,IAAI,CAAC;gBACD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAM,CAAC;gBAEhD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAE9C,MAAM,UAAU,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,EAAE,CAAA;gBAC1C,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;oBACtB,OAAO;wBACH,KAAK;wBACL,KAAK,EAAE,UAAU;wBACjB,UAAU,EAAE,WAAW;wBACvB,WAAW,EAAE,OAAO,CAAC,WAAW;wBAChC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;qBAC/B,CAAC;gBACN,CAAC;gBACD,OAAO;oBACH,KAAK;oBACL,KAAK,EAAE,UAAU;oBACjB,UAAU,EAAE,KAAK;iBACpB,CAAC;YACN,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,KAAK,YAAY,OAAC,CAAC,QAAQ,EAAE,CAAC;oBAC9B,MAAM,IAAI,KAAK,CAAC,gCAAgC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;gBACrE,CAAC;gBACD,MAAM,KAAK,CAAC;YAChB,CAAC;QACL,CAAC;IACL,CAAC;CACJ;AAjXD,sBAiXC"}
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/graphs/graph.ts"],"names":[],"mappings":"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"}

package/dist/nodes/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./function-node";
 export * from "./interrupt-node";
 export * from "./model-node";
+export * from "./state-transform";
 export * from "./types";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/nodes/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/nodes/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC"}

package/dist/nodes/index.js

@@ -17,5 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./function-node"), exports);
 __exportStar(require("./interrupt-node"), exports);
 __exportStar(require("./model-node"), exports);
+__exportStar(require("./state-transform"), exports);
 __exportStar(require("./types"), exports);
 //# sourceMappingURL=index.js.map

package/dist/nodes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/nodes/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,mDAAiC;AACjC,+CAA6B;AAC7B,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/nodes/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,mDAAiC;AACjC,+CAA6B;AAC7B,oDAAkC;AAClC,0CAAwB"}

package/dist/nodes/model-node.d.ts

@@ -1,70 +1,252 @@
-import { ModelMessages } from "../messages";
-import { BaseModel, StructuredOutputWrapper } from "../models/BaseModel";
+import { AgentMessage, ModelMessages, SystemMessage, ToolRequest } from "../messages";
+import { BaseModel, InvokeResponse, StructuredOutputWrapper } from "../models/BaseModel";
 import { NodeLike } from "./types";
 import { ContextLayer } from "../graphs/runtime-context";
 import { TypedKeys } from "../types";
+import { ToolDefinition } from "../tools";
 /**
  * Helper type to extract keys from an object that have ModelMessages[] values.
+ *
+ * @private
+ */
+type InputMessagesKeys<T> = TypedKeys<T, ModelMessages[]>;
+/**
+ * Helper type to extract keys from an object that have (AgentMessage | ToolRequest)[] values.
+ *
+ * @private
+ */
+type OutputMessagesKeys<T> = TypedKeys<T, (AgentMessage | ToolRequest)[]>;
+/**
+ * Configuration for selecting messages from state by key.
+ *
+ * @interface MessageSelected
+ * @template T - The state type
  */
-type MessagesKeys<T> = TypedKeys<T, ModelMessages[]>;
+interface MessageSelected<T> {
+    /** Key in state containing the messages array */
+    messages: InputMessagesKeys<T>;
+}
 /**
- * Configuration for messages provided through a function.
+ * Configuration for constructing messages dynamically from state and context.
+ *
+ * @interface MessageConstructed
+ * @template T - The state type
  */
-interface ConstructedMessages<T extends Record<string, unknown>> {
+interface MessageConstructed<T> {
+    /** Function that generates messages from current state and context */
     messages: (state: T, context: ContextLayer) => ModelMessages[];
 }
 /**
- * Configuration for messages provided through a state path.
+ * Union type for message configuration - either selected from state or constructed dynamically.
+ *
+ * @typedef {MessageSelected<T> | MessageConstructed<T>} MessageConfig
+ * @template T - The state type
+ */
+type MessageConfig<T> = MessageSelected<T> | MessageConstructed<T>;
+/**
+ * Configuration for selecting output location from state by key.
+ *
+ * @interface OutputSelected
+ * @template T - The state type
+ * @template M - The model type (BaseModel or StructuredOutputWrapper)
  */
-interface MessagesPath<T> {
-    messages: MessagesKeys<T>;
+interface OutputSelected<T, M extends BaseModel | StructuredOutputWrapper<any>> {
+    /**
+     * Key in state where output should be stored.
+     * For StructuredOutputWrapper: any key in state.
+     * For BaseModel: key that contains (AgentMessage | ToolRequest)[] array.
+     */
+    output: M extends StructuredOutputWrapper<any> ? keyof T : OutputMessagesKeys<T>;
 }
 /**
- * Settings for a ModelNode specifying where to get messages and where to store output.
+ * Configuration for constructing output dynamically from model response.
+ *
+ * @interface OutputConstructed
+ * @template T - The state type
+ * @template M - The model type (BaseModel or StructuredOutputWrapper)
+ */
+interface OutputConstructed<T, M extends BaseModel | StructuredOutputWrapper<any>> {
+    /**
+     * Function that transforms model response into partial state update.
+     * For StructuredOutputWrapper: receives the structured output directly.
+     * For BaseModel: receives InvokeResponse with messages array.
+     */
+    output: (response: M extends StructuredOutputWrapper<any> ? any : InvokeResponse, state: T, context: ContextLayer) => Partial<T>;
+}
+/**
+ * Union type for output configuration - either selected key or constructed dynamically.
+ *
+ * @typedef {OutputSelected<T, M> | OutputConstructed<T, M>} OutputConfig
+ * @template T - The state type
+ * @template M - The model type (BaseModel or StructuredOutputWrapper)
  */
-type ModelNodeSettings<T extends Record<string, unknown>> = {
-    output: keyof T;
-} & (ConstructedMessages<T> | MessagesPath<T>);
+type OutputConfig<T, M extends BaseModel | StructuredOutputWrapper<any>> = OutputSelected<T, M> | OutputConstructed<T, M>;
+/**
+ * Configuration for a static system message.
+ *
+ * @interface SystemMessageStatic
+ */
+interface SystemMessageStatic {
+    /** Static system message to use for all invocations */
+    systemMessage: SystemMessage;
+}
+/**
+ * Configuration for a dynamically generated system message.
+ *
+ * @interface SystemMessageDynamic
+ * @template T - The state type
+ */
+interface SystemMessageDynamic<T> {
+    /** Function that generates system message from current state and context */
+    systemMessage: (state: T, context: ContextLayer) => SystemMessage;
+}
+/**
+ * Union type for system message configuration - either static or dynamic.
+ *
+ * @typedef {SystemMessageStatic | SystemMessageDynamic<T>} SystemMessageConfig
+ * @template T - The state type
+ */
+type SystemMessageConfig<T> = SystemMessageStatic | SystemMessageDynamic<T>;
+/**
+ * Configuration for static tool definitions.
+ *
+ * @interface ToolsStatic
+ */
+interface ToolsStatic {
+    /** Array of tool definitions to use for all invocations */
+    tools: ToolDefinition[];
+}
+/**
+ * Configuration for dynamically generated tool definitions.
+ *
+ * @interface ToolsDynamic
+ * @template T - The state type
+ */
+interface ToolsDynamic<T> {
+    /** Function that generates tool definitions from current state and context */
+    tools: (state: T, context: ContextLayer) => ToolDefinition[];
+}
+/**
+ * Union type for tools configuration - either static or dynamic.
+ *
+ * @typedef {ToolsStatic | ToolsDynamic<T>} ToolsConfig
+ * @template T - The state type
+ */
+type ToolsConfig<T> = ToolsStatic | ToolsDynamic<T>;
+/**
+ * Configuration object for ModelNode.
+ *
+ * @typedef {Object} ModelNodeConfig
+ * @template T - The state type
+ * @template M - The model type (BaseModel or StructuredOutputWrapper)
+ *
+ * @property {MessageConfig<T>} messages - Configuration for message source (key or function)
+ * @property {OutputConfig<T, M>} output - Configuration for output destination (key or function)
+ * @property {SystemMessageConfig<T>} [systemMessage] - Optional system message (static or dynamic)
+ * @property {ToolsConfig<T>} [tools] - Optional tool definitions (static or dynamic). Ignored when using StructuredOutputWrapper.
+ *
+ * @example
+ * ```typescript
+ * // Static configuration
+ * const config: ModelNodeConfig<MyState, BaseModel> = {
+ *   messages: "conversationHistory",
+ *   output: "modelResponse",
+ *   systemMessage: new SystemMessage("You are helpful"),
+ *   tools: [searchTool, calculatorTool]
+ * };
+ *
+ * // Dynamic configuration
+ * const dynamicConfig: ModelNodeConfig<MyState, BaseModel> = {
+ *   messages: (state, context) => state.messages.filter(m => m.role === "user"),
+ *   output: (response, state, context) => ({
+ *     modelResponse: response.messages,
+ *     tokenUsage: response.usage
+ *   }),
+ *   systemMessage: (state, context) => new SystemMessage(`Context: ${state.context}`),
+ *   tools: (state, context) => state.availableTools
+ * };
+ * ```
+ */
+export type ModelNodeConfig<T extends Record<string, unknown>, M extends BaseModel | StructuredOutputWrapper<any>> = OutputConfig<T, M> & MessageConfig<T> & Partial<SystemMessageConfig<T> & ToolsConfig<T>>;
 /**
  * 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()
+ *   })
+ * });
  * ```
  */
-export declare class ModelNode<T extends Record<string, unknown>> implements NodeLike<T> {
+export declare class ModelNode<T extends Record<string, unknown>, M extends BaseModel | StructuredOutputWrapper<any> = BaseModel> implements NodeLike<T> {
     private readonly model;
-    private readonly settings;
+    private readonly 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: BaseModel | StructuredOutputWrapper<any>, settings: ModelNodeSettings<T>);
+    constructor(model: M, config: ModelNodeConfig<T, M>);
     /**
      * 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
      */
     run(state: T, context: ContextLayer): Promise<Partial<T>>;
 }

package/dist/nodes/model-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-node.d.ts","sourceRoot":"","sources":["../../src/nodes/model-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAcrC;;GAEG;AACH,KAAK,YAAY,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;AAErD;;GAEG;AACH,UAAU,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,KAAK,aAAa,EAAE,CAAC;CAClE;AAED;;GAEG;AACH,UAAU,YAAY,CAAC,CAAC;IACpB,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACpD;IAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACjB,CAAC,mBAAmB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;IAQxE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR7B;;;;;OAKG;gBAEkB,KAAK,EAAE,SAAS,GAAG,uBAAuB,CAAC,GAAG,CAAC,EAC/C,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAGnD;;;;;;;OAOG;IACG,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAkBlE"}
+{"version":3,"file":"model-node.d.ts","sourceRoot":"","sources":["../../src/nodes/model-node.ts"],"names":[],"mappings":"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"}

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,7 +31,7 @@ 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.
  *
@@ -39,8 +39,8 @@ export declare function defineTool<T>(name: string, description: string, schema:
  * @template K - The output type returned by the tool function
  * @template A - The additional arguments type
  */
-export interface ToolImplementation<T, K, A extends Record<string, any>> extends ToolDefinition<T> {
-    func: (input: T, additionalArgs?: A) => 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.
@@ -62,5 +62,5 @@ export interface ToolImplementation<T, K, A extends Record<string, any>> extends
  * );
  * ```
  */
-export declare function tool<T, K, A extends Record<string, any>>(toolDefinition: ToolDefinition<T>, func: (input: T, additionalArgs?: A) => K | Promise<K>): ToolImplementation<T, K, A>;
+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;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IAC9F,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACpD,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvD,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAK7B"}
+{"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.map

@@ -1 +1 @@
-{"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,MAAsB;IAEtB,OAAO;QACH,IAAI;QACJ,WAAW;QACX,MAAM;KACT,CAAC;AACN,CAAC;AAaD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,IAAI,CAChB,cAAiC,EACjC,IAAsD;IAEtD,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/merge-state.d.ts

@@ -1,21 +1,49 @@
 import { z } from "zod";
 /**
  * Merges partial state updates into a base state object.
- * Uses registered custom merge strategies for specific types.
- * Falls back to standard object/array merge behavior.
+ *
+ * Uses registered custom merge strategies for specific types when available.
+ * Falls back to standard merge behavior based on value types:
+ * - Undefined/null keys: Set the new value directly
+ * - Custom merge functions: Use registered strategy (handles entire value including nested)
+ * - Class instances: Replace directly (preserves object identity)
+ * - Arrays: Replace entire array (no element-level merging)
+ * - Plain objects: Recursively merge nested properties
+ * - Primitives: Replace the value
+ *
+ * The merge process uses `cloneAware()` to create a deep clone of the base state,
+ * ensuring the original state is not mutated while preserving class instances.
  *
  * @template T - The state object type
- * @param {T} base - The base state to merge into
- * @param {Partial<T>} changes - Partial state with updates
- * @param {z.ZodObject} schema - Zod schema for the state type
- * @returns {T} Merged state object
+ * @param {T} base - The base state to merge into (will not be mutated)
+ * @param {Partial<T>} changes - Partial state with updates to apply
+ * @param {z.ZodObject} schema - Zod schema for the state type (used to look up custom merge strategies)
+ * @returns {T} New merged state object (base is not mutated)
  *
  * @example
  * ```typescript
- * const base = { count: 5, items: [1, 2, 3] };
- * const changes = { count: 10, items: [4] };
+ * // Basic merge
+ * const base = { count: 5, items: [1, 2, 3], user: { name: "Alice" } };
+ * const changes = { count: 10, user: { age: 30 } };
  * const merged = mergeState(base, changes, schema);
- * // Results in { count: 10, items: [4] }
+ * // Results in { count: 10, items: [1, 2, 3], user: { name: "Alice", age: 30 } }
+ *
+ * // Array replacement (arrays are replaced, not merged)
+ * const base2 = { items: [1, 2, 3] };
+ * const changes2 = { items: [4, 5] };
+ * const merged2 = mergeState(base2, changes2, schema);
+ * // Results in { items: [4, 5] } (not [1, 2, 3, 4, 5])
+ *
+ * // Custom merge strategy (if registered)
+ * const schema = z.object({
+ *   count: z.number().register(STATE_MERGE, {
+ *     merge: (old, change) => old + change // Additive merge
+ *   })
+ * });
+ * const base3 = { count: 5 };
+ * const changes3 = { count: 3 };
+ * const merged3 = mergeState(base3, changes3, schema);
+ * // Results in { count: 8 } (5 + 3, not 3)
  * ```
  */
 export declare function mergeState<T extends Record<string, any>>(base: T, changes: Partial<T>, schema: z.ZodObject): T;

package/dist/util/merge-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge-state.d.ts","sourceRoot":"","sources":["../../src/util/merge-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,CAgC9G"}
+{"version":3,"file":"merge-state.d.ts","sourceRoot":"","sources":["../../src/util/merge-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,CAkC9G"}

package/dist/util/merge-state.js

@@ -5,51 +5,81 @@ const registry_1 = require("../graphs/registry");
 const clone_aware_1 = require("./clone-aware");
 /**
  * Merges partial state updates into a base state object.
- * Uses registered custom merge strategies for specific types.
- * Falls back to standard object/array merge behavior.
+ *
+ * Uses registered custom merge strategies for specific types when available.
+ * Falls back to standard merge behavior based on value types:
+ * - Undefined/null keys: Set the new value directly
+ * - Custom merge functions: Use registered strategy (handles entire value including nested)
+ * - Class instances: Replace directly (preserves object identity)
+ * - Arrays: Replace entire array (no element-level merging)
+ * - Plain objects: Recursively merge nested properties
+ * - Primitives: Replace the value
+ *
+ * The merge process uses `cloneAware()` to create a deep clone of the base state,
+ * ensuring the original state is not mutated while preserving class instances.
  *
  * @template T - The state object type
- * @param {T} base - The base state to merge into
- * @param {Partial<T>} changes - Partial state with updates
- * @param {z.ZodObject} schema - Zod schema for the state type
- * @returns {T} Merged state object
+ * @param {T} base - The base state to merge into (will not be mutated)
+ * @param {Partial<T>} changes - Partial state with updates to apply
+ * @param {z.ZodObject} schema - Zod schema for the state type (used to look up custom merge strategies)
+ * @returns {T} New merged state object (base is not mutated)
  *
  * @example
  * ```typescript
- * const base = { count: 5, items: [1, 2, 3] };
- * const changes = { count: 10, items: [4] };
+ * // Basic merge
+ * const base = { count: 5, items: [1, 2, 3], user: { name: "Alice" } };
+ * const changes = { count: 10, user: { age: 30 } };
  * const merged = mergeState(base, changes, schema);
- * // Results in { count: 10, items: [4] }
+ * // Results in { count: 10, items: [1, 2, 3], user: { name: "Alice", age: 30 } }
+ *
+ * // Array replacement (arrays are replaced, not merged)
+ * const base2 = { items: [1, 2, 3] };
+ * const changes2 = { items: [4, 5] };
+ * const merged2 = mergeState(base2, changes2, schema);
+ * // Results in { items: [4, 5] } (not [1, 2, 3, 4, 5])
+ *
+ * // Custom merge strategy (if registered)
+ * const schema = z.object({
+ *   count: z.number().register(STATE_MERGE, {
+ *     merge: (old, change) => old + change // Additive merge
+ *   })
+ * });
+ * const base3 = { count: 5 };
+ * const changes3 = { count: 3 };
+ * const merged3 = mergeState(base3, changes3, schema);
+ * // Results in { count: 8 } (5 + 3, not 3)
  * ```
  */
 function mergeState(base, changes, schema) {
     const acc = (0, clone_aware_1.cloneAware)(base);
     for (const [key, value] of Object.entries(changes)) {
-        // if there's nothing already present for the key, then we just set the value
+        // If there's nothing already present for the key, then we just set the value
         if (acc[key] === undefined || acc[key] === null) {
             acc[key] = value;
             continue;
         }
-        // if there's a registered merge function, then we assume the function handles the entirety of the value, including any nested values
-        if (registry_1.STATE_MERGE.has(schema.shape[key])) {
+        // If there's a registered merge function, then we assume the function handles 
+        // the entirety of the value, including any nested values
+        if (schema && registry_1.STATE_MERGE.has(schema.shape[key])) {
             acc[key] = registry_1.STATE_MERGE.get(schema.shape[key]).merge(acc[key], value);
             continue;
         }
         if (typeof value === "object") {
-            // The value is a class
+            // The value is a class instance - replace directly to preserve object identity
             if ('constructor' in value && !["Object", "Array"].includes(value.constructor.name)) {
                 acc[key] = value;
                 continue;
             }
-            // The value is an array
+            // The value is an array - replace the entire array (no element-level merging)
             if (Array.isArray(acc[key])) {
                 acc[key] = value;
                 continue;
             }
-            // The value is a plain object
+            // The value is a plain object - recursively merge nested properties
             acc[key] = mergeState(acc[key], value, schema.shape[key]);
         }
         else {
+            // The value is a primitive - replace directly
             acc[key] = value;
         }
     }

package/dist/util/merge-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"merge-state.js","sourceRoot":"","sources":["../../src/util/merge-state.ts"],"names":[],"mappings":";;AAuBA,gCAgCC;AAtDD,iDAAiD;AACjD,+CAA2C;AAE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,UAAU,CAAgC,IAAO,EAAE,OAAmB,EAAE,MAAmB;IACvG,MAAM,GAAG,GAAG,IAAA,wBAAU,EAAC,IAAI,CAAC,CAAC;IAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,6EAA6E;QAC7E,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7C,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC1C,SAAS;QACb,CAAC;QACD,qIAAqI;QACrI,IAAI,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACpC,GAA2B,CAAC,GAAG,CAAC,GAAG,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YAC/F,SAAS;QACb,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,uBAAuB;YACvB,IAAI,aAAa,IAAI,KAAK,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjF,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC1C,SAAS;YACb,CAAC;YACD,wBAAwB;YACxB,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACzB,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC1C,SAAS;YACb,CAAC;YAED,8BAA8B;YAC7B,GAA2B,CAAC,GAAG,CAAC,GAAG,UAAU,CAAE,GAA2B,CAAC,GAAG,CAAC,EAAE,KAAmB,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC,CAAC;QAC7I,CAAC;aAAM,CAAC;YACH,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC9C,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC"}
+{"version":3,"file":"merge-state.js","sourceRoot":"","sources":["../../src/util/merge-state.ts"],"names":[],"mappings":";;AAmDA,gCAkCC;AApFD,iDAAiD;AACjD,+CAA2C;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,SAAgB,UAAU,CAAgC,IAAO,EAAE,OAAmB,EAAE,MAAmB;IACvG,MAAM,GAAG,GAAG,IAAA,wBAAU,EAAC,IAAI,CAAC,CAAC;IAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,6EAA6E;QAC7E,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7C,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC1C,SAAS;QACb,CAAC;QACD,+EAA+E;QAC/E,yDAAyD;QACzD,IAAI,MAAM,IAAI,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC9C,GAA2B,CAAC,GAAG,CAAC,GAAG,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YAC/F,SAAS;QACb,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,+EAA+E;YAC/E,IAAI,aAAa,IAAI,KAAK,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjF,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC1C,SAAS;YACb,CAAC;YACD,8EAA8E;YAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACzB,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC1C,SAAS;YACb,CAAC;YAED,oEAAoE;YACnE,GAA2B,CAAC,GAAG,CAAC,GAAG,UAAU,CAAE,GAA2B,CAAC,GAAG,CAAC,EAAE,KAAmB,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC,CAAC;QAC7I,CAAC;aAAM,CAAC;YACJ,8CAA8C;YAC7C,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC9C,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ellyco/agentic",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Simple AI Agent Library",
   "repository": {
     "type": "git",