@q1k-oss/btree-workflows 0.0.1

package/src/composites/while.ts

@@ -0,0 +1,149 @@
+/**
+ * While node - Loop while condition is true
+ */
+
+import { CompositeNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+  type TreeNode,
+} from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+export interface WhileConfiguration extends NodeConfiguration {
+  maxIterations?: number; // Safety limit
+}
+
+/**
+ * While loops while the condition returns SUCCESS.
+ * Structure:
+ * - First child = condition
+ * - Second child = body
+ */
+export class While extends CompositeNode {
+  private maxIterations: number;
+  private currentIteration: number = 0;
+  private condition?: TreeNode;
+  private body?: TreeNode;
+  private bodyStarted: boolean = false;
+
+  constructor(config: WhileConfiguration) {
+    super(config);
+    this.maxIterations = config.maxIterations ?? 1000;
+  }
+
+  addChild(child: TreeNode): void {
+    if (!this.condition) {
+      this.condition = child;
+      this._children.push(child);
+      child.parent = this;
+    } else if (!this.body) {
+      this.body = child;
+      this._children.push(child);
+      child.parent = this;
+    } else {
+      throw new ConfigurationError(
+        "While can have maximum 2 children (condition, body)",
+      );
+    }
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    if (!this.condition) {
+      throw new ConfigurationError("While requires a condition child");
+    }
+    if (!this.body) {
+      throw new ConfigurationError("While requires a body child");
+    }
+
+    this.log(
+      `Starting while loop (iteration ${this.currentIteration}/${this.maxIterations})`,
+    );
+
+    // Loop while condition is SUCCESS
+    while (this.currentIteration < this.maxIterations) {
+      // Check for cancellation before each iteration
+      checkSignal(context.signal);
+
+      // Only check condition if body hasn't started for this iteration
+      if (!this.bodyStarted) {
+        // Evaluate condition
+        this.log(`Evaluating condition (iteration ${this.currentIteration})`);
+        const conditionStatus = await this.condition.tick(context);
+
+        if (conditionStatus === NodeStatus.RUNNING) {
+          this.log("Condition is running");
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+        }
+
+        if (conditionStatus === NodeStatus.FAILURE) {
+          this.log("Condition failed - exiting loop");
+          this._status = NodeStatus.SUCCESS;
+          this.currentIteration = 0;
+          this.bodyStarted = false;
+          return NodeStatus.SUCCESS;
+        }
+
+        // Condition succeeded, mark body as started
+        this.bodyStarted = true;
+      } else {
+        this.log(
+          `Body already started for iteration ${this.currentIteration} - continuing execution`,
+        );
+      }
+
+      // Execute body
+      this.log(`Executing body (iteration ${this.currentIteration})`);
+      const bodyStatus = await this.body.tick(context);
+
+      switch (bodyStatus) {
+        case NodeStatus.SUCCESS:
+          this.log("Body succeeded - continuing loop");
+          this.currentIteration++;
+          this.bodyStarted = false; // Reset for next iteration
+          this.condition.reset(); // Reset for next iteration
+          this.body.reset();
+          break;
+
+        case NodeStatus.FAILURE:
+          this.log("Body failed - While fails");
+          this._status = NodeStatus.FAILURE;
+          this.currentIteration = 0;
+          this.bodyStarted = false;
+          return NodeStatus.FAILURE;
+
+        case NodeStatus.RUNNING:
+          this.log("Body is running");
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+
+        default:
+          throw new Error(`Unexpected status from body: ${bodyStatus}`);
+      }
+    }
+
+    // Max iterations reached
+    this.log(`Max iterations (${this.maxIterations}) reached`);
+    this._status = NodeStatus.FAILURE;
+    this.currentIteration = 0;
+    this.bodyStarted = false;
+    return NodeStatus.FAILURE;
+  }
+
+  protected onReset(): void {
+    super.onReset();
+    this.log("Resetting - clearing body started flag");
+    this.currentIteration = 0;
+    this.bodyStarted = false;
+  }
+
+  protected onHalt(): void {
+    super.onHalt();
+    this.log("Halting - clearing body started flag");
+    this.currentIteration = 0;
+    this.bodyStarted = false;
+  }
+}

package/src/data-store/index.ts

@@ -0,0 +1,10 @@
+/**
+ * DataStore module exports
+ *
+ * Provides interfaces and implementations for large data storage
+ * outside workflow execution context.
+ */
+
+export type { DataStore, DataRef, PutOptions } from "./types.js";
+export { isDataRef } from "./types.js";
+export { MemoryDataStore } from "./memory-store.js";

package/src/data-store/memory-store.ts

