@q1k-oss/btree-workflows 0.0.1

package/src/observability/execution-tracker.ts

@@ -0,0 +1,320 @@
+/**
+ * ExecutionTracker - Aggregates node events into queryable state
+ * Used by workflow query handlers to expose real-time execution progress
+ */
+
+import { NodeEventType } from "../events.js";
+import type {
+  ExecutionProgress,
+  NodeState,
+  StructuredError,
+  TimelineEntry,
+  ObservableNodeEvent,
+} from "./types.js";
+
+/**
+ * Tracks execution state by subscribing to node events
+ * Provides query methods for progress, node states, errors, and timeline
+ */
+export class ExecutionTracker {
+  private nodeStates = new Map<string, NodeState>();
+  private timeline: TimelineEntry[] = [];
+  private errors: StructuredError[] = [];
+  private pathTaken: string[] = [];
+  private startedAt: number = Date.now();
+  private currentNodeId: string | null = null;
+  private totalNodes: number;
+  private finished: boolean = false;
+
+  constructor(totalNodes: number) {
+    this.totalNodes = totalNodes;
+  }
+
+  /**
+   * Process a node event and update internal state
+   * Called by NodeEventEmitter subscription
+   */
+  onNodeEvent(event: ObservableNodeEvent): void {
+    const state = this.getOrCreateState(
+      event.nodeId,
+      event.nodeType,
+      event.nodeName,
+      event.nodePath
+    );
+
+    const eventType = event.type as NodeEventType;
+
+    switch (eventType) {
+      case NodeEventType.TICK_START:
+        this.handleTickStart(state, event);
+        break;
+
+      case NodeEventType.TICK_END:
+        this.handleTickEnd(state, event);
+        break;
+
+      case NodeEventType.ERROR:
+        this.handleError(state, event);
+        break;
+
+      case NodeEventType.LOG:
+        // Log events don't affect tracking state
+        break;
+
+      case NodeEventType.HALT:
+      case NodeEventType.RESET:
+        // Could track these for debugging, but not critical for progress
+        break;
+    }
+  }
+
+  private handleTickStart(state: NodeState, event: ObservableNodeEvent): void {
+    state.status = "running";
+    state.tickCount++;
+    state.lastTickAt = event.timestamp;
+    this.currentNodeId = event.nodeId;
+
+    this.timeline.push({
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      event: "start",
+      timestamp: event.timestamp,
+    });
+  }
+
+  private handleTickEnd(state: NodeState, event: ObservableNodeEvent): void {
+    const status = event.data?.status;
+    const durationMs = event.data?.durationMs;
+
+    // Map NodeStatus strings to our simpler status
+    if (status === "SUCCESS") {
+      state.status = "success";
+      if (!this.pathTaken.includes(event.nodeId)) {
+        this.pathTaken.push(event.nodeId);
+      }
+    } else if (status === "FAILURE") {
+      state.status = "failure";
+    } else if (status === "RUNNING") {
+      state.status = "running";
+    } else {
+      state.status = "idle";
+    }
+
+    if (durationMs !== undefined) {
+      state.durationMs = durationMs;
+    }
+
+    this.timeline.push({
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      event: "end",
+      timestamp: event.timestamp,
+      status: state.status,
+      durationMs: state.durationMs,
+    });
+
+    // Clear current node if this was it
+    if (this.currentNodeId === event.nodeId && state.status !== "running") {
+      this.currentNodeId = null;
+    }
+  }
+
+  private handleError(state: NodeState, event: ObservableNodeEvent): void {
+    state.status = "failure";
+    const errorData = event.data?.error;
+    state.lastError = errorData?.message ?? "Unknown error";
+
+    const structuredError: StructuredError = {
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      message: errorData?.message ?? "Unknown error",
+      stack: errorData?.stack,
+      timestamp: event.timestamp,
+      blackboardSnapshot: event.data?.blackboard ?? {},
+      nodeInput: errorData?.input,
+      recoverable: this.isRecoverable(event.nodeType),
+      suggestedFix: this.suggestFix(event),
+    };
+
+    this.errors.push(structuredError);
+
+    this.timeline.push({
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      nodeName: event.nodeName,
+      nodePath: event.nodePath ?? "",
+      event: "error",
+      timestamp: event.timestamp,
+      error: {
+        message: structuredError.message,
+        stack: structuredError.stack,
+      },
+    });
+  }
+
+  /**
+   * Mark execution as finished
+   */
+  markFinished(): void {
+    this.finished = true;
+    this.currentNodeId = null;
+  }
+
+  /**
+   * Get overall execution progress
+   */
+  getProgress(): ExecutionProgress {
+    const states = [...this.nodeStates.values()];
+    const completed = states.filter((n) => n.status === "success").length;
+    const failed = states.filter((n) => n.status === "failure").length;
+
+    let status: "running" | "completed" | "failed";
+    if (failed > 0) {
+      status = "failed";
+    } else if (this.finished) {
+      status = "completed";
+    } else if (this.currentNodeId) {
+      status = "running";
+    } else {
+      status = "completed";
+    }
+
+    return {
+      totalNodes: this.totalNodes,
+      completedNodes: completed,
+      failedNodes: failed,
+      currentNodeId: this.currentNodeId,
+      currentNodeType: this.nodeStates.get(this.currentNodeId ?? "")?.type ?? null,
+      pathTaken: [...this.pathTaken],
+      startedAt: this.startedAt,
+      lastActivityAt:
+        this.timeline[this.timeline.length - 1]?.timestamp ?? this.startedAt,
+      status,
+    };
+  }
+
+  /**
+   * Get all node states
+   */
+  getNodeStates(): Map<string, NodeState> {
+    return new Map(this.nodeStates);
+  }
+
+  /**
+   * Get node states as a plain object (for JSON serialization)
+   */
+  getNodeStatesObject(): Record<string, NodeState> {
+    const result: Record<string, NodeState> = {};
+    for (const [id, state] of this.nodeStates) {
+      result[id] = { ...state };
+    }
+    return result;
+  }
+
+  /**
+   * Get all errors that occurred during execution
+   */
+  getErrors(): StructuredError[] {
+    return [...this.errors];
+  }
+
+  /**
+   * Get the full execution timeline
+   */
+  getTimeline(): TimelineEntry[] {
+    return [...this.timeline];
+  }
+
+  /**
+   * Get state for a specific node
+   */
+  getNodeState(nodeId: string): NodeState | undefined {
+    return this.nodeStates.get(nodeId);
+  }
+
+  private getOrCreateState(
+    id: string,
+    type: string,
+    name: string,
+    path?: string
+  ): NodeState {
+    if (!this.nodeStates.has(id)) {
+      this.nodeStates.set(id, {
+        id,
+        type,
+        name,
+        path: path ?? "",
+        status: "idle",
+        tickCount: 0,
+      });
+    }
+    return this.nodeStates.get(id)!;
+  }
+
+  /**
+   * Check if an error type is potentially recoverable with retry
+   */
+  private isRecoverable(nodeType: string): boolean {
+    // Nodes that often fail due to transient issues
+    const recoverableTypes = [
+      "FetchUrl",
+      "HttpRequest",
+      "CodeExecution",
+      "ParseFile",
+      "GenerateFile",
+      "IntegrationAction",
+    ];
+    return recoverableTypes.includes(nodeType);
+  }
+
+  /**
+   * Suggest a fix based on error patterns
+   */
+  private suggestFix(event: ObservableNodeEvent): string | undefined {
+    const msg = event.data?.error?.message ?? "";
+    const nodeType = event.nodeType;
+
+    // Timeout errors
+    if (msg.includes("timeout") || msg.includes("TIMEOUT") || msg.includes("timed out")) {
+      return "Consider increasing timeout or adding retry decorator";
+    }
+
+    // Undefined/null access
+    if (msg.includes("undefined") || msg.includes("null") || msg.includes("Cannot read property")) {
+      return "Check if required blackboard key exists before accessing";
+    }
+
+    // Network errors
+    if (msg.includes("network") || msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      return "Check URL accessibility, consider adding retry decorator";
+    }
+
+    // Authentication errors
+    if (msg.includes("401") || msg.includes("403") || msg.includes("unauthorized")) {
+      return "Check authentication credentials and permissions";
+    }
+
+    // File not found
+    if (msg.includes("not found") || msg.includes("ENOENT") || msg.includes("404")) {
+      return "Verify file path or URL exists";
+    }
+
+    // Code execution errors
+    if (nodeType === "CodeExecution") {
+      if (msg.includes("SyntaxError")) {
+        return "Fix syntax error in code";
+      }
+      if (msg.includes("ReferenceError")) {
+        return "Variable not defined - check getBB() keys";
+      }
+    }
+
+    return undefined;
+  }
+}

