@soleri/core 9.11.0 → 9.13.0

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 ─────────────────────────────────────

package/src/runtime/orchestrate-ops.ts

@@ -15,10 +15,10 @@ import { z } from 'zod';
 import type { OpDefinition, FacadeConfig } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
 import { buildPlan } from '../flows/plan-builder.js';
-import { FlowExecutor } from '../flows/executor.js';
+import { FlowExecutor, getPlanRunDir, loadManifest, saveManifest } from '../flows/executor.js';
 import { createDispatcher } from '../flows/dispatch-registry.js';
 import { runEpilogue } from '../flows/epilogue.js';
-import type { OrchestrationPlan, ExecutionResult } from '../flows/types.js';
+import type { OrchestrationPlan, ExecutionResult, PlanRunManifest } from '../flows/types.js';
 import type { ContextHealthStatus } from './context-health.js';
 import type { OperatorSignals } from '../operator/operator-context-types.js';
 import { loadAgentWorkflows, getWorkflowForIntent } from '../workflows/workflow-loader.js';
@@ -129,6 +129,13 @@ export function applyWorkflowOverride(plan: OrchestrationPlan, override: Workflo
     plan.estimatedTools = plan.steps.reduce((acc, s) => acc + s.tools.length, 0);
   }
 
+  // Set allowedTools from the merged tool set
+  for (const step of plan.steps) {
+    if (step.tools.length > 0) {
+      step.allowedTools = [...new Set(step.tools)];
+    }
+  }
+
   // Add workflow info to warnings for visibility
   plan.warnings.push(
     `Workflow override "${override.name}" applied (${override.gates.length} gate(s), ${override.tools.length} tool(s)).`,
@@ -156,9 +163,14 @@ const planStore = new Map<string, PlanEntry>();
  * If facades are provided, uses the full dispatch registry.
  * Otherwise, falls back to a simple runtime-based dispatcher.
  */
-function buildDispatch(agentId: string, runtime: AgentRuntime, facades?: FacadeConfig[]) {
+function buildDispatch(
+  agentId: string,
+  runtime: AgentRuntime,
+  facades?: FacadeConfig[],
+  activePlan?: import('../flows/dispatch-registry.js').ActivePlanRef,
+) {
   if (facades && facades.length > 0) {
-    return createDispatcher(agentId, facades);
+    return createDispatcher(agentId, facades, activePlan);
   }
 
   // Fallback: runtime-based dispatch for known tool patterns
@@ -534,10 +546,27 @@ export function createOrchestrateOps(
             })) ??
             [];
 
-          const aggregated = await runtime.subagentDispatcher.dispatch(tasks, {
-            parallel: parallelMode ?? true,
-            maxConcurrent: maxConcurrentParam ?? 3,
-          });
+          let aggregated;
+          let reapedOrphans: { taskId: string; pid?: number }[] = [];
+          try {
+            aggregated = await runtime.subagentDispatcher.dispatch(tasks, {
+              parallel: parallelMode ?? true,
+              maxConcurrent: maxConcurrentParam ?? 3,
+            });
+          } finally {
+            // Post-dispatch cleanup: reap orphaned subagent processes
+            try {
+              const reapResult = runtime.subagentDispatcher.reapOrphans();
+              if (reapResult.reaped.length > 0) {
+                reapedOrphans = reapResult.reaped.map((taskId) => ({ taskId }));
+                console.error(
+                  `[soleri] Reaped ${reapResult.reaped.length} orphaned subagent(s): ${reapResult.reaped.join(', ')}`,
+                );
+              }
+            } catch {
+              // Orphan reaping is best-effort — never blocks dispatch result
+            }
+          }
 
           // Track in brain session
           const existingSession = brainIntelligence.getSessionByPlanId(planId);
@@ -569,6 +598,7 @@ export function createOrchestrateOps(
               durationMs: aggregated.durationMs,
               totalUsage: aggregated.totalUsage,
             },
+            ...(reapedOrphans.length > 0 ? { reapedOrphans } : {}),
             ...(healthWarning ? { contextHealth: healthWarning } : {}),
           };
         }
