@soleri/core 2.9.0 → 2.11.0

package/src/runtime/playbook-ops.ts

@@ -1,12 +1,8 @@
 /**
- * Playbook Operations — 5 ops for playbook management.
+ * Playbook Operations — 8 ops for playbook management and execution.
  *
- * Existing ops (moved from core-ops.ts):
- *   playbook_list, playbook_get, playbook_create
- *
- * New ops:
- *   playbook_match  — match playbooks by intent + text
- *   playbook_seed   — seed built-in playbooks into vault
+ * Management: playbook_list, playbook_get, playbook_create, playbook_match, playbook_seed
+ * Execution:  playbook_start, playbook_step, playbook_complete
  */
 
 import { z } from 'zod';
@@ -17,11 +13,13 @@ import {
   matchPlaybooks,
   seedDefaultPlaybooks,
   entryToPlaybookDefinition,
+  getBuiltinPlaybook,
+  getAllBuiltinPlaybooks,
 } from '../playbooks/index.js';
 import type { PlaybookIntent } from '../playbooks/index.js';
 
 export function createPlaybookOps(runtime: AgentRuntime): OpDefinition[] {
-  const { vault } = runtime;
+  const { vault, playbookExecutor } = runtime;
 
   return [
     // ─── playbook_list ──────────────────────────────────────────────
@@ -155,7 +153,7 @@ export function createPlaybookOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
-    // ─── playbook_seed (NEW) ────────────────────────────────────────
+    // ─── playbook_seed ─────────────────────────────────────────────
     {
       name: 'playbook_seed',
       description:
@@ -165,5 +163,111 @@ export function createPlaybookOps(runtime: AgentRuntime): OpDefinition[] {
         return seedDefaultPlaybooks(vault);
       },
     },
+
+    // ─── playbook_start ──────────────────────────────────────────
+    {
+      name: 'playbook_start',
+      description:
+        'Start a playbook execution session. Returns the first step, tools, and gates. Use playbook_step to advance through steps.',
+      auth: 'write',
+      schema: z.object({
+        playbookId: z
+          .string()
+          .optional()
+          .describe('Built-in or vault playbook ID to start directly.'),
+        intent: z
+          .enum(['BUILD', 'FIX', 'REVIEW', 'PLAN', 'IMPROVE', 'DELIVER'])
+          .optional()
+          .describe('Auto-match a playbook by intent. Ignored if playbookId is provided.'),
+        text: z.string().optional().describe('Context text for auto-matching. Used with intent.'),
+      }),
+      handler: async (params) => {
+        const playbookId = params.playbookId as string | undefined;
+        const intent = params.intent as PlaybookIntent | undefined;
+        const text = (params.text as string | undefined) ?? '';
+
+        if (playbookId) {
+          // Direct start by ID — check built-in first, then vault
+          const builtin = getBuiltinPlaybook(playbookId);
+          if (builtin) {
+            return playbookExecutor.start(builtin);
+          }
+          const entry = vault.get(playbookId);
+          if (entry && entry.type === 'playbook') {
+            const def = entryToPlaybookDefinition(entry);
+            if (def) return playbookExecutor.start(def);
+          }
+          return { error: `Playbook not found: ${playbookId}` };
+        }
+
+        if (intent || text) {
+          // Auto-match
+          const vaultEntries = vault.list({ type: 'playbook', limit: 200 });
+          const vaultPlaybooks = vaultEntries
+            .map((e) => entryToPlaybookDefinition(e))
+            .filter((p): p is NonNullable<typeof p> => p !== null);
+
+          const match = matchPlaybooks(intent, text, vaultPlaybooks);
+          if (!match.playbook) {
+            return {
+              error: 'No matching playbook found',
+              available: getAllBuiltinPlaybooks().map((p) => ({ id: p.id, title: p.title })),
+            };
+          }
+          return playbookExecutor.start(match.playbook);
+        }
+
+        return {
+          error: 'Provide playbookId or intent/text for auto-matching',
+          available: getAllBuiltinPlaybooks().map((p) => ({ id: p.id, title: p.title })),
+        };
+      },
+    },
+
+    // ─── playbook_step ───────────────────────────────────────────
+    {
+      name: 'playbook_step',
+      description:
+        'Advance to the next step in an active playbook session. Marks the current step as done (or skipped) and returns the next step.',
+      auth: 'write',
+      schema: z.object({
+        sessionId: z.string().describe('Active playbook session ID from playbook_start.'),
+        output: z.string().optional().describe('Summary of what was accomplished in this step.'),
+        skip: z.boolean().optional().describe('Skip this step instead of completing it.'),
+      }),
+      handler: async (params) => {
+        return playbookExecutor.step(params.sessionId as string, {
+          output: params.output as string | undefined,
+          skip: params.skip as boolean | undefined,
+        });
+      },
+    },
+
+    // ─── playbook_complete ───────────────────────────────────────
+    {
+      name: 'playbook_complete',
+      description:
+        'Complete (or abort) a playbook session. Validates completion gates and returns a summary with pass/fail status.',
+      auth: 'write',
+      schema: z.object({
+        sessionId: z.string().describe('Active playbook session ID.'),
+        abort: z
+          .boolean()
+          .optional()
+          .describe('Abort instead of completing. Skips remaining steps.'),
+        gateResults: z
+          .record(z.boolean())
+          .optional()
+          .describe(
+            'Gate check results: { "gate-check-type": true/false }. Unmapped gates are treated as failed.',
+          ),
+      }),
+      handler: async (params) => {
+        return playbookExecutor.complete(params.sessionId as string, {
+          abort: params.abort as boolean | undefined,
+          gateResults: params.gateResults as Record<string, boolean> | undefined,
+        });
+      },
+    },
   ];
 }

