agentic-qe 3.13.10 → 3.13.12

package/dist/shared/http/http-client.js

@@ -2,7 +2,7 @@
  * Agentic QE v3 - HTTP Client
  * Fetch wrapper with timeout, retry, and circuit breaker patterns
  */
-import { ok, err } from '../types';
+import { ok, err } from '../types/index.js';
 import { toError } from '../error-utils.js';
 // ============================================================================
 // Constants

package/dist/shared/http/index.js

@@ -1,5 +1,5 @@
 /**
  * Agentic QE v3 - HTTP Module Exports
  */
-export { HttpClient, getHttpClient, createHttpClient, } from './http-client';
+export { HttpClient, getHttpClient, createHttpClient, } from './http-client.js';
 //# sourceMappingURL=index.js.map

package/dist/shared/index.js

@@ -2,19 +2,19 @@
  * Agentic QE v3 - Shared Kernel
  * Common building blocks used across all domains
  */
-export * from './types';
-export * from './entities';
-export * from './value-objects';
-export * from './events';
-export * from './parsers';
-export * from './io';
-export * from './http';
-export * from './embeddings';
-export * from './git';
-export * from './security';
-export * from './metrics';
-export * from './safe-json';
-export * from './error-utils';
-export { DomainServiceRegistry, ServiceKeys } from './domain-service-registry';
-export { ProviderManager, CircuitBreaker as LLMCircuitBreaker, CostTracker, LLMCache, ClaudeProvider, OpenAIProvider, OllamaProvider, createLLMError, isLLMError, } from './llm';
+export * from './types/index.js';
+export * from './entities/index.js';
+export * from './value-objects/index.js';
+export * from './events/index.js';
+export * from './parsers/index.js';
+export * from './io/index.js';
+export * from './http/index.js';
+export * from './embeddings/index.js';
+export * from './git/index.js';
+export * from './security/index.js';
+export * from './metrics/index.js';
+export * from './safe-json.js';
+export * from './error-utils.js';
+export { DomainServiceRegistry, ServiceKeys } from './domain-service-registry.js';
+export { ProviderManager, CircuitBreaker as LLMCircuitBreaker, CostTracker, LLMCache, ClaudeProvider, OpenAIProvider, OllamaProvider, createLLMError, isLLMError, } from './llm/index.js';
 //# sourceMappingURL=index.js.map

package/dist/shared/io/file-reader.js

@@ -4,7 +4,7 @@
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { ok, err } from '../types';
+import { ok, err } from '../types/index.js';
 import { validatePath } from '../security/path-traversal-validator.js';
 import { safeJsonParse } from '../safe-json.js';
 export class FileReadError extends Error {

package/dist/shared/io/index.js

@@ -8,5 +8,5 @@ FileReader,
 // Error classes
 FileReadError, JsonParseError, PathTraversalError, // SEC-004: Added for path traversal security
 // Convenience functions
-getFileReader, readFile, readJSON, fileExists, listFiles, } from './file-reader';
+getFileReader, readFile, readJSON, fileExists, listFiles, } from './file-reader.js';
 //# sourceMappingURL=index.js.map

package/dist/shared/llm/billing-modes.d.ts

@@ -11,6 +11,11 @@ import type { BillingMode, LLMProvider, LLMProviderType } from './interfaces';
  * Resolve a provider's billing mode: the instance's own `billingMode` wins,
  * else the per-type default, else `metered-api` (the safe, cap-requiring
  * assumption for an unknown provider).
+ *
+ * ADR-127: an external provider is expected to declare `billingMode` on the
+ * instance, which is why the instance's own value is consulted first. When it
+ * declares nothing it lands on `metered-api` and therefore requires a budget,
+ * rather than being silently treated as free.
  */
 export declare function resolveBillingMode(provider: Pick<LLMProvider, 'type' | 'billingMode'>): BillingMode;
 /** Resolve a billing mode from a bare provider type. */

package/dist/shared/llm/billing-modes.js

@@ -6,7 +6,19 @@
  * kernel, `aqe health`) can resolve a billing mode without constructing a
  * provider, and so a provider that doesn't set `billingMode` still resolves.
  */
