@soleri/core 2.12.0 → 8.0.0

package/src/flows/dispatch-registry.ts

@@ -0,0 +1,80 @@
+/**
+ * Dispatch registry — maps tool names to real facade op handlers.
+ *
+ * Tool names follow the convention: `{agentId}_{facadeName}_{opName}`
+ * e.g. "myagent_vault_search" → facade "myagent_vault", op "search".
+ */
+
+import type { FacadeConfig } from '../facades/types.js';
+
+type DispatchResult = { tool: string; status: string; data?: unknown; error?: string };
+type DispatchFn = (toolName: string, params: Record<string, unknown>) => Promise<DispatchResult>;
+
+/**
+ * Create a dispatcher function that routes tool calls to the correct facade op.
+ *
+ * @param agentId - Agent identifier prefix (e.g. "myagent")
+ * @param facades - Array of registered facade configs
+ * @returns A dispatch function that takes (toolName, params) and calls the matching handler
+ */
+export function createDispatcher(agentId: string, facades: FacadeConfig[]): DispatchFn {
+  // Build a lookup map: facadeName → { opName → handler }
+  const facadeMap = new Map<string, FacadeConfig>();
+  for (const facade of facades) {
+    facadeMap.set(facade.name, facade);
+  }
+
+  return async (toolName: string, params: Record<string, unknown>): Promise<DispatchResult> => {
+    const prefix = `${agentId}_`;
+
+    // Strip agent prefix if present
+    const unprefixed = toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName;
+
+    // Try progressively longer facade name prefixes.
+    // E.g. for "vault_extra_search": try "vault_extra_search", "vault_extra", "vault"
+    const parts = unprefixed.split('_');
+
+    for (let splitAt = parts.length - 1; splitAt >= 1; splitAt--) {
+      const facadeSuffix = parts.slice(0, splitAt).join('_');
+      const opName = parts.slice(splitAt).join('_');
+      const facadeFullName = `${prefix}${facadeSuffix}`;
+
+      const facade = facadeMap.get(facadeFullName);
+      if (!facade) continue;
+
+      const op = facade.ops.find((o) => o.name === opName);
+      if (!op) continue;
+
+      try {
+        const result = await op.handler(params);
+        return { tool: toolName, status: 'ok', data: result };
+      } catch (err) {
+        return {
+          tool: toolName,
+          status: 'error',
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    // Also try matching the full unprefixed name as a facade with "op" from params
+    const facade = facadeMap.get(`${prefix}${unprefixed}`);
+    if (facade && params.op && typeof params.op === 'string') {
+      const op = facade.ops.find((o) => o.name === params.op);
+      if (op) {
+        try {
+          const result = await op.handler(params);
+          return { tool: toolName, status: 'ok', data: result };
+        } catch (err) {
+          return {
+            tool: toolName,
+            status: 'error',
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+      }
+    }
+
+    return { tool: toolName, status: 'unregistered' };
+  };
+}

package/src/flows/epilogue.ts

@@ -0,0 +1,65 @@
+/**
+ * Epilogue — post-execution cleanup: capture knowledge and session summary.
+ * All operations are resilient (errors are caught, never propagated).
+ */
+
+import type { ProbeResults } from './types.js';
+
+type DispatchFn = (
+  toolName: string,
+  params: Record<string, unknown>,
+) => Promise<{ tool: string; status: string; data?: unknown; error?: string }>;
+
+/**
+ * Run post-execution epilogue steps.
+ * - Captures knowledge to vault (if available)
+ * - Captures session summary (if session store available)
+ *
+ * @returns Whether anything was captured and an optional session ID.
+ */
+export async function runEpilogue(
+  dispatch: DispatchFn,
+  probes: ProbeResults,
+  projectPath: string,
+  summary: string,
+): Promise<{ captured: boolean; sessionId?: string }> {
+  let captured = false;
+  let sessionId: string | undefined;
+
+  // Capture knowledge to vault
+  if (probes.vault) {
+    try {
+      await dispatch('capture_knowledge', {
+        title: 'Flow execution summary',
+        content: summary,
+        type: 'workflow',
+        tags: ['flow-engine', 'auto-captured'],
+        projectPath,
+      });
+      captured = true;
+    } catch {
+      // Silently ignore — vault capture is best-effort
+    }
+  }
+
+  // Capture session
+  if (probes.sessionStore) {
+    try {
+      const result = await dispatch('session_capture', {
+        summary,
+        projectPath,
+      });
+      captured = true;
+      if (result.data && typeof result.data === 'object') {
+        const data = result.data as Record<string, unknown>;
+        if (typeof data.sessionId === 'string') {
+          sessionId = data.sessionId;
+        }
+      }
+    } catch {
+      // Silently ignore — session capture is best-effort
+    }
+  }
+
+  return { captured, sessionId };
+}

package/src/flows/executor.ts

@@ -0,0 +1,182 @@
+/**
+ * Flow executor — runs an orchestration plan step-by-step,
+ * evaluating gates and handling branching.
+ */
+
+import type { OrchestrationPlan, ExecutionResult, StepResult } from './types.js';
+import { evaluateGate } from './gate-evaluator.js';
+
+/** Maximum iterations for BRANCH loops to prevent infinite cycles. */
+const MAX_BRANCH_ITERATIONS = 10;
+
+type DispatchFn = (
+  toolName: string,
+  params: Record<string, unknown>,
+) => Promise<{ tool: string; status: string; data?: unknown; error?: string }>;
+
+/**
+ * Executes an orchestration plan sequentially (with parallel inner steps).
+ */
+export class FlowExecutor {
+  private dispatch: DispatchFn;
+
+  constructor(dispatch: DispatchFn) {
+    this.dispatch = dispatch;
+  }
+
+  /**
+   * Execute a full orchestration plan. Returns an ExecutionResult
+   * summarizing what happened.
+   */
+  async execute(plan: OrchestrationPlan): Promise<ExecutionResult> {
+    const startTime = Date.now();
+    const stepResults: StepResult[] = [];
+    const toolsCalled: string[] = [];
+    let branchIterations = 0;
+    let currentIndex = 0;
+
+    while (currentIndex < plan.steps.length) {
+      const step = plan.steps[currentIndex];
+      const stepStart = Date.now();
+      step.status = 'running';
+
+      const toolResults: StepResult['toolResults'] = {};
+
+      try {
+        if (step.parallel && step.tools.length > 1) {
+          // Execute tools in parallel
+          const results = await Promise.allSettled(
+            step.tools.map((tool) => this.dispatch(tool, { stepId: step.id, planId: plan.planId })),
+          );
+          for (let i = 0; i < step.tools.length; i++) {
+            const toolName = step.tools[i];
+            const result = results[i];
+            if (result.status === 'fulfilled') {
+              toolResults[toolName] = result.value;
+            } else {
+              toolResults[toolName] = {
+                tool: toolName,
+                status: 'error',
+                error:
+                  result.reason instanceof Error ? result.reason.message : String(result.reason),
+              };
+            }
+            toolsCalled.push(toolName);
+          }
+        } else {
+          // Execute tools sequentially
+          for (const toolName of step.tools) {
+            try {
+              toolResults[toolName] = await this.dispatch(toolName, {
+                stepId: step.id,
+                planId: plan.planId,
+              });
+            } catch (_err) {
+              toolResults[toolName] = {
+                tool: toolName,
+                status: 'error',
+                error: _err instanceof Error ? _err.message : String(_err),
+              };
+            }
+            toolsCalled.push(toolName);
+          }
+        }
+      } catch (_err) {
+        // Entire step failed
+        const stepResult: StepResult = {
+          stepId: step.id,
+          status: 'failed',
+          toolResults,
+          durationMs: Date.now() - stepStart,
+        };
+        stepResults.push(stepResult);
+        step.status = 'failed';
+        break;
+      }
+
+      // Evaluate gate
+      const flatData: Record<string, unknown> = {};
+      for (const [key, val] of Object.entries(toolResults)) {
+        flatData[key] = val;
+        if (val.data && typeof val.data === 'object') {
+          Object.assign(flatData, val.data as Record<string, unknown>);
+        }
+      }
+
+      const verdict = evaluateGate(step.gate, flatData);
+
+      const stepResult: StepResult = {
+        stepId: step.id,
+        status: verdict.passed ? 'passed' : 'failed',
+        toolResults,
+        durationMs: Date.now() - stepStart,
+      };
+
+      if (!verdict.passed || verdict.action !== 'CONTINUE') {
+        stepResult.gateResult = {
+          action: verdict.action,
+          message: verdict.message,
+        };
+      }
+
+      stepResults.push(stepResult);
+
+      // Handle gate action
+      switch (verdict.action) {
+        case 'STOP':
+          step.status = 'failed';
+          // Stop execution
+          return buildResult(plan, stepResults, toolsCalled, startTime, 'partial');
+
+        case 'BRANCH': {
+          step.status = verdict.passed ? 'passed' : 'gate-paused';
+          branchIterations++;
+          if (branchIterations >= MAX_BRANCH_ITERATIONS) {
+            return buildResult(plan, stepResults, toolsCalled, startTime, 'partial');
+          }
+          if (verdict.goto) {
+            const targetIdx = plan.steps.findIndex((s) => s.id === verdict.goto);
+            if (targetIdx >= 0) {
+              currentIndex = targetIdx;
+              continue;
+            }
+          }
+          // No valid goto — continue to next step
+          step.status = 'passed';
+          currentIndex++;
+          break;
+        }
+
+        case 'CONTINUE':
+        default:
+          step.status = verdict.passed ? 'passed' : 'failed';
+          currentIndex++;
+          break;
+      }
+    }
+
+    const allPassed = stepResults.every((r) => r.status === 'passed');
+    const anyFailed = stepResults.some((r) => r.status === 'failed');
+    const status = allPassed ? 'completed' : anyFailed ? 'partial' : 'completed';
+
+    return buildResult(plan, stepResults, toolsCalled, startTime, status);
+  }
+}
+
+function buildResult(
+  plan: OrchestrationPlan,
+  stepResults: StepResult[],
+  toolsCalled: string[],
+  startTime: number,
+  status: ExecutionResult['status'],
+): ExecutionResult {
+  return {
+    planId: plan.planId,
+    status,
+    stepsCompleted: stepResults.filter((r) => r.status === 'passed').length,
+    totalSteps: plan.steps.length,
+    toolsCalled: [...new Set(toolsCalled)],
+    durationMs: Date.now() - startTime,
+    stepResults,
+  };
+}

package/src/flows/gate-evaluator.ts

@@ -0,0 +1,171 @@
+/**
+ * Gate evaluator — checks step gates against tool results to decide
+ * whether execution should CONTINUE, STOP, or BRANCH.
+ */
+
+import type { PlanStep, GateVerdict } from './types.js';
+
+/**
+ * Evaluate a plan step's gate against collected tool results.
+ * If no gate is defined, returns CONTINUE (passed).
+ */
+export function evaluateGate(
+  gate: PlanStep['gate'],
+  toolResults: Record<string, unknown>,
+): GateVerdict {
+  if (!gate) {
+    return { passed: true, action: 'CONTINUE' };
+  }
+
+  switch (gate.type) {
+    case 'GATE': {
+      const passed = gate.condition ? evaluateCondition(gate.condition, toolResults) : true;
+      if (passed) return { passed: true, action: 'CONTINUE' };
+      return {
+        passed: false,
+        action: (gate.onFail?.action as GateVerdict['action']) ?? 'STOP',
+        goto: gate.onFail?.goto,
+        message: gate.onFail?.message,
+      };
+    }
+
+    case 'SCORE': {
+      const score = extractScore(toolResults);
+      const minScore = gate.min ?? 0;
+      const passed = score >= minScore;
+      if (passed) return { passed: true, action: 'CONTINUE', score };
+      return {
+        passed: false,
+        action: (gate.onFail?.action as GateVerdict['action']) ?? 'STOP',
+        goto: gate.onFail?.goto,
+        message: gate.onFail?.message ?? `Score ${score} below minimum ${minScore}`,
+        score,
+      };
+    }
+
+    case 'CHECKPOINT': {
+      const passed = gate.condition ? evaluateCondition(gate.condition, toolResults) : true;
+      if (passed) return { passed: true, action: 'CONTINUE' };
+      return {
+        passed: false,
+        action: (gate.onFail?.action as GateVerdict['action']) ?? 'CONTINUE',
+        goto: gate.onFail?.goto,
+        message: gate.onFail?.message,
+      };
+    }
+
+    case 'BRANCH': {
+      // BRANCH gates always trigger branching
+      return {
+        passed: true,
+        action: 'BRANCH',
+        goto: gate.onFail?.goto,
+        message: gate.onFail?.message,
+      };
+    }
+
+    default:
+      return { passed: true, action: 'CONTINUE' };
+  }
+}
+
+/**
+ * Evaluate a simple condition string: "lhs op rhs".
+ * Supported operators: ==, !=, >=, <=, >, <
+ * lhs is resolved as a dotted path from data, rhs is a literal.
+ */
+export function evaluateCondition(condition: string, data: Record<string, unknown>): boolean {
+  const operators = ['>=', '<=', '!=', '==', '>', '<'] as const;
+  for (const op of operators) {
+    const idx = condition.indexOf(op);
+    if (idx === -1) continue;
+
+    const lhsPath = condition.slice(0, idx).trim();
+    const rhsRaw = condition.slice(idx + op.length).trim();
+    const lhsValue = resolvePath(data, lhsPath);
+    const rhsValue = parseConditionValue(rhsRaw);
+
+    const lNum = typeof lhsValue === 'number' ? lhsValue : Number(lhsValue);
+    const rNum = typeof rhsValue === 'number' ? rhsValue : Number(rhsValue);
+    const useNumeric = !Number.isNaN(lNum) && !Number.isNaN(rNum);
+
+    switch (op) {
+      case '==':
+        return useNumeric ? lNum === rNum : String(lhsValue) === String(rhsValue);
+      case '!=':
+        return useNumeric ? lNum !== rNum : String(lhsValue) !== String(rhsValue);
+      case '>=':
+        return useNumeric ? lNum >= rNum : false;
+      case '<=':
+        return useNumeric ? lNum <= rNum : false;
+      case '>':
+        return useNumeric ? lNum > rNum : false;
+      case '<':
+        return useNumeric ? lNum < rNum : false;
+    }
+  }
+
+  // No operator found — check if value is truthy
+  const val = resolvePath(data, condition.trim());
+  return !!val;
+}
+
+/**
+ * Extract a numeric score from tool results.
+ * Looks for common score field names.
+ */
+export function extractScore(data: Record<string, unknown>): number {
+  // Direct score fields
+  for (const key of ['score', 'validationScore', 'total']) {
+    if (typeof data[key] === 'number') return data[key] as number;
+  }
+
+  // Search within nested result objects
+  for (const val of Object.values(data)) {
+    if (val && typeof val === 'object' && !Array.isArray(val)) {
+      const nested = val as Record<string, unknown>;
+      for (const key of ['score', 'validationScore', 'total']) {
+        if (typeof nested[key] === 'number') return nested[key] as number;
+      }
+      // One more level: data property
+      if (nested.data && typeof nested.data === 'object') {
+        const deep = nested.data as Record<string, unknown>;
+        for (const key of ['score', 'validationScore', 'total']) {
+          if (typeof deep[key] === 'number') return deep[key] as number;
+        }
+      }
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * Resolve a dotted path like "result.data.score" against an object.
+ */
+export function resolvePath(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+function parseConditionValue(raw: string): string | number | boolean {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw === 'null') return 0;
+  // Strip quotes
+  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+    return raw.slice(1, -1);
+  }
+  const num = Number(raw);
+  if (!Number.isNaN(num)) return num;
+  return raw;
+}

package/src/flows/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Flow engine — YAML-driven workflow orchestration.
+ */
+
+// Types
+export type {
+  Flow,
+  FlowStep,
+  Gate,
+  GateAction,
+  ProbeName,
+  ProbeResults,
+  PlanStep,
+  SkippedStep,
+  OrchestrationPlan,
+  OrchestrationContext,
+  StepResult,
+  ExecutionResult,
+  GateVerdict,
+} from './types.js';
+
+// Loader
+export { loadFlowById, loadAllFlows, parseSimpleYaml } from './loader.js';
+
+// Probes
+export { runProbes } from './probes.js';
+
+// Plan builder
+export {
+  INTENT_TO_FLOW,
+  chainToToolName,
+  chainToRequires,
+  flowStepsToPlanSteps,
+  pruneSteps,
+  buildPlan,
+} from './plan-builder.js';
+
+// Context router
+export { detectContext, applyContextOverrides, getFlowOverrides } from './context-router.js';
+export type { ContextOverride } from './context-router.js';
+
+// Gate evaluator
+export { evaluateGate, evaluateCondition, extractScore, resolvePath } from './gate-evaluator.js';
+
+// Executor
+export { FlowExecutor } from './executor.js';
+
+// Dispatch registry
+export { createDispatcher } from './dispatch-registry.js';
+
+// Epilogue
+export { runEpilogue } from './epilogue.js';

package/src/flows/loader.ts

@@ -0,0 +1,63 @@
+/**
+ * Flow loader — reads and validates YAML flow files from a directory.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { flowSchema, type Flow } from './types.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_FLOWS_DIR = join(__dirname, '..', '..', 'data', 'flows');
+
+/** Re-export for backward compat (tests import this). */
+export const parseSimpleYaml = parseYaml;
+
+/**
+ * Load a single flow by its `id` field from *.flow.yaml files in a directory.
+ * Returns `null` if not found or validation fails.
+ */
+export function loadFlowById(flowId: string, flowsDir?: string): Flow | null {
+  const dir = flowsDir ?? DEFAULT_FLOWS_DIR;
+  if (!existsSync(dir)) return null;
+
+  const files = readdirSync(dir).filter((f) => f.endsWith('.flow.yaml'));
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(dir, file), 'utf-8');
+      const raw = parseYaml(content);
+      const parsed = flowSchema.safeParse(raw);
+      if (parsed.success && parsed.data.id === flowId) {
+        return parsed.data;
+      }
+    } catch {
+      // skip invalid files
+    }
+  }
+  return null;
+}
+
+/**
+ * Load all valid flows from *.flow.yaml files in a directory.
+ */
+export function loadAllFlows(flowsDir?: string): Flow[] {
+  const dir = flowsDir ?? DEFAULT_FLOWS_DIR;
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter((f) => f.endsWith('.flow.yaml'));
+  const flows: Flow[] = [];
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(dir, file), 'utf-8');
+      const raw = parseYaml(content);
+      const parsed = flowSchema.safeParse(raw);
+      if (parsed.success) {
+        flows.push(parsed.data);
+      }
+    } catch {
+      // skip invalid files
+    }
+  }
+  return flows;
+}