@q1k-oss/btree-workflows 0.0.1

package/src/behavior-tree.ts

@@ -0,0 +1,283 @@
+/**
+ * BehaviorTree - Wrapper for TreeNode with path-based indexing
+ * Enables partial tree updates without full reload
+ */
+
+import type {
+  TreeNode,
+  TemporalContext,
+  WorkflowArgs,
+  WorkflowResult,
+} from "./types.js";
+import { ScopedBlackboard } from "./blackboard.js";
+
+/**
+ * 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
+ */
+export interface ParsedPath {
+  treeId: string;
+  nodePath: string;
+}
+
+export class BehaviorTree {
+  private root: TreeNode;
+  private pathIndex: Map<string, TreeNode> = new Map();
+  private idIndex: Map<string, TreeNode> = new Map();
+
+  constructor(root: TreeNode) {
+    this.root = root;
+    this.buildNodeIndex();
+  }
+
+  /**
+   * Parse a path with tree ID prefix.
+   * Format: #TreeID/node/path
+   *
+   * @param fullPath Path string starting with # followed by tree ID
+   * @returns Object with treeId and nodePath
+   * @throws Error if path format is invalid
+   *
+   * Valid examples:
+   * - "#SimpleTest/0/1" -> { treeId: "SimpleTest", nodePath: "/0/1" }
+   * - "#MyTree/" -> { treeId: "MyTree", nodePath: "/" }
+   * - "#OnlyTree" -> { treeId: "OnlyTree", nodePath: "/" }
+   *
+   * Invalid examples:
+   * - "/0/1" - missing #TreeID prefix
+   * - "#/0/1" - empty tree ID
+   * - "#" - empty tree ID
+   */
+  static parsePathWithTreeId(fullPath: string): ParsedPath {
+    if (!fullPath.startsWith("#")) {
+      throw new Error(
+        `Invalid path format: '${fullPath}'. Path must start with #TreeID (e.g., #SimpleTest/0/1)`,
+      );
+    }
+
+    const slashIndex = fullPath.indexOf("/");
+    let treeId: string;
+    let nodePath: string;
+
+    if (slashIndex === -1) {
+      // No slash after tree ID, e.g., "#TreeId" means root of that tree
+      treeId = fullPath.slice(1);
+      nodePath = "/";
+    } else {
+      treeId = fullPath.slice(1, slashIndex);
+      nodePath = fullPath.slice(slashIndex);
+    }
+
+    // Validate tree ID is not empty
+    if (!treeId || treeId.trim() === "") {
+      throw new Error(
+        `Invalid path: tree ID cannot be empty in '${fullPath}'. Expected format: #TreeID/path`,
+      );
+    }
+
+    // Validate node path starts with /
+    if (!nodePath.startsWith("/")) {
+      throw new Error(
+        `Invalid path: node path must start with '/' in '${fullPath}'`,
+      );
+    }
+
+    return { treeId, nodePath };
+  }
+
+  /**
+   * Get the root node of the tree
+   */
+  getRoot(): TreeNode {
+    return this.root;
+  }
+
+  /**
+   * Find a node by its path
+   * Path format: / for root, /0 for first child, /0/1 for second child of first child
+   */
+  findNodeByPath(path: string): TreeNode | null {
+    return this.pathIndex.get(path) || null;
+  }
+
+  /**
+   * Find a node by its ID (if it has one)
+   * Convenience method for nodes with explicit IDs
+   */
+  findNodeById(nodeId: string): TreeNode | null {
+    return this.idIndex.get(nodeId) || null;
+  }
+
+  /**
+   * Get the path for a given node
+   * Returns null if the node is not in the tree
+   */
+  getNodePath(targetNode: TreeNode): string | null {
+    for (const [path, node] of this.pathIndex.entries()) {
+      if (node === targetNode) {
+        return path;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get the path for a node by its ID
+   * More reliable than instance-based lookup
+   * Returns null if the node is not in the tree
+   */
+  getNodePathById(nodeId: string): string | null {
+    const node = this.findNodeById(nodeId);
+    if (!node) return null;
+
+    // Search pathIndex for this node
+    for (const [path, indexedNode] of this.pathIndex.entries()) {
+      if (indexedNode.id === nodeId) {
+        return path;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Clone this BehaviorTree (deep clones the underlying TreeNode)
+   */
+  clone(): BehaviorTree {
+    const clonedRoot = this.root.clone();
+    return new BehaviorTree(clonedRoot);
+  }
+
+  /**
+   * Convert this BehaviorTree to a Temporal workflow function
+   * Returns a workflow function that can be registered with Temporal
+   *
+   * @returns A Temporal workflow function that executes this behavior tree
+   *
+   * @example
+   * ```typescript
+   * import { BehaviorTree } from '@wayfarer-ai/btree';
+   * import { Sequence } from '@wayfarer-ai/btree';
+   * import { PrintAction } from '@wayfarer-ai/btree';
+   *
+   * const root = new Sequence({ id: 'root' });
+   * root.addChild(new PrintAction({ id: 'step1', message: 'Hello' }));
+   * root.addChild(new PrintAction({ id: 'step2', message: 'World' }));
+   *
+   * const tree = new BehaviorTree(root);
+   * const workflow = tree.toWorkflow();
+   *
+   * // Register with Temporal worker
+   * // Worker.create({ workflows: { myWorkflow: workflow }, ... })
+   * ```
+   */
+  toWorkflow(): (args: WorkflowArgs) => Promise<WorkflowResult> {
+    const root = this.root;
+
+    return async function behaviorTreeWorkflow(
+      args: WorkflowArgs,
+    ): Promise<WorkflowResult> {
+      // Create TemporalContext
+      const context: TemporalContext = {
+        blackboard: new ScopedBlackboard(),
+        treeRegistry: args.treeRegistry,
+        timestamp: Date.now(),
+        sessionId: args.sessionId || `session-${Date.now()}`,
+        // Store input immutably for ${input.key} resolution
+        input: args.input ? Object.freeze({ ...args.input }) : undefined,
+        // Pass activities for I/O operations (deterministic Temporal execution)
+        activities: args.activities,
+        // Pass tokenProvider for IntegrationAction authentication
+        tokenProvider: args.tokenProvider,
+      };
+
+      // Also copy input to blackboard for backward compatibility
+      // This allows ${key} or ${bb.key} to access input values
+      if (args.input) {
+        for (const [key, value] of Object.entries(args.input)) {
+          context.blackboard.set(key, value);
+        }
+      }
+
+      // Execute tree
+      const status = await root.tick(context);
+
+      // Return result with output
+      return {
+        status,
+        output: context.blackboard.toJSON(),
+      };
+    };
+  }
+
+  /**
+   * Replace a node at the given path with a new node
+   * Updates parent-child relationships and rebuilds the index
+   */
+  replaceNodeAtPath(path: string, newNode: TreeNode): void {
+    const oldNode = this.findNodeByPath(path);
+    if (!oldNode) {
+      throw new Error(`Node not found at path: ${path}`);
+    }
+
+    if (path === "/") {
+      // Special case: replacing root
+      this.root = newNode;
+      newNode.parent = undefined;
+    } else {
+      // Find parent and child index from path
+      const pathParts = path.split("/").filter((p) => p);
+      const lastPart = pathParts[pathParts.length - 1];
+
+      if (!lastPart) {
+        throw new Error(`Invalid path format: ${path}`);
+      }
+
+      const childIndex = parseInt(lastPart, 10);
+
+      const parent = oldNode.parent;
+      if (!parent || !parent.children) {
+        throw new Error(`Cannot replace node: invalid parent at path ${path}`);
+      }
+
+      // Update parent's children array
+      parent.children[childIndex] = newNode;
+      newNode.parent = parent;
+    }
+
+    // Rebuild index (paths may have changed if newNode has different children)
+    this.buildNodeIndex();
+  }
+
+  /**
+   * Build the node index with path-based and ID-based lookups
+   */
+  private buildNodeIndex(): void {
+    this.pathIndex.clear();
+    this.idIndex.clear();
+
+    const indexNode = (node: TreeNode, path: string) => {
+      // Index by path (always works)
+      this.pathIndex.set(path, node);
+
+      // Also index by ID if present
+      if (node.id) {
+        this.idIndex.set(node.id, node);
+      }
+
+      // Recursively index children
+      if (node.children) {
+        node.children.forEach((child, index) => {
+          // Build child path: / becomes /0, /0 becomes /0/1, etc.
+          const childPath = path === "/" ? `/${index}` : `${path}/${index}`;
+          indexNode(child, childPath);
+        });
+      }
+    };
+
+    // Start indexing from root with path '/'
+    indexNode(this.root, "/");
+  }
+}

package/src/blackboard.test.ts

@@ -0,0 +1,222 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "./blackboard.js";
+
+describe("ScopedBlackboard", () => {
+  let blackboard: ScopedBlackboard;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard();
+  });
+
+  describe("Basic operations", () => {
+    it("should store and retrieve values", () => {
+      blackboard.set("key1", "value1");
+      blackboard.set("key2", 42);
+
+      expect(blackboard.get("key1")).toBe("value1");
+      expect(blackboard.get("key2")).toBe(42);
+    });
+
+    it("should return undefined for non-existent keys", () => {
+      expect(blackboard.get("nonexistent")).toBeUndefined();
+    });
+
+    it("should check if key exists", () => {
+      blackboard.set("exists", true);
+
+      expect(blackboard.has("exists")).toBe(true);
+      expect(blackboard.has("notexists")).toBe(false);
+    });
+
+    it("should delete keys", () => {
+      blackboard.set("toDelete", "value");
+      expect(blackboard.has("toDelete")).toBe(true);
+
+      blackboard.delete("toDelete");
+      expect(blackboard.has("toDelete")).toBe(false);
+    });
+
+    it("should clear all entries", () => {
+      blackboard.set("key1", "value1");
+      blackboard.set("key2", "value2");
+
+      blackboard.clear();
+
+      expect(blackboard.has("key1")).toBe(false);
+      expect(blackboard.has("key2")).toBe(false);
+      expect(blackboard.keys()).toHaveLength(0);
+    });
+  });
+
+  describe("Scoped inheritance", () => {
+    it("should create child scopes", () => {
+      const child = blackboard.createScope("child");
+
+      expect(child.getScopeName()).toBe("child");
+      expect(child.getParentScope()).toBe(blackboard);
+    });
+
+    it("should inherit values from parent scope", () => {
+      blackboard.set("parentValue", "inherited");
+
+      const child = blackboard.createScope("child");
+      expect(child.get("parentValue")).toBe("inherited");
+      expect(child.has("parentValue")).toBe(true);
+    });
+
+    it("should override parent values in child scope", () => {
+      blackboard.set("value", "parent");
+
+      const child = blackboard.createScope("child");
+      child.set("value", "child");
+
+      expect(blackboard.get("value")).toBe("parent");
+      expect(child.get("value")).toBe("child");
+    });
+
+    it("should not affect parent when deleting in child", () => {
+      blackboard.set("value", "parent");
+
+      const child = blackboard.createScope("child");
+      child.delete("value");
+
+      expect(blackboard.get("value")).toBe("parent");
+      expect(child.get("value")).toBe("parent"); // Still inherited
+    });
+
+    it("should support multi-level inheritance", () => {
+      blackboard.set("level0", "root");
+
+      const child1 = blackboard.createScope("child1");
+      child1.set("level1", "child1");
+
+      const child2 = child1.createScope("child2");
+      child2.set("level2", "child2");
+
+      expect(child2.get("level0")).toBe("root");
+      expect(child2.get("level1")).toBe("child1");
+      expect(child2.get("level2")).toBe("child2");
+
+      expect(child2.getFullScopePath()).toBe("root.child1.child2");
+    });
+
+    it("should reuse existing child scopes", () => {
+      const child1 = blackboard.createScope("child");
+      child1.set("value", "test");
+
+      const child2 = blackboard.createScope("child");
+      expect(child1).toBe(child2);
+      expect(child2.get("value")).toBe("test");
+    });
+  });
+
+  describe("Port operations", () => {
+    it("should get port with default value", () => {
+      expect(blackboard.getPort("missing", "default")).toBe("default");
+
+      blackboard.set("exists", "value");
+      expect(blackboard.getPort("exists", "default")).toBe("value");
+    });
+
+    it("should set port value", () => {
+      blackboard.setPort("port", 123);
+      expect(blackboard.get("port")).toBe(123);
+    });
+
+    it("should handle typed port operations", () => {
+      interface Config {
+        timeout: number;
+        retries: number;
+      }
+
+      const config: Config = { timeout: 1000, retries: 3 };
+      blackboard.setPort<Config>("config", config);
+
+      const retrieved = blackboard.getPort<Config>("config");
+      expect(retrieved).toEqual(config);
+    });
+  });
+
+  describe("Utility methods", () => {
+    it("should return all keys including inherited ones", () => {
+      blackboard.set("parent1", "value1");
+      blackboard.set("parent2", "value2");
+
+      const child = blackboard.createScope("child");
+      child.set("child1", "value3");
+      child.set("parent1", "overridden"); // Override parent key
+
+      const keys = child.keys();
+      expect(keys).toContain("parent1");
+      expect(keys).toContain("parent2");
+      expect(keys).toContain("child1");
+      expect(keys).toHaveLength(3);
+    });
+
+    it("should return entries with local values overriding parent", () => {
+      blackboard.set("shared", "parent");
+      blackboard.set("parentOnly", "value");
+
+      const child = blackboard.createScope("child");
+      child.set("shared", "child");
+      child.set("childOnly", "value");
+
+      const entries = child.entries();
+      const entriesMap = new Map(entries);
+
+      expect(entriesMap.get("shared")).toBe("child");
+      expect(entriesMap.get("parentOnly")).toBe("value");
+      expect(entriesMap.get("childOnly")).toBe("value");
+      expect(entries).toHaveLength(3);
+    });
+
+    it("should convert to JSON with only local entries", () => {
+      blackboard.set("parent", "value");
+
+      const child = blackboard.createScope("child");
+      child.set("child1", "value1");
+      child.set("child2", "value2");
+
+      const json = child.toJSON();
+      expect(json).toEqual({
+        child1: "value1",
+        child2: "value2",
+      });
+      expect(json).not.toHaveProperty("parent");
+    });
+  });
+
+  describe("Debug utilities", () => {
+    it("should not throw when calling debug", () => {
+      blackboard.set("key", "value");
+      const child = blackboard.createScope("child");
+      child.set("childKey", "childValue");
+
+      // Should not throw
+      expect(() => child.debug()).not.toThrow();
+    });
+  });
+
+  describe("Snapshots", () => {
+    it("should create independent snapshots with clone", () => {
+      blackboard.set("x", 1);
+      const snapshot = blackboard.clone();
+      blackboard.set("x", 2);
+
+      expect(snapshot.get("x")).toBe(1);
+      expect(blackboard.get("x")).toBe(2);
+    });
+
+    it("should deep clone child scopes", () => {
+      blackboard.set("parent", "value");
+      const child = blackboard.createScope("child");
+      child.set("child", "value");
+
+      const snapshot = blackboard.clone();
+      blackboard.set("parent", "changed");
+
+      expect(snapshot.get("parent")).toBe("value");
+      expect(blackboard.get("parent")).toBe("changed");
+    });
+  });
+});

package/src/blackboard.ts

@@ -0,0 +1,192 @@
+/**
+ * Scoped Blackboard implementation with inheritance
+ * Inspired by BehaviorTree.CPP's blackboard
+ *
+ * Simple mutable API with native deep cloning for snapshots
+ */
+
+import type { IScopedBlackboard } from "./types.js";
+
+/**
+ * Implementation of a hierarchical blackboard with scoped inheritance
+ * Uses simple mutable operations with snapshot support via structuredClone
+ */
+export class ScopedBlackboard implements IScopedBlackboard {
+  private data: Record<string, unknown> = {};
+  private parent: ScopedBlackboard | null = null;
+  private scopeName: string;
+  private childScopes: Map<string, ScopedBlackboard> = new Map();
+
+  constructor(
+    scopeName: string = "root",
+    parent: ScopedBlackboard | null = null,
+  ) {
+    this.scopeName = scopeName;
+    this.parent = parent;
+  }
+
+  get(key: string): unknown {
+    // First check local scope
+    if (key in this.data) {
+      return this.data[key];
+    }
+
+    // Then check parent scopes
+    if (this.parent) {
+      return this.parent.get(key);
+    }
+
+    return undefined;
+  }
+
+  set(key: string, value: unknown): void {
+    this.data[key] = value;
+  }
+
+  has(key: string): boolean {
+    // Check local scope
+    if (key in this.data) {
+      return true;
+    }
+
+    // Check parent scopes
+    if (this.parent) {
+      return this.parent.has(key);
+    }
+
+    return false;
+  }
+
+  delete(key: string): void {
+    // Only delete from local scope
+    delete this.data[key];
+  }
+
+  clear(): void {
+    this.data = {};
+    this.childScopes.clear();
+  }
+
+  createScope(name: string): IScopedBlackboard {
+    // Check if scope already exists
+    if (this.childScopes.has(name)) {
+      const scope = this.childScopes.get(name);
+      if (!scope) {
+        throw new Error(`Scope ${name} not found`);
+      }
+      return scope;
+    }
+
+    // Create new child scope
+    const childScope = new ScopedBlackboard(name, this);
+    this.childScopes.set(name, childScope);
+    return childScope;
+  }
+
+  getParentScope(): IScopedBlackboard | null {
+    return this.parent;
+  }
+
+  getScopeName(): string {
+    return this.scopeName;
+  }
+
+  getPort<T>(key: string, defaultValue?: T): T {
+    const value = this.get(key);
+    if (value === undefined && defaultValue !== undefined) {
+      return defaultValue;
+    }
+    return value as T;
+  }
+
+  setPort<T>(key: string, value: T): void {
+    this.set(key, value);
+  }
+
+  keys(): string[] {
+    const localKeys = Object.keys(this.data);
+    const parentKeys = this.parent ? this.parent.keys() : [];
+
+    // Combine keys, removing duplicates (local keys override parent keys)
+    const allKeys = new Set([...localKeys, ...parentKeys]);
+    return Array.from(allKeys);
+  }
+
+  entries(): [string, unknown][] {
+    const result: [string, unknown][] = [];
+    const processedKeys = new Set<string>();
+
+    // Add local entries first
+    for (const [key, value] of Object.entries(this.data)) {
+      result.push([key, value]);
+      processedKeys.add(key);
+    }
+
+    // Add parent entries that aren't overridden
+    if (this.parent) {
+      for (const [key, value] of this.parent.entries()) {
+        if (!processedKeys.has(key)) {
+          result.push([key, value]);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  toJSON(): Record<string, unknown> {
+    // Only return local entries, not inherited ones
+    return { ...this.data };
+  }
+
+  /**
+   * Create a deep clone of this blackboard for snapshots
+   * Uses structured cloning for deep copy
+   */
+  clone(): IScopedBlackboard {
+    // Create a new blackboard instance with the same scope configuration
+    const cloned = new ScopedBlackboard(this.scopeName, this.parent);
+
+    // Deep clone the data object using structuredClone (Node 17+)
+    // This creates a true deep copy without freezing the original
+    cloned.data = structuredClone(this.data);
+
+    // Recursively clone child scopes
+    this.childScopes.forEach((childScope, name) => {
+      cloned.childScopes.set(name, childScope.clone() as ScopedBlackboard);
+    });
+
+    return cloned;
+  }
+
+  /**
+   * Get the full scope path (e.g., "root.child.grandchild")
+   */
+  getFullScopePath(): string {
+    const path: string[] = [this.scopeName];
+    let current = this.parent;
+
+    while (current) {
+      path.unshift(current.scopeName);
+      current = current.parent;
+    }
+
+    return path.join(".");
+  }
+
+  /**
+   * Debug utility to print the blackboard hierarchy
+   */
+  debug(indent: number = 0): void {
+    const prefix = "  ".repeat(indent);
+    console.log(`${prefix}Scope: ${this.scopeName}`);
+
+    for (const [key, value] of Object.entries(this.data)) {
+      console.log(`${prefix}  ${key}: ${JSON.stringify(value)}`);
+    }
+
+    for (const [_name, childScope] of this.childScopes) {
+      childScope.debug(indent + 1);
+    }
+  }
+}

package/src/composites/conditional.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * Conditional composite configuration schema
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for Conditional composite configuration
+ * Uses base schema only - condition logic is in child nodes
+ */
+export const conditionalConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated Conditional configuration type
+ */
+export type ValidatedConditionalConfiguration = z.infer<
+  typeof conditionalConfigurationSchema
+>;