-/** Default billing mode per provider type. */
+import { isBuiltinProviderType } from './interfaces.js';
+import { registeredBillingDeclaration } from './provider-registry.js';
+/**
+ * Default billing mode per built-in provider type.
+ *
+ * ADR-127: keyed on `BuiltinProviderType`, not `LLMProviderType`, for two
+ * reasons: adding a built-in provider must still fail the build until this map
+ * is updated, and a lookup by an open `LLMProviderType` must type as
+ * `BillingMode | undefined` so the `?? 'metered-api'` fallback below is
+ * actually forced rather than merely present. An external provider registered
+ * per ADR-127 has no entry here and therefore falls through to `metered-api` —
+ * the conservative, cap-requiring assumption.
+ */
 const BILLING_MODE_BY_TYPE = {
     claude: 'metered-api',
     'claude-code': 'subscription',
@@ -19,17 +31,29 @@ const BILLING_MODE_BY_TYPE = {
     cognitum: 'metered-capped',
     ollama: 'local',
 };
+/**
+ * Look up the built-in default for a provider type, or `undefined` when the
+ * type is not one AQE ships (ADR-127: an externally registered provider).
+ */
+function builtinBillingMode(type) {
+    return isBuiltinProviderType(type) ? BILLING_MODE_BY_TYPE[type] : undefined;
+}
 /**
  * Resolve a provider's billing mode: the instance's own `billingMode` wins,
  * else the per-type default, else `metered-api` (the safe, cap-requiring
  * assumption for an unknown provider).
+ *
+ * ADR-127: an external provider is expected to declare `billingMode` on the
+ * instance, which is why the instance's own value is consulted first. When it
+ * declares nothing it lands on `metered-api` and therefore requires a budget,
+ * rather than being silently treated as free.
  */
 export function resolveBillingMode(provider) {
-    return provider.billingMode ?? BILLING_MODE_BY_TYPE[provider.type] ?? 'metered-api';
+    return provider.billingMode ?? builtinBillingMode(provider.type) ?? 'metered-api';
 }
 /** Resolve a billing mode from a bare provider type. */
 export function billingModeForType(type) {
-    return BILLING_MODE_BY_TYPE[type] ?? 'metered-api';
+    return builtinBillingMode(type) ?? 'metered-api';
 }
 /**
  * One-line notice shown at startup / in `aqe health` describing how the
@@ -47,6 +71,21 @@ export function billingNotice(provider, mode) {
             return (`ℹ️  LLM provider "${provider}" bills per-token but enforces a server-side ` +
                 `hard spend cap; it will pause at the cap rather than overspend.`);
         case 'subscription': {
+            // ADR-127: only a built-in may be named as drawing on a specific
+            // vendor's plan. An external provider that declares `subscription` is
+            // asserting something AQE cannot verify, and naming Claude Code or
+            // ChatGPT here would attribute the spend to a vendor that is not
+            // serving the work — the exact misrepresentation issue #628 refused to
+            // perform. Say what was declared, and say who declared it.
+            const declaration = registeredBillingDeclaration(provider);
+            if (declaration) {
+                const by = declaration.detail
+                    ? `declared by ${declaration.detail}`
+                    : `declared by ${declaration.source === 'config' ? 'config' : 'the registering caller'}`;
+                return (`ℹ️  LLM provider "${provider}" is an external provider that reports ` +
+                    `subscription billing (${by}) — AQE does not verify this. It draws on ` +
+                    `that host's own plan, not on your Claude Code or ChatGPT subscription.`);
+            }
             const sub = provider === 'codex' ? 'ChatGPT' : 'Claude Code';
             return (`ℹ️  LLM provider "${provider}" runs on your ${sub} subscription ` +
                 `(shared plan usage). Worst case is hitting your plan's rate limit and pausing — ` +

package/dist/shared/llm/circuit-breaker.js

@@ -11,7 +11,7 @@
  * - HALF-OPEN: Testing recovery, limited requests allowed
  */
 import { toError } from '../error-utils.js';
-import { createLLMError, } from './interfaces';
+import { createLLMError, } from './interfaces.js';
 /**
  * Default circuit breaker configuration
  */

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

@@ -41,11 +41,14 @@
  * const costs = manager.getCostSummary('day');
  * ```
  */
-export { type LLMProviderType, type MessageRole, type Message, type TokenUsage, type CostInfo, type LLMResponse, type EmbeddingResponse, type CompletionResponse, type LLMConfig, type ClaudeConfig, type OpenAIConfig, type OllamaConfig, type OpenRouterConfig, type GeminiConfig, type AzureOpenAIConfig, type BedrockConfig, type ProviderManagerConfig, type GenerateOptions, type EmbedOptions, type CompleteOptions, type LLMProvider, type HealthCheckResult, type CircuitBreakerState, type CircuitBreakerConfig, type CircuitBreakerStats, type CostPeriod, type CostSummary, type CostAlert, type CacheEntry, type LLMCacheConfig, type LLMCacheStats, type ProviderSelection, type ProviderMetrics, type LLMErrorCode, type LLMError, createLLMError, isLLMError, } from './interfaces';
+export { type LLMProviderType, type MessageRole, type Message, type TokenUsage, type CostInfo, type LLMResponse, type EmbeddingResponse, type CompletionResponse, type LLMConfig, type ClaudeConfig, type OpenAIConfig, type OllamaConfig, type OpenRouterConfig, type GeminiConfig, type AzureOpenAIConfig, type BedrockConfig, type ProviderManagerConfig, type GenerateOptions, type EmbedOptions, type CompleteOptions, type BuiltinProviderType, BUILTIN_PROVIDER_TYPES, isBuiltinProviderType, type LLMProvider, type HealthCheckResult, type CircuitBreakerState, type CircuitBreakerConfig, type CircuitBreakerStats, type CostPeriod, type CostSummary, type CostAlert, type CacheEntry, type LLMCacheConfig, type LLMCacheStats, type ProviderSelection, type ProviderMetrics, type LLMErrorCode, type LLMError, createLLMError, isLLMError, } from './interfaces';
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG, OpenAIProvider, DEFAULT_OPENAI_CONFIG, OllamaProvider, DEFAULT_OLLAMA_CONFIG, OpenRouterProvider, DEFAULT_OPENROUTER_CONFIG, GeminiProvider, DEFAULT_GEMINI_CONFIG, AzureOpenAIProvider, DEFAULT_AZURE_OPENAI_CONFIG, BedrockProvider, DEFAULT_BEDROCK_CONFIG, } from './providers';
 export { CircuitBreaker, CircuitBreakerManager, DEFAULT_CIRCUIT_BREAKER_CONFIG, } from './circuit-breaker';
 export { LLMCache, LLMResponseCache, DEFAULT_CACHE_CONFIG, type CacheableResponse, } from './cache';
 export { CostTracker, MODEL_PRICING, getGlobalCostTracker, resetGlobalCostTracker, } from './cost-tracker';
+export { registerProvider, tryRegisterProvider, unregisterProvider, resetProviderRegistry, isRegisteredProvider, getRegisteredProvider, listRegisteredProviders, registeredProviderTypes, createRegisteredProvider, registeredBillingDeclaration, validateProviderType, validateProviderInstance, type ProviderFactory, type ProviderRegistrationOptions, type ProviderRegistrationSource, type RegisteredProvider, } from './provider-registry';
+export { ExternalCliProvider, validateExternalCliConfig, resolvesOnPath, DEFAULT_EXTERNAL_CLI_TIMEOUT_MS, DEFAULT_EXTERNAL_CLI_CONCURRENCY, EXTERNAL_CLI_DEFAULT_MODEL, type ExternalCliProviderConfig, } from './providers/external-cli';
+export { registerExternalProviders, sanitizeExternalProviders, type ExternalProviderRegistrationResult, } from './router/external-provider-config';
 export { ProviderManager, createProviderManager, createQEProviderManager, DEFAULT_PROVIDER_MANAGER_CONFIG, } from './provider-manager';
 export { mapModelId, normalizeModelId, getCanonicalName, getModelFamily, getModelTier, isModelAvailableOnProvider, getSupportedProviders, listCanonicalModels, listModelsByProvider, listModelsByFamily, listModelsByTier, getModelMapping, MODEL_MAPPINGS, type ProviderType, type ModelMapping, } from './model-mapping';
 export { getModelCapabilities, getModelCost, getModelInfo, listModels, findModelsByCapability, findModelsByCost, findCheapestModel, findBestModelInBudget, getRecommendedModels, getDeprecationStatus, estimateRequestCost, compareModels, MODEL_REGISTRY, type ModelCapabilities, type ModelCostInfo, type ModelInfo, } from './model-registry';

package/dist/shared/llm/index.js

@@ -42,26 +42,30 @@
  * ```
  */
 // Core interfaces
-export { createLLMError, isLLMError, } from './interfaces';
+export { BUILTIN_PROVIDER_TYPES, isBuiltinProviderType, createLLMError, isLLMError, } from './interfaces.js';
 // Providers (ADR-043: All 7 provider types)
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG, OpenAIProvider, DEFAULT_OPENAI_CONFIG, OllamaProvider, DEFAULT_OLLAMA_CONFIG, 
 // ADR-043 New Providers
-OpenRouterProvider, DEFAULT_OPENROUTER_CONFIG, GeminiProvider, DEFAULT_GEMINI_CONFIG, AzureOpenAIProvider, DEFAULT_AZURE_OPENAI_CONFIG, BedrockProvider, DEFAULT_BEDROCK_CONFIG, } from './providers';
+OpenRouterProvider, DEFAULT_OPENROUTER_CONFIG, GeminiProvider, DEFAULT_GEMINI_CONFIG, AzureOpenAIProvider, DEFAULT_AZURE_OPENAI_CONFIG, BedrockProvider, DEFAULT_BEDROCK_CONFIG, } from './providers/index.js';
 // Circuit breaker
