r2mcp 0.2.0

package/dist/lint/checks/drift.js

@@ -0,0 +1,34 @@
+const DRIFT_SQL = `
+  SELECT
+    m1.id AS newer_id,
+    m2.id AS older_id,
+    (
+      SELECT COUNT(*)::int FROM unnest(m1.topics) t1
+      WHERE t1 = ANY(m2.topics)
+    ) AS shared_topics
+  FROM memories m1
+  JOIN memories m2 ON m1.created_at > m2.created_at + INTERVAL '30 days'
+  WHERE m1.type != 'archived' AND m2.type != 'archived'
+    AND (
+      SELECT COUNT(*) FROM unnest(m1.topics) t1
+      WHERE t1 = ANY(m2.topics)
+    ) >= 2
+    AND NOT EXISTS (
+      SELECT 1 FROM memory_edges e
+      WHERE (e.from_memory_id = m1.id AND e.to_memory_id = m2.id)
+         OR (e.from_memory_id = m2.id AND e.to_memory_id = m1.id)
+    )
+  ORDER BY shared_topics DESC, m1.created_at DESC
+  LIMIT $1
+`;
+export async function findDrift(pool, opts) {
+    const rows = await pool.query(DRIFT_SQL, [opts.limit]);
+    return rows.rows.map((r) => ({
+        check: 'drift',
+        memory_id: r.newer_id,
+        related_memory_id: r.older_id,
+        rationale: `Pair shares ${r.shared_topics} topics with >30d gap and no classifier-written edge — possible classification gap.`,
+        suggested_action: 'reclassify',
+        confidence: 0.55,
+    }));
+}

package/dist/lint/checks/orphans.d.ts

@@ -0,0 +1,5 @@
+import type { LintFinding } from '../types.js';
+import type { PoolLike } from './contradictions.js';
+export declare function findOrphans(pool: PoolLike, opts: {
+    limit: number;
+}): Promise<LintFinding[]>;

package/dist/lint/checks/orphans.js

@@ -0,0 +1,25 @@
+const ORPHANS_SQL = `
+  SELECT
+    m.id,
+    m.created_at::text AS created_at
+  FROM memories m
+  WHERE m.type != 'archived'
+    AND m.created_at < NOW() - INTERVAL '30 days'
+    AND NOT EXISTS (
+      SELECT 1 FROM memory_edges e
+      WHERE (e.from_memory_id = m.id OR e.to_memory_id = m.id)
+        AND e.valid_until IS NULL
+    )
+  ORDER BY m.created_at ASC
+  LIMIT $1
+`;
+export async function findOrphans(pool, opts) {
+    const rows = await pool.query(ORPHANS_SQL, [opts.limit]);
+    return rows.rows.map((r) => ({
+        check: 'orphans',
+        memory_id: r.id,
+        rationale: `Memory has no edges in either direction since ${r.created_at}.`,
+        suggested_action: 'human_review',
+        confidence: 0.6,
+    }));
+}

package/dist/lint/checks/stale.d.ts

@@ -0,0 +1,6 @@
+import type { LintFinding } from '../types.js';
+import type { PoolLike } from './contradictions.js';
+export declare function findStale(pool: PoolLike, opts: {
+    sinceDays: number;
+    limit: number;
+}): Promise<LintFinding[]>;

package/dist/lint/checks/stale.js

@@ -0,0 +1,29 @@
+const STALE_SQL = `
+  SELECT
+    m.id,
+    m.created_at::text AS created_at,
+    EXISTS (
+      SELECT 1 FROM memory_edges oe
+      WHERE oe.from_memory_id = m.id AND oe.valid_until IS NULL
+    ) AS has_outgoing
+  FROM memories m
+  WHERE m.type != 'archived'
+    AND m.tier != 'preferences'
+    AND m.created_at < NOW() - ($1 || ' days')::interval
+    AND NOT EXISTS (
+      SELECT 1 FROM memory_edges ie
+      WHERE ie.to_memory_id = m.id AND ie.valid_until IS NULL
+    )
+  ORDER BY m.created_at ASC
+  LIMIT $2
+`;
+export async function findStale(pool, opts) {
+    const rows = await pool.query(STALE_SQL, [opts.sinceDays, opts.limit]);
+    return rows.rows.map((r) => ({
+        check: 'stale',
+        memory_id: r.id,
+        rationale: `Memory created ${r.created_at} has no incoming edges${r.has_outgoing ? ' (but has outgoing references)' : ' or outgoing references'}.`,
+        suggested_action: 'archive',
+        confidence: r.has_outgoing ? 0.7 : 0.95,
+    }));
+}

