peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/reviewer/reviewer-service.js

@@ -0,0 +1,263 @@
+/**
+ * reviewer-service.ts — orchestrator for the G4 third-party reviewer.
+ *
+ * Flow (per AC-4.1 .. AC-4.6):
+ *   1. Load `reviewer` section from `~/.peaks/config.json` (reviewer-config).
+ *      Missing section => `{ ok: false, reason: 'no-reviewer-config' }`.
+ *   2. Pick a provider by selection mode (round-robin / hash / random).
+ *   3. Build the reviewer prompt (reviewer-prompt.md) with the slice's
+ *      context (rd/tech-doc + rd/karpathy-review.md + changed files).
+ *   4. Call the provider (ollama / anthropic / openai).
+ *   5. Validate the response against ReviewerEnvelope (zod-equivalent
+ *      manual guard; JSON Schema is the source of truth at
+ *      `schemas/reviewer-envelope.schema.json`).
+ *   6. Stamp `modelFamily` from `modelId` and return the envelope.
+ *
+ * Karpathy §2 — minimum code, no speculative abstractions. We deliberately
+ * do NOT pipe through the karpathy-reviewer path (out-of-scope per NG4).
+ */
+import { createHash } from 'node:crypto';
+import { deriveModelFamily } from './model-family.js';
+import { selectByMode, initialState } from './selection-strategies.js';
+import { callOllama } from './providers/ollama.js';
+import { callAnthropic } from './providers/anthropic.js';
+import { callOpenAI } from './providers/openai.js';
+import { loadReviewerConfig } from './reviewer-config.js';
+export const REVIEWER_ID = 'third-party-reviewer-v2.14.0';
+const VIOLATION_KINDS = [
+    'karpathy-violation',
+    'code-smell',
+    'security',
+    'perf',
+    'surgical-changes',
+    'simplicity-first',
+    'goal-driven-execution',
+    'think-before-coding'
+];
+const GATE_ACTIONS = ['block', 'allow', 'warn'];
+function isViolationKind(value) {
+    return typeof value === 'string' && VIOLATION_KINDS.includes(value);
+}
+function isGateAction(value) {
+    return typeof value === 'string' && GATE_ACTIONS.includes(value);
+}
+/**
+ * Validate a parsed JSON value against the ReviewerEnvelope contract
+ * (mirrors `schemas/reviewer-envelope.schema.json`). Returns the
+ * normalized envelope on success, or null when the input is malformed.
+ */
+export function validateReviewerEnvelope(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const v = value;
+    if (typeof v['reviewerId'] !== 'string' || v['reviewerId'].length === 0)
+        return null;
+    if (typeof v['modelId'] !== 'string' || v['modelId'].length === 0)
+        return null;
+    if (typeof v['modelFamily'] !== 'string' || v['modelFamily'].length === 0)
+        return null;
+    if (typeof v['passed'] !== 'boolean')
+        return null;
+    if (!Array.isArray(v['violations']))
+        return null;
+    const violations = [];
+    for (const raw of v['violations']) {
+        if (typeof raw !== 'object' || raw === null)
+            return null;
+        const r = raw;
+        if (!isViolationKind(r['kind']))
+            return null;
+        if (typeof r['file'] !== 'string' || r['file'].length === 0)
+            return null;
+        if (typeof r['line'] !== 'number' || !Number.isInteger(r['line']) || r['line'] < 0)
+            return null;
+        if (typeof r['hint'] !== 'string' || r['hint'].length === 0)
+            return null;
+        violations.push({
+            kind: r['kind'],
+            file: r['file'],
+            line: r['line'],
+            hint: r['hint']
+        });
+    }
+    if (!isGateAction(v['gateAction']))
+        return null;
+    if (typeof v['reason'] !== 'string' || v['reason'].length === 0)
+        return null;
+    return {
+        reviewerId: v['reviewerId'],
+        modelId: v['modelId'],
+        modelFamily: v['modelFamily'],
+        passed: v['passed'],
+        violations,
+        gateAction: v['gateAction'],
+        reason: v['reason']
+    };
+}
+/**
+ * Try to extract the first JSON object from an LLM text response.
+ * Many LLMs wrap JSON in ```json fences or surrounding prose; we
+ * tolerate both. Returns null when no JSON object is present.
+ */
+export function extractFirstJsonObject(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const candidate = fenced?.[1]?.trim() ?? text.trim();
+    // Try the whole candidate first.
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        // Fall back to a brace-balanced scan.
+        const start = candidate.indexOf('{');
+        if (start < 0)
+            return null;
+        let depth = 0;
+        for (let i = start; i < candidate.length; i += 1) {
+            const ch = candidate[i];
+            if (ch === '{')
+                depth += 1;
+            else if (ch === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    try {
+                        return JSON.parse(candidate.slice(start, i + 1));
+                    }
+                    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                        // TODO(g2): brace-balanced scan may slice mid-string or trap on malformed JSON;
+                        // null sentinel is intentional for slice B-1 reviewer parser — caller distinguishes
+                        // via ParseResult.ok flag at the call site (extractFirstJsonObject contract).
+                        return null;
+                    }
+                }
+            }
+        }
+        return null;
+    }
+}
+function buildPrompt(input) {
+    // Stable, deterministic envelope of context — sha256 of the body so
+    // the prompt stays bounded and does not leak the full slice content.
+    const digest = createHash('sha256').update(input.context).digest('hex').slice(0, 16);
+    return [
+        '# peaks-reviewer prompt (v2.14.0 G4)',
+        '',
+        `rid: ${input.rid}`,
+        `contextSha256: ${digest}`,
+        '',
+        '## Slice context (truncated to 8KB)',
+        input.context.slice(0, 8192),
+        '',
+        '## Required output (ReviewerEnvelope JSON)',
+        '',
+        'Respond with EXACTLY one JSON object matching this schema (no prose):',
+        '{',
+        '  "reviewerId": "third-party-reviewer-v2.14.0",',
+        '  "modelId": "<your modelId>",',
+        '  "modelFamily": "<e.g. claude / gpt-4o / llama>",',
+        '  "passed": <bool>,',
+        '  "violations": [{"kind": "<kind>", "file": "<path>", "line": <int>, "hint": "<str>"}],',
+        '  "gateAction": "block" | "allow" | "warn",',
+        '  "reason": "<one-sentence rationale>"',
+        '}',
+        '',
+        'Forbidden: prose, markdown, multiple objects, free-form JSON. Schema-validated only.'
+    ].join('\n');
+}
+function dispatchProvider(name, input) {
+    if (name === 'ollama')
+        return callOllama(input);
+    if (name === 'anthropic')
+        return callAnthropic(input);
+    if (name === 'openai')
+        return callOpenAI(input);
+    // Unknown provider names resolve to `providerUnavailable` — never throw.
+    return Promise.resolve({
+        ok: false,
+        error: `unknown provider ${String(name)}`,
+        latencyMs: 0
+    });
+}
+function skippedEnvelope(reason) {
+    return {
+        reviewerId: REVIEWER_ID,
+        modelId: 'skipped',
+        modelFamily: 'skipped',
+        passed: true,
+        violations: [],
+        gateAction: 'allow',
+        reason
+    };
+}
+export async function runReviewer(input) {
+    const status = loadReviewerConfig();
+    if (!status.ok) {
+        return {
+            ok: false,
+            reason: 'no-reviewer-config',
+            envelope: skippedEnvelope('skipped: no-reviewer-config (fallbackOnError=skip)')
+        };
+    }
+    const config = status.config;
+    const state = input.state ?? initialState();
+    const { result, nextState } = selectByMode(config.selection, config.providers, input.rid, state, input.rng);
+    const prompt = buildPrompt(input);
+    const callResult = await dispatchProvider(result.provider.name, {
+        provider: result.provider,
+        prompt,
+        ...(input.fetchImpl !== undefined ? { fetchImpl: input.fetchImpl } : {})
+    });
+    if (!callResult.ok) {
+        if (config.fallbackOnError === 'error') {
+            throw new Error(`peaks-reviewer: ${callResult.error}`);
+        }
+        return {
+            ok: true,
+            envelope: {
+                reviewerId: REVIEWER_ID,
+                modelId: result.provider.model,
+                modelFamily: deriveModelFamily(result.provider.model).modelFamily,
+                passed: true,
+                violations: [],
+                gateAction: 'warn',
+                reason: `skipped: provider ${result.provider.name} error (${callResult.error}); fallbackOnError=skip`
+            },
+            nextState
+        };
+    }
+    const parsed = extractFirstJsonObject(callResult.text);
+    const validated = validateReviewerEnvelope(parsed);
+    if (validated === null) {
+        return {
+            ok: true,
+            envelope: {
+                reviewerId: REVIEWER_ID,
+                modelId: result.provider.model,
+                modelFamily: deriveModelFamily(result.provider.model).modelFamily,
+                passed: true,
+                violations: [],
+                gateAction: 'warn',
+                reason: `provider ${result.provider.name} returned non-conforming JSON; treated as warn`
+            },
+            nextState
+        };
+    }
+    // Stamp modelFamily from the actual modelId we called — prevents the LLM
+    // from lying about its family and bypassing AC-4.4.
+    const stamped = {
+        ...validated,
+        modelId: result.provider.model,
+        modelFamily: deriveModelFamily(result.provider.model).modelFamily,
+        reviewerId: REVIEWER_ID
+    };
+    return { ok: true, envelope: stamped, nextState };
+}
+/**
+ * Compute the distinctness verdict: returns true when the third-party
+ * reviewer's modelFamily differs from the karpathy reviewer's. AC-4.4
+ * mandates this is a CI gate — equality fails the build.
+ */
+export function distinctFromKarpathy(thirdPartyFamily, karpathyFamily) {
+    if (thirdPartyFamily === 'skipped')
+        return true;
+    return thirdPartyFamily !== karpathyFamily;
+}

