@s_s/harmonia 1.2.0 → 1.4.0

package/build/core/workflow-engine.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Workflow engine — core state machine for node-based workflow execution.
+ *
+ * This module handles:
+ * - Node state initialization from a WorkflowDefinition
+ * - State transitions based on WorkflowEvents
+ * - NextAction computation (telling the coordinator what to do)
+ * - Gate evaluation
+ * - Goto execution (state reset + retry tracking)
+ * - Failure handling (onFailed, bubbling, onExhausted)
+ *
+ * Key insight: Core is passive (MCP server). Every interaction is
+ * coordinator-driven. Engine computes state changes and returns nextAction,
+ * but never proactively pushes the workflow forward.
+ */
+import type { WorkflowDefinition, GateNode, WorkflowState, NodeState, NextAction, WorkflowEvent, GateEvaluationResult } from './types.js';
+/** Context needed for gate evaluation */
+export interface GateContext {
+    /** Check if an artifact exists */
+    artifactExists: (artifactId: string) => boolean;
+    /** Check if an artifact is approved */
+    artifactApproved: (artifactId: string) => boolean;
+    /** Read a field from an artifact (returns undefined if not found) */
+    artifactField: (artifactId: string, field: string) => unknown;
+}
+/** Context needed by the engine for computing next actions */
+export interface EngineContext {
+    /** Gate evaluation context */
+    gate: GateContext;
+    /** Get role prompt (assembled by plugin layer) */
+    getRolePrompt?: (role: string, nodeId: string, gateResults?: GateEvaluationResult) => string;
+}
+/**
+ * Initialize node states for all nodes in a workflow definition.
+ * All nodes start as 'pending', except the first actionable node
+ * which will be activated when the workflow begins.
+ */
+export declare function initNodeStates(definition: WorkflowDefinition): Record<string, NodeState>;
+/**
+ * Start the workflow — activate the root node and return the first nextAction.
+ */
+export declare function startWorkflow(definition: WorkflowDefinition, state: WorkflowState, context: EngineContext): {
+    state: WorkflowState;
+    nextAction: NextAction;
+};
+/**
+ * Process a workflow event and compute the next action.
+ * This is the main entry point for all state transitions.
+ */
+export declare function computeNextAction(definition: WorkflowDefinition, state: WorkflowState, event: WorkflowEvent, context: EngineContext): {
+    state: WorkflowState;
+    nextAction: NextAction;
+};
+/**
+ * Handle node completion: mark as completed, advance to next node.
+ */
+export declare function completeNode(state: WorkflowState, definition: WorkflowDefinition, nodeId: string, context: EngineContext, result?: unknown): {
+    state: WorkflowState;
+    nextAction: NextAction;
+};
+/**
+// ─── Gate Evaluation ───
+
+/**
+ * Evaluate all conditions for a gate node.
+ * All conditions must pass for the gate to pass (AND logic).
+ */
+export declare function evaluateGate(gate: GateNode, gateCtx: GateContext): GateEvaluationResult;