@@ -626,8 +656,17 @@ export function createOrchestrateOps(
 
         if (entry) {
           // Flow-engine execution path
-          const dispatch = buildDispatch(agentId, runtime, facades);
-          const executor = new FlowExecutor(dispatch);
+          const activePlanRef = {
+            steps: entry.plan.steps.map((s) => ({
+              id: s.id,
+              allowedTools: s.allowedTools,
+              status: s.status,
+            })),
+            deviations: entry.plan.deviations,
+          };
+          const dispatch = buildDispatch(agentId, runtime, facades, activePlanRef);
+          const projectPath = (params.projectPath as string) ?? '.';
+          const executor = new FlowExecutor(dispatch, projectPath);
           const executionResult = await executor.execute(entry.plan);
 
           // Store result
@@ -1326,5 +1365,114 @@ export function createOrchestrateOps(
         };
       },
     },
+
+    // ─── orchestrate_rerun_step ──────────────────────────────────────
+    {
+      name: 'orchestrate_rerun_step',
+      description:
+        'Re-execute a single plan step without full restart. Marks the target step as invalidated then rerun, ' +
+        'marks downstream steps as stale (or rerun if within cascadeTo range). ' +
+        'Reads and writes the plan-run manifest on disk.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        stepNumber: z.number().describe('0-based step index to re-run'),
+        reason: z.string().describe('Why the step is being re-run'),
+        projectPath: z
+          .string()
+          .optional()
+          .default('.')
+          .describe('Project root (for manifest location)'),
+        cascadeTo: z
+          .number()
+          .optional()
+          .describe(
+            'If set, also mark steps up to this index (exclusive) as rerun instead of just stale',
+          ),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        const stepNumber = params.stepNumber as number;
+        const reason = params.reason as string;
+        const projectPath = params.projectPath as string;
+        const cascadeTo = params.cascadeTo as number | undefined;
+
+        const runDir = getPlanRunDir(projectPath, planId);
+        let manifest: PlanRunManifest;
+        try {
+          manifest = loadManifest(runDir, planId);
+        } catch (err) {
+          return { error: `Failed to load manifest: ${(err as Error).message}` };
+        }
+
+        const stepKeys = Object.keys(manifest.steps);
+        if (stepKeys.length === 0 && stepNumber > 0) {
+          return {
+            error:
+              'No step data in manifest — the plan may not have been executed with persistence enabled.',
+          };
+        }
+
+        // Find the step key at the target index by checking all steps
+        // Steps are keyed by stepId — we match by position in the plan
+        const allStepIds = Object.keys(manifest.steps);
+        const targetStepId = allStepIds[stepNumber];
+
+        if (!targetStepId && !manifest.steps[String(stepNumber)]) {
+          return {
+            error: `Step ${stepNumber} not found in manifest. Available steps: ${allStepIds.join(', ') || '(none)'}`,
+          };
+        }
+
+        const now = new Date().toISOString();
+        const affected: { stepId: string; status: string }[] = [];
+
+        // Mark all steps by their position
+        const sortedStepIds = Object.keys(manifest.steps);
+        for (let i = 0; i < sortedStepIds.length; i++) {
+          const sid = sortedStepIds[i];
+          const state = manifest.steps[sid];
+
+          if (i === stepNumber) {
+            // Target step: invalidated → rerun
+            state.status = 'rerun';
+            state.rerunCount += 1;
+            state.rerunReason = reason;
+            state.timestamp = now;
+            affected.push({ stepId: sid, status: 'rerun' });
+          } else if (i > stepNumber) {
+            // Downstream step
+            if (cascadeTo !== undefined && i < cascadeTo) {
+              state.status = 'rerun';
+              state.rerunCount += 1;
+              state.rerunReason = `Cascade from step ${stepNumber}: ${reason}`;
+              state.timestamp = now;
+              affected.push({ stepId: sid, status: 'rerun' });
+            } else {
+              state.status = 'stale';
+              state.timestamp = now;
+              affected.push({ stepId: sid, status: 'stale' });
+            }
+          }
+        }
+
+        manifest.lastRun = now;
+
+        try {
+          saveManifest(runDir, manifest);
+        } catch (err) {
+          return { error: `Failed to save manifest: ${(err as Error).message}` };
+        }
+
+        return {
+          planId,
+          stepNumber,
+          reason,
+          cascadeTo: cascadeTo ?? null,
+          affected,
+          manifestPath: runDir,
+        };
+      },
+    },
   ];
 }

