agentic-qe 3.9.36 → 3.10.1

package/dist/kernel/kernel.js

@@ -21,6 +21,7 @@ import { PluginCache } from '../plugins/cache';
 import { CapturedExperienceBridge } from '../bridge/captured-experience-bridge.js';
 import { DreamScheduler } from '../learning/dream/dream-scheduler.js';
 import { createDreamEngine } from '../learning/dream/dream-engine.js';
+import { createLLMRouterService, } from '../shared/llm/llm-router-service.js';
 // Import domain plugin factories
 import { createTestGenerationPlugin } from '../domains/test-generation/plugin';
 import { createTestExecutionPlugin } from '../domains/test-execution/plugin';
@@ -44,21 +45,25 @@ import '../domains/security-compliance';
 import '../domains/code-intelligence';
 import '../domains/quality-assessment';
 import { createEnterpriseIntegrationPlugin } from '../domains/enterprise-integration/plugin';
+// NOTE: underlying createXxxPlugin signatures are updated in Phase 2.
+// For Phase 1, the wrappers accept llmRouter but discard it — this
+// keeps the kernel boot path internally consistent without forcing
+// 13 simultaneous domain-level changes.
 const DOMAIN_FACTORIES = {
-    'test-generation': (eb, m, c) => createTestGenerationPlugin(eb, m, c),
-    'test-execution': (eb, m) => createTestExecutionPlugin(eb, m),
-    'coverage-analysis': (eb, m) => createCoverageAnalysisPlugin(eb, m),
-    'quality-assessment': (eb, m, c) => createQualityAssessmentPlugin(eb, m, c),
-    'defect-intelligence': (eb, m, c) => createDefectIntelligencePlugin(eb, m, c),
-    'requirements-validation': (eb, m, c) => createRequirementsValidationPlugin(eb, m, c),
-    'code-intelligence': (eb, m, c) => createCodeIntelligencePlugin(eb, m, c),
-    'security-compliance': (eb, m, c) => createSecurityCompliancePlugin(eb, m, c),
-    'contract-testing': (eb, m, c) => createContractTestingPlugin(eb, m, c),
-    'visual-accessibility': (eb, m, c) => createVisualAccessibilityPlugin(eb, m, c),
-    'chaos-resilience': (eb, m, c) => createChaosResiliencePlugin(eb, m, c),
-    'learning-optimization': (eb, m, c) => createLearningOptimizationPlugin(eb, m, c),
-    'enterprise-integration': (eb, m, c) => createEnterpriseIntegrationPlugin(eb, m, c),
-    'coordination': (eb, m, c) => createCoordinationPlugin(eb, m, c),
+    'test-generation': (eb, m, c, llmRouter) => createTestGenerationPlugin(eb, m, c, undefined, llmRouter),
+    'test-execution': (eb, m, _c, llmRouter) => createTestExecutionPlugin(eb, m, llmRouter),
+    'coverage-analysis': (eb, m, _c, llmRouter) => createCoverageAnalysisPlugin(eb, m, llmRouter),
+    'quality-assessment': (eb, m, c, llmRouter) => createQualityAssessmentPlugin(eb, m, c, undefined, llmRouter),
+    'defect-intelligence': (eb, m, c, llmRouter) => createDefectIntelligencePlugin(eb, m, c, undefined, llmRouter),
+    'requirements-validation': (eb, m, c, llmRouter) => createRequirementsValidationPlugin(eb, m, c, undefined, llmRouter),
+    'code-intelligence': (eb, m, c, llmRouter) => createCodeIntelligencePlugin(eb, m, c, undefined, llmRouter),
+    'security-compliance': (eb, m, c, llmRouter) => createSecurityCompliancePlugin(eb, m, c, undefined, llmRouter),
+    'contract-testing': (eb, m, c, llmRouter) => createContractTestingPlugin(eb, m, c, undefined, llmRouter),
+    'visual-accessibility': (eb, m, c, llmRouter) => createVisualAccessibilityPlugin(eb, m, c, undefined, llmRouter),
+    'chaos-resilience': (eb, m, c, llmRouter) => createChaosResiliencePlugin(eb, m, c, undefined, llmRouter),
+    'learning-optimization': (eb, m, c, llmRouter) => createLearningOptimizationPlugin(eb, m, c, undefined, llmRouter),
+    'enterprise-integration': (eb, m, c, _llmRouter) => createEnterpriseIntegrationPlugin(eb, m, c),
+    'coordination': (eb, m, c, _llmRouter) => createCoordinationPlugin(eb, m, c),
 };
 const DEFAULT_CONFIG = {
     maxConcurrentAgents: AGENT_CONSTANTS.MAX_CONCURRENT_AGENTS,
@@ -93,6 +98,10 @@ export class QEKernelImpl {
     // checkAndTriggerDream path so 10-second SQLite write transactions move
     // out of short-lived hook subprocesses into the long-lived kernel.
     _dreamScheduler;
+    // ADR-043: kernel singleton HybridRouter. Built during initialize() iff
+    // a provider key is in env or the project explicitly enables one.
+    _llmRouter;
+    _llmRouterBuild;
     constructor(config = {}) {
         this._config = { ...DEFAULT_CONFIG, ...config };
         this._startTime = new Date();
@@ -118,6 +127,15 @@ export class QEKernelImpl {
     get memory() {
         return this._memory;
     }
+    /**
+     * ADR-043: Get the LLM router built during initialize(). Returns
+     * undefined when llmRouter.enabled is false or no provider was
+     * available. Domain plugins receive this as their factory's 4th arg
+     * via DOMAIN_FACTORIES.
+     */
+    get llmRouter() {
+        return this._llmRouter;
+    }
     async initialize() {
         if (this._initialized) {
             return;
@@ -156,14 +174,20 @@ export class QEKernelImpl {
             // Re-create plugins with the real memory backend
             this._plugins = new DefaultPluginLoader(this._eventBus, this._memory, this._config.lazyLoading);
         }
+        // ADR-043: Build the kernel-singleton LLM router before plugin
+        // factories are registered, so the closure on the next loop can
+        // capture it. Builds iff configured/auto-detected; null otherwise.
+        await this._initializeLLMRouter(projectRoot);
         // Register domain factories for enabled domains
         for (const domain of this._config.enabledDomains) {
             const factory = DOMAIN_FACTORIES[domain];
             if (factory) {
                 // Wrap factory to match PluginLoader signature (async)
                 this._plugins.registerFactory(domain, async (eventBus, memory) => {
-                    // Create plugin synchronously, return as Promise
-                    return Promise.resolve(factory(eventBus, memory, this._coordinator));
+                    // Create plugin synchronously, return as Promise.
+                    // ADR-043: pass the kernel singleton llmRouter as 4th arg —
+                    // domain factories forward it to coordinators/services.
+                    return Promise.resolve(factory(eventBus, memory, this._coordinator, this._llmRouter));
                 });
             }
         }
@@ -199,7 +223,9 @@ export class QEKernelImpl {
                         if (typeof createPlugin !== 'function') {
                             throw new Error(`Plugin "${manifest.name}" entry point must export a default function or "createPlugin" function`);
                         }
-                        return createPlugin(eventBus, memory, this._coordinator);
+                        // ADR-043: forward llmRouter so external plugins can
+                        // opt into LLM enhancement on the same terms as built-ins.
+                        return createPlugin(eventBus, memory, this._coordinator, this._llmRouter);
                     });
                 }
             }
@@ -310,6 +336,106 @@ export class QEKernelImpl {
         }
         this._initialized = true;
     }
+    /**
+     * ADR-043: Build the kernel-singleton HybridRouter.
+     *
+     * Behavior is gated, in order:
+     *   1. AQE_LLM_ROUTER_DISABLED env var (kill-switch): if set to a truthy
+     *      value, ALWAYS skip — even when config.llmRouter.enabled === true.
+     *      This is the env-only opt-out for users who upgrade with a
+     *      provider key already in env and don't want billing surprises.
+     *   2. config.llmRouter.enabled:
+     *      'auto' (default): build iff at least one provider key is in env,
+     *                        or the project's llm-config.json enables a provider
+     *      true:             attempt to build; emit error event if no provider
+     *      false:            skip entirely (sets _llmRouter to undefined)
+     *
+     * On any error we publish a structured kernel.llm-router.init-failed
+     * event so monitoring catches misconfiguration. We also keep the
+     * console.warn for direct visibility in dev. The kernel still boots —
+     * a kernel that boots without LLMs is strictly better than a kernel
+     * that won't boot — but the failure is now observable.
+     */
+    async _initializeLLMRouter(projectRoot) {
+        // (1) Hard env kill-switch. Truthy values disable; falsy/empty pass.
+        // Same parse rule as src/mcp/tools/base.ts:isRouterKillSwitchSet
+        // so both code paths agree on what "disabled" means.
+        const killSwitch = (process.env.AQE_LLM_ROUTER_DISABLED ?? '').trim().toLowerCase();
+        if (killSwitch &&
+            killSwitch !== 'false' &&
+            killSwitch !== '0' &&
+            killSwitch !== 'no' &&
+            killSwitch !== 'off') {
+            this._llmRouter = undefined;
+            return;
+        }
+        const llmCfg = this._config.llmRouter ?? {};
+        const enabled = llmCfg.enabled ?? 'auto';
+        if (enabled === false) {
+            this._llmRouter = undefined;
+            return;
+        }
+        try {
+            const built = await createLLMRouterService({
+                projectRoot,
+                override: llmCfg.configOverride,
+                providerManager: llmCfg.providerManager,
+            });
+            if (!built) {
+                if (enabled === true) {
+                    console.warn('[QEKernel] llmRouter.enabled=true but no provider available — ' +
+                        'continuing without LLM router (domain services will skip LLM enhancement)');
+                    await this._publishLLMRouterEvent('init-no-provider', {
+                        reason: 'no provider available in env or disk config',
+                    });
+                }
+                this._llmRouter = undefined;
+                return;
+            }
+            this._llmRouterBuild = built;
+            this._llmRouter = built.router;
+            // Phase 5 wiring: register as shared singleton so MCP standalone
+            // tools see the same router instance (one cost tracker, one cache,
+            // one metric collector, one circuit breaker per provider).
+            try {
+                const { setSharedLLMRouter } = await import('../mcp/tools/base.js');
+                setSharedLLMRouter(built.router);
+            }
+            catch {
+                // MCP module not loaded — fine in CLI-only contexts.
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn('[QEKernel] LLM router init failed; continuing without LLM enhancement:', msg);
+            await this._publishLLMRouterEvent('init-failed', {
+                error: msg,
+                stack: err instanceof Error ? err.stack : undefined,
+            });
+            this._llmRouter = undefined;
+        }
+    }
+    /**
+     * ADR-043: emit a structured event on the kernel event bus when the
+     * LLM router can't be built. Observability hook for monitoring and
+     * alerting — a silent warn is not enough for production systems where
+     * "tests run without LLM analysis" is a quality regression worth
+     * paging on.
+     */
+    async _publishLLMRouterEvent(type, payload) {
+        try {
+            await this._eventBus.publish({
+                id: randomUUID(),
+                type: `kernel.llm-router.${type}`,
+                timestamp: new Date(),
+                source: 'qe-kernel',
+                payload,
+            });
+        }
+        catch {
+            // Event bus publish failures during boot must not crash the kernel.
+        }
+    }
     async dispose() {
         // ADR-094: Stop the dream scheduler first so a dream-in-progress doesn't
         // try to write to a disposed memory backend.
@@ -332,6 +458,20 @@ export class QEKernelImpl {
         await this._coordinator.dispose();
         await this._eventBus.dispose();
         await this._memory.dispose();
+        // ADR-043: clear the shared LLM router singleton if we registered
+        // one. Prevents test isolation problems where a stale router from
+        // a previous kernel boot leaks into the next.
+        if (this._llmRouter) {
+            try {
+                const { resetSharedLLMRouter } = await import('../mcp/tools/base.js');
+                resetSharedLLMRouter();
+            }
+            catch {
+                // MCP module not loaded — fine.
+            }
+            this._llmRouter = undefined;
+            this._llmRouterBuild = undefined;
+        }
         this._initialized = false;
     }
     getDomainAPI(domain) {

package/dist/learning/embedder-endpoint-client.d.ts

@@ -0,0 +1,133 @@
+/**
+ * External Embedder Endpoint Client (ADR-097)
+ *
+ * OpenAI-compatible `/v1/embeddings` client over HTTP and HTTP-over-Unix-socket.
+ * When `EmbeddingConfig.endpoint` is set, AQE skips loading `@huggingface/transformers`
+ * entirely and routes feature-extraction through this client.
+ *
+ * Design choices per ADR-097 (revised after devil's-advocate audit):
+ *   - OpenAI wire format with `encoding_format: 'float'` pinned (interop with TEI /
+ *     vLLM / llama.cpp / Ollama / LocalAI / LM Studio — float pin avoids the
+ *     base64 default some servers ship).
+ *   - HTTP + HTTP-over-Unix (one protocol, two transports — no NDJSON fork).
+ *   - Hard-fail with circuit breaker on errors (no silent hash fallback).
+ *   - L2-renormalize on receive (don't trust server claims).
+ *   - Bearer auth from env only; URL userinfo stripped + warned on construct.
+ *   - Probe + identity fingerprint required before `embed()`; breaker recovery
+ *     invalidates identity so re-probe runs against a fresh endpoint.
+ *   - True TCP connect timeout via socket-level setTimeout (not req.setTimeout).
+ *   - TLS knobs (ca / cert / key / rejectUnauthorized / servername) for self-hosted.
+ */
+/**
+ * Endpoint identity fingerprint — a SHA-256 of the L2-normalized canary embedding,
+ * truncated to the first 16 hex chars. Stable for a given (model, quantization, server)
+ * tuple. Changes signal a configuration drift the operator must investigate.
+ */
+export interface EndpointIdentity {
+    /** Embedding dimension reported by the endpoint */
+    dim: number;
+    /** Stable fingerprint of the canary embedding (model + quantization signature) */
+    fingerprint: string;
+    /** Endpoint URL that produced this fingerprint (redacted — no userinfo) */
+    endpoint: string;
+}
+/** TLS configuration knobs passed through to https.Agent. */
+export interface EmbedderTlsOptions {
+    /** Trusted CA bundle (PEM) or path-loaded buffer. */
+    ca?: string | Buffer | Array<string | Buffer>;
+    /** Client cert (PEM). */
+    cert?: string | Buffer;
+    /** Client key (PEM). */
+    key?: string | Buffer;
+    /** Default true — set false ONLY for explicit dev/test workflows. */
+    rejectUnauthorized?: boolean;
+    /** SNI override (e.g. for cert-pinned hosts behind an IP). */
+    servername?: string;
+}
+export interface EmbedderEndpointClientOptions {
+    /** Endpoint URL: http(s)://host:port or unix:/path/to.sock */
+    endpoint: string;
+    /** Bearer token for Authorization header (typically from AQE_EMBEDDER_TOKEN env) */
+    token?: string;
+    /** Model identifier sent in the OpenAI request body */
+    model?: string;
+    /** Expected embedding dimension; probe fails if mismatched */
+    expectedDim?: number;
+    /** Connect timeout in ms (default 5000). True TCP connect timeout — not idle. */
+    connectTimeoutMs?: number;
+    /** Per-request timeout in ms (default 30000). Idle-after-connect. */
+    requestTimeoutMs?: number;
+    /** Circuit breaker: failures within window before tripping (default 3) */
+    failureThreshold?: number;
+    /** Circuit breaker: failure window in ms (default 60_000) */
+    failureWindowMs?: number;
+    /** TLS overrides for https transport. Ignored for http/unix. */
+    tlsOptions?: EmbedderTlsOptions;
+}
+/**
+ * Parsed endpoint — either an HTTP(S) URL or a Unix socket path.
+ */
+interface ParsedEndpoint {
+    transport: 'http' | 'https' | 'unix';
+    socketPath?: string;
+    host?: string;
+    port?: number;
+    protocol?: 'http:' | 'https:';
+    /** URL with userinfo stripped, safe for logs. */
+    safeUrl: string;
+}
+/**
+ * Strip user:password@ from a URL for safe logging.
+ * Returns the original string for non-URL inputs (unix paths).
+ */
+export declare function redactEndpoint(endpoint: string): string;
+export declare function parseEndpoint(endpoint: string): ParsedEndpoint;
+/**
+ * OpenAI-compatible embeddings client with keep-alive, circuit breaker, and identity probe.
+ */
+export declare class EmbedderEndpointClient {
+    private readonly parsed;
+    private readonly agent;
+    private readonly breaker;
+    private readonly opts;
+    private cachedIdentity;
+    /** True while a probe is in flight — prevents the embed() lazy-probe race. */
+    private probeInFlight;
+    constructor(options: EmbedderEndpointClientOptions);
+    /** Public, redacted endpoint URL for logs/metrics. */
+    getSafeEndpoint(): string;
+    /**
+     * Embed an array of texts. Returns L2-normalized vectors in input order.
+     *
+     * Gated on `probe()` — if no cached identity exists, probe is run first so the
+     * dim/identity boundary check fires on every cold path. Concurrent embed calls
+     * share a single in-flight probe.
+     *
+     * Throws on error — callers MUST NOT fall back to hash embeddings, which would
+     * poison the HNSW index with non-comparable vectors.
+     */
+    embed(texts: string[]): Promise<number[][]>;
+    /**
+     * Probe the endpoint by embedding a fixed canary. Returns identity fingerprint.
+     * Asserts dim === expectedDim. Throws loud on mismatch.
+     * Public so operators can re-probe on demand; idempotent under concurrency.
+     */
+    probe(): Promise<EndpointIdentity>;
+    private ensureProbed;
+    private doProbe;
+    getCachedIdentity(): EndpointIdentity | null;
+    getBreakerState(): {
+        open: boolean;
+        failures: number;
+        trippedAt: number | null;
+    };
+    /**
+     * Close the underlying keep-alive agent. Tests should call this in afterEach.
+     */
+    close(): void;
+    private decodeAndNormalize;
+    private postEmbeddings;
+    private request;
+}
+export {};
+//# sourceMappingURL=embedder-endpoint-client.d.ts.map