package/dist/services/reviewer/selection-strategies.d.ts

@@ -0,0 +1,27 @@
+import type { ReviewerProviderConfig } from './reviewer-config.js';
+export type SelectionMode = 'round-robin' | 'hash' | 'random';
+export type SelectionResult = {
+    provider: ReviewerProviderConfig;
+    index: number;
+    /** Monotonic call counter for `round-robin` (1-based). */
+    callNumber: number;
+};
+export type RoundRobinState = {
+    mode: 'round-robin';
+    cursor: number;
+};
+export type SelectionState = RoundRobinState;
+export declare function initialState(): SelectionState;
+/** Round-robin: cycles across the provider array across calls. */
+export declare function selectRoundRobin(providers: ReadonlyArray<ReviewerProviderConfig>, state: SelectionState, rid: string): {
+    result: SelectionResult;
+    nextState: SelectionState;
+};
+/** Hash(rid): stable, deterministic; same rid always yields same provider. */
+export declare function selectHash(providers: ReadonlyArray<ReviewerProviderConfig>, rid: string): SelectionResult;
+/** Random: uniform sample; supports a seeded RNG for testability. */
+export declare function selectRandom(providers: ReadonlyArray<ReviewerProviderConfig>, rid: string, rng?: () => number): SelectionResult;
+export declare function selectByMode(mode: SelectionMode, providers: ReadonlyArray<ReviewerProviderConfig>, rid: string, state: SelectionState, rng?: () => number): {
+    result: SelectionResult;
+    nextState: SelectionState;
+};

