@soleri/core 9.5.0 → 9.6.0

package/src/runtime/session-briefing.test.ts

@@ -17,6 +17,14 @@ function makeRuntime(overrides?: {
     toolsUsed: string[];
     filesModified: string[];
   }>;
+  memories?: Array<{
+    id?: string;
+    createdAt: number;
+    projectPath?: string;
+    summary?: string;
+    context?: string;
+    type?: string;
+  }>;
   plans?: Array<{
     id: string;
     status: string;
@@ -45,6 +53,7 @@ function makeRuntime(overrides?: {
     vault: {
       stats: () => o.vaultStats ?? { totalEntries: 50, byType: { playbook: 5 } },
       getRecent: (_n: number) => o.recentEntries ?? [],
+      listMemories: () => o.memories ?? [],
     },
     curator: {
       healthAudit: () => ({
@@ -95,11 +104,34 @@ describe('session-briefing', () => {
       expect(data.sections.find((s) => s.label === 'Welcome')).toBeUndefined();
     });
 
-    it('includes Last session section', async () => {
+    it('includes Last session from cross-project memories when fresh', async () => {
+      const runtime = makeRuntime({
+        memories: [
+          {
+            id: 'mem-1',
+            createdAt: Date.now() - 600_000, // 10 min ago (ms)
+            projectPath: '/Users/me/projects/other-app',
+            summary: 'Fixed KPI card layout in the dashboard',
+            type: 'session',
+          },
+        ],
+      });
+      const ops = captureOps(createSessionBriefingOps(runtime));
+      const res = await executeOp(ops, 'session_briefing', {});
+
+      const data = res.data as { sections: Array<{ label: string; content: string }> };
+      const session = data.sections.find((s) => s.label === 'Last session');
+      expect(session).toBeDefined();
+      expect(session!.content).toContain('other-app');
+      expect(session!.content).toContain('Fixed KPI card layout');
+    });
+
+    it('falls back to brain sessions when no fresh memories exist', async () => {
       const runtime = makeRuntime({
+        memories: [], // no memories
         sessions: [
           {
-            endedAt: new Date(Date.now() - 3600000).toISOString(),
+            endedAt: new Date(Date.now() - 3600_000).toISOString(), // 1h ago
             domain: 'frontend',
             context: 'Refactored button component',
             toolsUsed: ['vault_search', 'brain_recommend'],
@@ -117,6 +149,63 @@ describe('session-briefing', () => {
       expect(session!.content).toContain('Refactored button component');
     });
 
+    it('skips Last session when all sessions are stale', async () => {
+      const staleTs = Date.now() - 72 * 3600_000; // 72h ago — beyond default 48h
+      const runtime = makeRuntime({
+        memories: [
+          {
+            id: 'mem-old',
+            createdAt: staleTs,
+            projectPath: '/old-project',
+            summary: 'Ancient session',
+            type: 'session',
+          },
+        ],
+        sessions: [
+          {
+            endedAt: new Date(staleTs).toISOString(),
+            domain: 'old',
+            context: 'Ancient brain session',
+            toolsUsed: [],
+            filesModified: [],
+          },
+        ],
+      });
+      const ops = captureOps(createSessionBriefingOps(runtime));
+      const res = await executeOp(ops, 'session_briefing', {});
+
+      const data = res.data as { sections: Array<{ label: string; content: string }> };
+      const session = data.sections.find((s) => s.label === 'Last session');
+      expect(session).toBeUndefined();
+    });
+
+    it('respects custom recencyHours parameter', async () => {
+      const runtime = makeRuntime({
+        memories: [
+          {
+            id: 'mem-3h',
+            createdAt: Date.now() - 3 * 3600_000, // 3h ago
+            projectPath: '/recent-project',
+            summary: 'Recent work',
+            type: 'session',
+          },
+        ],
+      });
+      const ops = captureOps(createSessionBriefingOps(runtime));
+
+      // With 1h window — should skip
+      const narrow = await executeOp(ops, 'session_briefing', { recencyHours: 1 });
+      const narrowData = narrow.data as { sections: Array<{ label: string }> };
+      expect(narrowData.sections.find((s) => s.label === 'Last session')).toBeUndefined();
+
+      // With 4h window — should include
+      const wide = await executeOp(ops, 'session_briefing', { recencyHours: 4 });
+      const wideData = wide.data as { sections: Array<{ label: string; content: string }> };
+      const session = wideData.sections.find((s) => s.label === 'Last session');
+      expect(session).toBeDefined();
+      expect(session!.content).toContain('Recent work');
+    });
+
     it('includes Active plans section', async () => {
       const runtime = makeRuntime({
         plans: [
@@ -234,6 +323,9 @@ describe('session-briefing', () => {
           getRecent: () => {
             throw new Error('no vault');
           },
+          listMemories: () => {
+            throw new Error('no vault');
+          },
         },
         curator: {
           healthAudit: () => {

package/src/runtime/session-briefing.ts

@@ -57,22 +57,58 @@ export function createSessionBriefingOps(runtime: AgentRuntime): OpDefinition[]
           // Vault stats unavailable — skip
         }
 
-        // 1. Last session
+        // 1. Last session — cross-project, with staleness threshold
         try {
-          const sessions = brainIntelligence.listSessions({ limit: 1, active: false });
-          dataPoints += sessions.length;
-          if (sessions.length > 0) {
-            const last = sessions[0];
-            const ago = formatTimeAgo(last.endedAt ? new Date(last.endedAt).getTime() : Date.now());
-            const domain = last.domain ? ` [${last.domain}]` : '';
-            const context = last.context ? `: ${last.context.slice(0, 80)}` : '';
-            const tools = last.toolsUsed.length > 0 ? `, used ${last.toolsUsed.length} tools` : '';
-            const files =
-              last.filesModified.length > 0 ? `, modified ${last.filesModified.length} files` : '';
+          const recencyMs = (params.recencyHours as number) * 3600_000;
+          const cutoff = Date.now() - recencyMs;
+
+          // Try cross-project memories first (most recent work, any project)
+          const recentMemories = vault.listMemories({ type: 'session', limit: 3 });
+          const freshMemory = recentMemories.find((m) => {
+            const ts = m.createdAt > 1e12 ? m.createdAt : m.createdAt * 1000;
+            return ts > cutoff;
+          });
+
+          if (freshMemory) {
+            const ts =
+              freshMemory.createdAt > 1e12 ? freshMemory.createdAt : freshMemory.createdAt * 1000;
+            const ago = formatTimeAgo(ts);
+            const project = freshMemory.projectPath
+              ? ` [${freshMemory.projectPath.split('/').pop()}]`
+              : '';
+            const summary = freshMemory.summary
+              ? `: ${freshMemory.summary.slice(0, 100)}`
+              : freshMemory.context
+                ? `: ${freshMemory.context.slice(0, 100)}`
+                : '';
+            dataPoints += recentMemories.length;
             sections.push({
               label: 'Last session',
-              content: `(${ago})${domain}${context}${tools}${files}`,
+              content: `(${ago})${project}${summary}`,
             });
+          } else {
+            // Fall back to brain sessions (same-project only) if no fresh memory
+            const sessions = brainIntelligence.listSessions({ limit: 1, active: false });
+            dataPoints += sessions.length;
+            if (sessions.length > 0) {
+              const last = sessions[0];
+              const endTs = last.endedAt ? new Date(last.endedAt).getTime() : 0;
+              if (endTs > cutoff) {
+                const ago = formatTimeAgo(endTs);
+                const domain = last.domain ? ` [${last.domain}]` : '';
+                const context = last.context ? `: ${last.context.slice(0, 80)}` : '';
+                const tools =
+                  last.toolsUsed.length > 0 ? `, used ${last.toolsUsed.length} tools` : '';
+                const files =
+                  last.filesModified.length > 0
+                    ? `, modified ${last.filesModified.length} files`
+                    : '';
+                sections.push({
+                  label: 'Last session',
+                  content: `(${ago})${domain}${context}${tools}${files}`,
+                });
+              }
+            }
           }
         } catch {
           // Session data unavailable — skip

package/src/runtime/types.ts

@@ -37,6 +37,8 @@ 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.
@@ -129,6 +131,10 @@ 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. */

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';