@@ -0,0 +1,161 @@
+/**
+ * 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
+ */
+
+import type { DataStore, DataRef, PutOptions } from "./types.js";
+
+interface StoredEntry {
+  data: unknown;
+  sizeBytes: number;
+  expiresAt?: number;
+}
+
+/**
+ * In-memory DataStore implementation
+ * Suitable for tests and local development
+ */
+export class MemoryDataStore implements DataStore {
+  private storage = new Map<string, StoredEntry>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options?: { cleanupIntervalMs?: number }) {
+    // Start periodic cleanup for expired entries
+    const cleanupMs = options?.cleanupIntervalMs ?? 60000; // 1 minute default
+    if (cleanupMs > 0) {
+      this.cleanupInterval = setInterval(() => this.cleanup(), cleanupMs);
+      // Don't prevent process exit
+      if (this.cleanupInterval.unref) {
+        this.cleanupInterval.unref();
+      }
+    }
+  }
+
+  async put(key: string, data: unknown, options?: PutOptions): Promise<DataRef> {
+    const serialized = JSON.stringify(data);
+    const sizeBytes = Buffer.byteLength(serialized, "utf8");
+
+    const entry: StoredEntry = {
+      data,
+      sizeBytes,
+    };
+
+    if (options?.ttlSeconds) {
+      entry.expiresAt = Date.now() + options.ttlSeconds * 1000;
+    }
+
+    this.storage.set(key, entry);
+
+    return {
+      store: "memory",
+      key,
+      sizeBytes,
+      expiresAt: entry.expiresAt,
+    };
+  }
+
+  async get(ref: DataRef): Promise<unknown> {
+    if (ref.store !== "memory") {
+      throw new Error(`MemoryDataStore cannot retrieve from store: ${ref.store}`);
+    }
+
+    const entry = this.storage.get(ref.key);
+
+    if (!entry) {
+      throw new Error(`Data not found for key: ${ref.key}`);
+    }
+
+    // Check expiration
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.storage.delete(ref.key);
+      throw new Error(`Data expired for key: ${ref.key}`);
+    }
+
+    // Return a deep clone to prevent accidental mutation
+    return structuredClone(entry.data);
+  }
+
+  async delete(ref: DataRef): Promise<void> {
+    if (ref.store !== "memory") {
+      throw new Error(`MemoryDataStore cannot delete from store: ${ref.store}`);
+    }
+
+    this.storage.delete(ref.key);
+  }
+
+  async exists(ref: DataRef): Promise<boolean> {
+    if (ref.store !== "memory") {
+      return false;
+    }
+
+    const entry = this.storage.get(ref.key);
+
+    if (!entry) {
+      return false;
+    }
+
+    // Check expiration
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.storage.delete(ref.key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Clear all stored data
+   * Useful for test cleanup
+   */
+  clear(): void {
+    this.storage.clear();
+  }
+
+  /**
+   * Get the number of stored entries
+   */
+  size(): number {
+    return this.storage.size;
+  }
+
+  /**
+   * Get total bytes stored
+   */
+  totalBytes(): number {
+    let total = 0;
+    for (const entry of this.storage.values()) {
+      total += entry.sizeBytes;
+    }
+    return total;
+  }
+
+  /**
+   * Stop the cleanup interval
+   * Call this when done with the store to prevent memory leaks in tests
+   */
+  dispose(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  /**
+   * Remove expired entries
+   */
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.storage.entries()) {
+      if (entry.expiresAt && now > entry.expiresAt) {
+        this.storage.delete(key);
+      }
+    }
+  }
+}

package/src/data-store/types.ts

@@ -0,0 +1,94 @@
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export function isDataRef(value: unknown): value is DataRef {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  return (
+    typeof obj.store === "string" &&
+    ["gcs", "s3", "redis", "memory"].includes(obj.store) &&
+    typeof obj.key === "string" &&
+    obj.key.length > 0
+  );
+}

package/src/debug/breakpoint.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Tests for Breakpoint node
+ */
+
+import { describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { Registry } from "../registry.js";
+import { NodeStatus, type TemporalContext } from "../types.js";
+import { Breakpoint } from "./breakpoint.js";
+
+describe("Breakpoint", () => {
+  const createContext = (): TemporalContext => ({
+    blackboard: new ScopedBlackboard(),
+    treeRegistry: new Registry(),
+    signal: new AbortController().signal,
+    timestamp: Date.now(),
+  });
+
+  it("should return RUNNING to signal pause", async () => {
+    const node = new Breakpoint({ id: "test-break" });
+    const context = createContext();
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.RUNNING);
+    expect(node.status()).toBe(NodeStatus.RUNNING);
+  });
+
+  it("should store the breakpointId", () => {
+    const node = new Breakpoint({ id: "my-breakpoint" });
+
+    expect(node.breakpointId).toBe("my-breakpoint");
+    expect(node.id).toBe("breakpoint-my-breakpoint");
+  });
+
+  it("should consistently return RUNNING", async () => {
+    const node = new Breakpoint({ id: "pause-here" });
+    const context = createContext();
+
+    // Execute multiple times - should always return RUNNING
+    const result1 = await node.tick(context);
+    const result2 = await node.tick(context);
+
+    expect(result1).toBe(NodeStatus.RUNNING);
+    expect(result2).toBe(NodeStatus.RUNNING);
+  });
+});

