@soleri/core 9.11.0 → 9.12.1

package/src/runtime/admin-ops.ts

@@ -277,6 +277,23 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
+    // ─── Subagent Orphan Reaping ────────────────────────────────────
+    {
+      name: 'admin_reap_orphans',
+      description:
+        'Detect and clean up orphaned subagent processes. Returns reaped PIDs and task IDs.',
+      auth: 'admin',
+      handler: async () => {
+        const dispatcher = runtime.subagentDispatcher;
+        const results = dispatcher.reapOrphans();
+        return {
+          reaped: results.reaped.length,
+          tasks: results.reaped,
+          alive: results.alive,
+        };
+      },
+    },
+
     // ─── Diagnostics ─────────────────────────────────────────────────
     {
       name: 'admin_diagnostic',

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

@@ -352,7 +352,7 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'admin_setup_global',
       description:
-        'Install global agent configuration — hookify rules to ~/.claude/, skills to ~/.claude/commands/, lifecycle hooks to settings.json. Dry-run by default.',
+        'Install global agent configuration — hookify rules to ~/.claude/, skills to ~/.claude/skills/, lifecycle hooks to settings.json. Dry-run by default.',
       auth: 'admin',
       schema: z.object({
         install: z.boolean().describe('Set true to install, false for dry-run preview'),
@@ -370,7 +370,7 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
           .boolean()
           .optional()
           .default(false)
-          .describe('Only install skills to ~/.claude/commands/'),
+          .describe('Only install skills to ~/.claude/skills/'),
       }),
       handler: async (params) => {
         const install = params.install as boolean;

package/src/runtime/embedding-ops.ts

@@ -0,0 +1,116 @@
+/**
+ * Embedding Ops — embed_status, embed_rebuild, embed_entry.
+ *
+ * Covers:
+ * - Embedding statistics and health
+ * - Batch rebuild of missing vectors
+ * - Single-entry embedding
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+import { getEntriesWithoutVectors } from '../vault/vault-entries.js';
+
+export function createEmbeddingOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault, flags, embeddingProvider, embeddingPipeline } = runtime;
+
+  return [
+    {
+      name: 'embed_status',
+      description:
+        'Get embedding subsystem status — provider info, vector counts, token usage. Returns { enabled: false } when embeddings are not configured.',
+      auth: 'read' as const,
+      handler: async () => {
+        if (!embeddingProvider || !flags.isEnabled('embedding-enabled')) {
+          return {
+            enabled: false,
+            reason: !flags.isEnabled('embedding-enabled')
+              ? 'feature flag embedding-enabled is off'
+              : 'no embedding config',
+          };
+        }
+
+        const persistence = vault.getProvider();
+        const model = embeddingProvider.model;
+        const missingIds = getEntriesWithoutVectors(persistence, model);
+
+        const embeddedRow = persistence.get<{ count: number }>(
+          'SELECT COUNT(*) as count FROM entry_vectors WHERE model = ?',
+          [model],
+        );
+        const totalEmbedded = embeddedRow?.count ?? 0;
+
+        const tokensRow = persistence.get<{ total: number }>(
+          `SELECT COALESCE(SUM(1), 0) as total FROM entry_vectors`,
+          [],
+        );
+
+        return {
+          enabled: true,
+          provider: embeddingProvider.providerName,
+          model: embeddingProvider.model,
+          dimensions: embeddingProvider.dimensions,
+          totalEmbedded,
+          totalMissing: missingIds.length,
+          // Token tracking is per-call in pipeline — we report what we can from the DB
+          totalTokensUsed: tokensRow?.total ?? 0,
+        };
+      },
+    },
+    {
+      name: 'embed_rebuild',
+      description:
+        'Trigger batch embedding of all vault entries missing vectors. Returns counts of embedded, skipped, failed entries and tokens used.',
+      auth: 'write' as const,
+      handler: async () => {
+        if (!embeddingPipeline || !flags.isEnabled('embedding-enabled')) {
+          return {
+            enabled: false,
+            reason: !flags.isEnabled('embedding-enabled')
+              ? 'feature flag embedding-enabled is off'
+              : 'no embedding pipeline configured',
+          };
+        }
+
+        const result = await embeddingPipeline.batchEmbed();
+        return {
+          enabled: true,
+          embedded: result.embedded,
+          skipped: result.skipped,
+          failed: result.failed,
+          tokensUsed: result.tokensUsed,
+        };
+      },
+    },
+    {
+      name: 'embed_entry',
+      description:
+        'Embed a single vault entry by ID. Returns { embedded: true } if a new vector was created, { embedded: false } if already up to date.',
+      auth: 'write' as const,
+      schema: z.object({
+        entryId: z.string().describe('Vault entry ID to embed'),
+      }),
+      handler: async (params) => {
+        if (!embeddingPipeline || !flags.isEnabled('embedding-enabled')) {
+          return {
+            enabled: false,
+            reason: !flags.isEnabled('embedding-enabled')
+              ? 'feature flag embedding-enabled is off'
+              : 'no embedding pipeline configured',
+          };
+        }
+
+        const entryId = params.entryId as string;
+        const entry = vault.get(entryId);
+        if (!entry) {
+          return { embedded: false, error: `Entry "${entryId}" not found` };
+        }
+
+        const text = [entry.title, entry.description, entry.context].filter(Boolean).join('\n');
+        const embedded = await embeddingPipeline.embedEntry(entryId, text);
+        return { embedded };
+      },
+    },
+  ];
+}

package/src/runtime/facades/admin-facade.test.ts

@@ -85,6 +85,9 @@ function mockRuntime(): AgentRuntime {
       get: vi.fn(),
     },
     packInstaller: { list: vi.fn(() => []) },
+    subagentDispatcher: {
+      reapOrphans: vi.fn().mockReturnValue({ reaped: [], alive: [] }),
+    },
     createdAt: Date.now() - 60000,
     persona: { name: 'TestAgent' },
   } as unknown as AgentRuntime;
@@ -327,4 +330,32 @@ describe('createAdminFacadeOps', () => {
       expect(result).toEqual({});
     });
   });
+
+  describe('admin_reap_orphans (from satellite)', () => {
+    it('returns empty when no orphans', async () => {
+      const result = (await findOp(ops, 'admin_reap_orphans').handler({})) as Record<
+        string,
+        unknown
+      >;
+      expect(result.reaped).toBe(0);
+      expect(result.tasks).toEqual([]);
+      expect(result.alive).toEqual([]);
+    });
+
+    it('returns reaped orphans', async () => {
+      vi.mocked(runtime.subagentDispatcher.reapOrphans).mockReturnValue({
+        reaped: ['task-1', 'task-2'],
+        alive: ['task-3'],
+      });
+      ops = createAdminFacadeOps(runtime);
+
+      const result = (await findOp(ops, 'admin_reap_orphans').handler({})) as Record<
+        string,
+        unknown
+      >;
+      expect(result.reaped).toBe(2);
+      expect(result.tasks).toEqual(['task-1', 'task-2']);
+      expect(result.alive).toEqual(['task-3']);
+    });
+  });
 });

package/src/runtime/facades/embedding-facade.ts

@@ -0,0 +1,11 @@
+/**
+ * Embedding facade — vector embedding management ops.
+ */
+
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createEmbeddingOps } from '../embedding-ops.js';
+
+export function createEmbeddingFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  return [...createEmbeddingOps(runtime)];
+}

