@ellyco/agentic 0.1.0

package/dist/graphs/runtime-context.d.ts

@@ -0,0 +1,189 @@
+import { StoredRun } from "./store/stored-run";
+/**
+ * Represents a layer of execution context within a graph traversal.
+ * Layers are stacked when graphs call other graphs (nested execution).
+ * Each layer tracks which node is currently executing.
+ *
+ * @class ContextLayer
+ *
+ * @example
+ * ```typescript
+ * // Each nested graph creates a new context layer
+ * const layer = runtime.nextLayer();
+ * layer.currentNode = "myNode";
+ * layer.custom.data = { ... };
+ * ```
+ */
+export declare class ContextLayer {
+    readonly index: number;
+    readonly runtime: RuntimeContext;
+    /**
+     * The name of the current node being executed
+     */
+    currentNode?: string;
+    /**
+     * Custom data storage for nodes and graphs to share information
+     */
+    custom: Record<string, any>;
+    /**
+     * Gets a unique identifier for this layer based on its position in the stack.
+     * Format: "ROOT" for the root layer, or "PARENT_ID.CURRENT_NODE" for nested layers.
+     *
+     * @returns {string} Unique identifier for this context layer
+     */
+    get id(): string;
+    /**
+     * Creates a new context layer.
+     *
+     * @param {number} index - The position of this layer in the context stack
+     * @param {RuntimeContext} runtime - Reference to the parent runtime context
+     */
+    constructor(index: number, runtime: RuntimeContext);
+    /**
+     * Creates and returns the next layer for nested execution.
+     *
+     * @returns {ContextLayer} A new child context layer
+     */
+    nextLayer(): ContextLayer;
+    /**
+     * Marks this layer as done executing.
+     * Removes it from the stack unless the runtime is interrupted.
+     */
+    done(): void;
+}
+/**
+ * Manages runtime state across graph execution and nested subgraphs.
+ * Maintains a stack of context layers for tracking nested execution.
+ * Handles interruption, resumption, and cursor management for checkpointing.
+ *
+ * @class RuntimeContext
+ *
+ * @example
+ * ```typescript
+ * const runtime = new RuntimeContext("run-123");
+ *
+ * // Track execution through nodes
+ * const layer = runtime.nextLayer();
+ * layer.currentNode = "node-1";
+ *
+ * // Handle interruption
+ * runtime.markInterrupted("Waiting for user input");
+ *
+ * // Later, wrap cursor for storage
+ * const cursor = runtime.wrapCursor(); // "node-1"
+ *
+ * // Restore from checkpoint
+ * const runtime2 = new RuntimeContext("run-123");
+ * runtime2.unwrapCursor(cursor);
+ * ```
+ */
+export declare class RuntimeContext {
+    readonly runId: string;
+    readonly storedRun?: StoredRun | undefined;
+    /**
+     * Stack of context layers for nested graph execution
+     */
+    private readonly contextLayers;
+    /**
+     * Current index in the context layer stack
+     */
+    private currentLayer;
+    /**
+     * Whether execution has been interrupted
+     */
+    private _interrupted;
+    /**
+     * Message describing why execution was interrupted
+     */
+    private _exitMessage;
+    /**
+     * Whether currently resuming from an interruption
+     */
+    private _resuming;
+    /**
+     * Gets whether the runtime is currently interrupted.
+     *
+     * @returns {boolean} True if interrupted, false otherwise
+     */
+    get interrupted(): boolean;
+    /**
+     * Gets the message associated with an interruption.
+     *
+     * @returns {string} The exit message (empty if not interrupted)
+     */
+    get exitMessage(): string;
+    /**
+     * Gets whether currently resuming from an interruption.
+     *
+     * @returns {boolean} True if resuming, false otherwise
+     */
+    get resuming(): boolean;
+    /**
+     * Creates a new runtime context.
+     *
+     * @param {string} runId - Unique identifier for this execution run
+     * @param {StoredRun} [storedRun] - Optional stored run for persistence
+     */
+    constructor(runId: string, storedRun?: StoredRun | undefined);
+    /**
+     * Restores execution state from a cursor (checkpoint).
+     * Sets up the context layer stack based on the cursor path.
+     * Marks the runtime as resuming.
+     *
+     * @param {string} cursor - Cursor string encoding the path through nested contexts
+     *   Format: "node1.node2.node3" where each segment is a node name
+     *
+     * @example
+     * ```typescript
+     * runtime.unwrapCursor("start.process.end");
+     * // Sets up 3 context layers with currentNode set appropriately
+     * ```
+     */
+    unwrapCursor(cursor: string): void;
+    /**
+     * Encodes the current execution path into a cursor for checkpointing.
+     * The cursor can later be used with unwrapCursor() to resume execution.
+     *
+     * @returns {string} Cursor encoding the current context path
+     *
+     * @example
+     * ```typescript
+     * const cursor = runtime.wrapCursor(); // "start.process.end"
+     * // Later restore with: runtime.unwrapCursor(cursor);
+     * ```
+     */
+    wrapCursor(): string;
+    /**
+     * Retrieves a context layer by its index.
+     *
+     * @param {number} index - The layer index to retrieve
+     * @returns {ContextLayer} The context layer at the specified index
+     */
+    getLayer(index: number): ContextLayer;
+    /**
+     * Gets or creates the next context layer for nested execution.
+     * If a layer already exists at the next depth, returns it.
+     * Otherwise, creates a new layer.
+     *
+     * @returns {ContextLayer} The next context layer
+     */
+    nextLayer(): ContextLayer;
+    /**
+     * Removes the top (most recent) context layer from the stack.
+     * Called when a nested graph or layer completes execution.
+     */
+    removeTopLayer(): void;
+    /**
+     * Marks the runtime as interrupted with an optional reason message.
+     * Used by nodes to signal that execution should pause.
+     *
+     * @param {string} [reason] - Optional message explaining the interruption
+     */
+    markInterrupted(reason?: string): void;
+    /**
+     * Clears the resuming flag after resumption is complete.
+     * Called after resuming nodes acknowledge they've been resumed.
+     */
+    markResumed(): void;
+}
+//# sourceMappingURL=runtime-context.d.ts.map