package/src/debug/breakpoint.ts

@@ -0,0 +1,30 @@
+/**
+ * Breakpoint - Pauses execution without failure
+ * Returns RUNNING to signal pause (not FAILURE)
+ */
+
+import { ActionNode } from "../base-node.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+
+export interface BreakpointConfig {
+  id: string;
+}
+
+/**
+ * Breakpoint pauses execution without marking it as a failure.
+ * Returns RUNNING to signal that execution should pause here.
+ * The session can then be resumed from this point.
+ */
+export class Breakpoint extends ActionNode {
+  readonly breakpointId: string;
+
+  constructor(config: BreakpointConfig) {
+    super({ id: `breakpoint-${config.id}` });
+    this.breakpointId = config.id;
+  }
+
+  async executeTick(_context: TemporalContext): Promise<NodeStatus> {
+    this._status = NodeStatus.RUNNING;
+    return NodeStatus.RUNNING;
+  }
+}

package/src/debug/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Debug nodes for behavior tree debugging and resume functionality
+ */
+
+// Breakpoint is not exported - it's still in development
+// The current implementation causes infinite loops with tickWhileRunning
+// See docs/backlog/DEBUG_MODE.md for the full implementation plan
+// export {
+//   Breakpoint,
+//   BreakpointSchema,
+//   type BreakpointConfig,
+// } from "./breakpoint.js";
+
+export {
+  ResumePoint,
+  type ResumePointConfig,
+} from "./resume-point.js";

package/src/debug/resume-point.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Tests for ResumePoint node
+ */
+
+import { describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { Registry } from "../registry.js";
+import { NodeStatus, type TemporalContext } from "../types.js";
+import { ResumePoint } from "./resume-point.js";
+
+describe("ResumePoint", () => {
+  const createContext = (): TemporalContext => ({
+    blackboard: new ScopedBlackboard(),
+    treeRegistry: new Registry(),
+    signal: new AbortController().signal,
+    timestamp: Date.now(),
+  });
+
+  it("should always return SUCCESS", async () => {
+    const node = new ResumePoint({ id: "test-resume" });
+    const context = createContext();
+
+    const result = await node.tick(context);
+
+    expect(result).toBe(NodeStatus.SUCCESS);
+    expect(node.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should store the resumePointId", () => {
+    const node = new ResumePoint({ id: "my-custom-id" });
+
+    expect(node.resumePointId).toBe("my-custom-id");
+    expect(node.id).toBe("resume-point-my-custom-id");
+  });
+
+  it("should not affect tree execution flow", async () => {
+    const node = new ResumePoint({ id: "marker" });
+    const context = createContext();
+
+    // Execute multiple times - should always succeed
+    const result1 = await node.tick(context);
+    const result2 = await node.tick(context);
+    const result3 = await node.tick(context);
+
+    expect(result1).toBe(NodeStatus.SUCCESS);
+    expect(result2).toBe(NodeStatus.SUCCESS);
+    expect(result3).toBe(NodeStatus.SUCCESS);
+  });
+});

package/src/debug/resume-point.ts

@@ -0,0 +1,29 @@
+/**
+ * ResumePoint - Marker node for resume location
+ * Always returns SUCCESS, used purely as a findable marker for LLM-based resume
+ */
+
+import { ActionNode } from "../base-node.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+
+export 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.
+ */
+export class ResumePoint extends ActionNode {
+  readonly resumePointId: string;
+
+  constructor(config: ResumePointConfig) {
+    super({ id: `resume-point-${config.id}` });
+    this.resumePointId = config.id;
+  }
+
+  async executeTick(_context: TemporalContext): Promise<NodeStatus> {
+    this._status = NodeStatus.SUCCESS;
+    return NodeStatus.SUCCESS;
+  }
+}

package/src/decorators/delay.schema.ts

@@ -0,0 +1,21 @@
+/**
+ * Delay decorator configuration schema
+ */
+
+import { z } from "zod";
+import { createNodeSchema, validations } from "../schemas/base.schema.js";
+
+/**
+ * Schema for Delay decorator configuration
+ * Validates that delayMs is non-negative (can be 0)
+ */
+export const delayConfigurationSchema = createNodeSchema("Delay", {
+  delayMs: validations.nonNegativeNumber("delayMs"),
+});
+
+/**
+ * Validated Delay configuration type
+ */
+export type ValidatedDelayConfiguration = z.infer<
+  typeof delayConfigurationSchema
+>;