package/dist/lint/checks/superseded-unflagged.d.ts

@@ -0,0 +1,5 @@
+import type { LintFinding } from '../types.js';
+import type { PoolLike } from './contradictions.js';
+export declare function findSupersededUnflagged(pool: PoolLike, opts: {
+    limit: number;
+}): Promise<LintFinding[]>;

package/dist/lint/checks/superseded-unflagged.js

@@ -0,0 +1,47 @@
+const SUPER_UNFLAGGED_SQL = `
+  SELECT
+    e.id::text AS edge_id,
+    e.from_memory_id AS from_id,
+    e.to_memory_id   AS to_id,
+    e.confidence::float AS confidence,
+    e.rationale,
+    m1.created_at::text AS from_created_at,
+    m2.created_at::text AS to_created_at,
+    (
+      SELECT COUNT(*)::int FROM unnest(m1.topics) t1
+      WHERE t1 = ANY(m2.topics)
+    ) AS shared_topics
+  FROM memory_edges e
+  JOIN memories m1 ON m1.id = e.from_memory_id
+  JOIN memories m2 ON m2.id = e.to_memory_id
+  WHERE e.relation = 'contradicts'
+    AND e.valid_until IS NULL
+    AND m1.created_at > m2.created_at  -- from is strictly newer
+    AND m1.type != 'archived'
+    AND m2.type != 'archived'
+  ORDER BY (m1.created_at - m2.created_at) DESC
+  LIMIT $1
+`;
+export async function findSupersededUnflagged(pool, opts) {
+    const rows = await pool.query(SUPER_UNFLAGGED_SQL, [opts.limit]);
+    const findings = [];
+    for (const r of rows.rows) {
+        const ageGapDays = ageDays(r.from_created_at, r.to_created_at);
+        let confidence = 0.85;
+        if (r.shared_topics >= 1 && ageGapDays >= 90)
+            confidence = 0.92;
+        findings.push({
+            check: 'superseded_unflagged',
+            memory_id: r.from_id,
+            related_memory_id: r.to_id,
+            rationale: `${r.from_id} contradicts ${r.to_id} but is ${ageGapDays}d newer with ${r.shared_topics} shared topics — likely supersedes, not contradicts.`,
+            suggested_action: 'fix_edge_type',
+            confidence,
+        });
+    }
+    return findings;
+}
+function ageDays(newer, older) {
+    const ms = new Date(newer).getTime() - new Date(older).getTime();
+    return Math.round(ms / (1000 * 60 * 60 * 24));
+}

package/dist/lint/run.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lint orchestrator — dispatches the requested check (or all five), composes
+ * findings into the standard `LintResult` shape, and applies `--fix` actions
+ * for findings with confidence >= 0.9.
+ *
+ * SQL-only. No LLM calls (C.R5). Each check is independent and runs as its
+ * own bounded query.
+ */
+import { type PoolLike } from './checks/contradictions.js';
+import { type LintInput, type LintResult } from './types.js';
+export declare function runLint(input: LintInput, pool: PoolLike): Promise<LintResult>;

package/dist/lint/run.js

