@soleri/core 2.12.0 → 7.0.0

package/src/runtime/domain-ops.ts

@@ -1,13 +1,18 @@
 /**
- * Domain facade factory — creates the standard 5-op domain facade pattern.
+ * Domain facade factory — creates domain facades with optional pack support.
  *
- * Every domain gets: get_patterns, search, get_entry, capture, remove.
- * This replaces per-domain generated facade files.
+ * Without packs: every domain gets the standard 5 ops (get_patterns, search,
+ * get_entry, capture, remove).
+ *
+ * With packs: pack ops are PRIMARY, standard 5 ops are FALLBACK for any op
+ * name not defined by the pack. Pack standalone facades are registered as
+ * additional MCP tools.
  */
 
 import { z } from 'zod';
 import type { FacadeConfig, OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import type { DomainPack } from '../domain-packs/types.js';
 
 function capitalize(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1);
@@ -200,16 +205,77 @@ export function createDomainFacade(
 }
 
 /**
- * Create domain facades for all domains.
+ * Create domain facades for all domains, with optional pack support.
+ *
+ * When packs are provided:
+ * - For each domain, check if any pack claims it via pack.domains[]
+ * - If a pack claims the domain: pack ops are PRIMARY, standard 5 ops are
+ *   FALLBACK (only for op names not defined by the pack)
+ * - Pack standalone facades (pack.facades[]) are registered as additional
+ *   MCP tools with agentId prefix
+ * - Domains not claimed by any pack get the standard 5 ops (OCP)
+ *
+ * When packs is undefined or empty: identical to previous behavior.
  *
  * @param runtime - The agent runtime
  * @param agentId - Agent identifier
  * @param domains - Array of domain names
+ * @param packs - Optional array of loaded domain packs
  */
 export function createDomainFacades(
   runtime: AgentRuntime,
   agentId: string,
   domains: string[],
+  packs?: DomainPack[],
 ): FacadeConfig[] {
-  return domains.map((d) => createDomainFacade(runtime, agentId, d));
+  // Build a map: domain name → pack that claims it
+  const packByDomain = new Map<string, DomainPack>();
+  if (packs) {
+    for (const pack of packs) {
+      for (const domain of pack.domains) {
+        packByDomain.set(domain, pack);
+      }
+    }
+  }
+
+  // Create domain facades (with pack merge when applicable)
+  const domainFacades = domains.map((domain) => {
+    const pack = packByDomain.get(domain);
+    if (!pack) {
+      // No pack claims this domain — standard 5-op facade (OCP)
+      return createDomainFacade(runtime, agentId, domain);
+    }
+
+    // Pack claims this domain — merge ops
+    const standardFacade = createDomainFacade(runtime, agentId, domain);
+    const packOpNames = new Set(pack.ops.map((op) => op.name));
+
+    // Pack ops are primary; standard ops are fallback for unclaimed names
+    const mergedOps: OpDefinition[] = [
+      ...pack.ops,
+      ...standardFacade.ops.filter((op) => !packOpNames.has(op.name)),
+    ];
+
+    return {
+      ...standardFacade,
+      ops: mergedOps,
+    };
+  });
+
+  // Collect standalone facades from packs (prefixed with agentId)
+  const standaloneFacades: FacadeConfig[] = [];
+  if (packs) {
+    for (const pack of packs) {
+      if (pack.facades) {
+        for (const facade of pack.facades) {
+          standaloneFacades.push({
+            ...facade,
+            name: `${agentId}_${facade.name}`,
+          });
+        }
+      }
+    }
+  }
+
+  return [...domainFacades, ...standaloneFacades];
 }

package/src/runtime/facades/cognee-facade.ts

@@ -11,7 +11,9 @@ import type { CogneeSearchType } from '../../cognee/types.js';
 import { createCogneeSyncOps } from '../cognee-sync-ops.js';
 
 export function createCogneeFacadeOps(runtime: AgentRuntime): OpDefinition[] {
-  const { cognee, vault, syncManager } = runtime;
+  // Only called when runtime.cognee is non-null (guarded in createSemanticFacades)
+  const cognee = runtime.cognee!;
+  const { vault, syncManager } = runtime;
 
   return [
     // ─── Cognee (inline from core-ops.ts) ───────────────────────

package/src/runtime/facades/index.ts

@@ -22,7 +22,7 @@ import { createAgencyFacadeOps } from './agency-facade.js';
 import { createChatFacadeOps } from './chat-facade.js';
 
 export function createSemanticFacades(runtime: AgentRuntime, agentId: string): FacadeConfig[] {
-  return [
+  const facades: FacadeConfig[] = [
     {
       name: `${agentId}_vault`,
       description: 'Knowledge management — search, CRUD, import/export, intake, archival.',
@@ -69,11 +69,6 @@ export function createSemanticFacades(runtime: AgentRuntime, agentId: string): F
       description: 'Agent behavior — identity, intent routing, morphing, guidelines, governance.',
       ops: createControlFacadeOps(runtime),
     },
-    {
-      name: `${agentId}_cognee`,
-      description: 'Knowledge graph — Cognee search, sync, export, graph stats.',
-      ops: createCogneeFacadeOps(runtime),
-    },
     {
       name: `${agentId}_context`,
       description: 'Context analysis — entity extraction, knowledge retrieval, confidence scoring.',
@@ -92,4 +87,15 @@ export function createSemanticFacades(runtime: AgentRuntime, agentId: string): F
       ops: createChatFacadeOps(runtime),
     },
   ];
+
+  // Cognee facade — only registered when Cognee integration is enabled
+  if (runtime.cognee) {
+    facades.push({
+      name: `${agentId}_cognee`,
+      description: 'Knowledge graph — Cognee search, sync, export, graph stats.',
+      ops: createCogneeFacadeOps(runtime),
+    });
+  }
+
+  return facades;
 }

package/src/runtime/facades/vault-facade.ts

@@ -12,6 +12,7 @@ import { createVaultExtraOps } from '../vault-extra-ops.js';
 import { createCaptureOps } from '../capture-ops.js';
 import { createIntakeOps } from '../intake-ops.js';
 import { createVaultSharingOps } from '../vault-sharing-ops.js';
+import { createVaultLinkingOps } from '../vault-linking-ops.js';
 import { ObsidianSync } from '../../vault/obsidian-sync.js';
 
 export function createVaultFacadeOps(runtime: AgentRuntime): OpDefinition[] {
@@ -479,5 +480,6 @@ export function createVaultFacadeOps(runtime: AgentRuntime): OpDefinition[] {
     ...createCaptureOps(runtime),
     ...createIntakeOps(intakePipeline),
     ...createVaultSharingOps(runtime),
+    ...createVaultLinkingOps(runtime),
   ];
 }

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,36 +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
         }
 
-        // Fallback: if brain returned nothing, pull from vault
+        // Fallback to vault if brain empty
         if (recommendations.length === 0) {
           try {
-            const vaultResults = vault.search(objective, { domain, limit: 5 });
+            const vaultResults = vault.search(prompt, { domain, limit: 5 });
             recommendations = vaultResults.map((r) => ({
               pattern: r.entry.title,
               strength: 50,
             }));
           } catch {
-            // Vault search failed — proceed without recommendations
+            // Vault search failed
           }
         }
 
-        // Build decisions from recommendations
+        // 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,
+          },
+        };
       },
     },
 
@@ -96,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'),
       }),
@@ -109,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);
 
-        // Start brain session linked to this plan
+        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,
+          });
+
+          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,
@@ -128,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'),
@@ -150,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,
@@ -163,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
         }
 
-        return { plan, session, extraction };
+        // 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, epilogue: epilogueResult };
       },
     },
 
@@ -180,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'),
@@ -193,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,
@@ -217,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,
         };
       },
     },
@@ -255,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,
@@ -264,7 +465,6 @@ export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
           filesModified,
         });
 
-        // End session immediately with outcome
         const endedSession = brainIntelligence.lifecycle({
           action: 'end',
           sessionId: startedSession.id,
@@ -273,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 };
       },
     },
   ];