@soleri/core 7.0.0 → 8.1.0

package/src/engine/bin/soleri-engine.ts

@@ -75,6 +75,7 @@ async function main(): Promise<void> {
   const runtime = createAgentRuntime({
     agentId,
     vaultPath,
+    agentDir,
     cognee: (engineConfig.cognee as boolean) ?? false,
   });
 
@@ -116,6 +117,14 @@ async function main(): Promise<void> {
   // 6. Seed default playbooks
   seedDefaultPlaybooks(runtime.vault);
 
+  // Log vault stats for first-run visibility
+  const vaultStats = runtime.vault.stats();
+  console.error(
+    `${tag} Vault: ${vaultStats.totalEntries} entries (${Object.entries(vaultStats.byType ?? {})
+      .map(([t, n]) => `${n} ${t}`)
+      .join(', ')})`,
+  );
+
   // 7. Load domain packs
   const packs = (config.packs ?? []) as Array<{ name: string; package: string; version?: string }>;
   const loadedPacks: Array<{ name: string; facades?: Array<{ name: string; ops: unknown[] }> }> =
@@ -128,9 +137,12 @@ async function main(): Promise<void> {
       const manifests = await loadDomainPacksFromConfig(refs);
 
       // Packs activate sequentially — order may matter for dependencies
+      const { createPackRuntime } = await import('../../domain-packs/pack-runtime.js');
+      const narrowedRuntime = createPackRuntime(runtime);
+
       for (const manifest of manifests) {
         if (manifest.onActivate) {
-          await manifest.onActivate(runtime); // eslint-disable-line no-await-in-loop
+          await manifest.onActivate(narrowedRuntime, runtime); // eslint-disable-line no-await-in-loop
         }
         loadedPacks.push(manifest);
         console.error(`${tag} Domain pack: ${manifest.name}`);
@@ -177,7 +189,7 @@ async function main(): Promise<void> {
   }));
 
   // 12. Register all engine tools
-  const { tools, totalOps } = registerEngine(server, runtime, {
+  const { tools, totalOps, registerTool } = registerEngine(server, runtime, {
     agentId,
     coreOps,
     domains: identity.domains,
@@ -194,6 +206,10 @@ async function main(): Promise<void> {
 
   console.error(`${tag} Registered ${tools.length} tools (${totalOps} ops)`);
 
+  // Enable hot reload for post-boot pack/plugin installation
+  const { setHotRegister } = await import('../../runtime/pack-ops.js');
+  setHotRegister(registerTool);
+
   // 13. Connect stdio transport
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/engine/index.ts

@@ -17,3 +17,5 @@ export { registerEngine } from './register-engine.js';
 export type { EngineRegistrationOptions, EngineRegistrationResult } from './register-engine.js';
 export { createCoreOps } from './core-ops.js';
 export type { AgentIdentityConfig } from './core-ops.js';
+export { ENGINE_MODULE_MANIFEST, CORE_KEY_OPS } from './module-manifest.js';
+export type { ModuleManifestEntry } from './module-manifest.js';

package/src/engine/module-manifest.ts

@@ -0,0 +1,99 @@
+/**
+ * Soleri Engine Module Manifest
+ *
+ * Single source of truth for engine module names, descriptions, and key ops.
+ * Used by register-engine.ts at runtime and by @soleri/forge for template generation.
+ *
+ * This file is intentionally dependency-free so it can be imported by any package.
+ */
+
+export interface ModuleManifestEntry {
+  /** Suffix for tool name: {agentId}_{suffix} */
+  suffix: string;
+  /** Human-readable description */
+  description: string;
+  /** Representative ops shown in placeholder tables (max 4) */
+  keyOps: string[];
+  /** If true, module requires a runtime condition to register */
+  conditional?: boolean;
+}
+
+/**
+ * Canonical list of engine modules.
+ * Order here determines order in generated tool tables.
+ */
+export const ENGINE_MODULE_MANIFEST: ModuleManifestEntry[] = [
+  {
+    suffix: 'vault',
+    description: 'Knowledge management — search, CRUD, import/export, intake, archival.',
+    keyOps: ['search_intelligent', 'capture_knowledge', 'capture_quick'],
+  },
+  {
+    suffix: 'plan',
+    description: 'Plan lifecycle — create, approve, execute, reconcile, complete, grading.',
+    keyOps: ['create_plan', 'approve_plan', 'plan_split', 'plan_reconcile'],
+  },
+  {
+    suffix: 'brain',
+    description: 'Learning system — intelligence pipeline, strengths, feedback, sessions.',
+    keyOps: ['recommend', 'strengths', 'feedback'],
+  },
+  {
+    suffix: 'memory',
+    description: 'Session & cross-project memory — capture, search, dedup, promote.',
+    keyOps: ['memory_search', 'memory_capture', 'session_capture'],
+  },
+  {
+    suffix: 'admin',
+    description: 'Infrastructure — health, config, telemetry, tokens, LLM, prompts.',
+    keyOps: ['admin_health', 'admin_tool_list', 'admin_diagnostic'],
+  },
+  {
+    suffix: 'curator',
+    description: 'Quality — duplicate detection, contradictions, grooming, health audit.',
+    keyOps: ['curator_groom', 'curator_status', 'curator_health'],
+  },
+  {
+    suffix: 'loop',
+    description: 'Iterative validation loops — start, iterate, cancel, complete, history.',
+    keyOps: ['loop_start', 'loop_status', 'loop_cancel'],
+  },
+  {
+    suffix: 'orchestrate',
+    description:
+      'Execution orchestration — project registration, playbooks, plan/execute/complete.',
+    keyOps: ['orchestrate_plan', 'orchestrate_execute', 'orchestrate_complete'],
+  },
+  {
+    suffix: 'control',
+    description: 'Agent behavior — identity, intent routing, morphing, guidelines, governance.',
+    keyOps: ['route_intent', 'morph', 'get_behavior_rules'],
+  },
+  {
+    suffix: 'context',
+    description: 'Context analysis — entity extraction, knowledge retrieval, confidence scoring.',
+    keyOps: ['context_extract_entities', 'context_retrieve_knowledge', 'context_analyze'],
+  },
+  {
+    suffix: 'agency',
+    description: 'Proactive intelligence — file watching, pattern surfacing, warnings.',
+    keyOps: ['agency_scan_file', 'agency_surface_patterns', 'agency_warnings'],
+  },
+  {
+    suffix: 'chat',
+    description: 'Chat transport — session management, response chunking, authentication.',
+    keyOps: ['chat_send', 'chat_history', 'chat_session'],
+  },
+  {
+    suffix: 'cognee',
+    description: 'Knowledge graph — Cognee search, sync, export, graph stats.',
+    keyOps: ['cognee_search', 'cognee_add', 'cognee_cognify'],
+    conditional: true,
+  },
+];
+
+/** Core facade ops (always present, not in ENGINE_MODULES) */
+export const CORE_KEY_OPS = ['health', 'identity', 'register', 'activate'];
+
+/** Engine major version — used for compatibility checks against domain packs. */
+export const ENGINE_MAJOR_VERSION = 8;

package/src/engine/register-engine.ts

@@ -60,6 +60,12 @@ export interface EngineRegistrationResult {
   tools: string[];
   /** Total op count across all tools */
   totalOps: number;
+  /**
+   * Register a new MCP tool at runtime (hot reload).
+   * Call this after installing a pack or activating a plugin post-boot.
+   * Automatically notifies connected clients via sendToolListChanged().
+   */
+  registerTool: (toolName: string, description: string, ops: OpDefinition[]) => void;
 }
 
 // ─── Module Definition ────────────────────────────────────────────────
@@ -75,7 +81,8 @@ interface ModuleDef {
   condition?: (runtime: AgentRuntime) => boolean;
 }
 
-const ENGINE_MODULES: ModuleDef[] = [
+/** @internal Exported for drift testing — do not use outside engine */
+export const ENGINE_MODULES: ModuleDef[] = [
   {
     suffix: 'vault',
     description: 'Knowledge management — search, CRUD, import/export, intake, archival.',
@@ -233,7 +240,19 @@ export function registerEngine(
     }
   }
 
-  return { tools: registeredTools, totalOps };
+  const registerTool = (toolName: string, description: string, ops: OpDefinition[]) => {
+    registerModuleTool(server, toolName, description, ops, authPolicy);
+    registeredTools.push(toolName);
+    totalOps += ops.length;
+    // Notify connected clients that tool list changed
+    try {
+      (server as unknown as { sendToolListChanged?: () => void }).sendToolListChanged?.();
+    } catch {
+      // Server may not support notifications yet — safe to ignore
+    }
+  };
+
+  return { tools: registeredTools, totalOps, registerTool };
 }
 
 // ─── Tool Registration (No Factory) ──────────────────────────────────

package/src/events/event-bus.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed Event Bus — generic event emitter for decoupled subsystem communication.
+ *
+ * Wraps Node EventEmitter with type-safe emit/subscribe.
+ * Any module can define its own event map and create a bus.
+ */
+
+import { EventEmitter } from 'node:events';
+
+/**
+ * Create a typed event bus.
+ *
+ * Usage:
+ * ```ts
+ * type MyEvents = {
+ *   'entry:created': { id: string; title: string };
+ *   'entry:deleted': { id: string };
+ * };
+ * const bus = new TypedEventBus<MyEvents>();
+ * bus.on('entry:created', (payload) => console.log(payload.title));
+ * bus.emit('entry:created', { id: '1', title: 'Hello' });
+ * ```
+ */
+export class TypedEventBus<TEvents extends Record<string, unknown>> {
+  private emitter = new EventEmitter();
+
+  on<E extends keyof TEvents & string>(event: E, listener: (payload: TEvents[E]) => void): this {
+    this.emitter.on(event, listener as (...args: unknown[]) => void);
+    return this;
+  }
+
+  once<E extends keyof TEvents & string>(event: E, listener: (payload: TEvents[E]) => void): this {
+    this.emitter.once(event, listener as (...args: unknown[]) => void);
+    return this;
+  }
+
+  off<E extends keyof TEvents & string>(event: E, listener: (payload: TEvents[E]) => void): this {
+    this.emitter.off(event, listener as (...args: unknown[]) => void);
+    return this;
+  }
+
+  emit<E extends keyof TEvents & string>(event: E, payload: TEvents[E]): boolean {
+    return this.emitter.emit(event, payload);
+  }
+
+  listenerCount(): number {
+    let total = 0;
+    for (const name of this.emitter.eventNames()) {
+      total += this.emitter.listenerCount(name);
+    }
+    return total;
+  }
+
+  removeAllListeners(): this {
+    this.emitter.removeAllListeners();
+    return this;
+  }
+}

package/src/flows/chain-runner.ts

@@ -0,0 +1,369 @@
+/**
+ * Chain Runner — executes multi-step workflows with data flow between steps.
+ *
+ * Steps call facade ops via a dispatch function. Each step's output is stored
+ * in a context object and can be referenced by subsequent steps via $variable syntax.
+ *
+ * Gates pause execution. Resume via approve(). State persists to SQLite.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { ChainDef, ChainInstance, StepOutput } from './chain-types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type DispatchFn = (op: string, params: Record<string, unknown>) => Promise<unknown>;
+
+type GateCheckFn = (
+  gate: string,
+  stepId: string,
+  stepResult: unknown,
+) => Promise<{ passed: boolean; message?: string }>;
+
+// ─── Class ───────────────────────────────────────────────────────────
+
+export class ChainRunner {
+  private provider: PersistenceProvider;
+
+  constructor(provider: PersistenceProvider) {
+    this.provider = provider;
+    this.initializeTable();
+  }
+
+  private initializeTable(): void {
+    this.provider.execSql(`
+      CREATE TABLE IF NOT EXISTS chain_instances (
+        id TEXT PRIMARY KEY,
+        chain_id TEXT NOT NULL,
+        chain_name TEXT NOT NULL DEFAULT '',
+        status TEXT NOT NULL DEFAULT 'running',
+        current_step TEXT,
+        paused_at_gate TEXT,
+        input TEXT NOT NULL DEFAULT '{}',
+        context TEXT NOT NULL DEFAULT '{}',
+        step_outputs TEXT NOT NULL DEFAULT '[]',
+        steps_completed INTEGER NOT NULL DEFAULT 0,
+        total_steps INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `);
+  }
+
+  /**
+   * Execute a chain from the beginning (or a specific step).
+   */
+  async execute(
+    chainDef: ChainDef,
+    input: Record<string, unknown>,
+    dispatch: DispatchFn,
+    gateCheck?: GateCheckFn,
+    startFromStep?: string,
+  ): Promise<ChainInstance> {
+    const instanceId = randomUUID().slice(0, 12);
+    const instance: ChainInstance = {
+      id: instanceId,
+      chainId: chainDef.id,
+      chainName: chainDef.name ?? chainDef.id,
+      status: 'running',
+      currentStep: null,
+      pausedAtGate: null,
+      input,
+      context: { input },
+      stepOutputs: [],
+      stepsCompleted: 0,
+      totalSteps: chainDef.steps.length,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    this.persist(instance);
+
+    // Find start index
+    let startIdx = 0;
+    if (startFromStep) {
+      const idx = chainDef.steps.findIndex((s) => s.id === startFromStep);
+      if (idx >= 0) startIdx = idx;
+    }
+
+    return this.runSteps(chainDef, instance, dispatch, gateCheck, startIdx);
+  }
+
+  /**
+   * Resume a paused chain from where it left off.
+   */
+  async resume(
+    instanceId: string,
+    chainDef: ChainDef,
+    dispatch: DispatchFn,
+    gateCheck?: GateCheckFn,
+  ): Promise<ChainInstance> {
+    const instance = this.getInstance(instanceId);
+    if (!instance) throw new Error(`Chain instance not found: ${instanceId}`);
+    if (instance.status !== 'paused') throw new Error(`Chain is ${instance.status}, not paused`);
+
+    // Find the step after the paused gate
+    const pausedStep = instance.pausedAtGate;
+    if (!pausedStep) throw new Error('No paused gate to resume from');
+
+    const stepIdx = chainDef.steps.findIndex((s) => s.id === pausedStep);
+    if (stepIdx < 0) throw new Error(`Paused step ${pausedStep} not found in chain def`);
+
+    // Mark step as approved, move to next
+    instance.status = 'running';
+    instance.pausedAtGate = null;
+    this.persist(instance);
+
+    return this.runSteps(chainDef, instance, dispatch, gateCheck, stepIdx + 1);
+  }
+
+  /**
+   * Approve a gate-paused step and resume the chain.
+   */
+  async approve(
+    instanceId: string,
+    chainDef: ChainDef,
+    dispatch: DispatchFn,
+    gateCheck?: GateCheckFn,
+  ): Promise<ChainInstance> {
+    return this.resume(instanceId, chainDef, dispatch, gateCheck);
+  }
+
+  /**
+   * Get chain instance status.
+   */
+  getInstance(instanceId: string): ChainInstance | null {
+    const row = this.provider.get<InstanceRow>('SELECT * FROM chain_instances WHERE id = ?', [
+      instanceId,
+    ]);
+    return row ? rowToInstance(row) : null;
+  }
+
+  /**
+   * List all chain instances.
+   */
+  list(limit: number = 20): ChainInstance[] {
+    const rows = this.provider.all<InstanceRow>(
+      'SELECT * FROM chain_instances ORDER BY updated_at DESC LIMIT ?',
+      [limit],
+    );
+    return rows.map(rowToInstance);
+  }
+
+  // ─── Core Execution Loop ──────────────────────────────────────────
+
+  private async runSteps(
+    chainDef: ChainDef,
+    instance: ChainInstance,
+    dispatch: DispatchFn,
+    gateCheck: GateCheckFn | undefined,
+    startIdx: number,
+  ): Promise<ChainInstance> {
+    // Steps MUST run sequentially — step N output feeds step N+1 input.
+    // Using recursive approach to satisfy no-await-in-loop lint rule.
+    return this.runStep(chainDef, instance, dispatch, gateCheck, startIdx);
+  }
+
+  private async runStep(
+    chainDef: ChainDef,
+    instance: ChainInstance,
+    dispatch: DispatchFn,
+    gateCheck: GateCheckFn | undefined,
+    idx: number,
+  ): Promise<ChainInstance> {
+    if (idx >= chainDef.steps.length) {
+      instance.status = 'completed';
+      instance.currentStep = null;
+      this.persist(instance);
+      return instance;
+    }
+
+    const step = chainDef.steps[idx];
+    instance.currentStep = step.id;
+    this.persist(instance);
+
+    const resolvedParams = resolveParams(step.params ?? {}, instance.context);
+
+    const stepStart = Date.now();
+    let result: unknown;
+    let stepStatus: StepOutput['status'] = 'completed';
+
+    try {
+      result = await dispatch(step.op, resolvedParams);
+    } catch (err) {
+      result = { error: (err as Error).message };
+      stepStatus = 'failed';
+    }
+
+    const output: StepOutput = {
+      stepId: step.id,
+      op: step.op,
+      result,
+      status: stepStatus,
+      durationMs: Date.now() - stepStart,
+    };
+
+    instance.stepOutputs.push(output);
+    instance.context[step.id] = result;
+    if (step.output) instance.context[step.output] = result;
+    if (stepStatus === 'completed') instance.stepsCompleted++;
+
+    // Check gate
+    if (step.gate && step.gate !== 'none' && stepStatus === 'completed') {
+      const gateResult = await this.evaluateChainGate(step.gate, step.id, result, gateCheck);
+      if (!gateResult.passed) {
+        if (step.gate === 'user-approval') {
+          instance.status = 'paused';
+          instance.pausedAtGate = step.id;
+          this.persist(instance);
+          return instance;
+        }
+        instance.status = 'failed';
+        this.persist(instance);
+        return instance;
+      }
+    }
+
+    if (stepStatus === 'failed') {
+      instance.status = 'failed';
+      this.persist(instance);
+      return instance;
+    }
+
+    this.persist(instance);
+    return this.runStep(chainDef, instance, dispatch, gateCheck, idx + 1);
+  }
+
+  private async evaluateChainGate(
+    gate: string,
+    stepId: string,
+    stepResult: unknown,
+    gateCheck?: GateCheckFn,
+  ): Promise<{ passed: boolean; message?: string }> {
+    switch (gate) {
+      case 'user-approval':
+        return { passed: false, message: 'Awaiting user approval' };
+
+      case 'auto-test': {
+        const result = stepResult as Record<string, unknown> | null;
+        if (!result) return { passed: false, message: 'Step returned no result' };
+        if (result.error) return { passed: false, message: `Step error: ${result.error}` };
+        return { passed: true };
+      }
+
+      case 'vault-check': {
+        if (gateCheck) return gateCheck(gate, stepId, stepResult);
+        return { passed: true };
+      }
+
+      default:
+        return { passed: true };
+    }
+  }
+
+  // ─── Persistence ──────────────────────────────────────────────────
+
+  private persist(instance: ChainInstance): void {
+    instance.updatedAt = new Date().toISOString();
+    this.provider.run(
+      `INSERT OR REPLACE INTO chain_instances
+       (id, chain_id, chain_name, status, current_step, paused_at_gate, input, context, step_outputs, steps_completed, total_steps, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        instance.id,
+        instance.chainId,
+        instance.chainName,
+        instance.status,
+        instance.currentStep,
+        instance.pausedAtGate,
+        JSON.stringify(instance.input),
+        JSON.stringify(instance.context),
+        JSON.stringify(instance.stepOutputs),
+        instance.stepsCompleted,
+        instance.totalSteps,
+        instance.createdAt,
+        instance.updatedAt,
+      ],
+    );
+  }
+}
+
+// ─── Variable Resolution ─────────────────────────────────────────────
+
+/**
+ * Resolve $variable references in params.
+ * $input.url → context.input.url
+ * $research.title → context.research.title
+ * $stepId → context.stepId (whole object)
+ */
+function resolveParams(
+  params: Record<string, unknown>,
+  context: Record<string, unknown>,
+): Record<string, unknown> {
+  const resolved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(params)) {
+    resolved[key] = resolveValue(value, context);
+  }
+  return resolved;
+}
+
+function resolveValue(value: unknown, context: Record<string, unknown>): unknown {
+  if (typeof value === 'string' && value.startsWith('$')) {
+    return resolveReference(value.slice(1), context);
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => resolveValue(v, context));
+  }
+  if (value !== null && typeof value === 'object') {
+    return resolveParams(value as Record<string, unknown>, context);
+  }
+  return value;
+}
+
+function resolveReference(path: string, context: Record<string, unknown>): unknown {
+  const parts = path.split('.');
+  let current: unknown = context;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+// ─── Row Types ───────────────────────────────────────────────────────
+
+interface InstanceRow {
+  id: string;
+  chain_id: string;
+  chain_name: string;
+  status: string;
+  current_step: string | null;
+  paused_at_gate: string | null;
+  input: string;
+  context: string;
+  step_outputs: string;
+  steps_completed: number;
+  total_steps: number;
+  created_at: string;
+  updated_at: string;
+}
+
+function rowToInstance(row: InstanceRow): ChainInstance {
+  return {
+    id: row.id,
+    chainId: row.chain_id,
+    chainName: row.chain_name,
+    status: row.status as ChainInstance['status'],
+    currentStep: row.current_step,
+    pausedAtGate: row.paused_at_gate,
+    input: JSON.parse(row.input) as Record<string, unknown>,
+    context: JSON.parse(row.context) as Record<string, unknown>,
+    stepOutputs: JSON.parse(row.step_outputs) as StepOutput[],
+    stepsCompleted: row.steps_completed,
+    totalSteps: row.total_steps,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}

package/src/flows/chain-types.ts

@@ -0,0 +1,57 @@
+/**
+ * Chain types — composable multi-step workflows with data flow.
+ */
+
+import { z } from 'zod';
+
+// ─── Chain Definition (YAML schema) ──────────────────────────────────
+
+export const chainStepSchema = z.object({
+  id: z.string(),
+  op: z.string().describe('Facade op to call'),
+  params: z
+    .record(z.unknown())
+    .optional()
+    .describe('Params — use $input.x or $stepId.field for data flow'),
+  output: z.string().optional().describe('Key to store step result under'),
+  gate: z.enum(['user-approval', 'auto-test', 'vault-check', 'none']).optional(),
+  description: z.string().optional(),
+});
+
+export const chainDefSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  steps: z.array(chainStepSchema).min(1),
+});
+
+export type ChainDef = z.infer<typeof chainDefSchema>;
+export type ChainStep = z.infer<typeof chainStepSchema>;
+
+// ─── Chain Instance (runtime state) ──────────────────────────────────
+
+export type ChainStatus = 'running' | 'paused' | 'completed' | 'failed';
+
+export interface StepOutput {
+  stepId: string;
+  op: string;
+  result: unknown;
+  status: 'completed' | 'failed' | 'skipped';
+  durationMs: number;
+}
+
+export interface ChainInstance {
+  id: string;
+  chainId: string;
+  chainName: string;
+  status: ChainStatus;
+  currentStep: string | null;
+  pausedAtGate: string | null;
+  input: Record<string, unknown>;
+  context: Record<string, unknown>;
+  stepOutputs: StepOutput[];
+  stepsCompleted: number;
+  totalSteps: number;
+  createdAt: string;
+  updatedAt: string;
+}

package/src/index.ts

@@ -541,7 +541,6 @@ export type {
 
 // ─── Persistence ───────────────────────────────────────────────────────
 export { SQLitePersistenceProvider } from './persistence/index.js';
-export { PostgresPersistenceProvider, translateSql } from './persistence/index.js';
 export type {
   PersistenceProvider,
   PersistenceParams,