@soleri/core 2.11.0 → 7.0.0

package/src/flows/context-router.ts

@@ -0,0 +1,257 @@
+/**
+ * Context-sensitive chain routing — the same intent routes to different chain
+ * sequences depending on what's being built/fixed/reviewed.
+ *
+ * Building a Button follows a different workflow than building a Page layout.
+ */
+
+import type { PlanStep, ProbeName } from './types.js';
+import { chainToToolName, chainToRequires } from './plan-builder.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ContextOverride {
+  /** Pattern to match against prompt or entities */
+  match: RegExp;
+  /** Context label */
+  context: string;
+  /** Chain substitutions: original chain → replacement chain */
+  chainOverrides?: Record<string, string>;
+  /** Additional chains to inject before specific steps */
+  injectBefore?: Record<string, string[]>;
+  /** Additional chains to inject after specific steps */
+  injectAfter?: Record<string, string[]>;
+  /** Steps to skip in this context */
+  skipSteps?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Context override definitions
+// ---------------------------------------------------------------------------
+
+const BUILD_OVERRIDES: ContextOverride[] = [
+  {
+    match: /\b(button|icon|badge|chip|tag|pill)\b/i,
+    context: 'small-component',
+    skipSteps: ['get-architecture'],
+    injectBefore: {
+      validate: ['button-semantics-check'],
+    },
+  },
+  {
+    match: /\b(page|layout|dashboard|screen|view)\b/i,
+    context: 'large-component',
+    injectBefore: {
+      validate: ['responsive-patterns'],
+    },
+    injectAfter: {
+      validate: ['performance-check'],
+    },
+  },
+  {
+    match: /\b(form|input|select|textarea|checkbox|radio|switch|dropdown)\b/i,
+    context: 'form-component',
+    injectBefore: {
+      validate: ['defensive-design', 'accessibility-precheck'],
+    },
+  },
+  {
+    match: /\b(modal|dialog|sheet|drawer|popover|overlay|tooltip)\b/i,
+    context: 'container-component',
+    injectBefore: {
+      validate: ['container-pattern-check', 'dialog-patterns'],
+    },
+  },
+];
+
+const FIX_OVERRIDES: ContextOverride[] = [
+  {
+    match: /\b(styl(e|ing)|color|token|theme|palette|css)\b/i,
+    context: 'design-fix',
+    injectBefore: {
+      validate: ['contrast-check', 'token-validation'],
+    },
+  },
+  {
+    match: /\b(accessib|a11y|aria|screen.?reader|keyboard|focus)\b/i,
+    context: 'a11y-fix',
+    injectBefore: {
+      validate: ['accessibility-audit'],
+    },
+  },
+];
+
+const REVIEW_OVERRIDES: ContextOverride[] = [
+  {
+    match: /\b(pr|pull.?request|diff|merge)\b/i,
+    context: 'pr-review',
+    injectAfter: {
+      'check-rules': ['review-pr-design'],
+    },
+  },
+  {
+    match: /\b(architecture|import|dependency|structure)\b/i,
+    context: 'architecture-review',
+    injectAfter: {
+      'check-rules': ['check-architecture'],
+    },
+  },
+];
+
+/**
+ * Registry mapping flow IDs to their context overrides.
+ */
+const FLOW_OVERRIDES: Record<string, ContextOverride[]> = {
+  'BUILD-flow': BUILD_OVERRIDES,
+  'FIX-flow': FIX_OVERRIDES,
+  'REVIEW-flow': REVIEW_OVERRIDES,
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect which contexts apply to a prompt and entity set.
+ * Returns an array of matching context labels.
+ */
+export function detectContext(
+  prompt: string,
+  entities: { components: string[]; actions: string[] },
+): string[] {
+  const contexts: string[] = [];
+  const searchText = [prompt, ...entities.components, ...entities.actions].join(' ');
+
+  // Check all flow overrides — a prompt might match contexts across flows
+  for (const overrides of Object.values(FLOW_OVERRIDES)) {
+    for (const override of overrides) {
+      if (override.match.test(searchText) && !contexts.includes(override.context)) {
+        contexts.push(override.context);
+      }
+    }
+  }
+
+  return contexts;
+}
+
+/**
+ * Apply context overrides to a set of plan steps: chain substitutions,
+ * injections (before/after), and step skipping.
+ */
+export function applyContextOverrides(
+  steps: PlanStep[],
+  contexts: string[],
+  flowId: string,
+  agentId: string = 'agent',
+): PlanStep[] {
+  const overrides = FLOW_OVERRIDES[flowId];
+  if (!overrides || contexts.length === 0) return steps;
+
+  // Collect active overrides for the detected contexts
+  const active = overrides.filter((o) => contexts.includes(o.context));
+  if (active.length === 0) return steps;
+
+  // Aggregate all skip, inject-before, inject-after, and chain overrides
+  const skipSet = new Set<string>();
+  const injectBefore = new Map<string, string[]>();
+  const injectAfter = new Map<string, string[]>();
+  const chainSubs = new Map<string, string>();
+
+  for (const ov of active) {
+    if (ov.skipSteps) ov.skipSteps.forEach((s) => skipSet.add(s));
+    if (ov.injectBefore) {
+      for (const [stepId, chains] of Object.entries(ov.injectBefore)) {
+        const existing = injectBefore.get(stepId) ?? [];
+        injectBefore.set(stepId, [...existing, ...chains]);
+      }
+    }
+    if (ov.injectAfter) {
+      for (const [stepId, chains] of Object.entries(ov.injectAfter)) {
+        const existing = injectAfter.get(stepId) ?? [];
+        injectAfter.set(stepId, [...existing, ...chains]);
+      }
+    }
+    if (ov.chainOverrides) {
+      for (const [from, to] of Object.entries(ov.chainOverrides)) {
+        chainSubs.set(from, to);
+      }
+    }
+  }
+
+  const result: PlanStep[] = [];
+
+  for (const step of steps) {
+    // 1. Skip steps
+    if (skipSet.has(step.id)) continue;
+
+    // 2. Inject before
+    const beforeChains = injectBefore.get(step.id);
+    if (beforeChains) {
+      result.push(buildInjectedStep(step.id, 'before', beforeChains, agentId));
+    }
+
+    // 3. Apply chain substitutions to existing step
+    let processed = step;
+    if (chainSubs.size > 0) {
+      const newTools = step.tools.map((tool) => {
+        for (const [from, to] of chainSubs) {
+          const fromTool = chainToToolName(from, agentId);
+          if (tool === fromTool) return chainToToolName(to, agentId);
+        }
+        return tool;
+      });
+      if (newTools.some((t, i) => t !== step.tools[i])) {
+        processed = { ...step, tools: newTools };
+      }
+    }
+
+    result.push(processed);
+
+    // 4. Inject after
+    const afterChains = injectAfter.get(step.id);
+    if (afterChains) {
+      result.push(buildInjectedStep(step.id, 'after', afterChains, agentId));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get all registered context overrides for a flow (useful for introspection).
+ */
+export function getFlowOverrides(flowId: string): ContextOverride[] {
+  return FLOW_OVERRIDES[flowId] ?? [];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a synthetic PlanStep from injected chains.
+ */
+function buildInjectedStep(
+  anchorStepId: string,
+  position: 'before' | 'after',
+  chains: string[],
+  agentId: string,
+): PlanStep {
+  const tools = chains.map((c) => chainToToolName(c, agentId));
+  const requires: ProbeName[] = [];
+  for (const chain of chains) {
+    const req = chainToRequires(chain);
+    if (req && !requires.includes(req)) requires.push(req);
+  }
+
+  return {
+    id: `ctx-${position}-${anchorStepId}`,
+    name: `Context: ${chains.join(', ')} (${position} ${anchorStepId})`,
+    tools,
+    parallel: chains.length > 1,
+    requires,
+    status: 'pending',
+  };
+}

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