@soleri/core 9.4.0 → 9.6.0

package/src/runtime/types.ts

@@ -36,6 +36,9 @@ import type { PipelineRunner } from '../queue/pipeline-runner.js';
 import type { OperatorProfileStore } from '../operator/operator-profile.js';
 import type { OperatorContextStore } from '../operator/operator-context-store.js';
 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';
 
 /**
  * Configuration for creating an agent runtime.
@@ -128,10 +131,16 @@ export interface AgentRuntime {
   persona: import('../persona/types.js').PersonaConfig;
   /** Generated persona system instructions for LLM context. */
   personaInstructions: import('../persona/types.js').PersonaSystemInstructions;
+  /** Runtime adapter registry — dispatch work to different AI CLIs. */
+  adapterRegistry: RuntimeAdapterRegistry;
+  /** Subagent dispatcher — spawn and manage child agent processes. */
+  subagentDispatcher: SubagentDispatcher;
   /** Context health monitor — tracks tool call volume and context window fill. */
   contextHealth: ContextHealthMonitor;
+  /** Shutdown registry — centralized cleanup for timers, watchers, child processes. */
+  shutdownRegistry: ShutdownRegistry;
   /** Timestamp (ms since epoch) when this runtime was created. */
   createdAt: number;
-  /** Close the vault database connection. Call on shutdown. */
+  /** Close all runtime resources (vault, timers, watchers). Call on shutdown. */
   close(): void;
 }

package/src/subagent/concurrency-manager.ts

