agentic-qe 3.12.3 → 3.13.1

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

@@ -22,6 +22,47 @@
 import { ProviderManager } from './provider-manager.js';
 import { HybridRouter } from './router/hybrid-router.js';
 import { loadRouterConfig, shouldEnableRouter, detectAvailableProvidersFromEnv, } from './router/config-store.js';
+import { setAgentProviderOverrides, createOverrideRoutingRules, } from './router/agent-router-config.js';
+import { DEFAULT_QE_ROUTING_RULES } from './router/routing-rules.js';
+import { createLogger } from '../../logging/logger-factory.js';
+const routerServiceLogger = createLogger('llm/router-service');
+/**
+ * Issue #568: make `.agentic-qe/llm-config.json`'s `agentOverrides` map actually
+ * take effect.
+ *
+ * Two steps, and both are needed:
+ *   1. install the map so `getPreferredModelForAgent()` consults it, and
+ *   2. materialize a routing rule per overridden agent and put it *ahead* of the
+ *      rules the router would otherwise evaluate.
+ *
+ * Step 2 is the part that was missing before: `HybridRouter` only ever evaluates
+ * `config.rules` (falling back to `DEFAULT_QE_ROUTING_RULES`), and the generated
+ * per-agent ruleset was never installed into either — which is why the whole
+ * `agent-router-config` mechanism was unreachable from outside a single call
+ * stack.
+ *
+ * No overrides on disk => returns the config untouched.
+ */
+function applyAgentOverrides(config) {
+    // Pass each provider's own default model so a `{ "provider": "ollama" }`
+    // override resolves to a model ollama can serve, not the Claude model id the
+    // agent's category default happened to carry.
+    const providerDefaultModels = {};
+    for (const [provider, cfg] of Object.entries(config.providers ?? {})) {
+        if (cfg?.defaultModel) {
+            providerDefaultModels[provider] = cfg.defaultModel;
+        }
+    }
+    setAgentProviderOverrides(config.agentOverrides, providerDefaultModels);
+    const overrideRules = createOverrideRoutingRules();
+    if (overrideRules.length === 0) {
+        return config;
+    }
+    // Mirror HybridRouter's own fallback so materializing overrides never has the
+    // side effect of dropping the default QE rules.
+    const baseRules = config.rules.length > 0 ? config.rules : DEFAULT_QE_ROUTING_RULES;
+    return { ...config, rules: [...overrideRules, ...baseRules] };
+}
 /**
  * Order in which we pick fallbacks when the user hasn't specified any.
  * Local-first (free), then cheapest cloud, then richer providers. This
@@ -46,11 +87,11 @@ const FALLBACK_PRIORITY = [
 export async function createLLMRouterService(options = {}) {
     // Honor the test-injected ProviderManager path first.
     if (options.providerManager) {
-        const config = loadRouterConfig({
+        const config = applyAgentOverrides(loadRouterConfig({
             projectRoot: options.projectRoot,
             override: options.override,
             env: options.env,
-        });
+        }));
         const router = new HybridRouter(options.providerManager, config);
         await router.initialize();
         return {
@@ -63,15 +104,29 @@ export async function createLLMRouterService(options = {}) {
     if (!shouldEnableRouter({ projectRoot: options.projectRoot, env: options.env })) {
         return null;
     }
-    const config = loadRouterConfig({
+    const config = applyAgentOverrides(loadRouterConfig({
         projectRoot: options.projectRoot,
         override: options.override,
         env: options.env,
-    });
+    }));
     const enabled = pickEnabledProviders(config, options.env ?? process.env);
     if (enabled.length === 0) {
         return null;
     }
+    // Issue #568: an override naming a provider that isn't enabled would silently
+    // fall through to the default chain — the exact "configured it and nothing
+    // happened" failure this feature exists to avoid. Say so out loud. We do NOT
+    // auto-enable it: that would opt the user into a provider (and possibly paid
+    // billing) they never turned on.
+    const enabledSet = new Set(enabled);
+    for (const [agentType, override] of Object.entries(config.agentOverrides ?? {})) {
+        if (override.provider && !enabledSet.has(override.provider)) {
+            routerServiceLogger.warn(`[llm-config] agentOverrides["${agentType}"] routes to provider ` +
+                `"${override.provider}", which is not enabled (no API key detected and not ` +
+                `enabled in .agentic-qe/llm-config.json). This override will not take effect ` +
+                `until that provider is available.`);
+        }
+    }
     const { primary, fallbacks } = pickPrimaryAndFallbacks(config, enabled);
     const providerManagerConfig = {
         primary: primary,

package/dist/shared/llm/provider-manager.d.ts

@@ -70,7 +70,7 @@ export declare class ProviderManager {
      */
     assertWithinBudget(input: string | Message[], options?: GenerateOptions | CompleteOptions): void;
     /** ADR-123: public spend recorder for those same bypassing callers. */