package/src/observability/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Observability module for workflow execution tracking
+ *
+ * Provides:
+ * - ExecutionTracker: Aggregates events into queryable state
+ * - Types: ExecutionProgress, NodeState, StructuredError, TimelineEntry
+ * - Sinks: ObservabilitySinks for Temporal workflow event export
+ */
+
+export { ExecutionTracker } from "./execution-tracker.js";
+export type {
+  ExecutionProgress,
+  NodeState,
+  StructuredError,
+  TimelineEntry,
+  ObservableNodeEvent,
+} from "./types.js";
+export type {
+  ObservabilitySinks,
+  SinkHandlerConfig,
+  InjectedObservabilitySinks,
+} from "./sinks.js";
+export { createObservabilitySinkHandler } from "./sinks.js";

package/src/observability/sinks.ts

@@ -0,0 +1,138 @@
+/**
+ * Workflow Sink types for exporting events from Temporal workflows
+ * Sinks allow workflows to export data without affecting determinism
+ */
+
+import type { Sinks } from "@temporalio/workflow";
+import type { ObservableNodeEvent } from "./types.js";
+
+/**
+ * Observability sinks for workflow event export
+ *
+ * Usage in workflow:
+ * ```typescript
+ * import { proxySinks } from '@temporalio/workflow';
+ * import type { ObservabilitySinks } from '@wayfarer-ai/btree-workflows';
+ *
+ * const { events } = proxySinks<ObservabilitySinks>();
+ * events.push(nodeEvent);  // Fire-and-forget
+ * ```
+ *
+ * The sink handler runs in the worker (outside the deterministic sandbox)
+ * and can safely perform I/O like database writes or triggering agents.
+ */
+export interface ObservabilitySinks extends Sinks {
+  events: {
+    /**
+     * Push a node event to external observers
+     * This is fire-and-forget - workflow execution continues immediately
+     */
+    push(event: ObservableNodeEvent): void;
+  };
+}
+
+/**
+ * Configuration for creating sink handlers
+ */
+export interface SinkHandlerConfig {
+  /**
+   * Called when a node event is received
+   * Can be async - workflow doesn't wait for completion
+   */
+  onEvent?: (
+    workflowId: string,
+    runId: string,
+    event: ObservableNodeEvent
+  ) => void | Promise<void>;
+
+  /**
+   * Called specifically for ERROR events
+   * Use this to trigger analyzer agent or alerting
+   */
+  onError?: (
+    workflowId: string,
+    runId: string,
+    event: ObservableNodeEvent
+  ) => void | Promise<void>;
+
+  /**
+   * Whether to log events to console (default: false)
+   */
+  logEvents?: boolean;
+}
+
+/**
+ * Sink function signature for InjectedSinks
+ */
+export interface SinkFunction<T extends (...args: any[]) => any> {
+  fn(info: { workflowId: string; runId: string }, ...args: Parameters<T>): ReturnType<T>;
+  callDuringReplay: boolean;
+}
+
+/**
+ * Type for InjectedSinks<ObservabilitySinks>
+ */
+export type InjectedObservabilitySinks = {
+  events: {
+    push: SinkFunction<(event: ObservableNodeEvent) => void>;
+  };
+};
+
+/**
+ * Create sink handler functions for InjectedSinks
+ *
+ * Usage in worker:
+ * ```typescript
+ * import { createObservabilitySinkHandler } from '@wayfarer-ai/btree-workflows';
+ *
+ * const sinks = createObservabilitySinkHandler({
+ *   onEvent: (workflowId, runId, event) => {
+ *     // Store event to database
+ *   },
+ *   onError: (workflowId, runId, event) => {
+ *     // Trigger analyzer agent
+ *   },
+ * });
+ *
+ * const worker = await Worker.create({ sinks, ... });
+ * ```
+ */
+export function createObservabilitySinkHandler(
+  config: SinkHandlerConfig = {}
+): InjectedObservabilitySinks {
+  return {
+    events: {
+      push: {
+        fn: (
+          workflowInfo: { workflowId: string; runId: string },
+          event: ObservableNodeEvent
+        ) => {
+          const { workflowId, runId } = workflowInfo;
+
+          // Log if configured
+          if (config.logEvents) {
+            console.log(
+              `[Sink] [${workflowId}] ${event.type}: ${event.nodeId} (${event.nodeType})`
+            );
+          }
+
+          // Call general event handler
+          if (config.onEvent) {
+            Promise.resolve(config.onEvent(workflowId, runId, event)).catch(
+              (err) => console.error("[Sink] Error in onEvent handler:", err)
+            );
+          }
+
+          // Call error handler for ERROR events
+          if (event.type === "error" && config.onError) {
+            Promise.resolve(config.onError(workflowId, runId, event)).catch(
+              (err) => console.error("[Sink] Error in onError handler:", err)
+            );
+          }
+        },
+        // Don't call during replay - events were already processed
+        callDuringReplay: false,
+      },
+    },
+  };
+}

