agentic-qe 3.13.11 → 3.14.0

package/dist/shared/llm/providers/external-cli.js

@@ -0,0 +1,385 @@
+/**
+ * Agentic QE v3 — Generic external CLI provider (ADR-127 / issue #628)
+ *
+ * A provider built from a *declaration* rather than from code. It generalizes
+ * the shape AQE has already shipped twice — `providers/codex.ts` and
+ * `providers/claude-code.ts` — into something a downstream integrator can
+ * obtain by writing JSON:
+ *
+ *   spawn a host CLI → feed it a prompt on stdin → read the completion from
+ *   stdout → attribute the usage honestly.
+ *
+ * WHY DECLARATIVE: the requester (agentic-kit) drives AQE as spawned
+ * subprocesses — the `aqe` CLI bundle and the MCP server bundle are separate
+ * esbuild artifacts — so an in-process `registerProvider()` call cannot reach
+ * them. A declaration in `.agentic-qe/llm-config.json` reaches both, and does
+ * so without AQE ever importing third-party code. See ADR-127 for why the
+ * dynamic-`import()` plugin design was rejected.
+ *
+ * LOAD-BEARING: `stripEnv` removes named variables from the child environment.
+ * A host that bills against a subscription must be able to guarantee an API
+ * key is not silently present to flip it back to metered billing — the same
+ * discipline `codex.ts` enforces for OPENAI_API_KEY / CODEX_API_KEY.
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants as fsConstants, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { createLLMError, } from '../interfaces.js';
+export const DEFAULT_EXTERNAL_CLI_TIMEOUT_MS = 180_000;
+export const DEFAULT_EXTERNAL_CLI_CONCURRENCY = 2;
+export const EXTERNAL_CLI_DEFAULT_MODEL = 'default';
+/**
+ * Validate a declaration. Returns an error message, or `undefined` when the
+ * declaration is usable.
+ *
+ * Deliberately does NOT check that the binary exists — that is a runtime
+ * availability question answered by `isAvailable()`. A declaration for a host
+ * that is not installed yet is valid-but-unavailable, not malformed, so a
+ * config file stays portable across machines.
+ */
+export function validateExternalCliConfig(type, config) {
+    if (!config || typeof config !== 'object') {
+        return `externalProviders["${type}"] must be an object`;
+    }
+    const c = config;
+    if (c.kind !== 'cli') {
+        return `externalProviders["${type}"].kind must be "cli" (got ${JSON.stringify(c.kind)})`;
+    }
+    if (!Array.isArray(c.command) || c.command.length === 0) {
+        return `externalProviders["${type}"].command must be a non-empty string array`;
+    }
+    if (!c.command.every((part) => typeof part === 'string' && part.length > 0)) {
+        return `externalProviders["${type}"].command must contain only non-empty strings`;
+    }
+    if (c.billingMode !== undefined &&
+        !['subscription', 'metered-api', 'metered-capped', 'local'].includes(c.billingMode)) {
+        return `externalProviders["${type}"].billingMode "${String(c.billingMode)}" is not a valid billing mode`;
+    }
+    if (c.models !== undefined && (!Array.isArray(c.models) || c.models.some((m) => typeof m !== 'string'))) {
+        return `externalProviders["${type}"].models must be a string array`;
+    }
+    if (c.timeoutMs !== undefined && (typeof c.timeoutMs !== 'number' || c.timeoutMs <= 0)) {
+        return `externalProviders["${type}"].timeoutMs must be a positive number`;
+    }
+    if (c.maxConcurrency !== undefined &&
+        (typeof c.maxConcurrency !== 'number' || c.maxConcurrency < 1)) {
+        return `externalProviders["${type}"].maxConcurrency must be >= 1`;
+    }
+    if (c.stripEnv !== undefined &&
+        (!Array.isArray(c.stripEnv) || c.stripEnv.some((k) => typeof k !== 'string'))) {
+        return `externalProviders["${type}"].stripEnv must be a string array`;
+    }
+    if ('apiKey' in c) {
+        // Matches saveRouterConfigFile's never-persist-keys discipline. Reported
+        // as an error so the key is noticed and removed rather than silently kept
+        // in a file that gets committed.
+        return `externalProviders["${type}"] must not contain an apiKey — keys belong in the environment, not in llm-config.json`;
+    }
+    return undefined;
+}
+// ============================================================================
+// Provider
+// ============================================================================
+export class ExternalCliProvider {
+    type;
+    name;
+    billingMode;
+    config;
+    requestCounter = 0;
+    availabilityCache;
+    active = 0;
+    queue = [];
+    constructor(type, config) {
+        const problem = validateExternalCliConfig(type, config);
+        if (problem) {
+            throw createLLMError(problem, 'INVALID_REGISTRATION', { retryable: false });
+        }
+        this.type = type;
+        this.config = config;
+        this.name = config.displayName ?? type;
+        // Undeclared => metered-api: assume it costs money and requires a cap.
+        this.billingMode = config.billingMode ?? 'metered-api';
+    }
+    /**
+     * Is the host's binary present and executable?
+     *
+     * Deliberately does NOT run it. AQE cannot know what invoking an arbitrary
+     * host costs — a declared host has no `--version` contract it agreed to, and
+     * spawning it with an empty prompt could burn a real request against the
+     * user's plan just to answer "are you installed?". Resolving the binary on
+     * PATH answers the question for free.
+     */
+    async isAvailable() {
+        const now = Date.now();
+        if (this.availabilityCache && now - this.availabilityCache.at < 60_000) {
+            return this.availabilityCache.available;
+        }
+        const available = resolvesOnPath(this.config.command[0]);
+        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: `External provider "${this.type}" could not run "${this.config.command[0]}". ` +
+                    `Check that the host is installed and on PATH.`,
+            };
+        }
+        return {
+            healthy: true,
+            latencyMs,
+            models: this.getSupportedModels(),
+            details: {
+                command: this.config.command[0],
+                billing: this.billingMode,
+                external: true,
+            },
+        };
+    }
+    async generate(input, options) {
+        const model = options?.model ?? this.defaultModel();
+        const requestId = `${this.type}-${++this.requestCounter}-${Date.now()}`;
+        const prompt = flattenPrompt(input, options?.systemPrompt);
+        const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs ?? DEFAULT_EXTERNAL_CLI_TIMEOUT_MS;
+        const extraArgs = [];
+        if (this.config.modelFlag && model && model !== EXTERNAL_CLI_DEFAULT_MODEL) {
+            extraArgs.push(this.config.modelFlag, model);
+        }
+        const start = Date.now();
+        const { code, stdout, stderr } = await this.withConcurrency(() => this.spawnHost(extraArgs, prompt, timeoutMs));
+        const latencyMs = Date.now() - start;
+        const content = stdout.trim();
+        if (code !== 0 && !content) {
+            throw this.classifyError(stderr || `${this.type} exited with code ${code}`, model);
+        }
+        // No per-token receipt from a generic CLI. Estimate for visibility only
+        // (~4 chars/token) and mark the cost `local-estimate` so ADR-126's
+        // provenance rule holds: an estimate is never reported as a measurement.
+        const promptTokens = Math.ceil(prompt.length / 4);
+        const completionTokens = Math.ceil(content.length / 4);
+        const usage = {
+            promptTokens,
+            completionTokens,
+            totalTokens: promptTokens + completionTokens,
+        };
+        return {
+            content,
+            model,
+            provider: this.type,
+            usage,
+            cost: {
+                inputCost: 0,
+                outputCost: 0,
+                totalCost: 0,
+                currency: 'USD',
+                // Even for a subscription host this is an estimate, not a receipt:
+                // AQE did not observe the billing event and cannot verify the mode
+                // the declaration claimed.
+                source: 'local-estimate',
+            },
+            latencyMs,
+            finishReason: 'stop',
+            cached: false,
+            requestId,
+        };
+    }
+    /**
+     * ADR-127: a generic CLI contract cannot promise an embeddings endpoint.
+     * Throws `EMBEDDING_UNSUPPORTED` — a distinct, non-retryable signal so the
+     * caller falls back to a provider that has one, and never receives a
+     * fabricated vector.
+     */
+    async embed(_text, _options) {
+        throw createLLMError(`External provider "${this.type}" does not support embeddings. ` +
+            `Use a provider with an embeddings endpoint (openai, ollama, cognitum).`, 'EMBEDDING_UNSUPPORTED', { provider: this.type, retryable: false });
+    }
+    async complete(prompt, options) {
+        const response = await this.generate(prompt, {
+            model: options?.model,
+            temperature: options?.temperature,
+            maxTokens: options?.maxTokens,
+        });
+        return {
+            completion: response.content,
+            model: response.model,
+            provider: this.type,
+            usage: response.usage,
+            latencyMs: response.latencyMs,
+            cached: response.cached,
+        };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    getSupportedModels() {
+        return [...(this.config.models ?? [EXTERNAL_CLI_DEFAULT_MODEL])];
+    }
+    /**
+     * Unknown. A declared host does not tell AQE its per-token price, and
+     * inventing one would feed fabricated numbers into cost reporting.
+     */
+    getCostPerToken() {
+        return { input: 0, output: 0 };
+    }
+    async dispose() {
+        // No persistent resources — each request is its own subprocess.
+    }
+    // -- internals -------------------------------------------------------------
+    defaultModel() {
+        return this.config.defaultModel ?? this.config.models?.[0] ?? EXTERNAL_CLI_DEFAULT_MODEL;
+    }
+    /**
+     * Child env with the declared keys removed (LOAD-BEARING — see file header).
+     * Static so tests can assert the strip without spawning anything.
+     */
+    static childEnv(stripEnv = [], base = process.env) {
+        const env = { ...base };
+        for (const key of stripEnv) {
+            delete env[key];
+        }
+        return env;
+    }
+    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: this.type,
+                model,
+                retryable: true,
+                retryAfterMs: 60_000,
+            });
+        }
+        return createLLMError(message, 'PROVIDER_UNAVAILABLE', {
+            provider: this.type,
+            model,
+            retryable: true,
+        });
+    }
+    spawnHost(extraArgs, stdin, timeoutMs) {
+        const [binary, ...baseArgs] = this.config.command;
+        const args = [...baseArgs, ...extraArgs];
+        return new Promise((resolve, reject) => {
+            const child = spawn(binary, args, {
+                env: ExternalCliProvider.childEnv(this.config.stripEnv),
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.kill('SIGKILL');
+                reject(createLLMError(`${this.type} timed out after ${timeoutMs}ms`, 'TIMEOUT', {
+                    provider: this.type,
+                    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 "${binary}" for provider "${this.type}": ${err.message}`, 'PROVIDER_UNAVAILABLE', { provider: this.type, retryable: false, cause: err }));
+            });
+            child.on('close', (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ code: code ?? 0, stdout, stderr });
+            });
+            // EPIPE guard: a host that exits before reading stdin (e.g. not logged
+            // in) makes the write emit 'error' on the stdin stream. Without a
+            // listener Node throws an uncaught exception that kills the calling
+            // process. The close/error handlers above carry the real outcome.
+            child.stdin.on('error', () => {
+                /* swallow EPIPE — outcome reported via close/error */
+            });
+            try {
+                child.stdin.write(stdin);
+                child.stdin.end();
+            }
+            catch {
+                /* stream already torn down — process handlers report the failure */
+            }
+        });
+    }
+    /** Semaphore so we never spawn unbounded host subprocesses. */
+    async withConcurrency(fn) {
+        const limit = this.config.maxConcurrency ?? DEFAULT_EXTERNAL_CLI_CONCURRENCY;
+        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();
+        }
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Does this binary resolve to something executable, without running it?
+ * An absolute or explicitly-relative path is checked directly; a bare name is
+ * looked up across PATH the way the shell would.
+ */
+export function resolvesOnPath(binary, env = process.env) {
+    const isExecutable = (candidate) => {
+        try {
+            accessSync(candidate, fsConstants.X_OK);
+            return statSync(candidate).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    if (binary.includes('/') || binary.includes('\\')) {
+        return isExecutable(binary);
+    }
+    const entries = (env.PATH ?? '').split(delimiter).filter(Boolean);
+    // PATHEXT matters on Windows, where `my-host` is really `my-host.cmd`.
+    const extensions = process.platform === 'win32'
+        ? ['', ...(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)]
+        : [''];
+    return entries.some((dir) => extensions.some((ext) => isExecutable(join(dir, binary + ext))));
+}
+/**
+ * Flatten messages into a single prompt. A generic CLI has no role protocol,
+ * so system content is hoisted into a preamble — the same strategy
+ * `codex.ts` uses and the reason `message-formatter` falls back to
+ * `'first-message'` for unknown providers.
+ */
+export function flattenPrompt(input, systemPrompt) {
+    if (typeof input === 'string') {
+        return systemPrompt ? `${systemPrompt}\n\n${input}` : input;
+    }
+    const systemParts = input.filter((m) => m.role === 'system').map((m) => m.content);
+    if (systemPrompt)
+        systemParts.unshift(systemPrompt);
+    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 `${preamble}${convo}`;
+}
+//# sourceMappingURL=external-cli.js.map

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

@@ -20,6 +20,20 @@
 import type { RouterConfig, ExtendedProviderType, AgentProviderOverride } from './types.js';
 /** Filename under .agentic-qe/ */
 export declare const ROUTER_CONFIG_FILENAME = "llm-config.json";
+/**
+ * Can `ProviderManager.createProvider()` build this type? True for the
+ * built-in constructible set, and for any provider registered per ADR-127.
+ */
+export declare function isRuntimeConstructible(provider: ExtendedProviderType): boolean;
+/**
+ * Every provider type the router may legitimately be pointed at: the ones AQE
+ * ships plus the ones a downstream integrator registered (ADR-127).
+ *
+ * `ALL_PROVIDER_TYPES` deliberately stays frozen as "what AQE ships" — it is
+ * exported public API that consumers read — so validation paths call this
+ * instead of widening that constant at runtime.
+ */
+export declare function allSelectableProviderTypes(): readonly ExtendedProviderType[];
 /**
  * Return the resolved config-file path for a project.
  * Caller may override projectRoot for tests; defaults to findProjectRoot().

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

@@ -20,6 +20,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { findProjectRoot } from '../../../kernel/unified-memory.js';
+import { isBuiltinExtendedProviderType } from './types.js';
+import { isRegisteredProvider, registeredProviderTypes, } from '../provider-registry.js';
+import { registerExternalProviders, sanitizeExternalProviders, } from './external-provider-config.js';
 import { DEFAULT_ROUTER_CONFIG, ALL_PROVIDER_TYPES } from './types.js';
 import { createLogger } from '../../../logging/logger-factory.js';
 // `console.warn` is not usable here: in MCP stdio mode stdout is the protocol
@@ -35,7 +38,7 @@ export const ROUTER_CONFIG_FILENAME = 'llm-config.json';
  * Empty array means "local provider, no key required". The set of
  * runtime-constructible providers is narrower than ExtendedProviderType
  * (e.g. onnx is in the type system but ProviderManager doesn't yet
- * have a case for it) — see RUNTIME_CONSTRUCTIBLE_PROVIDERS below.
+ * have a case for it) — see isRuntimeConstructible() below.
  */
 const PROVIDER_ENV_KEYS = {
     claude: ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY'],
@@ -58,14 +61,16 @@ const PROVIDER_ENV_KEYS = {
     onnx: [], // local
 };
 /**
- * Providers that ProviderManager.createProvider() can actually
- * instantiate today. Anything not in this set is dropped from the
+ * Built-in providers that ProviderManager.createProvider() can actually
+ * instantiate today. Anything not constructible is dropped from the
  * "available" set even if its env keys are present, so we don't emit
  * a "Failed to create X provider" warning at every kernel boot.
  *
  * Keep this in sync with src/shared/llm/provider-manager.ts:createProvider().
+ * ADR-127: externally registered providers are constructible too — call
+ * `isRuntimeConstructible()` rather than reading this set directly.
  */
-const RUNTIME_CONSTRUCTIBLE_PROVIDERS = new Set([
+const BUILTIN_CONSTRUCTIBLE_PROVIDERS = new Set([
     'claude',
     'claude-code',
     'codex',
@@ -77,6 +82,33 @@ const RUNTIME_CONSTRUCTIBLE_PROVIDERS = new Set([
     'bedrock',
     'cognitum',
 ]);
+/**
+ * Can `ProviderManager.createProvider()` build this type? True for the
+ * built-in constructible set, and for any provider registered per ADR-127.
+ */
+export function isRuntimeConstructible(provider) {
+    return BUILTIN_CONSTRUCTIBLE_PROVIDERS.has(provider) || isRegisteredProvider(provider);
+}
+/**
+ * Every provider type the router may legitimately be pointed at: the ones AQE
+ * ships plus the ones a downstream integrator registered (ADR-127).
+ *
+ * `ALL_PROVIDER_TYPES` deliberately stays frozen as "what AQE ships" — it is
+ * exported public API that consumers read — so validation paths call this
+ * instead of widening that constant at runtime.
+ */
+export function allSelectableProviderTypes() {
+    return [...ALL_PROVIDER_TYPES, ...registeredProviderTypes()];
+}
+/**
+ * Env keys that indicate a provider is configured. Returns `[]` for a provider
+ * AQE does not ship — an externally registered provider (ADR-127) brings its
+ * own availability check (a binary on PATH, typically) rather than an env key,
+ * so "no keys" is the correct answer, not a crash.
+ */
+function envKeysFor(provider) {
+    return isBuiltinExtendedProviderType(provider) ? PROVIDER_ENV_KEYS[provider] : [];
+}
 /**
  * Return the resolved config-file path for a project.
  * Caller may override projectRoot for tests; defaults to findProjectRoot().
@@ -91,13 +123,15 @@ export function getRouterConfigPath(projectRoot) {
  */
 export function detectAvailableProvidersFromEnv(env = process.env) {
     const available = new Set();
-    for (const provider of ALL_PROVIDER_TYPES) {
-        if (!RUNTIME_CONSTRUCTIBLE_PROVIDERS.has(provider)) {
+    // ADR-127: iterate registered providers alongside built-ins so an external
+    // host is detectable/enable-able without the user hand-editing `providers`.
+    for (const provider of allSelectableProviderTypes()) {
+        if (!isRuntimeConstructible(provider)) {
             // ProviderManager has no case for this provider yet (e.g. onnx).
             // Pretending it's available leads to "Failed to create" noise.
             continue;
         }
-        const keys = PROVIDER_ENV_KEYS[provider];
+        const keys = envKeysFor(provider);
         if (keys.length === 0) {
             // local providers — always available if their binary is, but at
             // config-merge time we treat them as "potentially available"
@@ -207,6 +241,19 @@ export function mergeRouterConfig(base, override) {
             };
         }
     }
+    // ADR-127: `externalProviders` gets the same keyed-object merge semantics —
+    // declaring one host must not wipe the others.
+    if (base.externalProviders || override.externalProviders) {
+        merged.externalProviders = { ...(base.externalProviders ?? {}) };
+        for (const [type, cfg] of Object.entries(override.externalProviders ?? {})) {
+            if (!cfg)
+                continue;
+            merged.externalProviders[type] = {
+                ...(base.externalProviders?.[type] ?? {}),
+                ...cfg,
+            };
+        }
+    }
     // Issue #568: `agentOverrides` gets keyed-object merge semantics (like
     // `providers`), NOT the shallow-replace treatment `fallbackChain` gets.
     // Overriding one agent type must not wipe the rest.
@@ -255,12 +302,14 @@ export function sanitizeAgentOverrides(raw) {
         const cleaned = {};
         if (entry.provider !== undefined) {
             const provider = entry.provider;
-            if (!ALL_PROVIDER_TYPES.includes(provider)) {
+            // ADR-127: registered external providers are valid override targets too.
+            const selectable = allSelectableProviderTypes();
+            if (!selectable.includes(provider)) {
                 warnings.push(`agentOverrides["${agentType}"].provider "${String(entry.provider)}" is not a known ` +
-                    `provider (${ALL_PROVIDER_TYPES.join(', ')}); ignoring this entry.`);
+                    `provider (${selectable.join(', ')}); ignoring this entry.`);
                 continue;
             }
-            if (!RUNTIME_CONSTRUCTIBLE_PROVIDERS.has(provider)) {
+            if (!isRuntimeConstructible(provider)) {
                 warnings.push(`agentOverrides["${agentType}"].provider "${provider}" cannot be instantiated at ` +
                     `runtime yet; ignoring this entry.`);
                 continue;
@@ -325,7 +374,7 @@ export function applyEnvProviderDetection(config, env = process.env, explicitlyD
         providers: { ...(config.providers ?? {}) },
     };
     for (const provider of available) {
-        const keys = PROVIDER_ENV_KEYS[provider];
+        const keys = envKeysFor(provider);
         if (keys.length === 0)
             continue; // local provider, leave default
         if (explicitlyDisabled.has(provider))
@@ -365,12 +414,17 @@ export function resolveProviderOverrideFromEnv(env = process.env) {
     if (!raw)
         return undefined;
     const normalized = raw === 'anthropic' ? 'claude' : raw;
-    if (ALL_PROVIDER_TYPES.includes(normalized)) {
+    // ADR-127: a registered external provider is selectable here on exactly the
+    // same terms as a built-in — that is the whole point of issue #628.
+    const selectable = allSelectableProviderTypes();
+    if (selectable.includes(normalized)) {
         return normalized;
     }
+    // The warning enumerates built-ins AND registered types, so a typo is never
+    // mistaken for "some provider got registered and I can't see it".
     // 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(', ')}.`);
+        `Valid values: ${selectable.join(', ')}.`);
     return undefined;
 }
 /**
@@ -381,6 +435,21 @@ export function resolveProviderOverrideFromEnv(env = process.env) {
 export function loadRouterConfig(options = {}) {
     const env = options.env ?? process.env;
     const onDisk = loadRouterConfigFile(options.projectRoot);
+    // ADR-127 (issue #628): register declared external providers FIRST. Every
+    // gate below — env detection, AQE_LLM_PROVIDER resolution, agentOverrides
+    // validation — asks the registry whether a type is selectable, so the
+    // declarations must be live before any of them run.
+    const { declarations, warnings: externalWarnings } = sanitizeExternalProviders(onDisk.externalProviders);
+    for (const warning of externalWarnings) {
+        logger.warn(`[llm-config] ${warning}`);
+    }
+    onDisk.externalProviders = declarations;
+    const registration = registerExternalProviders(declarations, {
+        sourceDetail: getRouterConfigPath(options.projectRoot),
+    });
+    for (const warning of registration.warnings) {
+        logger.warn(`[llm-config] ${warning}`);
+    }
     // Issue #568: validate the hand-editable per-agent map before it reaches the
     // router. Bad entries are dropped with a warning, never fatal.
     if (onDisk.agentOverrides !== undefined) {
@@ -394,6 +463,21 @@ export function loadRouterConfig(options = {}) {
     // ADR-123: an explicit `enabled: false` on disk is never resurrected by env.
     const explicitlyDisabled = collectExplicitlyDisabled(onDisk);
     let withEnv = applyEnvProviderDetection(merged, env, explicitlyDisabled);
+    // ADR-127: declaring an external host is enabling it. Without this the host
+    // would be selectable in principle but dropped by pickEnabledProviders,
+    // which is the "configured it and nothing happened" failure ADR-125 called
+    // out. An explicit `enabled: false` under `providers` still wins.
+    for (const type of registration.registered) {
+        if (explicitlyDisabled.has(type))
+            continue;
+        withEnv = {
+            ...withEnv,
+            providers: {
+                ...withEnv.providers,
+                [type]: { ...(withEnv.providers?.[type] ?? {}), enabled: true },
+            },
+        };
+    }
     // ADR-123: AQE_LLM_PROVIDER pins the default provider and enables it.
     const providerOverride = resolveProviderOverrideFromEnv(env);
     if (providerOverride) {
@@ -418,8 +502,12 @@ export function loadRouterConfig(options = {}) {
  */
 export function shouldEnableRouter(options = {}) {
     const env = options.env ?? process.env;
+    // ADR-127: a project whose only provider is an externally registered host
+    // still needs a router.
+    if (registeredProviderTypes().length > 0)
+        return true;
     for (const provider of ALL_PROVIDER_TYPES) {
-        const keys = PROVIDER_ENV_KEYS[provider];
+        const keys = envKeysFor(provider);
         if (keys.length === 0)
             continue;
         if (keys.some((k) => (env[k] ?? '').trim().length > 0)) {

package/dist/shared/llm/router/external-provider-config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Agentic QE v3 — Config-driven external provider registration
+ * ADR-127 (issue #628)
+ *
+ * Turns the `externalProviders` block of `.agentic-qe/llm-config.json` into
+ * live entries in the provider registry.
+ *
+ * This is the half of ADR-127 that actually unblocks the requester. An
+ * in-process `registerProvider()` call cannot reach the `aqe` CLI bundle or the
+ * MCP server bundle — they are separate esbuild artifacts spawned as
+ * subprocesses — but both call `loadRouterConfig()`, so a declaration on disk
+ * reaches both. No third-party code is imported: a declaration is data, and the
+ * provider it produces is AQE's own `ExternalCliProvider`.
+ *
+ * Untrusted-input discipline (inherited from ADR-125's `sanitizeAgentOverrides`):
+ * entries are validated and dropped **individually** with a warning. One
+ * malformed declaration must never fail router construction for the project.
+ */
+import { type ExternalCliProviderConfig } from '../providers/external-cli.js';
+/** Result of processing an `externalProviders` block. */
+export interface ExternalProviderRegistrationResult {
+    /** Types successfully registered. */
+    readonly registered: string[];
+    /** Human-readable reasons entries were dropped. */
+    readonly warnings: string[];
+}
+/**
+ * Register every valid declaration in an `externalProviders` block.
+ *
+ * Idempotent: re-registering the same type replaces the previous entry, and
+ * config-sourced registrations that are no longer declared are removed. API
+ * registrations (`registerProvider()`) are never touched — a config reload must
+ * not silently unregister a provider an embedder installed in-process.
+ */
+export declare function registerExternalProviders(declarations: Record<string, ExternalCliProviderConfig> | undefined, options?: {
+    sourceDetail?: string;
+}): ExternalProviderRegistrationResult;
+/**
+ * Extract and shallow-validate an `externalProviders` block read off disk.
+ * Returns only entries that are objects; deeper validation happens at
+ * registration so every rejection is reported through one path.
+ */
+export declare function sanitizeExternalProviders(raw: unknown): {
+    declarations: Record<string, ExternalCliProviderConfig>;
+    warnings: string[];
+};
+//# sourceMappingURL=external-provider-config.d.ts.map