package/dist/services/reviewer/selection-strategies.js

@@ -0,0 +1,53 @@
+/**
+ * selection-strategies.ts — pick a provider per rid for the G4 third-party
+ * reviewer. AC-4.6 requires:
+ *   - `round-robin` cycles across providers across slices
+ *   - `hash(rid)` is stable per rid (deterministic replay)
+ *   - `random` is uniform over the provider set
+ *
+ * Pure helpers, no I/O, no globals beyond an injected RNG (default
+ * `Math.random`). Karpathy §2 — minimum code, no premature abstraction.
+ */
+import { createHash } from 'node:crypto';
+export function initialState() {
+    return { mode: 'round-robin', cursor: 0 };
+}
+/** Round-robin: cycles across the provider array across calls. */
+export function selectRoundRobin(providers, state, rid) {
+    if (providers.length === 0) {
+        throw new Error(`selectRoundRobin: providers must be non-empty (rid=${rid})`);
+    }
+    const cursor = state.mode === 'round-robin' ? state.cursor : 0;
+    const index = cursor % providers.length;
+    const provider = providers[index];
+    const nextState = { mode: 'round-robin', cursor: cursor + 1 };
+    return { result: { provider, index, callNumber: cursor + 1 }, nextState };
+}
+/** Hash(rid): stable, deterministic; same rid always yields same provider. */
+export function selectHash(providers, rid) {
+    if (providers.length === 0) {
+        throw new Error(`selectHash: providers must be non-empty (rid=${rid})`);
+    }
+    const digest = createHash('sha256').update(`reviewer|${rid}`).digest();
+    // Use first 4 bytes as an unsigned 32-bit int; modulo provider count.
+    const n = digest.readUInt32BE(0);
+    const index = n % providers.length;
+    const provider = providers[index];
+    return { provider, index, callNumber: 0 };
+}
+/** Random: uniform sample; supports a seeded RNG for testability. */
+export function selectRandom(providers, rid, rng = Math.random) {
+    if (providers.length === 0) {
+        throw new Error(`selectRandom: providers must be non-empty (rid=${rid})`);
+    }
+    const index = Math.floor(rng() * providers.length) % providers.length;
+    const provider = providers[index];
+    return { provider, index, callNumber: 0 };
+}
+export function selectByMode(mode, providers, rid, state, rng) {
+    if (mode === 'round-robin')
+        return selectRoundRobin(providers, state, rid);
+    if (mode === 'hash')
+        return { result: selectHash(providers, rid), nextState: state };
+    return { result: selectRandom(providers, rid, rng), nextState: state };
+}

