@q1k-oss/btree-workflows 0.0.1

package/examples/yaml-workflows/README.md

@@ -0,0 +1,211 @@
+# YAML Workflow Examples
+
+This directory contains curated YAML workflow examples demonstrating the power and flexibility of declarative behavior tree definitions.
+
+## ✅ Working Examples
+
+These workflows are actively tested with Temporal and demonstrate production-ready patterns.
+
+### 01-simple-sequence.yaml
+**Complexity**: Low
+**Pattern**: Sequential execution
+**Nodes**: 4 nodes, 1 level deep
+
+Basic sequence of print actions. Perfect for getting started and testing the YAML workflow system.
+
+**Use cases:**
+- Learning YAML workflow format
+- Testing Temporal integration
+- Simple linear processes
+
+---
+
+### 02-parallel-timeout.yaml
+**Complexity**: Low-Medium
+**Pattern**: Parallel execution with timeout protection
+**Nodes**: 6 nodes, 3 levels deep
+
+Demonstrates concurrent task execution with timeout wrapper. All tasks must complete within 5 seconds.
+
+**Patterns demonstrated:**
+- Parallel execution (strict strategy)
+- Timeout decorator
+- Sequential flow with parallel section
+
+**Use cases:**
+- Concurrent API calls
+- Parallel data fetching
+- Time-critical operations
+
+---
+
+### 05-order-processing.yaml
+**Complexity**: High
+**Pattern**: Multi-phase workflow with parallel operations
+**Nodes**: 20+ nodes, 5 levels deep
+
+**Real-world e-commerce order processing workflow with 3 phases:**
+
+**Phase 1: Validation**
+- Parallel validation checks (inventory, payment, shipping)
+- 5-second timeout protection
+
+**Phase 2: Payment Processing**
+- Sequential payment flow
+- 1-second simulated delay
+- 10-second timeout
+
+**Phase 3: Order Fulfillment**
+- Parallel fulfillment tasks (inventory update, shipping label, email)
+- 500ms delays for each task
+
+**Patterns demonstrated:**
+- Nested sequences
+- Parallel execution at multiple levels
+- Multiple timeout wrappers
+- Delay decorators
+- Multi-phase workflow structure
+
+**Use cases:**
+- E-commerce checkout flows
+- Multi-step transaction processing
+- Complex orchestration workflows
+
+---
+
+## 📝 Reference Examples (Not Tested)
+
+These workflows showcase advanced patterns but contain node types that may require additional setup.
+
+### 03-ecommerce-checkout.yaml
+**Complexity**: Medium
+**Patterns**: Conditional logic, CheckCondition nodes, complex validation
+**Note**: Requires CheckCondition and additional node types to be registered
+
+Multi-phase checkout with validation, payment processing, and parallel post-checkout tasks.
+
+---
+
+### 04-ai-agent-workflow.yaml
+**Complexity**: Very High
+**Patterns**: Decision trees, iterative processing, complex routing
+**Note**: AI-generated workflow showcasing LLM's strength at complex decision logic
+
+Multi-step AI agent with decision routing, iterative research, quality checks, and fallback handling.
+
+**Key Insight**: This demonstrates where LLMs excel - generating complex decision logic that would be tedious to build manually.
+
+---
+
+## Usage
+
+### Running with Temporal
+
+```bash
+# Terminal 1: Start Temporal server
+temporal server start-dev
+
+# Terminal 2: Build and start worker
+npm run build
+cd examples/temporal
+npx tsx worker.ts
+
+# Terminal 3: Execute workflows
+cd examples/temporal
+npx tsx client.ts
+```
+
+### Loading in Your Code
+
+```typescript
+import { readFileSync } from 'fs';
+import { loadTreeFromYaml, Registry, registerStandardNodes } from '@wayfarer-ai/btree';
+
+// Setup registry with all built-in nodes
+const registry = new Registry();
+registerStandardNodes(registry);
+
+// Optionally register your custom nodes
+// registry.register('MyCustomAction', MyCustomAction, { category: 'action' });
+
+// Load YAML
+const yamlContent = readFileSync('./01-simple-sequence.yaml', 'utf-8');
+const tree = loadTreeFromYaml(yamlContent, registry);
+
+// Execute
+await tree.execute();
+```
+
+### With Temporal
+
+```typescript
+import { yamlWorkflow } from './yaml-workflow-loader.js';
+
+// In client
+const yamlContent = readFileSync('./workflow.yaml', 'utf-8');
+
+const result = await client.workflow.execute("yamlWorkflow", {
+  taskQueue: "btree-workflows",
+  workflowId: `my-workflow-${Date.now()}`,
+  args: [{
+    input: {},
+    treeRegistry: new Registry(),
+    yamlContent
+  }]
+});
+```
+
+## Node Types Reference
+
+### All Standard Nodes (via `registerStandardNodes()`)
+
+The `registerStandardNodes()` utility automatically registers all built-in nodes:
+
+**Composites (10):**
+- Sequence, Selector, Parallel
+- Conditional, ForEach, While
+- Recovery, ReactiveSequence, MemorySequence
+- SubTree
+
+**Decorators (10):**
+- Timeout, Delay, Repeat
+- Invert, ForceSuccess, ForceFailure
+- RunOnce, KeepRunningUntilFailure
+- Precondition, SoftAssert
+
+**Actions/Conditions (9):**
+- PrintAction, MockAction, CounterAction
+- CheckCondition, AlwaysCondition, WaitAction
+- Script, LogMessage, RegexExtract
+
+**Test Nodes (3):**
+- SuccessNode, FailureNode, RunningNode
+
+### Adding Custom Nodes
+
+```typescript
+import { Registry, registerStandardNodes } from "@wayfarer-ai/btree";
+import { MyCustomNode } from "./my-nodes.js";
+
+const registry = new Registry();
+registerStandardNodes(registry);  // Register all built-in nodes
+
+// Add your custom nodes
+registry.register("MyCustomNode", MyCustomNode, { category: "action" });
+```
+
+## Benefits of YAML Workflows
+
+✅ **Declarative** - Define what, not how
+✅ **Version Controlled** - Track workflow changes in git
+✅ **AI-Friendly** - Easy for LLMs to generate and modify
+✅ **Validated** - 4-stage validation catches errors early
+✅ **Type-Safe** - Runtime validation via Zod schemas
+✅ **Portable** - Same YAML works standalone or in Temporal
+✅ **Readable** - Non-developers can understand workflow logic
+
+## Complete Documentation
+
+- [YAML Specification](../../docs/yaml-specification.md) - Complete format reference
+- [Temporal Integration](../temporal/README.md) - Running YAML workflows in Temporal
+- [Node Reference](../../docs/workflow-engine/02-node-reference.md) - All available node types

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@q1k-oss/btree-workflows",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "dev": "tsup-node src/index.ts --watch --format cjs,esm --dts",
+    "build": "npm run clean && tsup-node src/index.ts --format cjs,esm --dts",
+    "typecheck": "tsc --noEmit",
+    "test": "CI=true vitest --coverage",
+    "test:watch": "vitest --watch",
+    "test:ui": "vitest --ui"
+  },
+  "dependencies": {
+    "@activepieces/piece-google-sheets": "^0.14.0",
+    "@activepieces/pieces-framework": "^0.23.0",
+    "@temporalio/activity": "^1.10.0",
+    "@temporalio/workflow": "^1.10.0",
+    "js-yaml": "^4.1.1",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@temporalio/client": "^1.10.0",
+    "@temporalio/testing": "^1.10.0",
+    "@temporalio/worker": "^1.10.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.2.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.2",
+    "typescript": "latest",
+    "vitest": "^3.2.4"
+  }
+}