package/src/runtime/planning-extra-ops.ts

@@ -9,10 +9,13 @@
  * deliverable submission, and deliverable verification.
  */
 
+import fs from 'node:fs';
 import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
 import type { DriftItem, TaskEvidence } from '../planning/planner.js';
+import type { PlanRunManifest } from '../flows/types.js';
+import { getPlanRunDir } from '../flows/executor.js';
 import { collectGitEvidence } from '../planning/evidence-collector.js';
 import { matchPlaybooks, type PlaybookMatchResult } from '../playbooks/index.js';
 import { entryToPlaybookDefinition } from '../playbooks/index.js';
@@ -178,6 +181,11 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
       schema: z.object({
         planId: z.string().describe('Plan ID to reconcile'),
         actualOutcome: z.string().describe('Description of what actually happened'),
+        projectPath: z
+          .string()
+          .optional()
+          .default('.')
+          .describe('Project root (for reading rerun manifest)'),
         driftItems: z
           .array(
             z.object({
@@ -195,10 +203,79 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           actualOutcome: params.actualOutcome as string,
           driftItems: params.driftItems as DriftItem[] | undefined,
         });
+
+        // Add tool deviations to drift report
+        const deviations =
+          (
+            plan as unknown as {
+              deviations?: Array<{
+                stepId: string;
+                expectedTools: string[];
+                actualTool: string;
+                timestamp: string;
+              }>;
+            }
+          ).deviations ?? [];
+        const toolDeviations =
+          deviations.length > 0
+            ? {
+                count: deviations.length,
+                byStep: Object.entries(
+                  deviations.reduce(
+                    (acc, d) => {
+                      (acc[d.stepId] = acc[d.stepId] || []).push(d);
+                      return acc;
+                    },
+                    {} as Record<string, typeof deviations>,
+                  ),
+                ).map(([stepId, devs]) => ({
+                  stepId,
+                  deviationCount: devs.length,
+                  unexpectedTools: [...new Set(devs.map((d) => d.actualTool))],
+                })),
+              }
+            : undefined;
+
+        // Attach rerun report if a plan-run manifest exists
+        let rerunReport: {
+          totalReruns: number;
+          staleSteps: number;
+          steps: { stepId: string; status: string; rerunCount: number; rerunReason?: string }[];
+        } | null = null;
+
+        try {
+          const projectPath = params.projectPath as string;
+          const runDir = getPlanRunDir(projectPath, params.planId as string);
+          const manifestPath = `${runDir}/manifest.json`;
+          if (fs.existsSync(manifestPath)) {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as PlanRunManifest;
+            const entries = Object.entries(manifest.steps);
+            const rerunSteps = entries.filter(
+              ([, s]) => s.rerunCount > 0 || s.status === 'rerun' || s.status === 'stale',
+            );
+            if (rerunSteps.length > 0) {
+              rerunReport = {
+                totalReruns: rerunSteps.reduce((sum, [, s]) => sum + s.rerunCount, 0),
+                staleSteps: entries.filter(([, s]) => s.status === 'stale').length,
+                steps: rerunSteps.map(([id, s]) => ({
+                  stepId: id,
+                  status: s.status,
+                  rerunCount: s.rerunCount,
+                  rerunReason: s.rerunReason,
+                })),
+              };
+            }
+          }
+        } catch {
+          // Manifest reading is best-effort
+        }
+
         return {
           reconciled: true,
           accuracy: plan.reconciliation!.accuracy,
           driftCount: plan.reconciliation!.driftItems.length,
+          toolDeviations,
+          rerunReport,
           plan,
         };
       },

package/src/runtime/preflight.ts

@@ -0,0 +1,53 @@
+/**
+ * Builds the pre-flight manifest for session_start responses.
+ * Extracted as a pure function for testability.
+ */
+
+import type { PreflightManifest } from './types.js';
+
+export interface PreflightInput {
+  /** Facade definitions: array of { name, ops: Array<{ name, description }> } */
+  facades: Array<{
+    name: string;
+    ops: Array<{ name: string; description: string }>;
+  }>;
+  /** Skill names installed for this agent */
+  skills: string[];
+  /** Plans currently in executing state */
+  executingPlans: Array<{ id: string; objective: string; status: string }>;
+  /** Whether the vault is connected */
+  vaultConnected?: boolean;
+  /** Vault stats */
+  vaultStats: {
+    totalEntries: number;
+    byDomain: Record<string, number>;
+  };
+}
+
+export function buildPreflightManifest(input: PreflightInput): PreflightManifest {
+  const tools: PreflightManifest['tools'] = [];
+  for (const facade of input.facades) {
+    for (const op of facade.ops) {
+      tools.push({ facade: facade.name, op: op.name, description: op.description });
+    }
+  }
+
+  const activePlans = input.executingPlans.map((p) => ({
+    planId: p.id,
+    title: p.objective,
+    status: p.status,
+  }));
+
+  const domains = Object.keys(input.vaultStats.byDomain);
+
+  return {
+    tools,
+    skills: input.skills,
+    activePlans,
+    vaultSummary: {
+      entryCount: input.vaultStats.totalEntries,
+      connected: input.vaultConnected ?? true,
+      domains,
+    },
+  };
+}

package/src/runtime/runtime.ts

@@ -56,6 +56,9 @@ import { PipelineRunner } from '../queue/pipeline-runner.js';
 import { evaluateQuality } from '../curator/quality-gate.js';
 import { classifyEntry } from '../curator/classifier.js';
 import type { AgentRuntimeConfig, AgentRuntime } from './types.js';
+import type { EmbeddingProvider } from '../embeddings/types.js';
+import { OpenAIEmbeddingProvider } from '../embeddings/openai-provider.js';
+import { EmbeddingPipeline } from '../embeddings/pipeline.js';
 import { loadPersona } from '../persona/loader.js';
 import { generatePersonaInstructions } from '../persona/prompt-generator.js';
 import { OperatorProfileStore } from '../operator/operator-profile.js';
@@ -104,12 +107,46 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     }
   }
 
