@soleri/core 2.11.0 → 7.0.0

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;
+}

package/src/flows/plan-builder.ts

@@ -0,0 +1,250 @@
+/**
+ * Plan builder — converts intent + flow + probes into an OrchestrationPlan.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { AgentRuntime } from '../runtime/types.js';
+import type {
+  Flow,
+  PlanStep,
+  SkippedStep,
+  OrchestrationPlan,
+  ProbeResults,
+  ProbeName,
+} from './types.js';
+import { loadFlowById } from './loader.js';
+import { runProbes } from './probes.js';
+import { detectContext, applyContextOverrides } from './context-router.js';
+import { chainToCapability } from '../capabilities/index.js';
+import type { CapabilityRegistry } from '../capabilities/index.js';
+
+// ---------------------------------------------------------------------------
+// Intent → Flow mapping
+// ---------------------------------------------------------------------------
+
+export const INTENT_TO_FLOW: Record<string, string> = {
+  BUILD: 'BUILD-flow',
+  CREATE: 'BUILD-flow',
+  FIX: 'FIX-flow',
+  REVIEW: 'REVIEW-flow',
+  PLAN: 'PLAN-flow',
+  DESIGN: 'DESIGN-flow',
+  ENHANCE: 'ENHANCE-flow',
+  IMPROVE: 'ENHANCE-flow',
+  EXPLORE: 'EXPLORE-flow',
+  DELIVER: 'DELIVER-flow',
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a chain name (e.g. "vault-search") to a tool name (e.g. "myagent_vault_search").
+ */
+export function chainToToolName(chain: string, agentId: string): string {
+  return `${agentId}_${chain.replace(/-/g, '_')}`;
+}
+
+/**
+ * Infer which probe capability a chain requires, or undefined if none.
+ */
+export function chainToRequires(chain: string): ProbeName | undefined {
+  const lower = chain.toLowerCase();
+  if (lower.startsWith('vault') || lower.startsWith('memory')) return 'vault';
+  if (lower.startsWith('brain')) return 'brain';
+  if (lower.startsWith('component') || lower.startsWith('token') || lower.startsWith('design'))
+    return 'designSystem';
+  if (lower.startsWith('session')) return 'sessionStore';
+  // recommend-* and get-stack-* have no hard requirements
+  if (lower.startsWith('recommend') || lower.startsWith('get-stack')) return undefined;
+  return undefined;
+}
+
+/**
+ * Convert flow steps into plan steps.
+ *
+ * Resolution order for capability IDs:
+ * 1. If the step has `needs:` (v2), use those capability IDs directly
+ * 2. If the step only has `chains:` (v1), map via chainToCapability()
+ * 3. chainToToolName() is still used for tool dispatch (fallback path)
+ *
+ * When an optional `registry` is provided, each resolved capability is
+ * validated. Unavailable capabilities are recorded in the step's
+ * `unavailableCapabilities` list (informational — pruning is separate).
+ */
+export function flowStepsToPlanSteps(
+  flow: Flow,
+  agentId: string,
+  registry?: CapabilityRegistry,
+): PlanStep[] {
+  return flow.steps.map((step) => {
+    // Tool names for dispatch fallback (always computed from chains)
+    const tools = (step.chains ?? []).map((c) => chainToToolName(c, agentId));
+
+    // Resolve capability IDs: prefer needs (v2), fall back to chains (v1)
+    const capabilityIds: string[] = [];
+    if (step.needs && step.needs.length > 0) {
+      capabilityIds.push(...step.needs);
+    } else if (step.chains) {
+      for (const chain of step.chains) {
+        const capId = chainToCapability(chain);
+        if (capId && !capabilityIds.includes(capId)) {
+          capabilityIds.push(capId);
+        }
+      }
+    }
+
+    // Probe-level requires (existing behavior, derived from chains)
+    const requires: ProbeName[] = [];
+    for (const chain of step.chains ?? []) {
+      const req = chainToRequires(chain);
+      if (req && !requires.includes(req)) requires.push(req);
+    }
+
+    // Validate capabilities against registry if provided
+    const unavailableCapabilities: string[] = [];
+    if (registry) {
+      for (const capId of capabilityIds) {
+        const resolved = registry.resolve(capId);
+        if (!resolved.available) {
+          unavailableCapabilities.push(capId);
+        }
+      }
+    }
+
+    const planStep: PlanStep = {
+      id: step.id,
+      name: step.name ?? step.id,
+      tools,
+      parallel: step.parallel ?? false,
+      requires,
+      status: 'pending',
+    };
+
+    // Attach capability metadata (non-breaking additions)
+    if (capabilityIds.length > 0) {
+      (planStep as PlanStep & { capabilities?: string[] }).capabilities = capabilityIds;
+    }
+    if (unavailableCapabilities.length > 0) {
+      (planStep as PlanStep & { unavailableCapabilities?: string[] }).unavailableCapabilities =
+        unavailableCapabilities;
+    }
+
+    if (step.gate) {
+      const gate = step.gate;
+      planStep.gate = {
+        type: gate.type,
+      };
+      if ('condition' in gate && gate.condition) {
+        planStep.gate.condition = gate.condition;
+      }
+      if ('min' in gate && gate.min !== undefined) {
+        planStep.gate.min = gate.min;
+      }
+      if (gate['on-false']) {
+        planStep.gate.onFail = {
+          action: gate['on-false'].action,
+          goto: gate['on-false'].goto,
+          message: gate['on-false'].message,
+        };
+      }
+    }
+
+    return planStep;
+  });
+}
+
+/**
+ * Remove steps whose required capabilities are not available.
+ */
+export function pruneSteps(
+  steps: PlanStep[],
+  probes: ProbeResults,
+): { kept: PlanStep[]; skipped: SkippedStep[] } {
+  const kept: PlanStep[] = [];
+  const skipped: SkippedStep[] = [];
+
+  for (const step of steps) {
+    const missingProbes = step.requires.filter((r) => !probes[r]);
+    if (missingProbes.length > 0) {
+      skipped.push({
+        id: step.id,
+        name: step.name,
+        reason: `Missing capabilities: ${missingProbes.join(', ')}`,
+      });
+    } else {
+      kept.push(step);
+    }
+  }
+
+  return { kept, skipped };
+}
+
+/**
+ * Build a full orchestration plan from intent, agent config, and runtime.
+ */
+export async function buildPlan(
+  intent: string,
+  agentId: string,
+  projectPath: string,
+  runtime: AgentRuntime,
+  prompt?: string,
+): Promise<OrchestrationPlan> {
+  const normalizedIntent = intent.toUpperCase();
+  const flowId = INTENT_TO_FLOW[normalizedIntent] ?? 'BUILD-flow';
+  const flow = loadFlowById(flowId);
+
+  const probes = await runProbes(runtime, projectPath);
+
+  let steps: PlanStep[] = [];
+  let skipped: SkippedStep[] = [];
+  const warnings: string[] = [];
+
+  if (flow) {
+    let allSteps = flowStepsToPlanSteps(flow, agentId);
+
+    // Context-sensitive chain routing: detect what's being built/fixed/reviewed
+    // and apply chain overrides (inject, skip, substitute) before pruning.
+    const entities = { components: [] as string[], actions: [] as string[] };
+    const contexts = prompt ? detectContext(prompt, entities) : [];
+    if (contexts.length > 0) {
+      allSteps = applyContextOverrides(allSteps, contexts, flowId, agentId);
+    }
+
+    const pruneResult = pruneSteps(allSteps, probes);
+    steps = pruneResult.kept;
+    skipped = pruneResult.skipped;
+
+    if (pruneResult.skipped.length > 0) {
+      warnings.push(`${pruneResult.skipped.length} step(s) skipped due to missing capabilities.`);
+    }
+  } else {
+    warnings.push(`Flow "${flowId}" not found — plan will have no steps.`);
+  }
+
+  if (!probes.vault) warnings.push('Vault unavailable — knowledge capture will be skipped.');
+  if (!probes.brain) warnings.push('Brain has no vocabulary — recommendations may be limited.');
+
+  const epilogue: string[] = [];
+  if (probes.vault) epilogue.push('capture_knowledge');
+  if (probes.sessionStore) epilogue.push('session_capture');
+
+  return {
+    planId: randomUUID(),
+    intent: normalizedIntent,
+    flowId,
+    steps,
+    skipped,
+    epilogue,
+    warnings,
+    summary: prompt ?? `${normalizedIntent} plan with ${steps.length} step(s)`,
+    estimatedTools: steps.reduce((acc, s) => acc + s.tools.length, 0),
+    context: {
+      intent: normalizedIntent,
+      probes,
+      entities: { components: [], actions: [] },
+      projectPath,
+    },
+  };
+}

