@q1k-oss/behaviour-tree-workflows 0.0.1

package/dist/index.js

@@ -0,0 +1,4879 @@
+// src/events.ts
+var NodeEventType = /* @__PURE__ */ ((NodeEventType2) => {
+  NodeEventType2["TICK_START"] = "tick_start";
+  NodeEventType2["TICK_END"] = "tick_end";
+  NodeEventType2["STATUS_CHANGE"] = "status_change";
+  NodeEventType2["ERROR"] = "error";
+  NodeEventType2["HALT"] = "halt";
+  NodeEventType2["RESET"] = "reset";
+  NodeEventType2["LOG"] = "log";
+  return NodeEventType2;
+})(NodeEventType || {});
+var NodeEventEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  allListeners = /* @__PURE__ */ new Set();
+  /**
+   * Subscribe to a specific event type
+   * @param type - The event type to listen for
+   * @param callback - Function to call when event occurs
+   */
+  on(type, callback) {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(type)?.add(callback);
+  }
+  /**
+   * Subscribe to all event types
+   * @param callback - Function to call for any event
+   */
+  onAll(callback) {
+    this.allListeners.add(callback);
+  }
+  /**
+   * Unsubscribe from a specific event type
+   * @param type - The event type to stop listening for
+   * @param callback - The callback to remove
+   */
+  off(type, callback) {
+    this.listeners.get(type)?.delete(callback);
+  }
+  /**
+   * Unsubscribe from all events
+   * @param callback - The callback to remove
+   */
+  offAll(callback) {
+    this.allListeners.delete(callback);
+  }
+  /**
+   * Emit an event to all registered listeners
+   * Errors in callbacks are caught and logged to prevent breaking execution
+   * @param event - The event to emit
+   */
+  emit(event) {
+    const typeListeners = this.listeners.get(event.type);
+    if (typeListeners) {
+      for (const callback of typeListeners) {
+        try {
+          callback(event);
+        } catch (error) {
+          console.error(`Error in event callback for ${event.type}:`, error);
+        }
+      }
+    }
+    for (const callback of this.allListeners) {
+      try {
+        callback(event);
+      } catch (error) {
+        console.error("Error in event callback (onAll):", error);
+      }
+    }
+  }
+  /**
+   * Remove all listeners
+   */
+  clear() {
+    this.listeners.clear();
+    this.allListeners.clear();
+  }
+  /**
+   * Get count of listeners for a specific type
+   * @param type - The event type to check
+   * @returns Number of listeners
+   */
+  listenerCount(type) {
+    return this.listeners.get(type)?.size || 0;
+  }
+  /**
+   * Get count of "all events" listeners
+   * @returns Number of listeners
+   */
+  allListenerCount() {
+    return this.allListeners.size;
+  }
+  /**
+   * Check if there are any listeners
+   * @returns True if any listeners are registered
+   */
+  hasListeners() {
+    return this.listeners.size > 0 || this.allListeners.size > 0;
+  }
+  /**
+   * Returns an Effect Stream of all events
+   * REMOVED: Effect-TS integration removed in Phase 1
+   * For streaming events in Temporal workflows, use native event emitter pattern
+   */
+  // toStream(): Stream.Stream<NodeEvent<unknown>> {
+  //   return Stream.asyncPush<NodeEvent<unknown>>((emit) =>
+  //     Effect.acquireRelease(
+  //       Effect.sync(() => {
+  //         const callback = (event: NodeEvent<unknown>) => {
+  //           emit.single(event);
+  //         };
+  //         this.onAll(callback);
+  //         return callback;
+  //       }),
+  //       (callback) => Effect.sync(() => this.offAll(callback)),
+  //     ),
+  //   );
+  // }
+  /**
+   * Returns an AsyncIterable of all events
+   * REMOVED: Effect-TS dependency removed in Phase 1
+   * Implement using native async generators if needed
+   */
+  // toAsyncIterable(): AsyncIterable<NodeEvent<unknown>> {
+  //   return Stream.toAsyncIterable(this.toStream());
+  // }
+};
+
+// src/types.ts
+var NodeStatus = /* @__PURE__ */ ((NodeStatus2) => {
+  NodeStatus2["SUCCESS"] = "SUCCESS";
+  NodeStatus2["FAILURE"] = "FAILURE";
+  NodeStatus2["RUNNING"] = "RUNNING";
+  NodeStatus2["IDLE"] = "IDLE";
+  return NodeStatus2;
+})(NodeStatus || {});
+
+// src/errors.ts
+var ConfigurationError = class _ConfigurationError extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.hint = hint;
+    this.name = "ConfigurationError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ConfigurationError);
+    }
+  }
+  isConfigurationError = true;
+};
+
+// src/utils/signal-check.ts
+var OperationCancelledError = class _OperationCancelledError extends Error {
+  constructor(message = "Operation was cancelled") {
+    super(message);
+    this.name = "OperationCancelledError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _OperationCancelledError);
+    }
+  }
+};
+function checkSignal(signal, message) {
+  if (signal?.aborted) {
+    throw new OperationCancelledError(message);
+  }
+}
+
+// src/utils/error-handler.ts
+function handleNodeError(error) {
+  if (error instanceof ConfigurationError) {
+    throw error;
+  }
+  if (error instanceof OperationCancelledError) {
+    throw error;
+  }
+  return "FAILURE" /* FAILURE */;
+}
+
+// src/base-node.ts
+var BaseNode = class {
+  id;
+  name;
+  type;
+  _status = "IDLE" /* IDLE */;
+  _lastError;
+  config;
+  _eventEmitter;
+  parent;
+  children;
+  constructor(config) {
+    this.id = config.id;
+    this.name = config.name || config.id;
+    this.type = this.constructor.name;
+    this.config = config;
+  }
+  halt() {
+    console.log(`[${this.type}:${this.name}] Halting...`);
+    this._eventEmitter?.emit({
+      type: "halt" /* HALT */,
+      nodeId: this.id,
+      nodeName: this.name,
+      nodeType: this.type,
+      timestamp: Date.now()
+    });
+    if (this._status === "RUNNING" /* RUNNING */) {
+      this.onHalt();
+      this._status = "IDLE" /* IDLE */;
+    }
+  }
+  reset() {
+    console.log(`[${this.type}:${this.name}] Resetting...`);
+    this._eventEmitter?.emit({
+      type: "reset" /* RESET */,
+      nodeId: this.id,
+      nodeName: this.name,
+      nodeType: this.type,
+      timestamp: Date.now()
+    });
+    this._status = "IDLE" /* IDLE */;
+    this._lastError = void 0;
+    this.onReset();
+  }
+  status() {
+    return this._status;
+  }
+  get lastError() {
+    return this._lastError;
+  }
+  providedPorts() {
+    return [];
+  }
+  /**
+   * Hook for derived classes to implement custom halt logic
+   */
+  onHalt() {
+  }
+  /**
+   * Hook for derived classes to implement custom reset logic
+   */
+  onReset() {
+  }
+  /**
+   * Helper to get input value from blackboard
+   */
+  getInput(context, key, defaultValue) {
+    const fullKey = this.config[key] || key;
+    return context.blackboard.getPort(fullKey, defaultValue);
+  }
+  /**
+   * Helper to set output value to blackboard
+   */
+  setOutput(context, key, value) {
+    const fullKey = this.config[key] || key;
+    context.blackboard.setPort(fullKey, value);
+  }
+  /**
+   * Log helper for debugging
+   */
+  log(message, ...args) {
+    console.log(`[${this.type}:${this.name}] ${message}`, ...args);
+  }
+};
+var ActionNode = class extends BaseNode {
+  /**
+   * Clone this action node
+   * Leaf nodes have no children to clone
+   */
+  clone() {
+    const ClonedClass = this.constructor;
+    return new ClonedClass({ ...this.config });
+  }
+  /**
+   * Tick with resumable execution support for leaf nodes
+   * Uses async/await for Promise-based async/RUNNING semantics
+   * All errors are caught and converted to NodeStatus.FAILURE
+   */
+  async tick(context) {
+    try {
+      this._eventEmitter = context.eventEmitter;
+      context.eventEmitter?.emit({
+        type: "tick_start" /* TICK_START */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now()
+      });
+      const status = await this.executeTick(context);
+      this._status = status;
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status }
+      });
+      return status;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorStack = error instanceof Error ? error.stack : void 0;
+      this._lastError = errorMessage;
+      this._status = "FAILURE" /* FAILURE */;
+      context.eventEmitter?.emit({
+        type: "error" /* ERROR */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: {
+          error: {
+            message: errorMessage,
+            stack: errorStack
+          },
+          blackboard: context.blackboard?.toJSON?.() ?? {}
+        }
+      });
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status: "FAILURE" /* FAILURE */ }
+      });
+      return handleNodeError(error);
+    }
+  }
+};
+var ConditionNode = class extends BaseNode {
+  /**
+   * Clone this condition node
+   * Leaf nodes have no children to clone
+   */
+  clone() {
+    const ClonedClass = this.constructor;
+    return new ClonedClass({ ...this.config });
+  }
+  /**
+   * Tick with resumable execution support for leaf nodes
+   * Uses async/await for Promise-based async/RUNNING semantics
+   * All errors are caught and converted to NodeStatus.FAILURE
+   */
+  async tick(context) {
+    try {
+      this._eventEmitter = context.eventEmitter;
+      context.eventEmitter?.emit({
+        type: "tick_start" /* TICK_START */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now()
+      });
+      const status = await this.executeTick(context);
+      this._status = status;
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status }
+      });
+      return status;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorStack = error instanceof Error ? error.stack : void 0;
+      this._lastError = errorMessage;
+      this._status = "FAILURE" /* FAILURE */;
+      context.eventEmitter?.emit({
+        type: "error" /* ERROR */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: {
+          error: {
+            message: errorMessage,
+            stack: errorStack
+          },
+          blackboard: context.blackboard?.toJSON?.() ?? {}
+        }
+      });
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status: "FAILURE" /* FAILURE */ }
+      });
+      return handleNodeError(error);
+    }
+  }
+};
+var DecoratorNode = class extends BaseNode {
+  child;
+  /**
+   * Clone this decorator node including its child
+   */
+  clone() {
+    const ClonedClass = this.constructor;
+    const cloned = new ClonedClass({ ...this.config });
+    if (this.child) {
+      cloned.setChild(this.child.clone());
+    }
+    return cloned;
+  }
+  /**
+   * Tick with resumable execution support - decorators can be resume points
+   * Uses async/await for Promise-based async/RUNNING semantics
+   * All errors are caught and converted to NodeStatus.FAILURE
+   */
+  async tick(context) {
+    try {
+      context.eventEmitter?.emit({
+        type: "tick_start" /* TICK_START */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now()
+      });
+      const status = await this.executeTick(context);
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status }
+      });
+      return status;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorStack = error instanceof Error ? error.stack : void 0;
+      this._lastError = errorMessage;
+      this._status = "FAILURE" /* FAILURE */;
+      context.eventEmitter?.emit({
+        type: "error" /* ERROR */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: {
+          error: {
+            message: errorMessage,
+            stack: errorStack
+          },
+          blackboard: context.blackboard?.toJSON?.() ?? {}
+        }
+      });
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status: "FAILURE" /* FAILURE */ }
+      });
+      return handleNodeError(error);
+    }
+  }
+  setChild(child) {
+    if (!child) {
+      throw new Error("Cannot set undefined child on decorator node");
+    }
+    this.child = child;
+    this.children = [child];
+    child.parent = this;
+  }
+  halt() {
+    super.halt();
+    if (this.child && this.child.status() === "RUNNING" /* RUNNING */) {
+      this.child.halt();
+    }
+  }
+  reset() {
+    super.reset();
+    if (this.child) {
+      this.child.reset();
+    }
+  }
+};
+var CompositeNode = class extends BaseNode {
+  _children = [];
+  /**
+   * Clone this composite node including all children
+   */
+  clone() {
+    const ClonedClass = this.constructor;
+    const cloned = new ClonedClass({ ...this.config });
+    const clonedChildren = this._children.map((child) => child.clone());
+    cloned.addChildren(clonedChildren);
+    return cloned;
+  }
+  /**
+   * Tick with resumable execution support - composites can be resume points
+   * Uses async/await for Promise-based async/RUNNING semantics
+   * All errors are caught and converted to NodeStatus.FAILURE
+   */
+  async tick(context) {
+    try {
+      context.eventEmitter?.emit({
+        type: "tick_start" /* TICK_START */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now()
+      });
+      const status = await this.executeTick(context);
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status }
+      });
+      return status;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorStack = error instanceof Error ? error.stack : void 0;
+      this._lastError = errorMessage;
+      this._status = "FAILURE" /* FAILURE */;
+      context.eventEmitter?.emit({
+        type: "error" /* ERROR */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: {
+          error: {
+            message: errorMessage,
+            stack: errorStack
+          },
+          blackboard: context.blackboard?.toJSON?.() ?? {}
+        }
+      });
+      context.eventEmitter?.emit({
+        type: "tick_end" /* TICK_END */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { status: "FAILURE" /* FAILURE */ }
+      });
+      return handleNodeError(error);
+    }
+  }
+  addChild(child) {
+    if (!child) {
+      throw new Error("Cannot add undefined child to composite node");
+    }
+    this._children.push(child);
+    this.children = this._children;
+    child.parent = this;
+  }
+  addChildren(children) {
+    children.forEach((child) => {
+      this.addChild(child);
+    });
+  }
+  halt() {
+    super.halt();
+    for (const child of this._children) {
+      if (child.status() === "RUNNING" /* RUNNING */) {
+        child.halt();
+      }
+    }
+  }
+  reset() {
+    super.reset();
+    for (const child of this._children) {
+      child.reset();
+    }
+  }
+  haltChildren(startIndex = 0) {
+    for (let i = startIndex; i < this._children.length; i++) {
+      const child = this._children[i];
+      if (child && child.status() === "RUNNING" /* RUNNING */) {
+        child.halt();
+      }
+    }
+  }
+};
+
+// src/blackboard.ts
+var ScopedBlackboard = class _ScopedBlackboard {
+  data = {};
+  parent = null;
+  scopeName;
+  childScopes = /* @__PURE__ */ new Map();
+  constructor(scopeName = "root", parent = null) {
+    this.scopeName = scopeName;
+    this.parent = parent;
+  }
+  get(key) {
+    if (key in this.data) {
+      return this.data[key];
+    }
+    if (this.parent) {
+      return this.parent.get(key);
+    }
+    return void 0;
+  }
+  set(key, value) {
+    this.data[key] = value;
+  }
+  has(key) {
+    if (key in this.data) {
+      return true;
+    }
+    if (this.parent) {
+      return this.parent.has(key);
+    }
+    return false;
+  }
+  delete(key) {
+    delete this.data[key];
+  }
+  clear() {
+    this.data = {};
+    this.childScopes.clear();
+  }
+  createScope(name) {
+    if (this.childScopes.has(name)) {
+      const scope = this.childScopes.get(name);
+      if (!scope) {
+        throw new Error(`Scope ${name} not found`);
+      }
+      return scope;
+    }
+    const childScope = new _ScopedBlackboard(name, this);
+    this.childScopes.set(name, childScope);
+    return childScope;
+  }
+  getParentScope() {
+    return this.parent;
+  }
+  getScopeName() {
+    return this.scopeName;
+  }
+  getPort(key, defaultValue) {
+    const value = this.get(key);
+    if (value === void 0 && defaultValue !== void 0) {
+      return defaultValue;
+    }
+    return value;
+  }
+  setPort(key, value) {
+    this.set(key, value);
+  }
+  keys() {
+    const localKeys = Object.keys(this.data);
+    const parentKeys = this.parent ? this.parent.keys() : [];
+    const allKeys = /* @__PURE__ */ new Set([...localKeys, ...parentKeys]);
+    return Array.from(allKeys);
+  }
+  entries() {
+    const result = [];
+    const processedKeys = /* @__PURE__ */ new Set();
+    for (const [key, value] of Object.entries(this.data)) {
+      result.push([key, value]);
+      processedKeys.add(key);
+    }
+    if (this.parent) {
+      for (const [key, value] of this.parent.entries()) {
+        if (!processedKeys.has(key)) {
+          result.push([key, value]);
+        }
+      }
+    }
+    return result;
+  }
+  toJSON() {
+    return { ...this.data };
+  }
+  /**
+   * Create a deep clone of this blackboard for snapshots
+   * Uses structured cloning for deep copy
+   */
+  clone() {
+    const cloned = new _ScopedBlackboard(this.scopeName, this.parent);
+    cloned.data = structuredClone(this.data);
+    this.childScopes.forEach((childScope, name) => {
+      cloned.childScopes.set(name, childScope.clone());
+    });
+    return cloned;
+  }
+  /**
+   * Get the full scope path (e.g., "root.child.grandchild")
+   */
+  getFullScopePath() {
+    const path2 = [this.scopeName];
+    let current = this.parent;
+    while (current) {
+      path2.unshift(current.scopeName);
+      current = current.parent;
+    }
+    return path2.join(".");
+  }
+  /**
+   * Debug utility to print the blackboard hierarchy
+   */
+  debug(indent = 0) {
+    const prefix = "  ".repeat(indent);
+    console.log(`${prefix}Scope: ${this.scopeName}`);
+    for (const [key, value] of Object.entries(this.data)) {
+      console.log(`${prefix}  ${key}: ${JSON.stringify(value)}`);
+    }
+    for (const [_name, childScope] of this.childScopes) {
+      childScope.debug(indent + 1);
+    }
+  }
+};
+
+// src/behavior-tree.ts
+var BehaviorTree = class _BehaviorTree {
+  root;
+  pathIndex = /* @__PURE__ */ new Map();
+  idIndex = /* @__PURE__ */ new Map();
+  constructor(root) {
+    this.root = root;
+    this.buildNodeIndex();
+  }
+  /**
+   * Parse a path with tree ID prefix.
+   * Format: #TreeID/node/path
+   *
+   * @param fullPath Path string starting with # followed by tree ID
+   * @returns Object with treeId and nodePath
+   * @throws Error if path format is invalid
+   *
+   * Valid examples:
+   * - "#SimpleTest/0/1" -> { treeId: "SimpleTest", nodePath: "/0/1" }
+   * - "#MyTree/" -> { treeId: "MyTree", nodePath: "/" }
+   * - "#OnlyTree" -> { treeId: "OnlyTree", nodePath: "/" }
+   *
+   * Invalid examples:
+   * - "/0/1" - missing #TreeID prefix
+   * - "#/0/1" - empty tree ID
+   * - "#" - empty tree ID
+   */
+  static parsePathWithTreeId(fullPath) {
+    if (!fullPath.startsWith("#")) {
+      throw new Error(
+        `Invalid path format: '${fullPath}'. Path must start with #TreeID (e.g., #SimpleTest/0/1)`
+      );
+    }
+    const slashIndex = fullPath.indexOf("/");
+    let treeId;
+    let nodePath;
+    if (slashIndex === -1) {
+      treeId = fullPath.slice(1);
+      nodePath = "/";
+    } else {
+      treeId = fullPath.slice(1, slashIndex);
+      nodePath = fullPath.slice(slashIndex);
+    }
+    if (!treeId || treeId.trim() === "") {
+      throw new Error(
+        `Invalid path: tree ID cannot be empty in '${fullPath}'. Expected format: #TreeID/path`
+      );
+    }
+    if (!nodePath.startsWith("/")) {
+      throw new Error(
+        `Invalid path: node path must start with '/' in '${fullPath}'`
+      );
+    }
+    return { treeId, nodePath };
+  }
+  /**
+   * Get the root node of the tree
+   */
+  getRoot() {
+    return this.root;
+  }
+  /**
+   * Find a node by its path
+   * Path format: / for root, /0 for first child, /0/1 for second child of first child
+   */
+  findNodeByPath(path2) {
+    return this.pathIndex.get(path2) || null;
+  }
+  /**
+   * Find a node by its ID (if it has one)
+   * Convenience method for nodes with explicit IDs
+   */
+  findNodeById(nodeId) {
+    return this.idIndex.get(nodeId) || null;
+  }
+  /**
+   * Get the path for a given node
+   * Returns null if the node is not in the tree
+   */
+  getNodePath(targetNode) {
+    for (const [path2, node] of this.pathIndex.entries()) {
+      if (node === targetNode) {
+        return path2;
+      }
+    }
+    return null;
+  }
+  /**
+   * Get the path for a node by its ID
+   * More reliable than instance-based lookup
+   * Returns null if the node is not in the tree
+   */
+  getNodePathById(nodeId) {
+    const node = this.findNodeById(nodeId);
+    if (!node) return null;
+    for (const [path2, indexedNode] of this.pathIndex.entries()) {
+      if (indexedNode.id === nodeId) {
+        return path2;
+      }
+    }
+    return null;
+  }
+  /**
+   * Clone this BehaviorTree (deep clones the underlying TreeNode)
+   */
+  clone() {
+    const clonedRoot = this.root.clone();
+    return new _BehaviorTree(clonedRoot);
+  }
+  /**
+   * Convert this BehaviorTree to a Temporal workflow function
+   * Returns a workflow function that can be registered with Temporal
+   *
+   * @returns A Temporal workflow function that executes this behavior tree
+   *
+   * @example
+   * ```typescript
+   * import { BehaviorTree } from '@wayfarer-ai/btree';
+   * import { Sequence } from '@wayfarer-ai/btree';
+   * import { PrintAction } from '@wayfarer-ai/btree';
+   *
+   * const root = new Sequence({ id: 'root' });
+   * root.addChild(new PrintAction({ id: 'step1', message: 'Hello' }));
+   * root.addChild(new PrintAction({ id: 'step2', message: 'World' }));
+   *
+   * const tree = new BehaviorTree(root);
+   * const workflow = tree.toWorkflow();
+   *
+   * // Register with Temporal worker
+   * // Worker.create({ workflows: { myWorkflow: workflow }, ... })
+   * ```
+   */
+  toWorkflow() {
+    const root = this.root;
+    return async function behaviorTreeWorkflow(args) {
+      const context = {
+        blackboard: new ScopedBlackboard(),
+        treeRegistry: args.treeRegistry,
+        timestamp: Date.now(),
+        sessionId: args.sessionId || `session-${Date.now()}`,
+        // Store input immutably for ${input.key} resolution
+        input: args.input ? Object.freeze({ ...args.input }) : void 0,
+        // Pass activities for I/O operations (deterministic Temporal execution)
+        activities: args.activities,
+        // Pass tokenProvider for IntegrationAction authentication
+        tokenProvider: args.tokenProvider
+      };
+      if (args.input) {
+        for (const [key, value] of Object.entries(args.input)) {
+          context.blackboard.set(key, value);
+        }
+      }
+      const status = await root.tick(context);
+      return {
+        status,
+        output: context.blackboard.toJSON()
+      };
+    };
+  }
+  /**
+   * Replace a node at the given path with a new node
+   * Updates parent-child relationships and rebuilds the index
+   */
+  replaceNodeAtPath(path2, newNode) {
+    const oldNode = this.findNodeByPath(path2);
+    if (!oldNode) {
+      throw new Error(`Node not found at path: ${path2}`);
+    }
+    if (path2 === "/") {
+      this.root = newNode;
+      newNode.parent = void 0;
+    } else {
+      const pathParts = path2.split("/").filter((p) => p);
+      const lastPart = pathParts[pathParts.length - 1];
+      if (!lastPart) {
+        throw new Error(`Invalid path format: ${path2}`);
+      }
+      const childIndex = parseInt(lastPart, 10);
+      const parent = oldNode.parent;
+      if (!parent || !parent.children) {
+        throw new Error(`Cannot replace node: invalid parent at path ${path2}`);
+      }
+      parent.children[childIndex] = newNode;
+      newNode.parent = parent;
+    }
+    this.buildNodeIndex();
+  }
+  /**
+   * Build the node index with path-based and ID-based lookups
+   */
+  buildNodeIndex() {
+    this.pathIndex.clear();
+    this.idIndex.clear();
+    const indexNode = (node, path2) => {
+      this.pathIndex.set(path2, node);
+      if (node.id) {
+        this.idIndex.set(node.id, node);
+      }
+      if (node.children) {
+        node.children.forEach((child, index) => {
+          const childPath = path2 === "/" ? `/${index}` : `${path2}/${index}`;
+          indexNode(child, childPath);
+        });
+      }
+    };
+    indexNode(this.root, "/");
+  }
+};
+
+// src/composites/conditional.ts
+var Conditional = class extends CompositeNode {
+  condition;
+  thenBranch;
+  elseBranch;
+  conditionEvaluated = false;
+  selectedBranch;
+  /**
+   * Override addChild to enforce conditional structure
+   */
+  addChild(child) {
+    if (!this.condition) {
+      this.condition = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.thenBranch) {
+      this.thenBranch = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.elseBranch) {
+      this.elseBranch = child;
+      this._children.push(child);
+      child.parent = this;
+    } else {
+      throw new ConfigurationError(
+        "Conditional can have maximum 3 children (condition, then, else)"
+      );
+    }
+  }
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.condition) {
+      throw new Error("Conditional requires at least a condition child");
+    }
+    if (!this.thenBranch) {
+      throw new Error(
+        "Conditional requires at least condition and then branch"
+      );
+    }
+    if (!this.conditionEvaluated) {
+      this.log("Evaluating condition");
+      const conditionStatus = await this.condition.tick(context);
+      switch (conditionStatus) {
+        case "SUCCESS" /* SUCCESS */:
+          this.log("Condition succeeded - will execute then branch");
+          this.selectedBranch = this.thenBranch;
+          this.conditionEvaluated = true;
+          break;
+        case "FAILURE" /* FAILURE */:
+          if (this.elseBranch) {
+            this.log("Condition failed - will execute else branch");
+            this.selectedBranch = this.elseBranch;
+            this.conditionEvaluated = true;
+          } else {
+            this.log("Condition failed - no else branch, returning FAILURE");
+            this._status = "FAILURE" /* FAILURE */;
+            return "FAILURE" /* FAILURE */;
+          }
+          break;
+        case "RUNNING" /* RUNNING */:
+          this.log("Condition is running");
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        default:
+          throw new Error(
+            `Unexpected status from condition: ${conditionStatus}`
+          );
+      }
+    } else {
+      this.log("Condition already evaluated - continuing branch execution");
+    }
+    if (!this.selectedBranch) {
+      throw new Error("No branch selected for execution");
+    }
+    const branchStatus = await this.selectedBranch.tick(context);
+    this._status = branchStatus;
+    if (branchStatus !== "RUNNING" /* RUNNING */) {
+      this.log("Branch completed - resetting condition check flag");
+      this.conditionEvaluated = false;
+      this.selectedBranch = void 0;
+    }
+    return branchStatus;
+  }
+  onHalt() {
+    this.log("Halting - resetting condition check flag");
+    this.conditionEvaluated = false;
+    this.selectedBranch = void 0;
+    super.onHalt();
+  }
+  onReset() {
+    this.log("Resetting - clearing condition check flag");
+    this.conditionEvaluated = false;
+    this.selectedBranch = void 0;
+  }
+};
+
+// src/composites/for-each.ts
+var ForEach = class extends CompositeNode {
+  collectionKey;
+  itemKey;
+  indexKey;
+  currentIndex = 0;
+  constructor(config) {
+    super(config);
+    this.collectionKey = config.collectionKey;
+    this.itemKey = config.itemKey;
+    this.indexKey = config.indexKey;
+  }
+  async executeTick(context) {
+    if (this._children.length === 0) {
+      throw new ConfigurationError(
+        "ForEach requires at least one child (body)"
+      );
+    }
+    const body = this._children[0];
+    if (!body) {
+      throw new ConfigurationError(
+        "ForEach requires at least one child (body)"
+      );
+    }
+    const collection = context.blackboard.get(this.collectionKey);
+    if (!collection) {
+      this.log(`Collection '${this.collectionKey}' not found in blackboard`);
+      this._status = "FAILURE" /* FAILURE */;
+      return "FAILURE" /* FAILURE */;
+    }
+    if (!Array.isArray(collection)) {
+      throw new Error(`Collection '${this.collectionKey}' is not an array`);
+    }
+    if (collection.length === 0) {
+      this.log("Collection is empty - returning SUCCESS");
+      this._status = "SUCCESS" /* SUCCESS */;
+      return "SUCCESS" /* SUCCESS */;
+    }
+    this.log(
+      `Iterating over collection (${collection.length} items), starting at index ${this.currentIndex}`
+    );
+    while (this.currentIndex < collection.length) {
+      checkSignal(context.signal);
+      const item = collection[this.currentIndex];
+      context.blackboard.set(this.itemKey, item);
+      if (this.indexKey) {
+        context.blackboard.set(this.indexKey, this.currentIndex);
+      }
+      this.log(
+        `Processing item ${this.currentIndex}: ${JSON.stringify(item)}`
+      );
+      const bodyStatus = await body.tick(context);
+      switch (bodyStatus) {
+        case "SUCCESS" /* SUCCESS */:
+          this.log(`Item ${this.currentIndex} succeeded`);
+          this.currentIndex++;
+          body.reset();
+          break;
+        case "FAILURE" /* FAILURE */:
+          this.log(`Item ${this.currentIndex} failed - ForEach fails`);
+          this._status = "FAILURE" /* FAILURE */;
+          this.currentIndex = 0;
+          return "FAILURE" /* FAILURE */;
+        case "RUNNING" /* RUNNING */:
+          this.log(`Item ${this.currentIndex} is running`);
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        // Will resume from this index next tick
+        default:
+          throw new Error(`Unexpected status from body: ${bodyStatus}`);
+      }
+    }
+    this.log("All items processed successfully");
+    this._status = "SUCCESS" /* SUCCESS */;
+    this.currentIndex = 0;
+    return "SUCCESS" /* SUCCESS */;
+  }
+  onReset() {
+    super.onReset();
+    this.currentIndex = 0;
+  }
+  onHalt() {
+    super.onHalt();
+    this.currentIndex = 0;
+  }
+};
+
+// src/composites/sequence.ts
+var Sequence = class extends CompositeNode {
+  currentChildIndex = 0;
+  async executeTick(context) {
+    this.log("Ticking with", this._children.length, "children");
+    if (this._children.length === 0) {
+      return "SUCCESS" /* SUCCESS */;
+    }
+    while (this.currentChildIndex < this._children.length) {
+      checkSignal(context.signal);
+      const child = this._children[this.currentChildIndex];
+      if (!child) {
+        throw new Error(
+          `Child at index ${this.currentChildIndex} is undefined`
+        );
+      }
+      this.log(`Ticking child ${this.currentChildIndex}: ${child.name}`);
+      const childStatus = await child.tick(context);
+      switch (childStatus) {
+        case "SUCCESS" /* SUCCESS */:
+          this.log(`Child ${child.name} succeeded`);
+          this.currentChildIndex++;
+          break;
+        case "FAILURE" /* FAILURE */:
+          this.log(`Child ${child.name} failed - sequence fails`);
+          this._status = "FAILURE" /* FAILURE */;
+          this.currentChildIndex = 0;
+          return "FAILURE" /* FAILURE */;
+        case "RUNNING" /* RUNNING */:
+          this.log(`Child ${child.name} is running`);
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        default:
+          throw new Error(`Unexpected status from child: ${childStatus}`);
+      }
+    }
+    this.log("All children succeeded");
+    this._status = "SUCCESS" /* SUCCESS */;
+    this.currentChildIndex = 0;
+    return "SUCCESS" /* SUCCESS */;
+  }
+  onHalt() {
+    this.haltChildren(this.currentChildIndex);
+    this.currentChildIndex = 0;
+  }
+  onReset() {
+    this.currentChildIndex = 0;
+  }
+};
+
+// src/composites/memory-sequence.ts
+var MemorySequence = class extends Sequence {
+  completedChildren = /* @__PURE__ */ new Set();
+  async executeTick(context) {
+    this.log(
+      `Ticking with ${this._children.length} children (${this.completedChildren.size} completed)`
+    );
+    if (this._children.length === 0) {
+      return "SUCCESS" /* SUCCESS */;
+    }
+    for (let i = 0; i < this._children.length; i++) {
+      checkSignal(context.signal);
+      const child = this._children[i];
+      if (!child) {
+        throw new ConfigurationError(`Child at index ${i} is undefined`);
+      }
+      if (this.completedChildren.has(child.id)) {
+        this.log(`Skipping completed child: ${child.name}`);
+        continue;
+      }
+      this.log(`Ticking child ${i}: ${child.name}`);
+      const childStatus = await child.tick(context);
+      switch (childStatus) {
+        case "SUCCESS" /* SUCCESS */:
+          this.log(`Child ${child.name} succeeded - remembering`);
+          this.completedChildren.add(child.id);
+          break;
+        case "FAILURE" /* FAILURE */:
+          this.log(`Child ${child.name} failed - sequence fails`);
+          this._status = "FAILURE" /* FAILURE */;
+          return "FAILURE" /* FAILURE */;
+        case "RUNNING" /* RUNNING */:
+          this.log(`Child ${child.name} is running`);
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        default:
+          throw new Error(`Unexpected status from child: ${childStatus}`);
+      }
+    }
+    this.log("All children succeeded");
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+  onReset() {
+    super.onReset();
+    this.log("Clearing completed children memory");
+    this.completedChildren.clear();
+  }
+  onHalt() {
+    super.onHalt();
+  }
+};
+var SequenceWithMemory = class extends MemorySequence {
+  constructor(config) {
+    super({ ...config, type: "SequenceWithMemory" });
+  }
+};
+
+// src/composites/parallel.ts
+var Parallel = class extends CompositeNode {
+  strategy;
+  successThreshold;
+  failureThreshold;
+  constructor(config) {
+    super(config);
+    this.strategy = config.strategy ?? "strict";
+    this.successThreshold = config.successThreshold;
+    this.failureThreshold = config.failureThreshold;
+  }
+  async executeTick(context) {
+    this.log(
+      `Ticking with ${this._children.length} children (strategy: ${this.strategy})`
+    );
+    if (this._children.length === 0) {
+      return "SUCCESS" /* SUCCESS */;
+    }
+    const childrenToTick = this._children.filter((child) => {
+      const status = child.status();
+      return status === "IDLE" /* IDLE */ || status === "RUNNING" /* RUNNING */;
+    });
+    this.log(
+      `Ticking ${childrenToTick.length}/${this._children.length} children (others completed)`
+    );
+    checkSignal(context.signal);
+    if (childrenToTick.length > 0) {
+      await Promise.all(childrenToTick.map((child) => child.tick(context)));
+    }
+    const allStatuses = this._children.map((child) => child.status());
+    const hasRunning = allStatuses.some(
+      (status) => status === "RUNNING" /* RUNNING */
+    );
+    if (hasRunning) {
+      this.log("At least one child returned RUNNING");
+      return "RUNNING" /* RUNNING */;
+    }
+    const successes = allStatuses.filter(
+      (status) => status === "SUCCESS" /* SUCCESS */
+    ).length;
+    const failures = allStatuses.filter(
+      (status) => status === "FAILURE" /* FAILURE */
+    ).length;
+    this.log(`Results - Successes: ${successes}, Failures: ${failures}`);
+    if (this.successThreshold !== void 0 && successes >= this.successThreshold) {
+      this.log(
+        `Success threshold met: ${successes}/${this.successThreshold} -> SUCCESS`
+      );
+      return "SUCCESS" /* SUCCESS */;
+    }
+    if (this.failureThreshold !== void 0 && failures >= this.failureThreshold) {
+      this.log(
+        `Failure threshold met: ${failures}/${this.failureThreshold} -> FAILURE`
+      );
+      return "FAILURE" /* FAILURE */;
+    }
+    if (this.strategy === "strict") {
+      const finalStatus = successes === this._children.length ? "SUCCESS" /* SUCCESS */ : "FAILURE" /* FAILURE */;
+      this.log(
+        `Strategy 'strict': ${successes}/${this._children.length} succeeded -> ${finalStatus}`
+      );
+      return finalStatus;
+    } else {
+      const finalStatus = successes > 0 ? "SUCCESS" /* SUCCESS */ : "FAILURE" /* FAILURE */;
+      this.log(`Strategy 'any': ${successes} succeeded -> ${finalStatus}`);
+      return finalStatus;
+    }
+  }
+  onHalt() {
+    this.log("Halting parallel execution");
+    for (const child of this._children) {
+      if (child.status() === "RUNNING" /* RUNNING */) {
+        child.halt();
+      }
+    }
+  }
+  onReset() {
+    this.log("Resetting parallel state");
+  }
+};
+
+// src/composites/reactive-sequence.ts
+var ReactiveSequence = class extends Sequence {
+  async executeTick(context) {
+    this.log("Ticking (reactive - always starts from beginning)");
+    if (this._children.length === 0) {
+      return "SUCCESS" /* SUCCESS */;
+    }
+    for (let i = 0; i < this._children.length; i++) {
+      checkSignal(context.signal);
+      const child = this._children[i];
+      if (!child) {
+        throw new ConfigurationError(`Child at index ${i} is undefined`);
+      }
+      this.log(`Ticking child ${i}: ${child.name}`);
+      const childStatus = await child.tick(context);
+      switch (childStatus) {
+        case "SUCCESS" /* SUCCESS */:
+          this.log(`Child ${child.name} succeeded`);
+          break;
+        case "FAILURE" /* FAILURE */:
+          this.log(`Child ${child.name} failed - sequence fails`);
+          this._status = "FAILURE" /* FAILURE */;
+          return "FAILURE" /* FAILURE */;
+        case "RUNNING" /* RUNNING */:
+          this.log(`Child ${child.name} is running`);
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        default:
+          throw new Error(`Unexpected status from child: ${childStatus}`);
+      }
+    }
+    this.log("All children succeeded");
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+  /**
+   * Override to prevent parent Sequence from resetting currentChildIndex
+   * (ReactiveSequence doesn't use currentChildIndex)
+   */
+  onReset() {
+    this._status = "IDLE" /* IDLE */;
+    for (const child of this._children) {
+      child.reset();
+    }
+  }
+};
+
+// src/composites/recovery.ts
+var Recovery = class extends CompositeNode {
+  tryBranch;
+  catchBranch;
+  finallyBranch;
+  addChild(child) {
+    if (!this.tryBranch) {
+      this.tryBranch = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.catchBranch) {
+      this.catchBranch = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.finallyBranch) {
+      this.finallyBranch = child;
+      this._children.push(child);
+      child.parent = this;
+    } else {
+      throw new ConfigurationError(
+        "Recovery can have maximum 3 children (try, catch, finally)"
+      );
+    }
+  }
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.tryBranch) {
+      throw new ConfigurationError("Recovery requires at least a try branch");
+    }
+    this.log("Executing try branch");
+    const tryResult = await this.tryBranch.tick(context);
+    let mainResult;
+    if (tryResult === "FAILURE" /* FAILURE */ && this.catchBranch) {
+      this.log("Try branch failed - executing catch branch");
+      mainResult = await this.catchBranch.tick(context);
+    } else {
+      mainResult = tryResult;
+    }
+    if (this.finallyBranch) {
+      this.log("Executing finally branch");
+      await this.finallyBranch.tick(context);
+      this.log("Finally branch completed");
+    }
+    this._status = mainResult;
+    return mainResult;
+  }
+};
+
+// src/composites/selector.ts
+var Selector = class extends CompositeNode {
+  currentChildIndex = 0;
+  async executeTick(context) {
+    this.log("Ticking with", this._children.length, "children");
+    if (this._children.length === 0) {
+      return "FAILURE" /* FAILURE */;
+    }
+    while (this.currentChildIndex < this._children.length) {
+      checkSignal(context.signal);
+      const child = this._children[this.currentChildIndex];
+      if (!child) {
+        throw new Error(
+          `Child at index ${this.currentChildIndex} is undefined`
+        );
+      }
+      this.log(`Ticking child ${this.currentChildIndex}: ${child.name}`);
+      const childStatus = await child.tick(context);
+      switch (childStatus) {
+        case "SUCCESS" /* SUCCESS */:
+          this.log(`Child ${child.name} succeeded - selector succeeds`);
+          this._status = "SUCCESS" /* SUCCESS */;
+          this.currentChildIndex = 0;
+          return "SUCCESS" /* SUCCESS */;
+        case "FAILURE" /* FAILURE */:
+          this.log(`Child ${child.name} failed`);
+          this.currentChildIndex++;
+          break;
+        case "RUNNING" /* RUNNING */:
+          this.log(`Child ${child.name} is running`);
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        default:
+          throw new Error(`Unexpected status from child: ${childStatus}`);
+      }
+    }
+    this.log("All children failed");
+    this._status = "FAILURE" /* FAILURE */;
+    this.currentChildIndex = 0;
+    return "FAILURE" /* FAILURE */;
+  }
+  onHalt() {
+    this.haltChildren(this.currentChildIndex);
+    this.currentChildIndex = 0;
+  }
+  onReset() {
+    this.currentChildIndex = 0;
+  }
+};
+var Fallback = class extends Selector {
+  constructor(config) {
+    super({ ...config, type: "Fallback" });
+  }
+};
+
+// src/utilities/variable-resolver.ts
+var VARIABLE_PATTERN = /\$\{(input|bb|env|param)\.([a-zA-Z0-9_.]+)\}|\$\{([a-zA-Z0-9_.]+)\}/g;
+var HAS_VARIABLE_PATTERN = /\$\{(input|bb|env|param)\.([a-zA-Z0-9_.]+)\}|\$\{([a-zA-Z0-9_.]+)\}/;
+var FULL_MATCH_PATTERN = /^\$\{(input|bb|env|param)\.([a-zA-Z0-9_.]+)\}$|^\$\{([a-zA-Z0-9_.]+)\}$/;
+var safeProcessEnv = () => {
+  try {
+    return typeof process !== "undefined" && process?.env ? process.env : {};
+  } catch {
+    return {};
+  }
+};
+function resolveString(str, ctx, opts = {}) {
+  const { preserveUndefined = true, envSource = safeProcessEnv() } = opts;
+  const fullMatch = str.match(FULL_MATCH_PATTERN);
+  if (fullMatch) {
+    const namespace = fullMatch[1];
+    const namespacedKey = fullMatch[2];
+    const simpleKey = fullMatch[3];
+    const key = namespacedKey || simpleKey;
+    const ns = namespace || "bb";
+    if (key) {
+      const value = resolveVariable(ns, key, ctx, envSource);
+      if (value !== void 0) {
+        return value;
+      }
+      return preserveUndefined ? str : void 0;
+    }
+  }
+  return str.replace(VARIABLE_PATTERN, (match, namespace, namespacedKey, simpleKey) => {
+    const key = namespacedKey || simpleKey;
+    const ns = namespace || "bb";
+    const value = resolveVariable(ns, key, ctx, envSource);
+    if (value === void 0) {
+      return preserveUndefined ? match : "";
+    }
+    if (value === null) {
+      return "null";
+    }
+    if (typeof value === "object") {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return String(value);
+      }
+    }
+    return String(value);
+  });
+}
+function resolveValue(value, ctx, opts = {}) {
+  if (typeof value === "string") {
+    return resolveString(value, ctx, opts);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveValue(item, ctx, opts));
+  }
+  if (value !== null && typeof value === "object") {
+    const resolved = {};
+    for (const [key, val] of Object.entries(value)) {
+      resolved[key] = resolveValue(val, ctx, opts);
+    }
+    return resolved;
+  }
+  return value;
+}
+function resolveVariable(namespace, key, ctx, envSource) {
+  switch (namespace) {
+    case "input":
+      return getNestedValue(ctx.input, key);
+    case "bb":
+      return getNestedBlackboardValue(ctx.blackboard, key);
+    case "env":
+      return envSource[key];
+    case "param":
+      if (ctx.testData) {
+        const parts = key.split(".");
+        const firstPart = parts[0];
+        if (firstPart) {
+          let value = ctx.testData.get(firstPart);
+          for (let i = 1; i < parts.length && value !== void 0; i++) {
+            const part = parts[i];
+            if (part && typeof value === "object" && value !== null) {
+              value = value[part];
+            } else {
+              return void 0;
+            }
+          }
+          return value;
+        }
+      }
+      return void 0;
+    default:
+      return getNestedBlackboardValue(ctx.blackboard, key);
+  }
+}
+function getNestedValue(obj, path2) {
+  if (obj === void 0 || obj === null) {
+    return void 0;
+  }
+  if (typeof obj !== "object") {
+    return void 0;
+  }
+  const parts = path2.split(".");
+  let value = obj;
+  for (const part of parts) {
+    if (value === void 0 || value === null) {
+      return void 0;
+    }
+    if (typeof value !== "object") {
+      return void 0;
+    }
+    value = value[part];
+  }
+  return value;
+}
+function getNestedBlackboardValue(blackboard, path2) {
+  const parts = path2.split(".");
+  const firstPart = parts[0];
+  if (!firstPart) {
+    return void 0;
+  }
+  let value = blackboard.get(firstPart);
+  for (let i = 1; i < parts.length && value !== void 0; i++) {
+    const part = parts[i];
+    if (part && typeof value === "object" && value !== null) {
+      value = value[part];
+    } else {
+      return void 0;
+    }
+  }
+  return value;
+}
+function hasVariables(str) {
+  return HAS_VARIABLE_PATTERN.test(str);
+}
+function extractVariables(str) {
+  const variables = [];
+  const pattern = /\$\{(input|bb|env|param)\.([a-zA-Z0-9_.]+)\}|\$\{([a-zA-Z0-9_.]+)\}/g;
+  let match;
+  while ((match = pattern.exec(str)) !== null) {
+    const namespace = match[1] || "bb";
+    const key = match[2] || match[3];
+    if (key) {
+      variables.push({ namespace, key });
+    }
+  }
+  return variables;
+}
+
+// src/composites/sub-tree.ts
+var SubTree = class extends ActionNode {
+  treeId;
+  params;
+  outputs;
+  clonedTree;
+  // Cached tree instance
+  constructor(config) {
+    super(config);
+    this.treeId = config.treeId;
+    this.params = config.params ?? {};
+    this.outputs = config.outputs ?? [];
+  }
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.clonedTree) {
+      if (!context.treeRegistry.hasTree(this.treeId)) {
+        throw new Error(
+          `SubTree tree '${this.treeId}' not found in registry. Available trees: ${context.treeRegistry.getAllTreeIds().join(", ") || "none"}`
+        );
+      }
+      const clonedBehaviorTree = context.treeRegistry.cloneTree(this.treeId);
+      this.clonedTree = clonedBehaviorTree.getRoot();
+      this.log(`Cloned SubTree tree '${this.treeId}' from registry`);
+    }
+    const subtreeScope = context.blackboard.createScope(`subtree_${this.id}`);
+    this.log(`Created scoped blackboard: ${subtreeScope.getFullScopePath()}`);
+    if (Object.keys(this.params).length > 0) {
+      const varCtx = {
+        blackboard: context.blackboard,
+        input: context.input,
+        testData: context.testData
+      };
+      const resolvedParams = resolveValue(this.params, varCtx);
+      for (const [key, value] of Object.entries(resolvedParams)) {
+        subtreeScope.set(key, value);
+        this.log(`Set param '${key}' in subtree scope`);
+      }
+    }
+    const scopedContext = {
+      ...context,
+      blackboard: subtreeScope
+    };
+    try {
+      this.log(`Executing SubTree tree '${this.treeId}'`);
+      const status = await this.clonedTree.tick(scopedContext);
+      if (this.outputs.length > 0 && (status === "SUCCESS" /* SUCCESS */ || status === "RUNNING" /* RUNNING */)) {
+        for (const outputKey of this.outputs) {
+          if (subtreeScope.has(outputKey)) {
+            const value = subtreeScope.get(outputKey);
+            context.blackboard.set(outputKey, value);
+            this.log(`Exported output '${outputKey}' to parent scope`);
+          } else {
+            this.log(`Output '${outputKey}' not found in subtree scope, skipping`);
+          }
+        }
+      }
+      this.log(
+        `SubTree tree '${this.treeId}' completed with status: ${status}`
+      );
+      return status;
+    } catch (error) {
+      this.log(`SubTree tree '${this.treeId}' failed with error: ${error}`);
+      throw error;
+    }
+  }
+  /**
+   * Override clone to include cloned tree
+   */
+  clone() {
+    const ClonedClass = this.constructor;
+    const cloned = new ClonedClass({ ...this.config });
+    return cloned;
+  }
+  /**
+   * Override halt to halt the referenced tree
+   */
+  halt() {
+    super.halt();
+    if (this.clonedTree && this.clonedTree.status() === "RUNNING" /* RUNNING */) {
+      this.clonedTree.halt();
+    }
+  }
+  /**
+   * Override reset to reset the referenced tree
+   */
+  reset() {
+    super.reset();
+    if (this.clonedTree) {
+      this.clonedTree.reset();
+    }
+  }
+};
+
+// src/composites/while.ts
+var While = class extends CompositeNode {
+  maxIterations;
+  currentIteration = 0;
+  condition;
+  body;
+  bodyStarted = false;
+  constructor(config) {
+    super(config);
+    this.maxIterations = config.maxIterations ?? 1e3;
+  }
+  addChild(child) {
+    if (!this.condition) {
+      this.condition = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.body) {
+      this.body = child;
+      this._children.push(child);
+      child.parent = this;
+    } else {
+      throw new ConfigurationError(
+        "While can have maximum 2 children (condition, body)"
+      );
+    }
+  }
+  async executeTick(context) {
+    if (!this.condition) {
+      throw new ConfigurationError("While requires a condition child");
+    }
+    if (!this.body) {
+      throw new ConfigurationError("While requires a body child");
+    }
+    this.log(
+      `Starting while loop (iteration ${this.currentIteration}/${this.maxIterations})`
+    );
+    while (this.currentIteration < this.maxIterations) {
+      checkSignal(context.signal);
+      if (!this.bodyStarted) {
+        this.log(`Evaluating condition (iteration ${this.currentIteration})`);
+        const conditionStatus = await this.condition.tick(context);
+        if (conditionStatus === "RUNNING" /* RUNNING */) {
+          this.log("Condition is running");
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        }
+        if (conditionStatus === "FAILURE" /* FAILURE */) {
+          this.log("Condition failed - exiting loop");
+          this._status = "SUCCESS" /* SUCCESS */;
+          this.currentIteration = 0;
+          this.bodyStarted = false;
+          return "SUCCESS" /* SUCCESS */;
+        }
+        this.bodyStarted = true;
+      } else {
+        this.log(
+          `Body already started for iteration ${this.currentIteration} - continuing execution`
+        );
+      }
+      this.log(`Executing body (iteration ${this.currentIteration})`);
+      const bodyStatus = await this.body.tick(context);
+      switch (bodyStatus) {
+        case "SUCCESS" /* SUCCESS */:
+          this.log("Body succeeded - continuing loop");
+          this.currentIteration++;
+          this.bodyStarted = false;
+          this.condition.reset();
+          this.body.reset();
+          break;
+        case "FAILURE" /* FAILURE */:
+          this.log("Body failed - While fails");
+          this._status = "FAILURE" /* FAILURE */;
+          this.currentIteration = 0;
+          this.bodyStarted = false;
+          return "FAILURE" /* FAILURE */;
+        case "RUNNING" /* RUNNING */:
+          this.log("Body is running");
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        default:
+          throw new Error(`Unexpected status from body: ${bodyStatus}`);
+      }
+    }
+    this.log(`Max iterations (${this.maxIterations}) reached`);
+    this._status = "FAILURE" /* FAILURE */;
+    this.currentIteration = 0;
+    this.bodyStarted = false;
+    return "FAILURE" /* FAILURE */;
+  }
+  onReset() {
+    super.onReset();
+    this.log("Resetting - clearing body started flag");
+    this.currentIteration = 0;
+    this.bodyStarted = false;
+  }
+  onHalt() {
+    super.onHalt();
+    this.log("Halting - clearing body started flag");
+    this.currentIteration = 0;
+    this.bodyStarted = false;
+  }
+};
+
+// src/decorators/delay.ts
+import { sleep } from "@temporalio/workflow";
+var Delay = class extends DecoratorNode {
+  delayMs;
+  delayStartTime = null;
+  useTemporalAPI = null;
+  // Cached detection result
+  constructor(config) {
+    super(config);
+    this.delayMs = config.delayMs;
+    if (this.delayMs < 0) {
+      throw new ConfigurationError(
+        `${this.name}: Delay must be non-negative (got ${this.delayMs})`
+      );
+    }
+  }
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError(`${this.name}: Decorator must have a child`);
+    }
+    if (this.delayMs === 0) {
+      return await this.child.tick(context);
+    }
+    if (this.useTemporalAPI === null) {
+      try {
+        this.log(`Starting delay of ${this.delayMs}ms`);
+        await sleep(this.delayMs);
+        this.useTemporalAPI = true;
+        this.log("Delay completed, executing child");
+        checkSignal(context.signal);
+        const childStatus2 = await this.child.tick(context);
+        this._status = childStatus2;
+        return childStatus2;
+      } catch (err) {
+        this.useTemporalAPI = false;
+      }
+    }
+    if (this.useTemporalAPI === true) {
+      this.log(`Starting delay of ${this.delayMs}ms`);
+      await sleep(this.delayMs);
+      this.log("Delay completed, executing child");
+      checkSignal(context.signal);
+      const childStatus2 = await this.child.tick(context);
+      this._status = childStatus2;
+      return childStatus2;
+    }
+    if (this.child.status() === "RUNNING" /* RUNNING */) {
+      checkSignal(context.signal);
+      const childStatus2 = await this.child.tick(context);
+      if (childStatus2 !== "RUNNING" /* RUNNING */) {
+        this.delayStartTime = null;
+      }
+      this._status = childStatus2;
+      return childStatus2;
+    }
+    if (this.delayStartTime === null) {
+      this.delayStartTime = Date.now();
+      this.log(`Starting delay of ${this.delayMs}ms`);
+    }
+    const elapsed = Date.now() - this.delayStartTime;
+    if (elapsed < this.delayMs) {
+      this._status = "RUNNING" /* RUNNING */;
+      return "RUNNING" /* RUNNING */;
+    }
+    this.log("Delay completed, executing child");
+    checkSignal(context.signal);
+    const childStatus = await this.child.tick(context);
+    if (childStatus !== "RUNNING" /* RUNNING */) {
+      this.delayStartTime = null;
+    }
+    this._status = childStatus;
+    return childStatus;
+  }
+  onHalt() {
+    this.delayStartTime = null;
+  }
+  onReset() {
+    this.delayStartTime = null;
+    this.useTemporalAPI = null;
+  }
+};
+
+// src/decorators/force-result.ts
+var ForceSuccess = class extends DecoratorNode {
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError("ForceSuccess requires a child");
+    }
+    const childStatus = await this.child.tick(context);
+    if (childStatus === "RUNNING" /* RUNNING */) {
+      this._status = "RUNNING" /* RUNNING */;
+      return "RUNNING" /* RUNNING */;
+    }
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+};
+var ForceFailure = class extends DecoratorNode {
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError("ForceFailure requires a child");
+    }
+    const childStatus = await this.child.tick(context);
+    if (childStatus === "RUNNING" /* RUNNING */) {
+      this._status = "RUNNING" /* RUNNING */;
+      return "RUNNING" /* RUNNING */;
+    }
+    this._status = "FAILURE" /* FAILURE */;
+    return "FAILURE" /* FAILURE */;
+  }
+};
+
+// src/decorators/invert.ts
+var Invert = class extends DecoratorNode {
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError(`${this.name}: Decorator must have a child`);
+    }
+    this.log("Ticking child");
+    const childStatus = await this.child.tick(context);
+    switch (childStatus) {
+      case "SUCCESS" /* SUCCESS */:
+        this.log("Child succeeded - returning FAILURE");
+        this._status = "FAILURE" /* FAILURE */;
+        return "FAILURE" /* FAILURE */;
+      case "FAILURE" /* FAILURE */:
+        this.log("Child failed - returning SUCCESS");
+        this._status = "SUCCESS" /* SUCCESS */;
+        return "SUCCESS" /* SUCCESS */;
+      case "RUNNING" /* RUNNING */:
+        this.log("Child is running");
+        this._status = "RUNNING" /* RUNNING */;
+        return "RUNNING" /* RUNNING */;
+      default:
+        return childStatus;
+    }
+  }
+};
+
+// src/decorators/keep-running.ts
+var KeepRunningUntilFailure = class extends DecoratorNode {
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError(
+        "KeepRunningUntilFailure requires a child"
+      );
+    }
+    const result = await this.child.tick(context);
+    switch (result) {
+      case "SUCCESS" /* SUCCESS */:
+        this.log("Child succeeded - resetting and continuing");
+        this.child.reset();
+        this._status = "RUNNING" /* RUNNING */;
+        return "RUNNING" /* RUNNING */;
+      case "FAILURE" /* FAILURE */:
+        this.log("Child failed - goal achieved");
+        this._status = "SUCCESS" /* SUCCESS */;
+        return "SUCCESS" /* SUCCESS */;
+      case "RUNNING" /* RUNNING */:
+        this.log("Child is running");
+        this._status = "RUNNING" /* RUNNING */;
+        return "RUNNING" /* RUNNING */;
+      default:
+        throw new Error(`Unexpected status from child: ${result}`);
+    }
+  }
+};
+
+// src/decorators/precondition.ts
+var Precondition = class extends DecoratorNode {
+  preconditions = [];
+  preconditionsChecked = false;
+  /**
+   * Add a precondition to check before main execution
+   */
+  addPrecondition(condition, resolver, required = true) {
+    this.preconditions.push({ condition, resolver, required });
+  }
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError("Precondition requires a child");
+    }
+    if (!this.preconditionsChecked) {
+      for (let i = 0; i < this.preconditions.length; i++) {
+        checkSignal(context.signal);
+        const precond = this.preconditions[i];
+        if (!precond) {
+          continue;
+        }
+        this.log(
+          `Checking precondition ${i + 1}/${this.preconditions.length}`
+        );
+        const conditionResult = await precond.condition.tick(context);
+        if (conditionResult === "RUNNING" /* RUNNING */) {
+          this.log(`Precondition ${i + 1} is running`);
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        }
+        if (conditionResult === "FAILURE" /* FAILURE */) {
+          this.log(`Precondition ${i + 1} failed`);
+          if (precond.resolver) {
+            this.log(`Attempting to resolve precondition ${i + 1}`);
+            const resolverResult = await precond.resolver.tick(context);
+            if (resolverResult === "RUNNING" /* RUNNING */) {
+              this.log(`Resolver ${i + 1} is running`);
+              this._status = "RUNNING" /* RUNNING */;
+              return "RUNNING" /* RUNNING */;
+            }
+            if (resolverResult === "SUCCESS" /* SUCCESS */) {
+              this.log(`Precondition ${i + 1} resolved successfully`);
+              const recheckResult = await precond.condition.tick(context);
+              if (recheckResult !== "SUCCESS" /* SUCCESS */) {
+                if (precond.required) {
+                  this.log(
+                    `Precondition ${i + 1} still not met after resolution`
+                  );
+                  this._status = "FAILURE" /* FAILURE */;
+                  return "FAILURE" /* FAILURE */;
+                } else {
+                  this.log(`Optional precondition ${i + 1} skipped`);
+                }
+              }
+            } else if (precond.required) {
+              this.log(`Failed to resolve required precondition ${i + 1}`);
+              this._status = "FAILURE" /* FAILURE */;
+              return "FAILURE" /* FAILURE */;
+            }
+          } else if (precond.required) {
+            this.log(`Required precondition ${i + 1} not met (no resolver)`);
+            this._status = "FAILURE" /* FAILURE */;
+            return "FAILURE" /* FAILURE */;
+          } else {
+            this.log(`Optional precondition ${i + 1} skipped`);
+          }
+        }
+      }
+      this.preconditionsChecked = true;
+      this.log("All preconditions met - executing main child");
+    } else {
+      this.log("Preconditions already verified - continuing child execution");
+    }
+    checkSignal(context.signal);
+    const result = await this.child.tick(context);
+    this._status = result;
+    if (result !== "RUNNING" /* RUNNING */) {
+      this.log("Child completed - resetting precondition check flag");
+      this.preconditionsChecked = false;
+    }
+    return result;
+  }
+  onHalt() {
+    this.log("Halting - resetting precondition check flag");
+    this.preconditionsChecked = false;
+    super.onHalt();
+  }
+  onReset() {
+    this.log("Resetting - clearing precondition check flag");
+    this.preconditionsChecked = false;
+  }
+};
+
+// src/decorators/repeat.ts
+var Repeat = class extends DecoratorNode {
+  numCycles;
+  currentCycle = 0;
+  constructor(config) {
+    super(config);
+    this.numCycles = config.numCycles;
+  }
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError("Repeat requires a child");
+    }
+    this.log(`Repeat cycle ${this.currentCycle}/${this.numCycles}`);
+    if (this.currentCycle >= this.numCycles) {
+      this.log("All cycles completed");
+      this._status = "SUCCESS" /* SUCCESS */;
+      this.currentCycle = 0;
+      return "SUCCESS" /* SUCCESS */;
+    }
+    const result = await this.child.tick(context);
+    switch (result) {
+      case "SUCCESS" /* SUCCESS */:
+        this.log(`Cycle ${this.currentCycle} succeeded`);
+        this.currentCycle++;
+        if (this.currentCycle < this.numCycles) {
+          this.child.reset();
+          this._status = "RUNNING" /* RUNNING */;
+          return "RUNNING" /* RUNNING */;
+        } else {
+          this._status = "SUCCESS" /* SUCCESS */;
+          this.currentCycle = 0;
+          return "SUCCESS" /* SUCCESS */;
+        }
+      case "FAILURE" /* FAILURE */:
+        this.log(`Cycle ${this.currentCycle} failed`);
+        this._status = "FAILURE" /* FAILURE */;
+        this.currentCycle = 0;
+        return "FAILURE" /* FAILURE */;
+      case "RUNNING" /* RUNNING */:
+        this.log(`Cycle ${this.currentCycle} is running`);
+        this._status = "RUNNING" /* RUNNING */;
+        return "RUNNING" /* RUNNING */;
+      default:
+        throw new Error(`Unexpected status from child: ${result}`);
+    }
+  }
+  onReset() {
+    super.onReset();
+    this.currentCycle = 0;
+  }
+  onHalt() {
+    super.onHalt();
+    this.currentCycle = 0;
+  }
+};
+
+// src/decorators/run-once.ts
+var RunOnce = class extends DecoratorNode {
+  hasRun = false;
+  cachedResult;
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError("RunOnce requires a child");
+    }
+    if (this.hasRun) {
+      this.log(
+        `Already executed, returning cached result: ${this.cachedResult}`
+      );
+      if (this.cachedResult === void 0) {
+        this._status = "RUNNING" /* RUNNING */;
+        return "RUNNING" /* RUNNING */;
+      }
+      this._status = this.cachedResult;
+      return this.cachedResult;
+    }
+    this.log("First execution - ticking child");
+    const result = await this.child.tick(context);
+    if (result !== "RUNNING" /* RUNNING */) {
+      this.hasRun = true;
+      this.cachedResult = result;
+      this.log(`Caching result: ${result}`);
+    } else {
+      this.log("Child is running - will retry on next tick");
+    }
+    this._status = result;
+    return result;
+  }
+  onReset() {
+    super.onReset();
+    this.hasRun = false;
+    this.cachedResult = void 0;
+  }
+};
+
+// src/decorators/soft-assert.ts
+var SoftAssert = class extends DecoratorNode {
+  failures = [];
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError("SoftAssert requires a child");
+    }
+    const result = await this.child.tick(context);
+    if (result === "FAILURE" /* FAILURE */) {
+      const failure = {
+        timestamp: Date.now(),
+        message: `Soft assertion failed: ${this.child.name}`
+      };
+      this.failures.push(failure);
+      this.log(`Soft assertion failed (continuing): ${this.child.name}`);
+      this._status = "SUCCESS" /* SUCCESS */;
+      return "SUCCESS" /* SUCCESS */;
+    }
+    this._status = result;
+    return result;
+  }
+  /**
+   * Get all recorded failures
+   */
+  getFailures() {
+    return [...this.failures];
+  }
+  /**
+   * Check if any assertions have failed
+   */
+  hasFailures() {
+    return this.failures.length > 0;
+  }
+  onReset() {
+    super.onReset();
+    this.failures = [];
+  }
+};
+
+// src/decorators/timeout.ts
+import { CancellationScope, isCancellation } from "@temporalio/workflow";
+var Timeout = class extends DecoratorNode {
+  timeoutMs;
+  startTime = null;
+  useTemporalAPI = null;
+  // Cached detection result
+  constructor(config) {
+    super(config);
+    this.timeoutMs = config.timeoutMs;
+    if (this.timeoutMs <= 0) {
+      throw new ConfigurationError(
+        `${this.name}: Timeout must be positive (got ${this.timeoutMs})`
+      );
+    }
+  }
+  async executeTick(context) {
+    checkSignal(context.signal);
+    if (!this.child) {
+      throw new ConfigurationError(`${this.name}: Decorator must have a child`);
+    }
+    if (this.useTemporalAPI === null) {
+      try {
+        this.log(`Starting timeout for ${this.timeoutMs}ms`);
+        const childStatus2 = await CancellationScope.withTimeout(
+          this.timeoutMs,
+          async () => {
+            return await this.child.tick(context);
+          }
+        );
+        this.useTemporalAPI = true;
+        this._status = childStatus2;
+        this.log(`Child completed with ${childStatus2}`);
+        return childStatus2;
+      } catch (err) {
+        if (isCancellation(err)) {
+          this.useTemporalAPI = true;
+          this.log(`Timeout after ${this.timeoutMs}ms`);
+          if (this.child.status() === "RUNNING" /* RUNNING */) {
+            this.child.halt();
+          }
+          this._status = "FAILURE" /* FAILURE */;
+          return "FAILURE" /* FAILURE */;
+        }
+        this.useTemporalAPI = false;
+      }
+    }
+    if (this.useTemporalAPI === true) {
+      try {
+        this.log(`Starting timeout for ${this.timeoutMs}ms`);
+        const childStatus2 = await CancellationScope.withTimeout(
+          this.timeoutMs,
+          async () => {
+            return await this.child.tick(context);
+          }
+        );
+        this._status = childStatus2;
+        this.log(`Child completed with ${childStatus2}`);
+        return childStatus2;
+      } catch (err) {
+        if (isCancellation(err)) {
+          this.log(`Timeout after ${this.timeoutMs}ms`);
+          if (this.child.status() === "RUNNING" /* RUNNING */) {
+            this.child.halt();
+          }
+          this._status = "FAILURE" /* FAILURE */;
+          return "FAILURE" /* FAILURE */;
+        }
+        throw err;
+      }
+    }
+    if (this.startTime === null) {
+      this.startTime = Date.now();
+      this.log(`Starting timeout for ${this.timeoutMs}ms`);
+    }
+    const elapsed = Date.now() - this.startTime;
+    if (elapsed >= this.timeoutMs) {
+      this.log(`Timeout after ${this.timeoutMs}ms`);
+      this.startTime = null;
+      if (this.child.status() === "RUNNING" /* RUNNING */) {
+        this.child.halt();
+      }
+      this._status = "FAILURE" /* FAILURE */;
+      return "FAILURE" /* FAILURE */;
+    }
+    const childStatus = await this.child.tick(context);
+    if (childStatus !== "RUNNING" /* RUNNING */) {
+      this.startTime = null;
+    }
+    this._status = childStatus;
+    return childStatus;
+  }
+  onHalt() {
+    this.startTime = null;
+    if (this.child && this.child.status() === "RUNNING" /* RUNNING */) {
+      this.child.halt();
+    }
+  }
+  onReset() {
+    this.startTime = null;
+    this.useTemporalAPI = null;
+  }
+};
+
+// src/schemas/base.schema.ts
+import { z } from "zod";
+var nodeConfigurationSchema = z.object({
+  id: z.string().min(1, "Node ID cannot be empty"),
+  name: z.string().optional()
+}).passthrough();
+function createNodeSchema(nodeType, fields) {
+  return nodeConfigurationSchema.extend(fields).describe(`${nodeType} configuration`);
+}
+var validations = {
+  /**
+   * Positive number validator (> 0)
+   */
+  positiveNumber: (fieldName) => z.number().positive(`${fieldName} must be positive`),
+  /**
+   * Non-negative number validator (>= 0)
+   */
+  nonNegativeNumber: (fieldName) => z.number().nonnegative(`${fieldName} must be non-negative`),
+  /**
+   * Positive integer validator (> 0, whole number)
+   */
+  positiveInteger: (fieldName) => z.number().int().positive(`${fieldName} must be a positive integer`),
+  /**
+   * Non-negative integer validator (>= 0, whole number)
+   */
+  nonNegativeInteger: (fieldName) => z.number().int().nonnegative(`${fieldName} must be a non-negative integer`),
+  /**
+   * Blackboard key validator (non-empty string)
+   */
+  blackboardKey: z.string().min(1, "Blackboard key cannot be empty"),
+  /**
+   * Tree ID validator (non-empty string for SubTree references)
+   */
+  treeId: z.string().min(1, "Tree ID cannot be empty"),
+  /**
+   * Duration in milliseconds validator (non-negative)
+   */
+  durationMs: (fieldName = "duration") => z.number().nonnegative(`${fieldName} must be non-negative milliseconds`)
+};
+
+// src/decorators/timeout.schema.ts
+var timeoutConfigurationSchema = createNodeSchema("Timeout", {
+  timeoutMs: validations.positiveNumber("timeoutMs")
+});
+
+// src/decorators/delay.schema.ts
+var delayConfigurationSchema = createNodeSchema("Delay", {
+  delayMs: validations.nonNegativeNumber("delayMs")
+});
+
+// src/decorators/repeat.schema.ts
+var repeatConfigurationSchema = createNodeSchema("Repeat", {
+  numCycles: validations.positiveInteger("numCycles")
+});
+
+// src/decorators/invert.schema.ts
+var invertConfigurationSchema = nodeConfigurationSchema;
+
+// src/decorators/force-result.schema.ts
+var forceSuccessConfigurationSchema = nodeConfigurationSchema;
+var forceFailureConfigurationSchema = nodeConfigurationSchema;
+
+// src/decorators/precondition.schema.ts
+var preconditionConfigurationSchema = nodeConfigurationSchema;
+
+// src/decorators/run-once.schema.ts
+var runOnceConfigurationSchema = nodeConfigurationSchema;
+
+// src/decorators/keep-running.schema.ts
+var keepRunningUntilFailureConfigurationSchema = nodeConfigurationSchema;
+
+// src/decorators/soft-assert.schema.ts
+var softAssertConfigurationSchema = nodeConfigurationSchema;
+
+// src/composites/parallel.schema.ts
+import { z as z2 } from "zod";
+var parallelStrategySchema = z2.enum(["strict", "any"]);
+var parallelConfigurationSchema = createNodeSchema("Parallel", {
+  strategy: parallelStrategySchema.optional().default("strict"),
+  successThreshold: validations.positiveInteger("successThreshold").optional(),
+  failureThreshold: validations.positiveInteger("failureThreshold").optional()
+});
+
+// src/composites/for-each.schema.ts
+var forEachConfigurationSchema = createNodeSchema("ForEach", {
+  collectionKey: validations.blackboardKey,
+  itemKey: validations.blackboardKey,
+  indexKey: validations.blackboardKey.optional()
+});
+
+// src/composites/while.schema.ts
+var whileConfigurationSchema = createNodeSchema("While", {
+  maxIterations: validations.positiveInteger("maxIterations").optional().default(1e3)
+});
+
+// src/composites/sub-tree.schema.ts
+var subTreeConfigurationSchema = createNodeSchema("SubTree", {
+  treeId: validations.treeId
+});
+
+// src/composites/sequence.schema.ts
+var sequenceConfigurationSchema = nodeConfigurationSchema;
+
+// src/composites/selector.schema.ts
+var selectorConfigurationSchema = nodeConfigurationSchema;
+
+// src/composites/conditional.schema.ts
+var conditionalConfigurationSchema = nodeConfigurationSchema;
+
+// src/composites/reactive-sequence.schema.ts
+var reactiveSequenceConfigurationSchema = nodeConfigurationSchema;
+
+// src/composites/memory-sequence.schema.ts
+var memorySequenceConfigurationSchema = nodeConfigurationSchema;
+
+// src/composites/recovery.schema.ts
+var recoveryConfigurationSchema = nodeConfigurationSchema;
+
+// src/schemas/validation.ts
+import { z as z3 } from "zod";
+function zodErrorToConfigurationError(error, nodeType, nodeId) {
+  const nodeIdentifier = nodeId ? `${nodeType}:${nodeId}` : nodeType;
+  const issues = error.issues.map((issue) => {
+    const path2 = issue.path.join(".");
+    return `  - ${path2 ? path2 + ": " : ""}${issue.message}`;
+  }).join("\n");
+  const message = `Invalid configuration for ${nodeIdentifier}:
+${issues}`;
+  const hint = "Check the node configuration and ensure all required fields are provided with valid values.";
+  return new ConfigurationError(message, hint);
+}
+function validateConfiguration(schema, config, nodeType, nodeId) {
+  try {
+    return schema.parse(config);
+  } catch (error) {
+    if (error instanceof z3.ZodError) {
+      throw zodErrorToConfigurationError(error, nodeType, nodeId);
+    }
+    throw error;
+  }
+}
+function safeValidateConfiguration(schema, config, nodeType, nodeId) {
+  const result = schema.safeParse(config);
+  if (result.success) {
+    return { success: true, data: result.data };
+  } else {
+    return {
+      success: false,
+      error: zodErrorToConfigurationError(result.error, nodeType, nodeId)
+    };
+  }
+}
+
+// src/schemas/tree-definition.schema.ts
+import { z as z4 } from "zod";
+var treeDefSchemaObject = z4.object({
+  type: z4.string().min(1, "Node type is required"),
+  id: z4.string().optional(),
+  name: z4.string().optional(),
+  props: z4.record(z4.string(), z4.unknown()).optional(),
+  children: z4.array(
+    z4.lazy(() => treeDefinitionSchema)
+  ).optional()
+});
+var treeDefinitionSchema = treeDefSchemaObject;
+function validateTreeDefinition(definition) {
+  return treeDefinitionSchema.parse(definition);
+}
+function validateDecoratorChildren(nodeType, children) {
+  const childCount = children?.length || 0;
+  if (childCount !== 1) {
+    throw new Error(
+      `Decorator ${nodeType} must have exactly one child (got ${childCount})`
+    );
+  }
+}
+function validateCompositeChildren(nodeType, children, minChildren = 0) {
+  const count = children?.length || 0;
+  if (count < minChildren) {
+    throw new Error(
+      `Composite ${nodeType} requires at least ${minChildren} children (got ${count})`
+    );
+  }
+}
+function validateChildCount(nodeType, children, expectedCount = 0) {
+  const count = children?.length || 0;
+  if (count !== expectedCount) {
+    throw new Error(
+      `${nodeType} requires exactly ${expectedCount} children (got ${count})`
+    );
+  }
+}
+function validateChildCountRange(nodeType, children, minChildren = 0, maxChildren) {
+  const count = children?.length || 0;
+  if (count < minChildren) {
+    throw new Error(
+      `${nodeType} requires at least ${minChildren} children (got ${count})`
+    );
+  }
+  if (maxChildren !== void 0 && count > maxChildren) {
+    throw new Error(
+      `${nodeType} allows at most ${maxChildren} children (got ${count})`
+    );
+  }
+}
+
+// src/schemas/index.ts
+var SchemaRegistry = class {
+  schemas = /* @__PURE__ */ new Map();
+  constructor() {
+    this.registerAllSchemas();
+  }
+  /**
+   * Register all node schemas
+   * Called automatically on construction
+   */
+  registerAllSchemas() {
+    this.register("Timeout", timeoutConfigurationSchema);
+    this.register("Delay", delayConfigurationSchema);
+    this.register("Repeat", repeatConfigurationSchema);
+    this.register("Invert", invertConfigurationSchema);
+    this.register("ForceSuccess", forceSuccessConfigurationSchema);
+    this.register("ForceFailure", forceFailureConfigurationSchema);
+    this.register("Precondition", preconditionConfigurationSchema);
+    this.register("RunOnce", runOnceConfigurationSchema);
+    this.register(
+      "KeepRunningUntilFailure",
+      keepRunningUntilFailureConfigurationSchema
+    );
+    this.register("SoftAssert", softAssertConfigurationSchema);
+    this.register("Parallel", parallelConfigurationSchema);
+    this.register("ForEach", forEachConfigurationSchema);
+    this.register("While", whileConfigurationSchema);
+    this.register("SubTree", subTreeConfigurationSchema);
+    this.register("Sequence", sequenceConfigurationSchema);
+    this.register("Selector", selectorConfigurationSchema);
+    this.register("Conditional", conditionalConfigurationSchema);
+    this.register("ReactiveSequence", reactiveSequenceConfigurationSchema);
+    this.register("MemorySequence", memorySequenceConfigurationSchema);
+    this.register("Recovery", recoveryConfigurationSchema);
+  }
+  /**
+   * Register a validation schema for a node type
+   *
+   * @param nodeType - Name of the node type (e.g., 'Timeout', 'Sequence')
+   * @param schema - Zod schema for validating this node type's configuration
+   * @throws Error if node type is already registered
+   *
+   * @example
+   * ```typescript
+   * schemaRegistry.register('Timeout', timeoutConfigurationSchema);
+   * ```
+   */
+  register(nodeType, schema) {
+    if (this.schemas.has(nodeType)) {
+      throw new Error(`Schema for node type '${nodeType}' already registered`);
+    }
+    this.schemas.set(nodeType, schema);
+  }
+  /**
+   * Get schema for a node type
+   * Returns base schema if no specific schema registered
+   *
+   * @param nodeType - Name of the node type
+   * @returns Zod schema for the node type (or base schema if not found)
+   *
+   * @example
+   * ```typescript
+   * const schema = schemaRegistry.getSchema('Timeout');
+   * const validated = schema.parse({ id: 'test', timeoutMs: 1000 });
+   * ```
+   */
+  getSchema(nodeType) {
+    return this.schemas.get(nodeType) || nodeConfigurationSchema;
+  }
+  /**
+   * Check if a schema is registered for a node type
+   *
+   * @param nodeType - Name of the node type
+   * @returns True if schema is registered, false otherwise
+   */
+  hasSchema(nodeType) {
+    return this.schemas.has(nodeType);
+  }
+  /**
+   * Get all registered node types
+   *
+   * @returns Array of registered node type names
+   */
+  getRegisteredTypes() {
+    return Array.from(this.schemas.keys());
+  }
+  /**
+   * Validate configuration for a specific node type
+   * Throws ZodError if validation fails
+   *
+   * @param nodeType - Name of the node type
+   * @param config - Configuration object to validate
+   * @returns Validated and parsed configuration
+   * @throws ZodError if validation fails
+   *
+   * @example
+   * ```typescript
+   * const config = schemaRegistry.validate('Timeout', {
+   *   id: 'test',
+   *   timeoutMs: 1000
+   * });
+   * ```
+   */
+  validate(nodeType, config) {
+    const schema = this.getSchema(nodeType);
+    return schema.parse(config);
+  }
+  /**
+   * Safe validation that returns success/error result
+   * Does not throw errors
+   *
+   * @param nodeType - Name of the node type
+   * @param config - Configuration object to validate
+   * @returns Result with success/error
+   *
+   * @example
+   * ```typescript
+   * const result = schemaRegistry.safeParse('Timeout', { id: 'test', timeoutMs: -100 });
+   * if (result.success) {
+   *   console.log(result.data);
+   * } else {
+   *   console.error(result.error);
+   * }
+   * ```
+   */
+  safeParse(nodeType, config) {
+    const schema = this.getSchema(nodeType);
+    return schema.safeParse(config);
+  }
+  /**
+   * Clear all registered schemas
+   * Useful for testing
+   */
+  clear() {
+    this.schemas.clear();
+  }
+};
+var schemaRegistry = new SchemaRegistry();
+
+// src/registry.ts
+var Registry = class {
+  nodeTypes = /* @__PURE__ */ new Map();
+  nodeMetadata = /* @__PURE__ */ new Map();
+  behaviorTrees = /* @__PURE__ */ new Map();
+  constructor() {
+    this.log("Registry created");
+  }
+  /**
+   * Register a node type with the registry
+   */
+  register(type, ctor, metadata) {
+    if (this.nodeTypes.has(type)) {
+      throw new Error(`Node type '${type}' is already registered`);
+    }
+    this.nodeTypes.set(type, ctor);
+    const fullMetadata = {
+      type,
+      category: metadata?.category || "action",
+      description: metadata?.description,
+      ports: metadata?.ports || []
+    };
+    this.nodeMetadata.set(type, fullMetadata);
+    this.log(`Registered node type: ${type} (${fullMetadata.category})`);
+  }
+  /**
+   * Create a node instance by type
+   * Validates configuration against schema before creating node
+   */
+  create(type, config) {
+    const Constructor = this.nodeTypes.get(type);
+    if (!Constructor) {
+      throw new Error(
+        `Unknown node type: '${type}'. Available types: ${this.getRegisteredTypes().join(", ")}`
+      );
+    }
+    const validatedConfig = validateConfiguration(
+      schemaRegistry.getSchema(type),
+      config,
+      type,
+      config.id
+    );
+    this.log(`Creating node of type: ${type} with id: ${validatedConfig.id}`);
+    return new Constructor(validatedConfig);
+  }
+  /**
+   * Check if a node type is registered
+   */
+  has(type) {
+    return this.nodeTypes.has(type);
+  }
+  /**
+   * Get metadata for a node type
+   */
+  getMetadata(type) {
+    return this.nodeMetadata.get(type);
+  }
+  /**
+   * Get all registered node types
+   */
+  getRegisteredTypes() {
+    return Array.from(this.nodeTypes.keys());
+  }
+  /**
+   * Get registered types by category
+   */
+  getTypesByCategory(category) {
+    const types = [];
+    for (const [type, metadata] of this.nodeMetadata) {
+      if (metadata.category === category) {
+        types.push(type);
+      }
+    }
+    return types;
+  }
+  /**
+   * Clear all registrations (node types, metadata, and behavior trees)
+   */
+  clear() {
+    this.nodeTypes.clear();
+    this.nodeMetadata.clear();
+    this.behaviorTrees.clear();
+    this.log("Registry cleared (nodes and trees)");
+  }
+  /**
+   * Register a behavior tree instance with source file metadata.
+   * Used for reusable trees like elements, step groups, and test cases.
+   *
+   * @param id Unique identifier for the tree
+   * @param tree BehaviorTree instance to register
+   * @param sourceFile Path to the source .sigma file
+   * @throws Error if a tree with the same ID is already registered
+   */
+  registerTree(id, tree, sourceFile) {
+    if (this.behaviorTrees.has(id)) {
+      throw new Error(`Behavior tree '${id}' is already registered`);
+    }
+    this.behaviorTrees.set(id, { tree, sourceFile });
+    this.log(`Registered behavior tree: ${id}`);
+  }
+  /**
+   * Unregister a behavior tree by ID.
+   * Useful for cleanup in long-running processes or tests.
+   *
+   * @param id Tree ID to unregister
+   * @returns true if tree was found and removed, false otherwise
+   */
+  unregisterTree(id) {
+    const deleted = this.behaviorTrees.delete(id);
+    if (deleted) {
+      this.log(`Unregistered behavior tree: ${id}`);
+    }
+    return deleted;
+  }
+  /**
+   * Replace an existing behavior tree registration.
+   * If the tree doesn't exist, it will be registered as new.
+   *
+   * @param id Tree ID to replace
+   * @param tree New BehaviorTree instance
+   * @param sourceFile Path to the source .sigma file
+   */
+  replaceTree(id, tree, sourceFile) {
+    const existed = this.behaviorTrees.has(id);
+    this.behaviorTrees.set(id, { tree, sourceFile });
+    this.log(`${existed ? "Replaced" : "Registered"} behavior tree: ${id}`);
+  }
+  /**
+   * Get a behavior tree instance by ID
+   */
+  getTree(id) {
+    return this.behaviorTrees.get(id)?.tree;
+  }
+  /**
+   * Get the source file path for a behavior tree
+   */
+  getTreeSourceFile(id) {
+    return this.behaviorTrees.get(id)?.sourceFile;
+  }
+  /**
+   * Get all trees that belong to a specific source file
+   */
+  getTreesForFile(filePath) {
+    const result = /* @__PURE__ */ new Map();
+    for (const [id, entry] of this.behaviorTrees) {
+      if (entry.sourceFile === filePath) {
+        result.set(id, entry.tree);
+      }
+    }
+    return result;
+  }
+  /**
+   * Check if a behavior tree is registered
+   */
+  hasTree(id) {
+    return this.behaviorTrees.has(id);
+  }
+  /**
+   * Clone a registered behavior tree for instantiation
+   * Returns the cloned BehaviorTree (caller should use getRoot() for TreeNode)
+   */
+  cloneTree(id) {
+    const entry = this.behaviorTrees.get(id);
+    if (!entry) {
+      throw new Error(
+        `Behavior tree '${id}' not found. Available trees: ${this.getAllTreeIds().join(", ") || "none"}`
+      );
+    }
+    this.log(`Cloning behavior tree: ${id}`);
+    return entry.tree.clone();
+  }
+  /**
+   * Get all registered behavior tree IDs
+   */
+  getAllTreeIds() {
+    return Array.from(this.behaviorTrees.keys());
+  }
+  /**
+   * Clear all registered behavior trees
+   */
+  clearTrees() {
+    this.behaviorTrees.clear();
+    this.log("Cleared all behavior trees");
+  }
+  /**
+   * Create a tree from a JSON definition
+   * Validates tree structure before creating nodes
+   */
+  createTree(definition) {
+    const validatedDef = treeDefinitionSchema.parse(definition);
+    if (!validatedDef.type) {
+      throw new Error("Node definition must have a type");
+    }
+    const config = {
+      id: validatedDef.id || `${validatedDef.type}_${Date.now()}`,
+      name: validatedDef.name || validatedDef.id,
+      ...validatedDef.props
+    };
+    const node = this.create(validatedDef.type, config);
+    if (validatedDef.children && Array.isArray(validatedDef.children)) {
+      if ("setChild" in node && typeof node.setChild === "function") {
+        if (validatedDef.children.length !== 1) {
+          throw new Error(
+            `Decorator ${validatedDef.type} must have exactly one child`
+          );
+        }
+        const child = this.createTree(validatedDef.children[0]);
+        node.setChild(child);
+      } else if ("addChildren" in node && typeof node.addChildren === "function") {
+        const children = validatedDef.children.map(
+          (childDef) => this.createTree(childDef)
+        );
+        node.addChildren(
+          children
+        );
+      }
+    }
+    return node;
+  }
+  /**
+   * Safe tree creation that returns success/error result
+   * Useful for user-facing tools that need graceful error handling
+   *
+   * @param definition - Tree definition to create
+   * @returns Success result with tree or failure result with error
+   *
+   * @example
+   * ```typescript
+   * const result = registry.safeCreateTree({
+   *   type: 'Sequence',
+   *   id: 'root',
+   *   children: [...]
+   * });
+   *
+   * if (result.success) {
+   *   console.log('Tree created:', result.tree);
+   * } else {
+   *   console.error('Failed:', result.error.message);
+   * }
+   * ```
+   */
+  safeCreateTree(definition) {
+    try {
+      const tree = this.createTree(definition);
+      return { success: true, tree };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error))
+      };
+    }
+  }
+  log(message) {
+    console.log(`[Registry] ${message}`);
+  }
+};
+
+// src/test-nodes.ts
+var PrintAction = class extends ActionNode {
+  message;
+  constructor(config) {
+    super(config);
+    this.message = config.message || "Hello from PrintAction!";
+  }
+  async executeTick(context) {
+    this.log(`Executing: "${this.message}"`);
+    if (this.config.outputKey && typeof this.config.outputKey === "string") {
+      context.blackboard.set(this.config.outputKey, this.message);
+    }
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+};
+var WaitAction = class extends ActionNode {
+  waitMs;
+  startTime = null;
+  constructor(config) {
+    super(config);
+    this.waitMs = config.waitMs || 1e3;
+  }
+  async executeTick(_context) {
+    if (this.startTime === null) {
+      this.startTime = Date.now();
+      this.log(`Starting wait for ${this.waitMs}ms`);
+      this._status = "RUNNING" /* RUNNING */;
+      return "RUNNING" /* RUNNING */;
+    }
+    const elapsed = Date.now() - this.startTime;
+    if (elapsed < this.waitMs) {
+      this.log(`Waiting... ${this.waitMs - elapsed}ms remaining`);
+      this._status = "RUNNING" /* RUNNING */;
+      return "RUNNING" /* RUNNING */;
+    }
+    this.log(`Wait completed after ${elapsed}ms`);
+    this.startTime = null;
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+  onReset() {
+    this.startTime = null;
+  }
+  onHalt() {
+    this.startTime = null;
+  }
+};
+var CounterAction = class extends ActionNode {
+  counterKey;
+  increment;
+  constructor(config) {
+    super(config);
+    this.counterKey = config.counterKey || "counter";
+    this.increment = config.increment || 1;
+  }
+  async executeTick(context) {
+    const currentValue = context.blackboard.get(this.counterKey) || 0;
+    const newValue = currentValue + this.increment;
+    context.blackboard.set(this.counterKey, newValue);
+    this.log(
+      `Counter '${this.counterKey}' incremented from ${currentValue} to ${newValue}`
+    );
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+};
+var MockAction = class extends ActionNode {
+  returnStatus;
+  ticksBeforeComplete;
+  currentTicks = 0;
+  constructor(config) {
+    super(config);
+    this.returnStatus = config.returnStatus || "SUCCESS" /* SUCCESS */;
+    this.ticksBeforeComplete = config.ticksBeforeComplete || 1;
+  }
+  async executeTick(_context) {
+    this.currentTicks++;
+    if (this.currentTicks < this.ticksBeforeComplete) {
+      this.log(
+        `Running... (tick ${this.currentTicks}/${this.ticksBeforeComplete})`
+      );
+      this._status = "RUNNING" /* RUNNING */;
+      return "RUNNING" /* RUNNING */;
+    }
+    this.log(`Completing with status: ${this.returnStatus}`);
+    this.currentTicks = 0;
+    this._status = this.returnStatus;
+    return this.returnStatus;
+  }
+  onReset() {
+    this.currentTicks = 0;
+  }
+  onHalt() {
+    this.currentTicks = 0;
+  }
+};
+var CheckCondition = class extends ConditionNode {
+  key;
+  operator;
+  value;
+  constructor(config) {
+    super(config);
+    this.key = config.key;
+    this.operator = config.operator || "==";
+    this.value = config.value;
+  }
+  async executeTick(context) {
+    const actualValue = context.blackboard.get(this.key);
+    let result = false;
+    switch (this.operator) {
+      case "==":
+        result = actualValue === this.value;
+        break;
+      case "!=":
+        result = actualValue !== this.value;
+        break;
+      case ">":
+        result = actualValue > this.value;
+        break;
+      case "<":
+        result = actualValue < this.value;
+        break;
+      case ">=":
+        result = actualValue >= this.value;
+        break;
+      case "<=":
+        result = actualValue <= this.value;
+        break;
+    }
+    this.log(
+      `Checking: ${this.key} ${this.operator} ${this.value} => ${actualValue} ${this.operator} ${this.value} = ${result}`
+    );
+    this._status = result ? "SUCCESS" /* SUCCESS */ : "FAILURE" /* FAILURE */;
+    return this._status;
+  }
+};
+var AlwaysCondition = class extends ConditionNode {
+  returnStatus;
+  constructor(config) {
+    super(config);
+    this.returnStatus = config.returnStatus || "SUCCESS" /* SUCCESS */;
+  }
+  async executeTick(_context) {
+    this.log(`Returning ${this.returnStatus}`);
+    this._status = this.returnStatus;
+    return this.returnStatus;
+  }
+};
+var SuccessNode = class extends ActionNode {
+  async executeTick(_context) {
+    this.log("Executing (SUCCESS)");
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+};
+var FailureNode = class extends ActionNode {
+  async executeTick(_context) {
+    this.log("Executing (FAILURE)");
+    this._status = "FAILURE" /* FAILURE */;
+    return "FAILURE" /* FAILURE */;
+  }
+};
+var RunningNode = class extends ActionNode {
+  async executeTick(_context) {
+    this.log("Executing (RUNNING)");
+    this._status = "RUNNING" /* RUNNING */;
+    return "RUNNING" /* RUNNING */;
+  }
+};
+
+// src/utilities/log-message.ts
+var LogMessage = class extends ActionNode {
+  message;
+  level;
+  constructor(config) {
+    super(config);
+    this.message = config.message;
+    this.level = config.level || "info";
+  }
+  async executeTick(context) {
+    try {
+      const resolvedMessage = this.resolveMessage(this.message, context);
+      switch (this.level) {
+        case "warn":
+          console.warn(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+        case "error":
+          console.error(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+        case "debug":
+          console.debug(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+        default:
+          console.log(`[LogMessage:${this.name}] ${resolvedMessage}`);
+          break;
+      }
+      context.eventEmitter?.emit({
+        type: "log" /* LOG */,
+        nodeId: this.id,
+        nodeName: this.name,
+        nodeType: this.type,
+        timestamp: Date.now(),
+        data: { level: this.level, message: resolvedMessage }
+      });
+      this._status = "SUCCESS" /* SUCCESS */;
+      return "SUCCESS" /* SUCCESS */;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(
+        `[LogMessage:${this.name}] Failed to log message: ${errorMessage}`
+      );
+      this._status = "FAILURE" /* FAILURE */;
+      return "FAILURE" /* FAILURE */;
+    }
+  }
+  /**
+   * Resolve variable references in message string
+   * Supports ${key}, ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+   */
+  resolveMessage(message, context) {
+    const varCtx = {
+      blackboard: context.blackboard,
+      input: context.input,
+      testData: context.testData
+    };
+    const resolved = resolveString(message, varCtx);
+    if (typeof resolved === "string") {
+      return resolved;
+    }
+    if (resolved === null) {
+      return "null";
+    }
+    if (typeof resolved === "object") {
+      try {
+        return JSON.stringify(resolved);
+      } catch {
+        return String(resolved);
+      }
+    }
+    return String(resolved);
+  }
+};
+
+// src/utilities/regex-extract.ts
+var RegexExtract = class extends ActionNode {
+  input;
+  pattern;
+  outputKey;
+  flags;
+  matchIndex;
+  constructor(config) {
+    super(config);
+    this.input = config.input;
+    this.pattern = config.pattern;
+    this.outputKey = config.outputKey;
+    this.flags = config.flags || "g";
+    this.matchIndex = config.matchIndex;
+  }
+  async executeTick(context) {
+    try {
+      const text = context.blackboard.get(this.input);
+      if (text === void 0 || text === null) {
+        throw new ConfigurationError(
+          `Input '${this.input}' not found in blackboard`
+        );
+      }
+      if (typeof text !== "string") {
+        throw new ConfigurationError(
+          `Input '${this.input}' must be a string, got ${typeof text}`
+        );
+      }
+      let regex;
+      try {
+        regex = new RegExp(this.pattern, this.flags);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid regex pattern: ${errorMessage}`);
+      }
+      const matches = text.match(regex) || [];
+      let result;
+      if (this.matchIndex !== void 0 && this.matchIndex >= 0) {
+        result = matches[this.matchIndex] || null;
+        this.log(`Extracted match at index ${this.matchIndex}: ${result}`);
+      } else {
+        result = matches;
+        this.log(`Extracted ${matches.length} match(es) from input`);
+      }
+      this.setOutput(context, this.outputKey, result);
+      this._status = "SUCCESS" /* SUCCESS */;
+      return "SUCCESS" /* SUCCESS */;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.log(`RegexExtract failed: ${errorMessage}`);
+      this._status = "FAILURE" /* FAILURE */;
+      return "FAILURE" /* FAILURE */;
+    }
+  }
+};
+
+// src/integrations/piece-executor.ts
+var PROVIDER_TO_PIECE = {
+  // Google services
+  "google": "google-sheets",
+  "google-sheets": "google-sheets",
+  "google-drive": "google-drive",
+  "google-calendar": "google-calendar",
+  "gmail": "gmail",
+  // Communication
+  "slack": "slack",
+  "discord": "discord",
+  "telegram": "telegram-bot",
+  "twilio": "twilio",
+  // AI/ML
+  "openai": "openai",
+  "anthropic": "anthropic",
+  // CRM & Sales
+  "hubspot": "hubspot",
+  "salesforce": "salesforce",
+  // Productivity
+  "notion": "notion",
+  "airtable": "airtable",
+  "asana": "asana",
+  "trello": "trello",
+  // Development
+  "github": "github",
+  "gitlab": "gitlab",
+  // E-commerce
+  "shopify": "shopify",
+  "stripe": "stripe",
+  // Other
+  "http": "http",
+  "webhook": "http"
+};
+var pieceCache = /* @__PURE__ */ new Map();
+function getPiecePackageName(provider) {
+  const pieceName = PROVIDER_TO_PIECE[provider.toLowerCase()];
+  if (pieceName) {
+    return `@activepieces/piece-${pieceName}`;
+  }
+  return `@activepieces/piece-${provider.toLowerCase()}`;
+}
+var PIECE_EXPORT_NAMES = {
+  "@activepieces/piece-google-sheets": "googleSheets",
+  "@activepieces/piece-slack": "slack",
+  "@activepieces/piece-openai": "openai",
+  "@activepieces/piece-discord": "discord",
+  "@activepieces/piece-notion": "notion",
+  "@activepieces/piece-github": "github",
+  "@activepieces/piece-http": "http"
+};
+async function loadPiece(packageName) {
+  if (pieceCache.has(packageName)) {
+    return pieceCache.get(packageName);
+  }
+  try {
+    const pieceModule = await import(packageName);
+    let piece = pieceModule;
+    const exportName = PIECE_EXPORT_NAMES[packageName];
+    if (exportName && pieceModule[exportName]) {
+      piece = pieceModule[exportName];
+    } else {
+      for (const key of Object.keys(pieceModule)) {
+        const exported = pieceModule[key];
+        if (exported && typeof exported === "object" && "_actions" in exported) {
+          piece = exported;
+          break;
+        }
+      }
+    }
+    pieceCache.set(packageName, piece);
+    return piece;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("Cannot find module")) {
+      throw new Error(
+        `Active Pieces package '${packageName}' is not installed. Run: npm install ${packageName}`
+      );
+    }
+    throw new Error(`Failed to load piece package '${packageName}': ${message}`);
+  }
+}
+async function executePieceAction(request) {
+  const { provider, action, inputs, auth } = request;
+  const packageName = getPiecePackageName(provider);
+  const piece = await loadPiece(packageName);
+  let actions;
+  if (piece._actions && typeof piece._actions === "object") {
+    actions = piece._actions;
+  } else if (piece.actions && typeof piece.actions === "object") {
+    actions = piece.actions;
+  } else if (piece.default && typeof piece.default === "object") {
+    const defaultExport = piece.default;
+    actions = defaultExport._actions || defaultExport.actions;
+  }
+  if (!actions) {
+    throw new Error(
+      `Piece '${packageName}' does not export actions. This may not be a valid Active Pieces package.`
+    );
+  }
+  const actionDef = actions[action];
+  if (!actionDef) {
+    const availableActions = Object.keys(actions).join(", ");
+    throw new Error(
+      `Action '${action}' not found in piece '${packageName}'. Available actions: ${availableActions}`
+    );
+  }
+  if (typeof actionDef.run !== "function") {
+    throw new Error(
+      `Action '${action}' in piece '${packageName}' does not have a run method`
+    );
+  }
+  const runFn = actionDef.run;
+  const result = await runFn({
+    auth,
+    propsValue: inputs,
+    // Additional context that some pieces might need
+    store: createMockStore(),
+    files: createMockFiles()
+  });
+  return result;
+}
+function createMockStore() {
+  const storage = {};
+  return {
+    async get(key) {
+      return storage[key];
+    },
+    async put(key, value) {
+      storage[key] = value;
+    },
+    async delete(key) {
+      delete storage[key];
+    }
+  };
+}
+function createMockFiles() {
+  return {
+    async write(params) {
+      console.log(`[PieceExecutor] Mock file write: ${params.fileName}`);
+      return `mock://files/${params.fileName}`;
+    }
+  };
+}
+async function listPieceActions(provider) {
+  const packageName = getPiecePackageName(provider);
+  const piece = await loadPiece(packageName);
+  let actions;
+  if (piece._actions && typeof piece._actions === "object") {
+    actions = piece._actions;
+  } else if (piece.actions && typeof piece.actions === "object") {
+    actions = piece.actions;
+  } else if (piece.default && typeof piece.default === "object") {
+    const defaultExport = piece.default;
+    actions = defaultExport._actions || defaultExport.actions;
+  }
+  if (!actions) {
+    return [];
+  }
+  return Object.entries(actions).map(([name, def]) => {
+    const actionDef = def;
+    return {
+      name,
+      displayName: actionDef.displayName,
+      description: actionDef.description
+    };
+  });
+}
+async function isPieceInstalled(provider) {
+  const packageName = getPiecePackageName(provider);
+  try {
+    await loadPiece(packageName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function clearPieceCache() {
+  pieceCache.clear();
+}
+
+// src/integrations/integration-action.ts
+var IntegrationAction = class extends ActionNode {
+  provider;
+  action;
+  inputs;
+  connectionId;
+  storeResult;
+  resultKey;
+  constructor(config) {
+    super(config);
+    if (!config.provider) {
+      throw new ConfigurationError("IntegrationAction requires provider");
+    }
+    if (!config.action) {
+      throw new ConfigurationError("IntegrationAction requires action");
+    }
+    this.provider = config.provider;
+    this.action = config.action;
+    this.inputs = config.inputs || {};
+    this.connectionId = config.connectionId;
+    this.storeResult = config.storeResult !== false;
+    this.resultKey = config.resultKey || `${this.id}.result`;
+  }
+  async executeTick(context) {
+    const integrationContext = context;
+    if (!integrationContext.tokenProvider) {
+      this._lastError = "No token provider configured in context. Set context.tokenProvider to fetch OAuth tokens.";
+      this.log(`Error: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+    try {
+      const resolvedInputs = this.resolveInputs(context);
+      this.log(`Resolved inputs: ${JSON.stringify(resolvedInputs)}`);
+      const auth = await integrationContext.tokenProvider(
+        context,
+        this.provider,
+        this.connectionId
+      );
+      this.log(`Got authentication for provider: ${this.provider}`);
+      const result = await this.executeAction(context, resolvedInputs, auth);
+      if (this.storeResult) {
+        context.blackboard.set(this.resultKey, result);
+        this.log(`Stored result in blackboard: ${this.resultKey}`);
+      }
+      this.log(
+        `Integration action completed: ${this.provider}/${this.action}`
+      );
+      return "SUCCESS" /* SUCCESS */;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`Integration action failed: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+  }
+  /**
+   * Dual-mode execution:
+   * - Activity mode: Use context.activities (deterministic for Temporal)
+   * - Standalone mode: Inline executePieceAction (for testing)
+   */
+  async executeAction(context, inputs, auth) {
+    const request = {
+      provider: this.provider,
+      action: this.action,
+      inputs,
+      auth
+    };
+    if (context.activities?.executePieceAction) {
+      this.log(`Executing via activity: ${this.provider}/${this.action}`);
+      return context.activities.executePieceAction(request);
+    }
+    this.log(`Executing inline (standalone): ${this.provider}/${this.action}`);
+    return executePieceAction(request);
+  }
+  /**
+   * Resolve variable references in inputs
+   * Supports ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+   */
+  resolveInputs(context) {
+    const varCtx = {
+      blackboard: context.blackboard,
+      input: context.input,
+      testData: context.testData
+    };
+    return resolveValue(this.inputs, varCtx, { preserveUndefined: false });
+  }
+};
+var envTokenProvider = async (_context, provider) => {
+  const normalizedProvider = provider.toUpperCase().replace(/-/g, "_");
+  const accessToken = process.env[`${normalizedProvider}_ACCESS_TOKEN`];
+  if (accessToken) {
+    return { access_token: accessToken };
+  }
+  const apiKey = process.env[`${normalizedProvider}_API_KEY`];
+  if (apiKey) {
+    return { api_key: apiKey };
+  }
+  throw new Error(
+    `No token found for provider ${provider}. Set ${normalizedProvider}_ACCESS_TOKEN or ${normalizedProvider}_API_KEY environment variable.`
+  );
+};
+
+// src/actions/python-script.ts
+var PythonScript = class extends ActionNode {
+  code;
+  packages;
+  timeout;
+  allowedEnvVars;
+  constructor(config) {
+    super(config);
+    if (!config.code) {
+      throw new ConfigurationError("PythonScript requires code");
+    }
+    this.code = config.code;
+    this.packages = config.packages || [];
+    this.timeout = config.timeout || 6e4;
+    this.allowedEnvVars = config.allowedEnvVars || [];
+  }
+  async executeTick(context) {
+    if (!context.activities?.executePythonScript) {
+      this._lastError = "PythonScript requires activities.executePythonScript to be configured. This activity executes Python code in a separate worker process.";
+      this.log(`Error: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+    try {
+      const request = {
+        code: this.resolveCode(context),
+        blackboard: context.blackboard.toJSON(),
+        input: context.input ? { ...context.input } : void 0,
+        env: this.getAllowedEnv(),
+        timeout: this.timeout
+      };
+      this.log(`Executing Python script (${this.code.length} chars, timeout: ${this.timeout}ms)`);
+      const result = await context.activities.executePythonScript(request);
+      for (const [key, value] of Object.entries(result.blackboard)) {
+        context.blackboard.set(key, value);
+      }
+      this.log(`Python script completed, ${Object.keys(result.blackboard).length} blackboard keys updated`);
+      if (result.stdout) {
+        this.log(`Python stdout: ${result.stdout}`);
+      }
+      if (result.stderr) {
+        this.log(`Python stderr: ${result.stderr}`);
+      }
+      return "SUCCESS" /* SUCCESS */;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`Python script failed: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+  }
+  /**
+   * Resolve variable references in the Python code
+   * Allows dynamic code templates like:
+   * code: "bb['output_key'] = '${input.prefix}_result'"
+   */
+  resolveCode(context) {
+    const varCtx = {
+      blackboard: context.blackboard,
+      input: context.input,
+      testData: context.testData
+    };
+    return resolveString(this.code, varCtx);
+  }
+  /**
+   * Get allowed environment variables to pass to Python
+   */
+  getAllowedEnv() {
+    const env = {};
+    for (const varName of this.allowedEnvVars) {
+      const value = process.env[varName];
+      if (value !== void 0) {
+        env[varName] = value;
+      }
+    }
+    return env;
+  }
+};
+
+// src/actions/parse-file.ts
+var ParseFile = class extends ActionNode {
+  file;
+  format;
+  sheetName;
+  columnMapping;
+  outputKey;
+  options;
+  constructor(config) {
+    super(config);
+    if (!config.file) {
+      throw new ConfigurationError("ParseFile requires file");
+    }
+    if (!config.outputKey) {
+      throw new ConfigurationError("ParseFile requires outputKey");
+    }
+    this.file = config.file;
+    this.format = config.format || "auto";
+    this.sheetName = config.sheetName;
+    this.columnMapping = config.columnMapping;
+    this.outputKey = config.outputKey;
+    this.options = config.options;
+  }
+  async executeTick(context) {
+    if (!context.activities?.parseFile) {
+      this._lastError = "ParseFile requires activities.parseFile to be configured. This activity handles file I/O outside the workflow sandbox.";
+      this.log(`Error: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+    try {
+      const varCtx = {
+        blackboard: context.blackboard,
+        input: context.input,
+        testData: context.testData
+      };
+      const resolvedFile = resolveValue(this.file, varCtx);
+      const request = {
+        file: resolvedFile,
+        format: this.format,
+        sheetName: this.sheetName,
+        columnMapping: this.columnMapping,
+        options: this.options
+      };
+      this.log(`Parsing file: ${resolvedFile} (format: ${this.format || "auto"})`);
+      const result = await context.activities.parseFile(request);
+      context.blackboard.set(this.outputKey, result.data);
+      this.log(
+        `Parsed ${result.rowCount} rows from ${resolvedFile}, columns: [${result.columns.join(", ")}]`
+      );
+      return "SUCCESS" /* SUCCESS */;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`Parse file failed: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+  }
+};
+
+// src/actions/generate-file.ts
+var GenerateFile = class extends ActionNode {
+  format;
+  dataKey;
+  columns;
+  filename;
+  storage;
+  outputKey;
+  constructor(config) {
+    super(config);
+    if (!config.format) {
+      throw new ConfigurationError("GenerateFile requires format");
+    }
+    if (!config.dataKey) {
+      throw new ConfigurationError("GenerateFile requires dataKey");
+    }
+    if (!config.filename) {
+      throw new ConfigurationError("GenerateFile requires filename");
+    }
+    if (!config.storage) {
+      throw new ConfigurationError("GenerateFile requires storage");
+    }
+    if (!config.outputKey) {
+      throw new ConfigurationError("GenerateFile requires outputKey");
+    }
+    this.format = config.format;
+    this.dataKey = config.dataKey;
+    this.columns = config.columns;
+    this.filename = config.filename;
+    this.storage = config.storage;
+    this.outputKey = config.outputKey;
+  }
+  async executeTick(context) {
+    if (!context.activities?.generateFile) {
+      this._lastError = "GenerateFile requires activities.generateFile to be configured. This activity handles file I/O outside the workflow sandbox.";
+      this.log(`Error: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+    try {
+      const varCtx = {
+        blackboard: context.blackboard,
+        input: context.input,
+        testData: context.testData
+      };
+      const data = context.blackboard.get(this.dataKey);
+      if (!Array.isArray(data)) {
+        this._lastError = `Data at '${this.dataKey}' is not an array (got ${typeof data})`;
+        this.log(`Error: ${this._lastError}`);
+        return "FAILURE" /* FAILURE */;
+      }
+      const resolvedFilename = resolveValue(this.filename, varCtx);
+      const request = {
+        format: this.format,
+        data,
+        columns: this.columns,
+        filename: resolvedFilename,
+        storage: this.storage
+      };
+      this.log(
+        `Generating ${this.format} file: ${resolvedFilename} (${data.length} rows, storage: ${this.storage})`
+      );
+      const result = await context.activities.generateFile(request);
+      context.blackboard.set(this.outputKey, result);
+      this.log(
+        `Generated file: ${result.filename} (${result.size} bytes, path: ${result.path})`
+      );
+      return "SUCCESS" /* SUCCESS */;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`Generate file failed: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+  }
+};
+
+// src/actions/http-request.ts
+var HttpRequest = class extends ActionNode {
+  url;
+  method;
+  headers;
+  body;
+  responseType;
+  timeout;
+  retry;
+  outputKey;
+  constructor(config) {
+    super(config);
+    if (!config.url) {
+      throw new ConfigurationError("HttpRequest requires url");
+    }
+    if (!config.outputKey) {
+      throw new ConfigurationError("HttpRequest requires outputKey");
+    }
+    this.url = config.url;
+    this.method = config.method || "GET";
+    this.headers = config.headers;
+    this.body = config.body;
+    this.responseType = config.responseType || "json";
+    this.timeout = config.timeout;
+    this.retry = config.retry;
+    this.outputKey = config.outputKey;
+  }
+  async executeTick(context) {
+    if (!context.activities?.fetchUrl) {
+      this._lastError = "HttpRequest requires activities.fetchUrl to be configured. This activity handles HTTP I/O outside the workflow sandbox.";
+      this.log(`Error: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+    try {
+      const varCtx = {
+        blackboard: context.blackboard,
+        input: context.input,
+        testData: context.testData
+      };
+      const resolvedUrl = resolveValue(this.url, varCtx);
+      const resolvedHeaders = this.headers ? resolveValue(this.headers, varCtx) : void 0;
+      const resolvedBody = this.body !== void 0 ? resolveValue(this.body, varCtx) : void 0;
+      const request = {
+        url: resolvedUrl,
+        method: this.method || "GET",
+        headers: resolvedHeaders,
+        body: resolvedBody,
+        timeout: this.timeout
+      };
+      this.log(`HTTP ${request.method} ${resolvedUrl}`);
+      let response;
+      let lastError;
+      const maxAttempts = this.retry?.maxAttempts || 1;
+      const backoffMs = this.retry?.backoffMs || 1e3;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          response = await context.activities.fetchUrl(request);
+          lastError = void 0;
+          break;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          if (attempt < maxAttempts) {
+            const delay = backoffMs * Math.pow(2, attempt - 1);
+            this.log(`Request failed, retrying in ${delay}ms (attempt ${attempt}/${maxAttempts})`);
+            await this.sleep(delay);
+          }
+        }
+      }
+      if (lastError) {
+        throw lastError;
+      }
+      if (!response) {
+        throw new Error("No response received");
+      }
+      let parsedData = response.data;
+      if (this.responseType === "json" && typeof response.data === "string") {
+        try {
+          parsedData = JSON.parse(response.data);
+        } catch {
+          this.log("Response is not valid JSON, keeping as string");
+        }
+      }
+      context.blackboard.set(this.outputKey, {
+        status: response.status,
+        headers: response.headers,
+        data: parsedData
+      });
+      this.log(
+        `HTTP ${request.method} ${resolvedUrl} -> ${response.status}`
+      );
+      return response.status >= 200 && response.status < 300 ? "SUCCESS" /* SUCCESS */ : "FAILURE" /* FAILURE */;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`HTTP request failed: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+  }
+  /**
+   * Sleep for the specified duration
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/data-store/types.ts
+function isDataRef(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  return typeof obj.store === "string" && ["gcs", "s3", "redis", "memory"].includes(obj.store) && typeof obj.key === "string" && obj.key.length > 0;
+}
+
+// src/actions/code-execution.ts
+var CodeExecution = class extends ActionNode {
+  code;
+  language;
+  timeout;
+  packages;
+  constructor(config) {
+    super(config);
+    if (!config.code) {
+      throw new ConfigurationError("CodeExecution requires code");
+    }
+    if (!config.language) {
+      throw new ConfigurationError("CodeExecution requires language");
+    }
+    if (!["javascript", "python"].includes(config.language)) {
+      throw new ConfigurationError(
+        `CodeExecution language must be 'javascript' or 'python', got: ${config.language}`
+      );
+    }
+    this.code = config.code;
+    this.language = config.language;
+    this.timeout = config.timeout ?? 3e4;
+    this.packages = config.packages ?? [];
+  }
+  async executeTick(context) {
+    if (!context.activities?.executeCode) {
+      this._lastError = "CodeExecution requires activities.executeCode to be configured. This activity handles sandboxed code execution via Microsandbox.";
+      this.log(`Error: ${this._lastError}`);
+      return "FAILURE" /* FAILURE */;
+    }
+    try {
+      const dataRefs = {};
+      const inlineContext = {};
+      for (const [key, value] of Object.entries(context.blackboard.toJSON())) {
+        if (isDataRef(value)) {
+          dataRefs[key] = value;
+        } else {
+          inlineContext[key] = value;
+        }
+      }
+      const request = {
+        code: this.code,
+        language: this.language,
+        dataRefs,
+        context: inlineContext,
+        input: context.input ? { ...context.input } : void 0,
+        timeout: this.timeout,
+        packages: this.packages.length > 0 ? this.packages : void 0,
+        workflowId: context.workflowInfo?.workflowId
+      };
+      this.log(
+        `Executing ${this.language} code (timeout: ${this.timeout}ms, packages: ${this.packages.length})`
+      );
+      const result = await context.activities.executeCode(request);
+      if (result.logs.length > 0) {
+        for (const log of result.logs) {
+          this.log(`[sandbox] ${log}`);
+        }
+      }
+      for (const [key, value] of Object.entries(result.values)) {
+        context.blackboard.set(key, value);
+      }
+      for (const [key, ref] of Object.entries(result.dataRefs)) {
+        context.blackboard.set(key, ref);
+      }
+      this.log(
+        `Code execution completed in ${result.executionTimeMs}ms (${Object.keys(result.values).length} values, ${Object.keys(result.dataRefs).length} refs)`
+      );
+      return "SUCCESS" /* SUCCESS */;
+    } catch (error) {
+      let actualMessage = error instanceof Error ? error.message : String(error);
+      if (error && typeof error === "object") {
+        const err = error;
+        if (err.cause?.cause?.message) {
+          actualMessage = err.cause.cause.message;
+        } else if (err.cause?.message) {
+          actualMessage = err.cause.message;
+        }
+      }
+      this.log(`Code execution failed: ${actualMessage}`);
+      throw new Error(`Code execution failed: ${actualMessage}`);
+    }
+  }
+};
+
+// src/registry-utils.ts
+function registerStandardNodes(registry) {
+  registry.register("Sequence", Sequence, { category: "composite" });
+  registry.register("Selector", Selector, { category: "composite" });
+  registry.register("Parallel", Parallel, { category: "composite" });
+  registry.register("Conditional", Conditional, {
+    category: "composite"
+  });
+  registry.register("ForEach", ForEach, { category: "composite" });
+  registry.register("While", While, { category: "composite" });
+  registry.register("Recovery", Recovery, { category: "composite" });
+  registry.register("ReactiveSequence", ReactiveSequence, {
+    category: "composite"
+  });
+  registry.register("MemorySequence", MemorySequence, {
+    category: "composite"
+  });
+  registry.register("SubTree", SubTree, { category: "composite" });
+  registry.register("Timeout", Timeout, { category: "decorator" });
+  registry.register("Delay", Delay, { category: "decorator" });
+  registry.register("Repeat", Repeat, { category: "decorator" });
+  registry.register("Invert", Invert, { category: "decorator" });
+  registry.register("ForceSuccess", ForceSuccess, {
+    category: "decorator"
+  });
+  registry.register("ForceFailure", ForceFailure, {
+    category: "decorator"
+  });
+  registry.register("RunOnce", RunOnce, { category: "decorator" });
+  registry.register("KeepRunningUntilFailure", KeepRunningUntilFailure, {
+    category: "decorator"
+  });
+  registry.register("Precondition", Precondition, {
+    category: "decorator"
+  });
+  registry.register("SoftAssert", SoftAssert, { category: "decorator" });
+  registry.register("PrintAction", PrintAction, { category: "action" });
+  registry.register("MockAction", MockAction, { category: "action" });
+  registry.register("SuccessNode", SuccessNode, { category: "action" });
+  registry.register("FailureNode", FailureNode, { category: "action" });
+  registry.register("RunningNode", RunningNode, { category: "action" });
+  registry.register("CounterAction", CounterAction, {
+    category: "action"
+  });
+  registry.register("CheckCondition", CheckCondition, {
+    category: "condition"
+  });
+  registry.register("AlwaysCondition", AlwaysCondition, {
+    category: "condition"
+  });
+  registry.register("WaitAction", WaitAction, { category: "action" });
+  registry.register("LogMessage", LogMessage, { category: "action" });
+  registry.register("RegexExtract", RegexExtract, { category: "action" });
+  registry.register("IntegrationAction", IntegrationAction, { category: "action" });
+  registry.register("PythonScript", PythonScript, { category: "action" });
+  registry.register("ParseFile", ParseFile, { category: "action" });
+  registry.register("GenerateFile", GenerateFile, { category: "action" });
+  registry.register("HttpRequest", HttpRequest, { category: "action" });
+  registry.register("CodeExecution", CodeExecution, { category: "action" });
+}
+
+// src/data-store/memory-store.ts
+var MemoryDataStore = class {
+  storage = /* @__PURE__ */ new Map();
+  cleanupInterval = null;
+  constructor(options) {
+    const cleanupMs = options?.cleanupIntervalMs ?? 6e4;
+    if (cleanupMs > 0) {
+      this.cleanupInterval = setInterval(() => this.cleanup(), cleanupMs);
+      if (this.cleanupInterval.unref) {
+        this.cleanupInterval.unref();
+      }
+    }
+  }
+  async put(key, data, options) {
+    const serialized = JSON.stringify(data);
+    const sizeBytes = Buffer.byteLength(serialized, "utf8");
+    const entry = {
+      data,
+      sizeBytes
+    };
+    if (options?.ttlSeconds) {
+      entry.expiresAt = Date.now() + options.ttlSeconds * 1e3;
+    }
+    this.storage.set(key, entry);
+    return {
+      store: "memory",
+      key,
+      sizeBytes,
+      expiresAt: entry.expiresAt
+    };
+  }
+  async get(ref) {
+    if (ref.store !== "memory") {
+      throw new Error(`MemoryDataStore cannot retrieve from store: ${ref.store}`);
+    }
+    const entry = this.storage.get(ref.key);
+    if (!entry) {
+      throw new Error(`Data not found for key: ${ref.key}`);
+    }
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.storage.delete(ref.key);
+      throw new Error(`Data expired for key: ${ref.key}`);
+    }
+    return structuredClone(entry.data);
+  }
+  async delete(ref) {
+    if (ref.store !== "memory") {
+      throw new Error(`MemoryDataStore cannot delete from store: ${ref.store}`);
+    }
+    this.storage.delete(ref.key);
+  }
+  async exists(ref) {
+    if (ref.store !== "memory") {
+      return false;
+    }
+    const entry = this.storage.get(ref.key);
+    if (!entry) {
+      return false;
+    }
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.storage.delete(ref.key);
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Clear all stored data
+   * Useful for test cleanup
+   */
+  clear() {
+    this.storage.clear();
+  }
+  /**
+   * Get the number of stored entries
+   */
+  size() {
+    return this.storage.size;
+  }
+  /**
+   * Get total bytes stored
+   */
+  totalBytes() {
+    let total = 0;
+    for (const entry of this.storage.values()) {
+      total += entry.sizeBytes;
+    }
+    return total;
+  }
+  /**
+   * Stop the cleanup interval
+   * Call this when done with the store to prevent memory leaks in tests
+   */
+  dispose() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+  /**
+   * Remove expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.storage.entries()) {
+      if (entry.expiresAt && now > entry.expiresAt) {
+        this.storage.delete(key);
+      }
+    }
+  }
+};
+
+// src/debug/resume-point.ts
+var ResumePoint = class extends ActionNode {
+  resumePointId;
+  constructor(config) {
+    super({ id: `resume-point-${config.id}` });
+    this.resumePointId = config.id;
+  }
+  async executeTick(_context) {
+    this._status = "SUCCESS" /* SUCCESS */;
+    return "SUCCESS" /* SUCCESS */;
+  }
+};
+
+// src/yaml/parser.ts
+import * as yaml from "js-yaml";
+
+// src/yaml/errors.ts
+var ValidationError = class extends Error {
+  constructor(message, path2, suggestion) {
+    super(message);
+    this.path = path2;
+    this.suggestion = suggestion;
+    this.name = "ValidationError";
+  }
+  /**
+   * Format error message with path and suggestion
+   */
+  format() {
+    let formatted = this.message;
+    if (this.path) {
+      formatted = `${this.path}: ${formatted}`;
+    }
+    if (this.suggestion) {
+      formatted += `
+Suggestion: ${this.suggestion}`;
+    }
+    return formatted;
+  }
+};
+var YamlSyntaxError = class extends ValidationError {
+  constructor(message, line, column, suggestion) {
+    super(message, void 0, suggestion);
+    this.line = line;
+    this.column = column;
+    this.name = "YamlSyntaxError";
+  }
+  format() {
+    let formatted = this.message;
+    if (this.line !== void 0) {
+      formatted = `Line ${this.line}${this.column !== void 0 ? `, Column ${this.column}` : ""}: ${formatted}`;
+    }
+    if (this.suggestion) {
+      formatted += `
+Suggestion: ${this.suggestion}`;
+    }
+    return formatted;
+  }
+};
+var StructureValidationError = class extends ValidationError {
+  constructor(message, path2, suggestion) {
+    super(message, path2, suggestion);
+    this.name = "StructureValidationError";
+  }
+};
+var ConfigValidationError = class extends ValidationError {
+  constructor(message, nodeType, path2, suggestion) {
+    super(message, path2, suggestion);
+    this.nodeType = nodeType;
+    this.name = "ConfigValidationError";
+  }
+  format() {
+    let formatted = `Invalid configuration for node type '${this.nodeType}'`;
+    if (this.path) {
+      formatted += ` at ${this.path}`;
+    }
+    formatted += `:
+${this.message}`;
+    if (this.suggestion) {
+      formatted += `
+Suggestion: ${this.suggestion}`;
+    }
+    return formatted;
+  }
+};
+var SemanticValidationError = class extends ValidationError {
+  constructor(message, path2, suggestion) {
+    super(message, path2, suggestion);
+    this.name = "SemanticValidationError";
+  }
+};
+var ValidationErrors = class extends Error {
+  constructor(errors) {
+    super(`Validation failed with ${errors.length} error(s)`);
+    this.errors = errors;
+    this.name = "ValidationErrors";
+  }
+  /**
+   * Format all errors as a single message
+   */
+  format() {
+    const header = `YAML validation failed
+
+Issues found:`;
+    const issues = this.errors.map((error, index) => {
+      const formatted = error.format();
+      return `  ${index + 1}. ${formatted.split("\n").join("\n     ")}`;
+    }).join("\n\n");
+    return `${header}
+${issues}`;
+  }
+};
+
+// src/yaml/validation/semantic-validator.ts
+var SemanticValidator = class {
+  /**
+   * Validate semantic rules for a tree definition
+   *
+   * @param definition - Tree definition to validate
+   * @param registry - Registry to check node types and tree references
+   * @returns Array of validation errors (empty if valid)
+   */
+  validate(definition, registry) {
+    const errors = [];
+    const seenIds = /* @__PURE__ */ new Set();
+    const subTreePath = [];
+    this.validateNode(definition, registry, seenIds, subTreePath, "", errors);
+    return errors;
+  }
+  /**
+   * Recursively validate a node and its children
+   */
+  validateNode(node, registry, seenIds, subTreePath, path2, errors) {
+    const nodePath = path2 ? `${path2}.${node.id || node.type}` : node.id || node.type;
+    if (!registry.has(node.type)) {
+      errors.push(
+        new SemanticValidationError(
+          `Unknown node type '${node.type}'`,
+          nodePath,
+          `Available types: ${registry.getRegisteredTypes().join(", ")}`
+        )
+      );
+      return;
+    }
+    if (node.id) {
+      if (seenIds.has(node.id)) {
+        errors.push(
+          new SemanticValidationError(
+            `Duplicate ID '${node.id}'`,
+            nodePath,
+            "Use unique IDs for each node in the tree"
+          )
+        );
+      } else {
+        seenIds.add(node.id);
+      }
+    }
+    if (node.type === "SubTree") {
+      const treeId = node.props?.treeId || "";
+      if (!treeId) {
+        errors.push(
+          new SemanticValidationError(
+            "SubTree node missing 'treeId' property",
+            nodePath,
+            "Specify which tree to reference with 'treeId' in props"
+          )
+        );
+      } else {
+        if (subTreePath.includes(treeId)) {
+          errors.push(
+            new SemanticValidationError(
+              `Circular SubTree reference detected: ${subTreePath.join(" -> ")} -> ${treeId}`,
+              nodePath,
+              "Remove circular tree references"
+            )
+          );
+        }
+        if (registry.hasTree && !registry.hasTree(treeId)) {
+          errors.push(
+            new SemanticValidationError(
+              `SubTree references unknown tree '${treeId}'`,
+              nodePath,
+              `Register the tree '${treeId}' before referencing it`
+            )
+          );
+        }
+      }
+    }
+    const metadata = registry.getMetadata(node.type);
+    if (metadata) {
+      if (metadata.category === "decorator") {
+        const childCount = node.children?.length || 0;
+        if (childCount !== 1) {
+          errors.push(
+            new SemanticValidationError(
+              `Decorator '${node.type}' must have exactly 1 child (has ${childCount})`,
+              nodePath,
+              "Decorators wrap a single child node"
+            )
+          );
+        }
+      }
+      if (node.type === "While") {
+        const childCount = node.children?.length || 0;
+        if (childCount !== 2) {
+          errors.push(
+            new SemanticValidationError(
+              `While node requires exactly 2 children: condition and body (has ${childCount})`,
+              nodePath,
+              "First child is the condition, second is the body to execute"
+            )
+          );
+        }
+      }
+      if (node.type === "Conditional") {
+        const childCount = node.children?.length || 0;
+        if (childCount < 2 || childCount > 3) {
+          errors.push(
+            new SemanticValidationError(
+              `Conditional node requires 2-3 children: condition, then, optional else (has ${childCount})`,
+              nodePath,
+              "First child is condition, second is 'then' branch, third is optional 'else' branch"
+            )
+          );
+        }
+      }
+      if (node.type === "ForEach") {
+        const childCount = node.children?.length || 0;
+        if (childCount === 0) {
+          errors.push(
+            new SemanticValidationError(
+              "ForEach node requires at least 1 child (the body to execute for each item)",
+              nodePath,
+              "Add a child node to execute for each item in the collection"
+            )
+          );
+        }
+      }
+    }
+    if (node.children && Array.isArray(node.children)) {
+      const newSubTreePath = node.type === "SubTree" && node.props?.treeId ? [...subTreePath, node.props.treeId] : subTreePath;
+      node.children.forEach((child, index) => {
+        this.validateNode(
+          child,
+          registry,
+          seenIds,
+          newSubTreePath,
+          `${nodePath}.children[${index}]`,
+          errors
+        );
+      });
+    }
+  }
+};
+var semanticValidator = new SemanticValidator();
+
+// src/yaml/parser.ts
+function parseYaml(yamlString) {
+  try {
+    const parsed = yaml.load(yamlString);
+    if (!parsed || typeof parsed !== "object") {
+      throw new YamlSyntaxError(
+        "Invalid YAML: expected an object",
+        void 0,
+        void 0,
+        "Ensure your YAML defines a tree structure with 'type' field"
+      );
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof YamlSyntaxError) {
+      throw error;
+    }
+    if (error instanceof yaml.YAMLException) {
+      throw new YamlSyntaxError(
+        error.message,
+        error.mark?.line,
+        error.mark?.column,
+        "Check YAML syntax (indentation, colons, quotes)"
+      );
+    }
+    throw new YamlSyntaxError(
+      `Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`,
+      void 0,
+      void 0,
+      "Ensure your YAML is well-formed"
+    );
+  }
+}
+function validateStructure(definition) {
+  try {
+    return treeDefinitionSchema.parse(definition);
+  } catch (error) {
+    throw new StructureValidationError(
+      `Invalid tree structure: ${error instanceof Error ? error.message : String(error)}`,
+      void 0,
+      "Ensure all nodes have 'type' field and children are arrays"
+    );
+  }
+}
+function loadTreeFromYaml(yamlString, registry, options = {}) {
+  const { validate = true, failFast = true, autoGenerateIds = true } = options;
+  const parsed = parseYaml(yamlString);
+  if (validate) {
+    const definition = validateStructure(parsed);
+    if (failFast) {
+      const semanticErrors = semanticValidator.validate(definition, registry);
+      if (semanticErrors.length > 0) {
+        if (failFast) {
+          throw semanticErrors[0];
+        } else {
+          throw new ValidationErrors(semanticErrors);
+        }
+      }
+    }
+    return registry.createTree(definition);
+  }
+  return registry.createTree(parsed);
+}
+function validateYaml(yamlString, registry, options = {}) {
+  const { collectAllErrors = false, checkReferences = true } = options;
+  const errors = [];
+  try {
+    const parsed = parseYaml(yamlString);
+    const definition = validateStructure(parsed);
+    if (checkReferences) {
+      const semanticErrors = semanticValidator.validate(definition, registry);
+      errors.push(...semanticErrors);
+    }
+    if (errors.length === 0 || collectAllErrors) {
+      const result = registry.safeCreateTree(definition);
+      if (!result.success) {
+        errors.push(
+          new StructureValidationError(
+            result.error.message,
+            void 0,
+            "Check node configurations match their schema requirements"
+          )
+        );
+      }
+    }
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  } catch (error) {
+    if (error instanceof ValidationErrors) {
+      return {
+        valid: false,
+        errors: error.errors
+      };
+    }
+    if (error instanceof ValidationError) {
+      errors.push(error);
+    } else {
+      errors.push(
+        new YamlSyntaxError(
+          error instanceof Error ? error.message : String(error)
+        )
+      );
+    }
+    return {
+      valid: false,
+      errors
+    };
+  }
+}
+function toYaml(definition) {
+  return yaml.dump(definition, {
+    indent: 2,
+    lineWidth: 80,
+    noRefs: true
+  });
+}
+
+// src/yaml/loader.ts
+import { readFile } from "fs/promises";
+async function loadTreeFromFile(filePath, registry, options = {}) {
+  try {
+    const yamlContent = await readFile(filePath, "utf-8");
+    return loadTreeFromYaml(yamlContent, registry, options);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    throw error;
+  }
+}
+
+// src/templates/template-loader.ts
+import * as fs from "fs";
+import * as path from "path";
+async function loadTemplatesFromDirectory(registry, options) {
+  const { templatesDir, idPrefix = "" } = options;
+  const loadedIds = [];
+  if (!fs.existsSync(templatesDir)) {
+    console.warn(
+      `[TemplateLoader] Templates directory not found: ${templatesDir}`
+    );
+    return loadedIds;
+  }
+  const files = fs.readdirSync(templatesDir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+  for (const file of files) {
+    const filePath = path.join(templatesDir, file);
+    try {
+      const yamlContent = fs.readFileSync(filePath, "utf-8");
+      const rootNode = loadTreeFromYaml(yamlContent, registry);
+      const tree = new BehaviorTree(rootNode);
+      const baseName = path.basename(file, path.extname(file));
+      const templateId = idPrefix + baseName;
+      registry.registerTree(templateId, tree, filePath);
+      loadedIds.push(templateId);
+      console.log(`[TemplateLoader] Registered template: ${templateId}`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to load template '${file}': ${errorMessage}`
+      );
+    }
+  }
+  console.log(
+    `[TemplateLoader] Loaded ${loadedIds.length} template(s) from ${templatesDir}`
+  );
+  return loadedIds;
+}
+function loadTemplate(registry, filePath, templateId) {
+  const yamlContent = fs.readFileSync(filePath, "utf-8");
+  const rootNode = loadTreeFromYaml(yamlContent, registry);
+  const tree = new BehaviorTree(rootNode);
+  const id = templateId || path.basename(filePath, path.extname(filePath));
+  registry.registerTree(id, tree, filePath);
+  console.log(`[TemplateLoader] Registered template: ${id} from ${filePath}`);
+  return id;
+}
+function hasTemplate(registry, templateId) {
+  return registry.hasTree(templateId);
+}
+function getTemplateIds(registry) {
+  return registry.getAllTreeIds();
+}
+
+// src/observability/execution-tracker.ts
+var ExecutionTracker = class {
+  nodeStates = /* @__PURE__ */ new Map();
+  timeline = [];
+  errors = [];
+  pathTaken = [];
+  startedAt = Date.now();
+  currentNodeId = null;
+  totalNodes;
+  finished = false;
+  constructor(totalNodes) {
+    this.totalNodes = totalNodes;
+  }
+  /**
+   * Process a node event and update internal state
+   * Called by NodeEventEmitter subscription
+   */
+  onNodeEvent(event) {
+    const state = this.getOrCreateState(
+      event.nodeId,
+      event.nodeType,
+      event.nodeName,
+      event.nodePath
+    );
+    const eventType = event.type;
+    switch (eventType) {
+      case "tick_start" /* TICK_START */:
+        this.handleTickStart(state, event);
+        break;
+      case "tick_end" /* TICK_END */:
+        this.handleTickEnd(state, event);
+        break;
+      case "error" /* ERROR */:
+        this.handleError(state, event);
+        break;
+      case "log" /* LOG */:
+        break;
+      case "halt" /* HALT */:
+      case "reset" /* RESET */:
+        break;
+    }
+  }
+  handleTickStart(state, event) {
+    state.status = "running";
+    state.tickCount++;
+    state.lastTickAt = event.timestamp;
+    this.currentNodeId = event.nodeId;
+    this.timeline.push({
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      event: "start",
+      timestamp: event.timestamp
+    });
+  }
+  handleTickEnd(state, event) {
+    const status = event.data?.status;
+    const durationMs = event.data?.durationMs;
+    if (status === "SUCCESS") {
+      state.status = "success";
+      if (!this.pathTaken.includes(event.nodeId)) {
+        this.pathTaken.push(event.nodeId);
+      }
+    } else if (status === "FAILURE") {
+      state.status = "failure";
+    } else if (status === "RUNNING") {
+      state.status = "running";
+    } else {
+      state.status = "idle";
+    }
+    if (durationMs !== void 0) {
+      state.durationMs = durationMs;
+    }
+    this.timeline.push({
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      event: "end",
+      timestamp: event.timestamp,
+      status: state.status,
+      durationMs: state.durationMs
+    });
+    if (this.currentNodeId === event.nodeId && state.status !== "running") {
+      this.currentNodeId = null;
+    }
+  }
+  handleError(state, event) {
+    state.status = "failure";
+    const errorData = event.data?.error;
+    state.lastError = errorData?.message ?? "Unknown error";
+    const structuredError = {
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      message: errorData?.message ?? "Unknown error",
+      stack: errorData?.stack,
+      timestamp: event.timestamp,
+      blackboardSnapshot: event.data?.blackboard ?? {},
+      nodeInput: errorData?.input,
+      recoverable: this.isRecoverable(event.nodeType),
+      suggestedFix: this.suggestFix(event)
+    };
+    this.errors.push(structuredError);
+    this.timeline.push({
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      event: "error",
+      timestamp: event.timestamp,
+      error: {
+        message: structuredError.message,
+        stack: structuredError.stack
+      }
+    });
+  }
+  /**
+   * Mark execution as finished
+   */
+  markFinished() {
+    this.finished = true;
+    this.currentNodeId = null;
+  }
+  /**
+   * Get overall execution progress
+   */
+  getProgress() {
+    const states = [...this.nodeStates.values()];
+    const completed = states.filter((n) => n.status === "success").length;
+    const failed = states.filter((n) => n.status === "failure").length;
+    let status;
+    if (failed > 0) {
+      status = "failed";
+    } else if (this.finished) {
+      status = "completed";
+    } else if (this.currentNodeId) {
+      status = "running";
+    } else {
+      status = "completed";
+    }
+    return {
+      totalNodes: this.totalNodes,
+      completedNodes: completed,
+      failedNodes: failed,
+      currentNodeId: this.currentNodeId,
+      currentNodeType: this.nodeStates.get(this.currentNodeId ?? "")?.type ?? null,
+      pathTaken: [...this.pathTaken],
+      startedAt: this.startedAt,
+      lastActivityAt: this.timeline[this.timeline.length - 1]?.timestamp ?? this.startedAt,
+      status
+    };
+  }
+  /**
+   * Get all node states
+   */
+  getNodeStates() {
+    return new Map(this.nodeStates);
+  }
+  /**
+   * Get node states as a plain object (for JSON serialization)
+   */
+  getNodeStatesObject() {
+    const result = {};
+    for (const [id, state] of this.nodeStates) {
+      result[id] = { ...state };
+    }
+    return result;
+  }
+  /**
+   * Get all errors that occurred during execution
+   */
+  getErrors() {
+    return [...this.errors];
+  }
+  /**
+   * Get the full execution timeline
+   */
+  getTimeline() {
+    return [...this.timeline];
+  }
+  /**
+   * Get state for a specific node
+   */
+  getNodeState(nodeId) {
+    return this.nodeStates.get(nodeId);
+  }
+  getOrCreateState(id, type, name, path2) {
+    if (!this.nodeStates.has(id)) {
+      this.nodeStates.set(id, {
+        id,
+        type,
+        name,
+        path: path2 ?? "",
+        status: "idle",
+        tickCount: 0
+      });
+    }
+    return this.nodeStates.get(id);
+  }
+  /**
+   * Check if an error type is potentially recoverable with retry
+   */
+  isRecoverable(nodeType) {
+    const recoverableTypes = [
+      "FetchUrl",
+      "HttpRequest",
+      "CodeExecution",
+      "ParseFile",
+      "GenerateFile",
+      "IntegrationAction"
+    ];
+    return recoverableTypes.includes(nodeType);
+  }
+  /**
+   * Suggest a fix based on error patterns
+   */
+  suggestFix(event) {
+    const msg = event.data?.error?.message ?? "";
+    const nodeType = event.nodeType;
+    if (msg.includes("timeout") || msg.includes("TIMEOUT") || msg.includes("timed out")) {
+      return "Consider increasing timeout or adding retry decorator";
+    }
+    if (msg.includes("undefined") || msg.includes("null") || msg.includes("Cannot read property")) {
+      return "Check if required blackboard key exists before accessing";
+    }
+    if (msg.includes("network") || msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      return "Check URL accessibility, consider adding retry decorator";
+    }
+    if (msg.includes("401") || msg.includes("403") || msg.includes("unauthorized")) {
+      return "Check authentication credentials and permissions";
+    }
+    if (msg.includes("not found") || msg.includes("ENOENT") || msg.includes("404")) {
+      return "Verify file path or URL exists";
+    }
+    if (nodeType === "CodeExecution") {
+      if (msg.includes("SyntaxError")) {
+        return "Fix syntax error in code";
+      }
+      if (msg.includes("ReferenceError")) {
+        return "Variable not defined - check getBB() keys";
+      }
+    }
+    return void 0;
+  }
+};
+
+// src/observability/sinks.ts
+function createObservabilitySinkHandler(config = {}) {
+  return {
+    events: {
+      push: {
+        fn: (workflowInfo, event) => {
+          const { workflowId, runId } = workflowInfo;
+          if (config.logEvents) {
+            console.log(
+              `[Sink] [${workflowId}] ${event.type}: ${event.nodeId} (${event.nodeType})`
+            );
+          }
+          if (config.onEvent) {
+            Promise.resolve(config.onEvent(workflowId, runId, event)).catch(
+              (err) => console.error("[Sink] Error in onEvent handler:", err)
+            );
+          }
+          if (event.type === "error" && config.onError) {
+            Promise.resolve(config.onError(workflowId, runId, event)).catch(
+              (err) => console.error("[Sink] Error in onError handler:", err)
+            );
+          }
+        },
+        // Don't call during replay - events were already processed
+        callDuringReplay: false
+      }
+    }
+  };
+}
+export {
+  ActionNode,
+  AlwaysCondition,
+  BaseNode,
+  BehaviorTree,
+  CheckCondition,
+  CodeExecution,
+  CompositeNode,
+  ConditionNode,
+  Conditional,
+  ConfigValidationError,
+  ConfigurationError,
+  CounterAction,
+  DecoratorNode,
+  Delay,
+  ExecutionTracker,
+  FailureNode,
+  Fallback,
+  ForEach,
+  ForceFailure,
+  ForceSuccess,
+  GenerateFile,
+  HttpRequest,
+  IntegrationAction,
+  Invert,
+  KeepRunningUntilFailure,
+  LogMessage,
+  MemoryDataStore,
+  MemorySequence,
+  MockAction,
+  NodeEventEmitter,
+  NodeEventType,
+  NodeStatus,
+  Parallel,
+  ParseFile,
+  Precondition,
+  PrintAction,
+  PythonScript,
+  ReactiveSequence,
+  Recovery,
+  RegexExtract,
+  Registry,
+  Repeat,
+  ResumePoint,
+  RunOnce,
+  RunningNode,
+  SchemaRegistry,
+  ScopedBlackboard,
+  Selector,
+  SemanticValidationError,
+  Sequence,
+  SequenceWithMemory,
+  SoftAssert,
+  StructureValidationError,
+  SubTree,
+  SuccessNode,
+  Timeout,
+  ValidationError,
+  ValidationErrors,
+  WaitAction,
+  While,
+  YamlSyntaxError,
+  clearPieceCache,
+  createNodeSchema,
+  createObservabilitySinkHandler,
+  envTokenProvider,
+  executePieceAction,
+  extractVariables,
+  getTemplateIds,
+  hasTemplate,
+  hasVariables,
+  isDataRef,
+  isPieceInstalled,
+  listPieceActions,
+  loadTemplate,
+  loadTemplatesFromDirectory,
+  loadTreeFromFile,
+  loadTreeFromYaml,
+  nodeConfigurationSchema,
+  parseYaml,
+  registerStandardNodes,
+  resolveString,
+  resolveValue,
+  safeValidateConfiguration,
+  schemaRegistry,
+  semanticValidator,
+  toYaml,
+  treeDefinitionSchema,
+  validateChildCount,
+  validateChildCountRange,
+  validateCompositeChildren,
+  validateConfiguration,
+  validateDecoratorChildren,
+  validateTreeDefinition,
+  validateYaml,
+  validations,
+  zodErrorToConfigurationError
+};