@soleri/core 2.12.0 → 7.0.0

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/index.ts

@@ -1,6 +1,6 @@
 // ─── Intelligence ────────────────────────────────────────────────────
 export type { IntelligenceEntry, IntelligenceBundle } from './intelligence/types.js';
-export { loadIntelligenceData } from './intelligence/loader.js';
+export { loadIntelligenceData, loadPacks } from './intelligence/loader.js';
 
 // ─── Vault ───────────────────────────────────────────────────────────
 export { Vault } from './vault/vault.js';
@@ -503,6 +503,15 @@ export {
 } from './runtime/deprecation.js';
 export type { DeprecationInfo } from './runtime/deprecation.js';
 
+// ─── Engine (v7 — direct registration, replaces facade factory) ───────
+export { registerEngine } from './engine/register-engine.js';
+export type {
+  EngineRegistrationOptions,
+  EngineRegistrationResult,
+} from './engine/register-engine.js';
+export { captureOps, executeOp } from './engine/test-helpers.js';
+export type { CapturedOp } from './engine/test-helpers.js';
+
 // ─── Migrations ────────────────────────────────────────────────────────
 export { MigrationRunner } from './migrations/index.js';
 export type { Migration, MigrationResult, MigrationState } from './migrations/index.js';
@@ -629,3 +638,61 @@ export type {
 // ─── Prompts ───────────────────────────────────────────────────────────
 export { TemplateManager, parseVariables, resolveIncludes } from './prompts/index.js';
 export type { PromptTemplate, TemplateVariable, RenderOptions } from './prompts/index.js';
+
+// ─── Domain Packs ──────────────────────────────────────────────────────
+export {
+  validateDomainPack,
+  SEMANTIC_FACADE_NAMES,
+  loadDomainPack,
+  loadDomainPacksFromConfig,
+  resolveDependencies,
+} from './domain-packs/index.js';
+export type {
+  DomainPack,
+  DomainPackManifest,
+  DomainPackRef,
+  KnowledgeManifest,
+  PackSkillDefinition,
+  ValidateResult as DomainPackValidateResult,
+  PackRuntime,
+  PackProjectContext,
+  PackCheckContext,
+} from './domain-packs/index.js';
+export {
+  createPackRuntime,
+  resolveToken,
+  listProjectTokens,
+  buildReverseIndex,
+} from './domain-packs/index.js';
+
+// ─── Capabilities ───────────────────────────────────────────────────────
+export * from './capabilities/index.js';
+
+// ─── Flow Engine ───────────────────────────────────────────────────────
+export type {
+  Flow,
+  FlowStep,
+  ProbeName,
+  ProbeResults,
+  PlanStep,
+  SkippedStep,
+  OrchestrationPlan,
+  OrchestrationContext,
+  StepResult as FlowStepResult,
+  ExecutionResult,
+  GateVerdict,
+} from './flows/index.js';
+export {
+  loadFlowById,
+  loadAllFlows,
+  runProbes,
+  INTENT_TO_FLOW,
+  chainToToolName,
+  buildPlan,
+  pruneSteps,
+  evaluateGate,
+  evaluateCondition,
+  FlowExecutor,
+  createDispatcher,
+  runEpilogue,
+} from './flows/index.js';

package/src/intelligence/loader.ts

@@ -93,3 +93,41 @@ function validateEntry(entry: IntelligenceEntry): boolean {
     Array.isArray(entry.tags)
   );
 }