package/dist/services/role/role-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * v2.15.0 follow-up — G9: role registry (lightweight RBAC).
+ *
+ * 12 Gaps memory: 团队多角色协同. This service manages a tiny
+ * in-memory / JSON-backed role → permission map. The CLI surfaces
+ *   - `peaks role list`              — list all roles
+ *   - `peaks role add <name>`        — register a role
+ *   - `peaks role grant <role> <perm>` — grant a permission
+ *   - `peaks role check <role> <perm>` — check if role has permission
+ *
+ * Persistence: `.peaks/role-registry.json` in the project root.
+ */
+export interface Role {
+    /** Unique role name (e.g. "senior-fe", "backend-lead", "admin"). */
+    readonly name: string;
+    /** Description (human-readable). */
+    readonly description: string;
+    /** Granted permissions (free-form strings, dot-separated convention). */
+    readonly permissions: readonly string[];
+}
+export interface RoleRegistry {
+    readonly version: 1;
+    readonly roles: readonly Role[];
+}
+export declare const EMPTY_ROLE_REGISTRY: RoleRegistry;
+export declare function getRoleRegistryPath(projectRoot: string): string;
+export declare function readRoleRegistry(projectRoot: string): RoleRegistry;
+export declare function writeRoleRegistry(projectRoot: string, registry: RoleRegistry): void;
+/** Add or update a role. Returns the new registry. */
+export declare function upsertRole(registry: RoleRegistry, role: Role): RoleRegistry;
+/** Grant a permission to a role. Returns the new registry. */
+export declare function grantPermission(registry: RoleRegistry, roleName: string, permission: string): RoleRegistry;
+/** Check if a role has a permission. */
+export declare function roleHasPermission(registry: RoleRegistry, roleName: string, permission: string): boolean;
+/** Permission categories that align with the peaks-loop 12 Gaps memory. */
+export declare const DEFAULT_PERMISSIONS: readonly string[];
+/** Default role preset for a Senior FE on a 24h AI programmer team. */
+export declare const DEFAULT_SENIOR_FE_ROLE: Role;