-export { CircuitBreaker, CircuitBreakerManager, DEFAULT_CIRCUIT_BREAKER_CONFIG, } from './circuit-breaker';
+export { CircuitBreaker, CircuitBreakerManager, DEFAULT_CIRCUIT_BREAKER_CONFIG, } from './circuit-breaker.js';
 // Cache
-export { LLMCache, LLMResponseCache, DEFAULT_CACHE_CONFIG, } from './cache';
+export { LLMCache, LLMResponseCache, DEFAULT_CACHE_CONFIG, } from './cache.js';
 // Cost tracker
-export { CostTracker, MODEL_PRICING, getGlobalCostTracker, resetGlobalCostTracker, } from './cost-tracker';
+export { CostTracker, MODEL_PRICING, getGlobalCostTracker, resetGlobalCostTracker, } from './cost-tracker.js';
+// External provider registration (ADR-127 / issue #628)
+export { registerProvider, tryRegisterProvider, unregisterProvider, resetProviderRegistry, isRegisteredProvider, getRegisteredProvider, listRegisteredProviders, registeredProviderTypes, createRegisteredProvider, registeredBillingDeclaration, validateProviderType, validateProviderInstance, } from './provider-registry.js';
+export { ExternalCliProvider, validateExternalCliConfig, resolvesOnPath, DEFAULT_EXTERNAL_CLI_TIMEOUT_MS, DEFAULT_EXTERNAL_CLI_CONCURRENCY, EXTERNAL_CLI_DEFAULT_MODEL, } from './providers/external-cli.js';
+export { registerExternalProviders, sanitizeExternalProviders, } from './router/external-provider-config.js';
 // Provider manager
