@q1k-oss/btree-workflows 0.0.1

package/examples/temporal/README.md

@@ -0,0 +1,117 @@
+# Temporal Activity Test
+
+This directory contains examples for running btree workflows with Temporal, including activity execution for I/O operations.
+
+## Prerequisites
+
+1. **Temporal Server** - Running locally on `localhost:7233`
+   ```bash
+   # Option 1: Use Temporal CLI (recommended for testing)
+   brew install temporal
+   temporal server start-dev
+
+   # Option 2: Use Docker
+   docker-compose up -d
+   ```
+
+2. **Build btree** - The dist folder must be built
+   ```bash
+   cd /path/to/btree
+   npm run build
+   ```
+
+## Running the Test
+
+### 1. Start the Worker (Terminal 1)
+
+```bash
+cd /path/to/btree/examples/temporal
+
+# For mock activities (no real API calls)
+BTREE_MOCK_ACTIVITIES=true npx tsx worker.ts
+
+# For real activities (requires actual credentials)
+# GOOGLE_SHEETS_ACCESS_TOKEN=xxx npx tsx worker.ts
+```
+
+You should see:
+```
+🚀 Starting Temporal worker for behavior tree workflows...
+📦 Bundling workflows...
+✅ Workflows bundled successfully
+✅ Worker started successfully!
+📋 Task Queue: btree-workflows
+🔄 Listening for workflow tasks...
+```
+
+### 2. Run the Client (Terminal 2)
+
+```bash
+cd /path/to/btree/examples/temporal
+npx tsx client.ts
+```
+
+You should see:
+```
+🔌 Connecting to Temporal server at localhost:7233...
+✅ Connected to Temporal server
+
+============================================================
+Workflow: Activity Test (IntegrationAction via Activity)
+============================================================
+✅ Result: { status: 'SUCCESS', output: { ... } }
+```
+
+## What's Being Tested
+
+The activity test workflow (`06-activity-test.yaml`) demonstrates:
+
+1. **IntegrationAction with Activities** - The `IntegrationAction` node uses `context.activities.executePieceAction` instead of inline execution, making it deterministic for Temporal replay.
+
+2. **Mock Token Provider** - The `yaml-workflow-loader.ts` includes a mock token provider for testing without real OAuth credentials.
+
+3. **Mock Activity Responses** - When `BTREE_MOCK_ACTIVITIES=true`, activities return simulated responses instead of making real API calls.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `worker.ts` | Temporal worker that registers workflows and activities |
+| `client.ts` | Client that executes workflows |
+| `activities.ts` | Activity implementations (run outside workflow sandbox) |
+| `yaml-workflow-loader.ts` | Workflow that loads YAML and passes activities to btree |
+| `workflows.ts` | Re-exports workflows for Temporal bundler |
+
+## Activity Flow
+
+```
+Client                Worker (Workflow)              Worker (Activity)
+  |                         |                              |
+  | execute(workflow)       |                              |
+  |------------------------>|                              |
+  |                         |                              |
+  |                         | IntegrationAction.tick()     |
+  |                         |   -> context.activities      |
+  |                         |      .executePieceAction()   |
+  |                         |                              |
+  |                         |----------- activity -------->|
+  |                         |                              |
+  |                         |                              | executePieceActionActivity()
+  |                         |                              |   -> executePieceAction()
+  |                         |                              |   -> API call (or mock)
+  |                         |                              |
+  |                         |<---------- result -----------|
+  |                         |                              |
+  |                         | Store result in blackboard   |
+  |                         |                              |
+  |<-- WorkflowResult ------|                              |
+```
+
+## Node Behavior Summary
+
+| Node | Activity Required | Standalone Fallback |
+|------|-------------------|---------------------|
+| `IntegrationAction` | Optional | Yes (inline execution) |
+| `PythonScript` | **Required** | No (needs Python worker) |
+| `ParseFile` | **Required** | No (needs file I/O) |
+| `GenerateFile` | **Required** | No (needs file I/O) |

package/examples/temporal/activities.ts