package/dist/services/role/role-registry.js

@@ -0,0 +1,83 @@
+/**
+ * v2.15.0 follow-up — G9: role registry (lightweight RBAC).
+ *
+ * 12 Gaps memory: 团队多角色协同. This service manages a tiny
+ * in-memory / JSON-backed role → permission map. The CLI surfaces
+ *   - `peaks role list`              — list all roles
+ *   - `peaks role add <name>`        — register a role
+ *   - `peaks role grant <role> <perm>` — grant a permission
+ *   - `peaks role check <role> <perm>` — check if role has permission
+ *
+ * Persistence: `.peaks/role-registry.json` in the project root.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+export const EMPTY_ROLE_REGISTRY = { version: 1, roles: [] };
+const STATE_FILE = '.peaks/role-registry.json';
+export function getRoleRegistryPath(projectRoot) {
+    return resolve(projectRoot, STATE_FILE);
+}
+export function readRoleRegistry(projectRoot) {
+    const path = getRoleRegistryPath(projectRoot);
+    if (!existsSync(path))
+        return EMPTY_ROLE_REGISTRY;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1)
+            return EMPTY_ROLE_REGISTRY;
+        return { version: 1, roles: Array.isArray(parsed.roles) ? parsed.roles : [] };
+    }
+    catch {
+        return EMPTY_ROLE_REGISTRY;
+    }
+}
+export function writeRoleRegistry(projectRoot, registry) {
+    const path = getRoleRegistryPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(registry, null, 2), 'utf8');
+}
+/** Add or update a role. Returns the new registry. */
+export function upsertRole(registry, role) {
+    const filtered = registry.roles.filter((r) => r.name !== role.name);
+    return { version: 1, roles: [...filtered, role] };
+}
+/** Grant a permission to a role. Returns the new registry. */
+export function grantPermission(registry, roleName, permission) {
+    const found = registry.roles.find((r) => r.name === roleName);
+    if (!found)
+        return registry;
+    if (found.permissions.includes(permission))
+        return registry;
+    const updated = { ...found, permissions: [...found.permissions, permission] };
+    return upsertRole(registry, updated);
+}
+/** Check if a role has a permission. */
+export function roleHasPermission(registry, roleName, permission) {
+    const role = registry.roles.find((r) => r.name === roleName);
+    if (!role)
+        return false;
+    return role.permissions.includes(permission);
+}
+/** Permission categories that align with the peaks-loop 12 Gaps memory. */
+export const DEFAULT_PERMISSIONS = [
+    'prd.write',
+    'prd.confirm',
+    'rd.implement',
+    'rd.review',
+    'qa.accept',
+    'qa.reject',
+    'release.canary',
+    'release.promote',
+    'release.hotfix',
+    'fork.sync',
+    'smoke.define',
+    'smoke.run',
+    'admin.full'
+];
+/** Default role preset for a Senior FE on a 24h AI programmer team. */
+export const DEFAULT_SENIOR_FE_ROLE = {
+    name: 'senior-fe',
+    description: 'Senior Frontend (业务资深 + 后端半盲 + 24h AI 程序员)',
+    permissions: ['prd.write', 'prd.confirm', 'rd.review', 'qa.accept', 'qa.reject', 'smoke.define', 'smoke.run']
+};

package/dist/services/runtime/runtime-detector.d.ts

@@ -0,0 +1,15 @@
+export type DetectedVendor = 'claude-code' | 'codex' | 'copilot' | 'unknown';
+export interface RuntimeDetectorOptions {
+    /** Override for env (used by tests). */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override for home directory (used by tests). */
+    readonly home?: string;
+}
+export interface DetectionResult {
+    readonly vendor: DetectedVendor;
+    /** Why this vendor was chosen — useful for diagnostics and tests. */
+    readonly reason: string;
+}
+/** Detect the active vendor. Order: claude-code → codex → copilot →
+ *  unknown. The first match wins. */
+export declare function detectRuntime(opts?: RuntimeDetectorOptions): DetectionResult;