@@ -0,0 +1,89 @@
+/**
+ * Per-agent-type semaphore for controlling concurrent subagent runs.
+ *
+ * Pure promise-based — zero external deps. FIFO ordering guarantees
+ * the first waiter is the first to acquire a slot when one frees up.
+ */
+
+interface TypeState {
+  active: number;
+  waiters: Array<() => void>;
+}
+
+const DEFAULT_MAX_CONCURRENT = 3;
+
+export class ConcurrencyManager {
+  private state: Map<string, TypeState> = new Map();
+
+  /**
+   * Acquire a concurrency slot for the given adapter type.
+   * Resolves immediately if a slot is available, otherwise queues
+   * and resolves when a slot frees up (FIFO).
+   */
+  async acquire(type: string, maxConcurrent: number = DEFAULT_MAX_CONCURRENT): Promise<void> {
+    const entry = this.getOrCreate(type);
+
+    if (entry.active < maxConcurrent) {
+      entry.active++;
+      return;
+    }
+
+    // At capacity — park until a slot opens.
+    return new Promise<void>((resolve) => {
+      entry.waiters.push(() => {
+        entry.active++;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Release a concurrency slot for the given adapter type.
+   * If waiters exist, the first one (FIFO) is unblocked.
+   * No-op if the type is not tracked.
+   */
+  release(type: string): void {
+    const entry = this.state.get(type);
+    if (!entry) return;
+
+    entry.active = Math.max(0, entry.active - 1);
+
+    if (entry.waiters.length > 0) {
+      const next = entry.waiters.shift()!;
+      next();
+    }
+  }
+
+  /** Return the number of active slots for a type (0 if untracked). */
+  getActive(type: string): number {
+    return this.state.get(type)?.active ?? 0;
+  }
+
+  /** Return the number of waiters queued for a type (0 if untracked). */
+  getWaiting(type: string): number {
+    return this.state.get(type)?.waiters.length ?? 0;
+  }
+
+  /** Clear all state, resolving any pending waiters immediately. */
+  reset(): void {
+    for (const entry of this.state.values()) {
+      for (const waiter of entry.waiters) {
+        waiter();
+      }
+      entry.waiters.length = 0;
+      entry.active = 0;
+    }
+    this.state.clear();
+  }
+
+  // ── internal ──────────────────────────────────────────────────────
+
+  private getOrCreate(type: string): TypeState {
+    let entry = this.state.get(type);
+    if (!entry) {
+      entry = { active: 0, waiters: [] };
+      this.state.set(type, entry);
+    }
+    return entry;
+  }
+}

package/src/subagent/dispatcher.ts

@@ -0,0 +1,326 @@
+/**
+ * SubagentDispatcher — the core orchestrator for subagent execution.
+ *
+ * Composes: TaskCheckout, WorkspaceResolver, ConcurrencyManager,
+ * OrphanReaper, and RuntimeAdapterRegistry to dispatch tasks to
+ * child agent processes.
+ */
+
+import type { RuntimeAdapterRegistry } from '../adapters/registry.js';
+import type {
+  SubagentTask,
+  SubagentResult,
+  SubagentStatus,
+  DispatchOptions,
+  AggregatedResult,
+} from './types.js';
+import { TaskCheckout } from './task-checkout.js';
+import { WorkspaceResolver } from './workspace-resolver.js';
+import { ConcurrencyManager } from './concurrency-manager.js';
+import { OrphanReaper } from './orphan-reaper.js';
+import { aggregate } from './result-aggregator.js';
+
+const DEFAULT_TIMEOUT = 300_000; // 5 minutes
+const DEFAULT_MAX_CONCURRENT = 3;
+
+export interface SubagentDispatcherConfig {
+  /** RuntimeAdapterRegistry for looking up adapters by type */
+  adapterRegistry: RuntimeAdapterRegistry;
+  /** Base directory for git worktree isolation */
+  baseDir?: string;
+}
+
+export class SubagentDispatcher {
+  private readonly checkout = new TaskCheckout();
+  private readonly workspace: WorkspaceResolver;
+  private readonly concurrency = new ConcurrencyManager();
+  private readonly reaper: OrphanReaper;
+  private readonly adapterRegistry: RuntimeAdapterRegistry;
+
+  constructor(config: SubagentDispatcherConfig) {
+    this.adapterRegistry = config.adapterRegistry;
+    this.workspace = new WorkspaceResolver(config.baseDir ?? process.cwd());
+    this.reaper = new OrphanReaper((taskId) => {
+      // On orphan: release the task claim and clean up workspace
+      this.checkout.release(taskId);
+      this.workspace.cleanup(taskId);
+    });
+  }
+
+  /**
+   * Dispatch one or more tasks to subagents.
+   *
+   * Tasks run in parallel by default (controlled by options.parallel).
+   * Each task goes through: claim → resolve workspace → acquire slot →
+   * execute via adapter → collect result.
+   */
+  async dispatch(tasks: SubagentTask[], options: DispatchOptions = {}): Promise<AggregatedResult> {
+    const {
+      parallel = true,
+      maxConcurrent = DEFAULT_MAX_CONCURRENT,
+      worktreeIsolation = false,
+      timeout = DEFAULT_TIMEOUT,
+      onTaskUpdate,
+    } = options;
+
+    if (tasks.length === 0) {
+      return aggregate([]);
+    }
+
+    // Resolve dependency order
+    const ordered = this.resolveDependencies(tasks);
+
+    if (parallel) {
+      // Run independent tasks in parallel, respecting dependencies
+      const results = await this.dispatchParallel(ordered, {
+        maxConcurrent,
+        worktreeIsolation,
+        timeout,
+        onTaskUpdate,
+      });
+      return aggregate(results);
+    }
+
+    // Sequential dispatch — await in loop is intentional (tasks must run one at a time)
+    const results: SubagentResult[] = [];
+    for (const task of ordered) {
+      // eslint-disable-line no-await-in-loop
+      onTaskUpdate?.(task.taskId, 'running');
+      const result = await this.executeTask(task, worktreeIsolation, timeout);
+      results.push(result);
+      onTaskUpdate?.(task.taskId, result.status);
+
+      // Stop on failure in sequential mode
+      if (result.exitCode !== 0) break;
+    }
+
+    return aggregate(results);
+  }
+
+  /** Clean up all resources (worktrees, claims, concurrency) */
+  cleanup(): void {
+    this.workspace.cleanupAll();
+    this.checkout.releaseAll();
+    this.concurrency.reset();
+    this.reaper.clear();
+  }
+
+  /** Run orphan detection and cleanup */
+  reapOrphans(): SubagentResult[] {
+    const orphaned = this.reaper.reap();
+    return orphaned.map((p) => ({
+      taskId: p.taskId,
+      status: 'orphaned' as const,
+      exitCode: 1,
+      error: `Process ${p.pid} died unexpectedly`,
+      durationMs: Date.now() - p.registeredAt,
+      pid: p.pid,
+    }));
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────
+
+  private async dispatchParallel(
+    tasks: SubagentTask[],
+    opts: {
+      maxConcurrent: number;
+      worktreeIsolation: boolean;
+      timeout: number;
+      onTaskUpdate?: (taskId: string, status: SubagentStatus) => void;
+    },
+  ): Promise<SubagentResult[]> {
+    const results = new Map<string, SubagentResult>();
+    const pending = new Map<string, SubagentTask>();
+    const completed = new Set<string>();
+
+    // Initialize all tasks as pending
+    for (const task of tasks) {
+      pending.set(task.taskId, task);
+    }
+
+    // Process in waves until all done
+    while (pending.size > 0) {
+      // Find tasks whose dependencies are all completed
+      const ready: SubagentTask[] = [];
+      for (const [_id, task] of pending) {
+        const deps = task.dependencies ?? [];
+        if (deps.every((d) => completed.has(d))) {
+          ready.push(task);
+        }
+      }
+
+      if (ready.length === 0 && pending.size > 0) {
+        // Deadlock — remaining tasks have unmet dependencies
+        for (const [deadId, task] of pending) {
+          results.set(deadId, {
+            taskId: deadId,
+            status: 'failed',
+            exitCode: 1,
+            error: `Unresolvable dependencies: ${(task.dependencies ?? []).filter((d) => !completed.has(d)).join(', ')}`,
+            durationMs: 0,
+          });
+        }
+        break;
+      }
+
+      // Dispatch ready tasks in parallel with concurrency control
+      // eslint-disable-next-line no-await-in-loop -- waves must complete before next wave
+      const waveResults = await Promise.allSettled(
+        ready.map(async (task) => {
+          opts.onTaskUpdate?.(task.taskId, 'running');
+          await this.concurrency.acquire(task.runtime ?? 'default', opts.maxConcurrent);
+          try {
+            return await this.executeTask(
+              task,
+              opts.worktreeIsolation,
+              task.timeout ?? opts.timeout,
+            );
+          } finally {
+            this.concurrency.release(task.runtime ?? 'default');
+          }
+        }),
+      );
+
+      // Collect results
+      for (let i = 0; i < ready.length; i++) {
+        const task = ready[i];
+        const settled = waveResults[i];
+        const result: SubagentResult =
+          settled.status === 'fulfilled'
+            ? settled.value
+            : {
+                taskId: task.taskId,
+                status: 'failed',
+                exitCode: 1,
+                error: settled.reason?.message ?? 'Unknown error',
+                durationMs: 0,
+              };
+
+        results.set(task.taskId, result);
+        completed.add(task.taskId);
+        pending.delete(task.taskId);
+        opts.onTaskUpdate?.(task.taskId, result.status);
+      }
+    }
+
+    // Return in original task order
+    return tasks.map((t) => results.get(t.taskId)!);
+  }
+
+  private async executeTask(
+    task: SubagentTask,
+    worktreeIsolation: boolean,
+    timeout: number,
+  ): Promise<SubagentResult> {
+    const startTime = Date.now();
+
+    // 1. Claim the task
+    const claimed = this.checkout.claim(task.taskId, 'dispatcher');
+    if (!claimed) {
+      return {
+        taskId: task.taskId,
+        status: 'failed',
+        exitCode: 1,
+        error: 'Task already claimed by another process',
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    // 2. Resolve workspace
+    const workspace = this.workspace.resolve(task.taskId, task.workspace, worktreeIsolation);
+
+    // 3. Get adapter
+    const adapterType = task.runtime ?? this.getDefaultAdapterType();
+    let adapter;
+    try {
+      adapter = this.adapterRegistry.get(adapterType);
+    } catch {
+      this.checkout.release(task.taskId);
+      return {
+        taskId: task.taskId,
+        status: 'failed',
+        exitCode: 1,
+        error: `Adapter '${adapterType}' not found in registry`,
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    // 4. Execute with timeout
+    try {
+      const resultPromise = adapter.execute({
+        runId: `subagent-${task.taskId}-${Date.now()}`,
+        prompt: task.prompt,
+        workspace,
+        config: { ...task.config, timeout },
+      });
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error('Task timed out')), timeout);
+      });
+
+      const adapterResult = await Promise.race([resultPromise, timeoutPromise]);
+
+      return {
+        taskId: task.taskId,
+        status: adapterResult.exitCode === 0 ? 'completed' : 'failed',
+        exitCode: adapterResult.exitCode,
+        summary: adapterResult.summary,
+        usage: adapterResult.usage,
+        sessionState: adapterResult.sessionState,
+        durationMs: Date.now() - startTime,
+      };
+    } catch (err) {
+      return {
+        taskId: task.taskId,
+        status: 'failed',
+        exitCode: 1,
+        error: err instanceof Error ? err.message : String(err),
+        durationMs: Date.now() - startTime,
+      };
+    } finally {
+      // Cleanup
+      this.checkout.release(task.taskId);
+      if (worktreeIsolation) {
+        this.workspace.cleanup(task.taskId);
+      }
+    }
+  }
+
+  /** Topological sort by dependencies (stable — preserves input order for equal deps) */
+  private resolveDependencies(tasks: SubagentTask[]): SubagentTask[] {
+    const taskMap = new Map(tasks.map((t) => [t.taskId, t]));
+    const sorted: SubagentTask[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+
+    const visit = (id: string) => {
+      if (visited.has(id)) return;
+      if (visiting.has(id)) return; // cycle — skip
+      visiting.add(id);
+
+      const task = taskMap.get(id);
+      if (task) {
+        for (const dep of task.dependencies ?? []) {
+          visit(dep);
+        }
+        visited.add(id);
+        visiting.delete(id);
+        sorted.push(task);
+      }
+    };
+
+    for (const task of tasks) {
+      visit(task.taskId);
+    }
+
+    return sorted;
+  }
+
+  private getDefaultAdapterType(): string {
+    try {
+      return this.adapterRegistry.getDefault().type;
+    } catch {
+      return 'claude-code';
+    }
+  }
+}

package/src/subagent/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Subagent runtime engine — spawn, manage, and aggregate results
+ * from child agent processes.
+ *
+ * @module subagent
+ */
+
+// Types
+export type {
+  SubagentTask,
+  SubagentStatus,
+  SubagentResult,
+  DispatchOptions,
+  AggregatedResult,
+  ClaimInfo,
+  WorktreeInfo,
+  TrackedProcess,
+} from './types.js';
+
+// Components
+export { TaskCheckout } from './task-checkout.js';
+export { WorkspaceResolver } from './workspace-resolver.js';
+export { ConcurrencyManager } from './concurrency-manager.js';
+export { OrphanReaper } from './orphan-reaper.js';
+export { aggregate as aggregateResults } from './result-aggregator.js';
+
+// Dispatcher
+export { SubagentDispatcher } from './dispatcher.js';

package/src/subagent/orphan-reaper.ts

@@ -0,0 +1,82 @@
+/**
+ * OrphanReaper — tracks spawned child processes and detects dead/orphaned ones.
+ *
+ * Uses `process.kill(pid, 0)` (signal 0) as an existence check:
+ * - No error → process is alive
+ * - ESRCH → process is dead (reap it)
+ * - EPERM → process is alive but we lack permission to signal it
+ */
+
+import type { TrackedProcess } from './types.js';
+
+export class OrphanReaper {
+  private readonly tracked = new Map<number, TrackedProcess>();
+  private readonly onOrphan?: (taskId: string, pid: number) => void;
+
+  constructor(onOrphan?: (taskId: string, pid: number) => void) {
+    this.onOrphan = onOrphan;
+  }
+
+  /** Start tracking a process. */
+  register(pid: number, taskId: string): void {
+    this.tracked.set(pid, { pid, taskId, registeredAt: Date.now() });
+  }
+
+  /** Stop tracking a process (called on normal completion). */
+  unregister(pid: number): void {
+    this.tracked.delete(pid);
+  }
+
+  /**
+   * Check each tracked PID for liveness. Dead processes are removed from
+   * tracking, the onOrphan callback is invoked, and they are returned.
+   */
+  reap(): TrackedProcess[] {
+    const reaped: TrackedProcess[] = [];
+
+    for (const [pid, entry] of this.tracked) {
+      if (!this.isAlive(pid)) {
+        this.tracked.delete(pid);
+        this.onOrphan?.(entry.taskId, pid);
+        reaped.push(entry);
+      }
+    }
+
+    return reaped;
+  }
+
+  /** Return all currently tracked processes. */
+  listTracked(): TrackedProcess[] {
+    return [...this.tracked.values()];
+  }
+
+  /** Check if a PID is currently tracked. */
+  isTracked(pid: number): boolean {
+    return this.tracked.has(pid);
+  }
+
+  /** Clear all tracked processes without killing them. */
+  clear(): void {
+    this.tracked.clear();
+  }
+
+  // ── internals ──────────────────────────────────────────────────────
+
+  /**
+   * Signal-0 existence check.
+   * - No error → alive
+   * - EPERM   → alive (exists but we can't signal it)
+   * - ESRCH   → dead
+   */
+  private isAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err: unknown) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'EPERM') return true;
+      // ESRCH or any other error → treat as dead
+      return false;
+    }
+  }
+}

package/src/subagent/result-aggregator.ts

@@ -0,0 +1,66 @@
+/**
+ * Result aggregator — merges results from multiple parallel subagent
+ * executions into a single summary.
+ */
+
+import type { AggregatedResult, SubagentResult } from './types.js';
+
+export function aggregate(results: SubagentResult[]): AggregatedResult {
+  if (results.length === 0) {
+    return {
+      status: 'all-passed',
+      totalTasks: 0,
+      completed: 0,
+      failed: 0,
+      totalUsage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+      filesChanged: [],
+      combinedSummary: '',
+      durationMs: 0,
+      results: [],
+    };
+  }
+
+  const completed = results.filter((r) => r.exitCode === 0).length;
+  const failed = results.length - completed;
+
+  const status: AggregatedResult['status'] =
+    failed === 0 ? 'all-passed' : completed === 0 ? 'all-failed' : 'partial';
+
+  const totalUsage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+  };
+  for (const r of results) {
+    totalUsage.inputTokens += r.usage?.inputTokens ?? 0;
+    totalUsage.outputTokens += r.usage?.outputTokens ?? 0;
+    totalUsage.totalTokens += r.usage?.totalTokens ?? 0;
+  }
+
+  const fileSet = new Set<string>();
+  for (const r of results) {
+    if (r.filesChanged) {
+      for (const f of r.filesChanged) fileSet.add(f);
+    }
+  }
+
+  const combinedSummary = results
+    .filter((r) => r.summary)
+    .map((r) => `[${r.taskId}] ${r.summary}`)
+    .join('\n');
+
+  // Parallel wall-clock: max of all durations
+  const durationMs = Math.max(...results.map((r) => r.durationMs));
+
+  return {
+    status,
+    totalTasks: results.length,
+    completed,
+    failed,
+    totalUsage,
+    filesChanged: [...fileSet],
+    combinedSummary,
+    durationMs,
+    results,
+  };
+}

package/src/subagent/task-checkout.ts

@@ -0,0 +1,60 @@
+/**
+ * Atomic task claim system — prevents two subagents from working the same task.
+ *
+ * Pure in-memory Map backing store. No async, no external deps.
+ */
+
+import type { ClaimInfo } from './types.js';
+
+export class TaskCheckout {
+  private readonly claims = new Map<string, ClaimInfo>();
+
+  /**
+   * Attempt to claim a task for a claimer.
+   * Returns true if the claim succeeds (or the same claimer already holds it).
+   * Returns false if the task is already claimed by a different claimer.
+   */
+  claim(taskId: string, claimerId: string): boolean {
+    const existing = this.claims.get(taskId);
+    if (existing) {
+      return existing.claimerId === claimerId;
+    }
+    this.claims.set(taskId, { taskId, claimerId, claimedAt: Date.now() });
+    return true;
+  }
+
+  /**
+   * Release a claimed task. Returns true if released, false if not claimed.
+   */
+  release(taskId: string): boolean {
+    return this.claims.delete(taskId);
+  }
+
+  /**
+   * Get claim info for a task, or undefined if unclaimed.
+   */
+  getClaimer(taskId: string): ClaimInfo | undefined {
+    return this.claims.get(taskId);
+  }
+
+  /**
+   * List all active claims.
+   */
+  listClaimed(): ClaimInfo[] {
+    return [...this.claims.values()];
+  }
+
+  /**
+   * Check whether a task is available (unclaimed).
+   */
+  isAvailable(taskId: string): boolean {
+    return !this.claims.has(taskId);
+  }
+
+  /**
+   * Clear all claims. Useful for cleanup between dispatch rounds.
+   */
+  releaseAll(): void {
+    this.claims.clear();
+  }
+}