package/src/flows/probes.ts

@@ -0,0 +1,70 @@
+/**
+ * Capability probes — detect what subsystems are available at runtime.
+ * All probes are resilient: they catch errors and return false on failure.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { AgentRuntime } from '../runtime/types.js';
+import type { ProbeResults } from './types.js';
+
+/**
+ * Run all 6 capability probes in parallel and return results.
+ */
+export async function runProbes(runtime: AgentRuntime, projectPath: string): Promise<ProbeResults> {
+  const [vault, brain, designSystem, sessionStore, projectRules, active] = await Promise.all([
+    probeVault(runtime),
+    probeBrain(runtime),
+    probeDesignSystem(runtime),
+    probeSessionStore(),
+    probeProjectRules(projectPath),
+    probeActive(),
+  ]);
+
+  return { vault, brain, designSystem, sessionStore, projectRules, active };
+}
+
+async function probeVault(runtime: AgentRuntime): Promise<boolean> {
+  try {
+    const stats = runtime.vault.stats();
+    return stats.totalEntries >= 0;
+  } catch {
+    return false;
+  }
+}
+
+async function probeBrain(runtime: AgentRuntime): Promise<boolean> {
+  try {
+    return runtime.brain.getVocabularySize() > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function probeDesignSystem(runtime: AgentRuntime): Promise<boolean> {
+  try {
+    return runtime.projectRegistry.list().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function probeSessionStore(): Promise<boolean> {
+  // Session store is always available in Soleri runtime
+  return true;
+}
+
+async function probeProjectRules(projectPath: string): Promise<boolean> {
+  try {
+    return (
+      existsSync(join(projectPath, 'docs', 'vault')) || existsSync(join(projectPath, '.soleri'))
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function probeActive(): Promise<boolean> {
+  // Always true when the engine is running
+  return true;
+}