-export { ProviderManager, createProviderManager, createQEProviderManager, DEFAULT_PROVIDER_MANAGER_CONFIG, } from './provider-manager';
+export { ProviderManager, createProviderManager, createQEProviderManager, DEFAULT_PROVIDER_MANAGER_CONFIG, } from './provider-manager.js';
 // Model mapping (ADR-043)
-export { mapModelId, normalizeModelId, getCanonicalName, getModelFamily, getModelTier, isModelAvailableOnProvider, getSupportedProviders, listCanonicalModels, listModelsByProvider, listModelsByFamily, listModelsByTier, getModelMapping, MODEL_MAPPINGS, } from './model-mapping';
+export { mapModelId, normalizeModelId, getCanonicalName, getModelFamily, getModelTier, isModelAvailableOnProvider, getSupportedProviders, listCanonicalModels, listModelsByProvider, listModelsByFamily, listModelsByTier, getModelMapping, MODEL_MAPPINGS, } from './model-mapping.js';
 // Model registry (ADR-043)
-export { getModelCapabilities, getModelCost, getModelInfo, listModels, findModelsByCapability, findModelsByCost, findCheapestModel, findBestModelInBudget, getRecommendedModels, getDeprecationStatus, estimateRequestCost, compareModels, MODEL_REGISTRY, } from './model-registry';
+export { getModelCapabilities, getModelCost, getModelInfo, listModels, findModelsByCapability, findModelsByCost, findCheapestModel, findBestModelInBudget, getRecommendedModels, getDeprecationStatus, estimateRequestCost, compareModels, MODEL_REGISTRY, } from './model-registry.js';
 // Metrics (ADR-043 Milestone 11)
