@q1k-oss/btree-workflows 0.0.1

package/src/decorators/timeout.test.ts

@@ -0,0 +1,274 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { MockAction, WaitAction } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { Timeout } from "./timeout.js";
+
+describe("Timeout", () => {
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    context = {
+      blackboard: new ScopedBlackboard(),
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should throw error if timeoutMs is not positive", () => {
+    expect(() => new Timeout({ id: "test", timeoutMs: 0 })).toThrow(
+      "test: Timeout must be positive (got 0)",
+    );
+
+    expect(() => new Timeout({ id: "test", timeoutMs: -100 })).toThrow(
+      "test: Timeout must be positive (got -100)",
+    );
+  });
+
+  it("should propagate ConfigurationError if no child is set", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 1000 });
+    try {
+      await timeout.tick(context);
+      throw new Error("Expected tick to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect((error as ConfigurationError).message).toContain(
+        "Decorator must have a child",
+      );
+    }
+  });
+
+  it("should pass through immediate SUCCESS", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 1000 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    timeout.setChild(child);
+
+    const status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(timeout.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should pass through immediate FAILURE", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 1000 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.FAILURE,
+    });
+
+    timeout.setChild(child);
+
+    const status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.FAILURE);
+    expect(timeout.status()).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should fail if child takes too long", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 50 });
+    const child = new WaitAction({
+      id: "child",
+      waitMs: 200, // Will take longer than timeout
+    });
+
+    timeout.setChild(child);
+
+    // First tick - child starts running
+    let status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    // Wait for timeout to elapse
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    // Next tick should fail due to timeout
+    status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.FAILURE);
+    expect(child.status()).toBe(NodeStatus.IDLE); // Child should be halted
+  });
+
+  it("should succeed if child completes before timeout", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 100 });
+    const child = new WaitAction({
+      id: "child",
+      waitMs: 30, // Will complete before timeout
+    });
+
+    timeout.setChild(child);
+
+    // First tick - child starts running
+    let status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    // Wait for child to complete
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    // Next tick should succeed
+    status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(timeout.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should halt child when timeout is reached", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 50 });
+    const child = new WaitAction({
+      id: "child",
+      waitMs: 200,
+    });
+
+    const haltSpy = vi.spyOn(child, "halt");
+
+    timeout.setChild(child);
+
+    // Start execution
+    await timeout.tick(context);
+
+    // Wait for timeout
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    // Next tick should halt the child
+    await timeout.tick(context);
+
+    expect(haltSpy).toHaveBeenCalled();
+  });
+
+  it("should cleanup timeout on completion", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 1000 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    timeout.setChild(child);
+
+    await timeout.tick(context);
+
+    // Check internal state is cleaned up
+    expect((timeout as unknown).startTime).toBeNull();
+  });
+
+  it("should handle halt correctly", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 1000 });
+    const child = new WaitAction({
+      id: "child",
+      waitMs: 100,
+    });
+
+    timeout.setChild(child);
+
+    // Start execution but don't await
+    const tickPromise = timeout.tick(context);
+
+    // Give it a moment to start
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    // Halt while running
+    timeout.halt();
+
+    // Status should be IDLE immediately after halt
+    expect(timeout.status()).toBe(NodeStatus.IDLE);
+    expect((timeout as unknown).startTime).toBeNull();
+
+    // Wait for tick to complete or fail (may complete with error)
+    try {
+      await tickPromise;
+    } catch (_e) {
+      // Expected if halt interrupts execution
+    }
+  });
+
+  it("should handle reset correctly", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 1000 });
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    timeout.setChild(child);
+
+    // Execute
+    await timeout.tick(context);
+
+    // Reset
+    timeout.reset();
+
+    expect(timeout.status()).toBe(NodeStatus.IDLE);
+    expect((timeout as unknown).startTime).toBeNull();
+  });
+
+  it("should handle multiple ticks while waiting", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 100 });
+    const child = new WaitAction({
+      id: "child",
+      waitMs: 50,
+    });
+
+    timeout.setChild(child);
+
+    // Multiple ticks while child is running
+    let status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    // Wait for child to complete
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should fail immediately if already timed out", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 50 });
+    const child = new WaitAction({
+      id: "child",
+      waitMs: 200,
+    });
+
+    timeout.setChild(child);
+
+    // Start and wait for timeout
+    await timeout.tick(context);
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    // Second tick after timeout elapsed - should fail immediately
+    const status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should handle timeout during child execution", async () => {
+    const timeout = new Timeout({ id: "test-timeout", timeoutMs: 20 });
+
+    // Child that will definitely take longer than timeout
+    const child = new WaitAction({
+      id: "child",
+      waitMs: 100, // Much longer than timeout
+    });
+
+    timeout.setChild(child);
+
+    // First tick: should start timeout and return RUNNING
+    const startTime = Date.now();
+    let status = await timeout.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+    expect(timeout.status()).toBe(NodeStatus.RUNNING);
+
+    // Wait for timeout to occur
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    // Second tick: should detect timeout and return FAILURE
+    status = await timeout.tick(context);
+    const elapsed = Date.now() - startTime;
+
+    // Should timeout after ~20ms, not wait for full 100ms
+    expect(elapsed).toBeLessThan(50); // Give some buffer for test environment
+    expect(status).toBe(NodeStatus.FAILURE);
+    expect(timeout.status()).toBe(NodeStatus.FAILURE);
+
+    // Child should have been halted
+    expect(child.status()).toBe(NodeStatus.IDLE);
+  });
+});