package/src/runtime/facades/index.ts

@@ -27,6 +27,8 @@ import { createIntakeFacadeOps } from './intake-facade.js';
 import { createLinksFacadeOps } from './links-facade.js';
 import { createBranchingFacadeOps } from './branching-facade.js';
 import { createTierFacadeOps } from './tier-facade.js';
+import { createEmbeddingFacadeOps } from './embedding-facade.js';
+import { createDreamOps } from '../../dream/dream-ops.js';
 
 export function createSemanticFacades(runtime: AgentRuntime, agentId: string): FacadeConfig[] {
   const facades: FacadeConfig[] = [
@@ -128,11 +130,21 @@ export function createSemanticFacades(runtime: AgentRuntime, agentId: string): F
       description: 'Vault branching — create, list, merge, delete branches.',
       ops: createBranchingFacadeOps(runtime),
     },
+    {
+      name: `${agentId}_embedding`,
+      description: 'Embedding management — status, batch rebuild, single-entry embedding.',
+      ops: createEmbeddingFacadeOps(runtime),
+    },
     {
       name: `${agentId}_tier`,
       description: 'Multi-vault tiers — connect, disconnect, search across sources.',
       ops: createTierFacadeOps(runtime),
     },
+    {
+      name: `${agentId}_dream`,
+      description: 'Dream — automatic memory consolidation, vault cleanup, and maintenance.',
+      ops: createDreamOps(runtime),
+    },
   ];
 
   return facades;