-    recordResponseSpend(response: LLMResponse): void;
+    recordResponseSpend(response: LLMResponse, agent?: string): void;
     /**
      * Generate text using the best available provider
      */

package/dist/shared/llm/provider-manager.js

@@ -18,6 +18,7 @@ import { createDefaultSpendLedger, InMemorySpendLedger, } from './spend-ledger';
 import { resolveBillingMode, billingNotice } from './billing-modes';
 import { ClaudeProvider } from './providers/claude';
 import { ClaudeCodeProvider } from './providers/claude-code';
+import { CodexProvider } from './providers/codex';
 import { CognitumProvider } from './providers/cognitum';
 import { OpenAIProvider } from './providers/openai';
 import { OllamaProvider } from './providers/ollama';
@@ -169,7 +170,7 @@ export class ProviderManager {
         }
     }
     /** ADR-123: persist a completed charge to the cross-process ledger. */
-    recordSpend(response) {
+    recordSpend(response, agent) {
         if (!this.spendLedger)
             return;
         this.spendLedger.record({
@@ -180,6 +181,7 @@ export class ProviderManager {
             promptTokens: response.usage.promptTokens,
             completionTokens: response.usage.completionTokens,
             requestId: response.requestId,
+            agent, // ADR-124 M2.3: per-agent attribution when the caller has context.
         });
     }
     /**
@@ -192,8 +194,8 @@ export class ProviderManager {
         this.enforceBudget(input, options);
     }
     /** ADR-123: public spend recorder for those same bypassing callers. */
-    recordResponseSpend(response) {
-        this.recordSpend(response);
+    recordResponseSpend(response, agent) {
+        this.recordSpend(response, agent);
     }
     /**
      * Generate text using the best available provider
@@ -417,6 +419,8 @@ export class ProviderManager {
                 return new ClaudeProvider(this.config.providers.claude);
             case 'claude-code':
                 return new ClaudeCodeProvider(this.config.providers['claude-code']);
+            case 'codex':
+                return new CodexProvider(this.config.providers.codex);
             case 'cognitum':
                 return new CognitumProvider(this.config.providers.cognitum);
             case 'openai':

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

@@ -285,10 +285,19 @@ export class ClaudeCodeProvider {
                 clearTimeout(timer);
                 resolve({ code: code ?? 0, stdout, stderr });
             });
-            if (stdin !== undefined) {
-                child.stdin.write(stdin);
+            // EPIPE guard (qe-court finding): if `claude` exits before reading stdin,
+            // an unhandled 'error' on the stdin stream crashes the calling process. The
+            // 'close'/'error' handlers above already capture the real outcome.
+            child.stdin.on('error', () => { });
+            try {
+                if (stdin !== undefined) {
+                    child.stdin.write(stdin);
+                }
+                child.stdin.end();
+            }
+            catch {
+                /* stream already torn down — process handlers report the failure */
             }
-            child.stdin.end();
         });
     }
     /** Simple semaphore so we don't spawn unbounded `claude` subprocesses. */

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

