@q1k-oss/btree-workflows 0.0.1 → 0.0.2

package/src/composites/while.ts

@@ -1,149 +0,0 @@
-/**
- * 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

@@ -1,10 +0,0 @@
-/**
- * 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

@@ -1,161 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-/**
- * 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

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,30 +0,0 @@
-/**
- * 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

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1,49 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-/**
- * 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
->;