package/src/decorators/timeout.ts

@@ -0,0 +1,159 @@
+/**
+ * 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
+ */
+
+import { CancellationScope, isCancellation } from "@temporalio/workflow";
+import { DecoratorNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+} from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+export interface TimeoutConfiguration extends NodeConfiguration {
+  /**
+   * Timeout duration in milliseconds
+   */
+  timeoutMs: number;
+}
+
+export class Timeout extends DecoratorNode {
+  private timeoutMs: number;
+  private startTime: number | null = null;
+  private useTemporalAPI: boolean | null = null;  // Cached detection result
+
+  constructor(config: TimeoutConfiguration) {
+    super(config);
+    this.timeoutMs = config.timeoutMs;
+
+    if (this.timeoutMs <= 0) {
+      throw new ConfigurationError(
+        `${this.name}: Timeout must be positive (got ${this.timeoutMs})`,
+      );
+    }
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError(`${this.name}: Decorator must have a child`);
+    }
+
+    // Try Temporal API on first execution only
+    if (this.useTemporalAPI === null) {
+      try {
+        this.log(`Starting timeout for ${this.timeoutMs}ms`);
+        const childStatus = await CancellationScope.withTimeout(
+          this.timeoutMs,
+          async () => {
+            return await this.child!.tick(context);
+          }
+        );
+
+        // Success - we're in a Temporal workflow
+        this.useTemporalAPI = true;
+        this._status = childStatus;
+        this.log(`Child completed with ${childStatus}`);
+        return childStatus;
+
+      } catch (err) {
+        // Handle Temporal timeout cancellation
+        if (isCancellation(err)) {
+          this.useTemporalAPI = true;
+          this.log(`Timeout after ${this.timeoutMs}ms`);
+
+          if (this.child.status() === NodeStatus.RUNNING) {
+            this.child.halt();
+          }
+
+          this._status = NodeStatus.FAILURE;
+          return NodeStatus.FAILURE;
+        }
+
+        // Not in Temporal workflow - use standalone polling
+        this.useTemporalAPI = false;
+        // Fall through to polling implementation below
+      }
+    }
+
+    // Use Temporal API (we know we're in a workflow)
+    if (this.useTemporalAPI === true) {
+      try {
+        this.log(`Starting timeout for ${this.timeoutMs}ms`);
+        const childStatus = await CancellationScope.withTimeout(
+          this.timeoutMs,
+          async () => {
+            return await this.child!.tick(context);
+          }
+        );
+
+        this._status = childStatus;
+        this.log(`Child completed with ${childStatus}`);
+        return childStatus;
+
+      } catch (err) {
+        if (isCancellation(err)) {
+          this.log(`Timeout after ${this.timeoutMs}ms`);
+
+          if (this.child.status() === NodeStatus.RUNNING) {
+            this.child.halt();
+          }
+
+          this._status = NodeStatus.FAILURE;
+          return NodeStatus.FAILURE;
+        }
+        throw err;
+      }
+    }
+
+    // Standalone polling implementation (multi-tick)
+    if (this.startTime === null) {
+      this.startTime = Date.now();
+      this.log(`Starting timeout for ${this.timeoutMs}ms`);
+    }
+
+    const elapsed = Date.now() - this.startTime;
+
+    if (elapsed >= this.timeoutMs) {
+      this.log(`Timeout after ${this.timeoutMs}ms`);
+      this.startTime = null;
+
+      if (this.child.status() === NodeStatus.RUNNING) {
+        this.child.halt();
+      }
+
+      this._status = NodeStatus.FAILURE;
+      return NodeStatus.FAILURE;
+    }
+
+    // Execute child
+    const childStatus = await this.child.tick(context);
+
+    if (childStatus !== NodeStatus.RUNNING) {
+      // Child completed - cleanup
+      this.startTime = null;
+    }
+
+    this._status = childStatus;
+    return childStatus;
+  }
+
+  protected onHalt(): void {
+    this.startTime = null;
+    if (this.child && this.child.status() === NodeStatus.RUNNING) {
+      this.child.halt();
+    }
+  }
+
+  protected onReset(): void {
+    this.startTime = null;
+    this.useTemporalAPI = null;  // Re-detect on next execution
+  }
+}

