@soleri/core 9.5.0 → 9.6.0

package/src/packs/pack-installer.ts

@@ -22,6 +22,7 @@ import type { Vault } from '../vault/vault.js';
 import type { PluginRegistry } from '../plugins/plugin-registry.js';
 import type { PluginContext } from '../plugins/types.js';
 import type { PackRuntime } from '../domain-packs/pack-runtime.js';
+import { PackLifecycleManager } from './pack-lifecycle.js';
 
 const MANIFEST_FILENAME = 'soleri-pack.json';
 
@@ -31,6 +32,7 @@ const MANIFEST_FILENAME = 'soleri-pack.json';
 
 export class PackInstaller {
   private packs = new Map<string, InstalledPack>();
+  readonly lifecycle = new PackLifecycleManager();
 
   constructor(
     private vault: Vault,
@@ -206,17 +208,21 @@ export class PackInstaller {
       const hooksDir = join(packDir, manifest.hooks?.dir ?? 'hooks');
       const hooks = existsSync(hooksDir) ? listMarkdownFiles(hooksDir) : [];
 
-      // Track installed pack
+      // Track installed pack with lifecycle
+      this.lifecycle.initState(manifest.id, 'installed');
+      this.lifecycle.transition(manifest.id, 'ready', 'Initial install');
+
       const installed: InstalledPack = {
         id: manifest.id,
         manifest,
         directory: packDir,
-        status: 'installed',
+        status: 'ready',
         vaultEntries,
         skills,
         hooks,
         facadesRegistered,
         installedAt: Date.now(),
+        transitions: this.lifecycle.getTransitions(manifest.id),
       };
       this.packs.set(manifest.id, installed);
 
@@ -231,17 +237,23 @@ export class PackInstaller {
     } catch (e) {
       const error = e instanceof Error ? e.message : String(e);
 
+      // Transition to error state
+      this.lifecycle.initState(manifest.id, 'installed');
+      this.lifecycle.transition(manifest.id, 'error', error);
+
       this.packs.set(manifest.id, {
         id: manifest.id,
         manifest,
         directory: packDir,
         status: 'error',
         error,
+        errorMessage: error,
         vaultEntries: 0,
         skills: [],
         hooks: [],
         facadesRegistered: false,
         installedAt: Date.now(),
+        transitions: this.lifecycle.getTransitions(manifest.id),
       });
 
       return {
@@ -269,11 +281,75 @@ export class PackInstaller {
       this.pluginRegistry.deactivate(packId);
     }
 
+    // Transition to uninstalled
+    try {
+      this.lifecycle.transition(packId, 'uninstalled', 'User uninstall');
+    } catch {
+      // May not be tracked in lifecycle — continue anyway
+    }
+    this.lifecycle.remove(packId);
+
     pack.status = 'uninstalled';
     this.packs.delete(packId);
     return true;
   }
 
+  /**
+   * Disable a pack — deactivates capabilities but preserves vault entries.
+   */
+  disable(packId: string): boolean {
+    const pack = this.packs.get(packId);
+    if (!pack) return false;
+
+    this.lifecycle.transition(packId, 'disabled', 'User disabled');
+
+    // Deactivate facades
+    if (pack.facadesRegistered) {
+      this.pluginRegistry.deactivate(packId);
+    }
+
+    pack.status = 'disabled';
+    pack.disabledAt = Date.now();
+    pack.transitions = this.lifecycle.getTransitions(packId);
+    return true;
+  }
+
+  /**
+   * Enable a previously disabled pack — reactivates capabilities.
+   */
+  async enable(packId: string, runtimeCtx?: unknown, packRuntime?: PackRuntime): Promise<boolean> {
+    const pack = this.packs.get(packId);
+    if (!pack) return false;
+
+    this.lifecycle.transition(packId, 'ready', 'User enabled');
+
+    // Reactivate facades
+    if (pack.manifest.facades.length > 0 && this.pluginRegistry.get(packId)) {
+      const ctx: PluginContext = {
+        packRuntime:
+          packRuntime ??
+          ({
+            vault: {},
+            getProject: () => undefined,
+            listProjects: () => [],
+            createCheck: () => '',
+            validateCheck: () => null,
+            validateAndConsume: () => null,
+          } as unknown as PackRuntime),
+        runtime: runtimeCtx ?? {},
+        manifest: this.pluginRegistry.get(packId)!.manifest,
+        directory: pack.directory,
+      };
+      await this.pluginRegistry.activate(packId, ctx);
+      pack.facadesRegistered = true;
+    }
+
+    pack.status = 'ready';
+    pack.disabledAt = undefined;
+    pack.transitions = this.lifecycle.getTransitions(packId);
+    return true;
+  }
+
   /**
    * Get an installed pack by ID.
    */

package/src/packs/pack-lifecycle.ts

@@ -0,0 +1,115 @@
+/**
+ * Pack Lifecycle Manager — Central state machine for pack lifecycle management.
+ *
+ * Manages in-memory pack states, validates transitions against VALID_TRANSITIONS,
+ * records transition history, and notifies listeners on state changes.
+ */
+
+import type { PackState, PackTransition } from './types.js';
+import { VALID_TRANSITIONS } from './types.js';
+
+type TransitionListener = (packId: string, from: PackState, to: PackState, reason?: string) => void;
+
+interface PackEntry {
+  state: PackState;
+  transitions: PackTransition[];
+}
+
+export class PackLifecycleManager {
+  private packs: Map<string, PackEntry> = new Map();
+  private listeners: Array<TransitionListener> = [];
+
+  /**
+   * Transition a pack to a new state. Validates against VALID_TRANSITIONS.
+   * Throws a descriptive error if the transition is not allowed.
+   */
+  transition(packId: string, to: PackState, reason?: string): void {
+    const entry = this.packs.get(packId);
+    if (!entry) {
+      throw new Error(`Pack '${packId}' is not being tracked`);
+    }
+
+    const currentState = entry.state;
+    const validTargets = VALID_TRANSITIONS[currentState];
+
+    if (!validTargets.includes(to)) {
+      throw new Error(
+        `Invalid pack lifecycle transition for '${packId}': '${currentState}' \u2192 '${to}'. Valid targets from '${currentState}': ${validTargets.join(', ')}`,
+      );
+    }
+
+    const transition: PackTransition = {
+      from: currentState,
+      to,
+      timestamp: Date.now(),
+      reason,
+    };
+
+    entry.state = to;
+    entry.transitions.push(transition);
+
+    for (const listener of this.listeners) {
+      listener(packId, currentState, to, reason);
+    }
+  }
+
+  /**
+   * Set initial state without transition validation (for loading from lockfile).
+   */
+  initState(packId: string, state: PackState): void {
+    this.packs.set(packId, { state, transitions: [] });
+  }
+
+  /**
+   * Returns current state of a pack, or undefined if not tracked.
+   */
+  getState(packId: string): PackState | undefined {
+    return this.packs.get(packId)?.state;
+  }
+
+  /**
+   * Returns the full transition history for a pack.
+   */
+  getTransitions(packId: string): PackTransition[] {
+    return this.packs.get(packId)?.transitions ?? [];
+  }
+
+  /**
+   * Register a listener for state transitions. Returns an unsubscribe function.
+   */
+  onTransition(callback: TransitionListener): () => void {
+    this.listeners.push(callback);
+    return () => {
+      const idx = this.listeners.indexOf(callback);
+      if (idx !== -1) {
+        this.listeners.splice(idx, 1);
+      }
+    };
+  }
+
+  /**
+   * Remove a pack from tracking entirely.
+   */
+  remove(packId: string): void {
+    this.packs.delete(packId);
+  }
+
+  /**
+   * List all tracked packs with their current state.
+   */
+  listAll(): Array<{ packId: string; state: PackState }> {
+    const result: Array<{ packId: string; state: PackState }> = [];
+    for (const [packId, entry] of this.packs) {
+      result.push({ packId, state: entry.state });
+    }
+    return result;
+  }
+
+  /**
+   * Clear all tracked state and listeners.
+   */
+  reset(): void {
+    this.packs.clear();
+    this.listeners.length = 0;
+  }
+}

package/src/packs/pack-lockfile.test.ts

@@ -81,7 +81,7 @@ describe('PackLockfile', () => {
     expect(existsSync(lockPath)).toBe(true);
 
     const data = JSON.parse(readFileSync(lockPath, 'utf-8'));
-    expect(data.version).toBe(1);
+    expect(data.version).toBe(2);
     expect(data.packs['test-pack'].version).toBe('1.0.0');
   });
 

package/src/packs/pack-system.test.ts

@@ -417,7 +417,7 @@ describe('PackInstaller', () => {
       const pack = installer.get('specific');
       expect(pack).toBeDefined();
       expect(pack?.manifest.version).toBe('3.0.0');
-      expect(pack?.status).toBe('installed');
+      expect(pack?.status).toBe('ready');
     });
   });
 });

