@q1k-oss/behaviour-tree-workflows 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,3320 @@
+import { z } from 'zod';
+import { Sinks } from '@temporalio/workflow';
+
+/**
+ * Event system for observing behavior tree execution
+ * Enables external systems (debuggers, monitors, agents) to track execution in real-time
+ */
+/**
+ * Types of events emitted by nodes during execution
+ */
+declare enum NodeEventType {
+    TICK_START = "tick_start",
+    TICK_END = "tick_end",
+    STATUS_CHANGE = "status_change",
+    ERROR = "error",
+    HALT = "halt",
+    RESET = "reset",
+    LOG = "log"
+}
+/**
+ * Data for LOG events emitted by LogMessage nodes
+ */
+interface LogEventData {
+    level: "info" | "warn" | "error" | "debug";
+    message: string;
+}
+/**
+ * Event emitted by a node during execution
+ */
+interface NodeEvent<TData> {
+    type: NodeEventType;
+    nodeId: string;
+    nodeName: string;
+    nodeType: string;
+    timestamp: number;
+    /** Tree path (e.g., "/0/1/2") - set by tree execution */
+    nodePath?: string;
+    data?: TData;
+}
+/**
+ * Callback function for node events
+ */
+type NodeEventCallback<TData> = (event: NodeEvent<TData>) => void;
+/**
+ * Event emitter for behavior tree nodes
+ * Supports subscribing to specific event types and emitting events
+ */
+declare class NodeEventEmitter {
+    private listeners;
+    private allListeners;
+    /**
+     * Subscribe to a specific event type
+     * @param type - The event type to listen for
+     * @param callback - Function to call when event occurs
+     */
+    on<TData>(type: NodeEventType, callback: NodeEventCallback<TData>): void;
+    /**
+     * Subscribe to all event types
+     * @param callback - Function to call for any event
+     */
+    onAll<TData>(callback: NodeEventCallback<TData>): void;
+    /**
+     * Unsubscribe from a specific event type
+     * @param type - The event type to stop listening for
+     * @param callback - The callback to remove
+     */
+    off<TData>(type: NodeEventType, callback: NodeEventCallback<TData>): void;
+    /**
+     * Unsubscribe from all events
+     * @param callback - The callback to remove
+     */
+    offAll<TData>(callback: NodeEventCallback<TData>): void;
+    /**
+     * 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<TData>(event: NodeEvent<TData>): void;
+    /**
+     * Remove all listeners
+     */
+    clear(): void;
+    /**
+     * Get count of listeners for a specific type
+     * @param type - The event type to check
+     * @returns Number of listeners
+     */
+    listenerCount(type: NodeEventType): number;
+    /**
+     * Get count of "all events" listeners
+     * @returns Number of listeners
+     */
+    allListenerCount(): number;
+    /**
+     * Check if there are any listeners
+     * @returns True if any listeners are registered
+     */
+    hasListeners(): boolean;
+}
+
+/**
+ * Core types for the Behavior Tree implementation
+ * Inspired by BehaviorTree.CPP
+ */
+/**
+ * Status of a node after tick execution
+ */
+declare enum NodeStatus {
+    SUCCESS = "SUCCESS",
+    FAILURE = "FAILURE",
+    RUNNING = "RUNNING",
+    IDLE = "IDLE"
+}
+/**
+ * Base configuration for all nodes
+ */
+interface NodeConfiguration {
+    id: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Context passed during tick execution
+ */
+interface TickContext {
+    blackboard: IScopedBlackboard;
+    treeRegistry: ITreeRegistry;
+    signal?: AbortSignal;
+    deltaTime?: number;
+    timestamp: number;
+    testData?: Map<string, unknown>;
+    /**
+     * Immutable workflow input parameters
+     * Accessible via ${input.key} syntax in variable resolution
+     * These are passed when the workflow starts and should not be modified
+     */
+    input?: Readonly<Record<string, unknown>>;
+    sessionId?: string;
+    eventEmitter?: NodeEventEmitter;
+}
+/**
+ * Token provider function type for OAuth/API key authentication
+ */
+type TokenProvider = (context: TemporalContext, provider: string, connectionId?: string) => Promise<PieceAuth>;
+/**
+ * Extended context for Temporal workflow execution
+ * Replaces EffectTickContext for Temporal-native execution
+ */
+interface TemporalContext extends TickContext {
+    workflowInfo?: {
+        workflowId: string;
+        runId: string;
+        namespace: string;
+    };
+    /**
+     * Activity functions for I/O operations
+     * When provided, I/O nodes use these instead of inline execution
+     * Controlplane creates these via proxyActivities() and passes to context
+     */
+    activities?: BtreeActivities;
+    /**
+     * Token provider for IntegrationAction authentication
+     * Returns OAuth tokens or API keys for third-party services
+     */
+    tokenProvider?: TokenProvider;
+}
+/**
+ * Activity capabilities that can be provided to btree
+ * Controlplane creates these via proxyActivities() and passes to context
+ */
+interface BtreeActivities {
+    /** Execute an Active Pieces action (Google Sheets, Slack, etc.) */
+    executePieceAction: (request: PieceActivityRequest) => Promise<unknown>;
+    /** Execute Python code via cross-language activity */
+    executePythonScript?: (request: PythonScriptRequest) => Promise<PythonScriptResult>;
+    /** Parse CSV/Excel file into structured data */
+    parseFile?: (request: ParseFileRequest) => Promise<ParseFileResult>;
+    /** Generate CSV/Excel file from data */
+    generateFile?: (request: GenerateFileRequest) => Promise<GenerateFileResult>;
+    /** Make HTTP request (for nodes that don't use Active Pieces) */
+    fetchUrl?: (request: HttpRequestActivity) => Promise<HttpResponseActivity>;
+    /** Execute code in sandbox (Microsandbox) - supports JavaScript and Python */
+    executeCode?: (request: CodeExecutionRequest) => Promise<CodeExecutionResult>;
+    /** Upload file to storage, returns DataRef */
+    uploadFile?: (request: UploadFileRequest) => Promise<UploadFileResult>;
+    /** Download file from storage */
+    downloadFile?: (request: DownloadFileRequest) => Promise<DownloadFileResult>;
+    /** Delete file from storage */
+    deleteFile?: (request: DeleteFileRequest) => Promise<DeleteFileResult>;
+    /** Check if file exists in storage */
+    fileExists?: (request: FileExistsRequest) => Promise<FileExistsResult>;
+}
+/**
+ * Authentication credentials for a piece
+ */
+type PieceAuth = {
+    access_token: string;
+    refresh_token?: string;
+} | {
+    api_key: string;
+} | Record<string, unknown>;
+interface PieceActivityRequest {
+    provider: string;
+    action: string;
+    inputs: Record<string, unknown>;
+    auth: PieceAuth;
+}
+interface PythonScriptRequest {
+    /** Python code to execute */
+    code: string;
+    /** Blackboard snapshot (serializable) */
+    blackboard: Record<string, unknown>;
+    /** Workflow input (read-only) */
+    input?: Record<string, unknown>;
+    /** Allowed environment variables */
+    env?: Record<string, string>;
+    /** Execution timeout in ms */
+    timeout?: number;
+}
+interface PythonScriptResult {
+    /** Modified blackboard values */
+    blackboard: Record<string, unknown>;
+    /** Stdout from Python execution */
+    stdout?: string;
+    /** Stderr from Python execution */
+    stderr?: string;
+}
+interface ParseFileRequest {
+    /** File path or URL */
+    file: string;
+    /** File format (auto-detect if not specified) */
+    format?: "csv" | "xlsx" | "xls" | "auto";
+    /** Sheet name for Excel (default: first sheet) */
+    sheetName?: string;
+    /** Column mapping { "Original Name": "normalizedName" } */
+    columnMapping?: Record<string, string>;
+    /** Parse options */
+    options?: {
+        skipRows?: number;
+        trim?: boolean;
+        emptyAsNull?: boolean;
+        dateColumns?: string[];
+        dateFormat?: string;
+    };
+}
+interface ParseFileResult {
+    /** Parsed data rows */
+    data: Record<string, unknown>[];
+    /** Number of rows parsed */
+    rowCount: number;
+    /** Column names detected */
+    columns: string[];
+}
+interface GenerateFileRequest {
+    /** Output format */
+    format: "csv" | "xlsx" | "json";
+    /** Data to write */
+    data: Record<string, unknown>[];
+    /** Column definitions */
+    columns?: Array<{
+        header: string;
+        key: string;
+        width?: number;
+    }>;
+    /** Output filename */
+    filename: string;
+    /** Storage type */
+    storage: "temp" | "persistent";
+}
+interface GenerateFileResult {
+    /** Generated filename */
+    filename: string;
+    /** MIME type */
+    contentType: string;
+    /** File size in bytes */
+    size: number;
+    /** File path or storage key */
+    path: string;
+    /** Pre-signed download URL (if persistent) */
+    url?: string;
+}
+interface HttpRequestActivity {
+    url: string;
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeout?: number;
+}
+interface HttpResponseActivity {
+    status: number;
+    headers: Record<string, string>;
+    data: unknown;
+}
+interface UploadFileRequest {
+    /** Base64-encoded file content */
+    fileBytes: string;
+    /** Target filename */
+    filename: string;
+    /** MIME type */
+    contentType?: string;
+    /** Workflow ID for organizing storage */
+    workflowId?: string;
+}
+interface UploadFileResult {
+    /** Reference to stored file */
+    dataRef: DataRef$1;
+    /** Uploaded filename */
+    filename: string;
+    /** File size in bytes */
+    sizeBytes: number;
+}
+interface DownloadFileRequest {
+    /** Reference to file in storage */
+    dataRef: DataRef$1;
+}
+interface DownloadFileResult {
+    /** Base64-encoded file content */
+    fileBytes: string;
+    /** File size in bytes */
+    sizeBytes: number;
+}
+interface DeleteFileRequest {
+    /** Reference to file in storage */
+    dataRef: DataRef$1;
+}
+interface DeleteFileResult {
+    /** Whether deletion was successful */
+    deleted: boolean;
+    /** Key of deleted file */
+    key: string;
+}
+interface FileExistsRequest {
+    /** Reference to file in storage */
+    dataRef: DataRef$1;
+}
+interface FileExistsResult {
+    /** Whether file exists */
+    exists: boolean;
+    /** Key checked */
+    key: string;
+}
+/**
+ * Reference to data stored in a DataStore
+ * Import from data-store module for full type, this is a lightweight re-export
+ */
+interface DataRef$1 {
+    store: "gcs" | "s3" | "redis" | "memory";
+    key: string;
+    sizeBytes?: number;
+    expiresAt?: number;
+}
+/**
+ * Request for code execution in a sandboxed environment
+ */
+interface CodeExecutionRequest {
+    /** Code to execute */
+    code: string;
+    /** Programming language */
+    language: "javascript" | "python";
+    /** References to large data stored in DataStore */
+    dataRefs?: Record<string, DataRef$1>;
+    /** Inline context data (small values) */
+    context?: Record<string, unknown>;
+    /** Workflow input data (read-only) */
+    input?: Record<string, unknown>;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+    /** Python packages to install before execution */
+    packages?: string[];
+    /** Associated workflow ID for data storage */
+    workflowId?: string;
+}
+/**
+ * Result from code execution
+ */
+interface CodeExecutionResult {
+    /** Small values returned inline */
+    values: Record<string, unknown>;
+    /** Large values stored in DataStore (returns refs) */
+    dataRefs: Record<string, DataRef$1>;
+    /** Console/stdout output from execution */
+    logs: string[];
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * Port definition for typed inputs/outputs
+ */
+interface PortDefinition {
+    name: string;
+    type: "input" | "output" | "inout";
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+}
+/**
+ * Base interface for all tree nodes
+ */
+interface TreeNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    tick(context: TemporalContext): Promise<NodeStatus>;
+    halt(): void;
+    reset(): void;
+    clone(): TreeNode;
+    providedPorts?(): PortDefinition[];
+    status(): NodeStatus;
+    lastError?: string;
+    parent?: TreeNode;
+    children?: TreeNode[];
+}
+/**
+ * Constructor type for node factories
+ */
+type NodeConstructor<T extends TreeNode = TreeNode> = new (config: NodeConfiguration) => T;
+/**
+ * Node metadata for registry
+ */
+interface NodeMetadata {
+    type: string;
+    category: "action" | "condition" | "decorator" | "composite" | "subtree";
+    description?: string;
+    ports?: PortDefinition[];
+}
+/**
+ * Interface for tree registry (session-scoped)
+ * Used by nodes like StepGroup and LocateElement to lookup behavior trees
+ */
+interface ITreeRegistry {
+    hasTree(id: string): boolean;
+    cloneTree(id: string): {
+        getRoot(): TreeNode;
+    };
+    getAllTreeIds(): string[];
+    registerTree(id: string, tree: {
+        getRoot(): TreeNode;
+        clone(): {
+            getRoot(): TreeNode;
+        };
+    }, sourceFile: string): void;
+    getTree(id: string): {
+        getRoot(): TreeNode;
+        clone(): {
+            getRoot(): TreeNode;
+        };
+    } | undefined;
+    getTreeSourceFile(id: string): string | undefined;
+    getTreesForFile(filePath: string): Map<string, {
+        getRoot(): TreeNode;
+        clone(): {
+            getRoot(): TreeNode;
+        };
+    }>;
+}
+/**
+ * Interface for scoped blackboard
+ */
+interface IScopedBlackboard {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    clear(): void;
+    createScope(name: string): IScopedBlackboard;
+    getParentScope(): IScopedBlackboard | null;
+    getScopeName(): string;
+    getFullScopePath(): string;
+    getPort<T>(key: string, defaultValue?: T): T;
+    setPort<T>(key: string, value: T): void;
+    keys(): string[];
+    entries(): [string, unknown][];
+    toJSON(): Record<string, unknown>;
+    clone(): IScopedBlackboard;
+}
+/**
+ * Arguments passed to a BehaviorTree workflow
+ */
+interface WorkflowArgs {
+    /**
+     * Input data to initialize the blackboard
+     */
+    input?: Record<string, unknown>;
+    /**
+     * Tree registry for looking up subtrees
+     */
+    treeRegistry: ITreeRegistry;
+    /**
+     * Optional session ID
+     */
+    sessionId?: string;
+    /**
+     * Activity functions for I/O operations (optional)
+     * When provided, nodes that support activities will use them instead of inline execution
+     * Controlplane creates these via proxyActivities() and passes them here
+     */
+    activities?: BtreeActivities;
+    /**
+     * Token provider for IntegrationAction authentication (optional)
+     * Returns OAuth tokens or API keys for third-party services
+     */
+    tokenProvider?: TokenProvider;
+}
+/**
+ * Result returned from a BehaviorTree workflow
+ */
+interface WorkflowResult {
+    /**
+     * Final status of the tree
+     */
+    status: NodeStatus;
+    /**
+     * Final blackboard state
+     */
+    output: Record<string, unknown>;
+}
+
+/**
+ * Abstract base class for all tree nodes
+ */
+declare abstract class BaseNode implements TreeNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    protected _status: NodeStatus;
+    protected _lastError?: string;
+    protected config: NodeConfiguration;
+    protected _eventEmitter?: NodeEventEmitter;
+    parent?: TreeNode;
+    children?: TreeNode[];
+    constructor(config: NodeConfiguration);
+    /**
+     * Main tick method - subclasses override to implement execution logic
+     * Returns Promise for async/RUNNING semantics
+     * All errors are caught and converted to NodeStatus.FAILURE
+     */
+    abstract tick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Clone this node (deep copy including children)
+     * Must be implemented by subclasses
+     */
+    abstract clone(): TreeNode;
+    halt(): void;
+    reset(): void;
+    status(): NodeStatus;
+    get lastError(): string | undefined;
+    providedPorts(): PortDefinition[];
+    /**
+     * Hook for derived classes to implement custom halt logic
+     */
+    protected onHalt(): void;
+    /**
+     * Hook for derived classes to implement custom reset logic
+     */
+    protected onReset(): void;
+    /**
+     * Helper to get input value from blackboard
+     */
+    protected getInput<T>(context: TemporalContext, key: string, defaultValue?: T): T;
+    /**
+     * Helper to set output value to blackboard
+     */
+    protected setOutput<T>(context: TemporalContext, key: string, value: T): void;
+    /**
+     * Log helper for debugging
+     */
+    protected log(message: string, ...args: unknown[]): void;
+}
+/**
+ * Base class for action nodes
+ * Includes resumable execution support and Effect-based async/RUNNING semantics
+ */
+declare abstract class ActionNode extends BaseNode {
+    /**
+     * Clone this action node
+     * Leaf nodes have no children to clone
+     */
+    clone(): TreeNode;
+    /**
+     * 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
+     */
+    tick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Abstract method for subclasses to implement their execution logic
+     * Returns Promise for async operations
+     */
+    protected abstract executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Base class for condition nodes
+ * Includes resumable execution support and async/RUNNING semantics
+ */
+declare abstract class ConditionNode extends BaseNode {
+    /**
+     * Clone this condition node
+     * Leaf nodes have no children to clone
+     */
+    clone(): TreeNode;
+    /**
+     * 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
+     */
+    tick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Abstract method for subclasses to implement their execution logic
+     * Returns Promise for async operations
+     */
+    protected abstract executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Base class for decorator nodes (single child)
+ */
+declare abstract class DecoratorNode extends BaseNode {
+    protected child?: TreeNode;
+    /**
+     * Clone this decorator node including its child
+     */
+    clone(): TreeNode;
+    /**
+     * 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
+     */
+    tick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Decorator nodes must implement their wrapping logic
+     * Returns Promise for async operations
+     */
+    protected abstract executeTick(context: TemporalContext): Promise<NodeStatus>;
+    setChild(child: TreeNode): void;
+    halt(): void;
+    reset(): void;
+}
+/**
+ * Base class for composite nodes (multiple children)
+ */
+declare abstract class CompositeNode extends BaseNode {
+    protected _children: TreeNode[];
+    /**
+     * Clone this composite node including all children
+     */
+    clone(): TreeNode;
+    /**
+     * 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
+     */
+    tick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Composite nodes must implement their traversal logic
+     * Returns Promise for async operations
+     */
+    protected abstract executeTick(context: TemporalContext): Promise<NodeStatus>;
+    addChild(child: TreeNode): void;
+    addChildren(children: TreeNode[]): void;
+    halt(): void;
+    reset(): void;
+    protected haltChildren(startIndex?: number): void;
+}
+
+/**
+ * BehaviorTree - Wrapper for TreeNode with path-based indexing
+ * Enables partial tree updates without full reload
+ */
+
+/**
+ * BehaviorTree class that wraps a TreeNode root with path-based indexing
+ * Paths use child indices: /0/1/2 represents root → child[0] → child[1] → child[2]
+ */
+/**
+ * Result of parsing a path with tree ID prefix
+ */
+interface ParsedPath {
+    treeId: string;
+    nodePath: string;
+}
+declare class BehaviorTree {
+    private root;
+    private pathIndex;
+    private idIndex;
+    constructor(root: TreeNode);
+    /**
+     * 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: string): ParsedPath;
+    /**
+     * Get the root node of the tree
+     */
+    getRoot(): TreeNode;
+    /**
+     * Find a node by its path
+     * Path format: / for root, /0 for first child, /0/1 for second child of first child
+     */
+    findNodeByPath(path: string): TreeNode | null;
+    /**
+     * Find a node by its ID (if it has one)
+     * Convenience method for nodes with explicit IDs
+     */
+    findNodeById(nodeId: string): TreeNode | null;
+    /**
+     * Get the path for a given node
+     * Returns null if the node is not in the tree
+     */
+    getNodePath(targetNode: TreeNode): string | 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: string): string | null;
+    /**
+     * Clone this BehaviorTree (deep clones the underlying TreeNode)
+     */
+    clone(): BehaviorTree;
+    /**
+     * 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(): (args: WorkflowArgs) => Promise<WorkflowResult>;
+    /**
+     * Replace a node at the given path with a new node
+     * Updates parent-child relationships and rebuilds the index
+     */
+    replaceNodeAtPath(path: string, newNode: TreeNode): void;
+    /**
+     * Build the node index with path-based and ID-based lookups
+     */
+    private buildNodeIndex;
+}
+
+/**
+ * Scoped Blackboard implementation with inheritance
+ * Inspired by BehaviorTree.CPP's blackboard
+ *
+ * Simple mutable API with native deep cloning for snapshots
+ */
+
+/**
+ * Implementation of a hierarchical blackboard with scoped inheritance
+ * Uses simple mutable operations with snapshot support via structuredClone
+ */
+declare class ScopedBlackboard implements IScopedBlackboard {
+    private data;
+    private parent;
+    private scopeName;
+    private childScopes;
+    constructor(scopeName?: string, parent?: ScopedBlackboard | null);
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+    clear(): void;
+    createScope(name: string): IScopedBlackboard;
+    getParentScope(): IScopedBlackboard | null;
+    getScopeName(): string;
+    getPort<T>(key: string, defaultValue?: T): T;
+    setPort<T>(key: string, value: T): void;
+    keys(): string[];
+    entries(): [string, unknown][];
+    toJSON(): Record<string, unknown>;
+    /**
+     * Create a deep clone of this blackboard for snapshots
+     * Uses structured cloning for deep copy
+     */
+    clone(): IScopedBlackboard;
+    /**
+     * Get the full scope path (e.g., "root.child.grandchild")
+     */
+    getFullScopePath(): string;
+    /**
+     * Debug utility to print the blackboard hierarchy
+     */
+    debug(indent?: number): void;
+}
+
+/**
+ * Conditional node - If-then-else logic for behavior trees
+ */
+
+/**
+ * Conditional implements if-then-else logic.
+ * Structure:
+ * - First child = condition
+ * - Second child = then branch
+ * - Third child (optional) = else branch
+ */
+declare class Conditional extends CompositeNode {
+    private condition?;
+    private thenBranch?;
+    private elseBranch?;
+    private conditionEvaluated;
+    private selectedBranch?;
+    /**
+     * Override addChild to enforce conditional structure
+     */
+    addChild(child: TreeNode): void;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onHalt(): void;
+    protected onReset(): void;
+}
+
+/**
+ * ForEach node - Iterate over collection
+ */
+
+interface ForEachConfiguration extends NodeConfiguration {
+    collectionKey: string;
+    itemKey: string;
+    indexKey?: string;
+}
+/**
+ * ForEach iterates over a collection from the blackboard.
+ * For each item, it sets the item (and optionally index) in the blackboard
+ * and executes the body (first child).
+ */
+declare class ForEach extends CompositeNode {
+    private collectionKey;
+    private itemKey;
+    private indexKey?;
+    private currentIndex;
+    constructor(config: ForEachConfiguration);
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onReset(): void;
+    protected onHalt(): void;
+}
+
+/**
+ * Sequence composite node
+ * Executes children in order until one fails or all succeed
+ */
+
+declare class Sequence extends CompositeNode {
+    private currentChildIndex;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onHalt(): void;
+    protected onReset(): void;
+}
+
+/**
+ * MemorySequence node - Remembers which children succeeded and skips them on retry
+ * Useful for long test sequences where early steps shouldn't re-run
+ */
+
+/**
+ * MemorySequence extends Sequence with memory of completed children.
+ * When a child fails, subsequent retries will skip already-successful children.
+ * This is particularly useful for expensive setup steps that shouldn't be re-executed.
+ */
+declare class MemorySequence extends Sequence {
+    private completedChildren;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onReset(): void;
+    protected onHalt(): void;
+}
+/**
+ * SequenceWithMemory is an alias for MemorySequence (BehaviorTree.CPP compatibility)
+ */
+declare class SequenceWithMemory extends MemorySequence {
+    constructor(config: NodeConfiguration);
+}
+
+/**
+ * Parallel composite node
+ * Executes all children concurrently (truly concurrent, not sequential)
+ */
+
+/**
+ * Execution strategy for parallel node
+ */
+type ParallelStrategy = "strict" | "any";
+interface ParallelConfiguration extends NodeConfiguration {
+    /**
+     * Execution strategy
+     * - 'strict': All children must succeed (default)
+     * - 'any': At least one child must succeed
+     */
+    strategy?: ParallelStrategy;
+    /**
+     * Optional: Number of children that must succeed (overrides strategy)
+     */
+    successThreshold?: number;
+    /**
+     * Optional: Number of children that must fail before parallel fails
+     */
+    failureThreshold?: number;
+}
+declare class Parallel extends CompositeNode {
+    private strategy;
+    private successThreshold?;
+    private failureThreshold?;
+    constructor(config: ParallelConfiguration);
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onHalt(): void;
+    protected onReset(): void;
+}
+
+/**
+ * ReactiveSequence node - Restarts from beginning each tick
+ * Responds to condition changes during execution
+ */
+
+/**
+ * ReactiveSequence restarts from the beginning on each tick.
+ * Unlike regular Sequence which remembers its position, ReactiveSequence
+ * re-evaluates all children from the start, making it responsive to
+ * conditions that might change between ticks.
+ *
+ * Use cases:
+ * - Real-time monitoring where conditions might change
+ * - Safety-critical checks that must be re-evaluated
+ * - Guard conditions that need constant verification
+ */
+declare class ReactiveSequence extends Sequence {
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Override to prevent parent Sequence from resetting currentChildIndex
+     * (ReactiveSequence doesn't use currentChildIndex)
+     */
+    protected onReset(): void;
+}
+
+/**
+ * Recovery node - Try-catch-finally error handling
+ */
+
+/**
+ * Recovery implements try-catch-finally error handling for behavior trees.
+ * Structure:
+ * - First child = try branch
+ * - Second child (optional) = catch branch
+ * - Third child (optional) = finally branch
+ *
+ * Behavior:
+ * - If try succeeds or returns RUNNING, use its result
+ * - If try returns FAILURE and catch exists, execute catch branch
+ * - Finally branch always executes (if present) after try/catch completes
+ * - Finally branch result does not affect the overall result
+ *
+ * Special error handling:
+ * - ConfigurationError and OperationCancelledError propagate immediately
+ * - When these special errors occur, finally branch does NOT execute
+ * - This differs from traditional finally semantics but is intentional:
+ *   ConfigurationError means the test is broken, so execution stops immediately
+ */
+declare class Recovery extends CompositeNode {
+    private tryBranch?;
+    private catchBranch?;
+    private finallyBranch?;
+    addChild(child: TreeNode): void;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * Selector (Fallback) composite node
+ * Executes children in order until one succeeds or all fail
+ */
+
+declare class Selector extends CompositeNode {
+    private currentChildIndex;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onHalt(): void;
+    protected onReset(): void;
+}
+/**
+ * Fallback is an alias for Selector (BehaviorTree.CPP compatibility)
+ */
+declare class Fallback extends Selector {
+    constructor(config: NodeConfiguration);
+}
+
+/**
+ * SubTree node - References and executes a behavior tree from the session-scoped registry
+ * Provides function-like reusability for step groups with scoped blackboard isolation
+ *
+ * Features:
+ * - params: Pass values to subtree's blackboard (supports variable resolution)
+ * - outputs: Export subtree values back to parent blackboard after execution
+ */
+
+interface SubTreeConfiguration extends NodeConfiguration {
+    /** BehaviorTree ID to look up from registry */
+    treeId: string;
+    /**
+     * Parameters to pass to the subtree's blackboard
+     * Supports variable resolution: ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Keys to export from subtree's blackboard back to parent after execution
+     * These values are copied to the parent scope when subtree completes
+     */
+    outputs?: string[];
+}
+/**
+ * SubTree - References and executes a behavior tree from the registry
+ *
+ * Execution flow:
+ * 1. Clone behavior tree from registry (lazy, on first tick)
+ * 2. Create scoped blackboard for isolation (subtree_${id})
+ * 3. Resolve and copy params to subtree's blackboard
+ * 4. Execute cloned tree with scoped context
+ * 5. Copy output values back to parent blackboard
+ * 6. Return the tree's execution status
+ *
+ * The scoped blackboard provides isolation while maintaining read access to parent scopes.
+ *
+ * @example
+ * ```yaml
+ * type: SubTree
+ * id: process-order
+ * props:
+ *   treeId: ProcessOrderFlow
+ *   params:
+ *     orderId: "${input.orderId}"
+ *     customer: "${bb.currentCustomer}"
+ *   outputs:
+ *     - orderResult
+ *     - processingTime
+ * ```
+ */
+declare class SubTree extends ActionNode {
+    private treeId;
+    private params;
+    private outputs;
+    private clonedTree?;
+    constructor(config: SubTreeConfiguration);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Override clone to include cloned tree
+     */
+    clone(): TreeNode;
+    /**
+     * Override halt to halt the referenced tree
+     */
+    halt(): void;
+    /**
+     * Override reset to reset the referenced tree
+     */
+    reset(): void;
+}
+
+/**
+ * While node - Loop while condition is true
+ */
+
+interface WhileConfiguration extends NodeConfiguration {
+    maxIterations?: number;
+}
+/**
+ * While loops while the condition returns SUCCESS.
+ * Structure:
+ * - First child = condition
+ * - Second child = body
+ */
+declare class While extends CompositeNode {
+    private maxIterations;
+    private currentIteration;
+    private condition?;
+    private body?;
+    private bodyStarted;
+    constructor(config: WhileConfiguration);
+    addChild(child: TreeNode): void;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onReset(): void;
+    protected onHalt(): void;
+}
+
+/**
+ * Delay decorator node
+ * Waits for a specified duration before executing the child
+ *
+ * In Temporal workflows: Uses sleep() for deterministic delays
+ * In standalone mode: Uses Date.now() polling for multi-tick behavior
+ */
+
+interface DelayConfiguration extends NodeConfiguration {
+    /**
+     * Delay duration in milliseconds
+     */
+    delayMs: number;
+}
+declare class Delay extends DecoratorNode {
+    private delayMs;
+    private delayStartTime;
+    private useTemporalAPI;
+    constructor(config: DelayConfiguration);
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onHalt(): void;
+    protected onReset(): void;
+}
+
+/**
+ * ForceSuccess and ForceFailure decorators
+ * Always return specific result regardless of child
+ */
+
+/**
+ * ForceSuccess always returns SUCCESS regardless of child result.
+ * Useful for ensuring a branch always succeeds.
+ */
+declare class ForceSuccess extends DecoratorNode {
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * ForceFailure always returns FAILURE regardless of child result.
+ * Useful for negation or testing.
+ */
+declare class ForceFailure extends DecoratorNode {
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * Invert decorator node
+ * Inverts the result of its child (SUCCESS becomes FAILURE and vice versa)
+ */
+
+declare class Invert extends DecoratorNode {
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * KeepRunningUntilFailure decorator
+ * Opposite of Retry - keeps running while child succeeds
+ */
+
+/**
+ * KeepRunningUntilFailure keeps executing its child while it succeeds.
+ * Returns SUCCESS when child fails (goal achieved).
+ * Returns RUNNING while child succeeds (keep going).
+ */
+declare class KeepRunningUntilFailure extends DecoratorNode {
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * Precondition decorator - Check/resolve preconditions before executing child
+ */
+
+/**
+ * Precondition checks preconditions before executing the main child.
+ * If preconditions fail, attempts to resolve them using resolvers.
+ * Useful for ensuring prerequisites are met before executing actions.
+ */
+declare class Precondition extends DecoratorNode {
+    private preconditions;
+    private preconditionsChecked;
+    /**
+     * Add a precondition to check before main execution
+     */
+    addPrecondition(condition: TreeNode, resolver?: TreeNode, required?: boolean): void;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onHalt(): void;
+    protected onReset(): void;
+}
+
+/**
+ * Repeat decorator - Execute child N times
+ */
+
+interface RepeatConfiguration extends NodeConfiguration {
+    numCycles: number;
+}
+/**
+ * Repeat executes its child exactly N times.
+ * Returns SUCCESS when all cycles complete successfully.
+ * Returns FAILURE if any cycle fails.
+ */
+declare class Repeat extends DecoratorNode {
+    private numCycles;
+    private currentCycle;
+    constructor(config: RepeatConfiguration);
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onReset(): void;
+    protected onHalt(): void;
+}
+
+/**
+ * RunOnce decorator - Execute child only once per session
+ */
+
+/**
+ * RunOnce executes its child only once and caches the result.
+ * Subsequent ticks return the cached result without re-executing the child.
+ * Useful for initialization or one-time setup operations.
+ */
+declare class RunOnce extends DecoratorNode {
+    private hasRun;
+    private cachedResult?;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onReset(): void;
+}
+
+/**
+ * SoftAssert decorator - Continue even if child fails
+ */
+
+/**
+ * SoftAssert converts child FAILURE to SUCCESS, allowing execution to continue.
+ * Logs all failures for later review but doesn't halt execution.
+ * Useful for non-critical checks that shouldn't block the test.
+ */
+declare class SoftAssert extends DecoratorNode {
+    private failures;
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Get all recorded failures
+     */
+    getFailures(): Array<{
+        timestamp: number;
+        message: string;
+    }>;
+    /**
+     * Check if any assertions have failed
+     */
+    hasFailures(): boolean;
+    protected onReset(): void;
+}
+
+/**
+ * Timeout decorator node
+ * Fails if the child doesn't complete within a specified time
+ *
+ * In Temporal workflows: Uses CancellationScope for deterministic timeouts
+ * In standalone mode: Uses Date.now() polling for multi-tick behavior
+ */
+
+interface TimeoutConfiguration extends NodeConfiguration {
+    /**
+     * Timeout duration in milliseconds
+     */
+    timeoutMs: number;
+}
+declare class Timeout extends DecoratorNode {
+    private timeoutMs;
+    private startTime;
+    private useTemporalAPI;
+    constructor(config: TimeoutConfiguration);
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    protected onHalt(): void;
+    protected onReset(): void;
+}
+
+/**
+ * Registry for behavior tree nodes
+ * Handles registration and creation of nodes by type
+ */
+
+declare class Registry {
+    private nodeTypes;
+    private nodeMetadata;
+    private behaviorTrees;
+    constructor();
+    /**
+     * Register a node type with the registry
+     */
+    register<T extends TreeNode>(type: string, ctor: NodeConstructor<T>, metadata?: Partial<NodeMetadata>): void;
+    /**
+     * Create a node instance by type
+     * Validates configuration against schema before creating node
+     */
+    create(type: string, config: NodeConfiguration): TreeNode;
+    /**
+     * Check if a node type is registered
+     */
+    has(type: string): boolean;
+    /**
+     * Get metadata for a node type
+     */
+    getMetadata(type: string): NodeMetadata | undefined;
+    /**
+     * Get all registered node types
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Get registered types by category
+     */
+    getTypesByCategory(category: NodeMetadata["category"]): string[];
+    /**
+     * Clear all registrations (node types, metadata, and behavior trees)
+     */
+    clear(): void;
+    /**
+     * 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: string, tree: BehaviorTree, sourceFile: string): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string, tree: BehaviorTree, sourceFile: string): void;
+    /**
+     * Get a behavior tree instance by ID
+     */
+    getTree(id: string): BehaviorTree | undefined;
+    /**
+     * Get the source file path for a behavior tree
+     */
+    getTreeSourceFile(id: string): string | undefined;
+    /**
+     * Get all trees that belong to a specific source file
+     */
+    getTreesForFile(filePath: string): Map<string, BehaviorTree>;
+    /**
+     * Check if a behavior tree is registered
+     */
+    hasTree(id: string): boolean;
+    /**
+     * Clone a registered behavior tree for instantiation
+     * Returns the cloned BehaviorTree (caller should use getRoot() for TreeNode)
+     */
+    cloneTree(id: string): BehaviorTree;
+    /**
+     * Get all registered behavior tree IDs
+     */
+    getAllTreeIds(): string[];
+    /**
+     * Clear all registered behavior trees
+     */
+    clearTrees(): void;
+    /**
+     * Create a tree from a JSON definition
+     * Validates tree structure before creating nodes
+     */
+    createTree(definition: unknown): TreeNode;
+    /**
+     * 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: unknown): {
+        success: true;
+        tree: TreeNode;
+    } | {
+        success: false;
+        error: Error;
+    };
+    private log;
+}
+
+/**
+ * Registry utilities for registering standard nodes
+ */
+
+/**
+ * Register all standard built-in nodes to a registry
+ * This includes composites, decorators, actions, conditions, and utilities
+ *
+ * @param registry - Registry to register nodes to
+ *
+ * @example
+ * ```typescript
+ * import { Registry, registerStandardNodes } from '@wayfarer-ai/btree';
+ *
+ * const registry = new Registry();
+ * registerStandardNodes(registry);
+ *
+ * // Now register your custom nodes
+ * registry.register('MyCustomAction', MyCustomAction, { category: 'action' });
+ * ```
+ */
+declare function registerStandardNodes(registry: Registry): void;
+
+/**
+ * Simple test nodes for demonstrating behavior tree functionality
+ */
+
+/**
+ * Simple action that prints a message and succeeds
+ */
+declare class PrintAction extends ActionNode {
+    private message;
+    constructor(config: NodeConfiguration & {
+        message?: string;
+    });
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Action that waits for a specified duration
+ */
+declare class WaitAction extends ActionNode {
+    private waitMs;
+    private startTime;
+    constructor(config: NodeConfiguration & {
+        waitMs?: number;
+    });
+    executeTick(_context: TemporalContext): Promise<NodeStatus>;
+    protected onReset(): void;
+    protected onHalt(): void;
+}
+/**
+ * Action that increments a counter in the blackboard
+ */
+declare class CounterAction extends ActionNode {
+    private counterKey;
+    private increment;
+    constructor(config: NodeConfiguration & {
+        counterKey?: string;
+        increment?: number;
+    });
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Action that can be configured to return any status
+ */
+declare class MockAction extends ActionNode {
+    private returnStatus;
+    private ticksBeforeComplete;
+    private currentTicks;
+    constructor(config: NodeConfiguration & {
+        returnStatus?: NodeStatus;
+        ticksBeforeComplete?: number;
+    });
+    executeTick(_context: TemporalContext): Promise<NodeStatus>;
+    protected onReset(): void;
+    protected onHalt(): void;
+}
+/**
+ * Condition that checks if a blackboard value meets a criteria
+ */
+declare class CheckCondition extends ConditionNode {
+    private key;
+    private operator;
+    private value;
+    constructor(config: NodeConfiguration & {
+        key: string;
+        operator?: string;
+        value: unknown;
+    });
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Simple condition that always returns the configured status
+ */
+declare class AlwaysCondition extends ConditionNode {
+    private returnStatus;
+    constructor(config: NodeConfiguration & {
+        returnStatus?: NodeStatus;
+    });
+    executeTick(_context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Simple test node that always succeeds
+ */
+declare class SuccessNode extends ActionNode {
+    executeTick(_context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Simple test node that always fails
+ */
+declare class FailureNode extends ActionNode {
+    executeTick(_context: TemporalContext): Promise<NodeStatus>;
+}
+/**
+ * Simple test node that stays running
+ */
+declare class RunningNode extends ActionNode {
+    executeTick(_context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * DataStore Interface
+ *
+ * Provides an abstraction for storing and retrieving large data payloads
+ * outside the workflow execution context. This keeps the Temporal workflow
+ * history lean while allowing workflows to process large datasets.
+ *
+ * Implementations:
+ * - MemoryDataStore: In-memory storage for tests
+ * - GCSDataStore: Google Cloud Storage for production (in controlplane)
+ * - RedisDataStore: Redis storage for caching (future)
+ */
+/**
+ * Reference to data stored in a DataStore
+ * This lightweight reference can be passed through workflows/activities
+ */
+interface DataRef {
+    /** Storage backend identifier */
+    store: "gcs" | "s3" | "redis" | "memory";
+    /** Unique key for retrieving the data */
+    key: string;
+    /** Size of stored data in bytes (for monitoring/optimization) */
+    sizeBytes?: number;
+    /** Unix timestamp when data expires (optional TTL) */
+    expiresAt?: number;
+}
+/**
+ * Options for storing data
+ */
+interface PutOptions {
+    /** Time-to-live in seconds (data auto-deleted after expiry) */
+    ttlSeconds?: number;
+    /** Content type hint for serialization */
+    contentType?: "json" | "csv" | "binary";
+    /** Associated workflow ID for grouping/cleanup */
+    workflowId?: string;
+}
+/**
+ * DataStore interface for storing and retrieving large payloads
+ */
+interface DataStore {
+    /**
+     * Store data and return a reference
+     * @param key - Unique identifier for the data
+     * @param data - Data to store (will be JSON serialized)
+     * @param options - Storage options (TTL, content type, etc.)
+     * @returns Reference to the stored data
+     */
+    put(key: string, data: unknown, options?: PutOptions): Promise<DataRef>;
+    /**
+     * Retrieve data by reference
+     * @param ref - Reference returned from put()
+     * @returns The stored data (JSON deserialized)
+     * @throws Error if data not found or expired
+     */
+    get(ref: DataRef): Promise<unknown>;
+    /**
+     * Delete data by reference
+     * @param ref - Reference to delete
+     */
+    delete(ref: DataRef): Promise<void>;
+    /**
+     * Check if data exists
+     * @param ref - Reference to check
+     * @returns true if data exists and hasn't expired
+     */
+    exists(ref: DataRef): Promise<boolean>;
+}
+/**
+ * Type guard to check if a value is a DataRef
+ * @param value - Value to check
+ * @returns true if value is a DataRef
+ */
+declare function isDataRef(value: unknown): value is DataRef;
+
+/**
+ * In-Memory DataStore Implementation
+ *
+ * Simple in-memory storage for testing and development.
+ * Data is lost when the process terminates.
+ *
+ * Features:
+ * - TTL support with automatic cleanup
+ * - Size tracking
+ * - Thread-safe for single Node.js process
+ */
+
+/**
+ * In-memory DataStore implementation
+ * Suitable for tests and local development
+ */
+declare class MemoryDataStore implements DataStore {
+    private storage;
+    private cleanupInterval;
+    constructor(options?: {
+        cleanupIntervalMs?: number;
+    });
+    put(key: string, data: unknown, options?: PutOptions): Promise<DataRef>;
+    get(ref: DataRef): Promise<unknown>;
+    delete(ref: DataRef): Promise<void>;
+    exists(ref: DataRef): Promise<boolean>;
+    /**
+     * Clear all stored data
+     * Useful for test cleanup
+     */
+    clear(): void;
+    /**
+     * Get the number of stored entries
+     */
+    size(): number;
+    /**
+     * Get total bytes stored
+     */
+    totalBytes(): number;
+    /**
+     * Stop the cleanup interval
+     * Call this when done with the store to prevent memory leaks in tests
+     */
+    dispose(): void;
+    /**
+     * Remove expired entries
+     */
+    private cleanup;
+}
+
+/**
+ * LogMessage Node - Log messages for debugging and test visibility
+ *
+ * Utility node that logs messages to console with optional variable resolution.
+ * Useful for debugging test flows and tracking execution progress.
+ *
+ * Supports variable resolution:
+ * - ${key} - Shorthand for blackboard (backward compatible)
+ * - ${input.key} - Workflow input parameters
+ * - ${bb.key} - Blackboard values
+ * - ${env.KEY} - Environment variables
+ * - ${param.key} - Test data parameters
+ *
+ * Use Cases:
+ * - Log intermediate values during test execution
+ * - Debug blackboard state at specific points
+ * - Add visibility to test steps
+ * - Track execution flow
+ *
+ * Examples:
+ * - Log static message: <LogMessage message="Starting form submission" />
+ * - Log blackboard value: <LogMessage message="Current URL: ${currentUrl}" />
+ * - Log input value: <LogMessage message="Order ID: ${input.orderId}" />
+ * - Log with level: <LogMessage message="Error occurred" level="error" />
+ */
+
+/**
+ * Configuration for LogMessage node
+ */
+interface LogMessageConfig extends NodeConfiguration {
+    message: string;
+    level?: "info" | "warn" | "error" | "debug";
+}
+/**
+ * LogMessage Node - Logs messages with optional variable resolution
+ */
+declare class LogMessage extends ActionNode {
+    private message;
+    private level;
+    constructor(config: LogMessageConfig);
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Resolve variable references in message string
+     * Supports ${key}, ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+     */
+    private resolveMessage;
+}
+
+/**
+ * RegexExtract Node - Extract text using regular expressions
+ *
+ * Data manipulation utility node that operates on blackboard values.
+ * Extracts matches from a text string using a regex pattern.
+ *
+ * Use Cases:
+ * - Extract email addresses from text
+ * - Extract numbers/IDs from strings
+ * - Parse structured data from unstructured text
+ * - Extract URLs from content
+ */
+
+/**
+ * Configuration for RegexExtract node
+ */
+interface RegexExtractConfig extends NodeConfiguration {
+    input: string;
+    pattern: string;
+    outputKey: string;
+    flags?: string;
+    matchIndex?: number;
+}
+/**
+ * RegexExtract Node - Extracts text using regular expressions
+ */
+declare class RegexExtract extends ActionNode {
+    private input;
+    private pattern;
+    private outputKey;
+    private flags;
+    private matchIndex?;
+    constructor(config: RegexExtractConfig);
+    executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * Unified Variable Resolver
+ *
+ * Resolves variable references in strings and objects with support for multiple namespaces:
+ * - ${input.key}  - Workflow input parameters (immutable)
+ * - ${bb.key}     - Blackboard values (mutable runtime state)
+ * - ${env.KEY}    - Environment variables
+ * - ${param.key}  - Test data parameters
+ * - ${key}        - Shorthand for ${bb.key} (backward compatibility)
+ *
+ * Features:
+ * - Nested property access: ${bb.user.profile.name}
+ * - Type preservation for full matches: "${bb.user}" returns the user object
+ * - String interpolation for partial matches: "Hello ${bb.name}!" returns string
+ */
+
+/**
+ * Context for variable resolution
+ */
+interface VariableContext {
+    /** Blackboard for runtime state */
+    blackboard: IScopedBlackboard;
+    /** Immutable workflow input parameters */
+    input?: Readonly<Record<string, unknown>>;
+    /** Test data parameters (from CSV, data tables, etc.) */
+    testData?: Map<string, unknown>;
+}
+/**
+ * Options for variable resolution
+ */
+interface ResolveOptions {
+    /** Whether to keep undefined placeholders in output (default: true) */
+    preserveUndefined?: boolean;
+    /** Custom environment source (default: process.env) */
+    envSource?: Record<string, string | undefined>;
+}
+declare function resolveString(str: string, ctx: VariableContext, opts?: ResolveOptions): unknown;
+/**
+ * Resolve variables in any value (string, object, array, or primitive)
+ *
+ * @param value - Value to resolve
+ * @param ctx - Variable context
+ * @param opts - Resolution options
+ * @returns Resolved value with all variable references replaced
+ */
+declare function resolveValue(value: unknown, ctx: VariableContext, opts?: ResolveOptions): unknown;
+/**
+ * Check if a string contains any variable references
+ *
+ * @param str - String to check
+ * @returns True if string contains ${...} patterns
+ */
+declare function hasVariables(str: string): boolean;
+/**
+ * Extract all variable references from a string
+ *
+ * @param str - String to analyze
+ * @returns Array of {namespace, key} objects
+ */
+declare function extractVariables(str: string): Array<{
+    namespace: string;
+    key: string;
+}>;
+
+/**
+ * ResumePoint - Marker node for resume location
+ * Always returns SUCCESS, used purely as a findable marker for LLM-based resume
+ */
+
+interface ResumePointConfig {
+    id: string;
+}
+/**
+ * ResumePoint is a marker node that LLM agents can insert to indicate
+ * where execution should resume from. It always returns SUCCESS.
+ */
+declare class ResumePoint extends ActionNode {
+    readonly resumePointId: string;
+    constructor(config: ResumePointConfig);
+    executeTick(_context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * Custom error types for behavior tree execution
+ */
+/**
+ * Error for test configuration/authoring issues.
+ * These errors are NOT caught by Selector/Sequence - they propagate up
+ * to signal that the test case itself is broken.
+ *
+ * Examples:
+ * - Element reference not found in blackboard
+ * - Missing required adapter
+ * - Invalid tree structure (decorator without child)
+ * - Invalid attribute values (negative timeout)
+ *
+ * These differ from operational failures (element not visible, timeout exceeded)
+ * which should return NodeStatus.FAILURE and can be handled by Selector.
+ */
+declare class ConfigurationError extends Error {
+    readonly hint?: string | undefined;
+    readonly isConfigurationError = true;
+    constructor(message: string, hint?: string | undefined);
+}
+
+/**
+ * Tree definition schemas
+ * Validates the structure of tree definitions before node creation
+ */
+
+/**
+ * Tree definition type
+ * Matches the format expected by Registry.createTree()
+ */
+interface TreeDefinition {
+    type: string;
+    id?: string;
+    name?: string;
+    props?: Record<string, unknown>;
+    children?: TreeDefinition[];
+}
+declare const treeDefinitionSchema: z.ZodType<TreeDefinition>;
+/**
+ * Validate tree definition structure (without type-specific validation)
+ * Type-specific validation happens in Registry.create()
+ *
+ * @param definition - Tree definition to validate
+ * @returns Validated tree definition
+ * @throws ZodError if structure is invalid
+ *
+ * @example
+ * ```typescript
+ * const definition = validateTreeDefinition({
+ *   type: 'Sequence',
+ *   id: 'root',
+ *   children: [
+ *     { type: 'PrintAction', id: 'action1' }
+ *   ]
+ * });
+ * ```
+ */
+declare function validateTreeDefinition(definition: unknown): TreeDefinition;
+/**
+ * Validate decorator has exactly one child
+ *
+ * @param nodeType - Type of the decorator node
+ * @param children - Children array to validate
+ * @throws Error if child count is not exactly 1
+ */
+declare function validateDecoratorChildren(nodeType: string, children?: TreeDefinition[]): void;
+/**
+ * Validate composite has at least minimum children
+ *
+ * @param nodeType - Type of the composite node
+ * @param children - Children array to validate
+ * @param minChildren - Minimum required children (default: 0)
+ * @throws Error if child count is less than minimum
+ */
+declare function validateCompositeChildren(nodeType: string, children?: TreeDefinition[], minChildren?: number): void;
+/**
+ * Validate specific child count for composites with fixed requirements
+ *
+ * @param nodeType - Type of the composite node
+ * @param children - Children array to validate
+ * @param expectedCount - Exact number of expected children
+ * @throws Error if child count doesn't match expected
+ *
+ * @example
+ * ```typescript
+ * // While node requires exactly 2 children (condition, body)
+ * validateChildCount('While', children, 2);
+ * ```
+ */
+declare function validateChildCount(nodeType: string, children?: TreeDefinition[], expectedCount?: number): void;
+/**
+ * Validate child count range for composites with flexible requirements
+ *
+ * @param nodeType - Type of the composite node
+ * @param children - Children array to validate
+ * @param minChildren - Minimum required children
+ * @param maxChildren - Maximum allowed children
+ * @throws Error if child count is outside range
+ *
+ * @example
+ * ```typescript
+ * // Conditional node requires 2-3 children (condition, then, optional else)
+ * validateChildCountRange('Conditional', children, 2, 3);
+ * ```
+ */
+declare function validateChildCountRange(nodeType: string, children?: TreeDefinition[], minChildren?: number, maxChildren?: number): void;
+
+/**
+ * YAML parser and validation error types
+ */
+/**
+ * Base class for all YAML validation errors
+ */
+declare class ValidationError extends Error {
+    path?: string | undefined;
+    suggestion?: string | undefined;
+    constructor(message: string, path?: string | undefined, suggestion?: string | undefined);
+    /**
+     * Format error message with path and suggestion
+     */
+    format(): string;
+}
+/**
+ * YAML syntax error (Stage 1)
+ * Thrown when YAML is malformed
+ */
+declare class YamlSyntaxError extends ValidationError {
+    line?: number | undefined;
+    column?: number | undefined;
+    constructor(message: string, line?: number | undefined, column?: number | undefined, suggestion?: string);
+    format(): string;
+}
+/**
+ * Tree structure validation error (Stage 2)
+ * Thrown when tree definition structure is invalid
+ */
+declare class StructureValidationError extends ValidationError {
+    constructor(message: string, path?: string, suggestion?: string);
+}
+/**
+ * Node configuration validation error (Stage 3)
+ * Thrown when node-specific configuration is invalid
+ */
+declare class ConfigValidationError extends ValidationError {
+    nodeType: string;
+    constructor(message: string, nodeType: string, path?: string, suggestion?: string);
+    format(): string;
+}
+/**
+ * Semantic validation error (Stage 4)
+ * Thrown when semantic rules are violated (duplicate IDs, circular refs, etc.)
+ */
+declare class SemanticValidationError extends ValidationError {
+    constructor(message: string, path?: string, suggestion?: string);
+}
+/**
+ * Collect multiple validation errors
+ */
+declare class ValidationErrors extends Error {
+    errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+    /**
+     * Format all errors as a single message
+     */
+    format(): string;
+}
+
+/**
+ * YAML parser for behavior tree definitions
+ * Implements 4-stage validation pipeline
+ */
+
+/**
+ * Options for YAML loading and validation
+ */
+interface LoadOptions {
+    /**
+     * Enable validation (default: true)
+     */
+    validate?: boolean;
+    /**
+     * Fail on first error or collect all errors (default: true - fail fast)
+     */
+    failFast?: boolean;
+    /**
+     * Auto-generate IDs for nodes without IDs (default: true)
+     */
+    autoGenerateIds?: boolean;
+}
+/**
+ * Validation options for validateYaml()
+ */
+interface ValidationOptions {
+    /**
+     * Collect all errors instead of failing fast (default: false)
+     */
+    collectAllErrors?: boolean;
+    /**
+     * Check semantic rules like references and circular deps (default: true)
+     */
+    checkReferences?: boolean;
+}
+/**
+ * Validation result
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings?: string[];
+}
+/**
+ * Parse YAML string to TreeDefinition
+ * Stage 1: YAML Syntax Validation
+ *
+ * @param yamlString - YAML content to parse
+ * @returns Parsed tree definition object
+ * @throws YamlSyntaxError if YAML is malformed
+ */
+declare function parseYaml(yamlString: string): TreeDefinition;
+/**
+ * Load and create tree from YAML string
+ *
+ * @param yamlString - YAML content defining the tree
+ * @param registry - Registry with registered node types
+ * @param options - Loading options
+ * @returns Created tree node
+ * @throws ValidationError if validation fails
+ *
+ * @example
+ * ```typescript
+ * const yaml = `
+ * type: Sequence
+ * id: my-seq
+ * children:
+ *   - type: PrintAction
+ *     id: action1
+ * `;
+ *
+ * const tree = loadTreeFromYaml(yaml, registry);
+ * ```
+ */
+declare function loadTreeFromYaml(yamlString: string, registry: Registry, options?: LoadOptions): TreeNode;
+/**
+ * Validate YAML without creating tree
+ * Useful for editors and validators
+ *
+ * @param yamlString - YAML content to validate
+ * @param registry - Registry with registered node types
+ * @param options - Validation options
+ * @returns Validation result with errors
+ *
+ * @example
+ * ```typescript
+ * const result = validateYaml(yaml, registry);
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+declare function validateYaml(yamlString: string, registry: Registry, options?: ValidationOptions): ValidationResult;
+/**
+ * Convert TreeDefinition to YAML string
+ *
+ * @param definition - Tree definition to convert
+ * @returns YAML string representation
+ *
+ * @example
+ * ```typescript
+ * const definition = { type: 'Sequence', id: 'root', children: [] };
+ * const yamlString = toYaml(definition);
+ * ```
+ */
+declare function toYaml(definition: TreeDefinition): string;
+
+/**
+ * File system integration for YAML loading
+ */
+
+/**
+ * Load and create tree from YAML file
+ *
+ * @param filePath - Path to YAML file
+ * @param registry - Registry with registered node types
+ * @param options - Loading options
+ * @returns Created tree node
+ * @throws ValidationError if validation fails
+ * @throws Error if file cannot be read
+ *
+ * @example
+ * ```typescript
+ * const tree = await loadTreeFromFile('./workflows/checkout.yaml', registry);
+ * ```
+ */
+declare function loadTreeFromFile(filePath: string, registry: Registry, options?: LoadOptions): Promise<TreeNode>;
+
+/**
+ * Semantic validation (Stage 4)
+ * Validates semantic rules like ID uniqueness, circular references, etc.
+ */
+
+/**
+ * Semantic validator for tree definitions
+ * Validates cross-node rules that can't be expressed in schemas
+ */
+declare class SemanticValidator {
+    /**
+     * 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: TreeDefinition, registry: Registry): SemanticValidationError[];
+    /**
+     * Recursively validate a node and its children
+     */
+    private validateNode;
+}
+/**
+ * Singleton semantic validator instance
+ */
+declare const semanticValidator: SemanticValidator;
+
+/**
+ * Base Zod schemas for node configurations
+ * Foundation for all node-specific validation schemas
+ */
+
+/**
+ * Base schema for all node configurations
+ * Matches NodeConfiguration interface from types.ts
+ */
+declare const nodeConfigurationSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * Branded type for validated configurations
+ * Ensures runtime type matches compile-time type
+ */
+type ValidatedNodeConfiguration = z.infer<typeof nodeConfigurationSchema>;
+/**
+ * Helper to create node-specific configuration schemas
+ * Extends base schema with node-specific fields
+ *
+ * @param nodeType - Name of the node type for error messages
+ * @param fields - Node-specific field definitions
+ * @returns Extended Zod schema
+ *
+ * @example
+ * ```typescript
+ * const timeoutSchema = createNodeSchema('Timeout', {
+ *   timeoutMs: validations.positiveNumber('timeoutMs'),
+ * });
+ * ```
+ */
+declare function createNodeSchema<T extends z.ZodRawShape>(nodeType: string, fields: T): z.ZodObject<(("id" | "name") & keyof T extends never ? {
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+} & T : ({
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+} extends infer T_2 extends z.core.util.SomeObject ? { [K in keyof T_2 as K extends keyof T ? never : K]: T_2[K]; } : never) & { [K_1 in keyof T]: T[K_1]; }) extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.core.$loose>;
+/**
+ * Common validation helpers
+ * Reusable validators for standard patterns
+ */
+declare const validations: {
+    /**
+     * Positive number validator (> 0)
+     */
+    positiveNumber: (fieldName: string) => z.ZodNumber;
+    /**
+     * Non-negative number validator (>= 0)
+     */
+    nonNegativeNumber: (fieldName: string) => z.ZodNumber;
+    /**
+     * Positive integer validator (> 0, whole number)
+     */
+    positiveInteger: (fieldName: string) => z.ZodNumber;
+    /**
+     * Non-negative integer validator (>= 0, whole number)
+     */
+    nonNegativeInteger: (fieldName: string) => z.ZodNumber;
+    /**
+     * Blackboard key validator (non-empty string)
+     */
+    blackboardKey: z.ZodString;
+    /**
+     * Tree ID validator (non-empty string for SubTree references)
+     */
+    treeId: z.ZodString;
+    /**
+     * Duration in milliseconds validator (non-negative)
+     */
+    durationMs: (fieldName?: string) => z.ZodNumber;
+};
+/**
+ * Infer TypeScript type from schema
+ * Helper for type-safe configuration interfaces
+ */
+type InferSchema<T extends z.ZodSchema> = z.infer<T>;
+
+/**
+ * Validation utilities and error conversion
+ * Converts Zod validation errors to ConfigurationError
+ */
+
+/**
+ * Convert Zod validation errors to ConfigurationError
+ * Preserves detailed error context and provides helpful hints
+ *
+ * @param error - Zod validation error
+ * @param nodeType - Type of node being validated
+ * @param nodeId - Optional node ID for context
+ * @returns ConfigurationError with formatted message
+ */
+declare function zodErrorToConfigurationError(error: z.ZodError<unknown>, nodeType: string, nodeId?: string): ConfigurationError;
+/**
+ * Validate and parse configuration with ConfigurationError conversion
+ * Throws ConfigurationError if validation fails
+ *
+ * @param schema - Zod schema to validate against
+ * @param config - Configuration object to validate
+ * @param nodeType - Type of node being validated
+ * @param nodeId - Optional node ID for error context
+ * @returns Validated and parsed configuration
+ * @throws ConfigurationError if validation fails
+ *
+ * @example
+ * ```typescript
+ * const validatedConfig = validateConfiguration(
+ *   timeoutSchema,
+ *   { id: 'test', timeoutMs: 1000 },
+ *   'Timeout',
+ *   'test'
+ * );
+ * ```
+ */
+declare function validateConfiguration<T = unknown>(schema: z.ZodSchema<T>, config: unknown, nodeType: string, nodeId?: string): T;
+/**
+ * Safe validation that returns result instead of throwing
+ * Useful for user-facing tools that need graceful error handling
+ *
+ * @param schema - Zod schema to validate against
+ * @param config - Configuration object to validate
+ * @param nodeType - Type of node being validated (for error messages)
+ * @param nodeId - Optional node ID for error context
+ * @returns Success result with data or failure result with error
+ *
+ * @example
+ * ```typescript
+ * const result = safeValidateConfiguration(
+ *   timeoutSchema,
+ *   { id: 'test', timeoutMs: -100 },
+ *   'Timeout'
+ * );
+ *
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+declare function safeValidateConfiguration<T>(schema: z.ZodSchema<T>, config: unknown, nodeType: string, nodeId?: string): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: ConfigurationError;
+};
+
+/**
+ * Schema registry and validation exports
+ * Central registry mapping node types to their validation schemas
+ */
+
+/**
+ * Central registry mapping node types to their validation schemas
+ *
+ * Responsibilities:
+ * - Register Zod schemas for each node type
+ * - Provide schema lookup by node type
+ * - Validate configurations against registered schemas
+ * - Fallback to base schema for unregistered types
+ *
+ * Usage:
+ * ```typescript
+ * // Register a schema
+ * schemaRegistry.register('Timeout', timeoutConfigurationSchema);
+ *
+ * // Get a schema
+ * const schema = schemaRegistry.getSchema('Timeout');
+ *
+ * // Validate configuration
+ * const config = schemaRegistry.validate('Timeout', { id: 'test', timeoutMs: 1000 });
+ * ```
+ */
+declare class SchemaRegistry {
+    private schemas;
+    constructor();
+    /**
+     * Register all node schemas
+     * Called automatically on construction
+     */
+    private registerAllSchemas;
+    /**
+     * 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: string, schema: z.ZodSchema): void;
+    /**
+     * 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: string): z.ZodSchema;
+    /**
+     * 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: string): boolean;
+    /**
+     * Get all registered node types
+     *
+     * @returns Array of registered node type names
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * 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<T>(nodeType: string, config: unknown): T;
+    /**
+     * 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: string, config: unknown): {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: z.ZodError<unknown>;
+    };
+    /**
+     * Clear all registered schemas
+     * Useful for testing
+     */
+    clear(): void;
+}
+/**
+ * Global singleton schema registry instance
+ * Used by Registry class for validation
+ */
+declare const schemaRegistry: SchemaRegistry;
+
+/**
+ * Template Loader
+ * Load YAML template files from a directory and register them in the btree Registry.
+ * Templates can then be referenced by SubTree nodes using their template ID.
+ */
+
+/**
+ * Options for loading templates from a directory
+ */
+interface TemplateLoaderOptions {
+    /** Path to the templates directory */
+    templatesDir: string;
+    /** Optional prefix to add to all template IDs (e.g., "tpl:") */
+    idPrefix?: string;
+}
+/**
+ * Load all template YAML files from a directory and register them in the registry.
+ *
+ * Each YAML file becomes a registered BehaviorTree that can be referenced
+ * by SubTree nodes using the filename (without extension) as the tree ID.
+ *
+ * @param registry - The Registry instance to register templates in
+ * @param options - Configuration options
+ * @returns Array of template IDs that were loaded
+ *
+ * @example
+ * ```typescript
+ * const registry = new Registry();
+ * registerStandardNodes(registry);
+ *
+ * const loadedIds = await loadTemplatesFromDirectory(registry, {
+ *   templatesDir: './templates',
+ *   idPrefix: 'tpl:'
+ * });
+ *
+ * // Templates can now be used via SubTree:
+ * // type: SubTree
+ * //   props:
+ * //     treeId: "tpl:order-validation"
+ * ```
+ */
+declare function loadTemplatesFromDirectory(registry: Registry, options: TemplateLoaderOptions): Promise<string[]>;
+/**
+ * Load a single template file and register it in the registry.
+ *
+ * @param registry - The Registry instance to register the template in
+ * @param filePath - Path to the YAML template file
+ * @param templateId - Optional custom ID for the template (defaults to filename)
+ * @returns The template ID that was registered
+ *
+ * @example
+ * ```typescript
+ * const id = loadTemplate(registry, './templates/order-validation.yaml');
+ * // Template is now available as "order-validation"
+ *
+ * const customId = loadTemplate(registry, './special.yaml', 'my-custom-id');
+ * // Template is now available as "my-custom-id"
+ * ```
+ */
+declare function loadTemplate(registry: Registry, filePath: string, templateId?: string): string;
+/**
+ * Check if a template exists in the registry
+ */
+declare function hasTemplate(registry: Registry, templateId: string): boolean;
+/**
+ * Get all registered template IDs
+ */
+declare function getTemplateIds(registry: Registry): string[];
+
+/**
+ * Integration Action Node
+ * Execute third-party service actions via Active Pieces packages
+ *
+ * Features:
+ * - Variable resolution: ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+ * - Pluggable token provider for OAuth/API key authentication
+ * - Dynamic Active Pieces action execution
+ * - Result storage in blackboard
+ */
+
+/**
+ * Configuration for IntegrationAction node
+ */
+interface IntegrationActionConfig extends NodeConfiguration {
+    /** Provider name: 'google-sheets', 'slack', 'openai', etc. */
+    provider: string;
+    /** Action name from Active Pieces: 'append_row', 'send_message', etc. */
+    action: string;
+    /** Action inputs (supports ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}) */
+    inputs?: Record<string, unknown>;
+    /** Connection ID to use (optional, defaults to user's primary connection) */
+    connectionId?: string;
+    /** Whether to store the result in blackboard (default: true) */
+    storeResult?: boolean;
+    /** Custom blackboard key for result (default: ${nodeId}.result) */
+    resultKey?: string;
+}
+/**
+ * Extended context with token provider
+ */
+interface IntegrationContext extends TemporalContext {
+    /** Token provider function for fetching OAuth tokens */
+    tokenProvider?: TokenProvider;
+    /** Tenant ID for multi-tenant token lookup */
+    tenantId?: string;
+    /** User ID for user-scoped token lookup */
+    userId?: string;
+}
+/**
+ * Integration Action Node
+ *
+ * Executes actions on third-party services using Active Pieces packages.
+ * Requires a token provider to be set in context for authentication.
+ *
+ * Supports variable resolution:
+ * - ${input.key} - Workflow input parameters
+ * - ${bb.key} - Blackboard values
+ * - ${env.KEY} - Environment variables
+ * - ${param.key} - Test data parameters
+ *
+ * @example
+ * ```yaml
+ * type: IntegrationAction
+ * id: add-to-sheet
+ * props:
+ *   provider: google-sheets
+ *   action: append_row
+ *   inputs:
+ *     spreadsheetId: "${input.spreadsheetId}"
+ *     sheetName: "Orders"
+ *     values:
+ *       - "${input.orderId}"
+ *       - "${bb.customerName}"
+ *       - "${bb.total}"
+ * ```
+ */
+declare class IntegrationAction extends ActionNode {
+    private provider;
+    private action;
+    private inputs;
+    private connectionId?;
+    private storeResult;
+    private resultKey;
+    constructor(config: IntegrationActionConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Dual-mode execution:
+     * - Activity mode: Use context.activities (deterministic for Temporal)
+     * - Standalone mode: Inline executePieceAction (for testing)
+     */
+    private executeAction;
+    /**
+     * Resolve variable references in inputs
+     * Supports ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+     */
+    private resolveInputs;
+}
+/**
+ * Default token provider that reads from environment variables
+ * Useful for testing and simple deployments
+ *
+ * Looks for:
+ * - {PROVIDER}_ACCESS_TOKEN (e.g., GOOGLE_ACCESS_TOKEN)
+ * - {PROVIDER}_API_KEY (e.g., OPENAI_API_KEY)
+ */
+declare const envTokenProvider: TokenProvider;
+
+/**
+ * Piece Executor
+ * Dynamically executes Active Pieces actions
+ *
+ * Active Pieces is an open-source automation platform with 440+ connectors.
+ * This module wraps their npm packages for use in btree workflows.
+ *
+ * @see https://activepieces.com/docs
+ */
+
+/**
+ * Execute an Active Pieces action
+ *
+ * @param request - Action request with provider, action, inputs, and auth
+ * @returns The result from the Active Pieces action
+ *
+ * @example
+ * ```typescript
+ * const result = await executePieceAction({
+ *   provider: 'google-sheets',
+ *   action: 'append_row',
+ *   inputs: {
+ *     spreadsheetId: 'xxx',
+ *     sheetName: 'Sheet1',
+ *     values: ['A', 'B', 'C']
+ *   },
+ *   auth: { access_token: 'ya29.xxx' }
+ * });
+ * ```
+ */
+declare function executePieceAction(request: PieceActivityRequest): Promise<unknown>;
+/**
+ * List available actions for a provider
+ * Useful for UI builders and documentation
+ */
+declare function listPieceActions(provider: string): Promise<{
+    name: string;
+    displayName?: string;
+    description?: string;
+}[]>;
+/**
+ * Check if a piece is installed
+ */
+declare function isPieceInstalled(provider: string): Promise<boolean>;
+/**
+ * Clear the piece cache (useful for testing)
+ */
+declare function clearPieceCache(): void;
+
+/**
+ * PythonScript Node
+ *
+ * Executes Python code via a cross-language Temporal activity.
+ * This node requires the `executePythonScript` activity to be configured
+ * in the context - it does not support standalone/inline execution because
+ * Python execution requires a separate Python worker process.
+ *
+ * Features:
+ * - Access to blackboard state via `bb` dict in Python
+ * - Access to workflow input via `input` dict in Python
+ * - Modifications to `bb` dict are merged back to blackboard
+ * - Configurable timeout and environment variables
+ */
+
+/**
+ * Configuration for PythonScript node
+ */
+interface PythonScriptConfig extends NodeConfiguration {
+    /** Python code to execute */
+    code: string;
+    /** Required packages (for documentation/validation) */
+    packages?: string[];
+    /** Execution timeout in ms (default: 60000) */
+    timeout?: number;
+    /** Allowed environment variables to pass to Python */
+    allowedEnvVars?: string[];
+}
+/**
+ * PythonScript Node
+ *
+ * Executes Python code via a cross-language Temporal activity.
+ * The Python code has access to:
+ * - `bb`: dict - Blackboard state (read/write)
+ * - `input`: dict - Workflow input (read-only)
+ *
+ * @example YAML
+ * ```yaml
+ * type: PythonScript
+ * id: transform-data
+ * props:
+ *   code: |
+ *     import pandas as pd
+ *     df = pd.DataFrame(bb['orders'])
+ *     bb['total'] = df['amount'].sum()
+ *     bb['count'] = len(df)
+ *   packages:
+ *     - pandas
+ *   timeout: 30000
+ * ```
+ */
+declare class PythonScript extends ActionNode {
+    private code;
+    private packages;
+    private timeout;
+    private allowedEnvVars;
+    constructor(config: PythonScriptConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Resolve variable references in the Python code
+     * Allows dynamic code templates like:
+     * code: "bb['output_key'] = '${input.prefix}_result'"
+     */
+    private resolveCode;
+    /**
+     * Get allowed environment variables to pass to Python
+     */
+    private getAllowedEnv;
+}
+
+/**
+ * ParseFile Node
+ *
+ * Parses CSV/Excel files into structured data via a Temporal activity.
+ * This node requires the `parseFile` activity to be configured in the context -
+ * it does not support standalone/inline execution because file I/O requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - CSV and Excel (xlsx, xls) file format support
+ * - Column mapping/renaming
+ * - Parse options (skip rows, trim, date parsing)
+ * - Result stored in blackboard
+ */
+
+/**
+ * Configuration for ParseFile node
+ */
+interface ParseFileConfig extends NodeConfiguration {
+    /** Path to file (supports ${input.file}, ${bb.filePath}) */
+    file: string;
+    /** File format */
+    format?: "csv" | "xlsx" | "xls" | "auto";
+    /** Sheet name for Excel (default: first sheet) */
+    sheetName?: string;
+    /** Column mapping { "Original Name": "normalizedName" } */
+    columnMapping?: Record<string, string>;
+    /** Output key on blackboard */
+    outputKey: string;
+    /** Parse options */
+    options?: ParseFileRequest["options"];
+}
+/**
+ * ParseFile Node
+ *
+ * Parses CSV/Excel files into structured data and stores the result in blackboard.
+ * Requires the `parseFile` activity to be configured.
+ *
+ * @example YAML
+ * ```yaml
+ * type: ParseFile
+ * id: parse-orders
+ * props:
+ *   file: "${input.orderFile}"
+ *   format: csv
+ *   columnMapping:
+ *     "Order ID": "orderId"
+ *     "Customer Name": "customerName"
+ *     "Amount": "amount"
+ *   outputKey: "orders"
+ *   options:
+ *     skipRows: 1
+ *     trim: true
+ * ```
+ */
+declare class ParseFile extends ActionNode {
+    private file;
+    private format;
+    private sheetName?;
+    private columnMapping?;
+    private outputKey;
+    private options?;
+    constructor(config: ParseFileConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * GenerateFile Node
+ *
+ * Generates CSV/Excel/JSON files from data via a Temporal activity.
+ * This node requires the `generateFile` activity to be configured in the context -
+ * it does not support standalone/inline execution because file I/O requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - CSV, Excel (xlsx), and JSON output formats
+ * - Column definitions with header names and widths
+ * - Temporary or persistent storage
+ * - Result metadata stored in blackboard (filename, path, URL)
+ */
+
+/**
+ * Configuration for GenerateFile node
+ */
+interface GenerateFileConfig extends NodeConfiguration {
+    /** Output format */
+    format: "csv" | "xlsx" | "json";
+    /** Data source (blackboard key) */
+    dataKey: string;
+    /** Column definitions */
+    columns?: Array<{
+        header: string;
+        key: string;
+        width?: number;
+    }>;
+    /** Output filename template (supports ${input.x}, ${bb.x}) */
+    filename: string;
+    /** Storage type */
+    storage: "temp" | "persistent";
+    /** Output key for file metadata (path, url, size) */
+    outputKey: string;
+}
+/**
+ * GenerateFile Node
+ *
+ * Generates a file from data in the blackboard and stores file metadata.
+ * Requires the `generateFile` activity to be configured.
+ *
+ * @example YAML
+ * ```yaml
+ * type: GenerateFile
+ * id: export-report
+ * props:
+ *   format: csv
+ *   dataKey: "processedOrders"
+ *   columns:
+ *     - header: "Order ID"
+ *       key: "orderId"
+ *     - header: "Customer"
+ *       key: "customerName"
+ *     - header: "Total"
+ *       key: "amount"
+ *       width: 15
+ *   filename: "orders-${bb.timestamp}.csv"
+ *   storage: persistent
+ *   outputKey: "exportedFile"
+ * ```
+ */
+declare class GenerateFile extends ActionNode {
+    private format;
+    private dataKey;
+    private columns?;
+    private filename;
+    private storage;
+    private outputKey;
+    constructor(config: GenerateFileConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * HttpRequest Node
+ *
+ * Makes HTTP requests via a Temporal activity.
+ * This node requires the `fetchUrl` activity to be configured in the context -
+ * it does not support standalone/inline execution because HTTP I/O requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - Support for GET, POST, PUT, DELETE, PATCH methods
+ * - Variable resolution in URL, headers, and body
+ * - Configurable response parsing (JSON/text/binary)
+ * - Retry with exponential backoff support
+ * - Timeout configuration
+ * - Result stored in blackboard
+ */
+
+/**
+ * Configuration for HttpRequest node
+ */
+interface HttpRequestConfig extends NodeConfiguration {
+    /** URL to request (supports ${input.x}, ${bb.x}) */
+    url: string;
+    /** HTTP method (default: GET) */
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** Request headers (supports variable resolution) */
+    headers?: Record<string, string>;
+    /** Request body (supports variable resolution) */
+    body?: unknown;
+    /** Expected response type for parsing */
+    responseType?: "json" | "text" | "binary";
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: {
+        maxAttempts: number;
+        backoffMs: number;
+    };
+    /** Output key on blackboard for response */
+    outputKey: string;
+}
+/**
+ * HttpRequest Node
+ *
+ * Makes HTTP requests via a Temporal activity and stores the response in blackboard.
+ * Requires the `fetchUrl` activity to be configured.
+ *
+ * @example YAML
+ * ```yaml
+ * type: HttpRequest
+ * id: fetch-user
+ * props:
+ *   url: "https://api.example.com/users/${input.userId}"
+ *   method: GET
+ *   headers:
+ *     Authorization: "Bearer ${bb.accessToken}"
+ *   timeout: 5000
+ *   responseType: json
+ *   outputKey: "userData"
+ * ```
+ *
+ * @example YAML with POST
+ * ```yaml
+ * type: HttpRequest
+ * id: create-order
+ * props:
+ *   url: "https://api.example.com/orders"
+ *   method: POST
+ *   headers:
+ *     Content-Type: "application/json"
+ *     Authorization: "Bearer ${bb.token}"
+ *   body:
+ *     customerId: "${input.customerId}"
+ *     items: "${bb.cartItems}"
+ *   timeout: 10000
+ *   retry:
+ *     maxAttempts: 3
+ *     backoffMs: 1000
+ *   outputKey: "orderResponse"
+ * ```
+ */
+declare class HttpRequest extends ActionNode {
+    private url;
+    private method;
+    private headers?;
+    private body?;
+    private responseType;
+    private timeout?;
+    private retry?;
+    private outputKey;
+    constructor(config: HttpRequestConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+    /**
+     * Sleep for the specified duration
+     */
+    private sleep;
+}
+
+/**
+ * CodeExecution Node
+ *
+ * Executes JavaScript or Python code in a secure sandboxed environment
+ * via Microsandbox (libkrun microVM). This node replaces the inline Script
+ * node for production use where untrusted/AI-generated code needs isolation.
+ *
+ * Features:
+ * - Support for JavaScript and Python
+ * - Full VM isolation (no network, no filesystem, no cloud credentials)
+ * - DataStore integration for large payloads
+ * - getBB/setBB helpers for blackboard access
+ * - getInput helper for workflow input access
+ * - Configurable timeout
+ * - Python package installation support
+ *
+ * Security:
+ * - Code runs in Microsandbox microVM
+ * - No cloud credentials exposed to sandbox
+ * - Activity fetches data from DataStore, not the sandbox
+ * - Only JSON data crosses the sandbox boundary
+ */
+
+/**
+ * Configuration for CodeExecution node
+ */
+interface CodeExecutionConfig extends NodeConfiguration {
+    /** Code to execute */
+    code: string;
+    /** Programming language: 'javascript' or 'python' */
+    language: "javascript" | "python";
+    /** Execution timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Python packages to install before execution */
+    packages?: string[];
+}
+/**
+ * CodeExecution Node
+ *
+ * Executes code in a sandboxed environment via Temporal activity.
+ * Requires the `executeCode` activity to be configured.
+ *
+ * @example YAML (JavaScript)
+ * ```yaml
+ * type: CodeExecution
+ * id: transform-data
+ * props:
+ *   language: javascript
+ *   code: |
+ *     const users = getBB('apiUsers');
+ *     const processed = users.map(u => ({
+ *       id: u.id,
+ *       name: u.name.toUpperCase()
+ *     }));
+ *     setBB('processedUsers', processed);
+ *   timeout: 30000
+ * ```
+ *
+ * @example YAML (Python)
+ * ```yaml
+ * type: CodeExecution
+ * id: analyze-data
+ * props:
+ *   language: python
+ *   packages:
+ *     - pandas
+ *   code: |
+ *     import pandas as pd
+ *
+ *     users = getBB('apiUsers')
+ *     df = pd.DataFrame(users)
+ *
+ *     setBB('userCount', len(df))
+ *     setBB('domains', df['email'].str.split('@').str[1].unique().tolist())
+ *   timeout: 60000
+ * ```
+ *
+ * Available functions in sandbox:
+ * - getBB(key): Get value from blackboard
+ * - setBB(key, value): Set value on blackboard
+ * - getInput(key): Get value from workflow input (read-only)
+ */
+declare class CodeExecution extends ActionNode {
+    private code;
+    private language;
+    private timeout;
+    private packages;
+    constructor(config: CodeExecutionConfig);
+    protected executeTick(context: TemporalContext): Promise<NodeStatus>;
+}
+
+/**
+ * Observability types for workflow execution tracking
+ * Used by ExecutionTracker and Analyzer Agent
+ */
+/**
+ * Overall execution progress summary
+ */
+interface ExecutionProgress {
+    /** Total number of nodes in the tree */
+    totalNodes: number;
+    /** Number of nodes that completed successfully */
+    completedNodes: number;
+    /** Number of nodes that failed */
+    failedNodes: number;
+    /** Currently executing node ID (null if not running) */
+    currentNodeId: string | null;
+    /** Type of currently executing node */
+    currentNodeType: string | null;
+    /** Ordered list of node IDs that have been executed */
+    pathTaken: string[];
+    /** Timestamp when execution started */
+    startedAt: number;
+    /** Timestamp of last activity */
+    lastActivityAt: number;
+    /** Overall status */
+    status: "running" | "completed" | "failed";
+}
+/**
+ * State of a single node during execution
+ */
+interface NodeState {
+    /** Node ID */
+    id: string;
+    /** Node type (e.g., "Sequence", "CodeExecution") */
+    type: string;
+    /** Node name */
+    name: string;
+    /** Tree path (e.g., "/0/1/2") */
+    path: string;
+    /** Current status */
+    status: "idle" | "running" | "success" | "failure";
+    /** Last error message if failed */
+    lastError?: string;
+    /** Number of times this node has been ticked */
+    tickCount: number;
+    /** Timestamp of last tick */
+    lastTickAt?: number;
+    /** Duration of last tick in ms */
+    durationMs?: number;
+}
+/**
+ * Structured error with rich context for debugging
+ */
+interface StructuredError {
+    /** Node ID where error occurred */
+    nodeId: string;
+    /** Node type */
+    nodeType: string;
+    /** Node name */
+    nodeName: string;
+    /** Tree path (e.g., "/0/1/2") */
+    nodePath: string;
+    /** Error message */
+    message: string;
+    /** Error stack trace (if available) */
+    stack?: string;
+    /** Timestamp when error occurred */
+    timestamp: number;
+    /** Blackboard snapshot at time of error */
+    blackboardSnapshot: Record<string, unknown>;
+    /** Input that was passed to the node */
+    nodeInput?: unknown;
+    /** Whether this error is potentially recoverable with retry */
+    recoverable: boolean;
+    /** Suggested fix based on error analysis */
+    suggestedFix?: string;
+}
+/**
+ * Entry in the execution timeline
+ */
+interface TimelineEntry {
+    /** Node ID */
+    nodeId: string;
+    /** Node type */
+    nodeType: string;
+    /** Node name */
+    nodeName: string;
+    /** Tree path */
+    nodePath: string;
+    /** Event type */
+    event: "start" | "end" | "error";
+    /** Timestamp */
+    timestamp: number;
+    /** Final status (for end events) */
+    status?: string;
+    /** Duration in ms (for end events) */
+    durationMs?: number;
+    /** Error details (for error events) */
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Extended NodeEvent with path and blackboard context
+ * Used internally by ExecutionTracker
+ */
+interface ObservableNodeEvent {
+    type: string;
+    nodeId: string;
+    nodeName: string;
+    nodeType: string;
+    nodePath?: string;
+    timestamp: number;
+    data?: {
+        status?: string;
+        durationMs?: number;
+        error?: {
+            message: string;
+            stack?: string;
+            input?: unknown;
+        };
+        blackboard?: Record<string, unknown>;
+    };
+}
+
+/**
+ * ExecutionTracker - Aggregates node events into queryable state
+ * Used by workflow query handlers to expose real-time execution progress
+ */
+
+/**
+ * Tracks execution state by subscribing to node events
+ * Provides query methods for progress, node states, errors, and timeline
+ */
+declare class ExecutionTracker {
+    private nodeStates;
+    private timeline;
+    private errors;
+    private pathTaken;
+    private startedAt;
+    private currentNodeId;
+    private totalNodes;
+    private finished;
+    constructor(totalNodes: number);
+    /**
+     * Process a node event and update internal state
+     * Called by NodeEventEmitter subscription
+     */
+    onNodeEvent(event: ObservableNodeEvent): void;
+    private handleTickStart;
+    private handleTickEnd;
+    private handleError;
+    /**
+     * Mark execution as finished
+     */
+    markFinished(): void;
+    /**
+     * Get overall execution progress
+     */
+    getProgress(): ExecutionProgress;
+    /**
+     * Get all node states
+     */
+    getNodeStates(): Map<string, NodeState>;
+    /**
+     * Get node states as a plain object (for JSON serialization)
+     */
+    getNodeStatesObject(): Record<string, NodeState>;
+    /**
+     * Get all errors that occurred during execution
+     */
+    getErrors(): StructuredError[];
+    /**
+     * Get the full execution timeline
+     */
+    getTimeline(): TimelineEntry[];
+    /**
+     * Get state for a specific node
+     */
+    getNodeState(nodeId: string): NodeState | undefined;
+    private getOrCreateState;
+    /**
+     * Check if an error type is potentially recoverable with retry
+     */
+    private isRecoverable;
+    /**
+     * Suggest a fix based on error patterns
+     */
+    private suggestFix;
+}
+
+/**
+ * Workflow Sink types for exporting events from Temporal workflows
+ * Sinks allow workflows to export data without affecting determinism
+ */
+
+/**
+ * Observability sinks for workflow event export
+ *
+ * Usage in workflow:
+ * ```typescript
+ * import { proxySinks } from '@temporalio/workflow';
+ * import type { ObservabilitySinks } from '@wayfarer-ai/btree-workflows';
+ *
+ * const { events } = proxySinks<ObservabilitySinks>();
+ * events.push(nodeEvent);  // Fire-and-forget
+ * ```
+ *
+ * The sink handler runs in the worker (outside the deterministic sandbox)
+ * and can safely perform I/O like database writes or triggering agents.
+ */
+interface ObservabilitySinks extends Sinks {
+    events: {
+        /**
+         * Push a node event to external observers
+         * This is fire-and-forget - workflow execution continues immediately
+         */
+        push(event: ObservableNodeEvent): void;
+    };
+}
+/**
+ * Configuration for creating sink handlers
+ */
+interface SinkHandlerConfig {
+    /**
+     * Called when a node event is received
+     * Can be async - workflow doesn't wait for completion
+     */
+    onEvent?: (workflowId: string, runId: string, event: ObservableNodeEvent) => void | Promise<void>;
+    /**
+     * Called specifically for ERROR events
+     * Use this to trigger analyzer agent or alerting
+     */
+    onError?: (workflowId: string, runId: string, event: ObservableNodeEvent) => void | Promise<void>;
+    /**
+     * Whether to log events to console (default: false)
+     */
+    logEvents?: boolean;
+}
+/**
+ * Sink function signature for InjectedSinks
+ */
+interface SinkFunction<T extends (...args: any[]) => any> {
+    fn(info: {
+        workflowId: string;
+        runId: string;
+    }, ...args: Parameters<T>): ReturnType<T>;
+    callDuringReplay: boolean;
+}
+/**
+ * Type for InjectedSinks<ObservabilitySinks>
+ */
+type InjectedObservabilitySinks = {
+    events: {
+        push: SinkFunction<(event: ObservableNodeEvent) => void>;
+    };
+};
+/**
+ * Create sink handler functions for InjectedSinks
+ *
+ * Usage in worker:
+ * ```typescript
+ * import { createObservabilitySinkHandler } from '@wayfarer-ai/btree-workflows';
+ *
+ * const sinks = createObservabilitySinkHandler({
+ *   onEvent: (workflowId, runId, event) => {
+ *     // Store event to database
+ *   },
+ *   onError: (workflowId, runId, event) => {
+ *     // Trigger analyzer agent
+ *   },
+ * });
+ *
+ * const worker = await Worker.create({ sinks, ... });
+ * ```
+ */
+declare function createObservabilitySinkHandler(config?: SinkHandlerConfig): InjectedObservabilitySinks;
+
+export { ActionNode, AlwaysCondition, BaseNode, BehaviorTree, type BtreeActivities, CheckCondition, CodeExecution, type CodeExecutionConfig, type CodeExecutionRequest, type CodeExecutionResult, CompositeNode, ConditionNode, Conditional, ConfigValidationError, ConfigurationError, CounterAction, type DataRef$1 as DataRef, type DataStore, DecoratorNode, Delay, type DeleteFileRequest, type DeleteFileResult, type DownloadFileRequest, type DownloadFileResult, type ExecutionProgress, ExecutionTracker, FailureNode, Fallback, type FileExistsRequest, type FileExistsResult, ForEach, ForceFailure, ForceSuccess, GenerateFile, type GenerateFileConfig, type GenerateFileRequest, type GenerateFileResult, HttpRequest, type HttpRequestActivity, type HttpRequestConfig, type HttpResponseActivity, type IScopedBlackboard, type ITreeRegistry, type InferSchema, type InjectedObservabilitySinks, IntegrationAction, type IntegrationActionConfig, type IntegrationContext, Invert, KeepRunningUntilFailure, type LoadOptions, type LogEventData, LogMessage, type LogMessageConfig, MemoryDataStore, MemorySequence, MockAction, type NodeConfiguration, type NodeConstructor, type NodeEvent, type NodeEventCallback, NodeEventEmitter, NodeEventType, type NodeMetadata, type NodeState, NodeStatus, type ObservabilitySinks, type ObservableNodeEvent, Parallel, type ParallelStrategy, ParseFile, type ParseFileConfig, type ParseFileRequest, type ParseFileResult, type ParsedPath, type PieceActivityRequest as PieceActionRequest, type PieceActivityRequest, type PieceAuth, type PortDefinition, Precondition, PrintAction, type PutOptions, PythonScript, type PythonScriptConfig, type PythonScriptRequest, type PythonScriptResult, ReactiveSequence, Recovery, RegexExtract, type RegexExtractConfig, Registry, Repeat, type ResolveOptions, ResumePoint, type ResumePointConfig, RunOnce, RunningNode, SchemaRegistry, ScopedBlackboard, Selector, SemanticValidationError, Sequence, SequenceWithMemory, type SinkHandlerConfig, SoftAssert, StructureValidationError, type StructuredError, SubTree, SuccessNode, type TemplateLoaderOptions, type TemporalContext, type TickContext, type TimelineEntry, Timeout, type TokenProvider, type TreeDefinition, type TreeNode, type UploadFileRequest, type UploadFileResult, type ValidatedNodeConfiguration, ValidationError, ValidationErrors, type ValidationOptions, type ValidationResult, type VariableContext, WaitAction, While, type WorkflowArgs, type WorkflowResult, 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 };