package/dist/services/runtime/runtime-detector.js

@@ -0,0 +1,62 @@
+/**
+ * Runtime detector — slice S2-a of RD-2.
+ *
+ * Given the current process environment, decide which vendor (if any)
+ * is the active AI runtime. Detection order matters: Claude Code is
+ * checked first because it is the default runtime for peaks-loop
+ * (the project literally runs inside Claude Code). Codex + Copilot
+ * are checked second; if none match we report `unknown`.
+ *
+ * Detectors MUST be cheap (no process spawn, no network). They look
+ * at env vars + filesystem sentinels + home-dir shapes only. This
+ * keeps `peaks runtime detect` sub-100ms even on cold paths.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Heuristic: Claude Code sets CLAUDE_CODE_ENTRYPOINT or has a
+ *  .claude/skills directory under HOME (peaks-loop installs there). */
+function detectClaudeCode(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CLAUDE_CODE === '1' || env.CLAUDE_CODE === 'true')
+        return true;
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined && env.CLAUDE_CODE_ENTRYPOINT.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.claude')))
+        return true;
+    return false;
+}
+/** Heuristic: Codex sets CODEX_HOME or has a .codex dir under HOME. */
+function detectCodex(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CODEX_HOME !== undefined && env.CODEX_HOME.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.codex')))
+        return true;
+    return false;
+}
+/** Heuristic: Copilot sets GITHUB_COPILOT or has a .copilot dir. */
+function detectCopilot(opts) {
+    const env = opts.env ?? process.env;
+    if (env.GITHUB_COPILOT === '1' || env.GITHUB_COPILOT === 'true')
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.copilot')))
+        return true;
+    return false;
+}
+/** Detect the active vendor. Order: claude-code → codex → copilot →
+ *  unknown. The first match wins. */
+export function detectRuntime(opts = {}) {
+    if (detectClaudeCode(opts)) {
+        return { vendor: 'claude-code', reason: 'CLAUDE_CODE_ENTRYPOINT / CLAUDE_CODE / ~/.claude matched' };
+    }
+    if (detectCodex(opts)) {
+        return { vendor: 'codex', reason: 'CODEX_HOME / ~/.codex matched' };
+    }
+    if (detectCopilot(opts)) {
+        return { vendor: 'copilot', reason: 'GITHUB_COPILOT / ~/.copilot matched' };
+    }
+    return { vendor: 'unknown', reason: 'no vendor sentinel detected' };
+}

