@njeybe/nativ 2.0.0

package/dist/mcp/server.js

@@ -0,0 +1,309 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { runTaskList, runTaskNext, runTaskStart, runTaskComplete, runTaskBlock, runTaskEscalate, runTaskAdd, runTaskProposePatch, } from '../commands/task.js';
+import { SUBAGENT_TYPES } from '../scanner/types.js';
+import { runInit } from '../commands/init.js';
+import { runStatus } from '../commands/status.js';
+import { runDoctor } from '../commands/doctor.js';
+import { runWorktreeCreate, runWorktreeList, runWorktreeMerge, runWorktreeRemove, } from '../commands/worktree.js';
+import { runDbStatus, runDbInspect, runDbDiff } from '../commands/db.js';
+import { runVerify } from '../commands/verify.js';
+import { runTestGen } from '../commands/test-gen.js';
+import { runBench } from '../commands/bench.js';
+import { TEST_FRAMEWORKS } from '../core/test-generator-types.js';
+import { packageVersion } from '../core/version.js';
+/**
+ * Native MCP (Model Context Protocol) server for Nativ over stdio.
+ *
+ * stdout is reserved for JSON-RPC frames, so the existing CLI handlers (which print via console.*)
+ * run inside `captureOutput`, which collects their output and returns it as tool content.
+ * Air-gap: only masked, structure-only commands are exposed. `db sync`, `db ui` and `init --force`
+ * are intentionally absent, and every tool is bound to the server's project root.
+ */
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+const ESCALATION_TYPES = [
+    'contract_drift',
+    'schema_flaw',
+    'missing_credential',
+    'dependency_conflict',
+    'architectural_ambiguity',
+];
+const RESOURCES = [
+    { name: 'context', uris: ['nativ://context'], file: 'context.md', mimeType: 'text/markdown', description: 'Project context, tech stack and guardrails (.ai/context.md)' },
+    { name: 'master-plan', uris: ['nativ://master-plan'], file: 'master_plan.json', mimeType: 'application/json', description: 'Milestones, tasks and their status (.ai/master_plan.json)' },
+    { name: 'db-schema', uris: ['nativ://db-schema'], file: 'db_schema.json', mimeType: 'application/json', description: 'Database schema contract (.ai/db_schema.json)' },
+    { name: 'api-contracts', uris: ['nativ://api-contracts'], file: 'api_contracts.json', mimeType: 'application/json', description: 'API route and schema contracts (.ai/api_contracts.json)' },
+    { name: 'escalation', uris: ['nativ://escalation'], file: 'escalation.json', mimeType: 'application/json', description: 'Tier-1 escalation records (.ai/escalation.json)' },
+    { name: 'telemetry', uris: ['nativ://telemetry'], file: 'telemetry.json', mimeType: 'application/json', description: 'Execution duration, token usage and cost telemetry (.ai/telemetry.json)' },
+];
+// Handlers share global console/process.exitCode state, so captured runs are serialized.
+let captureQueue = Promise.resolve();
+function captureOutput(fn, options = {}) {
+    const run = async () => {
+        const lines = [];
+        const collect = (...args) => {
+            lines.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a, null, 2))).join(' '));
+        };
+        const original = { log: console.log, error: console.error, warn: console.warn, info: console.info };
+        const previousExitCode = process.exitCode;
+        process.exitCode = undefined;
+        console.log = console.error = console.warn = console.info = collect;
+        let failed = false;
+        try {
+            await fn();
+            failed = options.errorOnExitCode !== false && process.exitCode !== undefined && process.exitCode !== 0;
+        }
+        catch (err) {
+            failed = true;
+            lines.push(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            Object.assign(console, original);
+            process.exitCode = previousExitCode;
+        }
+        const text = lines.join('\n').replace(ANSI_PATTERN, '').trim() || '(no output)';
+        return { content: [{ type: 'text', text }], isError: failed || undefined };
+    };
+    const result = captureQueue.then(run, run);
+    captureQueue = result.catch(() => undefined);
+    return result;
+}
+export function createMcpServer(targetDirArg) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    const server = new McpServer({ name: 'nativ', version: packageVersion() });
+    function registerNativTool(baseName, meta, handler) {
+        server.registerTool(`nativ_${baseName}`, meta, handler);
+    }
+    // ─── Task lifecycle tools ──────────────────────────────────────────────────
+    registerNativTool('task_next', {
+        description: 'Get the next executable task in the active milestone, with its role guide and JIT contract slice (JSON).',
+        inputSchema: {},
+    }, () => captureOutput(() => runTaskNext(targetDir, { json: true })));
+    registerNativTool('task_list', {
+        description: 'List project tasks from .ai/master_plan.json with optional filters (JSON).',
+        inputSchema: {
+            available: z.boolean().optional().describe('Only tasks that are unblocked and ready for execution'),
+            status: z.enum(['pending', 'in_progress', 'completed', 'blocked']).optional().describe('Filter by task status'),
+            milestone: z.string().optional().describe('Filter by milestone ID or name'),
+            fastPath: z.boolean().optional().describe('Only fast-path tasks'),
+        },
+    }, ({ available, status, milestone, fastPath }) => captureOutput(() => runTaskList(targetDir, { available, status, milestone, fastPath, json: true })));
+    registerNativTool('task_add', {
+        description: 'Append a task to .ai/master_plan.json with an auto-incremented ID (JSON). Goes to the given milestone, else the active one; ' +
+            'fastPath routes it to the fast-path milestone (created on first use).',
+        inputSchema: {
+            title: z.string().min(1).describe('Task title'),
+            description: z.string().optional().describe('What the task must accomplish'),
+            assignedSubagent: z.enum(SUBAGENT_TYPES).optional().describe('Sub-agent role (default backend)'),
+            milestone: z.string().optional().describe('Target milestone ID or name'),
+            verificationCommand: z.string().optional().describe('Command the task complete gatekeeper runs'),
+            targetFiles: z.array(z.string()).optional().describe('Files the task may modify'),
+            dependencies: z.array(z.string()).optional().describe('Task IDs that must be completed first'),
+            fastPath: z.boolean().optional().describe('Route to the fast-path track'),
+        },
+    }, ({ title, description, assignedSubagent, milestone, verificationCommand, targetFiles, dependencies, fastPath }) => captureOutput(() => runTaskAdd(title, targetDir, {
+        description,
+        agent: assignedSubagent,
+        milestone,
+        verify: verificationCommand,
+        files: targetFiles,
+        deps: dependencies,
+        fastPath,
+        json: true,
+    })));
+    registerNativTool('task_start', {
+        description: 'Mark a task as in_progress.',
+        inputSchema: { taskId: z.string().min(1).describe('Task ID, e.g. task-12') },
+    }, ({ taskId }) => captureOutput(() => runTaskStart(taskId, targetDir)));
+    registerNativTool('task_complete', {
+        description: "Mark a task as completed (automatically executes its verificationCommand unless skipVerify is true). Advances the milestone when all its tasks are done.",
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+            notes: z.string().optional().describe('Completion notes or summary'),
+            skipVerify: z.boolean().optional().describe('Skip automated verification command execution'),
+        },
+    }, ({ taskId, notes, skipVerify }) => captureOutput(() => runTaskComplete(taskId, targetDir, { notes, skipVerify })));
+    registerNativTool('verify', {
+        description: "Run verification commands on demand for a task, milestone, or all completed tasks without changing task status.",
+        inputSchema: {
+            taskId: z.string().optional().describe('Task ID to verify. Defaults to active in_progress task.'),
+            milestone: z.string().optional().describe('Filter by milestone ID or name'),
+            all: z.boolean().optional().describe('Run verification commands for all completed tasks to detect regressions'),
+        },
+    }, ({ taskId, milestone, all }) => captureOutput(() => runVerify(taskId, targetDir, { milestone, all, json: true })));
+    registerNativTool('task_block', {
+        description: 'Mark a task as blocked with a required reason (e.g. verification failed after 3 attempts).',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+            reason: z.string().min(1).describe('Why the task is blocked'),
+        },
+    }, ({ taskId, reason }) => captureOutput(() => runTaskBlock(taskId, reason, targetDir)));
+    registerNativTool('task_escalate', {
+        description: 'Escalate a contract or architectural blocker to the Architect (writes .ai/escalation.json and blocks the task).',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+            type: z.enum(ESCALATION_TYPES).describe('Escalation type'),
+            details: z.string().min(1).describe('Explanation of the contract gap or blocker'),
+            affected: z.array(z.string()).optional().describe('Affected contract paths, e.g. [".ai/db_schema.json"]'),
+        },
+    }, ({ taskId, type, details, affected }) => captureOutput(() => runTaskEscalate(taskId, targetDir, { type, details, affected: affected?.join(',') })));
+    registerNativTool('task_propose_patch', {
+        description: 'Propose an atomic modification to .ai/db_schema.json or .ai/api_contracts.json. ' +
+            'Evaluated deterministically by the Contract Governor. Additive changes are auto-approved; ' +
+            'destructive changes are rejected and trip the Circuit Breaker on 3 failures.',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+            target: z.enum(['db_schema', 'api_contracts']).describe('Target contract to patch'),
+            operation: z.enum(['ADD', 'ALTER', 'DROP', 'RENAME']).describe('Operation type'),
+            path: z.string().min(1).describe('Dot-notation path to modify (e.g. users.columns.phone)'),
+            value: z.any().optional().describe('Value or schema definition to apply'),
+            reason: z.string().min(1).describe('Technical rationale for proposing this patch'),
+            baseHash: z.string().optional().describe('Base schema hash to prevent concurrent dirty writes'),
+        },
+    }, ({ taskId, target, operation, path: targetPath, value, reason, baseHash }) => captureOutput(() => runTaskProposePatch(targetDir, {
+        taskId,
+        target,
+        operation,
+        path: targetPath,
+        value,
+        reason,
+        baseHash,
+        json: true,
+    })));
+    // ─── Worktree lifecycle tools ──────────────────────────────────────────────
+    registerNativTool('worktree_create', {
+        description: 'Create an isolated Git worktree branch for a task with mounted .ai/ contracts (JSON).',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+        },
+    }, ({ taskId }) => captureOutput(() => runWorktreeCreate(taskId, targetDir, { json: true })));
+    registerNativTool('worktree_list', {
+        description: 'List active agent Git worktrees and their branch mapping (JSON).',
+        inputSchema: {},
+    }, () => captureOutput(() => runWorktreeList(targetDir, { json: true })));
+    registerNativTool('worktree_merge', {
+        description: 'Merge an agent worktree branch into the base branch (enforces Safe Merge Gatekeeper unless force is true).',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+            force: z.boolean().optional().describe('Bypass Safe Merge Gatekeeper checks'),
+        },
+    }, ({ taskId, force }) => captureOutput(() => runWorktreeMerge(taskId, targetDir, { force, json: true })));
+    registerNativTool('worktree_remove', {
+        description: 'Safely remove an agent worktree and discard its branch without merging.',
+        inputSchema: {
+            taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
+            force: z.boolean().optional().describe('Force removal'),
+        },
+    }, ({ taskId, force }) => captureOutput(() => runWorktreeRemove(taskId, targetDir, { force, json: true })));
+    // ─── Workspace tools ───────────────────────────────────────────────────────
+    registerNativTool('init', {
+        description: 'Scaffold the .ai/ workflow (contracts, master plan, sub-agents, directives). Never overwrites existing files.',
+        inputSchema: {},
+    }, () => captureOutput(() => runInit(targetDir, { force: false })));
+    registerNativTool('status', {
+        description: 'Summarize execution progress across all milestones and tasks.',
+        inputSchema: {},
+    }, () => captureOutput(() => runStatus(targetDir)));
+    registerNativTool('doctor', {
+        description: 'Read-only health check of the Claude Code integration: MCP server, hooks, permissions, agents, enforcement mode and provider availability (JSON). ' +
+            'Reports drift but never repairs it; repairing is `nativ doctor --fix` in a terminal.',
+        inputSchema: {},
+    }, 
+    // A report that lists problems is still a successful report, not a tool failure.
+    () => captureOutput(async () => runDoctor(targetDir, { json: true }), { errorOnExitCode: false }));
+    // ─── Database telemetry tools (masked, structure-only) ─────────────────────
+    registerNativTool('db_status', {
+        description: 'Dev/Prod database connection health, engine, latency and table count. URLs are masked; no credentials are returned.',
+        inputSchema: {},
+    }, 
+    // An offline database is a valid status report, not a tool failure.
+    () => captureOutput(() => runDbStatus(targetDir, { json: true }), { errorOnExitCode: false }));
+    registerNativTool('db_inspect', {
+        description: 'Introspect live database structure (tables, columns, types, keys, indexes). Structure only; never reads row data.',
+        inputSchema: {
+            env: z.enum(['dev', 'prod']).optional().describe('Environment to inspect (default dev)'),
+            table: z.string().optional().describe('Only return a single table or collection'),
+        },
+    }, ({ env, table }) => captureOutput(() => runDbInspect(targetDir, { env: env ?? 'dev', table, json: true })));
+    registerNativTool('db_diff', {
+        description: 'Compute schema drift from the Dev database to .ai/db_schema.json (target "contract", default) or to Prod.',
+        inputSchema: {
+            target: z.enum(['contract', 'prod']).optional().describe('Comparison target (default contract)'),
+        },
+    }, ({ target }) => captureOutput(() => runDbDiff(targetDir, { target: target ?? 'contract', json: true })));
+    // ─── Test generation ─────────────────────────────────────────────────────
+    registerNativTool('test_gen', {
+        description: 'Generate API contract and DB integrity test suites from .ai/api_contracts.json and .ai/db_schema.json (JSON result). ' +
+            'Writes into the project unless dryRun is true; never overwrites files it did not generate.',
+        inputSchema: {
+            output: z.string().optional().describe('Output directory relative to the project (default tests/contract)'),
+            framework: z.enum(TEST_FRAMEWORKS).optional().describe('Test framework (default vitest)'),
+            baseUrl: z.string().optional().describe('Base URL the API suites call (default http://localhost:3000)'),
+            dryRun: z.boolean().optional().describe('Return the generated files without writing them'),
+        },
+    }, async ({ output, framework, baseUrl, dryRun }) => {
+        if (output) {
+            const rel = path.relative(targetDir, path.resolve(targetDir, output));
+            if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+                return { content: [{ type: 'text', text: 'Error: output must be a subdirectory of the project.' }], isError: true };
+            }
+        }
+        return captureOutput(() => runTestGen(targetDir, { output, framework, baseUrl, dryRun, json: true }));
+    });
+    // ─── Synthetic Benchmark Matrix ──────────────────────────────────────────
+    registerNativTool('bench', {
+        description: 'Run synthetic evaluation benchmarks across concurrency, invariants, verifications, and telemetry (JSON report).',
+        inputSchema: {
+            scenario: z
+                .enum(['all', 'concurrency', 'governor', 'verification', 'telemetry', 'e2e'])
+                .optional()
+                .describe('Target scenario to benchmark (default all)'),
+            concurrency: z.number().optional().describe('Number of simulated concurrent agent workers (default 6)'),
+        },
+    }, async ({ scenario, concurrency }) => captureOutput(() => runBench(targetDir, { scenario, concurrency, json: true })));
+    // ─── Contract resources ────────────────────────────────────────────────────
+    for (const res of RESOURCES) {
+        for (const uriStr of res.uris) {
+            server.registerResource(res.name, uriStr, { mimeType: res.mimeType, description: res.description }, async (uri) => {
+                const filePath = path.join(targetDir, '.ai', res.file);
+                let text;
+                if (fs.existsSync(filePath)) {
+                    text = fs.readFileSync(filePath, 'utf8');
+                }
+                else if (res.name === 'escalation') {
+                    text = JSON.stringify({ escalations: [] }, null, 2);
+                }
+                else if (res.name === 'telemetry') {
+                    text = JSON.stringify({
+                        version: '1.0.0',
+                        summary: {
+                            totalTasksCompleted: 0,
+                            totalDurationMs: 0,
+                            estimatedTotalTokens: 0,
+                            estimatedTotalCostUsd: 0,
+                            verificationPassRate: 1.0,
+                            circuitBreakerTrips: 0,
+                        },
+                        tasks: [],
+                    }, null, 2);
+                }
+                else {
+                    throw new Error(`.ai/${res.file} not found in ${targetDir}. Run nativ_init first.`);
+                }
+                return { contents: [{ uri: uri.href, mimeType: res.mimeType, text }] };
+            });
+        }
+    }
+    return server;
+}
+export async function startMcpServer(targetDirArg) {
+    // Keep stray console.log calls off stdout, which carries the JSON-RPC stream.
+    console.log = console.info = console.error;
+    const server = createMcpServer(targetDirArg);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Nativ MCP server running on stdio (project: ${path.resolve(targetDirArg || process.cwd())})`);
+}

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

@@ -0,0 +1,5 @@
+import { type Provider, type ProviderDeps } from './types.js';
+export declare const CLAUDE_API_DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+/** Resolves the key from .env files or the environment. The value never leaves this module. */
+export declare function resolveAnthropicApiKey(root: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function createClaudeApiProvider(deps?: ProviderDeps): Provider;

package/dist/providers/claude-api.js

@@ -0,0 +1,75 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { loadEnvFiles } from '../db/env-parser.js';
+import { ProviderError, stripJsonFence, } from './types.js';
+export const CLAUDE_API_DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Resolves the key from .env files or the environment. The value never leaves this module. */
+export function resolveAnthropicApiKey(root, env = process.env) {
+    try {
+        const key = loadEnvFiles(root).ANTHROPIC_API_KEY || env.ANTHROPIC_API_KEY;
+        if (typeof key === 'string' && key.trim().length > 0)
+            return key.trim();
+    }
+    catch {
+        // Air-gap guard: an unreadable env file means "no key", never an error that could echo its contents.
+    }
+    return null;
+}
+function retryAfterMs(err) {
+    const headers = err?.headers;
+    const raw = headers instanceof Headers ? headers.get('retry-after') : headers?.['retry-after'];
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : undefined;
+}
+export function createClaudeApiProvider(deps = {}) {
+    const env = deps.env ?? process.env;
+    let client = null;
+    const getClient = (root) => {
+        if (deps.anthropicClient)
+            return deps.anthropicClient();
+        if (!client) {
+            const apiKey = resolveAnthropicApiKey(root, env);
+            if (!apiKey)
+                throw new ProviderError('NO_CREDENTIALS', 'ANTHROPIC_API_KEY is not set.');
+            client = new Anthropic({ apiKey });
+        }
+        return client;
+    };
+    return {
+        id: 'claude-api',
+        defaultModel: CLAUDE_API_DEFAULT_MODEL,
+        hasCredentials(root) {
+            return deps.anthropicClient !== undefined || resolveAnthropicApiKey(root, env) !== null;
+        },
+        async complete(request, root) {
+            const sdk = getClient(root);
+            const timeout = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            try {
+                const reply = await sdk.messages.create({
+                    model: request.model ?? CLAUDE_API_DEFAULT_MODEL,
+                    max_tokens: 2048,
+                    ...(request.system ? { system: request.system } : {}),
+                    messages: [{ role: 'user', content: request.prompt }],
+                }, { timeout });
+                const text = reply.content.filter((block) => block.type === 'text').map((block) => block.text ?? '').join('');
+                if (!text.trim())
+                    throw new ProviderError('BAD_RESPONSE', 'Claude returned an empty result.');
+                return request.json ? stripJsonFence(text) : text;
+            }
+            catch (err) {
+                if (err instanceof ProviderError)
+                    throw err;
+                const status = err?.status;
+                const name = err?.name ?? '';
+                const message = err instanceof Error ? err.message : String(err);
+                if (status === 429 || status === 529)
+                    throw new ProviderError('RATE_LIMITED', message.slice(0, 300), retryAfterMs(err));
+                if (status === 401 || status === 403)
+                    throw new ProviderError('NO_CREDENTIALS', 'The Anthropic API key was rejected.');
+                if (/timeout|timed out/i.test(name + message))
+                    throw new ProviderError('TIMEOUT', `Claude did not answer within ${timeout}ms.`);
+                throw new ProviderError('BAD_RESPONSE', message.slice(0, 300));
+            }
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type Provider, type ProviderDeps } from './types.js';
+/** Alias understood by `claude --model`; cheap and fast enough for background triage. */
+export declare const CLAUDE_CLI_DEFAULT_MODEL = "haiku";
+/** Set on every child so a nested nativ hook, MCP server or provider never recurses into another call. */
+export declare const PROVIDER_CHILD_ENV = "NATIV_PROVIDER_CHILD";
+/** Default wait when the CLI reports a usage limit without saying when it resets. */
+export declare const DEFAULT_LIMIT_COOLDOWN_MS: number;
+/**
+ * Pulls a reset time out of a limit message when there is one: an epoch after a pipe
+ * ("Claude usage limit reached|1760000000"), the format Claude Code has used for subscription limits.
+ */
+export declare function parseLimitRetryAfter(text: string, now: number): number | undefined;
+export declare function createClaudeCliProvider(deps?: ProviderDeps): Provider;

package/dist/providers/claude-cli.js

@@ -0,0 +1,134 @@
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ProviderError, stripJsonFence, } from './types.js';
+/** Alias understood by `claude --model`; cheap and fast enough for background triage. */
+export const CLAUDE_CLI_DEFAULT_MODEL = 'haiku';
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Set on every child so a nested nativ hook, MCP server or provider never recurses into another call. */
+export const PROVIDER_CHILD_ENV = 'NATIV_PROVIDER_CHILD';
+let neutralCwd = null;
+/**
+ * A scratch directory with no project files. Running from here keeps the child from loading this
+ * project's CLAUDE.md, hooks, settings and MCP servers, which would slow the call and could loop back into nativ.
+ */
+function neutralWorkingDirectory() {
+    if (neutralCwd && fs.existsSync(neutralCwd))
+        return neutralCwd;
+    neutralCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'nativ-provider-'));
+    return neutralCwd;
+}
+function defaultHasBinary(name) {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        return spawnSync(probe, [name], { stdio: 'ignore' }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultSpawn(command, args, request) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        // No shell: the prompt travels over stdin and arguments are passed verbatim, so nothing is re-quoted or interpreted.
+        const child = spawn(command, args, { cwd: request.cwd, env: request.env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, request.timeoutMs);
+        child.stdout.setEncoding('utf8').on('data', (chunk) => (stdout += chunk));
+        child.stderr.setEncoding('utf8').on('data', (chunk) => (stderr += chunk));
+        child.on('error', (err) => finish({ code: null, stdout, stderr: err.message, timedOut: false, notFound: err.code === 'ENOENT' }));
+        child.on('close', (code) => finish({ code, stdout, stderr, timedOut }));
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(request.input);
+    });
+}
+/** Default wait when the CLI reports a usage limit without saying when it resets. */
+export const DEFAULT_LIMIT_COOLDOWN_MS = 20 * 60_000;
+const LIMIT_PATTERN = /usage limit|rate.?limit|limit reached|too many requests|overloaded|quota/i;
+/**
+ * Pulls a reset time out of a limit message when there is one: an epoch after a pipe
+ * ("Claude usage limit reached|1760000000"), the format Claude Code has used for subscription limits.
+ */
+export function parseLimitRetryAfter(text, now) {
+    const epoch = /\|(\d{10})\b/.exec(text);
+    if (!epoch)
+        return undefined;
+    const wait = Number(epoch[1]) * 1000 - now;
+    return wait > 0 ? wait : undefined;
+}
+export function createClaudeCliProvider(deps = {}) {
+    const run = deps.spawn ?? defaultSpawn;
+    const hasBinary = deps.hasBinary ?? defaultHasBinary;
+    const now = deps.now ?? Date.now;
+    const baseEnv = deps.env ?? process.env;
+    return {
+        id: 'claude-cli',
+        defaultModel: CLAUDE_CLI_DEFAULT_MODEL,
+        // A Claude Code login lives in the CLI's own store; the binary being present is the best offline signal we have.
+        hasCredentials() {
+            if (baseEnv[PROVIDER_CHILD_ENV] === '1')
+                return false;
+            return hasBinary('claude');
+        },
+        async complete(request) {
+            if (baseEnv[PROVIDER_CHILD_ENV] === '1') {
+                throw new ProviderError('NO_CREDENTIALS', 'Refusing to start Claude from inside a nativ provider call.');
+            }
+            const args = [
+                '-p',
+                '--output-format', 'json',
+                '--model', request.model ?? CLAUDE_CLI_DEFAULT_MODEL,
+                '--tools', '',
+                '--strict-mcp-config',
+                '--no-session-persistence',
+            ];
+            if (request.system)
+                args.push('--system-prompt', request.system);
+            const result = await run('claude', args, {
+                cwd: neutralWorkingDirectory(),
+                env: { ...baseEnv, [PROVIDER_CHILD_ENV]: '1' },
+                input: request.prompt,
+                timeoutMs: request.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            });
+            if (result.notFound)
+                throw new ProviderError('NO_CREDENTIALS', 'The claude executable was not found on PATH.');
+            if (result.timedOut)
+                throw new ProviderError('TIMEOUT', `Claude did not answer within ${request.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms.`);
+            let parsed = null;
+            try {
+                parsed = JSON.parse(result.stdout);
+            }
+            catch {
+                parsed = null;
+            }
+            const text = typeof parsed?.result === 'string' ? parsed.result : '';
+            const failed = result.code !== 0 || parsed === null || parsed.is_error === true;
+            if (failed) {
+                const detail = `${text} ${result.stderr}`.trim();
+                if (parsed?.api_error_status === 429 || LIMIT_PATTERN.test(detail)) {
+                    throw new ProviderError('RATE_LIMITED', detail.slice(0, 300) || 'Claude usage limit reached.', parseLimitRetryAfter(detail, now()) ?? DEFAULT_LIMIT_COOLDOWN_MS);
+                }
+                if (/not logged in|please run .*login|invalid api key|authentication/i.test(detail)) {
+                    throw new ProviderError('NO_CREDENTIALS', 'Claude Code is not logged in. Run `claude` once to sign in.');
+                }
+                throw new ProviderError('BAD_RESPONSE', (detail || `claude exited with code ${result.code}`).slice(0, 300));
+            }
+            if (!text.trim())
+                throw new ProviderError('BAD_RESPONSE', 'Claude returned an empty result.');
+            return request.json ? stripJsonFence(text) : text;
+        },
+    };
+}

package/dist/providers/gemini.d.ts

@@ -0,0 +1,8 @@
+import { type Provider, type ProviderDeps } from './types.js';
+export declare const GEMINI_DEFAULT_MODEL = "gemini-3.8-flash";
+/**
+ * Resolves the Google/Gemini API key from .env files or the environment.
+ * Zero-credential air-gap: the returned key is never stored in contracts or responses.
+ */
+export declare function resolveGeminiApiKey(root: string, env?: NodeJS.ProcessEnv): string | null;
+export declare function createGeminiProvider(deps?: ProviderDeps): Provider;

package/dist/providers/gemini.js

@@ -0,0 +1,78 @@
+import { loadEnvFiles } from '../db/env-parser.js';
+import { ProviderError, stripJsonFence } from './types.js';
+export const GEMINI_DEFAULT_MODEL = 'gemini-3.8-flash';
+/** A stalled call aborts here and the caller falls through to the next provider. */
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Resolves the Google/Gemini API key from .env files or the environment.
+ * Zero-credential air-gap: the returned key is never stored in contracts or responses.
+ */
+export function resolveGeminiApiKey(root, env = process.env) {
+    try {
+        const envVars = loadEnvFiles(root);
+        const key = envVars.GEMINI_API_KEY || envVars.GOOGLE_API_KEY || env.GEMINI_API_KEY || env.GOOGLE_API_KEY;
+        if (typeof key === 'string' && key.trim().length > 0)
+            return key.trim();
+    }
+    catch {
+        // Air-gap guard: suppress file read errors
+    }
+    return null;
+}
+export function createGeminiProvider(deps = {}) {
+    const env = deps.env ?? process.env;
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    return {
+        id: 'gemini',
+        defaultModel: GEMINI_DEFAULT_MODEL,
+        hasCredentials(root) {
+            return resolveGeminiApiKey(root, env) !== null;
+        },
+        async complete(request, root) {
+            const apiKey = resolveGeminiApiKey(root, env);
+            if (!apiKey)
+                throw new ProviderError('NO_CREDENTIALS', 'GEMINI_API_KEY is not set.');
+            const model = request.model ?? GEMINI_DEFAULT_MODEL;
+            const timeout = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const text = request.system ? `${request.system}\n\n${request.prompt}` : request.prompt;
+            let res;
+            try {
+                // The key travels in a header, never the URL, so it cannot leak through logged or proxied URLs.
+                res = await doFetch(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', 'x-goog-api-key': apiKey },
+                    body: JSON.stringify({
+                        contents: [{ parts: [{ text }] }],
+                        generationConfig: { ...(request.json ? { responseMimeType: 'application/json' } : {}), temperature: 0.2 },
+                    }),
+                    signal: AbortSignal.timeout(timeout),
+                });
+            }
+            catch (err) {
+                const name = err?.name ?? '';
+                if (name === 'TimeoutError' || name === 'AbortError')
+                    throw new ProviderError('TIMEOUT', `Gemini did not answer within ${timeout}ms.`);
+                throw new ProviderError('BAD_RESPONSE', err instanceof Error ? err.message : String(err));
+            }
+            if (res.status === 429) {
+                const seconds = Number(res.headers.get('retry-after'));
+                throw new ProviderError('RATE_LIMITED', 'Gemini rate limit reached.', Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : undefined);
+            }
+            if (res.status === 401 || res.status === 403)
+                throw new ProviderError('NO_CREDENTIALS', 'The Gemini API key was rejected.');
+            if (!res.ok)
+                throw new ProviderError('BAD_RESPONSE', `Gemini responded with HTTP ${res.status}.`);
+            let body;
+            try {
+                body = (await res.json());
+            }
+            catch {
+                throw new ProviderError('BAD_RESPONSE', 'Gemini returned a body that is not JSON.');
+            }
+            const out = body.candidates?.[0]?.content?.parts?.[0]?.text;
+            if (!out)
+                throw new ProviderError('BAD_RESPONSE', 'Gemini returned no text.');
+            return request.json ? stripJsonFence(out) : out;
+        },
+    };
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './claude-cli.js';
+export * from './claude-api.js';
+export * from './gemini.js';
+export * from './registry.js';

package/dist/providers/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './claude-cli.js';
+export * from './claude-api.js';
+export * from './gemini.js';
+export * from './registry.js';