agentic-qe 3.12.0 → 3.12.2

package/dist/shared/llm/providers/claude-code.js

@@ -0,0 +1,312 @@
+/**
+ * Agentic QE v3 — Claude Code (subscription) Provider (ADR-123, issue #557)
+ *
+ * Runs QE analysis on the user's Claude Pro/Max subscription by shelling out
+ * to the Claude Code CLI (`claude -p --output-format json`) instead of calling
+ * `api.anthropic.com` with a paid API key. The CLI authenticates with the
+ * user's existing OAuth login and draws from the subscription's shared usage
+ * allowance, so the worst case is "hit the plan rate limit and pause" rather
+ * than a surprise per-token bill.
+ *
+ * LOAD-BEARING: the child process env has ANTHROPIC_API_KEY / CLAUDE_API_KEY /
+ * ANTHROPIC_AUTH_TOKEN stripped. If any is present, the CLI silently reverts
+ * to API-key billing and this provider would be a lie. `parity` test coverage
+ * asserts the strip.
+ */
+import { spawn } from 'node:child_process';
+import { createLLMError, } from '../interfaces';
+import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
+/** Env vars whose presence flips the CLI from subscription to API billing. */
+export const API_BILLING_ENV_VARS = [
+    'ANTHROPIC_API_KEY',
+    'CLAUDE_API_KEY',
+    'ANTHROPIC_AUTH_TOKEN',
+];
+export const DEFAULT_CLAUDE_CODE_CONFIG = {
+    model: 'sonnet',
+    maxTokens: 4096,
+    temperature: 0.7,
+    timeoutMs: 120000,
+    maxRetries: 1,
+    binaryPath: 'claude',
+    maxConcurrency: 2,
+    disallowedTools: ['Bash', 'Edit', 'Write', 'NotebookEdit', 'WebFetch', 'WebSearch', 'Task'],
+};
+export class ClaudeCodeProvider {
+    type = 'claude-code';
+    name = 'Claude Code (subscription)';
+    billingMode = 'subscription';
+    config;
+    requestId = 0;
+    availabilityCache;
+    active = 0;
+    queue = [];
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CLAUDE_CODE_CONFIG, ...config };
+        const envConc = Number.parseInt(process.env.AQE_CLAUDE_CODE_CONCURRENCY ?? '', 10);
+        if (Number.isFinite(envConc) && envConc > 0) {
+            this.config.maxConcurrency = envConc;
+        }
+    }
+    async isAvailable() {
+        // Cache for 60s — spawning `claude --version` per call is wasteful.
+        const now = Date.now();
+        if (this.availabilityCache && now - this.availabilityCache.at < 60_000) {
+            return this.availabilityCache.available;
+        }
+        let available = false;
+        try {
+            const { code } = await this.runProcess(['--version'], undefined, 5000);
+            available = code === 0;
+        }
+        catch {
+            available = false;
+        }
+        this.availabilityCache = { at: now, available };
+        return available;
+    }
+    async healthCheck() {
+        const start = Date.now();
+        const available = await this.isAvailable();
+        const latencyMs = Date.now() - start;
+        if (!available) {
+            return {
+                healthy: false,
+                latencyMs,
+                error: `Claude Code CLI ("${this.config.binaryPath}") not found or not runnable. ` +
+                    `Install Claude Code and log in with your Pro/Max account.`,
+            };
+        }
+        return {
+            healthy: true,
+            latencyMs,
+            models: this.getSupportedModels(),
+            details: { binaryPath: this.config.binaryPath, billing: 'subscription' },
+        };
+    }
+    async generate(input, options) {
+        const model = this.toCliModel(options?.model ?? this.config.model);
+        const requestId = `claude-code-${++this.requestId}-${Date.now()}`;
+        const { prompt, systemPrompt } = this.flatten(input, options?.systemPrompt);
+        const args = ['-p', '--output-format', 'json', '--model', model];
+        if (systemPrompt) {
+            args.push('--append-system-prompt', systemPrompt);
+        }
+        const disallowed = this.config.disallowedTools ?? [];
+        if (disallowed.length > 0) {
+            args.push('--disallowedTools', ...disallowed);
+        }
+        const start = Date.now();
+        const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs ?? 120000;
+        const { code, stdout, stderr } = await this.withConcurrency(() => this.runProcess(args, prompt, timeoutMs));
+        const latencyMs = Date.now() - start;
+        if (code !== 0 && !stdout.trim()) {
+            throw this.classifyError(stderr || `claude exited with code ${code}`, model);
+        }
+        let data;
+        try {
+            data = JSON.parse(stdout);
+        }
+        catch {
+            throw createLLMError(`Could not parse claude -p JSON output: ${stdout.slice(0, 200)}`, 'PROVIDER_UNAVAILABLE', { provider: 'claude-code', model, retryable: true });
+        }
+        if (data.is_error) {
+            throw this.classifyError(data.result ?? data.api_error_status ?? 'claude error', model);
+        }
+        const u = data.usage ?? {};
+        const usage = {
+            promptTokens: u.input_tokens ?? 0,
+            completionTokens: u.output_tokens ?? 0,
+            totalTokens: (u.input_tokens ?? 0) + (u.output_tokens ?? 0),
+            cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+            cacheReadTokens: u.cache_read_input_tokens ?? 0,
+        };
+        // The concrete model that actually served the request (modelUsage key).
+        const resolvedModel = (data.modelUsage && Object.keys(data.modelUsage)[0]) || model;
+        TokenMetricsCollector.recordTokenUsage(requestId, 'claude-code-provider', 'llm', 'generate', {
+            inputTokens: usage.promptTokens,
+            outputTokens: usage.completionTokens,
+            totalTokens: usage.totalTokens,
+            // Subscription: no marginal API charge. total_cost_usd is the
+            // API-equivalent figure, recorded for visibility only, not billed.
+            estimatedCostUsd: 0,
+        });
+        return {
+            content: data.result ?? '',
+            model: resolvedModel,
+            provider: 'claude-code',
+            usage,
+            // Subscription billing: marginal monetary cost is $0. The figure is
+            // authoritative (we know the subscription doesn't bill per token), so
+            // it's a provider receipt, not a local estimate.
+            cost: { inputCost: 0, outputCost: 0, totalCost: 0, currency: 'USD', source: 'provider-receipt' },
+            latencyMs,
+            finishReason: this.mapFinishReason(data.stop_reason),
+            cached: false,
+            requestId,
+        };
+    }
+    async embed(_text, _options) {
+        throw createLLMError('Claude Code provider does not support embeddings. Use openai, ollama, or cognitum.', 'MODEL_NOT_FOUND', { provider: 'claude-code', retryable: false });
+    }
+    async complete(prompt, options) {
+        const response = await this.generate(prompt, {
+            model: options?.model,
+            temperature: options?.temperature ?? 0.2,
+            maxTokens: options?.maxTokens ?? 256,
+        });
+        return {
+            completion: response.content,
+            model: response.model,
+            provider: 'claude-code',
+            usage: response.usage,
+            latencyMs: response.latencyMs,
+            cached: response.cached,
+        };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    getSupportedModels() {
+        return ['opus', 'sonnet', 'haiku'];
+    }
+    getCostPerToken() {
+        // Subscription — no per-token monetary cost.
+        return { input: 0, output: 0 };
+    }
+    async dispose() {
+        // No persistent resources.
+    }
+    // -- internals -------------------------------------------------------------
+    /** Map an AQE canonical/model id to a CLI alias the `claude` binary accepts. */
+    toCliModel(model) {
+        const m = model.toLowerCase();
+        if (m.includes('opus'))
+            return 'opus';
+        if (m.includes('haiku'))
+            return 'haiku';
+        if (m.includes('sonnet'))
+            return 'sonnet';
+        return model;
+    }
+    flatten(input, systemPromptOpt) {
+        if (typeof input === 'string') {
+            return { prompt: input, systemPrompt: systemPromptOpt };
+        }
+        const systemParts = input.filter((m) => m.role === 'system').map((m) => m.content);
+        if (systemPromptOpt)
+            systemParts.unshift(systemPromptOpt);
+        const convo = input
+            .filter((m) => m.role !== 'system')
+            .map((m) => `${m.role === 'assistant' ? 'Assistant' : 'User'}: ${m.content}`)
+            .join('\n\n');
+        return {
+            prompt: convo,
+            systemPrompt: systemParts.length > 0 ? systemParts.join('\n\n') : undefined,
+        };
+    }
+    mapFinishReason(reason) {
+        switch (reason) {
+            case 'max_tokens':
+                return 'length';
+            case 'end_turn':
+            case 'stop_sequence':
+            default:
+                return 'stop';
+        }
+    }
+    classifyError(message, model) {
+        const lower = message.toLowerCase();
+        if (lower.includes('rate limit') ||
+            lower.includes('usage limit') ||
+            lower.includes('429') ||
+            lower.includes('quota')) {
+            // The *desired* failure mode: plan limit reached → pause and retry later.
+            return createLLMError(message, 'RATE_LIMITED', {
+                provider: 'claude-code',
+                model,
+                retryable: true,
+                retryAfterMs: 60_000,
+            });
+        }
+        return createLLMError(message, 'PROVIDER_UNAVAILABLE', {
+            provider: 'claude-code',
+            model,
+            retryable: true,
+        });
+    }
+    /**
+     * Build the child env with API-billing keys stripped (LOAD-BEARING).
+     * Exported logic tested by parity/env-strip tests.
+     */
+    static childEnv(base = process.env) {
+        const env = { ...base };
+        for (const key of API_BILLING_ENV_VARS) {
+            delete env[key];
+        }
+        return env;
+    }
+    runProcess(args, stdin, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.config.binaryPath ?? 'claude', args, {
+                env: ClaudeCodeProvider.childEnv(),
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.kill('SIGKILL');
+                reject(createLLMError('claude -p timed out', 'TIMEOUT', {
+                    provider: 'claude-code',
+                    retryable: true,
+                }));
+            }, timeoutMs);
+            child.stdout.on('data', (d) => (stdout += d.toString()));
+            child.stderr.on('data', (d) => (stderr += d.toString()));
+            child.on('error', (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(createLLMError(`Failed to spawn claude: ${err.message}`, 'PROVIDER_UNAVAILABLE', {
+                    provider: 'claude-code',
+                    retryable: false,
+                    cause: err,
+                }));
+            });
+            child.on('close', (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ code: code ?? 0, stdout, stderr });
+            });
+            if (stdin !== undefined) {
+                child.stdin.write(stdin);
+            }
+            child.stdin.end();
+        });
+    }
+    /** Simple semaphore so we don't spawn unbounded `claude` subprocesses. */
+    async withConcurrency(fn) {
+        const limit = this.config.maxConcurrency ?? 2;
+        if (this.active >= limit) {
+            await new Promise((resolve) => this.queue.push(resolve));
+        }
+        this.active++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.active--;
+            const next = this.queue.shift();
+            if (next)
+                next();
+        }
+    }
+}
+//# sourceMappingURL=claude-code.js.map

