@soleri/core 9.5.0 → 9.6.0

package/src/__tests__/subagent/workspace-resolver.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn().mockReturnValue(false),
+  mkdirSync: vi.fn(),
+}));
+
+import { WorkspaceResolver } from '../../subagent/workspace-resolver.js';
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+
+/** Normalize path separators to forward slashes for cross-platform assertions. */
+const norm = (p: string): string => p.replace(/\\/g, '/');
+
+describe('WorkspaceResolver', () => {
+  let resolver: WorkspaceResolver;
+  const baseDir = '/projects/test-repo';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    resolver = new WorkspaceResolver(baseDir);
+  });
+
+  it('resolve() returns original workspace when isolate=false', () => {
+    const result = resolver.resolve('task-1', '/original/workspace', false);
+    expect(result).toBe('/original/workspace');
+    expect(execSync).not.toHaveBeenCalled();
+  });
+
+  it('resolve() creates a worktree when isolate=true', () => {
+    (execSync as ReturnType<typeof vi.fn>).mockReturnValue('');
+
+    const result = resolver.resolve('task-1', '/original/workspace', true);
+    expect(norm(result)).toBe(`${baseDir}/.soleri/worktrees/task-1`);
+    expect(execSync).toHaveBeenCalledWith(
+      expect.stringContaining('git worktree add'),
+      expect.objectContaining({ cwd: baseDir }),
+    );
+  });
+
+  it('resolve() falls back to original workspace when git fails', () => {
+    (execSync as ReturnType<typeof vi.fn>).mockImplementation(() => {
+      throw new Error('git worktree failed');
+    });
+
+    // Suppress console.warn from the fallback
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const result = resolver.resolve('task-fail', '/original/workspace', true);
+    expect(result).toBe('/original/workspace');
+    warnSpy.mockRestore();
+  });
+
+  it('cleanup() calls git worktree remove and git branch -D', () => {
+    (execSync as ReturnType<typeof vi.fn>).mockReturnValue('');
+
+    // First create a worktree
+    resolver.resolve('task-1', '/original', true);
+    vi.clearAllMocks();
+
+    // Now clean it up
+    resolver.cleanup('task-1');
+    expect(execSync).toHaveBeenCalledWith(
+      expect.stringContaining('git worktree remove'),
+      expect.objectContaining({ cwd: baseDir }),
+    );
+    expect(execSync).toHaveBeenCalledWith(
+      expect.stringContaining('git branch -D'),
+      expect.objectContaining({ cwd: baseDir }),
+    );
+  });
+
+  it('cleanup() silently handles errors', () => {
+    (execSync as ReturnType<typeof vi.fn>)
+      .mockReturnValueOnce('') // worktree add succeeds
+      .mockImplementation(() => {
+        throw new Error('worktree already removed');
+      });
+
+    resolver.resolve('task-err', '/original', true);
+
+    // Should not throw
+    expect(() => resolver.cleanup('task-err')).not.toThrow();
+  });
+
+  it('cleanup() is a no-op for unknown task IDs', () => {
+    resolver.cleanup('nonexistent');
+    expect(execSync).not.toHaveBeenCalled();
+  });
+
+  it('listActive() tracks created worktrees', () => {
+    (execSync as ReturnType<typeof vi.fn>).mockReturnValue('');
+
+    resolver.resolve('task-a', '/ws', true);
+    resolver.resolve('task-b', '/ws', true);
+
+    const active = resolver.listActive();
+    expect(active).toHaveLength(2);
+    expect(active.map((w) => w.taskId).sort()).toEqual(['task-a', 'task-b']);
+    expect(norm(active[0].path)).toContain('.soleri/worktrees/');
+    expect(active[0].branch).toContain('subagent/');
+    expect(active[0].createdAt).toBeGreaterThan(0);
+  });
+
+  it('cleanupAll() removes all worktrees', () => {
+    (execSync as ReturnType<typeof vi.fn>).mockReturnValue('');
+
+    resolver.resolve('task-a', '/ws', true);
+    resolver.resolve('task-b', '/ws', true);
+    expect(resolver.listActive()).toHaveLength(2);
+
+    resolver.cleanupAll();
+    expect(resolver.listActive()).toHaveLength(0);
+  });
+
+  it('isActive() returns correct state', () => {
+    (execSync as ReturnType<typeof vi.fn>).mockReturnValue('');
+
+    expect(resolver.isActive('task-1')).toBe(false);
+    resolver.resolve('task-1', '/ws', true);
+    expect(resolver.isActive('task-1')).toBe(true);
+  });
+
+  it('resolve() creates parent directory if it does not exist', () => {
+    (existsSync as ReturnType<typeof vi.fn>).mockReturnValue(false);
+    (execSync as ReturnType<typeof vi.fn>).mockReturnValue('');
+
+    resolver.resolve('task-mkdir', '/ws', true);
+    const calledPath = (mkdirSync as ReturnType<typeof vi.fn>).mock.calls[0][0] as string;
+    expect(norm(calledPath)).toContain('.soleri/worktrees');
+    expect((mkdirSync as ReturnType<typeof vi.fn>).mock.calls[0][1]).toEqual(
+      expect.objectContaining({ recursive: true }),
+    );
+  });
+});