package/src/errors.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { ConfigurationError } from "./errors.js";
+
+describe("ConfigurationError", () => {
+  it("should create error with message", () => {
+    const error = new ConfigurationError("Element not found");
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(ConfigurationError);
+    expect(error.message).toBe("Element not found");
+    expect(error.name).toBe("ConfigurationError");
+    expect(error.isConfigurationError).toBe(true);
+  });
+
+  it("should create error with message and hint", () => {
+    const error = new ConfigurationError(
+      "Element not found",
+      "Use LocateElement first",
+    );
+
+    expect(error.message).toBe("Element not found");
+    expect(error.hint).toBe("Use LocateElement first");
+  });
+
+  it("should create error without hint", () => {
+    const error = new ConfigurationError("Something went wrong");
+
+    expect(error.message).toBe("Something went wrong");
+    expect(error.hint).toBeUndefined();
+  });
+
+  it("should have proper stack trace", () => {
+    const error = new ConfigurationError("Test error");
+
+    expect(error.stack).toBeDefined();
+    expect(error.stack).toContain("ConfigurationError");
+  });
+
+  it("should be distinguishable from regular Error", () => {
+    const configError = new ConfigurationError("Config error");
+    const regularError = new Error("Regular error");
+
+    expect(configError).toBeInstanceOf(ConfigurationError);
+    expect(regularError).not.toBeInstanceOf(ConfigurationError);
+
+    // ConfigurationError is also an Error
+    expect(configError).toBeInstanceOf(Error);
+    expect(regularError).toBeInstanceOf(Error);
+  });
+
+  it("should preserve error properties when caught and rethrown", () => {
+    try {
+      throw new ConfigurationError("Original message", "Original hint");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigurationError);
+      if (error instanceof ConfigurationError) {
+        expect(error.message).toBe("Original message");
+        expect(error.hint).toBe("Original hint");
+        expect(error.isConfigurationError).toBe(true);
+      }
+    }
+  });
+});

package/src/errors.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+export class ConfigurationError extends Error {
+  readonly isConfigurationError = true;
+
+  constructor(
+    message: string,
+    public readonly hint?: string,
+  ) {
+    super(message);
+    this.name = "ConfigurationError";
+
+    // Maintains proper stack trace in V8 environments (Chrome, Node.js)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ConfigurationError);
+    }
+  }
+}