package/src/runtime/plugin-ops.ts

@@ -0,0 +1,258 @@
+/**
+ * Plugin Operations — 5 ops for runtime plugin management.
+ *
+ * plugin_list, plugin_load, plugin_activate, plugin_deactivate, plugin_status
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+import { loadPlugins, validateDependencies, sortByDependencies } from '../plugins/index.js';
+
+export function createPluginOps(runtime: AgentRuntime, opSink?: OpDefinition[]): OpDefinition[] {
+  const { pluginRegistry, config } = runtime;
+  const injectedByPlugin = new Map<string, OpDefinition[]>();
+
+  const injectPluginOps = (pluginId: string): { injected: number; error?: string } => {
+    if (!opSink) return { injected: 0 };
+    if (injectedByPlugin.has(pluginId)) {
+      return { injected: injectedByPlugin.get(pluginId)?.length ?? 0 };
+    }
+
+    const plugin = pluginRegistry.get(pluginId);
+    if (!plugin) return { injected: 0, error: `Plugin not found: ${pluginId}` };
+
+    const pluginOps = plugin.facades.flatMap((f) => f.ops);
+    const existing = new Set(opSink.map((o) => o.name));
+    const collisions = pluginOps.filter((o) => existing.has(o.name)).map((o) => o.name);
+    if (collisions.length > 0) {
+      return {
+        injected: 0,
+        error: `Plugin op name collision: ${collisions.join(', ')}`,
+      };
+    }
+
+    opSink.push(...pluginOps);
+    injectedByPlugin.set(pluginId, pluginOps);
+    return { injected: pluginOps.length };
+  };
+
+  const removePluginOps = (pluginId: string): number => {
+    const injected = injectedByPlugin.get(pluginId);
+    if (!injected || !opSink) return 0;
+    const names = new Set(injected.map((o) => o.name));
+    for (let i = opSink.length - 1; i >= 0; i--) {
+      if (names.has(opSink[i].name)) {
+        opSink.splice(i, 1);
+      }
+    }
+    injectedByPlugin.delete(pluginId);
+    return names.size;
+  };
+
+  return [
+    // ─── plugin_list ──────────────────────────────────────────────────
+    {
+      name: 'plugin_list',
+      description: 'List all registered plugins with their status, version, and facade count.',
+      auth: 'read',
+      handler: async () => {
+        const plugins = pluginRegistry.list();
+        return {
+          plugins: plugins.map((p) => ({
+            id: p.id,
+            name: p.manifest.name,
+            version: p.manifest.version,
+            domain: p.manifest.domain,
+            status: p.status,
+            provenance: p.provenance,
+            facades: p.facades.length,
+            ops: p.facades.reduce((sum, f) => sum + f.ops.length, 0),
+            error: p.error,
+          })),
+          count: plugins.length,
+          active: plugins.filter((p) => p.status === 'active').length,
+        };
+      },
+    },
+
+    // ─── plugin_load ──────────────────────────────────────────────────
+    {
+      name: 'plugin_load',
+      description:
+        'Scan plugin directories and load all valid plugins. Validates manifests and checks dependencies. Does not activate — call plugin_activate separately.',
+      auth: 'admin',
+      schema: z.object({
+        projectPath: z.string().optional().describe('Project path for project-level plugins.'),
+        extraDirs: z
+          .array(z.string())
+          .optional()
+          .describe('Additional directories to scan for plugins.'),
+      }),
+      handler: async (params) => {
+        const projectPath = (params.projectPath as string | undefined) ?? process.cwd();
+        const extraDirs = (params.extraDirs as string[] | undefined) ?? [];
+
+        const result = loadPlugins(config.agentId, projectPath, extraDirs);
+
+        const loadErrors = result.errors;
+        const dependencyErrors = validateDependencies(result.loaded).map((e) => ({
+          id: e.pluginId,
+          dependency: e.missingDep,
+          error: `Plugin "${e.pluginId}" requires "${e.missingDep}" which is not available`,
+        }));
+
+        // Sort by dependency order and register
+        const registered: string[] = [];
+        const regErrors: Array<{ id: string; error: string }> = [];
+
+        if (dependencyErrors.length === 0) {
+          const sorted = sortByDependencies(result.loaded);
+          for (const plugin of sorted) {
+            try {
+              // Skip already registered
+              if (pluginRegistry.get(plugin.manifest.id)) continue;
+              pluginRegistry.register(plugin);
+              registered.push(plugin.manifest.id);
+            } catch (e) {
+              regErrors.push({
+                id: plugin.manifest.id,
+                error: e instanceof Error ? e.message : String(e),
+              });
+            }
+          }
+        }
+
+        const errors = [
+          ...loadErrors,
+          ...dependencyErrors.map((e) => ({ directory: '', error: e.error })),
+          ...regErrors.map((e) => ({ directory: '', error: e.error })),
+        ];
+
+        return {
+          registered,
+          registeredCount: registered.length,
+          loadErrors,
+          dependencyErrors,
+          registrationErrors: regErrors,
+          errors,
+        };
+      },
+    },
+
+    // ─── plugin_activate ──────────────────────────────────────────────
+    {
+      name: 'plugin_activate',
+      description:
+        'Activate a registered plugin — builds its facades and makes ops available. Optionally activate all registered plugins.',
+      auth: 'admin',
+      schema: z.object({
+        pluginId: z.string().optional().describe('Plugin ID to activate. Omit to activate all.'),
+      }),
+      handler: async (params) => {
+        const pluginId = params.pluginId as string | undefined;
+
+        if (pluginId) {
+          const plugin = pluginRegistry.get(pluginId);
+          if (!plugin) return { error: `Plugin not found: ${pluginId}` };
+
+          const result = await pluginRegistry.activate(pluginId, {
+            runtime,
+            manifest: plugin.manifest,
+            directory: plugin.directory,
+          });
+          const injected = result.status === 'active' ? injectPluginOps(pluginId) : { injected: 0 };
+
+          return {
+            id: result.id,
+            status: result.status,
+            facades: result.facades.length,
+            ops: result.facades.reduce((sum, f) => sum + f.ops.length, 0),
+            injectedOps: injected.injected,
+            injectionError: injected.error,
+            error: result.error,
+          };
+        }
+
+        // Activate all registered plugins
+        const pending = pluginRegistry.list().filter((plugin) => plugin.status !== 'active');
+        const results = await Promise.all(
+          pending.map(async (plugin) => {
+            const activated = await pluginRegistry.activate(plugin.id, {
+              runtime,
+              manifest: plugin.manifest,
+              directory: plugin.directory,
+            });
+            const injected =
+              activated.status === 'active' ? injectPluginOps(plugin.id) : { injected: 0 };
+            return {
+              id: activated.id,
+              status: activated.status,
+              error: activated.error ?? injected.error,
+            };
+          }),
+        );
+
+        return {
+          activated: results.filter((r) => r.status === 'active').length,
+          errors: results.filter((r) => r.status === 'error'),
+          results,
+        };
+      },
+    },
+
+    // ─── plugin_deactivate ────────────────────────────────────────────
+    {
+      name: 'plugin_deactivate',
+      description: 'Deactivate a plugin — removes its facades from the runtime.',
+      auth: 'admin',
+      schema: z.object({
+        pluginId: z.string().describe('Plugin ID to deactivate.'),
+      }),
+      handler: async (params) => {
+        const pluginId = params.pluginId as string;
+        const success = pluginRegistry.deactivate(pluginId);
+        if (!success) return { error: `Plugin not found: ${pluginId}` };
+        const removedOps = removePluginOps(pluginId);
+        return { deactivated: true, id: pluginId, removedOps };
+      },
+    },
+
+    // ─── plugin_status ────────────────────────────────────────────────
+    {
+      name: 'plugin_status',
+      description:
+        'Get detailed status of a specific plugin including manifest, facades, and activation state.',
+      auth: 'read',
+      schema: z.object({
+        pluginId: z.string().describe('Plugin ID to inspect.'),
+      }),
+      handler: async (params) => {
+        const pluginId = params.pluginId as string;
+        const plugin = pluginRegistry.get(pluginId);
+        if (!plugin) return { error: `Plugin not found: ${pluginId}` };
+
+        return {
+          id: plugin.id,
+          name: plugin.manifest.name,
+          version: plugin.manifest.version,
+          description: plugin.manifest.description,
+          domain: plugin.manifest.domain,
+          status: plugin.status,
+          provenance: plugin.provenance,
+          directory: plugin.directory,
+          error: plugin.error,
+          dependencies: plugin.manifest.dependencies,
+          facades: plugin.facades.map((f) => ({
+            name: f.name,
+            description: f.description,
+            ops: f.ops.map((o) => o.name),
+          })),
+          intelligence: plugin.manifest.intelligence.length,
+          registeredAt: plugin.registeredAt,
+          activatedAt: plugin.activatedAt,
+        };
+      },
+    },
+  ];
+}

package/src/runtime/runtime.ts

@@ -9,7 +9,6 @@
 
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { Vault } from '../vault/vault.js';
 import { Brain } from '../brain/brain.js';
 import { BrainIntelligence } from '../brain/intelligence.js';
 import { Planner } from '../planning/planner.js';
@@ -27,8 +26,19 @@ import { IntakePipeline } from '../intake/intake-pipeline.js';
 import { Telemetry } from '../telemetry/telemetry.js';
 import { ProjectRegistry } from '../project/project-registry.js';
 import { TemplateManager } from '../prompts/template-manager.js';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { createLogger } from '../logging/logger.js';
+import { FeatureFlags } from './feature-flags.js';
+import { HealthRegistry } from '../health/health-registry.js';
+import { checkVaultIntegrity } from '../health/vault-integrity.js';
+import { PlaybookExecutor } from '../playbooks/playbook-executor.js';
+import { PluginRegistry } from '../plugins/plugin-registry.js';
+import { PackInstaller } from '../packs/pack-installer.js';
+import { VaultManager } from '../vault/vault-manager.js';
+import { VaultBranching } from '../vault/vault-branching.js';
+import { ContextEngine } from '../context/context-engine.js';
+import { AgencyManager } from '../agency/agency-manager.js';
+import { KnowledgeReview } from '../vault/knowledge-review.js';
 import type { AgentRuntimeConfig, AgentRuntime } from './types.js';
 
 /**
@@ -48,8 +58,21 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   // Logger — structured output to stderr
   const logger = createLogger({ level: config.logLevel, prefix: `[${agentId}]` });
 
-  // Vault — persistent SQLite knowledge store
-  const vault = new Vault(vaultPath);
+  // Vault Manager — multi-tier vault orchestration
+  const vaultManager = new VaultManager({ agentId });
+
+  // Vault — persistent SQLite knowledge store (agent tier)
+  const vault = vaultManager.open('agent', vaultPath);
+
+  // Shared vault — cross-agent intelligence (lower priority than agent vault)
+  try {
+    const sharedVaultDir = join(homedir(), '.soleri');
+    mkdirSync(sharedVaultDir, { recursive: true });
+    const sharedVaultPath = config.sharedVaultPath ?? join(sharedVaultDir, 'vault.db');
+    vaultManager.connect('shared', sharedVaultPath, 0.6);
+  } catch (err) {
+    logger.warn(`Shared vault unavailable: ${err instanceof Error ? err.message : String(err)}`);
+  }
 
   // Seed intelligence data if dataDir provided
   if (config.dataDir) {
@@ -120,6 +143,51 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   // Intake Pipeline — PDF/book ingestion with LLM classification
   const intakePipeline = new IntakePipeline(vault.getProvider(), vault, llmClient);
 
+  // Playbook Executor — in-memory step-by-step workflow sessions
+  const playbookExecutor = new PlaybookExecutor();
+
+  // Plugin Registry — dynamic facade loading
+  const pluginRegistry = new PluginRegistry();
+
+  // Pack Installer — knowledge pack management
+  const packInstaller = new PackInstaller(vault, pluginRegistry);
+
+  // Vault Branching — experiment with knowledge changes before merging
+  const vaultBranching = new VaultBranching(vault);
+
+  // Context Engine — entity extraction, knowledge retrieval, confidence scoring
+  const contextEngine = new ContextEngine(vault, brain, brainIntelligence, cognee);
+
+  // Agency Manager — proactive file watching, pattern surfacing (disabled by default)
+  const agencyManager = new AgencyManager(vault);
+
+  // Knowledge Review — team review workflows (submit/approve/reject)
+  const knowledgeReview = new KnowledgeReview(vault.getProvider());
+
+  // Health Registry — centralized subsystem status tracking
+  const health = new HealthRegistry();
+  health.register('vault', 'healthy');
+  health.register('brain', 'healthy');
+  health.register('cognee', cognee.getStatus()?.available ? 'healthy' : 'degraded');
+  health.register(
+    'llm',
+    llmClient.isAvailable().openai || llmClient.isAvailable().anthropic ? 'healthy' : 'degraded',
+  );
+  health.register('planner', 'healthy');
+
+  // Vault integrity check on startup (non-fatal)
+  try {
+    const integrity = checkVaultIntegrity(vault.getProvider());
+    if (!integrity.schemaValid || !integrity.ftsValid) {
+      health.update('vault', 'degraded', integrity.errors.join('; '));
+      if (integrity.ftsRebuilt) {
+        logger.info('Vault FTS index rebuilt automatically');
+      }
+    }
+  } catch {
+    // Integrity check itself failed — vault may still work
+  }
+
   return {
     config,
     logger,
@@ -140,11 +208,22 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     templateManager,
     syncManager,
     intakePipeline,
+    authPolicy: { mode: 'permissive', callerLevel: 'admin' },
+    flags: new FeatureFlags(join(agentHome, 'flags.json')),
+    health,
+    playbookExecutor,
+    pluginRegistry,
+    packInstaller,
+    vaultManager,
+    vaultBranching,
+    contextEngine,
+    agencyManager,
+    knowledgeReview,
     createdAt: Date.now(),
     close: () => {
       syncManager.close();
       cognee.resetPendingCognify();
-      vault.close();
+      vaultManager.close();
     },
   };
 }

package/src/runtime/telemetry-ops.ts

@@ -0,0 +1,57 @@
+/**
+ * Extended telemetry ops — error aggregation and slow op detection.
+ *
+ * Complements admin_telemetry, admin_telemetry_recent, admin_telemetry_reset
+ * in admin-extra-ops with higher-level analysis.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+export function createTelemetryOps(runtime: AgentRuntime): OpDefinition[] {
+  const { telemetry } = runtime;
+
+  return [
+    {
+      name: 'telemetry_errors',
+      description: 'Get recent errors grouped by op name with error details.',
+      auth: 'read' as const,
+      handler: async () => {
+        const stats = telemetry.getStats();
+        const recent = telemetry.getRecent(200);
+        const errors = recent.filter((c) => !c.success);
+        return {
+          errorCount: errors.length,
+          errorsByOp: stats.errorsByOp,
+          recentErrors: errors.slice(0, 20).map((e) => ({
+            op: e.op,
+            facade: e.facade,
+            error: e.error,
+            timestamp: e.timestamp,
+          })),
+        };
+      },
+    },
+    {
+      name: 'telemetry_slow_ops',
+      description: 'Get the slowest ops by average duration, filtered by threshold.',
+      auth: 'read' as const,
+      schema: z.object({
+        threshold: z
+          .number()
+          .optional()
+          .default(100)
+          .describe('Minimum avg duration in ms to report'),
+      }),
+      handler: async (params) => {
+        const stats = telemetry.getStats();
+        const threshold = (params.threshold as number) ?? 100;
+        return {
+          slowOps: stats.slowestOps.filter((o) => o.avgMs >= threshold),
+          avgDurationMs: stats.avgDurationMs,
+        };
+      },
+    },
+  ];
+}

package/src/runtime/types.ts

@@ -17,6 +17,17 @@ import type { CogneeSyncManager } from '../cognee/sync-manager.js';
 import type { IntakePipeline } from '../intake/intake-pipeline.js';
 import type { Logger } from '../logging/logger.js';
 import type { LogLevel } from '../logging/types.js';
+import type { AuthPolicy } from '../facades/types.js';
+import type { FeatureFlags } from './feature-flags.js';
+import type { HealthRegistry } from '../health/health-registry.js';
+import type { PlaybookExecutor } from '../playbooks/playbook-executor.js';
+import type { PluginRegistry } from '../plugins/plugin-registry.js';
+import type { PackInstaller } from '../packs/pack-installer.js';
+import type { VaultManager } from '../vault/vault-manager.js';
+import type { VaultBranching } from '../vault/vault-branching.js';
+import type { ContextEngine } from '../context/context-engine.js';
+import type { AgencyManager } from '../agency/agency-manager.js';
+import type { KnowledgeReview } from '../vault/knowledge-review.js';
 
 /**
  * Configuration for creating an agent runtime.
@@ -35,6 +46,8 @@ export interface AgentRuntimeConfig {
   templatesDir?: string;
   /** Minimum log level. Default: 'info' (or SOLERI_LOG_LEVEL env var). */
   logLevel?: LogLevel;