-export { RouterMetricsCollector, createRouterMetricsCollector, getGlobalRouterMetrics, resetGlobalRouterMetrics, CostMetricsCollector, createCostMetricsCollector, getGlobalCostMetrics, resetGlobalCostMetrics, } from './metrics';
+export { RouterMetricsCollector, createRouterMetricsCollector, getGlobalRouterMetrics, resetGlobalRouterMetrics, CostMetricsCollector, createCostMetricsCollector, getGlobalCostMetrics, resetGlobalCostMetrics, } from './metrics/index.js';
 // HybridRouter (ADR-043: Intelligent provider routing)
-export { HybridRouter, createHybridRouter, createQERouter, } from './router';
-export { ALL_PROVIDER_TYPES, DEFAULT_ROUTER_CONFIG, DEFAULT_FALLBACK_BEHAVIOR, RoutingRuleEngine, DEFAULT_QE_ROUTING_RULES, } from './router';
+export { HybridRouter, createHybridRouter, createQERouter, } from './router/index.js';
+export { ALL_PROVIDER_TYPES, DEFAULT_ROUTER_CONFIG, DEFAULT_FALLBACK_BEHAVIOR, RoutingRuleEngine, DEFAULT_QE_ROUTING_RULES, } from './router/index.js';
 //# sourceMappingURL=index.js.map

package/dist/shared/llm/interfaces.d.ts

@@ -9,9 +9,32 @@
  * - Response caching
  */
 /**
- * Supported LLM provider types
+ * Provider types AQE ships built in. Exhaustive — safe to key a `Record` on.
+ *
+ * ADR-127: this is the closed half of the provider identity space. Anything
+ * that must be exhaustively handled (billing defaults, env-key maps, prompt
+ * translation strategies) keys on THIS type, not on `LLMProviderType`.
  */
-export type LLMProviderType = 'claude' | 'claude-code' | 'codex' | 'openai' | 'ollama' | 'openrouter' | 'bedrock' | 'azure-openai' | 'gemini' | 'cognitum';
+export type BuiltinProviderType = 'claude' | 'claude-code' | 'codex' | 'openai' | 'ollama' | 'openrouter' | 'bedrock' | 'azure-openai' | 'gemini' | 'cognitum';
+/**
+ * Supported LLM provider types.
+ *
+ * ADR-127: open. A downstream integrator may register an additional provider
+ * identity (via `registerProvider()` or an `externalProviders` entry in
+ * `.agentic-qe/llm-config.json`) so `AQE_LLM_PROVIDER=<their-host>` resolves to
+ * a provider they supply, instead of forking this union or misrepresenting
+ * their host as an unrelated vendor (issue #628).
+ *
+ * The `(string & {})` arm keeps editor autocomplete on the built-ins while
+ * admitting registered identities. Because this type is no longer exhaustive,
+ * a `Record` keyed on it can no longer be checked by the compiler — use
+ * `BuiltinProviderType` for those and read through a fallback.
+ */
+export type LLMProviderType = BuiltinProviderType | (string & {});
+/** The built-in provider types, as a runtime array. ADR-127. */
+export declare const BUILTIN_PROVIDER_TYPES: readonly BuiltinProviderType[];
+/** Type guard: is this one of the provider types AQE ships? */
+export declare function isBuiltinProviderType(type: string): type is BuiltinProviderType;
 /**
  * Message role in a conversation
  */