package/dist/graphs/runtime-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.d.ts","sourceRoot":"","sources":["../../src/graphs/runtime-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;aAgCD,KAAK,EAAE,MAAM;aACb,OAAO,EAAE,cAAc;IAhC3C;;OAEG;IACI,WAAW,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACI,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAM;IAExC;;;;;OAKG;IACH,IAAI,EAAE,IAAI,MAAM,CAMf;IAED;;;;;OAKG;gBAEiB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc;IAG3C;;;;OAIG;IACH,SAAS,IAAI,YAAY;IAIzB;;;OAGG;IACH,IAAI,IAAI,IAAI;CAKf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,cAAc;aA2DK,KAAK,EAAE,MAAM;aAAkB,SAAS,CAAC,EAAE,SAAS;IA1DhF;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IAEpD;;OAEG;IACH,OAAO,CAAC,YAAY,CAAc;IAElC;;OAEG;IACH,OAAO,CAAC,YAAY,CAAS;IAE7B;;OAEG;IACH,OAAO,CAAC,YAAY,CAAM;IAE1B;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;OAIG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;OAKG;gBACyB,KAAK,EAAE,MAAM,EAAkB,SAAS,CAAC,EAAE,SAAS,YAAA;IAEhF;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAelC;;;;;;;;;;;OAWG;IACH,UAAU,IAAI,MAAM;IAQpB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAIrC;;;;;;OAMG;IACH,SAAS,IAAI,YAAY;IAgBzB;;;OAGG;IACH,cAAc,IAAI,IAAI;IAKtB;;;;;OAKG;IACH,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtC;;;OAGG;IACH,WAAW,IAAI,IAAI;CAGtB"}