@@ -0,0 +1,373 @@
+/**
+ * Activity implementations for btree workflows
+ *
+ * These run in the worker process (outside the workflow sandbox)
+ * and handle all I/O operations deterministically for Temporal.
+ */
+
+import {
+  executePieceAction,
+  type PieceActivityRequest,
+  type PythonScriptRequest,
+  type PythonScriptResult,
+  type ParseFileRequest,
+  type ParseFileResult,
+  type GenerateFileRequest,
+  type GenerateFileResult,
+  type HttpRequestActivity,
+  type HttpResponseActivity,
+} from "../../dist/index.js";
+
+/**
+ * Execute an Active Pieces action
+ * This wraps the btree executePieceAction for use as a Temporal activity
+ */
+export async function executePieceActionActivity(
+  request: PieceActivityRequest
+): Promise<unknown> {
+  console.log(
+    `[Activity] executePieceAction: ${request.provider}/${request.action}`
+  );
+  console.log(`[Activity] Inputs:`, JSON.stringify(request.inputs, null, 2));
+
+  // For testing without actual credentials, we can mock responses
+  if (process.env.BTREE_MOCK_ACTIVITIES === "true") {
+    console.log(`[Activity] MOCK MODE - returning simulated response`);
+    return mockPieceAction(request);
+  }
+
+  // Real execution via Active Pieces
+  const result = await executePieceAction(request);
+  console.log(`[Activity] Result:`, JSON.stringify(result, null, 2));
+  return result;
+}
+
+/**
+ * Execute Python code (placeholder - would need Python worker)
+ */
+export async function executePythonScriptActivity(
+  request: PythonScriptRequest
+): Promise<PythonScriptResult> {
+  console.log(`[Activity] executePythonScript`);
+  console.log(`[Activity] Code length: ${request.code.length} chars`);
+
+  // Mock implementation for testing
+  if (process.env.BTREE_MOCK_ACTIVITIES === "true") {
+    console.log(`[Activity] MOCK MODE - returning simulated Python result`);
+    return {
+      blackboard: request.blackboard,
+      stdout: "Mock Python execution",
+      stderr: "",
+    };
+  }
+
+  // Real implementation would call a Python worker via gRPC or subprocess
+  throw new Error(
+    "Real Python execution requires a Python worker. Set BTREE_MOCK_ACTIVITIES=true for testing."
+  );
+}
+
+/**
+ * Parse a file (CSV/Excel)
+ */
+export async function parseFileActivity(
+  request: ParseFileRequest
+): Promise<ParseFileResult> {
+  console.log(`[Activity] parseFile: ${request.file}`);
+
+  // Mock implementation for testing
+  if (process.env.BTREE_MOCK_ACTIVITIES === "true") {
+    console.log(`[Activity] MOCK MODE - returning simulated parsed data`);
+    return {
+      data: [
+        { orderId: "ORD-001", product: "Widget", quantity: 5, price: 10.99 },
+        { orderId: "ORD-002", product: "Gadget", quantity: 3, price: 24.99 },
+        { orderId: "ORD-003", product: "Gizmo", quantity: 10, price: 5.49 },
+      ],
+      rowCount: 3,
+      columns: ["orderId", "product", "quantity", "price"],
+    };
+  }
+
+  // Real implementation would use papaparse for CSV, xlsx for Excel
+  throw new Error(
+    "Real file parsing requires file system access. Set BTREE_MOCK_ACTIVITIES=true for testing."
+  );
+}
+
+/**
+ * Generate a file (CSV/Excel/JSON)
+ */
+export async function generateFileActivity(
+  request: GenerateFileRequest
+): Promise<GenerateFileResult> {
+  console.log(`[Activity] generateFile: ${request.filename} (${request.format})`);
+  console.log(`[Activity] Data rows: ${request.data.length}`);
+
+  // Mock implementation for testing
+  if (process.env.BTREE_MOCK_ACTIVITIES === "true") {
+    console.log(`[Activity] MOCK MODE - returning simulated file metadata`);
+    return {
+      filename: request.filename,
+      contentType: getContentType(request.format),
+      size: JSON.stringify(request.data).length,
+      path: `/tmp/${request.filename}`,
+      url:
+        request.storage === "persistent"
+          ? `https://storage.example.com/files/${request.filename}`
+          : undefined,
+    };
+  }
+
+  // Real implementation would use json2csv, xlsx, etc.
+  throw new Error(
+    "Real file generation requires file system access. Set BTREE_MOCK_ACTIVITIES=true for testing."
+  );
+}
+
+/**
+ * Fetch a URL (HTTP request)
+ * Uses native fetch() API with timeout support via AbortController
+ */
+export async function fetchUrlActivity(
+  request: HttpRequestActivity
+): Promise<HttpResponseActivity> {
+  console.log(`[Activity] fetchUrl: ${request.method} ${request.url}`);
+
+  // Mock implementation for testing
+  if (process.env.BTREE_MOCK_ACTIVITIES === "true") {
+    console.log(`[Activity] MOCK MODE - returning simulated HTTP response`);
+    return mockFetchUrl(request);
+  }
+
+  // Real implementation using native fetch
+  const controller = new AbortController();
+  const timeoutId = request.timeout
+    ? setTimeout(() => controller.abort(), request.timeout)
+    : null;
+
+  try {
+    const fetchOptions: RequestInit = {
+      method: request.method,
+      headers: request.headers,
+      signal: controller.signal,
+    };
+
+    // Add body for non-GET requests
+    if (request.body !== undefined && request.method !== "GET") {
+      fetchOptions.body =
+        typeof request.body === "string"
+          ? request.body
+          : JSON.stringify(request.body);
+    }
+
+    const response = await fetch(request.url, fetchOptions);
+
+    // Extract headers into a plain object
+    const headers: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    // Parse response based on content type
+    const contentType = response.headers.get("content-type") || "";
+    let data: unknown;
+
+    if (contentType.includes("application/json")) {
+      data = await response.json();
+    } else if (contentType.includes("text/")) {
+      data = await response.text();
+    } else {
+      // For binary data, convert to base64
+      const buffer = await response.arrayBuffer();
+      data = Buffer.from(buffer).toString("base64");
+    }
+
+    console.log(`[Activity] fetchUrl response: ${response.status}`);
+    return {
+      status: response.status,
+      headers,
+      data,
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Request timed out after ${request.timeout}ms`);
+    }
+    throw error;
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mock Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function mockPieceAction(request: PieceActivityRequest): unknown {
+  const { provider, action, inputs } = request;
+
+  // Google Sheets mocks
+  if (provider === "google-sheets" || provider === "google") {
+    if (action === "append_row" || action === "insert_row") {
+      return {
+        spreadsheetId: inputs.spreadsheetId,
+        updatedRange: "Sheet1!A1:C1",
+        updatedRows: 1,
+        updatedColumns: (inputs.values as unknown[])?.length || 3,
+        updatedCells: (inputs.values as unknown[])?.length || 3,
+      };
+    }
+    if (action === "get_values" || action === "read_rows") {
+      return {
+        values: [
+          ["Header1", "Header2", "Header3"],
+          ["Value1", "Value2", "Value3"],
+          ["Value4", "Value5", "Value6"],
+        ],
+      };
+    }
+  }
+
+  // Slack mocks
+  if (provider === "slack") {
+    if (action === "send_message" || action === "post_message") {
+      return {
+        ok: true,
+        channel: inputs.channel || "#general",
+        ts: `${Date.now()}.000000`,
+        message: {
+          text: inputs.text || inputs.message,
+          ts: `${Date.now()}.000000`,
+        },
+      };
+    }
+  }
+
+  // OpenAI mocks
+  if (provider === "openai") {
+    if (action === "chat" || action === "ask_chatgpt") {
+      return {
+        id: `chatcmpl-${Date.now()}`,
+        choices: [
+          {
+            message: {
+              role: "assistant",
+              content: "This is a mock response from the AI assistant.",
+            },
+            finish_reason: "stop",
+          },
+        ],
+        usage: { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 },
+      };
+    }
+  }
+
+  // Default mock response
+  return {
+    success: true,
+    provider,
+    action,
+    timestamp: new Date().toISOString(),
+    mock: true,
+  };
+}
+
+function mockFetchUrl(request: HttpRequestActivity): HttpResponseActivity {
+  const { url, method } = request;
+
+  // Simulate different API responses based on URL patterns
+  if (url.includes("/users")) {
+    if (method === "GET") {
+      return {
+        status: 200,
+        headers: { "content-type": "application/json" },
+        data: {
+          id: 1,
+          name: "Mock User",
+          email: "mock@example.com",
+        },
+      };
+    }
+    if (method === "POST") {
+      return {
+        status: 201,
+        headers: { "content-type": "application/json" },
+        data: {
+          id: 123,
+          success: true,
+          message: "User created",
+        },
+      };
+    }
+  }
+
+  if (url.includes("/orders")) {
+    if (method === "POST") {
+      return {
+        status: 201,
+        headers: { "content-type": "application/json" },
+        data: {
+          orderId: `ORD-${Date.now()}`,
+          status: "created",
+          timestamp: new Date().toISOString(),
+        },
+      };
+    }
+    if (method === "GET") {
+      return {
+        status: 200,
+        headers: { "content-type": "application/json" },
+        data: {
+          orders: [
+            { id: "ORD-001", total: 99.99, status: "shipped" },
+            { id: "ORD-002", total: 149.99, status: "pending" },
+          ],
+        },
+      };
+    }
+  }
+
+  if (url.includes("/error")) {
+    return {
+      status: 500,
+      headers: { "content-type": "application/json" },
+      data: { error: "Internal Server Error", mock: true },
+    };
+  }
+
+  if (url.includes("/not-found")) {
+    return {
+      status: 404,
+      headers: { "content-type": "application/json" },
+      data: { error: "Not Found", mock: true },
+    };
+  }
+
+  // Default success response
+  return {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    data: {
+      success: true,
+      url,
+      method,
+      timestamp: new Date().toISOString(),
+      mock: true,
+    },
+  };
+}
+
+function getContentType(format: string): string {
+  switch (format) {
+    case "csv":
+      return "text/csv";
+    case "xlsx":
+      return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    case "json":
+      return "application/json";
+    default:
+      return "application/octet-stream";
+  }
+}

package/examples/temporal/client.ts

@@ -0,0 +1,115 @@
+/**
+ * Temporal Client
+ * Executes YAML-defined behavior tree workflows on Temporal server
+ */
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { Connection, Client } from "@temporalio/client";
+import { Registry } from "../../dist/index.js";
+import type { YamlWorkflowArgs } from "./yaml-workflow-loader.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function run() {
+  console.log("🔌 Connecting to Temporal server at localhost:7233...");
+
+  const connection = await Connection.connect({
+    address: "localhost:7233",
+  });
+
+  const client = new Client({ connection });
+  console.log("✅ Connected to Temporal server\n");
+
+  // Create tree registry (required for SubTree nodes)
+  const treeRegistry = new Registry();
+
+  // Load YAML workflows
+  const workflows = [
+    {
+      name: "Simple Sequence",
+      file: "../yaml-workflows/01-simple-sequence.yaml",
+      id: "simple-sequence",
+      input: {},
+    },
+    {
+      name: "Parallel with Timeout",
+      file: "../yaml-workflows/02-parallel-timeout.yaml",
+      id: "parallel-timeout",
+      input: {},
+    },
+    {
+      name: "Activity Test (IntegrationAction via Activity)",
+      file: "../yaml-workflows/07-activity-simple-test.yaml",
+      id: "activity-test",
+      input: {
+        spreadsheetId: "test-spreadsheet-123",
+        orderId: "ORD-" + Date.now(),
+        customerName: "John Doe",
+        amount: 99.99,
+      },
+    },
+    // {
+    //   name: "Order Processing",
+    //   file: "../yaml-workflows/05-order-processing.yaml",
+    //   id: "order-processing",
+    //   input: {},
+    // },
+    // Complex workflows (comment out for initial test)
+    // {
+    //   name: "E-commerce Checkout",
+    //   file: "../yaml-workflows/03-ecommerce-checkout.yaml",
+    //   id: "ecommerce-checkout",
+    //   input: {},
+    // },
+    // {
+    //   name: "AI Agent Workflow",
+    //   file: "../yaml-workflows/04-ai-agent-workflow.yaml",
+    //   id: "ai-agent",
+    //   input: {},
+    // },
+  ];
+
+  // Execute each YAML workflow
+  for (const workflow of workflows) {
+    console.log("=".repeat(60));
+    console.log(`Workflow: ${workflow.name}`);
+    console.log("=".repeat(60));
+
+    try {
+      // Load YAML content from file
+      const yamlContent = readFileSync(join(__dirname, workflow.file), "utf-8");
+
+      // Create workflow args with YAML content
+      const args: YamlWorkflowArgs = {
+        input: workflow.input || {},
+        treeRegistry,
+        yamlContent,
+      };
+
+      // Execute workflow
+      const result = await client.workflow.execute("yamlWorkflow", {
+        taskQueue: "btree-workflows",
+        workflowId: `${workflow.id}-${Date.now()}`,
+        args: [args],
+      });
+
+      console.log("✅ Result:", result);
+      console.log("\n");
+    } catch (error) {
+      console.error(`❌ Workflow failed:`, error);
+      console.log("\n");
+    }
+  }
+
+  console.log("=".repeat(60));
+  console.log("🎉 All YAML workflows completed!");
+  console.log("=".repeat(60));
+}
+
+run().catch((err) => {
+  console.error("❌ Client error:", err);
+  process.exit(1);
+});