package/src/adapters/claude-code-adapter.ts

@@ -0,0 +1,163 @@
+/**
+ * ClaudeCodeRuntimeAdapter — RuntimeAdapter implementation for Claude Code CLI.
+ *
+ * Thin wrapper around a dispatch function (actual child process spawning is #411).
+ * Provides environment detection, session codec, and skill sync.
+ */
+
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
+
+import type {
+  RuntimeAdapter,
+  AdapterExecutionContext,
+  AdapterExecutionResult,
+  AdapterSessionState,
+  AdapterSessionCodec,
+  AdapterEnvironmentTestResult,
+} from './types.js';
+import type { SkillEntry } from '../skills/sync-skills.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+/** Shape of Claude Code session data */
+interface ClaudeCodeSessionData {
+  sessionId: string;
+  cwd: string;
+}
+
+/** Dispatch function signature — injected via constructor */
+export type ClaudeCodeDispatchFn = (
+  prompt: string,
+  workspace: string,
+  config?: Record<string, unknown>,
+) => Promise<{
+  exitCode: number;
+  output?: string;
+  usage?: { inputTokens?: number; outputTokens?: number };
+}>;
+
+// ─── Session Codec ───────────────────────────────────────────────────
+
+const claudeCodeSessionCodec: AdapterSessionCodec = {
+  serialize(state: AdapterSessionState): string {
+    return JSON.stringify(state);
+  },
+
+  deserialize(serialized: string): AdapterSessionState {
+    return JSON.parse(serialized) as AdapterSessionState;
+  },
+
+  getDisplayId(state: AdapterSessionState): string {
+    const data = state.data as unknown as ClaudeCodeSessionData;
+    return data.sessionId ?? 'unknown';
+  },
+};
+
+// ─── Adapter ─────────────────────────────────────────────────────────
+
+export class ClaudeCodeRuntimeAdapter implements RuntimeAdapter {
+  readonly type = 'claude-code' as const;
+  readonly sessionCodec = claudeCodeSessionCodec;
+
+  private readonly dispatch: ClaudeCodeDispatchFn | undefined;
+
+  constructor(dispatch?: ClaudeCodeDispatchFn) {
+    this.dispatch = dispatch;
+  }
+
+  // ── Execute ──────────────────────────────────────────────────────
+
+  async execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+    if (!this.dispatch) {
+      return {
+        exitCode: 1,
+        summary: 'No dispatch function configured — cannot execute.',
+      };
+    }
+
+    ctx.onLog?.(`[claude-code] Executing run ${ctx.runId} in ${ctx.workspace}`);
+
+    const result = await this.dispatch(ctx.prompt, ctx.workspace, ctx.config);
+
+    const executionResult: AdapterExecutionResult = {
+      exitCode: result.exitCode,
+      provider: 'anthropic',
+      summary: result.output,
+    };
+
+    if (result.usage) {
+      executionResult.usage = {
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        totalTokens: (result.usage.inputTokens ?? 0) + (result.usage.outputTokens ?? 0),
+      };
+    }
+
+    // Propagate session state if the incoming context had one
+    if (ctx.session) {
+      executionResult.sessionState = ctx.session;
+    }
+
+    return executionResult;
+  }
+
+  // ── Environment Test ─────────────────────────────────────────────
+
+  async testEnvironment(): Promise<AdapterEnvironmentTestResult> {
+    try {
+      const cmd = platform() === 'win32' ? 'where claude' : 'which claude';
+      const cliPath = execSync(cmd, { encoding: 'utf-8', timeout: 5_000 }).trim();
+
+      // Try to get version
+      let version: string | undefined;
+      try {
+        version = execSync('claude --version', {
+          encoding: 'utf-8',
+          timeout: 5_000,
+        }).trim();
+      } catch {
+        // Version detection is optional — CLI may not support --version
+      }
+
+      return {
+        available: true,
+        version,
+        details: { path: cliPath },
+      };
+    } catch (err) {
+      return {
+        available: false,
+        error: err instanceof Error ? err.message : 'Claude CLI not found in PATH',
+      };
+    }
+  }
+
+  // ── Skill Sync ───────────────────────────────────────────────────
+
+  async syncSkills(skills: SkillEntry[]): Promise<void> {
+    if (skills.length === 0) return;
+
+    try {
+      // Dynamic import to avoid hard failure if sync-skills is unavailable
+      const { syncSkillsToClaudeCode } = await import('../skills/sync-skills.js');
+
+      // syncSkillsToClaudeCode expects directories, but we have individual
+      // SkillEntry items. Extract unique parent directories from source paths.
+      const dirs = [
+        ...new Set(
+          skills.map((s) => {
+            // sourcePath is typically <dir>/<skill-name>/SKILL.md — go up two levels
+            const parts = s.sourcePath.split('/');
+            // Remove filename and skill folder to get the skills root dir
+            return parts.slice(0, -2).join('/');
+          }),
+        ),
+      ];
+
+      syncSkillsToClaudeCode(dirs);
+    } catch {
+      // Graceful degradation — skill sync is optional
+    }
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime adapter abstraction — dispatch work to any AI CLI.
+ *
+ * @module adapters
+ */
+
+// Types
+export type {
+  RuntimeAdapter,
+  AdapterExecutionContext,
+  AdapterExecutionResult,
+  AdapterTokenUsage,
+  AdapterSessionState,
+  AdapterSessionCodec,
+  AdapterEnvironmentTestResult,
+} from './types.js';
+
+// Registry
+export { RuntimeAdapterRegistry } from './registry.js';
+
+// Built-in adapters
+export { ClaudeCodeRuntimeAdapter } from './claude-code-adapter.js';

package/src/adapters/registry.ts

@@ -0,0 +1,53 @@
+/**
+ * RuntimeAdapterRegistry — simple Map-backed registry for runtime adapters.
+ *
+ * Adapters register at engine startup. No dynamic loading.
+ */
+
+import type { RuntimeAdapter } from './types.js';
+
+export class RuntimeAdapterRegistry {
+  private readonly adapters = new Map<string, RuntimeAdapter>();
+  private defaultType: string | undefined;
+
+  /** Register an adapter. Throws if the type is already registered. */
+  register(type: string, adapter: RuntimeAdapter): void {
+    if (this.adapters.has(type)) {
+      throw new Error(`RuntimeAdapterRegistry: adapter type "${type}" is already registered.`);
+    }
+    this.adapters.set(type, adapter);
+  }
+
+  /** Get an adapter by type. Throws if not found. */
+  get(type: string): RuntimeAdapter {
+    const adapter = this.adapters.get(type);
+    if (!adapter) {
+      const available = this.list().join(', ') || '(none)';
+      throw new Error(
+        `RuntimeAdapterRegistry: unknown adapter type "${type}". Registered: ${available}`,
+      );
+    }
+    return adapter;
+  }
+
+  /** List all registered adapter type strings. */
+  list(): string[] {
+    return [...this.adapters.keys()];
+  }
+
+  /** Set the default adapter type. Throws if the type is not registered. */
+  setDefault(type: string): void {
+    if (!this.adapters.has(type)) {
+      throw new Error(`RuntimeAdapterRegistry: cannot set default to unregistered type "${type}".`);
+    }
+    this.defaultType = type;
+  }
+
+  /** Get the default adapter. Throws if no default is set. */
+  getDefault(): RuntimeAdapter {
+    if (!this.defaultType) {
+      throw new Error('RuntimeAdapterRegistry: no default adapter has been set.');
+    }
+    return this.get(this.defaultType);
+  }
+}

package/src/adapters/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Runtime adapter abstraction — dispatch work to any AI CLI.
+ *
+ * SEPARATE from enforcement HostAdapter (which translates rules).
+ * This is about executing tasks on different runtimes (Claude Code, Codex, Cursor, etc.)
+ *
+ * Inspired by Paperclip AI's ServerAdapterModule pattern.
+ */
+
+import type { SkillEntry } from '../skills/sync-skills.js';
+
+// ─── Execution Context ──────────────────────────────────────────────
+
+/** Context passed to an adapter when executing a task */
+export interface AdapterExecutionContext {
+  /** Unique run identifier */
+  runId: string;
+  /** The prompt or task description to execute */
+  prompt: string;
+  /** Working directory for execution */
+  workspace: string;
+  /** Session state from previous run (adapter-specific format) */
+  session?: AdapterSessionState;
+  /** Skills to inject into the runtime */
+  skills?: SkillEntry[];
+  /** Adapter-specific configuration overrides */
+  config?: Record<string, unknown>;
+  /** Callback for streaming log output */
+  onLog?: (message: string) => void;
+  /** Callback for metadata events (tokens used, model, etc.) */
+  onMeta?: (meta: Record<string, unknown>) => void;
+}
+
+/** Opaque session state — each adapter defines its own shape */
+export interface AdapterSessionState {
+  /** Adapter type that created this state */
+  adapterType: string;
+  /** Serialized session data (adapter-specific) */
+  data: Record<string, unknown>;
+}
+
+// ─── Execution Result ───────────────────────────────────────────────
+
+/** Result returned after adapter execution */
+export interface AdapterExecutionResult {
+  /** Exit code (0 = success) */
+  exitCode: number;
+  /** Whether execution timed out */
+  timedOut?: boolean;
+  /** Token usage */
+  usage?: AdapterTokenUsage;
+  /** Session state to persist for next run */
+  sessionState?: AdapterSessionState;
+  /** Human-readable summary of what was done */
+  summary?: string;
+  /** Structured result data */
+  resultData?: Record<string, unknown>;
+  /** Provider and model info */
+  provider?: string;
+  model?: string;
+}
+
+/** Token usage reported by the adapter */
+export interface AdapterTokenUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+
+// ─── Session Codec ──────────────────────────────────────────────────
+
+/** Per-adapter session serialization — each runtime stores different session data */
+export interface AdapterSessionCodec {
+  /** Serialize session state for persistence */
+  serialize(state: AdapterSessionState): string;
+  /** Deserialize persisted session state */
+  deserialize(serialized: string): AdapterSessionState;
+  /** Get a human-readable display ID for the session */
+  getDisplayId(state: AdapterSessionState): string;
+}
+
+// ─── Environment Test ───────────────────────────────────────────────
+
+/** Result of testing whether a runtime is available */
+export interface AdapterEnvironmentTestResult {
+  /** Whether the runtime CLI is available */
+  available: boolean;
+  /** Runtime version (if detected) */
+  version?: string;
+  /** Additional details (path, capabilities, etc.) */
+  details?: Record<string, unknown>;
+  /** Error message if not available */
+  error?: string;
+}
+
+// ─── Runtime Adapter Interface ──────────────────────────────────────
+
+/** Core adapter interface — implement this for each AI runtime */
+export interface RuntimeAdapter {
+  /** Adapter type identifier (e.g., 'claude-code', 'codex', 'cursor') */
+  readonly type: string;
+
+  /** Execute a task in this runtime */
+  execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
+
+  /** Test whether this runtime is available in the current environment */
+  testEnvironment(): Promise<AdapterEnvironmentTestResult>;
+
+  /** Optional: session codec for persisting runtime-specific session state */
+  sessionCodec?: AdapterSessionCodec;
+
+  /** Optional: sync skills into the runtime's expected format */
+  syncSkills?(skills: SkillEntry[]): Promise<void>;
+}

package/src/curator/curator.ts

@@ -5,6 +5,7 @@ import type {
   CuratorStatus,
   TagNormalizationResult,
   CanonicalTag,
+  DuplicateCandidate,
   DuplicateDetectionResult,
   Contradiction,
   ContradictionStatus,

package/src/index.ts

@@ -1,3 +1,34 @@
+// ─── Adapters ────────────────────────────────────────────────────────
+export { RuntimeAdapterRegistry } from './adapters/registry.js';
+export { ClaudeCodeRuntimeAdapter } from './adapters/claude-code-adapter.js';
+export type {
+  RuntimeAdapter,
+  AdapterExecutionContext,
+  AdapterExecutionResult,
+  AdapterTokenUsage,
+  AdapterSessionState,
+  AdapterSessionCodec,
+  AdapterEnvironmentTestResult,
+} from './adapters/types.js';
+
+// ─── Subagent ────────────────────────────────────────────────────────
+export { SubagentDispatcher } from './subagent/dispatcher.js';
+export { TaskCheckout } from './subagent/task-checkout.js';
+export { WorkspaceResolver } from './subagent/workspace-resolver.js';
+export { ConcurrencyManager } from './subagent/concurrency-manager.js';
+export { OrphanReaper } from './subagent/orphan-reaper.js';
+export { aggregate as aggregateResults } from './subagent/result-aggregator.js';
+export type {
+  SubagentTask,
+  SubagentStatus,
+  SubagentResult,
+  DispatchOptions,
+  AggregatedResult,
+  ClaimInfo,
+  WorktreeInfo,
+  TrackedProcess,
+} from './subagent/types.js';
+
 // ─── Paths ──────────────────────────────────────────────────────────
 export {
   SOLERI_HOME,
@@ -617,7 +648,13 @@ export { computeContentHash } from './vault/content-hash.js';
 export type { HashableEntry } from './vault/content-hash.js';
 
 // ─── Knowledge Packs ────────────────────────────────────────────────────
-export { PackInstaller, packManifestSchema } from './packs/index.js';
+export {
+  PackInstaller,
+  PackLifecycleManager,
+  packManifestSchema,
+  VALID_TRANSITIONS,
+} from './packs/index.js';
+export type { PackState, PackTransition } from './packs/index.js';
 export { PackLockfile, inferPackType } from './packs/index.js';
 export { resolvePack, checkNpmVersion, checkVersionCompat } from './packs/index.js';
 export type {

package/src/packs/index.ts

@@ -5,17 +5,21 @@
 export {
   packManifestSchema,
   PACK_TIERS,
+  VALID_TRANSITIONS,
   type PackManifest,
   type PackTier as ManifestPackTier,
   type PackStatus,
+  type PackState,
+  type PackTransition,
   type InstalledPack,
   type InstallResult,
   type ValidateResult,
 } from './types.js';
 
 export { PackInstaller } from './pack-installer.js';
+export { PackLifecycleManager } from './pack-lifecycle.js';
 
-export { PackLockfile, inferPackType } from './lockfile.js';
+export { PackLockfile, inferPackType, LOCKFILE_VERSION } from './lockfile.js';
 export type { LockEntry, PackType, PackSource, PackTier, LockfileData } from './lockfile.js';
 
 export { resolvePack, checkNpmVersion, checkVersionCompat } from './resolver.js';

package/src/packs/lockfile.ts

@@ -41,15 +41,25 @@ export interface LockEntry {
   soleriRange?: string;
   /** Pack tier: default (ships with engine), community (free), premium (unlocked today) */
   tier?: PackTier;
+  /** Current pack lifecycle state */
+  state?: string;
+  /** Most recent lifecycle transition */
+  lastTransition?: { from: string; to: string; timestamp: string; reason?: string };
+  /** ISO timestamp when the pack was disabled */
+  disabledAt?: string;
+  /** Error details if the pack is in an error state */
+  errorMessage?: string;
 }
 
 export type PackType = 'hooks' | 'skills' | 'knowledge' | 'domain' | 'bundle';
 export type PackSource = 'built-in' | 'local' | 'npm';
 export type PackTier = 'default' | 'community' | 'premium';
 
+export const LOCKFILE_VERSION = 2;
+
 export interface LockfileData {
   /** Lockfile format version */
-  version: 1;
+  version: number;
   /** Map of packId → lock entry */
   packs: Record<string, LockEntry>;
 }
@@ -141,18 +151,73 @@ export class PackLockfile {
     return 'sha256-' + createHash('sha256').update(content).digest('hex');
   }
 
+  /**
+   * Update lifecycle fields for a pack entry and save.
+   */
+  updateLifecycle(
+    packId: string,
+    state: string,
+    transition?: { from: string; to: string; reason?: string },
+  ): void {
+    const entry = this.data.packs[packId];
+    if (!entry) return;
+
+    entry.state = state;
+
+    if (transition) {
+      entry.lastTransition = {
+        from: transition.from,
+        to: transition.to,
+        timestamp: new Date().toISOString(),
+        reason: transition.reason,
+      };
+    }
+
+    if (state === 'disabled') {
+      entry.disabledAt = new Date().toISOString();
+    } else {
+      delete entry.disabledAt;
+    }
+
+    if (state === 'error') {
+      // errorMessage is set externally if needed; keep existing value
+    } else {
+      delete entry.errorMessage;
+    }
+
+    this.dirty = true;
+    this.save();
+  }
+
   private load(): LockfileData {
     if (!existsSync(this.filePath)) {
-      return { version: 1, packs: {} };
+      return { version: LOCKFILE_VERSION, packs: {} };
     }
     try {
       const raw = JSON.parse(readFileSync(this.filePath, 'utf-8'));
-      if (raw.version === 1 && typeof raw.packs === 'object') {
+      if (typeof raw.packs !== 'object') {
+        return { version: LOCKFILE_VERSION, packs: {} };
+      }
+
+      // Migrate v1 → v2: add lifecycle fields
+      if (raw.version === 1) {
+        for (const entry of Object.values(raw.packs) as LockEntry[]) {
+          if (!entry.state) {
+            entry.state = 'ready';
+          }
+        }
+        raw.version = LOCKFILE_VERSION;
+        // Mark dirty so the migrated data gets persisted on next save
+        this.dirty = true;
+      }
+
+      if (raw.version === LOCKFILE_VERSION) {
         return raw as LockfileData;
       }
-      return { version: 1, packs: {} };
+
+      return { version: LOCKFILE_VERSION, packs: {} };
     } catch {
-      return { version: 1, packs: {} };
+      return { version: LOCKFILE_VERSION, packs: {} };
     }
   }
 }