package/dist/services/runtime/runtime-service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime service — slice S2-a of RD-2.
+ *
+ * Orchestrator that wires the runtime detector + vendor adapter
+ * registry into a small surface that the CLI commands call. The
+ * service owns the canonical list of built-in adapters (claude-code /
+ * codex / copilot) and decides which adapter handles a given
+ * `--via <id>` request.
+ *
+ * Design notes (Karpathy #2 Simplicity First):
+ *
+ *  - The service is a thin orchestrator — it does NOT contain any
+ *    vendor verb strings (claude / codex / copilot). All vendor verbs
+ *    live in `src/services/runtime/vendors/<vendor>.ts`. Verified by
+ *    AC-1.
+ *  - When `compactVia(id)` is called with an unknown id, the service
+ *    returns a "no-op" result with exitCode=0 and a warning instead of
+ *    throwing — vendor-neutrality means peaks-loop MUST keep working
+ *    even when the requested vendor adapter isn't registered.
+ *  - The service is the SOLE owner of the built-in adapter list. Tests
+ *    and CLI commands should never instantiate adapters directly;
+ *    they should call `listBuiltInAdapters()` or `getAdapter(id)`.
+ */
+import type { VendorAdapter, VendorCompactResult } from './vendor-adapter.js';
+export interface RuntimeServiceOptions {
+    /** Override the built-in adapter list (used by tests + the
+     *  adapter-registry's `register()` flow). */
+    readonly builtIns?: VendorAdapter[];
+    /** Override the home dir used by adapter detect() helpers. */
+    readonly home?: string;
+}
+/** Pure orchestrator. The runtime service holds built-in adapters as
+ *  the baseline registry; the AdapterRegistry layer (`src/services/
+ *  adapter/adapter-registry.ts`) extends this baseline at runtime via
+ *  user-registered adapters persisted to `.peaks/runtime/adapters.json`.
+ *  The two layers are intentionally separate:
+ *    - runtime-service: built-in vendor adapters for the runtime-detect
+ *      compact flow (S2-a).
+ *    - adapter-registry: persisted user-registered adapters (S2-a).
+ *  runtime-service itself does NOT consult the adapter registry —
+ *  callers (`peaks runtime compact --via <id>`) layer them: first look
+ *  up the id in the persisted registry, fall back to the built-in list.
+ */
+export declare class RuntimeService {
+    private readonly builtIns;
+    constructor(opts?: RuntimeServiceOptions);
+    /** Return all built-in adapters. Order: claude-code, codex, copilot. */
+    listBuiltInAdapters(): VendorAdapter[];
+    /** Resolve a built-in adapter by id. Returns undefined when not
+     *  found — caller should fall back to adapter registry or unknown. */
+    getBuiltInAdapter(id: string): VendorAdapter | undefined;
+    /** Compact via a built-in adapter. When the id is unknown, returns
+     *  a no-op result with a warning rather than throwing — vendor
+     *  neutrality demands peaks-loop stay alive even when a vendor is
+     *  not wired up. */
+    compactVia(id: string, force: boolean | undefined): Promise<VendorCompactResult & {
+        warning?: string;
+    }>;
+}

package/dist/services/runtime/runtime-service.js

@@ -0,0 +1,51 @@
+import { ClaudeCodeAdapter } from './vendors/claude-code.js';
+import { CodexAdapter } from './vendors/codex.js';
+import { CopilotAdapter } from './vendors/copilot.js';
+const DEFAULT_BUILT_INS = [
+    new ClaudeCodeAdapter(),
+    new CodexAdapter(),
+    new CopilotAdapter()
+];
+/** Pure orchestrator. The runtime service holds built-in adapters as
+ *  the baseline registry; the AdapterRegistry layer (`src/services/
+ *  adapter/adapter-registry.ts`) extends this baseline at runtime via
+ *  user-registered adapters persisted to `.peaks/runtime/adapters.json`.
+ *  The two layers are intentionally separate:
+ *    - runtime-service: built-in vendor adapters for the runtime-detect
+ *      compact flow (S2-a).
+ *    - adapter-registry: persisted user-registered adapters (S2-a).
+ *  runtime-service itself does NOT consult the adapter registry —
+ *  callers (`peaks runtime compact --via <id>`) layer them: first look
+ *  up the id in the persisted registry, fall back to the built-in list.
+ */
+export class RuntimeService {
+    builtIns;
+    constructor(opts = {}) {
+        this.builtIns = opts.builtIns ?? [...DEFAULT_BUILT_INS];
+    }
+    /** Return all built-in adapters. Order: claude-code, codex, copilot. */
+    listBuiltInAdapters() {
+        return [...this.builtIns];
+    }
+    /** Resolve a built-in adapter by id. Returns undefined when not
+     *  found — caller should fall back to adapter registry or unknown. */
+    getBuiltInAdapter(id) {
+        return this.builtIns.find((a) => a.id === id);
+    }
+    /** Compact via a built-in adapter. When the id is unknown, returns
+     *  a no-op result with a warning rather than throwing — vendor
+     *  neutrality demands peaks-loop stay alive even when a vendor is
+     *  not wired up. */
+    async compactVia(id, force) {
+        const adapter = this.getBuiltInAdapter(id);
+        if (adapter === undefined) {
+            return {
+                exitCode: 0,
+                stdout: '',
+                stderr: '',
+                warning: `no built-in adapter registered for id="${id}" — falling back to no-op; use \`peaks adapter register --id ${id} --binary <cmd>\` to wire one`
+            };
+        }
+        return adapter.compact({ force: force === true });
+    }
+}