+  // Feature Flags — file-based + env var + runtime toggles (created early so other modules can check)
+  const flags = new FeatureFlags(getAgentFlagsPath(agentId));
+
   // Planner — multi-step task tracking
   const planner = new Planner(plansPath);
 
+  // ─── Embedding Provider (optional) ────────────────────────────────
+  // Only initialized when both config.embedding is present AND the
+  // 'embedding-enabled' feature flag is on. Brain continues without
+  // embeddings when either condition is unmet (vector weight stays 0).
+  let embeddingProvider: EmbeddingProvider | undefined;
+  let embeddingPipeline: EmbeddingPipeline | undefined;
+
+  if (config.embedding && flags.isEnabled('embedding-enabled')) {
+    try {
+      const embeddingConfig = config.embedding;
+      if (embeddingConfig.provider === 'openai') {
+        const openaiPool = new KeyPool(loadKeyPoolConfig(agentId).openai);
+        embeddingProvider = new OpenAIEmbeddingProvider(embeddingConfig, openaiPool);
+      }
+      // Future providers (ollama, etc.) would be added here
+
+      if (embeddingProvider) {
+        embeddingPipeline = new EmbeddingPipeline(embeddingProvider, vault.getProvider());
+        logger.info(
+          `[Embedding] Initialized: ${embeddingProvider.providerName}/${embeddingProvider.model} (${embeddingProvider.dimensions}d)`,
+        );
+      }
+    } catch (err) {
+      logger.warn(
+        `[Embedding] Failed to initialize: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      // Graceful degradation — continue without embeddings
+    }
+  }
+
   // Brain — intelligence layer (TF-IDF scoring, auto-tagging, dedup)
   // Pass vaultManager so intelligentSearch queries all connected sources (not just agent tier)
-  const brain = new Brain(vault, vaultManager);
+  // Pass embeddingProvider for hybrid FTS5+vector search when available
+  const brain = new Brain(vault, vaultManager, embeddingProvider);
 
   // Brain Intelligence — pattern strengths, session knowledge, intelligence pipeline
   const brainIntelligence = new BrainIntelligence(vault, brain);
@@ -366,7 +403,7 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     intakePipeline,
     textIngester,
     authPolicy: { mode: 'permissive', callerLevel: 'admin' },
-    flags: new FeatureFlags(getAgentFlagsPath(agentId)),
+    flags,
     health,
     playbookExecutor,
     pluginRegistry,
@@ -392,6 +429,8 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
       const p = loadPersona(agentId, config.persona ?? undefined);
       return generatePersonaInstructions(p);
     })(),
+    embeddingProvider,
+    embeddingPipeline,
     adapterRegistry,
     subagentDispatcher,
     contextHealth: new ContextHealthMonitor(),

package/src/runtime/types.ts

@@ -39,6 +39,20 @@ import type { ContextHealthMonitor } from './context-health.js';
 import type { ShutdownRegistry } from './shutdown-registry.js';
 import type { RuntimeAdapterRegistry } from '../adapters/registry.js';
 import type { SubagentDispatcher } from '../subagent/dispatcher.js';
+import type { EmbeddingConfig, EmbeddingProvider } from '../embeddings/types.js';
+import type { EmbeddingPipeline } from '../embeddings/pipeline.js';
+
+/** Pre-flight manifest returned by session_start for agent self-awareness. */
+export interface PreflightManifest {
+  tools: Array<{ facade: string; op: string; description: string }>;
+  skills: string[];
+  activePlans: Array<{ planId: string; title: string; status: string }>;
+  vaultSummary: {
+    entryCount: number;
+    connected: boolean;
+    domains: string[];
+  };
+}
 
 /**
  * Configuration for creating an agent runtime.
@@ -63,6 +77,8 @@ export interface AgentRuntimeConfig {
   agentDir?: string;
   /** Persona configuration from agent.yaml. If omitted, Italian Craftsperson default is used. */
   persona?: Partial<import('../persona/types.js').PersonaConfig>;
+  /** Embedding provider configuration. If omitted, embeddings are disabled. */
+  embedding?: EmbeddingConfig;
 }
 
 /**
@@ -135,6 +151,10 @@ export interface AgentRuntime {
   adapterRegistry: RuntimeAdapterRegistry;
   /** Subagent dispatcher — spawn and manage child agent processes. */
   subagentDispatcher: SubagentDispatcher;
+  /** Embedding provider — generates dense vectors for hybrid search (optional). */
+  embeddingProvider?: EmbeddingProvider;
+  /** Embedding pipeline — batch and incremental embedding of vault entries (optional). */
+  embeddingPipeline?: EmbeddingPipeline;
   /** Context health monitor — tracks tool call volume and context window fill. */
   contextHealth: ContextHealthMonitor;
   /** Shutdown registry — centralized cleanup for timers, watchers, child processes. */