@soleri/core 9.5.0 → 9.6.0

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();
+  }
+}

package/src/subagent/types.ts

@@ -0,0 +1,138 @@
+/**
+ * Subagent runtime engine — types for spawning, managing, and aggregating
+ * results from child agent processes.
+ *
+ * The SubagentDispatcher composes: TaskCheckout, WorkspaceResolver,
+ * ConcurrencyManager, OrphanReaper, and RuntimeAdapterRegistry.
+ */
+
+import type { AdapterSessionState, AdapterTokenUsage } from '../adapters/types.js';
+
+// ─── Task ───────────────────────────────────────────────────────────
+
+/** A task to be dispatched to a subagent */
+export interface SubagentTask {
+  /** Unique task identifier */
+  taskId: string;
+  /** The prompt or task description for the subagent */
+  prompt: string;
+  /** Working directory for execution */
+  workspace: string;
+  /** Runtime adapter type (e.g., 'claude-code', 'codex'). Falls back to registry default. */
+  runtime?: string;
+  /** Task IDs this task depends on (must complete first) */
+  dependencies?: string[];
+  /** Timeout in milliseconds. Default: 300_000 (5 min) */
+  timeout?: number;
+  /** Additional context to pass to the adapter */
+  config?: Record<string, unknown>;
+}
+
+// ─── Status ─────────────────────────────────────────────────────────
+
+/** Lifecycle status of a subagent task */
+export type SubagentStatus = 'queued' | 'claimed' | 'running' | 'completed' | 'failed' | 'orphaned';
+
+// ─── Result ─────────────────────────────────────────────────────────
+
+/** Result from a single subagent execution */
+export interface SubagentResult {
+  /** Task ID this result belongs to */
+  taskId: string;
+  /** Final status */
+  status: SubagentStatus;
+  /** Exit code from the adapter (0 = success) */
+  exitCode: number;
+  /** Human-readable summary of what the subagent did */
+  summary?: string;
+  /** Token usage */
+  usage?: AdapterTokenUsage;
+  /** Session state for potential resume */
+  sessionState?: AdapterSessionState;
+  /** Files changed by this subagent */
+  filesChanged?: string[];
+  /** Error message if failed */
+  error?: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** PID of the child process (if spawned) */
+  pid?: number;
+}
+
+// ─── Dispatch Options ───────────────────────────────────────────────
+
+/** Options controlling how tasks are dispatched */
+export interface DispatchOptions {
+  /** Run tasks in parallel (default: true) */
+  parallel?: boolean;
+  /** Max concurrent subagents (default: 3) */
+  maxConcurrent?: number;
+  /** Isolate each task in a git worktree (default: false) */
+  worktreeIsolation?: boolean;
+  /** Global timeout per task in ms (default: 300_000) */
+  timeout?: number;
+  /** Callback for per-task status updates */
+  onTaskUpdate?: (taskId: string, status: SubagentStatus) => void;
+}
+
+// ─── Aggregated Result ──────────────────────────────────────────────
+
+/** Aggregated result from multiple subagent executions */
+export interface AggregatedResult {
+  /** Overall status */
+  status: 'all-passed' | 'partial' | 'all-failed';
+  /** Total tasks dispatched */
+  totalTasks: number;
+  /** Count of completed tasks */
+  completed: number;
+  /** Count of failed tasks */
+  failed: number;
+  /** Sum of all token usage */
+  totalUsage: AdapterTokenUsage;
+  /** Deduplicated list of all files changed */
+  filesChanged: string[];
+  /** Combined summary from all tasks */
+  combinedSummary: string;
+  /** Total duration in milliseconds */
+  durationMs: number;
+  /** Per-task results */
+  results: SubagentResult[];
+}
+
+// ─── Claim Info ─────────────────────────────────────────────────────
+
+/** Information about a task claim */
+export interface ClaimInfo {
+  /** Task ID */
+  taskId: string;
+  /** Agent/process that claimed this task */
+  claimerId: string;
+  /** When the claim was made */
+  claimedAt: number;
+}
+
+// ─── Worktree Info ──────────────────────────────────────────────────
+
+/** Information about an active git worktree */
+export interface WorktreeInfo {
+  /** Task ID this worktree is for */
+  taskId: string;
+  /** Absolute path to the worktree */
+  path: string;
+  /** Branch name (if created) */
+  branch?: string;
+  /** When the worktree was created */
+  createdAt: number;
+}
+
+// ─── Tracked Process ────────────────────────────────────────────────
+
+/** A tracked child process for orphan detection */
+export interface TrackedProcess {
+  /** Process ID */
+  pid: number;
+  /** Task ID this process is executing */
+  taskId: string;
+  /** When the process was registered */
+  registeredAt: number;
+}

package/src/subagent/workspace-resolver.ts

