@soleri/core 2.12.0 → 8.0.0

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

package/src/flows/types.ts

@@ -0,0 +1,217 @@
+/**
+ * Flow engine types — YAML-driven workflow orchestration.
+ *
+ * Flow → Steps → Chains (ops) → Gates → Execution
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Gate types
+// ---------------------------------------------------------------------------
+
+export const gateActionSchema = z.object({
+  action: z.enum(['STOP', 'BRANCH', 'CONTINUE']),
+  goto: z.string().optional(),
+  message: z.string().optional(),
+});
+
+export const gateSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('GATE'),
+    condition: z.string(),
+    'on-false': gateActionSchema,
+  }),
+  z.object({
+    type: z.literal('SCORE'),
+    min: z.number(),
+    'grade-thresholds': z.record(z.number()).optional(),
+    'on-false': gateActionSchema,
+  }),
+  z.object({
+    type: z.literal('CHECKPOINT'),
+    condition: z.string().optional(),
+    save: z.array(z.string()).optional(),
+    'on-false': gateActionSchema,
+  }),
+  z.object({
+    type: z.literal('BRANCH'),
+    'on-false': gateActionSchema.optional(),
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// Step
+// ---------------------------------------------------------------------------
+
+export const flowStepSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  chains: z.array(z.string()).optional(),
+  parallel: z.boolean().optional(),
+  output: z.array(z.string()).optional(),
+  gate: gateSchema.optional(),
+  /** Capability IDs required by this step (v2) */
+  needs: z.array(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Flow (root YAML structure)
+// ---------------------------------------------------------------------------
+
+export const flowSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  version: z.string().optional(),
+  triggers: z.object({
+    modes: z.array(z.string()),
+    contexts: z.array(z.string()).optional(),
+    'min-confidence': z.enum(['HIGH', 'MEDIUM', 'LOW']).optional(),
+  }),
+  steps: z.array(flowStepSchema),
+  scoring: z
+    .object({
+      weights: z.record(z.number()),
+      formula: z.string().optional(),
+    })
+    .optional(),
+  'on-error': z
+    .object({
+      default: z
+        .object({
+          action: z.string(),
+          message: z.string().optional(),
+          recovery: z.string().optional(),
+        })
+        .optional(),
+      'max-retries': z.number().optional(),
+      escalation: z
+        .object({
+          action: z.string(),
+          message: z.string().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+  /** Strategy when a step's capability requirement is not satisfied */
+  onMissingCapability: z
+    .object({
+      default: z.enum(['skip-with-warning', 'fail', 'ask-user']).default('skip-with-warning'),
+      blocking: z.array(z.string()).optional().default([]),
+    })
+    .optional(),
+  metadata: z
+    .object({
+      author: z.string().optional(),
+      domain: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+export type Flow = z.infer<typeof flowSchema>;
+export type FlowStep = z.infer<typeof flowStepSchema>;
+export type Gate = z.infer<typeof gateSchema>;
+export type GateAction = z.infer<typeof gateActionSchema>;
+
+// ---------------------------------------------------------------------------
+// Probes
+// ---------------------------------------------------------------------------
+
+export type ProbeName =
+  | 'vault'
+  | 'brain'
+  | 'designSystem'
+  | 'sessionStore'
+  | 'projectRules'
+  | 'active';
+
+export interface ProbeResults {
+  vault: boolean;
+  brain: boolean;
+  designSystem: boolean;
+  sessionStore: boolean;
+  projectRules: boolean;
+  active: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Plan (built from flow + probes)
+// ---------------------------------------------------------------------------
+
+export interface PlanStep {
+  id: string;
+  name: string;
+  tools: string[];
+  parallel: boolean;
+  requires: ProbeName[];
+  gate?: {
+    type: string;
+    condition?: string;
+    min?: number;
+    onFail?: { action: string; goto?: string; message?: string };
+  };
+  status: 'pending' | 'running' | 'passed' | 'failed' | 'skipped' | 'gate-paused';
+}
+
+export interface SkippedStep {
+  id: string;
+  name: string;
+  reason: string;
+}
+
+export interface OrchestrationPlan {
+  planId: string;
+  intent: string;
+  flowId: string;
+  steps: PlanStep[];
+  skipped: SkippedStep[];
+  epilogue: string[];
+  warnings: string[];
+  summary: string;
+  estimatedTools: number;
+  context: OrchestrationContext;
+}
+
+export interface OrchestrationContext {
+  intent: string;
+  probes: ProbeResults;
+  entities: { components: string[]; actions: string[]; technologies?: string[] };
+  projectPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+export interface StepResult {
+  stepId: string;
+  status: 'passed' | 'failed' | 'skipped' | 'gate-paused';
+  toolResults: Record<string, { tool: string; status: string; data?: unknown; error?: string }>;
+  durationMs: number;
+  gateResult?: { action: string; message?: string };
+}
+
+export interface ExecutionResult {
+  planId: string;
+  status: 'completed' | 'partial' | 'failed';
+  stepsCompleted: number;
+  totalSteps: number;
+  toolsCalled: string[];
+  durationMs: number;
+  stepResults: StepResult[];
+}
+
+// ---------------------------------------------------------------------------
+// Gate verdict
+// ---------------------------------------------------------------------------
+
+export interface GateVerdict {
+  passed: boolean;
+  action: 'CONTINUE' | 'STOP' | 'BRANCH';
+  goto?: string;
+  message?: string;
+  score?: number;
+}

package/src/health/doctor-checks.ts

@@ -0,0 +1,115 @@
+/**
+ * Doctor Checks — 8 specialized health checks for comprehensive diagnostics.
+ *
+ * Each check validates a subsystem and reports pass/warn/fail.
+ */
+
+import type { HealthRegistry } from './health-registry.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+export interface DoctorCheckResult {
+  check: string;
+  status: 'pass' | 'warn' | 'fail';
+  message: string;
+}
+
+export function runDoctorChecks(runtime: AgentRuntime): DoctorCheckResult[] {
+  const results: DoctorCheckResult[] = [];
+
+  // 1. Config
+  try {
+    const id = runtime.config.agentId;
+    results.push({
+      check: 'config',
+      status: id ? 'pass' : 'fail',
+      message: id ? `Agent "${id}" configured` : 'No agent ID',
+    });
+  } catch (e) {
+    results.push({ check: 'config', status: 'fail', message: (e as Error).message });
+  }
+
+  // 2. Database
+  try {
+    runtime.vault.getProvider().get<{ v: number }>('PRAGMA user_version');
+    results.push({ check: 'database', status: 'pass', message: 'SQLite healthy' });
+  } catch (e) {
+    results.push({ check: 'database', status: 'fail', message: (e as Error).message });
+  }
+
+  // 3. Vault
+  try {
+    const stats = runtime.vault.stats();
+    results.push({
+      check: 'vault',
+      status: stats.totalEntries > 0 ? 'pass' : 'warn',
+      message: stats.totalEntries > 0 ? `${stats.totalEntries} entries` : 'Vault empty',
+    });
+  } catch (e) {
+    results.push({ check: 'vault', status: 'fail', message: (e as Error).message });
+  }
+
+  // 4. LLM
+  try {
+    const pool = runtime.keyPool;
+    const total = (pool.openai?.getActiveKey() ? 1 : 0) + (pool.anthropic?.getActiveKey() ? 1 : 0);
+    results.push({
+      check: 'llm',
+      status: total > 0 ? 'pass' : 'warn',
+      message: total > 0 ? `${total} provider(s) available` : 'No API keys — LLM features disabled',
+    });
+  } catch {
+    results.push({ check: 'llm', status: 'warn', message: 'LLM check failed' });
+  }
+
+  // 5. Auth
+  results.push({
+    check: 'auth',
+    status: 'pass',
+    message: `Mode: ${runtime.authPolicy.mode}`,
+  });
+
+  // 6. Plugins
+  try {
+    const count = runtime.pluginRegistry.list().length;
+    results.push({ check: 'plugins', status: 'pass', message: `${count} plugin(s)` });
+  } catch {
+    results.push({ check: 'plugins', status: 'warn', message: 'Plugin check failed' });
+  }
+
+  // 7. Embeddings (Cognee)
+  try {
+    const available = runtime.cognee?.isAvailable ?? false;
+    results.push({
+      check: 'embeddings',
+      status: available ? 'pass' : 'warn',
+      message: available ? 'Cognee available' : 'Cognee not available — vector search disabled',
+    });
+  } catch {
+    results.push({ check: 'embeddings', status: 'warn', message: 'Embedding check failed' });
+  }
+
+  // 8. Security
+  results.push({
+    check: 'security',
+    status: runtime.authPolicy.mode === 'permissive' ? 'warn' : 'pass',
+    message:
+      runtime.authPolicy.mode === 'permissive'
+        ? 'Permissive mode — all ops allowed'
+        : `Enforcement: ${runtime.authPolicy.mode}`,
+  });
+
+  return results;
+}
+
+export function registerDoctorChecks(health: HealthRegistry, runtime: AgentRuntime): void {
+  const results = runDoctorChecks(runtime);
+  for (const r of results) {
+    health.register(
+      r.check,
+      r.status === 'pass' ? 'healthy' : r.status === 'warn' ? 'degraded' : 'down',
+    );
+    if (r.status !== 'pass') {
+      health.update(r.check, r.status === 'warn' ? 'degraded' : 'down', r.message);
+    }
+  }
+}