agentic-qe 3.13.11 → 3.14.0

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

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

@@ -0,0 +1,227 @@
+/**
+ * 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 { isBuiltinProviderType, createLLMError, } from './interfaces.js';
+// ============================================================================
+// Registry state
+// ============================================================================
+const registry = new Map();
+/**
+ * Reserved identifiers that must never be claimed by an external provider.
+ * `anthropic` is normalized to `claude` by `resolveProviderOverrideFromEnv`,
+ * so registering it would create a type whose env selector is unreachable.
+ */
+const RESERVED_TYPES = new Set(['anthropic']);
+/** A provider type must be a URL/env-safe slug — this is an env var value. */
+const VALID_TYPE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+// ============================================================================
+// Registration
+// ============================================================================
+/**
+ * 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 function validateProviderType(type) {
+    if (typeof type !== 'string' || type.trim().length === 0) {
+        return 'provider type must be a non-empty string';
+    }
+    if (type !== type.toLowerCase()) {
+        return `provider type "${type}" must be lowercase (AQE_LLM_PROVIDER is matched case-insensitively)`;
+    }
+    if (!VALID_TYPE.test(type)) {
+        return `provider type "${type}" must match ${VALID_TYPE.source} (lowercase alphanumeric and dashes)`;
+    }
+    if (isBuiltinProviderType(type)) {
+        return `provider type "${type}" is built in and cannot be overridden`;
+    }
+    if (RESERVED_TYPES.has(type)) {
+        return `provider type "${type}" is reserved`;
+    }
+    return 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 function registerProvider(type, factory, options = {}) {
+    const problem = validateProviderType(type);
+    if (problem) {
+        throw createLLMError(problem, 'INVALID_REGISTRATION', { retryable: false });
+    }
+    if (typeof factory !== 'function') {
+        throw createLLMError(`provider "${type}" must be registered with a factory function`, 'INVALID_REGISTRATION', { retryable: false });
+    }
+    registry.set(type, {
+        ...options,
+        type,
+        factory,
+        source: options.source ?? 'api',
+    });
+}
+/**
+ * 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 function tryRegisterProvider(type, factory, options = {}) {
+    try {
+        registerProvider(type, factory, options);
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+/** Remove a registration. Returns true if something was removed. */
+export function unregisterProvider(type) {
+    return registry.delete(type);
+}
+/**
+ * Clear all registrations. Tests must call this between cases — the registry
+ * is module-global (ADR-125 precedent: `resetAgentProviderOverrides()`).
+ */
+export function resetProviderRegistry() {
+    registry.clear();
+}
+// ============================================================================
+// Lookup
+// ============================================================================
+/** Is this type registered as an external provider? */
+export function isRegisteredProvider(type) {
+    return registry.has(type);
+}
+/** Get a registration, or `undefined`. */
+export function getRegisteredProvider(type) {
+    return registry.get(type);
+}
+/** All registrations, in registration order. */
+export function listRegisteredProviders() {
+    return [...registry.values()];
+}
+/** Just the registered type strings. */
+export function registeredProviderTypes() {
+    return [...registry.keys()];
+}
+// ============================================================================
+// Construction
+// ============================================================================
+/**
+ * The subset of `LLMProvider` a registered provider must actually implement
+ * for the manager and router to drive it. `embed` is deliberately excluded —
+ * a CLI-shaped host cannot generally offer an embeddings endpoint, and
+ * `ExternalCliProvider` throws `EMBEDDING_UNSUPPORTED` so the caller falls
+ * back rather than receiving a fabricated vector.
+ */
+const REQUIRED_PROVIDER_METHODS = [
+    'isAvailable',
+    'healthCheck',
+    'generate',
+    'complete',
+    'getConfig',
+    'getSupportedModels',
+    'getCostPerToken',
+    'dispose',
+];
+/**
+ * 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 function validateProviderInstance(type, instance) {
+    if (!instance || typeof instance !== 'object') {
+        return `provider "${type}" factory returned ${instance === null ? 'null' : typeof instance}, expected an LLMProvider`;
+    }
+    const candidate = instance;
+    const missing = REQUIRED_PROVIDER_METHODS.filter((method) => typeof candidate[method] !== 'function');
+    if (missing.length > 0) {
+        return `provider "${type}" is missing required LLMProvider method(s): ${missing.join(', ')}`;
+    }
+    if (typeof candidate.type !== 'string' || candidate.type.length === 0) {
+        return `provider "${type}" must expose a non-empty \`type\``;
+    }
+    if (candidate.type !== type) {
+        return `provider "${type}" reports type "${candidate.type}" — a provider must not claim an identity other than the one it was registered under`;
+    }
+    return 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 function createRegisteredProvider(type) {
+    const registration = registry.get(type);
+    if (!registration) {
+        throw createLLMError(`Unknown provider type: ${type}`, 'PROVIDER_UNAVAILABLE', {
+            retryable: false,
+        });
+    }
+    const instance = registration.factory(registration.config);
+    const problem = validateProviderInstance(type, instance);
+    if (problem) {
+        throw createLLMError(problem, 'INVALID_REGISTRATION', { retryable: false });
+    }
+    return instance;
+}
+/**
+ * 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 function registeredBillingDeclaration(type) {
+    const registration = registry.get(type);
+    if (!registration)
+        return undefined;
+    return {
+        // Absent declaration → metered-api: assume it costs money and needs a cap.
+        mode: registration.billingMode ?? 'metered-api',
+        source: registration.source,
+        detail: registration.sourceDetail,
+    };
+}
+//# sourceMappingURL=provider-registry.js.map

package/dist/shared/llm/providers/external-cli.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 { type BillingMode, type CompleteOptions, type CompletionResponse, type EmbedOptions, type EmbeddingResponse, type GenerateOptions, type HealthCheckResult, type LLMConfig, type LLMProvider, type LLMResponse, type Message } from '../interfaces';
+/**
+ * A declared external CLI provider. This is the on-disk contract — see ADR-127
+ * §Schema. Everything except `kind` and `command` is optional.
+ */
+export interface ExternalCliProviderConfig {
+    /** Discriminator. Only `'cli'` exists today; `'http'` is a follow-up. */
+    readonly kind: 'cli';
+    /** argv. Not shell-interpreted — `command[0]` is the binary. */
+    readonly command: readonly string[];
+    /** How this host bills. Unverified assertion; defaults to `metered-api`. */
+    readonly billingMode?: BillingMode;
+    /** Models this host accepts. Defaults to `['default']`. */
+    readonly models?: readonly string[];
+    /** Model used when the caller does not name one. Defaults to `models[0]`. */
+    readonly defaultModel?: string;
+    /** Flag used to pass the model, e.g. `--model`. Omitted = never passed. */
+    readonly modelFlag?: string;
+    /** Hard timeout per invocation. Defaults to 180000. */
+    readonly timeoutMs?: number;
+    /** Max concurrent subprocesses. Defaults to 2. */
+    readonly maxConcurrency?: number;
+    /** Env vars removed from the child process before spawning. */
+    readonly stripEnv?: readonly string[];
+    /** Human-facing name for CLI output. Defaults to the type string. */
+    readonly displayName?: string;
+}
+export declare const DEFAULT_EXTERNAL_CLI_TIMEOUT_MS = 180000;
+export declare const DEFAULT_EXTERNAL_CLI_CONCURRENCY = 2;
+export declare 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 declare function validateExternalCliConfig(type: string, config: unknown): string | undefined;
+export declare class ExternalCliProvider implements LLMProvider {
+    readonly type: string;
+    readonly name: string;
+    readonly billingMode: BillingMode;
+    private readonly config;
+    private requestCounter;
+    private availabilityCache?;
+    private active;
+    private readonly queue;
+    constructor(type: string, config: ExternalCliProviderConfig);
+    /**
+     * 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.
+     */
+    isAvailable(): Promise<boolean>;
+    healthCheck(): Promise<HealthCheckResult>;
+    generate(input: string | Message[], options?: GenerateOptions): Promise<LLMResponse>;
+    /**
+     * 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.
+     */
+    embed(_text: string, _options?: EmbedOptions): Promise<EmbeddingResponse>;
+    complete(prompt: string, options?: CompleteOptions): Promise<CompletionResponse>;
+    getConfig(): LLMConfig;
+    getSupportedModels(): string[];
+    /**
+     * Unknown. A declared host does not tell AQE its per-token price, and
+     * inventing one would feed fabricated numbers into cost reporting.
+     */
+    getCostPerToken(): {
+        input: number;
+        output: number;
+    };
+    dispose(): Promise<void>;
+    private defaultModel;
+    /**
+     * 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?: readonly string[], base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    private classifyError;
+    private spawnHost;
+    /** Semaphore so we never spawn unbounded host subprocesses. */
+    private withConcurrency;
+}
+/**
+ * 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 declare function resolvesOnPath(binary: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 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 declare function flattenPrompt(input: string | Message[], systemPrompt?: string): string;
+//# sourceMappingURL=external-cli.d.ts.map