package/src/actions/code-execution.schema.ts

@@ -0,0 +1,27 @@
+/**
+ * Zod schema for CodeExecution node validation
+ */
+
+import { z } from "zod";
+import { createNodeSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for CodeExecution node props
+ */
+export const codeExecutionSchema = createNodeSchema("CodeExecution", {
+  /** Code to execute */
+  code: z.string().min(1, "Code is required"),
+
+  /** Programming language */
+  language: z.enum(["javascript", "python"], {
+    message: "Language must be 'javascript' or 'python'",
+  }),
+
+  /** Execution timeout in milliseconds */
+  timeout: z.number().int().positive().optional().default(30000),
+
+  /** Python packages to install before execution */
+  packages: z.array(z.string()).optional().default([]),
+});
+
+export type CodeExecutionSchemaType = z.infer<typeof codeExecutionSchema>;

package/src/actions/code-execution.ts

@@ -0,0 +1,218 @@
+/**
+ * CodeExecution Node
+ *
+ * Executes JavaScript or Python code in a secure sandboxed environment
+ * via Microsandbox (libkrun microVM). This node replaces the inline Script
+ * node for production use where untrusted/AI-generated code needs isolation.
+ *
+ * Features:
+ * - Support for JavaScript and Python
+ * - Full VM isolation (no network, no filesystem, no cloud credentials)
+ * - DataStore integration for large payloads
+ * - getBB/setBB helpers for blackboard access
+ * - getInput helper for workflow input access
+ * - Configurable timeout
+ * - Python package installation support
+ *
+ * Security:
+ * - Code runs in Microsandbox microVM
+ * - No cloud credentials exposed to sandbox
+ * - Activity fetches data from DataStore, not the sandbox
+ * - Only JSON data crosses the sandbox boundary
+ */
+
+import { ActionNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  type CodeExecutionRequest,
+  type DataRef,
+  NodeStatus,
+} from "../types.js";
+import { isDataRef } from "../data-store/types.js";
+
+/**
+ * Configuration for CodeExecution node
+ */
+export interface CodeExecutionConfig extends NodeConfiguration {
+  /** Code to execute */
+  code: string;
+  /** Programming language: 'javascript' or 'python' */
+  language: "javascript" | "python";
+  /** Execution timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Python packages to install before execution */
+  packages?: string[];
+}
+
+/**
+ * CodeExecution Node
+ *
+ * Executes code in a sandboxed environment via Temporal activity.
+ * Requires the `executeCode` activity to be configured.
+ *
+ * @example YAML (JavaScript)
+ * ```yaml
+ * type: CodeExecution
+ * id: transform-data
+ * props:
+ *   language: javascript
+ *   code: |
+ *     const users = getBB('apiUsers');
+ *     const processed = users.map(u => ({
+ *       id: u.id,
+ *       name: u.name.toUpperCase()
+ *     }));
+ *     setBB('processedUsers', processed);
+ *   timeout: 30000
+ * ```
+ *
+ * @example YAML (Python)
+ * ```yaml
+ * type: CodeExecution
+ * id: analyze-data
+ * props:
+ *   language: python
+ *   packages:
+ *     - pandas
+ *   code: |
+ *     import pandas as pd
+ *
+ *     users = getBB('apiUsers')
+ *     df = pd.DataFrame(users)
+ *
+ *     setBB('userCount', len(df))
+ *     setBB('domains', df['email'].str.split('@').str[1].unique().tolist())
+ *   timeout: 60000
+ * ```
+ *
+ * Available functions in sandbox:
+ * - getBB(key): Get value from blackboard
+ * - setBB(key, value): Set value on blackboard
+ * - getInput(key): Get value from workflow input (read-only)
+ */
+export class CodeExecution extends ActionNode {
+  private code: string;
+  private language: "javascript" | "python";
+  private timeout: number;
+  private packages: string[];
+
+  constructor(config: CodeExecutionConfig) {
+    super(config);
+
+    if (!config.code) {
+      throw new ConfigurationError("CodeExecution requires code");
+    }
+
+    if (!config.language) {
+      throw new ConfigurationError("CodeExecution requires language");
+    }
+
+    if (!["javascript", "python"].includes(config.language)) {
+      throw new ConfigurationError(
+        `CodeExecution language must be 'javascript' or 'python', got: ${config.language}`
+      );
+    }
+
+    this.code = config.code;
+    this.language = config.language;
+    this.timeout = config.timeout ?? 30000;
+    this.packages = config.packages ?? [];
+  }
+
+  protected async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    // Validate activity is available
+    if (!context.activities?.executeCode) {
+      this._lastError =
+        "CodeExecution requires activities.executeCode to be configured. " +
+        "This activity handles sandboxed code execution via Microsandbox.";
+      this.log(`Error: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+
+    try {
+      // Separate DataRefs from inline values in blackboard
+      const dataRefs: Record<string, DataRef> = {};
+      const inlineContext: Record<string, unknown> = {};
+
+      for (const [key, value] of Object.entries(context.blackboard.toJSON())) {
+        if (isDataRef(value)) {
+          dataRefs[key] = value;
+        } else {
+          inlineContext[key] = value;
+        }
+      }
+
+      // Build the request
+      const request: CodeExecutionRequest = {
+        code: this.code,
+        language: this.language,
+        dataRefs,
+        context: inlineContext,
+        input: context.input ? { ...context.input } : undefined,
+        timeout: this.timeout,
+        packages: this.packages.length > 0 ? this.packages : undefined,
+        workflowId: context.workflowInfo?.workflowId,
+      };
+
+      this.log(
+        `Executing ${this.language} code (timeout: ${this.timeout}ms, packages: ${this.packages.length})`
+      );
+
+      // Execute in sandbox via activity
+      const result = await context.activities.executeCode(request);
+
+      // Log any output from the sandbox
+      if (result.logs.length > 0) {
+        for (const log of result.logs) {
+          this.log(`[sandbox] ${log}`);
+        }
+      }
+
+      // Merge results back to blackboard
+      for (const [key, value] of Object.entries(result.values)) {
+        context.blackboard.set(key, value);
+      }
+
+      // Store DataRefs for large results
+      for (const [key, ref] of Object.entries(result.dataRefs)) {
+        context.blackboard.set(key, ref);
+      }
+
+      this.log(
+        `Code execution completed in ${result.executionTimeMs}ms ` +
+          `(${Object.keys(result.values).length} values, ${Object.keys(result.dataRefs).length} refs)`
+      );
+
+      return NodeStatus.SUCCESS;
+    } catch (error) {
+      // Extract the actual error message from Temporal's ActivityFailure chain
+      // ActivityFailure -> ApplicationFailure -> cause -> actual error
+      let actualMessage = error instanceof Error ? error.message : String(error);
+
+      // Try to extract the actual cause from Temporal's error chain
+      if (error && typeof error === "object") {
+        const err = error as {
+          cause?: {
+            message?: string;
+            cause?: { message?: string };
+          };
+        };
+        // ActivityFailure.cause is ApplicationFailure
+        // ApplicationFailure.cause.message is the actual error
+        if (err.cause?.cause?.message) {
+          actualMessage = err.cause.cause.message;
+        } else if (err.cause?.message) {
+          actualMessage = err.cause.message;
+        }
+      }
+
+      this.log(`Code execution failed: ${actualMessage}`);
+
+      // Re-throw with the extracted message so ActionNode's error handler
+      // can emit ERROR event with the actual error context
+      throw new Error(`Code execution failed: ${actualMessage}`);
+    }
+  }
+}