+  /** Path to shared global vault. Default: ~/.soleri/vault.db */
+  sharedVaultPath?: string;
 }
 
 /**
@@ -61,6 +74,28 @@ export interface AgentRuntime {
   templateManager: TemplateManager;
   syncManager: CogneeSyncManager;
   intakePipeline: IntakePipeline;
+  /** Mutable auth policy — controls facade dispatch enforcement. */
+  authPolicy: AuthPolicy;
+  /** Feature flags — file-based + env var + runtime toggles. */
+  flags: FeatureFlags;
+  /** Centralized health registry — subsystem status tracking. */
+  health: HealthRegistry;
+  /** Playbook executor — in-memory step-by-step workflow sessions. */
+  playbookExecutor: PlaybookExecutor;
+  /** Plugin registry — dynamic facade loading without re-scaffold. */
+  pluginRegistry: PluginRegistry;
+  /** Pack installer — knowledge pack installation and management. */
+  packInstaller: PackInstaller;
+  /** Vault manager — multi-tier vault orchestration with cascading search. */
+  vaultManager: VaultManager;
+  /** Vault branching — experiment with knowledge changes before merging. */
+  vaultBranching: VaultBranching;
+  /** Context engine — entity extraction, knowledge retrieval, confidence scoring. */
+  contextEngine: ContextEngine;
+  /** Agency manager — proactive file watching, pattern surfacing, warning detection. */
+  agencyManager: AgencyManager;
+  /** Knowledge review — team review workflows (submit/approve/reject). */
+  knowledgeReview: KnowledgeReview;
   /** Timestamp (ms since epoch) when this runtime was created. */
   createdAt: number;
   /** Close the vault database connection. Call on shutdown. */