package/dist/graphs/runtime-context.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeContext = exports.ContextLayer = void 0;
+/**
+ * Represents a layer of execution context within a graph traversal.
+ * Layers are stacked when graphs call other graphs (nested execution).
+ * Each layer tracks which node is currently executing.
+ *
+ * @class ContextLayer
+ *
+ * @example
+ * ```typescript
+ * // Each nested graph creates a new context layer
+ * const layer = runtime.nextLayer();
+ * layer.currentNode = "myNode";
+ * layer.custom.data = { ... };
+ * ```
+ */
+class ContextLayer {
+    index;
+    runtime;
+    /**
+     * The name of the current node being executed
+     */
+    currentNode;
+    /**
+     * Custom data storage for nodes and graphs to share information
+     */
+    custom = {};
+    /**
+     * Gets a unique identifier for this layer based on its position in the stack.
+     * Format: "ROOT" for the root layer, or "PARENT_ID.CURRENT_NODE" for nested layers.
+     *
+     * @returns {string} Unique identifier for this context layer
+     */
+    get id() {
+        if (this.index === 0) {
+            return "ROOT";
+        }
+        const lastLayer = this.runtime.getLayer(this.index - 1);
+        return `${lastLayer.id}.${lastLayer.currentNode}`;
+    }
+    /**
+     * Creates a new context layer.
+     *
+     * @param {number} index - The position of this layer in the context stack
+     * @param {RuntimeContext} runtime - Reference to the parent runtime context
+     */
+    constructor(index, runtime) {
+        this.index = index;
+        this.runtime = runtime;
+    }
+    /**
+     * Creates and returns the next layer for nested execution.
+     *
+     * @returns {ContextLayer} A new child context layer
+     */
+    nextLayer() {
+        return this.runtime.nextLayer();
+    }
+    /**
+     * Marks this layer as done executing.
+     * Removes it from the stack unless the runtime is interrupted.
+     */
+    done() {
+        if (!this.runtime.interrupted) {
+            this.runtime.removeTopLayer();
+        }
+    }
+}
+exports.ContextLayer = ContextLayer;
+/**
+ * Manages runtime state across graph execution and nested subgraphs.
+ * Maintains a stack of context layers for tracking nested execution.
+ * Handles interruption, resumption, and cursor management for checkpointing.
+ *
+ * @class RuntimeContext
+ *
+ * @example
+ * ```typescript
+ * const runtime = new RuntimeContext("run-123");
+ *
+ * // Track execution through nodes
+ * const layer = runtime.nextLayer();
+ * layer.currentNode = "node-1";
+ *
+ * // Handle interruption
+ * runtime.markInterrupted("Waiting for user input");
+ *
+ * // Later, wrap cursor for storage
+ * const cursor = runtime.wrapCursor(); // "node-1"
+ *
+ * // Restore from checkpoint
+ * const runtime2 = new RuntimeContext("run-123");
+ * runtime2.unwrapCursor(cursor);
+ * ```
+ */
+class RuntimeContext {
+    runId;
+    storedRun;
+    /**
+     * Stack of context layers for nested graph execution
+     */
+    contextLayers = [];
+    /**
+     * Current index in the context layer stack
+     */
+    currentLayer = -1;
+    /**
+     * Whether execution has been interrupted
+     */
+    _interrupted = false;
+    /**
+     * Message describing why execution was interrupted
+     */
+    _exitMessage = "";
+    /**
+     * Whether currently resuming from an interruption
+     */
+    _resuming = false;
+    /**
+     * Gets whether the runtime is currently interrupted.
+     *
+     * @returns {boolean} True if interrupted, false otherwise
+     */
+    get interrupted() {
+        return this._interrupted;
+    }
+    /**
+     * Gets the message associated with an interruption.
+     *
+     * @returns {string} The exit message (empty if not interrupted)
+     */
+    get exitMessage() {
+        return this._exitMessage;
+    }
+    /**
+     * Gets whether currently resuming from an interruption.
+     *
+     * @returns {boolean} True if resuming, false otherwise
+     */
+    get resuming() {
+        return this._resuming;
+    }
+    /**
+     * Creates a new runtime context.
+     *
+     * @param {string} runId - Unique identifier for this execution run
+     * @param {StoredRun} [storedRun] - Optional stored run for persistence
+     */
+    constructor(runId, storedRun) {
+        this.runId = runId;
+        this.storedRun = storedRun;
+    }
+    /**
+     * Restores execution state from a cursor (checkpoint).
+     * Sets up the context layer stack based on the cursor path.
+     * Marks the runtime as resuming.
+     *
+     * @param {string} cursor - Cursor string encoding the path through nested contexts
+     *   Format: "node1.node2.node3" where each segment is a node name
+     *
+     * @example
+     * ```typescript
+     * runtime.unwrapCursor("start.process.end");
+     * // Sets up 3 context layers with currentNode set appropriately
+     * ```
+     */
+    unwrapCursor(cursor) {
+        this._resuming = true;
+        const layers = cursor.split(".");
+        let idPrefix = "";
+        for (const layer of layers) {
+            const contextLayer = new ContextLayer(this.contextLayers.length, this);
+            contextLayer.currentNode = layer;
+            this.contextLayers.push(contextLayer);
+            idPrefix = idPrefix.length > 0 ? `${idPrefix}.${layer}` : layer;
+        }
+    }
+    /**
+     * Encodes the current execution path into a cursor for checkpointing.
+     * The cursor can later be used with unwrapCursor() to resume execution.
+     *
+     * @returns {string} Cursor encoding the current context path
+     *
+     * @example
+     * ```typescript
+     * const cursor = runtime.wrapCursor(); // "start.process.end"
+     * // Later restore with: runtime.unwrapCursor(cursor);
+     * ```
+     */
+    wrapCursor() {
+        const layerCursors = [];
+        for (const layer of this.contextLayers) {
+            layerCursors.push(layer.currentNode);
+        }
+        return layerCursors.join(".");
+    }
+    /**
+     * Retrieves a context layer by its index.
+     *
+     * @param {number} index - The layer index to retrieve
+     * @returns {ContextLayer} The context layer at the specified index
+     */
+    getLayer(index) {
+        return this.contextLayers[index];
+    }
+    /**
+     * Gets or creates the next context layer for nested execution.
+     * If a layer already exists at the next depth, returns it.
+     * Otherwise, creates a new layer.
+     *
+     * @returns {ContextLayer} The next context layer
+     */
+    nextLayer() {
+        // already a contextLayer present at this depth
+        if (this.currentLayer < this.contextLayers.length - 1) {
+            const layer = this.contextLayers[this.currentLayer + 1];
+            this.currentLayer++;
+            return layer;
+        }
+        const contextLayer = new ContextLayer(this.contextLayers.length, this);
+        this.contextLayers.push(contextLayer);
+        this.currentLayer++;
+        return contextLayer;
+    }
+    /**
+     * Removes the top (most recent) context layer from the stack.
+     * Called when a nested graph or layer completes execution.
+     */
+    removeTopLayer() {
+        this.contextLayers.pop();
+        this.currentLayer--;
+    }
+    /**
+     * Marks the runtime as interrupted with an optional reason message.
+     * Used by nodes to signal that execution should pause.
+     *
+     * @param {string} [reason] - Optional message explaining the interruption
+     */
+    markInterrupted(reason) {
+        this._interrupted = true;
+        this._exitMessage = reason ?? "";
+    }
+    /**
+     * Clears the resuming flag after resumption is complete.
+     * Called after resuming nodes acknowledge they've been resumed.
+     */
+    markResumed() {
+        this._resuming = false;
+    }
+}
+exports.RuntimeContext = RuntimeContext;
+//# sourceMappingURL=runtime-context.js.map

