agentic-qe 3.12.1 → 3.12.3

package/dist/shared/llm/providers/cognitum.js

@@ -0,0 +1,369 @@
+/**
+ * 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 { createLLMError, } from '../interfaces';
+import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
+import { toError } from '../../error-utils.js';
+import { backoffDelay } from '../retry.js';
+export const DEFAULT_COGNITUM_CONFIG = {
+    model: 'cognitum-auto',
+    maxTokens: 4096,
+    temperature: 0.7,
+    timeoutMs: 60000,
+    maxRetries: 3,
+    enableCache: true,
+    enableCircuitBreaker: true,
+};
+export class CognitumProvider {
+    type = 'cognitum';
+    name = 'Cognitum';
+    billingMode = 'metered-capped';
+    config;
+    requestId = 0;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_COGNITUM_CONFIG, ...config };
+    }
+    async isAvailable() {
+        if (!this.getApiKey())
+            return false;
+        try {
+            return (await this.healthCheck()).healthy;
+        }
+        catch {
+            return false;
+        }
+    }
+    async healthCheck() {
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            return {
+                healthy: false,
+                error: 'API key not configured. Set COGNITUM_API_KEY environment variable.',
+            };
+        }
+        const start = Date.now();
+        try {
+            const response = await this.fetchWithTimeout(`${this.getBaseUrl()}/v1/models`, { method: 'GET', headers: this.getHeaders() }, 5000);
+            const latencyMs = Date.now() - start;
+            if (!response.ok) {
+                return { healthy: false, latencyMs, error: `API error: ${response.status}` };
+            }
+            return {
+                healthy: true,
+                latencyMs,
+                models: this.getSupportedModels(),
+                details: { billing: 'metered-capped', baseUrl: this.getBaseUrl() },
+            };
+        }
+        catch (error) {
+            return { healthy: false, error: error instanceof Error ? error.message : 'Unknown error' };
+        }
+    }
+    async generate(input, options) {
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            throw createLLMError('Cognitum API key not configured', 'API_KEY_MISSING', {
+                provider: 'cognitum',
+                retryable: false,
+            });
+        }
+        const messages = this.formatMessages(input, options?.systemPrompt);
+        const model = options?.model ?? this.config.model;
+        const maxTokens = options?.maxTokens ?? this.config.maxTokens ?? 4096;
+        const temperature = options?.temperature ?? this.config.temperature ?? 0.7;
+        const requestId = `cognitum-${++this.requestId}-${Date.now()}`;
+        const start = Date.now();
+        const body = { model, max_tokens: maxTokens, temperature, messages };
+        if (options?.stopSequences?.length)
+            body.stop = options.stopSequences;
+        try {
+            const response = await this.fetchWithRetry(`${this.getBaseUrl()}/v1/chat/completions`, { method: 'POST', headers: this.getHeaders(), body: JSON.stringify(body) }, options?.timeoutMs ?? this.config.timeoutMs ?? 60000, this.config.maxRetries ?? 3);
+            const latencyMs = Date.now() - start;
+            if (!response.ok) {
+                throw await this.toApiError(response, model);
+            }
+            const data = (await response.json());
+            const receipt = data.x_cognitum;
+            const usage = {
+                promptTokens: data.usage.prompt_tokens,
+                completionTokens: data.usage.completion_tokens,
+                totalTokens: data.usage.total_tokens,
+                cacheReadTokens: data.usage.cache_read_tokens ?? 0,
+            };
+            const cost = this.receiptCost(receipt);
+            TokenMetricsCollector.recordTokenUsage(requestId, 'cognitum-provider', 'llm', 'generate', {
+                inputTokens: usage.promptTokens,
+                outputTokens: usage.completionTokens,
+                totalTokens: usage.totalTokens,
+                estimatedCostUsd: cost.totalCost,
+            });
+            return {
+                content: data.choices[0]?.message?.content ?? '',
+                // Prefer the concrete resolved model from the receipt over the tier name.
+                model: receipt?.resolved_model ?? data.model,
+                provider: 'cognitum',
+                usage,
+                cost,
+                latencyMs,
+                finishReason: this.mapFinishReason(data.choices[0]?.finish_reason),
+                cached: receipt?.cache === 'hit',
+                requestId,
+            };
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error)
+                throw error;
+            throw createLLMError(error instanceof Error ? error.message : 'Request failed', 'NETWORK_ERROR', { provider: 'cognitum', model, retryable: true, cause: error });
+        }
+    }
+    async embed(text, options) {
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            throw createLLMError('Cognitum API key not configured', 'API_KEY_MISSING', {
+                provider: 'cognitum',
+                retryable: false,
+            });
+        }
+        const model = options?.model ?? 'cognitum-embed';
+        const start = Date.now();
+        try {
+            const response = await this.fetchWithTimeout(`${this.getBaseUrl()}/v1/embeddings`, {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify({ model, input: text }),
+            }, options?.timeoutMs ?? this.config.timeoutMs ?? 30000);
+            const latencyMs = Date.now() - start;
+            if (!response.ok) {
+                throw await this.toApiError(response, model);
+            }
+            const data = (await response.json());
+            return {
+                embedding: data.data[0].embedding,
+                model: data.x_cognitum?.resolved_model ?? data.model,
+                provider: 'cognitum',
+                tokenCount: data.usage.total_tokens,
+                latencyMs,
+                cached: false,
+            };
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error)
+                throw error;
+            throw createLLMError(error instanceof Error ? error.message : 'Embedding request failed', 'NETWORK_ERROR', { provider: 'cognitum', model, retryable: true, cause: error });
+        }
+    }
+    async complete(prompt, options) {
+        const response = await this.generate(prompt, {
+            model: options?.model,
+            temperature: options?.temperature ?? 0.2,
+            maxTokens: options?.maxTokens ?? 256,
+            stopSequences: options?.stopSequences,
+        });
+        return {
+            completion: response.content,
+            model: response.model,
+            provider: 'cognitum',
+            usage: response.usage,
+            latencyMs: response.latencyMs,
+            cached: response.cached,
+        };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    getSupportedModels() {
+        return ['cognitum-auto', 'cognitum-low', 'cognitum-mid', 'cognitum-high'];
+    }
+    getCostPerToken() {
+        // Cost is per-request from the receipt, not a fixed per-token table.
+        return { input: 0, output: 0 };
+    }
+    async dispose() {
+        // No persistent resources.
+    }
+    /**
+     * 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).
+     */
+    async getRemoteBudget() {
+        try {
+            const response = await this.fetchWithTimeout(`${this.getBaseUrl()}/v1/usage`, { method: 'GET', headers: this.getHeaders() }, 5000);
+            if (!response.ok)
+                return undefined;
+            const data = (await response.json());
+            const b = data.budget;
+            if (!b)
+                return undefined;
+            return {
+                servingBudgetUsd: b.servingBudgetUsd ?? 0,
+                hardCapUsd: b.hardCapUsd ?? 0,
+                committedUsd: b.committedUsd ?? 0,
+                headroomUsd: b.headroomUsd ?? 0,
+                status: b.status ?? 'unknown',
+                headroomExhausted: b.headroomExhausted ?? false,
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // -- internals -------------------------------------------------------------
+    /** Build a CostInfo from the authoritative receipt price. */
+    receiptCost(receipt) {
+        const total = receipt?.price_usd ?? 0;
+        return {
+            inputCost: 0,
+            outputCost: 0,
+            totalCost: total,
+            currency: 'USD',
+            source: receipt?.price_usd !== undefined ? 'provider-receipt' : 'local-estimate',
+        };
+    }
+    getApiKey() {
+        return this.config.apiKey ?? process.env.COGNITUM_API_KEY;
+    }
+    getBaseUrl() {
+        return (this.config.baseUrl ?? process.env.COGNITUM_BASE_URL ?? 'https://api.cognitum.one').replace(/\/$/, '');
+    }
+    getHeaders() {
+        return {
+            'Content-Type': 'application/json',
+            'X-API-Key': this.getApiKey(),
+        };
+    }
+    formatMessages(input, systemPrompt) {
+        const messages = [];
+        if (typeof input === 'string') {
+            if (systemPrompt)
+                messages.push({ role: 'system', content: systemPrompt });
+            messages.push({ role: 'user', content: input });
+        }
+        else {
+            const hasSystem = input.some((m) => m.role === 'system');
+            if (systemPrompt && !hasSystem)
+                messages.push({ role: 'system', content: systemPrompt });
+            for (const m of input)
+                messages.push({ role: m.role, content: m.content });
+        }
+        return messages;
+    }
+    mapFinishReason(reason) {
+        switch (reason) {
+            case 'length':
+                return 'length';
+            case 'content_filter':
+                return 'content_filter';
+            case 'stop':
+            default:
+                return 'stop';
+        }
+    }
+    async toApiError(response, model) {
+        const text = await response.text().catch(() => '');
+        let message = text;
+        try {
+            const parsed = JSON.parse(text);
+            message = parsed.error ?? text;
+        }
+        catch {
+            // non-JSON body
+        }
+        switch (response.status) {
+            case 401:
+            case 403:
+                return createLLMError(message || 'Unauthorized', 'API_KEY_INVALID', {
+                    provider: 'cognitum',
+                    model,
+                    retryable: false,
+                });
+            case 402:
+                // Payment required / budget cap reached — the metered-capped pause.
+                return createLLMError(message || 'Budget cap reached', 'COST_LIMIT_EXCEEDED', {
+                    provider: 'cognitum',
+                    model,
+                    retryable: false,
+                });
+            case 429:
+                return createLLMError(message || 'Rate limited', 'RATE_LIMITED', {
+                    provider: 'cognitum',
+                    model,
+                    retryable: true,
+                    retryAfterMs: 60000,
+                });
+            case 500:
+            case 502:
+            case 503:
+                return createLLMError(message || 'Provider unavailable', 'PROVIDER_UNAVAILABLE', {
+                    provider: 'cognitum',
+                    model,
+                    retryable: true,
+                    retryAfterMs: 5000,
+                });
+            default:
+                return createLLMError(message || `HTTP ${response.status}`, 'UNKNOWN', {
+                    provider: 'cognitum',
+                    model,
+                    retryable: false,
+                });
+        }
+    }
+    async fetchWithTimeout(url, options, timeoutMs) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, { ...options, signal: controller.signal });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw createLLMError('Request timed out', 'TIMEOUT', {
+                    provider: 'cognitum',
+                    retryable: true,
+                });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async fetchWithRetry(url, options, timeoutMs, maxRetries) {
+        let lastError;
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                const response = await this.fetchWithTimeout(url, options, timeoutMs);
+                if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+                    return response;
+                }
+                if (response.status >= 500 || response.status === 429) {
+                    if (attempt < maxRetries - 1) {
+                        await this.sleep(backoffDelay(attempt));
+                        continue;
+                    }
+                }
+                return response;
+            }
+            catch (error) {
+                lastError = toError(error);
+                if (attempt < maxRetries - 1)
+                    await this.sleep(backoffDelay(attempt));
+            }
+        }
+        throw lastError ?? new Error('Request failed after retries');
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=cognitum.js.map

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