package/src/packs/types.ts

@@ -108,13 +108,43 @@ export type PackManifest = z.infer<typeof packManifestSchema>;
 // INSTALL TYPES
 // =============================================================================
 
-export type PackStatus = 'installed' | 'error' | 'uninstalled';
+// ─── Lifecycle States ─────────────────────────────────────────────────
+
+/** Full lifecycle state for a pack */
+export type PackState =
+  | 'installed' // Just installed, not yet activated
+  | 'ready' // Active — capabilities, skills, hooks all live
+  | 'disabled' // Temporarily deactivated — vault entries kept, capabilities off
+  | 'error' // Failed to activate — error message in errorMessage field
+  | 'upgrade_pending' // New version available, old version still active
+  | 'uninstalled'; // Removed — vault entries remain (permanent knowledge)
+
+/** @deprecated Use PackState instead */
+export type PackStatus = PackState;
+
+/** Valid state transitions — key is "from" state, values are allowed "to" states */
+export const VALID_TRANSITIONS: Record<PackState, PackState[]> = {
+  installed: ['ready', 'error', 'uninstalled'],
+  ready: ['ready', 'disabled', 'error', 'upgrade_pending', 'uninstalled'],
+  disabled: ['ready', 'uninstalled'],
+  error: ['ready', 'uninstalled'],
+  upgrade_pending: ['ready', 'error', 'uninstalled'],
+  uninstalled: ['installed'],
+};
+
+/** A recorded state transition */
+export interface PackTransition {
+  from: PackState;
+  to: PackState;
+  timestamp: number;
+  reason?: string;
+}
 
 export interface InstalledPack {
   id: string;
   manifest: PackManifest;
   directory: string;
-  status: PackStatus;
+  status: PackState;
   error?: string;
   /** Number of vault entries seeded */
   vaultEntries: number;
@@ -125,6 +155,14 @@ export interface InstalledPack {
   /** Whether facades were registered via plugin system */
   facadesRegistered: boolean;
   installedAt: number;
+  /** Lifecycle transition history (most recent last) */
+  transitions?: PackTransition[];
+  /** When the pack was disabled (if in disabled state) */
+  disabledAt?: number;
+  /** Error message (if in error state) */
+  errorMessage?: string;
+  /** Version available for upgrade (if in upgrade_pending state) */
+  upgradeVersion?: string;
 }
 
 export interface InstallResult {

package/src/persistence/sqlite-provider.ts

@@ -3,9 +3,14 @@
  *
  * Supports both positional (array) and named (object) parameters.
  * Exposes getDatabase() for backward-compat consumers that need the raw db.
+ *
+ * better-sqlite3 is loaded lazily at construction time (not at module import)
+ * so that code paths that never instantiate a provider don't require the
+ * native module to be installed.
  */
 
-import Database from 'better-sqlite3';
+import type Database from 'better-sqlite3';
+import { createRequire } from 'node:module';
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type {
@@ -15,6 +20,24 @@ import type {
   FtsSearchOptions,
 } from './types.js';
 
+type DatabaseConstructor = typeof Database;
+let _DatabaseCtor: DatabaseConstructor | undefined;
+
+function loadDriver(): DatabaseConstructor {
+  if (!_DatabaseCtor) {
+    const req = createRequire(import.meta.url);
+    try {
+      _DatabaseCtor = req('better-sqlite3') as DatabaseConstructor;
+    } catch {
+      throw new Error(
+        'better-sqlite3 is required for persistence but is not installed.\n' +
+          'Run: npm install better-sqlite3',
+      );
+    }
+  }
+  return _DatabaseCtor;
+}
+
 /** Apply performance-tuning PRAGMAs for file-backed SQLite databases. */
 export function applyPerformancePragmas(db: Database.Database): void {
   db.pragma('cache_size = -64000'); // 64MB
@@ -28,8 +51,9 @@ export class SQLitePersistenceProvider implements PersistenceProvider {
   private db: Database.Database;
 
   constructor(path: string = ':memory:') {
+    const Driver = loadDriver();
     if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
-    this.db = new Database(path);
+    this.db = new Driver(path);
     if (path !== ':memory:') applyPerformancePragmas(this.db);
   }
 

package/src/runtime/admin-setup-ops.test.ts

@@ -5,17 +5,21 @@ import type { OpDefinition } from '../facades/types.js';
 
 // ─── Mock Node.js fs/os modules ────────────────────────────────────────
 
+/** Normalize path separators so Windows backslash paths match forward-slash keys */
+const norm = (p: string): string => p.replace(/\\/g, '/');
+
 const mockFs: Record<string, string> = {};
 const mockDirs = new Set<string>();
 
 vi.mock('node:fs', () => ({
-  existsSync: vi.fn((p: string) => p in mockFs || mockDirs.has(p)),
+  existsSync: vi.fn((p: string) => norm(p) in mockFs || mockDirs.has(norm(p))),
   readFileSync: vi.fn((p: string) => {
-    if (p in mockFs) return mockFs[p];
+    const key = norm(p);
+    if (key in mockFs) return mockFs[key];
     throw new Error(`ENOENT: ${p}`);
   }),
   writeFileSync: vi.fn((p: string, content: string) => {
-    mockFs[p] = content;
+    mockFs[norm(p)] = content;
   }),
   mkdirSync: vi.fn((_p: string) => undefined),
   copyFileSync: vi.fn(),
@@ -30,7 +34,8 @@ vi.mock('node:os', () => ({
 
 vi.mock('node:path', async () => {
   const actual = await vi.importActual<typeof import('node:path')>('node:path');
-  return actual;
+  // Always use posix path semantics so mock filesystem keys (forward slashes) work on all platforms
+  return { ...actual.posix, default: actual.posix };
 });
 
 vi.mock('./claude-md-helpers.js', () => ({

package/src/runtime/orchestrate-ops.ts

@@ -38,6 +38,7 @@ import {
 import { detectRationalizations } from '../planning/rationalization-detector.js';
 import { ImpactAnalyzer } from '../planning/impact-analyzer.js';
 import type { ImpactReport } from '../planning/impact-analyzer.js';
+import { recordPlanFeedback } from './plan-feedback-helper.js';
 
 // ---------------------------------------------------------------------------
 // Intent detection — keyword-based mapping from prompt to intent
@@ -235,7 +236,7 @@ export function createOrchestrateOps(
   runtime: AgentRuntime,
   facades?: FacadeConfig[],
 ): OpDefinition[] {
-  const { planner, brainIntelligence, vault, contextHealth } = runtime;
+  const { planner, brain, brainIntelligence, vault, contextHealth } = runtime;
   const agentId = runtime.config.agentId;
 
   return [
@@ -385,11 +386,149 @@ export function createOrchestrateOps(
         planId: z.string().describe('ID of the plan to execute (flow planId or legacy planId)'),
         domain: z.string().optional().describe('Domain for brain session tracking'),
         context: z.string().optional().describe('Additional context for the brain session'),
+        runtime: z
+          .string()
+          .optional()
+          .describe(
+            'Runtime adapter type (e.g. "claude-code", "codex"). ' +
+              'When provided, dispatches via the adapter instead of the flow engine.',
+          ),
+        subagent: z
+          .boolean()
+          .optional()
+          .describe(
+            'When true, dispatches plan tasks via SubagentDispatcher instead of FlowExecutor. ' +
+              'Each task runs as a separate subagent process.',
+          ),
+        parallel: z
+          .boolean()
+          .optional()
+          .describe(
+            'Run subagent tasks in parallel (default: true). Only applies when subagent=true.',
+          ),
+        maxConcurrent: z
+          .number()
+          .optional()
+          .describe('Max concurrent subagents (default: 3). Only applies when subagent=true.'),
       }),
       handler: async (params) => {
         const planId = params.planId as string;
         const domain = params.domain as string | undefined;
         const context = params.context as string | undefined;
+        const runtimeType = params.runtime as string | undefined;
+        const useSubagent = params.subagent as boolean | undefined;
+        const parallelMode = params.parallel as boolean | undefined;
+        const maxConcurrentParam = params.maxConcurrent as number | undefined;
+
+        // ── Subagent dispatch path ───────────────────────────────────
+        // When subagent=true, dispatch plan tasks via SubagentDispatcher.
+        // Each task runs as a separate child process via the adapter layer.
+        if (useSubagent && runtime.subagentDispatcher) {
+          const entry = planStore.get(planId);
+          const legacyPlan = !entry ? planner.get(planId) : undefined;
+          const tasks =
+            entry?.plan.steps.map((s) => ({
+              taskId: s.id,
+              prompt: s.name,
+              workspace: process.cwd(),
+              runtime: runtimeType,
+              timeout: 300_000,
+            })) ??
+            legacyPlan?.tasks?.map((t) => ({
+              taskId: t.id,
+              prompt: t.title ?? t.description ?? '',
+              workspace: process.cwd(),
+              runtime: runtimeType,
+              timeout: 300_000,
+            })) ??
+            [];
+
+          const aggregated = await runtime.subagentDispatcher.dispatch(tasks, {
+            parallel: parallelMode ?? true,
+            maxConcurrent: maxConcurrentParam ?? 3,
+          });
+
+          // Track in brain session
+          const existingSession = brainIntelligence.getSessionByPlanId(planId);
+          const session =
+            existingSession && !existingSession.endedAt
+              ? existingSession
+              : brainIntelligence.lifecycle({
+                  action: 'start',
+                  domain,
+                  context,
+                  planId,
+                });
+
+          contextHealth.track({
+            type: 'orchestrate_execute',
+            payloadSize: JSON.stringify(aggregated).length,
+          });
+          const healthStatus = contextHealth.check();
+          const healthWarning = buildHealthWarning(healthStatus, vault);
+
+          return {
+            plan: { id: planId, status: 'executing' },
+            session,
+            subagent: {
+              status: aggregated.status,
+              totalTasks: aggregated.totalTasks,
+              completed: aggregated.completed,
+              failed: aggregated.failed,
+              durationMs: aggregated.durationMs,
+              totalUsage: aggregated.totalUsage,
+            },
+            ...(healthWarning ? { contextHealth: healthWarning } : {}),
+          };
+        }
+
+        // ── Adapter dispatch path ────────────────────────────────────
+        // When a runtime is specified, dispatch the plan's prompt via the
+        // adapter instead of the flow engine. This is the integration point
+        // for multi-runtime support (GH #410).
+        if (runtimeType && runtime.adapterRegistry) {
+          const adapter = runtime.adapterRegistry.get(runtimeType);
+          const entry = planStore.get(planId);
+          const prompt = entry?.plan.summary ?? `Execute plan ${planId}`;
+
+          const adapterResult = await adapter.execute({
+            runId: `${planId}-${Date.now()}`,
+            prompt,
+            workspace: process.cwd(),
+            config: { planId, domain },
+          });
+
+          // Track in brain session
+          const existingSession = brainIntelligence.getSessionByPlanId(planId);
+          const session =
+            existingSession && !existingSession.endedAt
+              ? existingSession
+              : brainIntelligence.lifecycle({
+                  action: 'start',
+                  domain,
+                  context,
+                  planId,
+                });
+
+          contextHealth.track({
+            type: 'orchestrate_execute',
+            payloadSize: JSON.stringify(adapterResult).length,
+          });
+          const healthStatus = contextHealth.check();
+          const healthWarning = buildHealthWarning(healthStatus, vault);
+
+          return {
+            plan: { id: planId, status: 'executing' },
+            session,
+            adapter: {
+              type: runtimeType,
+              exitCode: adapterResult.exitCode,
+              summary: adapterResult.summary,
+              usage: adapterResult.usage,
+            },
+            ...(healthWarning ? { contextHealth: healthWarning } : {}),
+          };
+        }
 
         // Look up flow plan
         const entry = planStore.get(planId);
@@ -636,6 +775,19 @@ export function createOrchestrateOps(
           filesModified,
         });
 
+        // Record brain feedback for vault entries referenced in plan decisions
+        if (planObj && planObj.decisions) {
+          try {
+            recordPlanFeedback(
+              { objective: planObj.objective, decisions: planObj.decisions },
+              brain,
+              brainIntelligence,
+            );
+          } catch {
+            // Brain feedback is best-effort
+          }
+        }
+
         // Extract knowledge — runs regardless of plan existence
         let extraction = null;
         try {

package/src/runtime/runtime.ts

@@ -61,6 +61,9 @@ import { generatePersonaInstructions } from '../persona/prompt-generator.js';
 import { OperatorProfileStore } from '../operator/operator-profile.js';
 import { ContextHealthMonitor } from './context-health.js';
 import { ShutdownRegistry } from './shutdown-registry.js';
+import { RuntimeAdapterRegistry } from '../adapters/registry.js';
+import { ClaudeCodeRuntimeAdapter } from '../adapters/claude-code-adapter.js';
+import { SubagentDispatcher } from '../subagent/dispatcher.js';
 
 /**
  * Create a fully initialized agent runtime.
@@ -322,6 +325,8 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   shutdownRegistry.register('pipelineRunner', () => pipelineRunner.stop());
   // Agency manager — close FSWatchers and debounce timers
   shutdownRegistry.register('agencyManager', () => agencyManager.disable());
+
+  shutdownRegistry.register('subagentDispatcher', () => subagentDispatcher.cleanup());
   // Loop manager — clear accumulated state
   shutdownRegistry.register('loopManager', () => {
     if (loop.isActive()) {
@@ -333,6 +338,14 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     }
   });
 
+  // Runtime Adapter Registry — dispatch work to different AI CLIs
+  const adapterRegistry = new RuntimeAdapterRegistry();
+  adapterRegistry.register('claude-code', new ClaudeCodeRuntimeAdapter());
+  adapterRegistry.setDefault('claude-code');
+
+  // Subagent Dispatcher — spawn and manage child agent processes
+  const subagentDispatcher = new SubagentDispatcher({ adapterRegistry });
+
   return {
     config,
     logger,
@@ -379,6 +392,8 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
       const p = loadPersona(agentId, config.persona ?? undefined);
       return generatePersonaInstructions(p);
     })(),
+    adapterRegistry,
+    subagentDispatcher,
     contextHealth: new ContextHealthMonitor(),
     shutdownRegistry,
     createdAt: Date.now(),