@q1k-oss/btree-workflows 0.0.1

package/src/decorators/repeat.ts

@@ -0,0 +1,94 @@
+/**
+ * Repeat decorator - Execute child N times
+ */
+
+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 RepeatConfiguration extends NodeConfiguration {
+  numCycles: number;
+}
+
+/**
+ * Repeat executes its child exactly N times.
+ * Returns SUCCESS when all cycles complete successfully.
+ * Returns FAILURE if any cycle fails.
+ */
+export class Repeat extends DecoratorNode {
+  private numCycles: number;
+  private currentCycle: number = 0;
+
+  constructor(config: RepeatConfiguration) {
+    super(config);
+    this.numCycles = config.numCycles;
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError("Repeat requires a child");
+    }
+
+    this.log(`Repeat cycle ${this.currentCycle}/${this.numCycles}`);
+
+    // Check if we've completed all cycles
+    if (this.currentCycle >= this.numCycles) {
+      this.log("All cycles completed");
+      this._status = NodeStatus.SUCCESS;
+      this.currentCycle = 0; // Reset for next run
+      return NodeStatus.SUCCESS;
+    }
+
+    // Tick child
+    const result = await this.child.tick(context);
+
+    switch (result) {
+      case NodeStatus.SUCCESS:
+        this.log(`Cycle ${this.currentCycle} succeeded`);
+        this.currentCycle++;
+
+        // Check if more cycles remain
+        if (this.currentCycle < this.numCycles) {
+          this.child.reset(); // Reset for next cycle
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+        } else {
+          // All cycles complete - don't reset after final cycle
+          this._status = NodeStatus.SUCCESS;
+          this.currentCycle = 0;
+          return NodeStatus.SUCCESS;
+        }
+
+      case NodeStatus.FAILURE:
+        this.log(`Cycle ${this.currentCycle} failed`);
+        this._status = NodeStatus.FAILURE;
+        this.currentCycle = 0;
+        return NodeStatus.FAILURE;
+
+      case NodeStatus.RUNNING:
+        this.log(`Cycle ${this.currentCycle} is running`);
+        this._status = NodeStatus.RUNNING;
+        return NodeStatus.RUNNING;
+
+      default:
+        throw new Error(`Unexpected status from child: ${result}`);
+    }
+  }
+
+  protected onReset(): void {
+    super.onReset();
+    this.currentCycle = 0;
+  }
+
+  protected onHalt(): void {
+    super.onHalt();
+    this.currentCycle = 0;
+  }
+}

package/src/decorators/run-once.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * RunOnce decorator configuration schema
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for RunOnce decorator configuration
+ * Uses base schema only (no additional properties)
+ */
+export const runOnceConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated RunOnce configuration type
+ */
+export type ValidatedRunOnceConfiguration = z.infer<
+  typeof runOnceConfigurationSchema
+>;

