@q1k-oss/btree-workflows 0.0.1

package/src/decorators/invert.test.ts

@@ -0,0 +1,135 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { MockAction } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { Invert } from "./invert.js";
+
+describe("Invert", () => {
+  let context: TemporalContext;
+  let invert: Invert;
+
+  beforeEach(() => {
+    context = {
+      blackboard: new ScopedBlackboard(),
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+    invert = new Invert({ id: "test-invert" });
+  });
+
+  it("should propagate ConfigurationError if no child is set", async () => {
+    try {
+      await invert.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 invert SUCCESS to FAILURE", async () => {
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    invert.setChild(child);
+
+    const status = await invert.tick(context);
+    expect(status).toBe(NodeStatus.FAILURE);
+    expect(invert.status()).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should invert FAILURE to SUCCESS", async () => {
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.FAILURE,
+    });
+
+    invert.setChild(child);
+
+    const status = await invert.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(invert.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should pass through RUNNING status", async () => {
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.RUNNING,
+    });
+
+    invert.setChild(child);
+
+    const status = await invert.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+    expect(invert.status()).toBe(NodeStatus.RUNNING);
+  });
+
+  it("should pass through other statuses unchanged", async () => {
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.IDLE,
+    });
+
+    invert.setChild(child);
+
+    const status = await invert.tick(context);
+    expect(status).toBe(NodeStatus.IDLE);
+  });
+
+  it("should properly propagate halt to child", () => {
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.RUNNING,
+    });
+
+    invert.setChild(child);
+
+    // Set child to RUNNING state
+    (child as unknown)._status = NodeStatus.RUNNING;
+
+    // Halt the invert decorator
+    invert.halt();
+
+    expect(child.status()).toBe(NodeStatus.IDLE);
+  });
+
+  it("should properly propagate reset to child", () => {
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    invert.setChild(child);
+
+    // Set child to SUCCESS state
+    (child as unknown)._status = NodeStatus.SUCCESS;
+
+    // Reset the invert decorator
+    invert.reset();
+
+    expect(child.status()).toBe(NodeStatus.IDLE);
+  });
+
+  it("should work with async children", async () => {
+    const child = new MockAction({
+      id: "child",
+      returnStatus: NodeStatus.SUCCESS,
+      ticksBeforeComplete: 2, // Will return RUNNING first
+    });
+
+    invert.setChild(child);
+
+    // First tick - child returns RUNNING
+    let status = await invert.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    // Second tick - child returns SUCCESS, inverted to FAILURE
+    status = await invert.tick(context);
+    expect(status).toBe(NodeStatus.FAILURE);
+  });
+});

package/src/decorators/invert.ts

@@ -0,0 +1,42 @@
+/**
+ * Invert decorator node
+ * Inverts the result of its child (SUCCESS becomes FAILURE and vice versa)
+ */
+
+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";
+
+export class Invert extends DecoratorNode {
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError(`${this.name}: Decorator must have a child`);
+    }
+
+    this.log("Ticking child");
+    const childStatus = await this.child.tick(context);
+
+    switch (childStatus) {
+      case NodeStatus.SUCCESS:
+        this.log("Child succeeded - returning FAILURE");
+        this._status = NodeStatus.FAILURE;
+        return NodeStatus.FAILURE;
+
+      case NodeStatus.FAILURE:
+        this.log("Child failed - returning SUCCESS");
+        this._status = NodeStatus.SUCCESS;
+        return NodeStatus.SUCCESS;
+
+      case NodeStatus.RUNNING:
+        this.log("Child is running");
+        this._status = NodeStatus.RUNNING;
+        return NodeStatus.RUNNING;
+
+      default:
+        return childStatus;
+    }
+  }
+}

package/src/decorators/keep-running.schema.ts

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