@@ -0,0 +1,58 @@
+/**
+ * Agentic QE v3 — Codex CLI (subscription) Provider (ADR-123 / ADR-124 M3.5)
+ *
+ * Runs QE analysis on the user's ChatGPT subscription by shelling out to the
+ * Codex CLI (`codex exec`) instead of calling the OpenAI API with a paid key.
+ * The CLI authenticates with the user's existing ChatGPT login (~/.codex/auth.json)
+ * and draws from the subscription allowance, so the worst case is "hit the plan
+ * limit and pause" rather than a per-token bill. Mirrors the claude-code provider.
+ *
+ * WHY: gives AQE a cross-vendor (GPT-family) engine — used as a provider fallback
+ * and, crucially, as an independent prosecutor/juror in qe-court (ADR-124), where
+ * a non-Claude, non-Cognitum brain is the strongest form of writer≠juror.
+ *
+ * LOAD-BEARING: the child process env has OPENAI_API_KEY / CODEX_API_KEY stripped.
+ * If present, the CLI could revert to API-key billing and this provider would be
+ * a lie. `parity` test coverage asserts the strip.
+ */
+import { LLMProvider, LLMProviderType, BillingMode, CodexConfig, Message, GenerateOptions, EmbedOptions, CompleteOptions, LLMResponse, EmbeddingResponse, CompletionResponse, HealthCheckResult } from '../interfaces';
+export type { CodexConfig };
+/** Env vars whose presence could flip the CLI from subscription to API billing. */
+export declare const API_BILLING_ENV_VARS: readonly ["OPENAI_API_KEY", "CODEX_API_KEY"];
+/** Sentinel meaning "let Codex use its own configured default model". */
+export declare const CODEX_DEFAULT_MODEL = "default";
+export declare const DEFAULT_CODEX_CONFIG: CodexConfig;
+export declare class CodexProvider implements LLMProvider {
+    readonly type: LLMProviderType;
+    readonly name: string;
+    readonly billingMode: BillingMode;
+    private config;
+    private requestId;
+    private availabilityCache?;
+    private active;
+    private readonly queue;
+    constructor(config?: Partial<CodexConfig>);
+    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(): CodexConfig;
+    getSupportedModels(): string[];
+    getCostPerToken(): {
+        input: number;
+        output: number;
+    };
+    dispose(): Promise<void>;
+    private flatten;
+    private classifyError;
+    /**
+     * Build the child env with API-billing keys stripped (LOAD-BEARING).
+     * Exported logic tested by parity/env-strip tests.
+     */
+    static childEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    private runProcess;
+    /** Simple semaphore so we don't spawn unbounded `codex` subprocesses. */
+    private withConcurrency;
+}
+//# sourceMappingURL=codex.d.ts.map

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