package/src/decorators/run-once.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Tests for RunOnce decorator
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { FailureNode, SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { RunOnce } from "./run-once.js";
+
+describe("RunOnce", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should execute child once", async () => {
+    const runOnce = new RunOnce({ id: "once1" });
+
+    let tickCount = 0;
+    class CountingNode extends SuccessNode {
+      async tick(context: TemporalContext) {
+        tickCount++;
+        return await super.tick(context);
+      }
+    }
+
+    runOnce.setChild(new CountingNode({ id: "child" }));
+
+    await runOnce.tick(context);
+    await runOnce.tick(context);
+    await runOnce.tick(context);
+
+    expect(tickCount).toBe(1); // Only executed once
+  });
+
+  it("should cache SUCCESS result", async () => {
+    const runOnce = new RunOnce({ id: "once1" });
+    runOnce.setChild(new SuccessNode({ id: "child" }));
+
+    const result1 = await runOnce.tick(context);
+    const result2 = await runOnce.tick(context);
+    const result3 = await runOnce.tick(context);
+
+    expect(result1).toBe(NodeStatus.SUCCESS);
+    expect(result2).toBe(NodeStatus.SUCCESS);
+    expect(result3).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should cache FAILURE result", async () => {
+    const runOnce = new RunOnce({ id: "once1" });
+    runOnce.setChild(new FailureNode({ id: "child" }));
+
+    const result1 = await runOnce.tick(context);
+    const result2 = await runOnce.tick(context);
+
+    expect(result1).toBe(NodeStatus.FAILURE);
+    expect(result2).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should not cache RUNNING result", async () => {
+    const runOnce = new RunOnce({ id: "once1" });
+
+    let tickCount = 0;
+    class RunningThenSuccess extends SuccessNode {
+      async tick(context: TemporalContext) {
+        tickCount++;
+        if (tickCount < 3) {
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+        }
+        return await super.tick(context);
+      }
+    }
+
+    runOnce.setChild(new RunningThenSuccess({ id: "child" }));
+
+    const result1 = await runOnce.tick(context); // RUNNING
+    const result2 = await runOnce.tick(context); // RUNNING
+    const result3 = await runOnce.tick(context); // SUCCESS (cached)
+    const result4 = await runOnce.tick(context); // SUCCESS (from cache)
+
+    expect(result1).toBe(NodeStatus.RUNNING);
+    expect(result2).toBe(NodeStatus.RUNNING);
+    expect(result3).toBe(NodeStatus.SUCCESS);
+    expect(result4).toBe(NodeStatus.SUCCESS);
+    expect(tickCount).toBe(3); // Ticked 3 times (not cached while RUNNING)
+  });
+
+  it("should reset cache on reset", async () => {
+    const runOnce = new RunOnce({ id: "once1" });
+
+    let tickCount = 0;
+    class CountingNode extends SuccessNode {
+      async tick(context: TemporalContext) {
+        tickCount++;
+        return await super.tick(context);
+      }
+    }
+
+    runOnce.setChild(new CountingNode({ id: "child" }));
+
+    // First execution
+    await runOnce.tick(context);
+    expect(tickCount).toBe(1);
+
+    // Second tick - should use cache
+    await runOnce.tick(context);
+    expect(tickCount).toBe(1);
+
+    // Reset
+    runOnce.reset();
+
+    // Third tick - should execute again
+    await runOnce.tick(context);
+    expect(tickCount).toBe(2);
+  });
+
+  it("should propagate ConfigurationError if no child", async () => {
+    const runOnce = new RunOnce({ id: "once1" });
+
+    try {
+      await runOnce.tick(context);
+      expect.fail("Should have thrown an error");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect((error as ConfigurationError).message).toContain(
+        "RunOnce requires a child",
+      );
+    }
+  });
+});

package/src/decorators/run-once.ts

@@ -0,0 +1,61 @@
+/**
+ * RunOnce decorator - Execute child only once per session
+ */
+
+import { DecoratorNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+/**
+ * RunOnce executes its child only once and caches the result.
+ * Subsequent ticks return the cached result without re-executing the child.
+ * Useful for initialization or one-time setup operations.
+ */
+export class RunOnce extends DecoratorNode {
+  private hasRun: boolean = false;
+  private cachedResult?: NodeStatus;
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError("RunOnce requires a child");
+    }
+
+    // Return cached result if already executed
+    if (this.hasRun) {
+      this.log(
+        `Already executed, returning cached result: ${this.cachedResult}`,
+      );
+      if (this.cachedResult === undefined) {
+        this._status = NodeStatus.RUNNING;
+        return NodeStatus.RUNNING;
+      }
+      this._status = this.cachedResult;
+      return this.cachedResult;
+    }
+
+    // Execute child for the first time
+    this.log("First execution - ticking child");
+    const result = await this.child.tick(context);
+
+    // Cache result only if not RUNNING
+    if (result !== NodeStatus.RUNNING) {
+      this.hasRun = true;
+      this.cachedResult = result;
+      this.log(`Caching result: ${result}`);
+    } else {
+      this.log("Child is running - will retry on next tick");
+    }
+
+    this._status = result;
+    return result;
+  }
+
+  protected onReset(): void {
+    super.onReset();
+    this.hasRun = false;
+    this.cachedResult = undefined;
+  }
+}

package/src/decorators/soft-assert.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * SoftAssert decorator configuration schema
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for SoftAssert decorator configuration
+ * Uses base schema only (no additional properties)
+ */
+export const softAssertConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated SoftAssert configuration type
+ */
+export type ValidatedSoftAssertConfiguration = z.infer<
+  typeof softAssertConfigurationSchema
+>;