package/src/runtime/facades/orchestrate-facade.test.ts

@@ -95,6 +95,22 @@ describe('orchestrate-facade', () => {
     expect(data.governance).toBeDefined();
   });
 
+  it('session_start includes preflight manifest', async () => {
+    const result = await executeOp(ops, 'session_start', { projectPath: '/test/proj' });
+    expect(result.success).toBe(true);
+    const data = result.data as Record<string, unknown>;
+    const preflight = data.preflight as Record<string, unknown>;
+    expect(preflight).toBeDefined();
+    expect(Array.isArray(preflight.tools)).toBe(true);
+    expect(Array.isArray(preflight.skills)).toBe(true);
+    expect(Array.isArray(preflight.activePlans)).toBe(true);
+    expect(preflight.vaultSummary).toBeDefined();
+    const vaultSummary = preflight.vaultSummary as Record<string, unknown>;
+    expect(typeof vaultSummary.entryCount).toBe('number');
+    expect(typeof vaultSummary.connected).toBe('boolean');
+    expect(Array.isArray(vaultSummary.domains)).toBe(true);
+  });
+
   it('session_start increments session count on second call', async () => {
     await executeOp(ops, 'session_start', { projectPath: '/test/proj' });
     const result = await executeOp(ops, 'session_start', { projectPath: '/test/proj' });

package/src/runtime/facades/orchestrate-facade.ts

@@ -10,6 +10,18 @@ import { createOrchestrateOps } from '../orchestrate-ops.js';
 import { createProjectOps } from '../project-ops.js';
 import { createPlaybookOps } from '../playbook-ops.js';
 import { checkForUpdate } from '../../update-check.js';
+import { buildPreflightManifest } from '../preflight.js';
+import { ENGINE_MODULE_MANIFEST } from '../../engine/module-manifest.js';
+import {
+  createTracker,
+  advanceStep,
+  recordEvidence,
+  generateCheckpoint,
+  validateCompletion,
+  persistTracker,
+  loadTracker,
+} from '../../skills/step-tracker.js';
+import type { SkillStep, EvidenceType } from '../../skills/step-tracker.js';
 
 export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[] {
   const { vault, governance, projectRegistry } = runtime;
@@ -85,6 +97,59 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
           // package.json not readable — skip update check silently
         }
 
+        // Auto-dream: increment session counter and check gate
+        let dreamInfo: { status: unknown; gate: { eligible: boolean; reason: string } } | null =
+          null;
+        try {
+          const { ensureDreamSchema } = await import('../../dream/schema.js');
+          const { DreamEngine } = await import('../../dream/dream-engine.js');
+          ensureDreamSchema(runtime.vault.getProvider());
+          const dreamEngine = new DreamEngine(runtime.vault, runtime.curator);
+          dreamEngine.incrementSessionCount();
+          const gate = dreamEngine.checkGate();
+          dreamInfo = { status: dreamEngine.getStatus(), gate };
+          if (gate.eligible) {
+            // Fire-and-forget: don't block session_start
+            Promise.resolve()
+              .then(() => dreamEngine.run())
+              .catch(() => {
+                /* best-effort */
+              });
+          }
+        } catch {
+          /* dream module not available — skip silently */
+        }
+
+        // ─── Pre-flight manifest ───────────────────────────────
+        let skills: string[] = [];
+        try {
+          const { discoverSkills } = await import('../../skills/sync-skills.js');
+          const agentDir = runtime.config.agentDir;
+          const skillsDirs = agentDir ? [join(agentDir, 'skills')] : [];
+          skills = discoverSkills(skillsDirs).map((s) => s.name);
+        } catch {
+          // Skills discovery is best-effort
+        }
+
+        const agentId = runtime.config.agentId;
+        const facades = ENGINE_MODULE_MANIFEST.map((m) => ({
+          name: `${agentId}_${m.suffix}`,
+          ops: m.keyOps.map((op) => ({ name: op, description: m.description })),
+        }));
+
+        const executingPlans = runtime.planner.getExecuting().map((p) => ({
+          id: p.id,
+          objective: p.objective,
+          status: p.status,
+        }));
+
+        const preflight = buildPreflightManifest({
+          facades,
+          skills,
+          executingPlans,
+          vaultStats: stats,
+        });
+
         return {
           project,
           is_new: isNew,
@@ -101,11 +166,92 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
             isQuotaWarning: quotaStatus.isWarning,
             expiredThisSession: expired,
           },
+          preflight,
           ...(stagingWarning ? { stagingWarning } : {}),
+          ...(dreamInfo ? { dream: dreamInfo } : {}),
         };
       },
     },
 