@@ -0,0 +1,305 @@
+/**
+ * Agentic QE v3 — Codex CLI (subscription) Provider (ADR-123 / ADR-124 M3.5)
+ *
+ * Runs QE analysis on the user's ChatGPT subscription by shelling out to the
+ * Codex CLI (`codex exec`) instead of calling the OpenAI API with a paid key.
+ * The CLI authenticates with the user's existing ChatGPT login (~/.codex/auth.json)
+ * and draws from the subscription allowance, so the worst case is "hit the plan
+ * limit and pause" rather than a per-token bill. Mirrors the claude-code provider.
+ *
+ * WHY: gives AQE a cross-vendor (GPT-family) engine — used as a provider fallback
+ * and, crucially, as an independent prosecutor/juror in qe-court (ADR-124), where
+ * a non-Claude, non-Cognitum brain is the strongest form of writer≠juror.
+ *
+ * LOAD-BEARING: the child process env has OPENAI_API_KEY / CODEX_API_KEY stripped.
+ * If present, the CLI could revert to API-key billing and this provider would be
+ * a lie. `parity` test coverage asserts the strip.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createLLMError, } from '../interfaces';
+import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
+/** Env vars whose presence could flip the CLI from subscription to API billing. */
+export const API_BILLING_ENV_VARS = ['OPENAI_API_KEY', 'CODEX_API_KEY'];
+/** Sentinel meaning "let Codex use its own configured default model". */
+export const CODEX_DEFAULT_MODEL = 'default';
+export const DEFAULT_CODEX_CONFIG = {
+    model: CODEX_DEFAULT_MODEL,
+    maxTokens: 4096,
+    temperature: 0.7,
+    timeoutMs: 180000,
+    maxRetries: 1,
+    binaryPath: 'codex',
+    maxConcurrency: 2,
+};
+export class CodexProvider {
+    type = 'codex';
+    name = 'Codex CLI (subscription)';
+    billingMode = 'subscription';
+    config;
+    requestId = 0;
+    availabilityCache;
+    active = 0;
+    queue = [];
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CODEX_CONFIG, ...config };
+        const envConc = Number.parseInt(process.env.AQE_CODEX_CONCURRENCY ?? '', 10);
+        if (Number.isFinite(envConc) && envConc > 0) {
+            this.config.maxConcurrency = envConc;
+        }
+    }
+    async isAvailable() {
+        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, 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: `Codex CLI ("${this.config.binaryPath}") not found or not runnable. ` +
+                    `Install Codex and log in with your ChatGPT account (\`codex login\`).`,
+            };
+        }
+        return {
+            healthy: true,
+            latencyMs,
+            models: this.getSupportedModels(),
+            details: { binaryPath: this.config.binaryPath, billing: 'subscription' },
+        };
+    }
+    async generate(input, options) {
+        const model = options?.model ?? this.config.model ?? CODEX_DEFAULT_MODEL;
+        const requestId = `codex-${++this.requestId}-${Date.now()}`;
+        const { prompt } = this.flatten(input, options?.systemPrompt);
+        // `codex exec` is agentic; keep it read-only and non-interactive. We capture
+        // just the final assistant message via -o <file> to avoid parsing the noisy
+        // JSONL event stream.
+        const tmp = mkdtempSync(join(tmpdir(), 'aqe-codex-'));
+        const outFile = join(tmp, 'last-message.txt');
+        const args = [
+            'exec',
+            '--skip-git-repo-check',
+            '--sandbox', 'read-only',
+            '-o', outFile,
+        ];
+        if (model && model !== CODEX_DEFAULT_MODEL) {
+            args.push('-m', model);
+        }
+        const start = Date.now();
+        const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs ?? 180000;
+        try {
+            const { code, stderr } = await this.withConcurrency(() => this.runProcess(args, prompt, undefined, timeoutMs));
+            const latencyMs = Date.now() - start;
+            let content = '';
+            try {
+                content = readFileSync(outFile, 'utf8').trim();
+            }
+            catch {
+                content = '';
+            }
+            if (code !== 0 && !content) {
+                throw this.classifyError(stderr || `codex exited with code ${code}`, model);
+            }
+            // Subscription: no per-token receipt. Estimate usage from text length for
+            // visibility only (≈4 chars/token); marginal monetary cost is $0.
+            const promptTokens = Math.ceil(prompt.length / 4);
+            const completionTokens = Math.ceil(content.length / 4);
+            const usage = {
+                promptTokens,
+                completionTokens,
+                totalTokens: promptTokens + completionTokens,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+            };
+            TokenMetricsCollector.recordTokenUsage(requestId, 'codex-provider', 'llm', 'generate', {
+                inputTokens: usage.promptTokens,
+                outputTokens: usage.completionTokens,
+                totalTokens: usage.totalTokens,
+                estimatedCostUsd: 0,
+            });
+            return {
+                content,
+                model: model === CODEX_DEFAULT_MODEL ? 'codex-default' : model,
+                provider: 'codex',
+                usage,
+                // Subscription billing: marginal cost is $0 and we know it authoritatively.
+                cost: { inputCost: 0, outputCost: 0, totalCost: 0, currency: 'USD', source: 'provider-receipt' },
+                latencyMs,
+                finishReason: 'stop',
+                cached: false,
+                requestId,
+            };
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    async embed(_text, _options) {
+        throw createLLMError('Codex provider does not support embeddings. Use openai, ollama, or cognitum.', 'MODEL_NOT_FOUND', { provider: 'codex', 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: 'codex',
+            usage: response.usage,
+            latencyMs: response.latencyMs,
+            cached: response.cached,
+        };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    getSupportedModels() {
+        // Codex resolves the concrete model from its profile/login; these are the
+        // common ids accepted via -m. `default` = whatever the CLI is configured to.
+        return [CODEX_DEFAULT_MODEL, 'gpt-5-codex', 'o3', 'o4-mini'];
+    }
+    getCostPerToken() {
+        return { input: 0, output: 0 };
+    }
+    async dispose() {
+        // No persistent resources.
+    }
+    // -- internals -------------------------------------------------------------
+    flatten(input, systemPromptOpt) {
+        if (typeof input === 'string') {
+            return { prompt: systemPromptOpt ? `${systemPromptOpt}\n\n${input}` : input };
+        }
+        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');
+        const preamble = systemParts.length > 0 ? `${systemParts.join('\n\n')}\n\n` : '';
+        return { prompt: `${preamble}${convo}` };
+    }
+    classifyError(message, model) {
+        const lower = message.toLowerCase();
+        if (lower.includes('rate limit') ||
+            lower.includes('usage limit') ||
+            lower.includes('429') ||
+            lower.includes('quota')) {
+            return createLLMError(message, 'RATE_LIMITED', {
+                provider: 'codex',
+                model,
+                retryable: true,
+                retryAfterMs: 60_000,
+            });
+        }
+        return createLLMError(message, 'PROVIDER_UNAVAILABLE', {
+            provider: 'codex',
+            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, _unused, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.config.binaryPath ?? 'codex', args, {
+                env: CodexProvider.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('codex exec timed out', 'TIMEOUT', {
+                    provider: 'codex',
+                    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 codex: ${err.message}`, 'PROVIDER_UNAVAILABLE', {
+                    provider: 'codex',
+                    retryable: false,
+                    cause: err,
+                }));
+            });
+            child.on('close', (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ code: code ?? 0, stdout, stderr });
+            });
+            // EPIPE guard: if codex exits before reading stdin (e.g. not logged in),
+            // the write/end can emit 'error' on the stdin stream. Without a listener
+            // Node throws an uncaught exception that crashes the calling process. The
+            // 'close'/'error' handlers above already capture the real outcome.
+            child.stdin.on('error', () => { });
+            try {
+                if (stdin !== undefined) {
+                    child.stdin.write(stdin);
+                }
+                child.stdin.end();
+            }
+            catch {
+                /* stream already torn down — the process handlers report the failure */
+            }
+        });
+    }
+    /** Simple semaphore so we don't spawn unbounded `codex` 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=codex.js.map

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

@@ -4,6 +4,7 @@
  */
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG } from './claude';
 export { ClaudeCodeProvider, DEFAULT_CLAUDE_CODE_CONFIG, API_BILLING_ENV_VARS, type ClaudeCodeConfig, } from './claude-code';
+export { CodexProvider, DEFAULT_CODEX_CONFIG, CODEX_DEFAULT_MODEL, type CodexConfig, } from './codex';
 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';

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

@@ -4,6 +4,7 @@
  */
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG } from './claude';
 export { ClaudeCodeProvider, DEFAULT_CLAUDE_CODE_CONFIG, API_BILLING_ENV_VARS, } from './claude-code';
+export { CodexProvider, DEFAULT_CODEX_CONFIG, CODEX_DEFAULT_MODEL, } from './codex';
 export { CognitumProvider, DEFAULT_COGNITUM_CONFIG, } from './cognitum';
 export { OpenAIProvider, DEFAULT_OPENAI_CONFIG } from './openai';
 export { OllamaProvider, DEFAULT_OLLAMA_CONFIG } from './ollama';

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

@@ -8,7 +8,7 @@
  * - Override mechanism for specific tasks
  * - Agent category detection and preferred model resolution
  */
-import { ExtendedProviderType, RoutingRule, TaskComplexity } from './types';
+import { ExtendedProviderType, RoutingRule, TaskComplexity, AgentProviderOverride } from './types';
 /**
  * Agent categories for routing decisions
  */
@@ -120,7 +120,34 @@ export declare const DEFAULT_CATEGORY_CAPABILITIES: Record<AgentCategory, AgentC
  */
 export declare function getAgentRoutingCategory(agentType: string): AgentCategory;
 /**
- * Get the preferred model for an agent type
+ * Install the on-disk per-agent overrides (issue #568). Called by the router
+ * service after `loadRouterConfig()` has validated them.
+ *
+ * Replaces the whole map rather than merging, so reloading a config that
+ * removed an entry actually removes it.
+ *
+ * @param overrides validated `agentOverrides` map
+ * @param defaultModels per-provider default model ids, so a provider-only
+ *   override resolves to a model that provider can actually serve
+ */
+export declare function setAgentProviderOverrides(overrides: Record<string, AgentProviderOverride> | undefined, defaultModels?: Partial<Record<ExtendedProviderType, string>>): void;
+/** Current on-disk per-agent overrides. Primarily for diagnostics and tests. */
+export declare function getAgentProviderOverrides(): Readonly<Record<string, AgentProviderOverride>>;
+/** Clear installed overrides. For tests. */
+export declare function resetAgentProviderOverrides(): void;
+/**
+ * Get the preferred model for an agent type.
+ *
+ * Resolution order (issue #568):
+ *   1. `agentOverrides[agentType]` from `.agentic-qe/llm-config.json` — the
+ *      user's explicit, hand-written intent, so it wins.
+ *   2. the agent's category default (`AGENT_CATEGORY_MAP` ->
+ *      `DEFAULT_CATEGORY_MODELS`).
+ *
+ * An override is a *partial*: fields it does not set keep their category
+ * default, so `{ "provider": "ollama" }` re-provisions the provider without
+ * forcing the user to also restate temperature, token budget, and priority.
+ *
  * @param agentType - The agent type identifier
  * @returns The model preference configuration
  */
@@ -161,6 +188,23 @@ export declare function isLatencySensitive(agentType: string): boolean;
  * @returns A routing rule for this agent type
  */
 export declare function createAgentRoutingRule(agentType: string): RoutingRule;
+/**
+ * Build routing rules for exactly the agent types the user overrode on disk
+ * (issue #568).
+ *
+ * Why a separate builder rather than `createAgentRoutingRule`: that one also
+ * constrains on `requiresReasoning`, which is right for the generated
+ * whole-roster ruleset but wrong here — a user who wrote
+ * `"qe-mutation-tester": { "provider": "ollama" }` means *always*, not "only when
+ * the request happens to be flagged as needing reasoning". These rules match on
+ * agent type alone.
+ *
+ * Returns `[]` when nothing is overridden, so a project without the key gets the
+ * exact rule set it got before.
+ *
+ * @returns Routing rules, highest priority first
+ */
+export declare function createOverrideRoutingRules(): RoutingRule[];
 /**
  * Create routing rules for all agents in a category
  * @param category - The agent category