package/dist/graphs/runtime-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.js","sourceRoot":"","sources":["../../src/graphs/runtime-context.ts"],"names":[],"mappings":"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"}

package/dist/graphs/state-machine.d.ts

@@ -0,0 +1,105 @@
+import { Graph } from "./graph";
+import { type NodeLike } from "../nodes/types";
+import { z } from "zod";
+/**
+ * A general-purpose graph with arbitrary node and edge definitions.
+ * Supports both simple edges and conditional edges for complex workflows.
+ * Nodes can be added manually and edges can be configured dynamically.
+ *
+ * @class StateMachine
+ * @extends {Graph<T, S>}
+ * @template T - The Zod schema for state
+ * @template S - The inferred state type from T
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   status: z.enum(["pending", "processing", "done"]),
+ *   data: z.string()
+ * });
+ *
+ * const sm = new StateMachine(schema);
+ * sm.addNode("process", new FunctionNode(...));
+ * sm.addNode("validate", new FunctionNode(...));
+ *
+ * sm.addEdge(START, "process");
+ * sm.addConditionalEdge("process", ["validate", END], (state) => {
+ *   return state.data ? "validate" : END;
+ * });
+ * sm.addEdge("validate", END);
+ * ```
+ */
+export declare class StateMachine<T extends z.ZodObject, S extends Record<string, unknown> = z.infer<T>> extends Graph<T, S> {
+    /**
+     * Adds a node to the state machine.
+     *
+     * @param {string} name - Unique name for the node (cannot be "start" or "end")
+     * @param {NodeLike<S> | Graph<any, S>} node - The node implementation
+     * @returns {this} The state machine instance for method chaining
+     * @throws {Error} If name is reserved or node already exists
+     *
+     * @example
+     * ```typescript
+     * sm.addNode("myNode", new FunctionNode((state) => ({ ...state })));
+     * ```
+     */
+    addNode(name: string, node: NodeLike<S> | Graph<any, S>): this;
+    /**
+     * Adds a simple edge from one node to another.
+     * The graph will always transition from 'from' to 'to'.
+     *
+     * @param {string} from - Source node name
+     * @param {string} to - Destination node name
+     * @returns {this} The state machine instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * sm.addEdge("start", "nodeA");
+     * sm.addEdge("nodeA", "nodeB");
+     * sm.addEdge("nodeB", "end");
+     * ```
+     */
+    addEdge(from: string, to: string): this;
+    /**
+     * Adds a conditional edge from one node to multiple possible destinations.
+     * A function determines which destination to transition to based on state.
+     *
+     * @template K - Tuple of possible destination names
+     * @param {string} from - Source node name
+     * @param {K} to - Tuple of possible destination node names
+     * @param {(state: S) => K[number]} func - Function that returns the destination
+     * @returns {this} The state machine instance for method chaining
+     * @throws {Error} If no destinations are provided
+     *
+     * @example
+     * ```typescript
+     * sm.addConditionalEdge(
+     *   "decision",
+     *   ["path1", "path2", "end"],
+     *   (state) => {
+     *     if (state.priority > 5) return "path1";
+     *     if (state.priority > 2) return "path2";
+     *     return "end";
+     *   }
+     * );
+     * ```
+     */
+    addConditionalEdge<K extends string[]>(from: string, to: K, func: (state: S) => K[number]): this;
+    /**
+     * StateMachine doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {S} state - The graph state
+     * @returns {S} The same state
+     */
+    protected stateToNodeState(state: S): S;
+    /**
+     * StateMachine doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {Partial<S>} nodeState - The partial node state
+     * @returns {Partial<S>} The same partial state
+     */
+    protected nodeStateToState(nodeState: Partial<S>): Partial<S>;
+}
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/graphs/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/graphs/state-machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,EAAS,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IAChH;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI;IAW9D;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAKvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,EACjC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,EACL,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAC9B,IAAI;IAWP;;;;;;OAMG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC;IAIvC;;;;;;OAMG;IACH,SAAS,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAGhE"}