@@ -0,0 +1,117 @@
+/**
+ * WorkspaceResolver — Git worktree isolation for subagent tasks.
+ *
+ * When isolation is requested, creates a dedicated git worktree per task
+ * at `<baseDir>/.soleri/worktrees/<taskId>/`. Falls back gracefully to the
+ * original workspace if git worktree creation fails.
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { WorktreeInfo } from './types.js';
+
+const EXEC_OPTS = { encoding: 'utf-8' as const, timeout: 30_000 };
+
+export class WorkspaceResolver {
+  private readonly baseDir: string;
+  private readonly worktrees = new Map<string, WorktreeInfo>();
+
+  constructor(baseDir: string) {
+    this.baseDir = baseDir;
+  }
+
+  /**
+   * Resolve a workspace path for a task.
+   *
+   * If `isolate` is true, creates a git worktree at
+   * `<baseDir>/.soleri/worktrees/<taskId>/` on branch `subagent/<taskId>`.
+   * Returns the worktree path on success, or the original `workspace` on failure.
+   *
+   * If `isolate` is false, returns `workspace` as-is.
+   */
+  resolve(taskId: string, workspace: string, isolate: boolean): string {
+    if (!isolate) {
+      return workspace;
+    }
+
+    try {
+      const worktreePath = join(this.baseDir, '.soleri', 'worktrees', taskId);
+      const branch = `subagent/${taskId}`;
+
+      // Ensure parent directory exists
+      const parentDir = join(this.baseDir, '.soleri', 'worktrees');
+      if (!existsSync(parentDir)) {
+        mkdirSync(parentDir, { recursive: true });
+      }
+
+      execSync(`git worktree add "${worktreePath}" -b "${branch}"`, {
+        ...EXEC_OPTS,
+        cwd: this.baseDir,
+      });
+
+      const info: WorktreeInfo = {
+        taskId,
+        path: worktreePath,
+        branch,
+        createdAt: Date.now(),
+      };
+      this.worktrees.set(taskId, info);
+
+      return worktreePath;
+    } catch (err) {
+      // Graceful fallback — log warning and return original workspace
+      console.warn(
+        `[WorkspaceResolver] Failed to create worktree for task "${taskId}":`,
+        err instanceof Error ? err.message : err,
+      );
+      return workspace;
+    }
+  }
+
+  /**
+   * Remove the worktree for a given task.
+   * Silently handles errors (e.g., worktree already removed).
+   */
+  cleanup(taskId: string): void {
+    const info = this.worktrees.get(taskId);
+    if (!info) {
+      return;
+    }
+
+    try {
+      execSync(`git worktree remove "${info.path}" --force`, { ...EXEC_OPTS, cwd: this.baseDir });
+    } catch {
+      // Silently ignore — worktree may already be gone
+    }
+
+    // Clean up the branch as well
+    if (info.branch) {
+      try {
+        execSync(`git branch -D "${info.branch}"`, { ...EXEC_OPTS, cwd: this.baseDir });
+      } catch {
+        // Silently ignore — branch may not exist
+      }
+    }
+
+    this.worktrees.delete(taskId);
+  }
+
+  /** Remove all active worktrees. */
+  cleanupAll(): void {
+    for (const taskId of Array.from(this.worktrees.keys())) {
+      this.cleanup(taskId);
+    }
+  }
+
+  /** Return all currently active worktrees. */
+  listActive(): WorktreeInfo[] {
+    return [...this.worktrees.values()];
+  }
+
+  /** Check whether a worktree exists for the given task. */
+  isActive(taskId: string): boolean {
+    return this.worktrees.has(taskId);
+  }
+}

package/src/vault/vault-scaling.test.ts

@@ -10,6 +10,7 @@ import { Vault } from './vault.js';
 import { Brain } from '../brain/brain.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 
+const isCI = !!process.env.CI;
 const DOMAINS = ['design', 'a11y', 'performance', 'security', 'architecture', 'testing', 'ux'];
 const TYPES: IntelligenceEntry['type'][] = ['pattern', 'anti-pattern', 'rule', 'playbook'];
 const SEVERITIES: IntelligenceEntry['severity'][] = ['critical', 'warning', 'suggestion'];
@@ -76,7 +77,7 @@ describe('Vault Scaling — 10K entries', () => {
       const elapsed = performance.now() - start;
 
       expect(results.length).toBeGreaterThan(0);
-      expect(elapsed).toBeLessThan(50);
+      expect(elapsed).toBeLessThan(isCI ? 500 : 50);
     }
   });
 
@@ -89,7 +90,7 @@ describe('Vault Scaling — 10K entries', () => {
     const elapsed = performance.now() - start;
 
     expect(results.length).toBeGreaterThan(0);
-    expect(elapsed).toBeLessThan(50);
+    expect(elapsed).toBeLessThan(isCI ? 500 : 50);
   });
 
   test('list with filters under 200ms at 10K', () => {

package/vitest.config.ts

@@ -11,6 +11,8 @@ export default defineConfig({
       provider: 'v8',
       include: ['src/**/*.ts'],
       exclude: ['src/**/*.test.ts', 'src/__tests__/**', 'src/index.ts'],
+      reporter: ['text', 'json-summary'],
+      reportOnFailure: true,
     },
   },
 });

package/src/hooks/index.ts

@@ -1,6 +0,0 @@
-export {
-  scoreCandidateForConversion,
-  type CandidateDimensions,
-  type CandidateScore,
-  type DimensionLevel,
-} from './candidate-scorer.js';