package/src/decorators/keep-running.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Tests for KeepRunningUntilFailure 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 { KeepRunningUntilFailure } from "./keep-running.js";
+
+describe("KeepRunningUntilFailure", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  it("should return RUNNING while child succeeds", async () => {
+    const keep = new KeepRunningUntilFailure({ id: "keep1" });
+    keep.setChild(new SuccessNode({ id: "child" }));
+
+    const result = await keep.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+  });
+
+  it("should return SUCCESS on child failure", async () => {
+    const keep = new KeepRunningUntilFailure({ id: "keep1" });
+    keep.setChild(new FailureNode({ id: "child" }));
+
+    const result = await keep.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should reset child between ticks", async () => {
+    const keep = new KeepRunningUntilFailure({ id: "keep1" });
+
+    let tickCount = 0;
+    class CountingNode extends SuccessNode {
+      tick(context: TemporalContext) {
+        tickCount++;
+        return super.tick(context);
+      }
+    }
+
+    keep.setChild(new CountingNode({ id: "child" }));
+
+    await keep.tick(context);
+    await keep.tick(context);
+    await keep.tick(context);
+
+    expect(tickCount).toBe(3); // Ticked 3 times (reset between each)
+  });
+
+  it("should propagate RUNNING from child", async () => {
+    const keep = new KeepRunningUntilFailure({ id: "keep1" });
+
+    let tickCount = 0;
+    class RunningThenFail extends SuccessNode {
+      tick(_context: TemporalContext) {
+        const self = this;
+        return (async () => {
+          tickCount++;
+          if (tickCount < 3) {
+            self._status = NodeStatus.RUNNING;
+            return NodeStatus.RUNNING;
+          }
+          self._status = NodeStatus.FAILURE;
+          return NodeStatus.FAILURE;
+        })();
+      }
+    }
+
+    keep.setChild(new RunningThenFail({ id: "child" }));
+
+    let result = await keep.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+
+    result = await keep.tick(context);
+    expect(result).toBe(NodeStatus.RUNNING);
+
+    result = await keep.tick(context);
+    expect(result).toBe(NodeStatus.SUCCESS); // Child failed
+  });
+
+  it("should propagate ConfigurationError if no child", async () => {
+    const keep = new KeepRunningUntilFailure({ id: "keep1" });
+
+    try {
+      await keep.tick(context);
+      throw new Error("Expected tick to throw");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect((error as ConfigurationError).message).toContain(
+        "KeepRunningUntilFailure requires a child",
+      );
+    }
+  });
+});

package/src/decorators/keep-running.ts

@@ -0,0 +1,49 @@
+/**
+ * KeepRunningUntilFailure decorator
+ * Opposite of Retry - keeps running while child succeeds
+ */
+
+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";
+
+/**
+ * KeepRunningUntilFailure keeps executing its child while it succeeds.
+ * Returns SUCCESS when child fails (goal achieved).
+ * Returns RUNNING while child succeeds (keep going).
+ */
+export class KeepRunningUntilFailure extends DecoratorNode {
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    checkSignal(context.signal);
+
+    if (!this.child) {
+      throw new ConfigurationError(
+        "KeepRunningUntilFailure requires a child",
+      );
+    }
+
+    const result = await this.child.tick(context);
+
+    switch (result) {
+      case NodeStatus.SUCCESS:
+        this.log("Child succeeded - resetting and continuing");
+        this.child.reset();
+        this._status = NodeStatus.RUNNING;
+        return NodeStatus.RUNNING;
+
+      case NodeStatus.FAILURE:
+        this.log("Child failed - goal achieved");
+        this._status = NodeStatus.SUCCESS;
+        return NodeStatus.SUCCESS;
+
+      case NodeStatus.RUNNING:
+        this.log("Child is running");
+        this._status = NodeStatus.RUNNING;
+        return NodeStatus.RUNNING;
+
+      default:
+        throw new Error(`Unexpected status from child: ${result}`);
+    }
+  }
+}

package/src/decorators/precondition.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * Precondition decorator configuration schema
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for Precondition decorator configuration
+ * Uses base schema only - preconditions are set programmatically via API
+ */
+export const preconditionConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated Precondition configuration type
+ */
+export type ValidatedPreconditionConfiguration = z.infer<
+  typeof preconditionConfigurationSchema
+>;