+
+/**
+ * Load all knowledge packs from a packs directory.
+ * Each subdirectory is a pack with JSON bundle files and an optional soleri-pack.json manifest.
+ *
+ * Structure:
+ *   packsDir/
+ *     design-system/
+ *       soleri-pack.json        ← optional manifest
+ *       design-tokens.json      ← IntelligenceBundle
+ *       components.json         ← IntelligenceBundle
+ *     clean-code/
+ *       refactoring.json        ← IntelligenceBundle
+ *
+ * Returns entries grouped by pack name for installPack() calls.
+ */
+export function loadPacks(
+  packsDir: string,
+): Array<{ packName: string; entries: IntelligenceEntry[] }> {
+  const result: Array<{ packName: string; entries: IntelligenceEntry[] }> = [];
+  let dirs: string[];
+  try {
+    dirs = readdirSync(packsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+      .map((d) => d.name);
+  } catch {
+    return result;
+  }
+
+  for (const dir of dirs) {
+    const packPath = join(packsDir, dir);
+    const entries = loadIntelligenceData(packPath);
+    if (entries.length > 0) {
+      result.push({ packName: dir, entries });
+    }
+  }
+  return result;
+}

package/src/intelligence/types.ts

@@ -12,6 +12,7 @@ export interface IntelligenceEntry {
   tags: string[];
   appliesTo?: string[];
   tier?: 'agent' | 'project' | 'team'; // scope tier — auto-detected or manually set
+  origin?: 'agent' | 'pack' | 'user'; // knowledge origin — 'agent' = engine, 'pack' = installable knowledge pack, 'user' = personal capture
   validFrom?: number; // unix epoch — when entry becomes active
   validUntil?: number; // unix epoch — when entry expires (null = never)
 }

package/src/packs/types.ts

@@ -34,6 +34,25 @@ export const packManifestSchema = z.object({
   engine: z.string().optional(),
   /** Pack dependencies (other pack IDs) */
   dependencies: z.array(z.string()).optional().default([]),
+  /** Capability declarations — what this pack can do and what it needs */
+  capabilities: z
+    .array(
+      z.object({
+        id: z
+          .string()
+          .regex(
+            /^[a-z][a-z0-9]*\.[a-z][a-z0-9]*$/,
+            'Capability ID must be domain.action format (e.g., color.validate)',
+          ),
+        description: z.string().min(1),
+        provides: z.array(z.string()),
+        requires: z.array(z.string()),
+        depends: z.array(z.string()).optional().default([]),
+        knowledge: z.array(z.string()).optional().default([]),
+      }),
+    )
+    .optional()
+    .default([]),
   /** Facade definitions (same as plugin manifest) */
   facades: z
     .array(

package/src/playbooks/generic/onboarding.ts

@@ -0,0 +1,79 @@
+/**
+ * Generic Playbook: New User Onboarding
+ *
+ * Guides first-time users through the agent's capabilities.
+ * Activates when vault is empty or user asks "what can you do?"
+ */
+
+import type { PlaybookDefinition } from '../playbook-types.js';
+
+export const onboardingPlaybook: PlaybookDefinition = {
+  id: 'generic-onboarding',
+  tier: 'generic',
+  title: 'New User Onboarding',
+  trigger:
+    'Use when the user is new (vault is empty, no session history) or when they ask "what can you do?", "how do I use you?", "help", "getting started", "what is this?", "features", "capabilities".',
+  description:
+    "Walks a new user through the agent's capabilities in a friendly, progressive way. Shows what's available, demonstrates the 5-step rhythm with a quick example, and suggests next actions based on the user's goals.",
+  steps: `1. INTRODUCE — Explain who you are
+   - Your name, role, and current domains (from activation context)
+   - What makes you different: you learn, remember, and improve
+   - Your installed packs and what they enable
+
+2. SHOW CAPABILITIES — Walk through what you can do
+   - Vault: "I search my knowledge base before every decision"
+   - Planning: "I create structured plans with approval gates"
+   - Brain: "I learn from past sessions and recommend patterns"
+   - Memory: "I remember across conversations and projects"
+   - Domains: list each domain and what it covers
+   - If packs are missing: "You can add more capabilities with soleri pack install"
+
+3. DEMONSTRATE — Quick live example
+   - Run a vault search on something relevant to the user's project
+   - Show the result: "This is what I already know about your domain"
+   - If vault is empty: "Let's capture our first pattern together"
+
+4. ORIENT — Help the user find their starting point
+   - Ask: "What are you working on?" or "What problem are you trying to solve?"
+   - Based on their answer, suggest the right workflow:
+     - Building something new → "Let me create a plan"
+     - Fixing a bug → "Let me search for known patterns"
+     - Learning the codebase → "Let me explore and capture what I find"
+     - Setting up → "Let me run a health check: op:admin_health"
+
+5. HANDOFF — Set expectations
+   - "From now on, just describe what you need — I'll figure out the workflow"
+   - "If you want me to remember something, say 'capture this' or 'remember'"
+   - "Say 'what do you know about X?' to search my vault anytime"`,
+  expectedOutcome:
+    'User understands what the agent can do, has seen a live demonstration, and has a clear first task to work on. The agent transitions from onboarding to productive work.',
+  category: 'methodology',
+  tags: ['onboarding', 'getting-started', 'help', 'capabilities', 'generic'],
+  matchIntents: ['PLAN'],
+  matchKeywords: [
+    'what can you do',
+    'help',
+    'getting started',
+    'how do I use',
+    'features',
+    'capabilities',
+    'onboarding',
+    'introduce',
+    'what is this',
+    'new here',
+    'first time',
+  ],
+  gates: [],
+  taskTemplates: [],
+  toolInjections: [
+    'op:activate — show current capabilities and system status',
+    'op:admin_health — demonstrate health check',
+    'op:search_intelligent — live demo of vault search',
+    'op:brain_recommend — show brain recommendations',
+  ],
+  verificationCriteria: [
+    'User received a clear overview of agent capabilities',
+    'User saw a live demonstration of at least one capability',
+    'User expressed a first task or area of interest',
+  ],
+};

package/src/playbooks/playbook-registry.ts

@@ -23,6 +23,7 @@ import { codeReviewPlaybook } from './generic/code-review.js';
 import { subagentExecutionPlaybook } from './generic/subagent-execution.js';
 import { systematicDebuggingPlaybook } from './generic/systematic-debugging.js';
 import { verificationPlaybook } from './generic/verification.js';
+import { onboardingPlaybook } from './generic/onboarding.js';
 
 // =============================================================================
 // SCORING WEIGHTS
@@ -49,6 +50,7 @@ const BUILTIN_PLAYBOOKS: PlaybookDefinition[] = [
   subagentExecutionPlaybook,
   systematicDebuggingPlaybook,
   verificationPlaybook,
+  onboardingPlaybook,
 ];
 
 /**

package/src/runtime/admin-extra-ops.ts

@@ -240,7 +240,7 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
       description: 'Status of all runtime modules — check each is initialized.',
       auth: 'read',
       handler: async () => {
-        const cogneeStatus = cognee.getStatus();
+        const cogneeStatus = cognee?.getStatus() ?? null;
         const llmAvailable = runtime.llmClient.isAvailable();
         const loopStatus = runtime.loop.getStatus();
 
@@ -292,11 +292,13 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
           // Brain rebuild failed — graceful degradation
         }
 
-        try {
-          cognee.resetPendingCognify();
-          cleared.push('cognee');
-        } catch {
-          // Cognee reset failed — graceful degradation
+        if (cognee) {
+          try {
+            cognee.resetPendingCognify();
+            cleared.push('cognee');
+          } catch {
+            // Cognee reset failed — graceful degradation
+          }
         }
 
         try {
@@ -798,10 +800,14 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
         }
 
         // Cognee
-        const cogneeStatus = cognee.getStatus();
+        const cogneeStatus = cognee?.getStatus() ?? null;
         checks.cognee = {
           ok: cogneeStatus?.available ?? false,
-          detail: cogneeStatus?.available ? 'Connected' : 'Not available (optional)',
+          detail: cognee
+            ? cogneeStatus?.available
+              ? 'Connected'
+              : 'Not available (optional)'
+            : 'Disabled',
         };
 
         // LLM keys

package/src/runtime/admin-ops.ts

@@ -51,7 +51,7 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
       auth: 'read',
       handler: async () => {
         const vaultStats = vault.stats();
-        const cogneeStatus = cognee.getStatus();
+        const cogneeStatus = cognee?.getStatus() ?? null;
         const llmAvailable = llmClient.isAvailable();
         const brainStats = brain.getStats();
         const curatorStatus = curator.getStatus();
@@ -183,10 +183,10 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
 
         // Reset cognee health cache by checking health again (no direct reset method)
         // The next isAvailable check will need a fresh health probe
-        const cogneeHealth = await cognee.healthCheck().catch(() => null);
+        const cogneeHealth = cognee ? await cognee.healthCheck().catch(() => null) : null;
 
         return {
-          cleared: ['brain_vocabulary', 'cognee_health_cache'],
+          cleared: ['brain_vocabulary', ...(cognee ? ['cognee_health_cache'] : [])],
           brainVocabularySize: brain.getStats().vocabularySize,
           cogneeAvailable: cogneeHealth?.available ?? false,
         };
@@ -252,7 +252,7 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
 
         // 4. Cognee availability
         try {
-          const cogneeStatus = cognee.getStatus();
+          const cogneeStatus = cognee?.getStatus() ?? null;
           if (cogneeStatus?.available) {
             checks.push({
               name: 'cognee',

package/src/runtime/capture-ops.ts

@@ -136,6 +136,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
                     counterExample: entry.counterExample,
                     why: entry.why,
                     tier: finalTier,
+                    origin: 'user',
                   });
                   const scopeMeta = scopeResult
                     ? {
@@ -227,7 +228,44 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
           }
         }
 
-        return { captured, proposed, rejected, duplicated, results };
+        // Auto-suggest links for captured entries (Zettelkasten enrichment)
+        let suggestedLinks: Array<{
+          entryId: string;
+          title: string;
+          suggestedType: string;
+          score: number;
+        }> = [];
+        try {
+          if (captured > 0) {
+            const firstCaptured = results.find((r) => r.action === 'capture');
+            if (firstCaptured) {
+              const { LinkManager } = await import('../vault/linking.js');
+              const lm = new LinkManager(vault.getProvider());
+              const suggestions = lm.suggestLinks(firstCaptured.id, 3);
+              suggestedLinks = suggestions
+                .filter(
+                  (s) => s.entryId !== firstCaptured.id && !s.entryId.endsWith(firstCaptured.id),
+                )
+                .map((s) => ({
+                  entryId: s.entryId,
+                  title: s.title,
+                  suggestedType: s.suggestedType,
+                  score: s.score,
+                }));
+            }
+          }
+        } catch {
+          /* never break capture for suggestions */
+        }
+
+        return {
+          captured,
+          proposed,
+          rejected,
+          duplicated,
+          results,
+          ...(suggestedLinks.length > 0 ? { suggestedLinks } : {}),
+        };
       },
     },
 
@@ -307,6 +345,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
                   description,
                   tags,
                   tier: finalTier,
+                  origin: 'user',
                 });
                 if (captureResult.blocked) {
                   return {