package/src/decorators/soft-assert.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Tests for SoftAssert decorator
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { FailureNode, RunningNode, SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { SoftAssert } from "./soft-assert.js";
+
+describe("SoftAssert", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should convert FAILURE to SUCCESS", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+    soft.setChild(new FailureNode({ id: "child" }));
+
+    const result = await soft.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should propagate SUCCESS", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+    soft.setChild(new SuccessNode({ id: "child" }));
+
+    const result = await soft.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should propagate RUNNING", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+    soft.setChild(new RunningNode({ id: "child" }));
+
+    const result = await soft.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+  });
+
+  it("should log failures", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+    soft.setChild(new FailureNode({ id: "child" }));
+
+    await soft.tick(context);
+
+    const failures = soft.getFailures();
+    expect(failures).toHaveLength(1);
+    expect(failures[0]?.message).toContain("Soft assertion failed");
+  });
+
+  it("should track multiple failures", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+    soft.setChild(new FailureNode({ id: "child" }));
+
+    await soft.tick(context);
+    await soft.tick(context);
+    await soft.tick(context);
+
+    const failures = soft.getFailures();
+    expect(failures).toHaveLength(3);
+  });
+
+  it("should reset failure history on reset", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+    soft.setChild(new FailureNode({ id: "child" }));
+
+    await soft.tick(context);
+    await soft.tick(context);
+    expect(soft.hasFailures()).toBe(true);
+
+    soft.reset();
+    expect(soft.hasFailures()).toBe(false);
+    expect(soft.getFailures()).toHaveLength(0);
+  });
+
+  it("should provide hasFailures helper", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+    soft.setChild(new FailureNode({ id: "child" }));
+
+    expect(soft.hasFailures()).toBe(false);
+    await soft.tick(context);
+    expect(soft.hasFailures()).toBe(true);
+  });
+
+  it("should propagate ConfigurationError if no child", async () => {
+    const soft = new SoftAssert({ id: "soft1" });
+
+    try {
+      await soft.tick(context);
+      expect.fail("Should have thrown an error");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect((error as ConfigurationError).message).toContain(
+        "SoftAssert requires a child",
+      );
+    }
+  });
+});

package/src/decorators/soft-assert.ts

@@ -0,0 +1,68 @@
+/**
+ * SoftAssert decorator - Continue even if child fails
+ */
+
+import { DecoratorNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+/**
+ * SoftAssert converts child FAILURE to SUCCESS, allowing execution to continue.
+ * Logs all failures for later review but doesn't halt execution.
+ * Useful for non-critical checks that shouldn't block the test.
+ */
+export class SoftAssert extends DecoratorNode {
+  private failures: Array<{
+    timestamp: number;
+    message: string;
+  }> = [];
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError("SoftAssert requires a child");
+    }
+
+    const result = await this.child.tick(context);
+
+    if (result === NodeStatus.FAILURE) {
+      // Log failure
+      const failure = {
+        timestamp: Date.now(),
+        message: `Soft assertion failed: ${this.child.name}`,
+      };
+      this.failures.push(failure);
+
+      this.log(`Soft assertion failed (continuing): ${this.child.name}`);
+
+      // Convert FAILURE to SUCCESS
+      this._status = NodeStatus.SUCCESS;
+      return NodeStatus.SUCCESS;
+    }
+
+    // Propagate SUCCESS or RUNNING as-is
+    this._status = result;
+    return result;
+  }
+
+  /**
+   * Get all recorded failures
+   */
+  getFailures(): Array<{ timestamp: number; message: string }> {
+    return [...this.failures];
+  }
+
+  /**
+   * Check if any assertions have failed
+   */
+  hasFailures(): boolean {
+    return this.failures.length > 0;
+  }
+
+  protected onReset(): void {
+    super.onReset();
+    this.failures = [];
+  }
+}

package/src/decorators/timeout.schema.ts

@@ -0,0 +1,21 @@
+/**
+ * Timeout decorator configuration schema
+ */
+
+import { z } from "zod";
+import { createNodeSchema, validations } from "../schemas/base.schema.js";
+
+/**
+ * Schema for Timeout decorator configuration
+ * Validates that timeoutMs is a positive number
+ */
+export const timeoutConfigurationSchema = createNodeSchema("Timeout", {
+  timeoutMs: validations.positiveNumber("timeoutMs"),
+});
+
+/**
+ * Validated Timeout configuration type
+ */
+export type ValidatedTimeoutConfiguration = z.infer<
+  typeof timeoutConfigurationSchema
+>;