@@ -0,0 +1,95 @@
+/**
+ * Lint orchestrator — dispatches the requested check (or all five), composes
+ * findings into the standard `LintResult` shape, and applies `--fix` actions
+ * for findings with confidence >= 0.9.
+ *
+ * SQL-only. No LLM calls (C.R5). Each check is independent and runs as its
+ * own bounded query.
+ */
+import { findContradictions } from './checks/contradictions.js';
+import { findStale } from './checks/stale.js';
+import { findOrphans } from './checks/orphans.js';
+import { findDrift } from './checks/drift.js';
+import { findSupersededUnflagged } from './checks/superseded-unflagged.js';
+import { ALL_CHECKS, FIX_CONFIDENCE_THRESHOLD, } from './types.js';
+const DEFAULT_LIMIT = 100;
+const DEFAULT_SINCE_DAYS = 90;
+export async function runLint(input, pool) {
+    const limit = input.limit ?? DEFAULT_LIMIT;
+    const sinceDays = input.since_days ?? DEFAULT_SINCE_DAYS;
+    const checksToRun = input.check ? [input.check] : [...ALL_CHECKS];
+    const findings = [];
+    for (const check of checksToRun) {
+        if (check === 'contradictions') {
+            findings.push(...(await findContradictions(pool, { limit, memoryId: input.memory_id })));
+        }
+        else if (check === 'stale') {
+            findings.push(...(await findStale(pool, { sinceDays, limit })));
+        }
+        else if (check === 'orphans') {
+            findings.push(...(await findOrphans(pool, { limit })));
+        }
+        else if (check === 'drift') {
+            findings.push(...(await findDrift(pool, { limit })));
+        }
+        else if (check === 'superseded_unflagged') {
+            findings.push(...(await findSupersededUnflagged(pool, { limit })));
+        }
+    }
+    const summary = buildSummary(findings);
+    const result = { summary, findings };
+    if (input.fix) {
+        const fixesApplied = await applyFixes(pool, findings);
+        result.fixes_applied = fixesApplied;
+    }
+    return result;
+}
+/**
+ * Compose the per-check counts plus total. Always includes every check name
+ * even when count is 0 — keeps the response shape stable across invocations
+ * (C.AC2: shape doesn't drift between different `check` selections).
+ */
+function buildSummary(findings) {
+    const by_check = {
+        contradictions: 0,
+        stale: 0,
+        orphans: 0,
+        drift: 0,
+        superseded_unflagged: 0,
+    };
+    for (const f of findings)
+        by_check[f.check]++;
+    return {
+        total_findings: findings.length,
+        by_check,
+    };
+}
+/**
+ * Apply auto-fixes for findings with confidence >= 0.9 (C.R3, C.AC4).
+ *
+ * Currently fixed:
+ *   - stale: archive the memory (set type='archived')
+ *   - superseded_unflagged: rewrite edge type from 'contradicts' to 'supersedes'
+ *
+ * Other check types return findings only — `--fix` is a no-op for them.
+ */
+async function applyFixes(pool, findings) {
+    const applied = [];
+    for (const f of findings) {
+        if (f.confidence < FIX_CONFIDENCE_THRESHOLD)
+            continue;
+        if (f.check === 'stale' && f.suggested_action === 'archive') {
+            await pool.query(`UPDATE memories SET type = 'archived', updated_at = NOW() WHERE id = $1 AND type != 'archived'`, [f.memory_id]);
+            applied.push({ memory_id: f.memory_id, action: 'archive' });
+        }
+        else if (f.check === 'superseded_unflagged' &&
+            f.suggested_action === 'fix_edge_type' &&
+            f.related_memory_id) {
+            await pool.query(`UPDATE memory_edges
+         SET relation = 'supersedes', updated_at = NOW()
+         WHERE from_memory_id = $1 AND to_memory_id = $2 AND relation = 'contradicts' AND valid_until IS NULL`, [f.memory_id, f.related_memory_id]);
+            applied.push({ memory_id: f.memory_id, action: 'fix_edge_type' });
+        }
+    }
+    return applied;
+}

package/dist/lint/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Lint surfaces structural feedback that `meditate()` could only express
+ * implicitly. Five SQL-driven checks against memory_edges + memories — no
+ * LLM calls (SPEC-044 C.R5).
+ */
+export type CheckName = 'contradictions' | 'stale' | 'orphans' | 'drift' | 'superseded_unflagged';
+/**
+ * Suggested actions are a closed vocabulary so callers can route findings
+ * without natural-language matching. Each check's findings draw from the
+ * subset that fits its domain.
+ */
+export type SuggestedAction = 'archive_one' | 'add_supersedes_edge' | 'human_review' | 'archive' | 'reclassify' | 'fix_edge_type';
+export interface LintFinding {
+    check: CheckName;
+    memory_id: string;
+    /** Optional companion memory when the finding is about a pair (contradictions, drift, superseded_unflagged). */
+    related_memory_id?: string;
+    /**
+     * Optional first topic of `memory_id`'s memory, surfaced so downstream
+     * consumers (e.g. SPEC-047 lint→compile breadcrumb, which needs `compile
+     * --topic=<topic>`) can route findings without a second DB query. Populated
+     * by `contradictions` today; other checks may follow.
+     */
+    topic?: string;
+    rationale: string;
+    suggested_action: SuggestedAction;
+    /** Confidence score [0..1]. `lint --fix` only acts on findings >= 0.9. */
+    confidence: number;
+}
+export interface LintSummary {
+    total_findings: number;
+    by_check: Record<CheckName, number>;
+}
+export interface LintInput {
+    check?: CheckName;
+    /** Used by stale check (default: 90 days). */
+    since_days?: number;
+    /** Cap findings per-check (default: 100). */
+    limit?: number;
+    /** When true, apply fixes for findings with confidence >= 0.9. */
+    fix?: boolean;
+    /**
+     * Optional scope filter — only applied by the `contradictions` check today.
+     * Restricts findings to edges where either endpoint matches this memory id.
+     * Added for SPEC-047 (`lint --check=contradictions --memory-id=<id>`
+     * breadcrumb path); other checks ignore it.
+     */
+    memory_id?: string;
+}
+export interface LintResult {
+    summary: LintSummary;
+    findings: LintFinding[];
+    /** Per-finding action records when fix=true. */
+    fixes_applied?: Array<{
+        memory_id: string;
+        action: SuggestedAction;
+    }>;
+}
+export declare const ALL_CHECKS: ReadonlyArray<CheckName>;
+export declare const FIX_CONFIDENCE_THRESHOLD = 0.9;

