@soleri/core 2.11.0 → 7.0.0

package/src/runtime/orchestrate-ops.ts

@@ -1,57 +1,180 @@
 /**
- * Orchestration operations — compose planning + brain + vault into high-level workflows.
+ * Orchestration operations — flow-engine-driven workflows.
  *
- * These ops are convenience wrappers that sequence multiple module calls:
- *   - orchestrate_plan: brain-informed plan creation
- *   - orchestrate_execute: start plan + brain session together
- *   - orchestrate_complete: finish plan + brain session + extract knowledge
+ * These ops wire the YAML flow engine into the facade layer:
+ *   - orchestrate_plan: intent detection + buildPlan from flow engine
+ *   - orchestrate_execute: FlowExecutor dispatches steps to facade ops
+ *   - orchestrate_complete: runEpilogue captures knowledge + session
  *   - orchestrate_status: combined status across all modules
  *   - orchestrate_quick_capture: one-call knowledge capture without full planning
  */
 
 import { z } from 'zod';
-import type { OpDefinition } from '../facades/types.js';
+import type { OpDefinition, FacadeConfig } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import { buildPlan } from '../flows/plan-builder.js';
+import { FlowExecutor } from '../flows/executor.js';
+import { createDispatcher } from '../flows/dispatch-registry.js';
+import { runEpilogue } from '../flows/epilogue.js';
+import type { OrchestrationPlan, ExecutionResult } from '../flows/types.js';
+
+// ---------------------------------------------------------------------------
+// Intent detection — keyword-based mapping from prompt to intent
+// ---------------------------------------------------------------------------
+
+const INTENT_KEYWORDS: [RegExp, string][] = [
+  [/\b(fix|bug|broken|error|crash|issue)\b/i, 'FIX'],
+  [/\b(review|audit|check|inspect)\b/i, 'REVIEW'],
+  [/\b(build|create|add|new|implement|scaffold)\b/i, 'BUILD'],
+  [/\b(plan|architect|design-system|roadmap)\b/i, 'PLAN'],
+  [/\b(enhance|improve|refactor|optimize)\b/i, 'ENHANCE'],
+  [/\b(explore|research|investigate|spike)\b/i, 'EXPLORE'],
+  [/\b(deploy|ship|release|publish)\b/i, 'DELIVER'],
+  [/\b(design|palette|theme|color|typography)\b/i, 'DESIGN'],
+];
+
+function detectIntent(prompt: string): string {
+  for (const [pattern, intent] of INTENT_KEYWORDS) {
+    if (pattern.test(prompt)) return intent;
+  }
+  return 'BUILD'; // default
+}
+
+// ---------------------------------------------------------------------------
+// In-memory plan store
+// ---------------------------------------------------------------------------
+
+interface PlanEntry {
+  plan: OrchestrationPlan;
+  executionResult?: ExecutionResult;
+  createdAt: number;
+}
+
+const planStore = new Map<string, PlanEntry>();
+
+// ---------------------------------------------------------------------------
+// Helper: create a runtime-backed dispatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a dispatch function that routes tool names to runtime modules.
+ * If facades are provided, uses the full dispatch registry.
+ * Otherwise, falls back to a simple runtime-based dispatcher.
+ */
+function buildDispatch(
+  agentId: string,
+  runtime: AgentRuntime,
+  facades?: FacadeConfig[],
+) {
+  if (facades && facades.length > 0) {
+    return createDispatcher(agentId, facades);
+  }
+
+  // Fallback: runtime-based dispatch for known tool patterns
+  return async (
+    toolName: string,
+    params: Record<string, unknown>,
+  ): Promise<{ tool: string; status: string; data?: unknown; error?: string }> => {
+    try {
+      // Handle well-known epilogue tools directly via runtime
+      if (toolName === 'capture_knowledge' || toolName.endsWith('_capture_knowledge')) {
+        const title = (params.title as string) ?? 'Flow execution';
+        const description = (params.content as string) ?? (params.description as string) ?? '';
+        const tags = (params.tags as string[]) ?? ['workflow'];
+        runtime.vault.add({
+          id: `flow-${Date.now()}`,
+          title,
+          description,
+          type: 'pattern',
+          domain: 'workflow',
+          severity: 'suggestion',
+          tags,
+        });
+        return { tool: toolName, status: 'ok', data: { title } };
+      }
+
+      if (toolName === 'session_capture' || toolName.endsWith('_session_capture')) {
+        // Session capture is best-effort
+        return { tool: toolName, status: 'ok', data: { sessionId: 'flow-session' } };
+      }
+
+      // For other tools: mark as unregistered (graceful degradation)
+      return { tool: toolName, status: 'unregistered' };
+    } catch (err) {
+      return {
+        tool: toolName,
+        status: 'error',
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Op factory
+// ---------------------------------------------------------------------------
 
 /**
  * Create the 5 orchestration operations for an agent runtime.
+ * Optionally accepts facades for full dispatch capability.
  */
-export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
+export function createOrchestrateOps(
+  runtime: AgentRuntime,
+  facades?: FacadeConfig[],
+): OpDefinition[] {
   const { planner, brainIntelligence, vault } = runtime;
+  const agentId = runtime.config.agentId;
 
   return [
     // ─── orchestrate_plan ─────────────────────────────────────────
     {
       name: 'orchestrate_plan',
       description:
-        'Create a brain-informed plan with recommendations from pattern strengths. ' +
-        'Fetches relevant brain recommendations for the domain/task, then creates a plan ' +
-        'with those recommendations injected as decisions.',
+        'Create a flow-engine-driven plan. Detects intent from the prompt, ' +
+        'loads the matching YAML flow, probes runtime capabilities, and builds ' +
+        'a pruned orchestration plan with gate-guarded steps.',
       auth: 'write',
       schema: z.object({
-        objective: z.string().describe('What the plan aims to achieve'),
-        scope: z.string().describe('Boundaries of the work'),
+        prompt: z
+          .string()
+          .describe('Natural language description of what to do'),
+        projectPath: z
+          .string()
+          .optional()
+          .default('.')
+          .describe('Project root path'),
+        // Legacy params — still accepted for backward compat
+        objective: z
+          .string()
+          .optional()
+          .describe('(Legacy) Plan objective — use prompt instead'),
+        scope: z
+          .string()
+          .optional()
+          .describe('(Legacy) Plan scope'),
         domain: z
           .string()
           .optional()
-          .describe('Domain for brain recommendations (e.g. "component", "styling")'),
+          .describe('Domain hint for brain recommendations'),
         tasks: z
           .array(z.object({ title: z.string(), description: z.string() }))
           .optional()
           .describe('Optional pre-defined tasks'),
       }),
       handler: async (params) => {
-        const objective = params.objective as string;
-        const scope = params.scope as string;
+        const prompt = (params.prompt as string) ?? (params.objective as string) ?? '';
+        const projectPath = (params.projectPath as string) ?? '.';
         const domain = params.domain as string | undefined;
-        const tasks = (params.tasks as Array<{ title: string; description: string }>) ?? [];
 
-        // Get brain recommendations — graceful degradation if no data
+        // 1. Detect intent from prompt
+        const intent = detectIntent(prompt);
+
+        // 2. Get brain recommendations — graceful degradation
         let recommendations: Array<{ pattern: string; strength: number }> = [];
         try {
           const raw = brainIntelligence.recommend({
             domain,
-            task: objective,
+            task: prompt,
             limit: 5,
           });
           recommendations = raw.map((r) => ({
@@ -59,23 +182,63 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
             strength: r.strength,
           }));
         } catch {
-          // Brain has no data yet — proceed without recommendations
+          // Brain has no data yet
         }
 
-        // Build decisions from recommendations
+        // Fallback to vault if brain empty
+        if (recommendations.length === 0) {
+          try {
+            const vaultResults = vault.search(prompt, { domain, limit: 5 });
+            recommendations = vaultResults.map((r) => ({
+              pattern: r.entry.title,
+              strength: 50,
+            }));
+          } catch {
+            // Vault search failed
+          }
+        }
+
+        // 3. Build flow-engine plan
+        const plan = await buildPlan(intent, agentId, projectPath, runtime, prompt);
+
+        // 4. Store in planStore
+        planStore.set(plan.planId, { plan, createdAt: Date.now() });
+
+        // 5. Also create a planner plan for lifecycle tracking (backward compat)
         const decisions = recommendations.map(
           (r) => `Brain pattern: ${r.pattern} (strength: ${r.strength.toFixed(1)})`,
         );
+        const tasks = (params.tasks as Array<{ title: string; description: string }>) ?? [];
 
-        // Create plan with recommendations as context
-        const plan = planner.create({
-          objective,
-          scope,
-          decisions,
-          tasks,
-        });
+        let legacyPlan;
+        try {
+          legacyPlan = planner.create({
+            objective: prompt,
+            scope: (params.scope as string) ?? `${intent} workflow`,
+            decisions,
+            tasks,
+          });
+        } catch {
+          // Planner creation failed — flow plan still valid
+        }
 
-        return { plan, recommendations };
+        return {
+          plan: legacyPlan ?? {
+            id: plan.planId,
+            objective: prompt,
+            decisions,
+          },
+          recommendations,
+          flow: {
+            planId: plan.planId,
+            intent: plan.intent,
+            flowId: plan.flowId,
+            stepsCount: plan.steps.length,
+            skippedCount: plan.skipped.length,
+            warnings: plan.warnings,
+            estimatedTools: plan.estimatedTools,
+          },
+        };
       },
     },
 
@@ -83,11 +246,11 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'orchestrate_execute',
       description:
-        'Start plan execution and open a brain session to track the work. ' +
-        'The plan must be in "approved" status. Returns both the updated plan and session ID.',
+        'Execute a flow-engine plan. Dispatches each step to its facade ops, ' +
+        'evaluates gates, and tracks execution with a brain session.',
       auth: 'write',
       schema: z.object({
-        planId: z.string().describe('ID of the approved plan to start executing'),
+        planId: z.string().describe('ID of the plan to execute (flow planId or legacy planId)'),
         domain: z.string().optional().describe('Domain for brain session tracking'),
         context: z.string().optional().describe('Additional context for the brain session'),
       }),
@@ -96,10 +259,41 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
         const domain = params.domain as string | undefined;
         const context = params.context as string | undefined;
 
-        // Start plan execution
-        const plan = planner.startExecution(planId);
+        // Look up flow plan
+        const entry = planStore.get(planId);
+
+        if (entry) {
+          // Flow-engine execution path
+          const dispatch = buildDispatch(agentId, runtime, facades);
+          const executor = new FlowExecutor(dispatch);
+          const executionResult = await executor.execute(entry.plan);
+
+          // Store result
+          entry.executionResult = executionResult;
+
+          // Start brain session
+          const session = brainIntelligence.lifecycle({
+            action: 'start',
+            domain,
+            context,
+            planId,
+          });
 
-        // Start brain session linked to this plan
+          return {
+            plan: { id: planId, status: 'executing' },
+            session,
+            execution: {
+              status: executionResult.status,
+              stepsCompleted: executionResult.stepsCompleted,
+              totalSteps: executionResult.totalSteps,
+              toolsCalled: executionResult.toolsCalled,
+              durationMs: executionResult.durationMs,
+            },
+          };
+        }
+
+        // Legacy path: no flow plan found, use planner directly
+        const plan = planner.startExecution(planId);
         const session = brainIntelligence.lifecycle({
           action: 'start',
           domain,
@@ -115,9 +309,8 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'orchestrate_complete',
       description:
-        'Complete plan execution, end brain session, and extract knowledge. ' +
-        'Performs three steps: marks plan completed, ends the brain session with outcome, ' +
-        'and runs knowledge extraction on the session.',
+        'Complete plan execution, run epilogue (knowledge capture + session capture), ' +
+        'end brain session, and clean up.',
       auth: 'write',
       schema: z.object({
         planId: z.string().describe('ID of the executing plan to complete'),
@@ -137,10 +330,10 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
         const toolsUsed = (params.toolsUsed as string[]) ?? [];
         const filesModified = (params.filesModified as string[]) ?? [];
 
-        // Complete the plan
+        // Complete the planner plan (legacy lifecycle)
         const plan = planner.complete(planId);
 
-        // End brain session with outcome
+        // End brain session
         const session = brainIntelligence.lifecycle({
           action: 'end',
           sessionId,
@@ -150,15 +343,36 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
           filesModified,
         });
 
-        // Extract knowledge from the session — graceful if nothing to extract
+        // Extract knowledge
         let extraction = null;
         try {
           extraction = brainIntelligence.extractKnowledge(sessionId);
         } catch {
-          // Session may not have enough signal for extraction — that's OK
+          // Not enough signal
+        }
+
+        // Run flow-engine epilogue if we have a flow plan
+        let epilogueResult = null;
+        const entry = planStore.get(planId);
+        if (entry) {
+          try {
+            const dispatch = buildDispatch(agentId, runtime, facades);
+            const summary = `${outcome}: ${entry.plan.summary}. Tools: ${toolsUsed.join(', ') || 'none'}. Files: ${filesModified.join(', ') || 'none'}.`;
+            epilogueResult = await runEpilogue(
+              dispatch,
+              entry.plan.context.probes,
+              entry.plan.context.projectPath,
+              summary,
+            );
+          } catch {
+            // Epilogue is best-effort
+          }
+
+          // Clean up plan store
+          planStore.delete(planId);
         }
 
-        return { plan, session, extraction };
+        return { plan, session, extraction, epilogue: epilogueResult };
       },
     },
 
@@ -167,7 +381,7 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
       name: 'orchestrate_status',
       description:
         'Get combined orchestration status: active plans, brain session context, ' +
-        'vault stats, and recent brain recommendations.',
+        'vault stats, recent brain recommendations, and flow plan store.',
       auth: 'read',
       schema: z.object({
         domain: z.string().optional().describe('Filter recommendations by domain'),
@@ -180,22 +394,13 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
         const domain = params.domain as string | undefined;
         const sessionLimit = (params.sessionLimit as number) ?? 5;
 
-        // Active plans
         const activePlans = planner.getActive();
-
-        // Brain session context
         const sessionContext = brainIntelligence.getSessionContext(sessionLimit);
-
-        // Vault stats
         const vaultStats = vault.stats();
 
-        // Recent recommendations — graceful degradation
         let recommendations: Array<{ pattern: string; strength: number }> = [];
         try {
-          const raw = brainIntelligence.recommend({
-            domain,
-            limit: 5,
-          });
+          const raw = brainIntelligence.recommend({ domain, limit: 5 });
           recommendations = raw.map((r) => ({
             pattern: r.pattern,
             strength: r.strength,
@@ -204,15 +409,25 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
           // No recommendations available
         }
 
-        // Brain intelligence stats
         const brainStats = brainIntelligence.getStats();
 
+        // Include flow plan store info
+        const flowPlans = Array.from(planStore.entries()).map(([id, e]) => ({
+          planId: id,
+          intent: e.plan.intent,
+          flowId: e.plan.flowId,
+          stepsCount: e.plan.steps.length,
+          hasResult: !!e.executionResult,
+          createdAt: e.createdAt,
+        }));
+
         return {
           activePlans,
           sessionContext,
           vaultStats,
           recommendations,
           brainStats,
+          flowPlans,
         };
       },
     },
@@ -242,7 +457,6 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
         const filesModified = (params.filesModified as string[]) ?? [];
         const outcome = (params.outcome as string) ?? 'completed';
 
-        // Start session
         const startedSession = brainIntelligence.lifecycle({
           action: 'start',
           domain,
@@ -251,7 +465,6 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
           filesModified,
         });
 
-        // End session immediately with outcome
         const endedSession = brainIntelligence.lifecycle({
           action: 'end',
           sessionId: startedSession.id,
@@ -260,18 +473,14 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
           planOutcome: outcome,
         });
 
-        // Extract knowledge — graceful if nothing to extract
         let extraction = null;
         try {
           extraction = brainIntelligence.extractKnowledge(startedSession.id);
         } catch {
-          // Not enough signal — that's fine
+          // Not enough signal
         }
 
-        return {
-          session: endedSession,
-          extraction,
-        };
+        return { session: endedSession, extraction };
       },
     },
   ];

package/src/runtime/runtime.ts

@@ -85,21 +85,24 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   // Planner — multi-step task tracking
   const planner = new Planner(plansPath);
 
-  // Cognee — vector search client (graceful degradation if Cognee is down)
-  const cogneePartial: Partial<import('../cognee/types.js').CogneeConfig> = { dataset: agentId };
-  if (process.env.COGNEE_BASE_URL) cogneePartial.baseUrl = process.env.COGNEE_BASE_URL;
-  if (process.env.COGNEE_API_TOKEN) cogneePartial.apiToken = process.env.COGNEE_API_TOKEN;
-  if (process.env.COGNEE_DATASET) cogneePartial.dataset = process.env.COGNEE_DATASET;
-  const cognee = new CogneeClient(cogneePartial);
+  // Cognee — vector search client (opt-in, graceful degradation if Cognee is down)
+  let cognee: CogneeClient | null = null;
+  if (config.cognee) {
+    const cogneePartial: Partial<import('../cognee/types.js').CogneeConfig> = { dataset: agentId };
+    if (process.env.COGNEE_BASE_URL) cogneePartial.baseUrl = process.env.COGNEE_BASE_URL;
+    if (process.env.COGNEE_API_TOKEN) cogneePartial.apiToken = process.env.COGNEE_API_TOKEN;
+    if (process.env.COGNEE_DATASET) cogneePartial.dataset = process.env.COGNEE_DATASET;
+    cognee = new CogneeClient(cogneePartial);
+  }
 
   // Brain — intelligence layer (TF-IDF scoring, auto-tagging, dedup)
-  const brain = new Brain(vault, cognee);
+  const brain = new Brain(vault, cognee ?? undefined);
 
   // Brain Intelligence — pattern strengths, session knowledge, intelligence pipeline
   const brainIntelligence = new BrainIntelligence(vault, brain);
 
   // Curator — vault self-maintenance (dedup, contradictions, grooming, health)
-  const curator = new Curator(vault, cognee);
+  const curator = new Curator(vault, cognee ?? undefined);
 
   // Governance — policy engine + proposal tracker for gated knowledge capture
   const governance = new Governance(vault);
@@ -132,13 +135,16 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   const anthropicKeyPool = new KeyPool(keyPoolFiles.anthropic);
   const llmClient = new LLMClient(openaiKeyPool, anthropicKeyPool, agentId);
 
-  // Cognee Sync Manager — queue-based dirty tracking with offline resilience
-  const syncManager = new CogneeSyncManager(
-    vault.getProvider(),
-    cognee,
-    cogneePartial.dataset ?? agentId,
-  );
-  vault.setSyncManager(syncManager);
+  // Cognee Sync Manager — queue-based dirty tracking with offline resilience (only when Cognee enabled)
+  let syncManager: CogneeSyncManager | null = null;
+  if (cognee) {
+    syncManager = new CogneeSyncManager(
+      vault.getProvider(),
+      cognee,
+      process.env.COGNEE_DATASET ?? agentId,
+    );
+    vault.setSyncManager(syncManager);
+  }
 
   // Intake Pipeline — PDF/book ingestion with LLM classification
   const intakePipeline = new IntakePipeline(vault.getProvider(), vault, llmClient);
@@ -168,7 +174,10 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   const health = new HealthRegistry();
   health.register('vault', 'healthy');
   health.register('brain', 'healthy');
-  health.register('cognee', cognee.getStatus()?.available ? 'healthy' : 'degraded');
+  health.register(
+    'cognee',
+    cognee ? (cognee.getStatus()?.available ? 'healthy' : 'degraded') : 'down',
+  );
   health.register(
     'llm',
     llmClient.isAvailable().openai || llmClient.isAvailable().anthropic ? 'healthy' : 'degraded',
@@ -221,8 +230,8 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     knowledgeReview,
     createdAt: Date.now(),
     close: () => {
-      syncManager.close();
-      cognee.resetPendingCognify();
+      syncManager?.close();
+      cognee?.resetPendingCognify();
       vaultManager.close();
     },
   };

package/src/runtime/types.ts

@@ -48,6 +48,8 @@ export interface AgentRuntimeConfig {
   logLevel?: LogLevel;
   /** Path to shared global vault. Default: ~/.soleri/vault.db */
   sharedVaultPath?: string;
+  /** Enable Cognee vector search integration. Default: false (opt-in). */
+  cognee?: boolean;
 }
 
 /**
@@ -63,7 +65,8 @@ export interface AgentRuntime {
   planner: Planner;
   curator: Curator;
   governance: Governance;
-  cognee: CogneeClient;
+  /** Cognee vector search client. Null when Cognee integration is disabled. */
+  cognee: CogneeClient | null;
   loop: LoopManager;
   identityManager: IdentityManager;
   intentRouter: IntentRouter;
@@ -72,7 +75,8 @@ export interface AgentRuntime {
   telemetry: Telemetry;
   projectRegistry: ProjectRegistry;
   templateManager: TemplateManager;
-  syncManager: CogneeSyncManager;
+  /** Cognee sync manager. Null when Cognee integration is disabled. */
+  syncManager: CogneeSyncManager | null;
   intakePipeline: IntakePipeline;
   /** Mutable auth policy — controls facade dispatch enforcement. */
   authPolicy: AuthPolicy;