@@ -3,6 +3,8 @@
  * Export all provider implementations
  */
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG } from './claude';
+export { ClaudeCodeProvider, DEFAULT_CLAUDE_CODE_CONFIG, API_BILLING_ENV_VARS, type ClaudeCodeConfig, } from './claude-code';
+export { CognitumProvider, DEFAULT_COGNITUM_CONFIG, type CognitumConfig, type CognitumBudget, } from './cognitum';
 export { OpenAIProvider, DEFAULT_OPENAI_CONFIG } from './openai';
 export { OllamaProvider, DEFAULT_OLLAMA_CONFIG } from './ollama';
 export { OpenRouterProvider, DEFAULT_OPENROUTER_CONFIG, OPENROUTER_PRICING, type OpenRouterConfig, } from './openrouter';

package/dist/shared/llm/providers/index.js

@@ -3,6 +3,8 @@
  * Export all provider implementations
  */
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG } from './claude';
+export { ClaudeCodeProvider, DEFAULT_CLAUDE_CODE_CONFIG, API_BILLING_ENV_VARS, } from './claude-code';
+export { CognitumProvider, DEFAULT_COGNITUM_CONFIG, } from './cognitum';
 export { OpenAIProvider, DEFAULT_OPENAI_CONFIG } from './openai';
 export { OllamaProvider, DEFAULT_OLLAMA_CONFIG } from './ollama';
 export { OpenRouterProvider, DEFAULT_OPENROUTER_CONFIG, OPENROUTER_PRICING, } from './openrouter';

