@soleri/core 2.11.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

@@ -1,22 +1,25 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import type { IntelligenceBundle, IntelligenceEntry } from './types.js';
 
 export function loadIntelligenceData(dataDir: string): IntelligenceEntry[] {
   const entries: IntelligenceEntry[] = [];
   let files: string[];
   try {
-    files = readdirSync(dataDir).filter((f) => f.endsWith('.json'));
+    files = readdirSync(dataDir).filter((f) => f.endsWith('.json') && f !== 'soleri-pack.json');
   } catch {
     console.warn('Intelligence data directory not found: ' + dataDir);
     return entries;
   }
 
+  const packDomain = readPackDomain(dataDir);
+
   for (const file of files) {
     try {
       const raw = readFileSync(join(dataDir, file), 'utf-8');
-      const bundle = JSON.parse(raw) as IntelligenceBundle;
-      if (!bundle.entries || !Array.isArray(bundle.entries)) continue;
+      const parsed: unknown = JSON.parse(raw);
+      const bundle = toBundleEnvelope(parsed, file, dataDir, packDomain);
+      if (!bundle) continue;
       for (const entry of bundle.entries) {
         if (validateEntry(entry)) entries.push(entry);
       }
@@ -27,6 +30,56 @@ export function loadIntelligenceData(dataDir: string): IntelligenceEntry[] {
   return entries;
 }
 
+/** Read `soleri-pack.json` from the data directory to resolve domain names. */
+function readPackDomain(dataDir: string): string | undefined {
+  const packPath = join(dataDir, 'soleri-pack.json');
+  if (!existsSync(packPath)) return undefined;
+  try {
+    const pack: unknown = JSON.parse(readFileSync(packPath, 'utf-8'));
+    if (pack && typeof pack === 'object' && 'domains' in pack) {
+      const domains = (pack as { domains: unknown }).domains;
+      if (Array.isArray(domains) && domains.length > 0 && typeof domains[0] === 'string') {
+        return domains[0];
+      }
+    }
+  } catch {
+    /* ignore malformed pack file */
+  }
+  return undefined;
+}
+
+/** Normalise parsed JSON into an IntelligenceBundle, handling bare arrays. */
+function toBundleEnvelope(
+  parsed: unknown,
+  file: string,
+  dataDir: string,
+  packDomain: string | undefined,
+): IntelligenceBundle | undefined {
+  // Already a bundled envelope
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    const obj = parsed as Record<string, unknown>;
+    if (Array.isArray(obj.entries)) return parsed as IntelligenceBundle;
+    return undefined;
+  }
+
+  // Bare array — wrap in an envelope
+  if (Array.isArray(parsed)) {
+    const domain = packDomain ?? inferDomain(file, dataDir);
+    return { domain, version: '1.0.0', entries: parsed as IntelligenceEntry[] };
+  }
+
+  return undefined;
+}
+
+/** Infer domain from filename, falling back to parent directory name. */
+function inferDomain(file: string, dataDir: string): string {
+  const stem = basename(file, '.json');
+  // Generic filenames like "patterns", "rules", "entries" — use parent dir name instead
+  const generic = new Set(['patterns', 'rules', 'entries', 'data', 'index']);
+  if (generic.has(stem)) return basename(dirname(dataDir + '/')) || stem;
+  return stem;
+}
+
 function validateEntry(entry: IntelligenceEntry): boolean {
   return (
     typeof entry.id === 'string' &&
@@ -40,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',