package/dist/lint/types.js

@@ -0,0 +1,13 @@
+/**
+ * Lint surfaces structural feedback that `meditate()` could only express
+ * implicitly. Five SQL-driven checks against memory_edges + memories — no
+ * LLM calls (SPEC-044 C.R5).
+ */
+export const ALL_CHECKS = [
+    'contradictions',
+    'stale',
+    'orphans',
+    'drift',
+    'superseded_unflagged',
+];
+export const FIX_CONFIDENCE_THRESHOLD = 0.9;

package/dist/mcp-response.d.ts

@@ -0,0 +1,7 @@
+import { type ToolName } from './breadcrumbs.js';
+export declare function asMcpResponse<T extends object>(toolName: ToolName, result: T, args: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/mcp-response.js

@@ -0,0 +1,13 @@
+// SPEC-047 Phase 5 — MCP response shaping.
+//
+// Centralises JSON-stringify + breadcrumb wrapping for every server.tool() handler.
+// Lives in its own module (not src/index.ts) so test files can import asMcpResponse
+// without triggering the MCP server's main() and DB init.
+import { withBreadcrumbs } from './breadcrumbs.js';
+export function asMcpResponse(toolName, result, args) {
+    const ctx = { tool: toolName, response: result, args };
+    const wrapped = withBreadcrumbs(result, ctx);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(wrapped, null, 2) }],
+    };
+}

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,13 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { CompleteRequest, CompleteResponse, LLMProvider, LogicalModel, ProviderName } from './types.js';
+export declare class AnthropicProvider implements LLMProvider {
+    readonly name: ProviderName;
+    readonly concurrencyLimit = 10;
+    private sdk;
+    constructor(opts?: {
+        apiKey?: string;
+        sdk?: Anthropic;
+    });
+    static priceForTokens(model: LogicalModel, inputTokens: number, outputTokens: number): number;
+    complete(req: CompleteRequest): Promise<CompleteResponse>;
+}

package/dist/providers/anthropic.js

@@ -0,0 +1,56 @@
+import Anthropic from '@anthropic-ai/sdk';
+const MODEL_IDS = {
+    haiku: 'claude-haiku-4-5-20251001',
+    opus: 'claude-opus-4-7',
+    sonnet: 'claude-sonnet-4-6',
+};
+// Per-million-token list prices (USD), public list price as of 2026-05.
+const PRICES = {
+    haiku: { input: 0.8, output: 4.0 },
+    opus: { input: 15.0, output: 75.0 },
+    sonnet: { input: 3.0, output: 15.0 },
+};
+const DEFAULT_MAX_TOKENS = 256;
+export class AnthropicProvider {
+    name = 'anthropic';
+    concurrencyLimit = 10;
+    sdk;
+    constructor(opts = {}) {
+        if (opts.sdk) {
+            this.sdk = opts.sdk;
+            return;
+        }
+        const apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            throw new Error('ANTHROPIC_API_KEY is required to construct AnthropicProvider');
+        }
+        this.sdk = new Anthropic({ apiKey });
+    }
+    static priceForTokens(model, inputTokens, outputTokens) {
+        const p = PRICES[model];
+        return (inputTokens / 1_000_000) * p.input + (outputTokens / 1_000_000) * p.output;
+    }
+    async complete(req) {
+        const startedAt = Date.now();
+        const response = await this.sdk.messages.create({
+            model: MODEL_IDS[req.model],
+            max_tokens: req.max_tokens ?? DEFAULT_MAX_TOKENS,
+            system: req.system,
+            messages: [{ role: 'user', content: req.prompt }],
+        });
+        const text = response.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('');
+        const inputTokens = response.usage.input_tokens;
+        const outputTokens = response.usage.output_tokens;
+        return {
+            response: text,
+            cost_usd: AnthropicProvider.priceForTokens(req.model, inputTokens, outputTokens),
+            latency_ms: Date.now() - startedAt,
+            input_tokens: inputTokens,
+            output_tokens: outputTokens,
+            raw: response,
+        };
+    }
+}