package/dist/shared/llm/router/config-store.d.ts

@@ -58,19 +58,39 @@ export declare function mergeRouterConfig(base: RouterConfig, override: Partial<
  * GOOGLE_API_KEY doesn't also have to remember to flip gemini.enabled
  * to true). Providers without keys are left at their existing setting.
  *
- * COUNTERINTUITIVE: env presence OVERRIDES an explicit `enabled: false`
- * on disk. The reasoning: env is more recent / more authoritative than
- * a stale checked-in config file, and users who set an API key in env
- * usually intend to use the provider. To truly disable a provider that
- * has a key in env, either unset the env key OR set the env-only
- * kill-switch `AQE_LLM_ROUTER_DISABLED=1` (which disables the entire
- * router). This precedence is documented in ADR-043's addendum.
+ * ADR-123 AMENDMENT to ADR-043's addendum: env presence force-enables a
+ * provider ONLY when the user has not *explicitly* disabled it on disk. An
+ * explicit `enabled: false` in `.agentic-qe/llm-config.json` now wins over
+ * key presence — the previous behavior (env always overrides disk) meant
+ * merely exporting `ANTHROPIC_API_KEY` silently opted a user into paid API
+ * billing even after they had turned the provider off (issue #557). A
+ * provider left unset on disk is still force-enabled when its key is present
+ * (the convenient default). To disable a provider that has a key in env, set
+ * `enabled: false` for it on disk, unset the env key, or use the env-only
+ * kill-switch `AQE_LLM_ROUTER_DISABLED=1` (disables the whole router).
+ *
+ * @param explicitlyDisabled providers the user set to `enabled: false` in the
+ *   raw on-disk config; these are never force-enabled by env detection.
+ */
+export declare function applyEnvProviderDetection(config: RouterConfig, env?: NodeJS.ProcessEnv, explicitlyDisabled?: ReadonlySet<ExtendedProviderType>): RouterConfig;
+/**
+ * Collect providers the user *explicitly* set to `enabled: false` in the raw
+ * on-disk config (as opposed to a default `false`). Used so env detection
+ * doesn't resurrect a provider the user deliberately turned off (ADR-123).
+ */
+export declare function collectExplicitlyDisabled(onDisk: Partial<RouterConfig>): Set<ExtendedProviderType>;
+/**
+ * ADR-123: highest-precedence provider selector. `AQE_LLM_PROVIDER=<type>`
+ * (e.g. `claude-code`, `cognitum`, `openai`) overrides `defaultProvider` and
+ * force-enables that provider, so a user can switch the execution provider for
+ * a single run without editing `llm-config.json`. `anthropic` is accepted as
+ * an alias for `claude`. Unknown values are ignored (a warning is logged).
  */
-export declare function applyEnvProviderDetection(config: RouterConfig, env?: NodeJS.ProcessEnv): RouterConfig;
+export declare function resolveProviderOverrideFromEnv(env?: NodeJS.ProcessEnv): ExtendedProviderType | undefined;
 /**
- * The full load path: defaults <- disk <- env detection <- override.
- * This is what the kernel and CLI both call. Returns a fully-resolved
- * RouterConfig ready to hand to HybridRouter.
+ * The full load path: defaults <- disk <- env detection <- AQE_LLM_PROVIDER
+ * override <- explicit override. This is what the kernel and CLI both call.
+ * Returns a fully-resolved RouterConfig ready to hand to HybridRouter.
  */
 export declare function loadRouterConfig(options?: {
     projectRoot?: string;

package/dist/shared/llm/router/config-store.js

@@ -34,12 +34,18 @@ export const ROUTER_CONFIG_FILENAME = 'llm-config.json';
  */
 const PROVIDER_ENV_KEYS = {
     claude: ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY'],
+    // ADR-123: claude-code authenticates via the user's Claude Code OAuth login
+    // (subscription), NOT an env key. Empty array = "no key required"; actual
+    // availability is gated on the `claude` binary being on PATH (see the
+    // provider's isAvailable()).
+    'claude-code': [],
     openai: ['OPENAI_API_KEY'],
     ollama: [], // ollama is local; no key required
     openrouter: ['OPENROUTER_API_KEY'],
     gemini: ['GOOGLE_AI_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY'],
     'azure-openai': ['AZURE_OPENAI_API_KEY'],
     bedrock: ['AWS_ACCESS_KEY_ID'], // bedrock auth is more complex; presence is a hint
+    cognitum: ['COGNITUM_API_KEY'], // ADR-123: metered-capped gateway
     onnx: [], // local
 };
 /**
@@ -52,12 +58,14 @@ const PROVIDER_ENV_KEYS = {
  */
 const RUNTIME_CONSTRUCTIBLE_PROVIDERS = new Set([
     'claude',
+    'claude-code',
     'openai',
     'ollama',
     'openrouter',
     'gemini',
     'azure-openai',
     'bedrock',
+    'cognitum',
 ]);
 /**
  * Return the resolved config-file path for a project.
@@ -197,15 +205,21 @@ export function mergeRouterConfig(base, override) {
  * GOOGLE_API_KEY doesn't also have to remember to flip gemini.enabled
  * to true). Providers without keys are left at their existing setting.
  *
- * COUNTERINTUITIVE: env presence OVERRIDES an explicit `enabled: false`
- * on disk. The reasoning: env is more recent / more authoritative than
- * a stale checked-in config file, and users who set an API key in env
- * usually intend to use the provider. To truly disable a provider that
- * has a key in env, either unset the env key OR set the env-only
- * kill-switch `AQE_LLM_ROUTER_DISABLED=1` (which disables the entire
- * router). This precedence is documented in ADR-043's addendum.
+ * ADR-123 AMENDMENT to ADR-043's addendum: env presence force-enables a
+ * provider ONLY when the user has not *explicitly* disabled it on disk. An
+ * explicit `enabled: false` in `.agentic-qe/llm-config.json` now wins over
+ * key presence — the previous behavior (env always overrides disk) meant
+ * merely exporting `ANTHROPIC_API_KEY` silently opted a user into paid API
+ * billing even after they had turned the provider off (issue #557). A
+ * provider left unset on disk is still force-enabled when its key is present
+ * (the convenient default). To disable a provider that has a key in env, set
+ * `enabled: false` for it on disk, unset the env key, or use the env-only
+ * kill-switch `AQE_LLM_ROUTER_DISABLED=1` (disables the whole router).
+ *
+ * @param explicitlyDisabled providers the user set to `enabled: false` in the
+ *   raw on-disk config; these are never force-enabled by env detection.
  */
-export function applyEnvProviderDetection(config, env = process.env) {
+export function applyEnvProviderDetection(config, env = process.env, explicitlyDisabled = new Set()) {
     const available = detectAvailableProvidersFromEnv(env);
     const merged = {
         ...config,
@@ -215,6 +229,8 @@ export function applyEnvProviderDetection(config, env = process.env) {
         const keys = PROVIDER_ENV_KEYS[provider];
         if (keys.length === 0)
             continue; // local provider, leave default
+        if (explicitlyDisabled.has(provider))
+            continue; // ADR-123: honor explicit off
         const current = merged.providers[provider] ?? { enabled: false };
         if (!current.enabled) {
             merged.providers[provider] = { ...current, enabled: true };
@@ -223,14 +239,68 @@ export function applyEnvProviderDetection(config, env = process.env) {
     return merged;
 }
 /**
- * The full load path: defaults <- disk <- env detection <- override.
- * This is what the kernel and CLI both call. Returns a fully-resolved
- * RouterConfig ready to hand to HybridRouter.
+ * Collect providers the user *explicitly* set to `enabled: false` in the raw
+ * on-disk config (as opposed to a default `false`). Used so env detection
+ * doesn't resurrect a provider the user deliberately turned off (ADR-123).
+ */
+export function collectExplicitlyDisabled(onDisk) {
+    const disabled = new Set();
+    if (!onDisk.providers)
+        return disabled;
+    for (const [provider, cfg] of Object.entries(onDisk.providers)) {
+        if (cfg && cfg.enabled === false) {
+            disabled.add(provider);
+        }
+    }
+    return disabled;
+}
+/**
+ * ADR-123: highest-precedence provider selector. `AQE_LLM_PROVIDER=<type>`
+ * (e.g. `claude-code`, `cognitum`, `openai`) overrides `defaultProvider` and
+ * force-enables that provider, so a user can switch the execution provider for
+ * a single run without editing `llm-config.json`. `anthropic` is accepted as
+ * an alias for `claude`. Unknown values are ignored (a warning is logged).
+ */
+export function resolveProviderOverrideFromEnv(env = process.env) {
+    const raw = (env.AQE_LLM_PROVIDER ?? '').trim().toLowerCase();
+    if (!raw)
+        return undefined;
+    const normalized = raw === 'anthropic' ? 'claude' : raw;
+    if (ALL_PROVIDER_TYPES.includes(normalized)) {
+        return normalized;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`[router-config] Ignoring AQE_LLM_PROVIDER="${raw}": not a known provider. ` +
+        `Valid values: ${ALL_PROVIDER_TYPES.join(', ')}.`);
+    return undefined;
+}
+/**
+ * The full load path: defaults <- disk <- env detection <- AQE_LLM_PROVIDER
+ * override <- explicit override. This is what the kernel and CLI both call.
+ * Returns a fully-resolved RouterConfig ready to hand to HybridRouter.
  */
 export function loadRouterConfig(options = {}) {
+    const env = options.env ?? process.env;
     const onDisk = loadRouterConfigFile(options.projectRoot);
     const merged = mergeRouterConfig(DEFAULT_ROUTER_CONFIG, onDisk);
-    const withEnv = applyEnvProviderDetection(merged, options.env);
+    // ADR-123: an explicit `enabled: false` on disk is never resurrected by env.
+    const explicitlyDisabled = collectExplicitlyDisabled(onDisk);
+    let withEnv = applyEnvProviderDetection(merged, env, explicitlyDisabled);
+    // ADR-123: AQE_LLM_PROVIDER pins the default provider and enables it.
+    const providerOverride = resolveProviderOverrideFromEnv(env);
+    if (providerOverride) {
+        withEnv = {
+            ...withEnv,
+            defaultProvider: providerOverride,
+            providers: {
+                ...withEnv.providers,
+                [providerOverride]: {
+                    ...(withEnv.providers?.[providerOverride] ?? {}),
+                    enabled: true,
+                },
+            },
+        };
+    }
     return options.override ? mergeRouterConfig(withEnv, options.override) : withEnv;
 }
 /**

package/dist/shared/llm/router/hybrid-router.js

@@ -489,6 +489,15 @@ export class HybridRouter {
                 order = toolCapable;
             }
         }
+        // ADR-123 (issue #557): enforce the spend budget on the PRIMARY QE
+        // execution path. Domains call HybridRouter.chat() directly, which runs
+        // provider.generate() below — bypassing ProviderManager.generate() where
+        // the budget is otherwise checked. Gate once per request (not per fallback
+        // attempt); throws COST_LIMIT_EXCEEDED, or no-ops when no budget is set.
+        this.providerManager.assertWithinBudget(params.messages, {
+            model: order[0]?.model,
+            maxTokens: params.maxTokens,
+        });
         // Execute with fallback
         for (const { provider: providerType, model } of order) {
             if (attempts >= fallbackBehavior.maxAttempts)
@@ -508,6 +517,9 @@ export class HybridRouter {
                     skipCache: params.skipCache,
                     metadata: params.metadata,
                 });
+                // ADR-123: persist the charge to the cross-process ledger so budgets
+                // hold across a fleet of processes.
+                this.providerManager.recordResponseSpend(response);
                 const callLatency = Date.now() - callStartTime;
                 // Record success in legacy tracker
                 this.metrics.recordSuccess(providerType);
@@ -609,8 +621,12 @@ export class HybridRouter {
      */
     resolveModelIds(model, providerType) {
         // Map provider type to model-mapping provider format
+        // Partial: claude-code shares Anthropic model IDs; cognitum uses its own
+        // tier names (cognitum-low/mid/high) that aren't in the mapping table, so
+        // it falls through the `!mappingProvider` guard below to pass-through.
         const providerMapping = {
             claude: 'anthropic',
+            'claude-code': 'anthropic',
             openai: 'openai',
             ollama: 'ollama',
             openrouter: 'openrouter',

package/dist/shared/llm/router/types.js

@@ -23,12 +23,14 @@
  */
 export const ALL_PROVIDER_TYPES = [
     'claude',
+    'claude-code', // ADR-123: subscription-billed via `claude -p`
     'openai',
     'ollama',
     'openrouter',
     'gemini',
     'azure-openai',
     'bedrock',
+    'cognitum', // ADR-123: metered-capped gateway (api.cognitum.one)
     'onnx',
 ];
 /**
@@ -133,12 +135,17 @@ export const DEFAULT_ROUTER_CONFIG = {
     fallbackBehavior: DEFAULT_FALLBACK_BEHAVIOR,
     providers: {
         claude: { enabled: true, defaultModel: 'claude-sonnet-4-6' },
+        // ADR-123: opt-in (issue #557 — don't default the subscription/fleet path
+        // on). Enabled explicitly via AQE_LLM_PROVIDER=claude-code or disk config.
+        'claude-code': { enabled: false, defaultModel: 'claude-sonnet-4-6' },
         openai: { enabled: true, defaultModel: 'gpt-4o' },
         ollama: { enabled: true, defaultModel: 'llama3.1' },
         openrouter: { enabled: true, defaultModel: 'anthropic/claude-sonnet-4' },
         gemini: { enabled: false, defaultModel: 'gemini-pro' },
         'azure-openai': { enabled: false },
         bedrock: { enabled: false },
+        // ADR-123: opt-in; enabled when COGNITUM_API_KEY present or via override.
+        cognitum: { enabled: false, defaultModel: 'cognitum-auto' },
         onnx: { enabled: true, defaultModel: 'phi-4' },
     },
     enableMetrics: true,