@@ -629,7 +652,15 @@ export interface ProviderMetrics {
 /**
  * LLM-specific error codes
  */
-export type LLMErrorCode = 'API_KEY_INVALID' | 'API_KEY_MISSING' | 'RATE_LIMITED' | 'CONTEXT_LENGTH_EXCEEDED' | 'CONTENT_FILTERED' | 'MODEL_NOT_FOUND' | 'PROVIDER_UNAVAILABLE' | 'CIRCUIT_OPEN' | 'TIMEOUT' | 'NETWORK_ERROR' | 'COST_LIMIT_EXCEEDED' | 'UNKNOWN';
+export type LLMErrorCode = 'API_KEY_INVALID' | 'API_KEY_MISSING' | 'RATE_LIMITED' | 'CONTEXT_LENGTH_EXCEEDED' | 'CONTENT_FILTERED' | 'MODEL_NOT_FOUND' | 'PROVIDER_UNAVAILABLE' | 'CIRCUIT_OPEN' | 'TIMEOUT' | 'NETWORK_ERROR' | 'COST_LIMIT_EXCEEDED'
+/** ADR-127: a provider registration or its produced instance was malformed. */
+ | 'INVALID_REGISTRATION'
+/**
+ * ADR-127: this provider has no embeddings endpoint. Distinct from a
+ * failure — the caller should fall back to another provider rather than
+ * retry, and must never receive a fabricated vector.
+ */
+ | 'EMBEDDING_UNSUPPORTED' | 'UNKNOWN';
 /**
  * LLM error with rich context
  */

package/dist/shared/llm/interfaces.js

@@ -8,6 +8,23 @@
  * - Circuit breaker support for resilience
  * - Response caching
  */
+/** The built-in provider types, as a runtime array. ADR-127. */
+export const BUILTIN_PROVIDER_TYPES = [
+    'claude',
+    'claude-code',
+    'codex',
+    'openai',
+    'ollama',
+    'openrouter',
+    'bedrock',
+    'azure-openai',
+    'gemini',
+    'cognitum',
+];
+/** Type guard: is this one of the provider types AQE ships? */
+export function isBuiltinProviderType(type) {
+    return BUILTIN_PROVIDER_TYPES.includes(type);
+}
 /**
  * Create an LLM error
  */

package/dist/shared/llm/metrics/cost-metrics.js

@@ -8,8 +8,8 @@
  * - Budget monitoring and alerts
  * - Cost optimization insights
  */
-import { ALL_PROVIDER_TYPES } from '../router/types';
-import { MODEL_PRICING } from '../cost-tracker';
+import { ALL_PROVIDER_TYPES } from '../router/types.js';
+import { MODEL_PRICING } from '../cost-tracker.js';
 // ============================================================================
 // CostMetricsCollector Implementation
 // ============================================================================

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

@@ -9,7 +9,7 @@
  * - Audit logging
  */
 // Router metrics
-export { RouterMetricsCollector, createRouterMetricsCollector, getGlobalRouterMetrics, resetGlobalRouterMetrics, } from './router-metrics';
+export { RouterMetricsCollector, createRouterMetricsCollector, getGlobalRouterMetrics, resetGlobalRouterMetrics, } from './router-metrics.js';
 // Cost metrics
-export { CostMetricsCollector, createCostMetricsCollector, getGlobalCostMetrics, resetGlobalCostMetrics, } from './cost-metrics';
+export { CostMetricsCollector, createCostMetricsCollector, getGlobalCostMetrics, resetGlobalCostMetrics, } from './cost-metrics.js';
 //# sourceMappingURL=index.js.map

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

@@ -10,7 +10,7 @@
  * - Time-windowed aggregations
  */
 import { randomUUID } from 'crypto';
-import { ALL_PROVIDER_TYPES, } from '../router/types';
+import { ALL_PROVIDER_TYPES, } from '../router/types.js';
 // ============================================================================
 // RouterMetricsCollector Implementation
 // ============================================================================

package/dist/shared/llm/model-registry.js

@@ -22,7 +22,7 @@
  * const visionModels = findModelsByCapability({ supportsVision: true });
  * ```
  */
-import { normalizeModelId, getModelMapping, } from './model-mapping';
+import { normalizeModelId, getModelMapping, } from './model-mapping.js';
 // ============================================================================
 // Model Registry Data
 // ============================================================================

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

@@ -9,24 +9,25 @@
  * - Response caching
  * - Cost tracking
  */
-import { createLLMError, } from './interfaces';
+import { createLLMError, } from './interfaces.js';
 import { secureRandomInt } from '../utils/crypto-random.js';
-import { CircuitBreakerManager } from './circuit-breaker';
-import { LLMResponseCache } from './cache';
-import { CostTracker, getGlobalCostTracker } from './cost-tracker';
-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';
-import { OpenRouterProvider } from './providers/openrouter';
-import { GeminiProvider } from './providers/gemini';
-import { AzureOpenAIProvider } from './providers/azure-openai';
-import { BedrockProvider } from './providers/bedrock';
+import { CircuitBreakerManager } from './circuit-breaker.js';
+import { LLMResponseCache } from './cache.js';
+import { CostTracker, getGlobalCostTracker } from './cost-tracker.js';
+import { createDefaultSpendLedger, InMemorySpendLedger, } from './spend-ledger.js';
+import { resolveBillingMode, billingNotice } from './billing-modes.js';
+import { ClaudeProvider } from './providers/claude.js';
+import { ClaudeCodeProvider } from './providers/claude-code.js';
+import { CodexProvider } from './providers/codex.js';
+import { CognitumProvider } from './providers/cognitum.js';
+import { OpenAIProvider } from './providers/openai.js';
+import { OllamaProvider } from './providers/ollama.js';
+import { OpenRouterProvider } from './providers/openrouter.js';
+import { GeminiProvider } from './providers/gemini.js';
+import { AzureOpenAIProvider } from './providers/azure-openai.js';
+import { BedrockProvider } from './providers/bedrock.js';
 import { toError } from '../error-utils.js';
+import { createRegisteredProvider } from './provider-registry.js';
 /**
  * Default provider manager configuration
  */
@@ -441,7 +442,13 @@ export class ProviderManager {
             case 'bedrock':
                 return new BedrockProvider(this.config.providers.bedrock);
             default:
-                throw new Error(`Unknown provider type: ${type}`);
+                // ADR-127: not a built-in. Fall through to the external provider
+                // registry, which throws PROVIDER_UNAVAILABLE when nothing is
+                // registered under this type — preserving the previous behavior for a
+                // genuinely unknown type while letting a downstream integrator supply
+                // one. Built-in cases are matched first, so a registration can never
+                // shadow a provider AQE ships.
+                return createRegisteredProvider(type);
         }
     }
     /**

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

@@ -0,0 +1,135 @@
+/**
+ * Agentic QE v3 — External provider registry
+ * ADR-127: External provider registration (issue #628)
+ *
+ * The sanctioned extension point for provider identity. A downstream
+ * integrator can register an additional provider type so
+ * `AQE_LLM_PROVIDER=<their-host>` resolves to a provider they supply, instead
+ * of forking `BuiltinProviderType` or projecting their host onto an unrelated
+ * vendor identity (which would make `aqe health` misreport who served the work).
+ *
+ * Two entry points feed this registry:
+ *   1. `registerProvider()` — for a consumer that embeds AQE in-process.
+ *   2. The `externalProviders` block in `.agentic-qe/llm-config.json` — for the
+ *      subprocess case (the `aqe` CLI and MCP server are separate bundles, so
+ *      an in-process call cannot reach them). See `external-provider-config.ts`.
+ *
+ * State is process-global module state, matching ADR-125's
+ * `agent-router-config.ts`. Tests must call `resetProviderRegistry()`.
+ */
+import { type BillingMode, type LLMProvider, type LLMProviderType } from './interfaces';
+/**
+ * Builds a provider instance. Receives whatever config the caller registered
+ * the provider with (an `externalProviders` entry, or the `config` passed to
+ * `registerProvider`). Must return an object satisfying `LLMProvider`.
+ */
+export type ProviderFactory = (config?: unknown) => LLMProvider;
+/** Where a registration came from — surfaced by `aqe health` (ADR-127). */
+export type ProviderRegistrationSource = 'api' | 'config';
+export interface ProviderRegistrationOptions {
+    /**
+     * How this provider bills. ADR-123/ADR-127: this is an *assertion by the
+     * registrant*, not something AQE can verify, so it is recorded with its
+     * source and surfaced as "declared by". Omitting it resolves to
+     * `metered-api` — the conservative, cap-requiring assumption.
+     */
+    readonly billingMode?: BillingMode;
+    /** Human-facing name for CLI output. Defaults to the type string. */
+    readonly displayName?: string;
+    /** Models this provider accepts. Informational; used by CLI listings. */
+    readonly models?: readonly string[];
+    /** Opaque config handed back to the factory on each construction. */
+    readonly config?: unknown;
+    /** Provenance. Defaults to `'api'`. */
+    readonly source?: ProviderRegistrationSource;
+    /** For `source: 'config'`, the file the declaration came from. */
+    readonly sourceDetail?: string;
+}
+export interface RegisteredProvider extends ProviderRegistrationOptions {
+    readonly type: string;
+    readonly factory: ProviderFactory;
+    readonly source: ProviderRegistrationSource;
+}
+/**
+ * Validate a candidate provider type. Returns an error message, or `undefined`
+ * when the type is acceptable.
+ *
+ * Exported so config-driven registration can report per-entry problems without
+ * throwing (a bad line in a config file must never be fatal — ADR-125's
+ * drop-individually discipline).
+ */
+export declare function validateProviderType(type: string): string | undefined;
+/**
+ * Register an additional provider type (ADR-127).
+ *
+ * Throws on an invalid or colliding type — an in-process caller passing a bad
+ * type has a bug, and silently ignoring it would strand `AQE_LLM_PROVIDER`
+ * pointing at nothing. Config-driven registration uses
+ * `tryRegisterProvider()` instead, which reports rather than throws.
+ *
+ * Re-registering the same type replaces the previous entry.
+ *
+ * @example
+ * ```typescript
+ * import { registerProvider } from 'agentic-qe/shared/llm';
+ *
+ * registerProvider('my-host', () => new MyHostProvider(), {
+ *   billingMode: 'subscription',
+ *   displayName: 'My Host (subscription)',
+ * });
+ * // now AQE_LLM_PROVIDER=my-host resolves
+ * ```
+ */
+export declare function registerProvider(type: string, factory: ProviderFactory, options?: ProviderRegistrationOptions): void;
+/**
+ * Config-driven registration. Returns an error message instead of throwing, so
+ * one malformed `externalProviders` entry drops itself rather than failing
+ * router construction for the whole project.
+ */
+export declare function tryRegisterProvider(type: string, factory: ProviderFactory, options?: ProviderRegistrationOptions): string | undefined;
+/** Remove a registration. Returns true if something was removed. */
+export declare function unregisterProvider(type: string): boolean;
+/**
+ * Clear all registrations. Tests must call this between cases — the registry
+ * is module-global (ADR-125 precedent: `resetAgentProviderOverrides()`).
+ */
+export declare function resetProviderRegistry(): void;
+/** Is this type registered as an external provider? */
+export declare function isRegisteredProvider(type: string): boolean;
+/** Get a registration, or `undefined`. */
+export declare function getRegisteredProvider(type: string): RegisteredProvider | undefined;
+/** All registrations, in registration order. */
+export declare function listRegisteredProviders(): readonly RegisteredProvider[];
+/** Just the registered type strings. */
+export declare function registeredProviderTypes(): readonly string[];
+/**
+ * Validate that a factory actually produced something the manager can drive.
+ * Returns an error message, or `undefined` when the instance conforms.
+ *
+ * This runs at construction rather than registration because the product is
+ * what must conform, and calling a factory eagerly at registration time would
+ * be an unwanted side effect (a provider constructor may spawn processes or
+ * open handles).
+ */
+export declare function validateProviderInstance(type: string, instance: unknown): string | undefined;
+/**
+ * Build an instance of a registered provider.
+ *
+ * Throws `PROVIDER_UNAVAILABLE` when the type is not registered, and
+ * `INVALID_REQUEST` when the factory produced something that is not a usable
+ * `LLMProvider`. `ProviderManager.createProvider()` calls this from the
+ * `default` arm of its built-in `switch`, so built-ins always win and a
+ * registration can never shadow one.
+ */
+export declare function createRegisteredProvider(type: LLMProviderType): LLMProvider;
+/**
+ * The billing mode a registered provider declared, with its provenance, for
+ * `aqe health` to render as "external — <mode> (declared by <source>)".
+ * Returns `undefined` for a type that is not registered.
+ */
+export declare function registeredBillingDeclaration(type: LLMProviderType): {
+    mode: BillingMode;
+    source: ProviderRegistrationSource;
+    detail?: string;
+} | undefined;
+//# sourceMappingURL=provider-registry.d.ts.map