package/src/observability/types.ts

@@ -0,0 +1,130 @@
+/**
+ * Observability types for workflow execution tracking
+ * Used by ExecutionTracker and Analyzer Agent
+ */
+
+/**
+ * Overall execution progress summary
+ */
+export interface ExecutionProgress {
+  /** Total number of nodes in the tree */
+  totalNodes: number;
+  /** Number of nodes that completed successfully */
+  completedNodes: number;
+  /** Number of nodes that failed */
+  failedNodes: number;
+  /** Currently executing node ID (null if not running) */
+  currentNodeId: string | null;
+  /** Type of currently executing node */
+  currentNodeType: string | null;
+  /** Ordered list of node IDs that have been executed */
+  pathTaken: string[];
+  /** Timestamp when execution started */
+  startedAt: number;
+  /** Timestamp of last activity */
+  lastActivityAt: number;
+  /** Overall status */
+  status: "running" | "completed" | "failed";
+}
+
+/**
+ * State of a single node during execution
+ */
+export interface NodeState {
+  /** Node ID */
+  id: string;
+  /** Node type (e.g., "Sequence", "CodeExecution") */
+  type: string;
+  /** Node name */
+  name: string;
+  /** Tree path (e.g., "/0/1/2") */
+  path: string;
+  /** Current status */
+  status: "idle" | "running" | "success" | "failure";
+  /** Last error message if failed */
+  lastError?: string;
+  /** Number of times this node has been ticked */
+  tickCount: number;
+  /** Timestamp of last tick */
+  lastTickAt?: number;
+  /** Duration of last tick in ms */
+  durationMs?: number;
+}
+
+/**
+ * Structured error with rich context for debugging
+ */
+export interface StructuredError {
+  /** Node ID where error occurred */
+  nodeId: string;
+  /** Node type */
+  nodeType: string;
+  /** Node name */
+  nodeName: string;
+  /** Tree path (e.g., "/0/1/2") */
+  nodePath: string;
+  /** Error message */
+  message: string;
+  /** Error stack trace (if available) */
+  stack?: string;
+  /** Timestamp when error occurred */
+  timestamp: number;
+  /** Blackboard snapshot at time of error */
+  blackboardSnapshot: Record<string, unknown>;
+  /** Input that was passed to the node */
+  nodeInput?: unknown;
+  /** Whether this error is potentially recoverable with retry */
+  recoverable: boolean;
+  /** Suggested fix based on error analysis */
+  suggestedFix?: string;
+}
+
+/**
+ * Entry in the execution timeline
+ */
+export interface TimelineEntry {
+  /** Node ID */
+  nodeId: string;
+  /** Node type */
+  nodeType: string;
+  /** Node name */
+  nodeName: string;
+  /** Tree path */
+  nodePath: string;
+  /** Event type */
+  event: "start" | "end" | "error";
+  /** Timestamp */
+  timestamp: number;
+  /** Final status (for end events) */
+  status?: string;
+  /** Duration in ms (for end events) */
+  durationMs?: number;
+  /** Error details (for error events) */
+  error?: {
+    message: string;
+    stack?: string;
+  };
+}
+
+/**
+ * Extended NodeEvent with path and blackboard context
+ * Used internally by ExecutionTracker
+ */
+export interface ObservableNodeEvent {
+  type: string;
+  nodeId: string;
+  nodeName: string;
+  nodeType: string;
+  nodePath?: string;
+  timestamp: number;
+  data?: {
+    status?: string;
+    durationMs?: number;
+    error?: {
+      message: string;
+      stack?: string;
+      input?: unknown;
+    };
+    blackboard?: Record<string, unknown>;
+  };
+}