+    // ─── Skill Step Tracking ──────────────────────────────────────
+    {
+      name: 'skill_step_start',
+      description:
+        'Create a skill step tracker. Persists initial state to disk and returns the tracker with checkpoint summary.',
+      auth: 'write',
+      schema: z.object({
+        skillName: z.string().describe('Name of the skill being tracked'),
+        steps: z
+          .array(
+            z.object({
+              id: z.string(),
+              description: z.string(),
+              evidence: z.enum(['tool_called', 'file_exists']),
+            }),
+          )
+          .describe('Ordered steps with evidence requirements'),
+      }),
+      handler: async (params) => {
+        const steps = (
+          params.steps as Array<{ id: string; description: string; evidence: EvidenceType }>
+        ).map((s): SkillStep => ({ id: s.id, description: s.description, evidence: s.evidence }));
+        const tracker = createTracker(params.skillName as string, steps);
+        const filePath = persistTracker(tracker);
+        const checkpoint = generateCheckpoint(tracker);
+        return { tracker, filePath, checkpoint };
+      },
+    },
+    {
+      name: 'skill_step_advance',
+      description:
+        'Record evidence for the current step, advance to the next step, persist state, and return checkpoint summary.',
+      auth: 'write',
+      schema: z.object({
+        runId: z.string().describe('Run ID returned by skill_step_start'),
+        stepId: z.string().describe('Step ID to record evidence for'),
+        evidence: z.string().describe('Evidence value (tool name or file path)'),
+        verified: z.boolean().optional().default(true).describe('Whether evidence is verified'),
+      }),
+      handler: async (params) => {
+        let tracker = loadTracker(params.runId as string);
+        if (!tracker) {
+          return { error: `No tracker found for runId: ${params.runId}` };
+        }
+        tracker = recordEvidence(
+          tracker,
+          params.stepId as string,
+          params.evidence as string,
+          (params.verified as boolean) ?? true,
+        );
+        tracker = advanceStep(tracker);
+        const filePath = persistTracker(tracker);
+        const checkpoint = generateCheckpoint(tracker);
+        return { tracker, filePath, checkpoint };
+      },
+    },
+    {
+      name: 'skill_step_complete',
+      description:
+        'Validate skill completion, persist final state, and return a completion result with any skipped steps.',
+      auth: 'write',
+      schema: z.object({
+        runId: z.string().describe('Run ID returned by skill_step_start'),
+      }),
+      handler: async (params) => {
+        const tracker = loadTracker(params.runId as string);
+        if (!tracker) {
+          return { error: `No tracker found for runId: ${params.runId}` };
+        }
+        const result = validateCompletion(tracker);
+        // Mark completed if all steps have evidence
+        const finalTracker = result.complete
+          ? { ...tracker, completedAt: tracker.completedAt ?? new Date().toISOString() }
+          : tracker;
+        const filePath = persistTracker(finalTracker);
+        return { result, tracker: finalTracker, filePath };
+      },
+    },
+
     // ─── Satellite ops ───────────────────────────────────────────
     ...createOrchestrateOps(runtime),
     ...createProjectOps(runtime),

package/src/runtime/feature-flags.ts

@@ -23,6 +23,10 @@ const BUILT_IN_FLAGS: Record<string, FlagDefinition> = {
     description: 'Sync vault entries to Cognee knowledge graph',
     defaultValue: true,
   },