package/dist/shared/llm/providers/cognitum.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Agentic QE v3 — Cognitum Provider (ADR-123)
+ *
+ * api.cognitum.one is an OpenAI-compatible (and Anthropic-compatible) LLM
+ * gateway with two properties that matter for issue #557:
+ *   1. Every response carries an `x_cognitum` receipt with an authoritative
+ *      per-request `price_usd` — so cost is a provider receipt, not a local
+ *      price-table estimate.
+ *   2. It enforces a server-side hard spend cap (`/v1/usage` → `hardCapUsd`),
+ *      so the worst case is "provider pauses at the cap", not a surprise bill.
+ *
+ * Models are tiers (`cognitum-auto|low|mid|high`); the gateway resolves each
+ * to a concrete model and reports it back in the receipt (`resolved_model`).
+ */
+import { LLMProvider, LLMProviderType, BillingMode, CognitumConfig, Message, GenerateOptions, EmbedOptions, CompleteOptions, LLMResponse, EmbeddingResponse, CompletionResponse, HealthCheckResult } from '../interfaces';
+export type { CognitumConfig };
+export declare const DEFAULT_COGNITUM_CONFIG: CognitumConfig;
+/** Server-side budget snapshot from GET /v1/usage. */
+export interface CognitumBudget {
+    servingBudgetUsd: number;
+    hardCapUsd: number;
+    committedUsd: number;
+    headroomUsd: number;
+    status: string;
+    headroomExhausted: boolean;
+}
+export declare class CognitumProvider implements LLMProvider {
+    readonly type: LLMProviderType;
+    readonly name: string;
+    readonly billingMode: BillingMode;
+    private config;
+    private requestId;
+    constructor(config?: Partial<CognitumConfig>);
+    isAvailable(): Promise<boolean>;
+    healthCheck(): Promise<HealthCheckResult>;
+    generate(input: string | Message[], options?: GenerateOptions): Promise<LLMResponse>;
+    embed(text: string, options?: EmbedOptions): Promise<EmbeddingResponse>;
+    complete(prompt: string, options?: CompleteOptions): Promise<CompletionResponse>;
+    getConfig(): CognitumConfig;
+    getSupportedModels(): string[];
+    getCostPerToken(): {
+        input: number;
+        output: number;
+    };
+    dispose(): Promise<void>;
+    /**
+     * ADR-123: read the provider's server-side budget so `aqe health` and the
+     * billing notice can show real remaining headroom. Returns undefined on any
+     * failure (best-effort — never throws).
+     */
+    getRemoteBudget(): Promise<CognitumBudget | undefined>;
+    /** Build a CostInfo from the authoritative receipt price. */
+    private receiptCost;
+    private getApiKey;
+    private getBaseUrl;
+    private getHeaders;
+    private formatMessages;
+    private mapFinishReason;
+    private toApiError;
+    private fetchWithTimeout;
+    private fetchWithRetry;
+    private sleep;
+}
+//# sourceMappingURL=cognitum.d.ts.map