package/dist/providers/claude-code.d.ts

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process';
+import type { CompleteRequest, CompleteResponse, LLMProvider, ProviderName } from './types.js';
+export interface ClaudeCodeOptions {
+    /** Override the binary name (tests use this to point at a stub). */
+    binary?: string;
+    /** Override the spawn function (tests use this to inject a mock child process). */
+    spawnFn?: typeof spawn;
+    /** Per-call timeout in milliseconds. Default 120s. */
+    runTimeoutMs?: number;
+}
+export declare class ClaudeCodeProvider implements LLMProvider {
+    readonly name: ProviderName;
+    readonly concurrencyLimit = 2;
+    private readonly binary;
+    private readonly spawnFn;
+    private readonly runTimeoutMs;
+    constructor(opts?: ClaudeCodeOptions);
+    complete(req: CompleteRequest): Promise<CompleteResponse>;
+    private composePrompt;
+}
+/**
+ * Probe whether Claude Code is logged in. Fast (~5s timeout). Used by
+ * `selectProvider()` for auto-fallback (D.AC1).
+ */
+export declare function probeClaudeCode(opts?: {
+    binary?: string;
+    spawnFn?: typeof spawn;
+    timeoutMs?: number;
+}): Promise<boolean>;
+interface ClaudeJsonEnvelope {
+    text: string;
+    raw: unknown;
+}
+export declare function parseClaudeJson(stdout: string): ClaudeJsonEnvelope;
+export {};

package/dist/providers/claude-code.js

