agentic-qe 3.10.0 → 3.10.2

package/dist/init/phases/07-hooks.js

@@ -172,6 +172,9 @@ export class HooksPhase extends BasePhase {
         this.installBrainCheckpoint(projectRoot, context);
         // Install statusline-v3 helper into .claude/helpers/
         this.installStatusline(projectRoot, context);
+        // Install the resilient hook shim into .claude/hooks/ — the generated
+        // settings.json hooks invoke it (`node .../aqe-hook.cjs <cmd>`).
+        this.installHookShim(projectRoot, context);
         // Install cross-phase memory config
         const crossPhasePath = join(hooksDir, 'cross-phase-memory.yaml');
         if (!existsSync(crossPhasePath)) {
@@ -290,40 +293,73 @@ export class HooksPhase extends BasePhase {
             context.services.log('  Installed statusline-v3.cjs (generated)');
         }
     }
+    /**
+     * Install the resilient hook shim (aqe-hook.cjs) into .claude/hooks/.
+     * The generated settings.json hooks run `node .../aqe-hook.cjs <cmd>` — the
+     * shim resolves a project-local AQE bundle (or falls back to npx), strips
+     * init noise from stdout, swallows stderr, and always exits 0.
+     */
+    installHookShim(projectRoot, context) {
+        const destDir = join(projectRoot, '.claude', 'hooks');
+        if (!existsSync(destDir)) {
+            mkdirSync(destDir, { recursive: true });
+        }
+        const destPath = join(destDir, 'aqe-hook.cjs');
+        // Source candidates: the installed dependency, then this package's own copy
+        // (resolved relative to the compiled init module — works for npx too).
+        const sourcePaths = [
+            join(projectRoot, 'node_modules', 'agentic-qe', '.claude', 'hooks', 'aqe-hook.cjs'),
+            join(__dirname, '..', '..', '..', '.claude', 'hooks', 'aqe-hook.cjs'),
+        ];
+        for (const src of sourcePaths) {
+            if (existsSync(src) && src !== destPath) {
+                const { copyFileSync } = require('fs');
+                copyFileSync(src, destPath);
+                context.services.log('  Installed aqe-hook.cjs (copied)');
+                return;
+            }
+        }
+        if (existsSync(destPath)) {
+            // Already present (e.g. dogfooding this repo) — leave it.
+            return;
+        }
+        // Should not happen for a real install (the file ships in the package).
+        context.services.log('  ⚠ aqe-hook.cjs source not found — hooks will fall back to `npx agentic-qe`');
+    }
     /**
      * Generate a minimal statusline-v3.cjs script as a fallback.
      * Used when the full asset isn't available for copying.
      */
     generateMinimalStatuslineScript() {
-        return `#!/usr/bin/env node
-/**
- * Agentic QE v3 Statusline (minimal fallback, generated by aqe init)
- * For the full statusline, reinstall: npx agentic-qe init --auto
- */
-const fs = require('fs');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-function q(bin, args, d) { try { return execFileSync(bin, args, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim(); } catch { return d || ''; } }
-
-const dir = path.resolve(__dirname, '..', '..');
-const dbPath = path.join(dir, '.agentic-qe', 'memory.db');
-let patterns = 0;
-try {
-  if (fs.existsSync(dbPath)) {
-    const Database = require('better-sqlite3');
-    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
-    db.pragma('busy_timeout = 5000');
-    patterns = db.prepare("SELECT COUNT(*) AS c FROM qe_patterns WHERE usage_count > 0 OR quality_score > 0 OR name NOT LIKE 'bench-%'").get()?.c || 0;
-    db.close();
-  }
-} catch { /* ignore */ }
-
-const branch = q('git', ['branch', '--show-current']);
-const branchStr = branch ? \`  \\x1b[34m⎇ \${branch}\\x1b[0m\` : '';
-const patStr = patterns > 0 ? \`  \\x1b[35m🎓 \${patterns} patterns\\x1b[0m\` : '';
-
-console.log(\`\\x1b[1m\\x1b[35m▊ Agentic QE v3\\x1b[0m\${branchStr}\${patStr}\`);
+        return `#!/usr/bin/env node
+/**
+ * Agentic QE v3 Statusline (minimal fallback, generated by aqe init)
+ * For the full statusline, reinstall: npx agentic-qe init --auto
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function q(bin, args, d) { try { return execFileSync(bin, args, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim(); } catch { return d || ''; } }
+
+const dir = path.resolve(__dirname, '..', '..');
+const dbPath = path.join(dir, '.agentic-qe', 'memory.db');
+let patterns = 0;
+try {
+  if (fs.existsSync(dbPath)) {
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    db.pragma('busy_timeout = 5000');
+    patterns = db.prepare("SELECT COUNT(*) AS c FROM qe_patterns WHERE usage_count > 0 OR quality_score > 0 OR name NOT LIKE 'bench-%'").get()?.c || 0;
+    db.close();
+  }
+} catch { /* ignore */ }
+
+const branch = q('git', ['branch', '--show-current']);
+const branchStr = branch ? \`  \\x1b[34m⎇ \${branch}\\x1b[0m\` : '';
+const patStr = patterns > 0 ? \`  \\x1b[35m🎓 \${patterns} patterns\\x1b[0m\` : '';
+
+console.log(\`\\x1b[1m\\x1b[35m▊ Agentic QE v3\\x1b[0m\${branchStr}\${patStr}\`);
 `;
     }
     /**
@@ -331,62 +367,62 @@ console.log(\`\\x1b[1m\\x1b[35m▊ Agentic QE v3\\x1b[0m\${branchStr}\${patStr}\
      * Used when the source file isn't available for copying.
      */
     generateBrainCheckpointScript() {
-        return `#!/usr/bin/env node
-/**
- * Brain Checkpoint Helper (generated by aqe init)
- *
- * Usage:
- *   node brain-checkpoint.cjs export   # Export brain to aqe.rvf (session-end)
- *   node brain-checkpoint.cjs verify   # Verify aqe.rvf exists (session-start)
- */
-const { execFileSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
-const AQE_DIR = path.join(PROJECT_ROOT, '.agentic-qe');
-const RVF_PATH = path.join(AQE_DIR, 'aqe.rvf');
-const DB_PATH = path.join(AQE_DIR, 'memory.db');
-const MAX_AGE_HOURS = 24;
-
-function log(msg) { process.stderr.write('[brain-checkpoint] ' + msg + '\\n'); }
-
-function exportBrain() {
-  if (!fs.existsSync(DB_PATH)) { log('No memory.db, skipping'); return { exported: false }; }
-  try {
-    if (fs.existsSync(RVF_PATH)) fs.unlinkSync(RVF_PATH);
-    const idmap = RVF_PATH + '.idmap.json';
-    if (fs.existsSync(idmap)) fs.unlinkSync(idmap);
-    const result = execFileSync(
-      'npx', ['agentic-qe', 'brain', 'export', '-o', RVF_PATH, '--format', 'rvf'],
-      { timeout: 60000, encoding: 'utf-8' }
-    );
-    const m = result.match(/Patterns:\\s+(\\d+)/);
-    const p = m ? m[1] : '0';
-    log('Exported ' + p + ' patterns to aqe.rvf');
-    return { exported: true, patterns: parseInt(p) };
-  } catch (e) {
-    log('Export failed: ' + e.message);
-    return { exported: false, reason: e.message };
-  }
-}
-
-function verifyBrain() {
-  if (!fs.existsSync(RVF_PATH)) {
-    log('No aqe.rvf found');
-    return { valid: false, reason: 'missing' };
-  }
-  const stat = fs.statSync(RVF_PATH);
-  const ageH = (Date.now() - stat.mtimeMs) / 3600000;
-  if (stat.size < 1024) { log('aqe.rvf too small'); return { valid: false, reason: 'too-small' }; }
-  if (ageH > MAX_AGE_HOURS) { log('aqe.rvf is ' + ageH.toFixed(1) + 'h old'); return { valid: true, stale: true }; }
-  log('aqe.rvf OK (' + (stat.size/1048576).toFixed(1) + ' MB)');
-  return { valid: true, stale: false };
-}
-
-const cmd = process.argv[2] || 'verify';
-const result = cmd === 'export' ? exportBrain() : verifyBrain();
-if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result));
+        return `#!/usr/bin/env node
+/**
+ * Brain Checkpoint Helper (generated by aqe init)
+ *
+ * Usage:
+ *   node brain-checkpoint.cjs export   # Export brain to aqe.rvf (session-end)
+ *   node brain-checkpoint.cjs verify   # Verify aqe.rvf exists (session-start)
+ */
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+const AQE_DIR = path.join(PROJECT_ROOT, '.agentic-qe');
+const RVF_PATH = path.join(AQE_DIR, 'aqe.rvf');
+const DB_PATH = path.join(AQE_DIR, 'memory.db');
+const MAX_AGE_HOURS = 24;
+
+function log(msg) { process.stderr.write('[brain-checkpoint] ' + msg + '\\n'); }
+
+function exportBrain() {
+  if (!fs.existsSync(DB_PATH)) { log('No memory.db, skipping'); return { exported: false }; }
+  try {
+    if (fs.existsSync(RVF_PATH)) fs.unlinkSync(RVF_PATH);
+    const idmap = RVF_PATH + '.idmap.json';
+    if (fs.existsSync(idmap)) fs.unlinkSync(idmap);
+    const result = execFileSync(
+      'npx', ['agentic-qe', 'brain', 'export', '-o', RVF_PATH, '--format', 'rvf'],
+      { timeout: 60000, encoding: 'utf-8' }
+    );
+    const m = result.match(/Patterns:\\s+(\\d+)/);
+    const p = m ? m[1] : '0';
+    log('Exported ' + p + ' patterns to aqe.rvf');
+    return { exported: true, patterns: parseInt(p) };
+  } catch (e) {
+    log('Export failed: ' + e.message);
+    return { exported: false, reason: e.message };
+  }
+}
+
+function verifyBrain() {
+  if (!fs.existsSync(RVF_PATH)) {
+    log('No aqe.rvf found');
+    return { valid: false, reason: 'missing' };
+  }
+  const stat = fs.statSync(RVF_PATH);
+  const ageH = (Date.now() - stat.mtimeMs) / 3600000;
+  if (stat.size < 1024) { log('aqe.rvf too small'); return { valid: false, reason: 'too-small' }; }
+  if (ageH > MAX_AGE_HOURS) { log('aqe.rvf is ' + ageH.toFixed(1) + 'h old'); return { valid: true, stale: true }; }
+  log('aqe.rvf OK (' + (stat.size/1048576).toFixed(1) + ' MB)');
+  return { valid: true, stale: false };
+}
+
+const cmd = process.argv[2] || 'verify';
+const result = cmd === 'export' ? exportBrain() : verifyBrain();
+if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result));
 `;
     }
     /**
@@ -410,7 +446,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks guard --file "$TOOL_INPUT_file_path" --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" guard --file "$TOOL_INPUT_file_path" --json',
                             timeout: 3000,
                             continueOnError: true,
                         },
@@ -422,7 +458,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks pre-edit --file "$TOOL_INPUT_file_path" --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" pre-edit --file "$TOOL_INPUT_file_path" --json',
                             timeout: 5000,
                             continueOnError: true,
                         },
@@ -434,7 +470,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks pre-command --command "$TOOL_INPUT_command" --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" pre-command --command "$TOOL_INPUT_command" --json',
                             timeout: 3000,
                             continueOnError: true,
                         },
@@ -446,7 +482,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks pre-task --description "$TOOL_INPUT_prompt" --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" pre-task --description "$TOOL_INPUT_prompt" --json',
                             timeout: 5000,
                             continueOnError: true,
                         },
@@ -459,7 +495,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks post-edit --file "$TOOL_INPUT_file_path" --success --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-edit --file "$TOOL_INPUT_file_path" --success --json',
                             timeout: 5000,
                             continueOnError: true,
                         },
@@ -470,7 +506,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks post-command --command "$TOOL_INPUT_command" --success --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-command --command "$TOOL_INPUT_command" --success true --json',
                             timeout: 5000,
                             continueOnError: true,
                         },
@@ -481,7 +517,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks post-task --task-id "$TOOL_RESULT_agent_id" --success --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-task --task-id "$TOOL_RESULT_agent_id" --agent "$TOOL_INPUT_subagent_type" --success true --description "$TOOL_INPUT_prompt" --json',
                             timeout: 5000,
                             continueOnError: true,
                         },
@@ -496,7 +532,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                             // (e.g. {"prompt":"..."}). $PROMPT is NOT exposed as an env
                             // var, so we let the CLI read stdin directly.
                             type: 'command',
-                            command: 'npx agentic-qe hooks route --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" route --json',
                             timeout: 5000,
                             continueOnError: true,
                         },
@@ -508,7 +544,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks session-start --session-id "$SESSION_ID" --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" session-start --session-id "$SESSION_ID" --json',
                             timeout: 10000,
                             continueOnError: true,
                         },
@@ -530,7 +566,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                     hooks: [
                         {
                             type: 'command',
-                            command: 'npx agentic-qe hooks session-end --save-state --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" session-end --save-state --json',
                             timeout: 5000,
                             continueOnError: true,
                         },
@@ -544,7 +580,7 @@ if (process.argv.includes('--json')) process.stdout.write(JSON.stringify(result)
                             // — without this, `routing_outcomes` accumulates quality_score=-1
                             // rows forever in direct-work sessions (no Task/Agent spawned).
                             type: 'command',
-                            command: 'npx agentic-qe hooks post-route --success true --json',
+                            command: 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/aqe-hook.cjs" post-route --success true --json',
                             timeout: 5000,
                             continueOnError: true,
                         },

package/dist/kernel/interfaces.d.ts

@@ -259,6 +259,17 @@ export interface QEKernel extends Initializable, Disposable {
     readonly plugins: PluginLoader;
     /** Get the memory backend */
     readonly memory: MemoryBackend;
+    /**
+     * Get the LLM router (ADR-043). Returns undefined when no provider
+     * keys are present in env and the project has no router config — the
+     * kernel boots fine without a router; the LLM-enhancement branches
+     * in domain services simply stay dark.
+     *
+     * Type intentionally returned as `unknown` here to avoid a hard
+     * dependency from kernel/interfaces.ts on shared/llm/router/. Callers
+     * who need the typed HybridRouter import it directly.
+     */
+    readonly llmRouter?: unknown;
     /** Get a domain's API (synchronous, returns undefined if not loaded) */
     getDomainAPI<T>(domain: DomainName): T | undefined;
     /** Get a domain's API with lazy loading support */
@@ -324,6 +335,32 @@ export interface KernelConfig {
      * DreamEngine init cost.
      */
     enableDreamScheduler?: boolean;
+    /**
+     * LLM router configuration (ADR-043). Controls whether the kernel
+     * boots a HybridRouter and injects it into domain plugins so the
+     * isLLMAnalysisAvailable() branches in 14 services actually fire.
+     *
+     * - `enabled: 'auto'` (default): build a router iff at least one
+     *   provider API key is present in env, OR the project's
+     *   .agentic-qe/llm-config.json explicitly enables a provider.
+     * - `enabled: true`: always try to build a router; if no provider is
+     *   available, log a warning and continue without one.
+     * - `enabled: false`: skip the router entirely. Use this to revert to
+     *   the pre-wiring behavior (deterministic-only scanners).
+     *
+     * `configOverride` is merged on top of the disk + env config (highest
+     * precedence) — useful for tests.
+     */
+    llmRouter?: {
+        enabled?: 'auto' | true | false;
+        configOverride?: Partial<import('../shared/llm/router/types').RouterConfig>;
+        /**
+         * Inject a pre-built ProviderManager (for tests). When supplied,
+         * config-store loading is skipped and the provided manager is used
+         * directly. Typed as unknown to avoid the dependency.
+         */
+        providerManager?: unknown;
+    };
 }
 /**
  * Event middleware interface for anti-drift and other event processing (ADR-060)

package/dist/kernel/kernel.d.ts

@@ -6,6 +6,7 @@ import { DomainName } from '../shared/types';
 import { QEKernel, EventBus, AgentCoordinator, PluginLoader, MemoryBackend, KernelHealth, KernelConfig } from './interfaces';
 import { ToolCallSignatureTracker } from './anti-drift-middleware.js';
 import type { LoopDetectionResult } from './anti-drift-middleware.js';
+import type { HybridRouter } from '../shared/llm/router/hybrid-router.js';
 import '../domains/test-generation';
 import '../domains/coverage-analysis';
 import '../domains/security-compliance';
@@ -22,12 +23,50 @@ export declare class QEKernelImpl implements QEKernel {
     private _loopTracker;
     private _experienceBridge?;
     private _dreamScheduler?;
+    private _llmRouter?;
+    private _llmRouterBuild?;
     constructor(config?: Partial<KernelConfig>);
     get eventBus(): EventBus;
     get coordinator(): AgentCoordinator;
     get plugins(): PluginLoader;
     get memory(): MemoryBackend;
+    /**
+     * 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(): HybridRouter | undefined;
     initialize(): Promise<void>;
+    /**
+     * 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.
+     */
+    private _initializeLLMRouter;
+    /**
+     * 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.
+     */
+    private _publishLLMRouterEvent;
     dispose(): Promise<void>;
     getDomainAPI<T>(domain: DomainName): T | undefined;
     /**