@q1k-oss/btree-workflows 0.0.1

package/src/events.test.ts

@@ -0,0 +1,347 @@
+/**
+ * Tests for event system
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "./blackboard.js";
+import { Sequence } from "./composites/sequence.js";
+import { type NodeEvent, NodeEventEmitter, NodeEventType } from "./events.js";
+import { RunningNode, SuccessNode } from "./test-nodes.js";
+import { type TemporalContext, NodeStatus } from "./types.js";
+
+describe("NodeEventEmitter", () => {
+  let emitter: NodeEventEmitter;
+
+  beforeEach(() => {
+    emitter = new NodeEventEmitter();
+  });
+
+  describe("Basic Functionality", () => {
+    it("should emit events to registered listeners", () => {
+      const events: NodeEvent[] = [];
+
+      emitter.on(NodeEventType.TICK_START, (event) => {
+        events.push(event);
+      });
+
+      emitter.emit({
+        type: NodeEventType.TICK_START,
+        nodeId: "test",
+        nodeName: "Test",
+        nodeType: "TestNode",
+        timestamp: Date.now(),
+      });
+
+      expect(events.length).toBe(1);
+      expect(events[0]?.type).toBe(NodeEventType.TICK_START);
+    });
+
+    it("should support multiple listeners for same event type", () => {
+      let count1 = 0;
+      let count2 = 0;
+
+      emitter.on(NodeEventType.TICK_START, () => count1++);
+      emitter.on(NodeEventType.TICK_START, () => count2++);
+
+      emitter.emit({
+        type: NodeEventType.TICK_START,
+        nodeId: "test",
+        nodeName: "Test",
+        nodeType: "TestNode",
+        timestamp: Date.now(),
+      });
+
+      expect(count1).toBe(1);
+      expect(count2).toBe(1);
+    });
+
+    it("should support onAll for listening to all events", () => {
+      const events: NodeEvent[] = [];
+
+      emitter.onAll((event) => events.push(event));
+
+      emitter.emit({
+        type: NodeEventType.TICK_START,
+        nodeId: "test",
+        nodeName: "Test",
+        nodeType: "TestNode",
+        timestamp: Date.now(),
+      });
+
+      emitter.emit({
+        type: NodeEventType.TICK_END,
+        nodeId: "test",
+        nodeName: "Test",
+        nodeType: "TestNode",
+        timestamp: Date.now(),
+        data: { status: NodeStatus.SUCCESS },
+      });
+
+      expect(events.length).toBe(2);
+      expect(events[0]?.type).toBe(NodeEventType.TICK_START);
+      expect(events[1]?.type).toBe(NodeEventType.TICK_END);
+    });
+
+    it("should remove listeners with off()", () => {
+      let count = 0;
+      const callback = () => count++;
+
+      emitter.on(NodeEventType.TICK_START, callback);
+
+      emitter.emit({
+        type: NodeEventType.TICK_START,
+        nodeId: "test",
+        nodeName: "Test",
+        nodeType: "TestNode",
+        timestamp: Date.now(),
+      });
+
+      expect(count).toBe(1);
+
+      emitter.off(NodeEventType.TICK_START, callback);
+
+      emitter.emit({
+        type: NodeEventType.TICK_START,
+        nodeId: "test",
+        nodeName: "Test",
+        nodeType: "TestNode",
+        timestamp: Date.now(),
+      });
+
+      expect(count).toBe(1); // Should not increment
+    });
+
+    it("should clear all listeners", () => {
+      let count = 0;
+
+      emitter.on(NodeEventType.TICK_START, () => count++);
+      emitter.onAll(() => count++);
+
+      emitter.clear();
+
+      emitter.emit({
+        type: NodeEventType.TICK_START,
+        nodeId: "test",
+        nodeName: "Test",
+        nodeType: "TestNode",
+        timestamp: Date.now(),
+      });
+
+      expect(count).toBe(0);
+    });
+
+    it("should handle errors in callbacks gracefully", () => {
+      const events: NodeEvent[] = [];
+
+      // This callback throws an error
+      emitter.on(NodeEventType.TICK_START, () => {
+        throw new Error("Test error");
+      });
+
+      // This callback should still execute
+      emitter.on(NodeEventType.TICK_START, (event) => {
+        events.push(event);
+      });
+
+      // Should not throw
+      expect(() => {
+        emitter.emit({
+          type: NodeEventType.TICK_START,
+          nodeId: "test",
+          nodeName: "Test",
+          nodeType: "TestNode",
+          timestamp: Date.now(),
+        });
+      }).not.toThrow();
+
+      // Second callback should have executed
+      expect(events.length).toBe(1);
+    });
+  });
+
+  describe("Listener Counting", () => {
+    it("should report correct listener counts", () => {
+      expect(emitter.listenerCount(NodeEventType.TICK_START)).toBe(0);
+      expect(emitter.allListenerCount()).toBe(0);
+      expect(emitter.hasListeners()).toBe(false);
+
+      emitter.on(NodeEventType.TICK_START, () => {});
+      emitter.on(NodeEventType.TICK_START, () => {});
+      emitter.onAll(() => {});
+
+      expect(emitter.listenerCount(NodeEventType.TICK_START)).toBe(2);
+      expect(emitter.allListenerCount()).toBe(1);
+      expect(emitter.hasListeners()).toBe(true);
+    });
+  });
+});
+
+describe("Event Integration with Nodes", () => {
+  let blackboard: ScopedBlackboard;
+  let emitter: NodeEventEmitter;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    emitter = new NodeEventEmitter();
+  });
+
+  describe("TICK Events", () => {
+    it("should emit TICK_START and TICK_END for successful execution", async () => {
+      const events: NodeEvent[] = [];
+      emitter.onAll((event) => events.push(event));
+
+      const node = new SuccessNode({ id: "success" });
+      const context: TemporalContext = {
+        blackboard,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        eventEmitter: emitter,
+      };
+      await node.tick(context);
+
+      expect(events.length).toBe(2);
+      expect(events[0]?.type).toBe(NodeEventType.TICK_START);
+      expect(events[0]?.nodeId).toBe("success");
+      expect(events[1]?.type).toBe(NodeEventType.TICK_END);
+      expect(events[1]?.data?.status).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should emit events for all nodes in a tree", async () => {
+      const events: NodeEvent[] = [];
+      emitter.onAll((event) => events.push(event));
+
+      const sequence = new Sequence({ id: "seq" });
+      sequence.addChildren([
+        new SuccessNode({ id: "child1" }),
+        new SuccessNode({ id: "child2" }),
+      ]);
+
+      const context: TemporalContext = {
+        blackboard,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        eventEmitter: emitter,
+      };
+      await sequence.tick(context);
+
+      // Sequence starts, child1 starts/ends, child2 starts/ends, sequence ends
+      const nodeIds = events.map((e) => e.nodeId);
+      expect(nodeIds).toContain("seq");
+      expect(nodeIds).toContain("child1");
+      expect(nodeIds).toContain("child2");
+    });
+  });
+
+  describe("ERROR Events", () => {
+    it("should emit ERROR event when node throws", async () => {
+      const events: NodeEvent[] = [];
+      emitter.on(NodeEventType.ERROR, (event) => events.push(event));
+
+      class ThrowingNode extends SuccessNode {
+        async executeTick(_context: TemporalContext) {
+          throw new Error("Test error");
+        }
+      }
+
+      const node = new ThrowingNode({ id: "throwing" });
+      const context: TemporalContext = {
+        blackboard,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        eventEmitter: emitter,
+      };
+
+      // Errors are converted to FAILURE status
+      const status = await node.tick(context);
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toBe("Test error");
+
+      // ERROR events are emitted for thrown errors
+      expect(events.length).toBe(1);
+      expect(events[0].type).toBe(NodeEventType.ERROR);
+      expect(events[0].nodeId).toBe("throwing");
+      expect(events[0].data).toEqual({ error: "Test error" });
+    });
+  });
+
+  describe("HALT Events", () => {
+    it("should emit HALT event when node is halted", () => {
+      const events: NodeEvent[] = [];
+      emitter.on(NodeEventType.HALT, (event) => events.push(event));
+
+      const node = new RunningNode({ id: "running" });
+      // Store emitter reference
+      node._eventEmitter = emitter;
+      node._status = NodeStatus.RUNNING;
+
+      node.halt();
+
+      expect(events.length).toBe(1);
+      expect(events[0]?.type).toBe(NodeEventType.HALT);
+      expect(events[0]?.nodeId).toBe("running");
+    });
+  });
+
+  describe("RESET Events", () => {
+    it("should emit RESET event when node is reset", () => {
+      const events: NodeEvent[] = [];
+      emitter.on(NodeEventType.RESET, (event) => events.push(event));
+
+      const node = new SuccessNode({ id: "node" });
+      // Store emitter reference
+      node._eventEmitter = emitter;
+
+      node.reset();
+
+      expect(events.length).toBe(1);
+      expect(events[0]?.type).toBe(NodeEventType.RESET);
+      expect(events[0]?.nodeId).toBe("node");
+    });
+  });
+});
+
+describe("Event Data Validation", () => {
+  it("should include all required fields in events", async () => {
+    const events: NodeEvent[] = [];
+    const emitter = new NodeEventEmitter();
+    emitter.onAll((event) => events.push(event));
+
+    const node = new SuccessNode({ id: "test", name: "TestNode" });
+    const context: TemporalContext = {
+      blackboard: new ScopedBlackboard("root"),
+      timestamp: Date.now(),
+      deltaTime: 0,
+      eventEmitter: emitter,
+    };
+    await node.tick(context);
+
+    for (const event of events) {
+      expect(event.type).toBeDefined();
+      expect(event.nodeId).toBeDefined();
+      expect(event.nodeName).toBeDefined();
+      expect(event.nodeType).toBeDefined();
+      expect(event.timestamp).toBeGreaterThan(0);
+    }
+  });
+
+  it("should include status in TICK_END data", async () => {
+    const emitter = new NodeEventEmitter();
+    let tickEndEvent: NodeEvent | undefined;
+
+    emitter.on(NodeEventType.TICK_END, (event) => {
+      tickEndEvent = event;
+    });
+
+    const node = new SuccessNode({ id: "test" });
+    const context: TemporalContext = {
+      blackboard: new ScopedBlackboard("root"),
+      timestamp: Date.now(),
+      deltaTime: 0,
+      eventEmitter: emitter,
+    };
+    await node.tick(context);
+
+    expect(tickEndEvent).toBeDefined();
+    expect(tickEndEvent?.data?.status).toBe(NodeStatus.SUCCESS);
+  });
+});

package/src/events.ts

@@ -0,0 +1,183 @@
+/**
+ * Event system for observing behavior tree execution
+ * Enables external systems (debuggers, monitors, agents) to track execution in real-time
+ */
+
+// Effect-TS removed in Phase 1 - toStream() method commented out
+
+/**
+ * Types of events emitted by nodes during execution
+ */
+export 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
+ */
+export interface LogEventData {
+  level: "info" | "warn" | "error" | "debug";
+  message: string;
+}
+
+/**
+ * Event emitted by a node during execution
+ */
+export 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
+ */
+export type NodeEventCallback<TData> = (event: NodeEvent<TData>) => void;
+
+/**
+ * Event emitter for behavior tree nodes
+ * Supports subscribing to specific event types and emitting events
+ */
+export class NodeEventEmitter {
+  private listeners: Map<NodeEventType, Set<NodeEventCallback<unknown>>> =
+    new Map();
+  private allListeners: Set<NodeEventCallback<unknown>> = new Set();
+
+  /**
+   * Subscribe to a specific event type
+   * @param type - The event type to listen for
+   * @param callback - Function to call when event occurs
+   */
+  on<TData>(type: NodeEventType, callback: NodeEventCallback<TData>): void {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, new Set());
+    }
+    this.listeners.get(type)?.add(callback as NodeEventCallback<unknown>);
+  }
+
+  /**
+   * Subscribe to all event types
+   * @param callback - Function to call for any event
+   */
+  onAll<TData>(callback: NodeEventCallback<TData>): void {
+    this.allListeners.add(callback as NodeEventCallback<unknown>);
+  }
+
+  /**
+   * 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 {
+    this.listeners.get(type)?.delete(callback as NodeEventCallback<unknown>);
+  }
+
+  /**
+   * Unsubscribe from all events
+   * @param callback - The callback to remove
+   */
+  offAll<TData>(callback: NodeEventCallback<TData>): void {
+    this.allListeners.delete(callback as NodeEventCallback<unknown>);
+  }
+
+  /**
+   * 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 {
+    // Emit to type-specific listeners
+    const typeListeners = this.listeners.get(event.type);
+    if (typeListeners) {
+      for (const callback of typeListeners) {
+        try {
+          callback(event as NodeEvent<unknown>);
+        } catch (error) {
+          console.error(`Error in event callback for ${event.type}:`, error);
+        }
+      }
+    }
+
+    // Emit to "all events" listeners
+    for (const callback of this.allListeners) {
+      try {
+        callback(event);
+      } catch (error) {
+        console.error("Error in event callback (onAll):", error);
+      }
+    }
+  }
+
+  /**
+   * Remove all listeners
+   */
+  clear(): void {
+    this.listeners.clear();
+    this.allListeners.clear();
+  }
+
+  /**
+   * Get count of listeners for a specific type
+   * @param type - The event type to check
+   * @returns Number of listeners
+   */
+  listenerCount(type: NodeEventType): number {
+    return this.listeners.get(type)?.size || 0;
+  }
+
+  /**
+   * Get count of "all events" listeners
+   * @returns Number of listeners
+   */
+  allListenerCount(): number {
+    return this.allListeners.size;
+  }
+
+  /**
+   * Check if there are any listeners
+   * @returns True if any listeners are registered
+   */
+  hasListeners(): boolean {
+    return this.listeners.size > 0 || this.allListeners.size > 0;
+  }
+
+  /**
+   * Returns an Effect Stream of all events
+   * REMOVED: Effect-TS integration removed in Phase 1
+   * For streaming events in Temporal workflows, use native event emitter pattern
+   */
+  // toStream(): Stream.Stream<NodeEvent<unknown>> {
+  //   return Stream.asyncPush<NodeEvent<unknown>>((emit) =>
+  //     Effect.acquireRelease(
+  //       Effect.sync(() => {
+  //         const callback = (event: NodeEvent<unknown>) => {
+  //           emit.single(event);
+  //         };
+  //         this.onAll(callback);
+  //         return callback;
+  //       }),
+  //       (callback) => Effect.sync(() => this.offAll(callback)),
+  //     ),
+  //   );
+  // }
+
+  /**
+   * Returns an AsyncIterable of all events
+   * REMOVED: Effect-TS dependency removed in Phase 1
+   * Implement using native async generators if needed
+   */
+  // toAsyncIterable(): AsyncIterable<NodeEvent<unknown>> {
+  //   return Stream.toAsyncIterable(this.toStream());
+  // }
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * btree - Core behavior tree implementation
+ * Inspired by BehaviorTree.CPP
+ */
+
+// Base nodes
+export {
+  ActionNode,
+  BaseNode,
+  CompositeNode,
+  ConditionNode,
+  DecoratorNode,
+} from "./base-node.js";
+// Behavior tree wrapper
+export { BehaviorTree, type ParsedPath } from "./behavior-tree.js";
+// Blackboard
+export { ScopedBlackboard } from "./blackboard.js";
+// Composite nodes
+export * from "./composites/index.js";
+
+// Decorator nodes
+export * from "./decorators/index.js";
+// Event system
+export * from "./events.js";
+// Registry
+export { Registry } from "./registry.js";
+export { registerStandardNodes } from "./registry-utils.js";
+// Scripting (deprecated) - use CodeExecution instead
+// export * from "./scripting/index.js";
+// Test nodes (for examples and testing)
+export * from "./test-nodes.js";
+export type {
+  IScopedBlackboard,
+  ITreeRegistry,
+  TemporalContext,
+  WorkflowArgs,
+  WorkflowResult,
+  // Activity types
+  BtreeActivities,
+  PieceActivityRequest,
+  PieceAuth,
+  PythonScriptRequest,
+  PythonScriptResult,
+  ParseFileRequest,
+  ParseFileResult,
+  GenerateFileRequest,
+  GenerateFileResult,
+  HttpRequestActivity,
+  HttpResponseActivity,
+  // Code execution types
+  CodeExecutionRequest,
+  CodeExecutionResult,
+  DataRef,
+  // Token provider
+  TokenProvider,
+} from "./types.js";
+// DataStore module
+export * from "./data-store/index.js";
+// Core types
+export * from "./types.js";
+// Re-export commonly used types for convenience
+export { NodeStatus } from "./types.js";
+// Utility nodes
+export * from "./utilities/index.js";
+// Debug nodes
+export * from "./debug/index.js";
+// Error types
+export { ConfigurationError } from "./errors.js";
+// YAML parsing and validation
+export * from "./yaml/index.js";
+// Schemas (for advanced usage)
+export * from "./schemas/index.js";
+// Template loading
+export * from "./templates/template-loader.js";
+// Integrations (Active Pieces)
+export * from "./integrations/index.js";
+// Activity-based action nodes
+export * from "./actions/index.js";
+// Observability (execution tracking, sinks)
+export * from "./observability/index.js";

package/src/integrations/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Integrations Module
+ * Third-party service integrations via Active Pieces
+ */
+
+// Main integration action node
+export {
+  IntegrationAction,
+  type IntegrationActionConfig,
+  type IntegrationContext,
+  type TokenProvider,
+  envTokenProvider,
+} from "./integration-action.js";
+
+// Piece executor
+export {
+  executePieceAction,
+  listPieceActions,
+  isPieceInstalled,
+  clearPieceCache,
+} from "./piece-executor.js";
+
+// Re-export types from types.ts for convenience
+export type {
+  PieceAuth,
+  PieceActivityRequest,
+} from "../types.js";
+
+// Backward compatibility alias
+export type { PieceActivityRequest as PieceActionRequest } from "../types.js";