@@ -0,0 +1,175 @@
+import { spawn } from 'node:child_process';
+/**
+ * Claude Code headless adapter.
+ *
+ * Spawns `claude -p <prompt> --output-format=json` and reads the JSON envelope
+ * from stdout. Auth is OAuth-based (Max plan); `cost_usd` is exactly 0 for
+ * every call (Max-covered, D.AC5 strict equality).
+ *
+ * Probe: `probeClaudeCode()` runs a minimal prompt with a 5s timeout to
+ * detect whether the binary is on PATH and the user is logged in.
+ */
+// Map logical models to the model identifiers Claude Code's CLI accepts.
+const MODEL_IDS = {
+    haiku: 'claude-haiku-4-5',
+    opus: 'claude-opus-4-7',
+    sonnet: 'claude-sonnet-4-6',
+};
+const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
+const DEFAULT_RUN_TIMEOUT_MS = 120_000;
+export class ClaudeCodeProvider {
+    name = 'claude-code';
+    // Subprocess overhead — keep this conservative. D.R6.
+    concurrencyLimit = 2;
+    binary;
+    spawnFn;
+    runTimeoutMs;
+    constructor(opts = {}) {
+        // Resolution precedence: explicit opts.binary → R2MCP_CLAUDE_BIN env →
+        // bare 'claude'. The env var lets packaged consumers point at an
+        // absolute install path (e.g., ~/.local/bin/claude) when the spawning
+        // process inherits a sanitized PATH (launchd jobs, systemd services).
+        this.binary = opts.binary ?? process.env.R2MCP_CLAUDE_BIN ?? 'claude';
+        this.spawnFn = opts.spawnFn ?? spawn;
+        this.runTimeoutMs = opts.runTimeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+    }
+    async complete(req) {
+        const startedAt = Date.now();
+        const args = [
+            '-p',
+            this.composePrompt(req),
+            '--output-format=json',
+            '--model',
+            MODEL_IDS[req.model],
+        ];
+        const stdout = await runClaude(this.spawnFn, this.binary, args, this.runTimeoutMs);
+        const parsed = parseClaudeJson(stdout);
+        return {
+            response: parsed.text,
+            cost_usd: 0, // Max-covered (D.AC5 strict equality)
+            latency_ms: Date.now() - startedAt,
+            raw: parsed.raw,
+        };
+    }
+    composePrompt(req) {
+        if (!req.system)
+            return req.prompt;
+        // Claude Code headless takes a single prompt string. Inline the system
+        // section so the same prompt structure works across providers.
+        return `[SYSTEM]\n${req.system}\n[/SYSTEM]\n\n${req.prompt}`;
+    }
+}
+/**
+ * Probe whether Claude Code is logged in. Fast (~5s timeout). Used by
+ * `selectProvider()` for auto-fallback (D.AC1).
+ */
+export async function probeClaudeCode(opts = {}) {
+    const binary = opts.binary ?? process.env.R2MCP_CLAUDE_BIN ?? 'claude';
+    const spawnFn = opts.spawnFn ?? spawn;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    try {
+        const out = await runClaude(spawnFn, binary, ['-p', 'ok', '--output-format=json'], timeoutMs);
+        const parsed = parseClaudeJson(out);
+        return typeof parsed.text === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * claw-8cjf.7: an ENOENT here means the claude CLI isn't on this process's
+ * PATH (common under launchd / MCP hosts with sanitized PATH). Name the
+ * escape hatch instead of surfacing a bare `spawn claude ENOENT`.
+ */
+function wrapSpawnError(err, binary) {
+    if (err.code !== 'ENOENT')
+        return err;
+    return new Error(`could not spawn '${binary}' (ENOENT) — the claude CLI is not on this process's PATH. ` +
+        `Set R2MCP_CLAUDE_BIN to the absolute path of the claude binary ` +
+        `(e.g. ~/.local/bin/claude) in your environment or .mcp.json "env" block.`, { cause: err });
+}
+function runClaude(spawnFn, binary, args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawnFn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch (err) {
+            reject(wrapSpawnError(err instanceof Error ? err : new Error(String(err)), binary));
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* ignore */
+            }
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            stdout += d.toString();
+        });
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(wrapSpawnError(err, binary));
+        });
+        child.on('exit', (code, signal) => {
+            clearTimeout(timer);
+            if (timedOut)
+                return reject(new Error(`claude timed out after ${timeoutMs}ms`));
+            if (code !== 0) {
+                return reject(new Error(`claude exited ${code} (signal=${signal}): ${stderr.slice(0, 500)}`));
+            }
+            resolve(stdout);
+        });
+    });
+}
+export function parseClaudeJson(stdout) {
+    // Claude Code's --output-format=json envelope wraps the assistant response.
+    // Shape varies slightly across versions; the canonical fields are
+    // { result: "...", ... } or { messages: [...], ... }. We accept either.
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`Claude Code output was not JSON: ${stdout.slice(0, 200)}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('Claude Code JSON envelope is not an object');
+    }
+    const obj = parsed;
+    // Preferred: top-level `result` field
+    if (typeof obj.result === 'string') {
+        return { text: obj.result, raw: parsed };
+    }
+    // Fallback: messages array, take the last assistant message text
+    if (Array.isArray(obj.messages)) {
+        const msgs = obj.messages;
+        for (let i = msgs.length - 1; i >= 0; i--) {
+            const m = msgs[i];
+            if (m.role !== 'assistant')
+                continue;
+            if (typeof m.content === 'string')
+                return { text: m.content, raw: parsed };
+            if (Array.isArray(m.content)) {
+                const text = m.content
+                    .filter((b) => {
+                    return !!b && typeof b === 'object' && b.type === 'text';
+                })
+                    .map((b) => b.text)
+                    .join('');
+                if (text)
+                    return { text, raw: parsed };
+            }
+        }
+    }
+    throw new Error(`Claude Code JSON envelope had no readable response: ${stdout.slice(0, 200)}`);
+}

package/dist/providers/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Provider-selection error surfaces. Kept in a dedicated module so consumers
+ * can import them without pulling in the heavy adapter modules.
+ */
+export declare class ProviderUnavailableError extends Error {
+    constructor(message: string);
+}
+/**
+ * The exact error message thrown when no provider can be auto-selected.
+ * D.AC4 requires that all three remediation paths be named.
+ */
+export declare const NO_PROVIDER_AVAILABLE_MESSAGE: string;