+  'embedding-enabled': {
+    description: 'Enable vector embedding provider for hybrid search',
+    defaultValue: false,
+  },
 };
 
 export class FeatureFlags {

package/src/runtime/orchestrate-ops.test.ts

@@ -245,6 +245,137 @@ describe('createOrchestrateOps', () => {
       expect(rt.contextHealth.track).toHaveBeenCalled();
       expect(rt.contextHealth.check).toHaveBeenCalled();
     });
+
+    // ─── Post-dispatch cleanup (subagent path) ─────────────────
+    describe('post-dispatch cleanup', () => {
+      function addSubagentDispatcher(
+        runtime: AgentRuntime,
+        opts: {
+          dispatchResult?: Record<string, unknown>;
+          dispatchError?: Error;
+          reapResult?: string[];
+          reapThrows?: boolean;
+        } = {},
+      ) {
+        const dispatchMock = opts.dispatchError
+          ? vi.fn().mockRejectedValue(opts.dispatchError)
+          : vi.fn().mockResolvedValue(
+              opts.dispatchResult ?? {
+                status: 'completed',
+                totalTasks: 1,
+                completed: 1,
+                failed: 0,
+                durationMs: 100,
+                totalUsage: {},
+              },
+            );
+        const reapMock = opts.reapThrows
+          ? vi.fn().mockImplementation(() => {
+              throw new Error('reap failed');
+            })
+          : vi.fn().mockReturnValue({
+              reaped: opts.reapResult ?? [],
+              alive: [],
+            });
+        const cleanupMock = vi.fn();
+
+        (runtime as Record<string, unknown>).subagentDispatcher = {
+          dispatch: dispatchMock,
+          reapOrphans: reapMock,
+          cleanup: cleanupMock,
+        };
+
+        return { dispatchMock, reapMock, cleanupMock };
+      }
+
+      it('calls reapOrphans after successful subagent dispatch', async () => {
+        const { reapMock } = addSubagentDispatcher(rt);
+        ops = createOrchestrateOps(rt);
+
+        const op = findOp(ops, 'orchestrate_execute');
+        await op.handler({ planId: 'legacy-plan', subagent: true });
+
+        expect(reapMock).toHaveBeenCalledTimes(1);
+      });
+
+      it('calls reapOrphans even when dispatch fails', async () => {
+        const { reapMock } = addSubagentDispatcher(rt, {
+          dispatchError: new Error('dispatch boom'),
+        });
+        ops = createOrchestrateOps(rt);
+
+        const op = findOp(ops, 'orchestrate_execute');
+        await expect(op.handler({ planId: 'legacy-plan', subagent: true })).rejects.toThrow(
+          'dispatch boom',
+        );
+
+        expect(reapMock).toHaveBeenCalledTimes(1);
+      });
+
+      it('includes reapedOrphans in result when orphans found', async () => {
+        addSubagentDispatcher(rt, {
+          reapResult: ['t1'],
+        });
+        ops = createOrchestrateOps(rt);
+
+        const op = findOp(ops, 'orchestrate_execute');
+        const result = (await op.handler({
+          planId: 'legacy-plan',
+          subagent: true,
+        })) as Record<string, unknown>;
+
+        expect(result).toHaveProperty('reapedOrphans');
+        const reaped = result.reapedOrphans as Array<{ taskId: string }>;
+        expect(reaped).toHaveLength(1);
+        expect(reaped[0].taskId).toBe('t1');
+      });
+
+      it('omits reapedOrphans from result when none found', async () => {
+        addSubagentDispatcher(rt, { reapResult: [] });
+        ops = createOrchestrateOps(rt);
+
+        const op = findOp(ops, 'orchestrate_execute');
+        const result = (await op.handler({
+          planId: 'legacy-plan',
+          subagent: true,
+        })) as Record<string, unknown>;
+
+        expect(result).not.toHaveProperty('reapedOrphans');
+      });
+
+      it('does not throw when reapOrphans fails', async () => {
+        addSubagentDispatcher(rt, { reapThrows: true });
+        ops = createOrchestrateOps(rt);
+
+        const op = findOp(ops, 'orchestrate_execute');
+        // Should complete successfully despite reap failure
+        const result = (await op.handler({
+          planId: 'legacy-plan',
+          subagent: true,
+        })) as Record<string, unknown>;
+
+        expect(result).toHaveProperty('subagent');
+        expect(result).not.toHaveProperty('reapedOrphans');
+      });
+
+      it('logs reaped orphans to stderr', async () => {
+        const stderrSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+        addSubagentDispatcher(rt, {
+          reapResult: ['t1', 't2'],
+        });
+        ops = createOrchestrateOps(rt);
+
+        const op = findOp(ops, 'orchestrate_execute');
+        await op.handler({ planId: 'legacy-plan', subagent: true });
+
+        expect(stderrSpy).toHaveBeenCalledWith(
+          expect.stringContaining('Reaped 2 orphaned subagent(s)'),
+        );
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('t1'));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('t2'));
+        stderrSpy.mockRestore();
+      });
+    });
   });
 
   // ─── orchestrate_complete ─────────────────────────────────────