package/dist/graphs/state-machine.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateMachine = void 0;
+const graph_1 = require("./graph");
+/**
+ * A general-purpose graph with arbitrary node and edge definitions.
+ * Supports both simple edges and conditional edges for complex workflows.
+ * Nodes can be added manually and edges can be configured dynamically.
+ *
+ * @class StateMachine
+ * @extends {Graph<T, S>}
+ * @template T - The Zod schema for state
+ * @template S - The inferred state type from T
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   status: z.enum(["pending", "processing", "done"]),
+ *   data: z.string()
+ * });
+ *
+ * const sm = new StateMachine(schema);
+ * sm.addNode("process", new FunctionNode(...));
+ * sm.addNode("validate", new FunctionNode(...));
+ *
+ * sm.addEdge(START, "process");
+ * sm.addConditionalEdge("process", ["validate", END], (state) => {
+ *   return state.data ? "validate" : END;
+ * });
+ * sm.addEdge("validate", END);
+ * ```
+ */
+class StateMachine extends graph_1.Graph {
+    /**
+     * Adds a node to the state machine.
+     *
+     * @param {string} name - Unique name for the node (cannot be "start" or "end")
+     * @param {NodeLike<S> | Graph<any, S>} node - The node implementation
+     * @returns {this} The state machine instance for method chaining
+     * @throws {Error} If name is reserved or node already exists
+     *
+     * @example
+     * ```typescript
+     * sm.addNode("myNode", new FunctionNode((state) => ({ ...state })));
+     * ```
+     */
+    addNode(name, node) {
+        if (name === graph_1.START || name === graph_1.END) {
+            throw new Error(`Node ${name} is reserved`);
+        }
+        if (name in this.nodes) {
+            throw new Error(`Node ${name} already exists`);
+        }
+        this.nodes[name] = node;
+        return this;
+    }
+    /**
+     * Adds a simple edge from one node to another.
+     * The graph will always transition from 'from' to 'to'.
+     *
+     * @param {string} from - Source node name
+     * @param {string} to - Destination node name
+     * @returns {this} The state machine instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * sm.addEdge("start", "nodeA");
+     * sm.addEdge("nodeA", "nodeB");
+     * sm.addEdge("nodeB", "end");
+     * ```
+     */
+    addEdge(from, to) {
+        this.edges[from] = to;
+        return this;
+    }
+    /**
+     * Adds a conditional edge from one node to multiple possible destinations.
+     * A function determines which destination to transition to based on state.
+     *
+     * @template K - Tuple of possible destination names
+     * @param {string} from - Source node name
+     * @param {K} to - Tuple of possible destination node names
+     * @param {(state: S) => K[number]} func - Function that returns the destination
+     * @returns {this} The state machine instance for method chaining
+     * @throws {Error} If no destinations are provided
+     *
+     * @example
+     * ```typescript
+     * sm.addConditionalEdge(
+     *   "decision",
+     *   ["path1", "path2", "end"],
+     *   (state) => {
+     *     if (state.priority > 5) return "path1";
+     *     if (state.priority > 2) return "path2";
+     *     return "end";
+     *   }
+     * );
+     * ```
+     */
+    addConditionalEdge(from, to, func) {
+        if (to.length === 0) {
+            throw new Error(`No edges defined for conditional edge from ${from}`);
+        }
+        this.conditionalEdges[from] = to;
+        this.conditionalFuncs[from] = func;
+        return this;
+    }
+    /**
+     * StateMachine doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {S} state - The graph state
+     * @returns {S} The same state
+     */
+    stateToNodeState(state) {
+        return state;
+    }
+    /**
+     * StateMachine doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {Partial<S>} nodeState - The partial node state
+     * @returns {Partial<S>} The same partial state
+     */
+    nodeStateToState(nodeState) {
+        return nodeState;
+    }
+}
+exports.StateMachine = StateMachine;
+//# sourceMappingURL=state-machine.js.map