agentic-qe 3.14.7 → 3.15.0

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

@@ -235,27 +235,30 @@ export class FileReader {
     resolvePath(filePath) {
         // Determine if path is absolute
         const isAbsolutePath = path.isAbsolute(filePath);
+        const normalizedBase = path.resolve(this.basePath);
+        const normalizedPath = path.resolve(normalizedBase, filePath);
+        const relativePath = path.relative(normalizedBase, normalizedPath);
+        if (this.basePath && (relativePath === '..' || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath))) {
+            throw new PathTraversalError(filePath, ['Path escapes base directory'], 'critical');
+        }
+        // Absolute checkout prefixes are not user-controlled depth beneath the root.
+        // Keep validating the original spelling so encoded traversal remains blocked.
+        const baseDepth = this.basePath ? normalizedBase.split(/[\\/]/).filter(Boolean).length : 0;
         // SEC-004 FIX: Validate path to prevent directory traversal
         // For absolute paths, validate without basePath to avoid incorrect combination
         // For relative paths, validate with basePath for proper containment check
         const validation = validatePath(filePath, {
             basePath: isAbsolutePath ? '' : this.basePath,
             allowAbsolute: true,
+            maxDepth: 10 + (isAbsolutePath ? baseDepth : 0),
             // Allow common development file extensions
             deniedExtensions: ['.exe', '.bat', '.cmd', '.ps1', '.dll', '.so'],
         });
         if (!validation.valid) {
             throw new PathTraversalError(filePath, [validation.error || 'Path validation failed'], validation.riskLevel);
         }
-        // For absolute paths, verify they stay within basePath if one is configured
-        if (isAbsolutePath && this.basePath) {
-            const normalizedBase = path.resolve(this.basePath);
-            const normalizedPath = path.resolve(filePath);
-            if (!normalizedPath.startsWith(normalizedBase)) {
-                throw new PathTraversalError(filePath, ['Path escapes base directory'], 'critical');
-            }
+        if (isAbsolutePath)
             return normalizedPath;
-        }
         // Use the normalized path from validation if available
         if (validation.normalizedPath) {
             return validation.normalizedPath;

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

@@ -5,7 +5,7 @@
  * Provides efficient caching of LLM responses to reduce costs and latency
  * for repeated queries. Uses LRU (Least Recently Used) eviction policy.
  */
-import { CacheEntry, LLMCacheConfig, LLMCacheStats, LLMResponse, EmbeddingResponse, CompletionResponse } from './interfaces';
+import { CacheEntry, LLMCacheConfig, LLMCacheStats, LLMResponse, EmbeddingResponse, CompletionResponse, type GenerateOptions } from './interfaces';
 /**
  * Default cache configuration
  */
@@ -14,6 +14,7 @@ export declare const DEFAULT_CACHE_CONFIG: LLMCacheConfig;
  * Type for cacheable response types
  */
 export type CacheableResponse = LLMResponse | EmbeddingResponse | CompletionResponse;
+type CacheKeyOptions = Pick<GenerateOptions, 'model' | 'temperature' | 'maxTokens' | 'systemPrompt' | 'stopSequences' | 'effort' | 'preferredProvider'>;
 /**
  * LRU Cache implementation for LLM responses
  */
@@ -28,12 +29,7 @@ export declare class LLMCache<T = CacheableResponse> {
     /**
      * Generate a cache key from request parameters
      */
-    static generateKey(type: 'generation' | 'embedding' | 'completion', input: string, options?: {
-        model?: string;
-        temperature?: number;
-        maxTokens?: number;
-        systemPrompt?: string;
-    }): string;
+    static generateKey(type: 'generation' | 'embedding' | 'completion', input: string, options?: CacheKeyOptions): string;
     /**
      * Get a cached value
      */
@@ -99,21 +95,11 @@ export declare class LLMResponseCache {
     /**
      * Get a cached generation response
      */
-    getGeneration(input: string, options?: {
-        model?: string;
-        temperature?: number;
-        maxTokens?: number;
-        systemPrompt?: string;
-    }): LLMResponse | undefined;
+    getGeneration(input: string, options?: CacheKeyOptions): LLMResponse | undefined;
     /**
      * Cache a generation response
      */
-    setGeneration(input: string, response: LLMResponse, options?: {
-        model?: string;
-        temperature?: number;
-        maxTokens?: number;
-        systemPrompt?: string;
-    }, ttlMs?: number): void;
+    setGeneration(input: string, response: LLMResponse, options?: CacheKeyOptions, ttlMs?: number): void;
     /**
      * Get a cached embedding response
      */
@@ -129,19 +115,11 @@ export declare class LLMResponseCache {
     /**
      * Get a cached completion response
      */
-    getCompletion(prompt: string, options?: {
-        model?: string;
-        temperature?: number;
-        maxTokens?: number;
-    }): CompletionResponse | undefined;
+    getCompletion(prompt: string, options?: CacheKeyOptions): CompletionResponse | undefined;
     /**
      * Cache a completion response
      */
-    setCompletion(prompt: string, response: CompletionResponse, options?: {
-        model?: string;
-        temperature?: number;
-        maxTokens?: number;
-    }, ttlMs?: number): void;
+    setCompletion(prompt: string, response: CompletionResponse, options?: CacheKeyOptions, ttlMs?: number): void;
     /**
      * Get combined cache statistics
      */
@@ -160,4 +138,5 @@ export declare class LLMResponseCache {
      */
     pruneExpired(): number;
 }
+export {};
 //# sourceMappingURL=cache.d.ts.map

package/dist/shared/llm/cache.js

@@ -5,6 +5,7 @@
  * Provides efficient caching of LLM responses to reduce costs and latency
  * for repeated queries. Uses LRU (Least Recently Used) eviction policy.
  */
+import { createHash } from 'node:crypto';
 /**
  * Default cache configuration
  */
@@ -41,15 +42,13 @@ export class LLMCache {
             options?.systemPrompt ?? '',
             input,
         ];
-        // Simple hash function
-        const str = parts.join('|');
-        let hash = 0;
-        for (let i = 0; i < str.length; i++) {
-            const char = str.charCodeAt(i);
-            hash = ((hash << 5) - hash) + char;
-            hash = hash & hash;
+        const outputOptions = [options?.stopSequences, options?.effort, options?.preferredProvider];
+        if (outputOptions.some(value => value !== undefined)) {
+            parts.push(JSON.stringify(outputOptions));
         }
-        return `${type}:${Math.abs(hash).toString(36)}`;
+        // Encode field boundaries before hashing: prompt text may contain delimiters.
+        const hash = createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+        return `${type}:${hash}`;
     }
     /**
      * Get a cached value
@@ -182,7 +181,9 @@ export class LLMCache {
             entry.createdAt = new Date(entry.createdAt);
             entry.lastAccessedAt = new Date(entry.lastAccessedAt);
             this.cache.set(key, entry);
-            this.accessOrder.push(key);
+            if (this.config.enableLRU) {
+                this.updateAccessOrder(key);
+            }
         }
         // Evict if over capacity
         while (this.cache.size > this.config.maxSize) {
@@ -223,14 +224,14 @@ export class LLMCache {
         if (this.accessOrder.length === 0) {
             // Fallback: delete first entry
             const firstKey = this.cache.keys().next().value;
-            if (firstKey) {
+            if (firstKey !== undefined) {
                 this.cache.delete(firstKey);
                 this.evictions++;
             }
             return;
         }
         const lruKey = this.accessOrder.shift();
-        if (lruKey) {
+        if (lruKey !== undefined) {
             this.cache.delete(lruKey);
             this.evictions++;
         }

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

@@ -244,7 +244,8 @@ export class CostTracker {
         for (const record of relevantRecords) {
             totalCost += record.cost.totalCost;
             totalTokens += record.usage.totalTokens;
-            byProvider[record.provider] += record.cost.totalCost;
+            const providerCost = Object.hasOwn(byProvider, record.provider) ? byProvider[record.provider] : 0;
+            byProvider[record.provider] = providerCost + record.cost.totalCost;
             byModel[record.model] = (byModel[record.model] || 0) + record.cost.totalCost;
         }
         return {

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

@@ -207,12 +207,7 @@ export class ProviderManager {
         // Check cache first
         if (!options?.skipCache) {
             const inputStr = typeof input === 'string' ? input : JSON.stringify(input);
-            const cached = this.cache.getGeneration(inputStr, {
-                model: options?.model,
-                temperature: options?.temperature,
-                maxTokens: options?.maxTokens,
-                systemPrompt: options?.systemPrompt,
-            });
+            const cached = this.cache.getGeneration(inputStr, options);
             if (cached) {
                 return { ...cached, cached: true };
             }
@@ -224,12 +219,7 @@ export class ProviderManager {
         // Cache the response
         if (!options?.skipCache) {
             const inputStr = typeof input === 'string' ? input : JSON.stringify(input);
-            this.cache.setGeneration(inputStr, response, {
-                model: options?.model,
-                temperature: options?.temperature,
-                maxTokens: options?.maxTokens,
-                systemPrompt: options?.systemPrompt,
-            });
+            this.cache.setGeneration(inputStr, response, options);
         }
         // Track cost (in-process) and persist to the cross-process ledger.
         this.costTracker.recordUsage(response.provider, response.model, response.usage, response.requestId);
@@ -265,11 +255,7 @@ export class ProviderManager {
         await this.ensureInitialized();
         // Check cache first
         if (!options?.skipCache) {
-            const cached = this.cache.getCompletion(prompt, {
-                model: options?.model,
-                temperature: options?.temperature,
-                maxTokens: options?.maxTokens,
-            });
+            const cached = this.cache.getCompletion(prompt, options);
             if (cached) {
                 return { ...cached, cached: true };
             }
@@ -279,11 +265,7 @@ export class ProviderManager {
         const response = await this.executeWithFailover('complete', async (provider) => provider.complete(prompt, options));
         // Cache the response
         if (!options?.skipCache) {
-            this.cache.setCompletion(prompt, response, {
-                model: options?.model,
-                temperature: options?.temperature,
-                maxTokens: options?.maxTokens,
-            });
+            this.cache.setCompletion(prompt, response, options);
         }
         // ADR-123: persist to the cross-process ledger (completion has usage too).
         this.costTracker.recordUsage(response.provider, response.model, response.usage, `complete-${response.model}-${Date.now()}`);

package/dist/shared/llm/providers/gemini.d.ts

@@ -100,6 +100,7 @@ export declare class GeminiProvider implements LLMProvider {
      * Format input to Gemini contents format
      */
     private formatContents;
+    private isPromptBlocked;
     /**
      * Map Gemini finish reason to standard format
      */

package/dist/shared/llm/providers/gemini.js

@@ -191,7 +191,10 @@ export class GeminiProvider {
                 totalTokens: usage.totalTokens,
                 estimatedCostUsd: cost.totalCost,
             });
-            const content = data.candidates[0]?.content?.parts
+            // A blocked prompt has no candidates; preserve it as a terminal result.
+            const blocked = this.isPromptBlocked(data.promptFeedback);
+            const candidate = blocked ? undefined : data.candidates[0];
+            const content = candidate?.content?.parts
                 ?.map(p => p.text ?? '')
                 .join('') ?? '';
             return {
@@ -201,7 +204,7 @@ export class GeminiProvider {
                 usage,
                 cost,
                 latencyMs,
-                finishReason: this.mapFinishReason(data.candidates[0]?.finishReason),
+                finishReason: blocked ? 'content_filter' : this.mapFinishReason(candidate?.finishReason),
                 cached: false,
                 requestId,
             };
@@ -269,10 +272,10 @@ export class GeminiProvider {
                 buffer = lines.pop() || '';
                 for (const line of lines) {
                     const trimmed = line.trim();
-                    if (!trimmed || !trimmed.startsWith('data: '))
+                    if (!trimmed || !trimmed.startsWith('data:'))
                         continue;
                     try {
-                        const chunk = safeJsonParse(trimmed.slice(6));
+                        const chunk = safeJsonParse(trimmed.slice(5).trimStart());
                         const text = chunk.candidates?.[0]?.content?.parts
                             ?.map(p => p.text ?? '')
                             .join('') ?? '';
@@ -280,7 +283,10 @@ export class GeminiProvider {
                             fullContent += text;
                             yield text;
                         }
-                        if (chunk.candidates?.[0]?.finishReason) {
+                        if (this.isPromptBlocked(chunk.promptFeedback)) {
+                            finishReason = 'content_filter';
+                        }
+                        else if (chunk.candidates?.[0]?.finishReason) {
                             finishReason = this.mapFinishReason(chunk.candidates[0].finishReason);
                         }
                         if (chunk.usageMetadata) {
@@ -479,6 +485,9 @@ export class GeminiProvider {
             parts: [{ text: m.content }],
         }));
     }
+    isPromptBlocked(feedback) {
+        return !!feedback?.blockReason && feedback.blockReason !== 'BLOCK_REASON_UNSPECIFIED';
+    }
     /**
      * Map Gemini finish reason to standard format
      */

package/dist/shared/llm/providers/openrouter.js

@@ -299,11 +299,14 @@ export class OpenRouterProvider {
                 buffer = lines.pop() || '';
                 for (const line of lines) {
                     const trimmed = line.trim();
-                    if (!trimmed || trimmed === 'data: [DONE]')
+                    if (!trimmed || !trimmed.startsWith('data:'))
                         continue;
-                    if (trimmed.startsWith('data: ')) {
+                    const data = trimmed.slice(5).trimStart();
+                    if (data === '[DONE]')
+                        continue;
+                    if (trimmed.startsWith('data:')) {
                         try {
-                            const chunk = safeJsonParse(trimmed.slice(6));
+                            const chunk = safeJsonParse(data);
                             const delta = chunk.choices[0]?.delta;
                             if (delta?.content) {
                                 fullContent += delta.content;

package/dist/shared/metrics/code-metrics.js

@@ -228,7 +228,7 @@ export class CodeMetricsAnalyzer {
         // Count decision points
         const decisionPatterns = [
             /\bif\s*\(/g,
-            /\belse\s+if\s*\(/g,
+            // The if pattern already counts else-if decisions.
             /\bfor\s*\(/g,
             /\bwhile\s*\(/g,
             /\bcase\s+/g,

package/dist/shared/metrics/system-metrics.js

@@ -76,7 +76,13 @@ export class SystemMetricsCollector {
      */
     collectProcessMetrics() {
         const memUsage = process.memoryUsage();
-        const cpuUsage = process.cpuUsage(this.lastCpuUsage ?? undefined);
+        const currentCpuUsage = process.cpuUsage();
+        const cpuUsage = this.lastCpuUsage
+            ? {
+                user: currentCpuUsage.user - this.lastCpuUsage.user,
+                system: currentCpuUsage.system - this.lastCpuUsage.system,
+            }
+            : currentCpuUsage;
         // Calculate CPU percentage
         const now = Date.now();
         const elapsedMs = this.lastCpuTime > 0 ? now - this.lastCpuTime : 1000;
@@ -85,7 +91,7 @@ export class SystemMetricsCollector {
         const totalCpuUs = cpuUsage.user + cpuUsage.system;
         const cpuPercent = (totalCpuUs / elapsedUs) * 100;
         // Update last values
-        this.lastCpuUsage = cpuUsage;
+        this.lastCpuUsage = currentCpuUsage;
         this.lastCpuTime = now;
         // Calculate memory percentage
         const totalMem = os.totalmem();

package/dist/shared/retry-engine.js

@@ -1,14 +1,4 @@
-/**
- * Agentic QE v3 - Unified Retry Engine
- * IMP-03: Retry Engine with Exponential Backoff
- *
- * Provides a single, well-tested retry loop with exponential backoff,
- * jitter, abort signal support, and retryable-error classification.
- *
- * The circuit breaker (circuit-breaker.ts) is a separate concern that
- * receives success/failure signals from callers — this engine does NOT
- * import or depend on it. Integration is planned for a later phase.
- */
+import { isCallerInputError } from './error-utils.js';
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -59,7 +49,7 @@ const NON_RETRYABLE_HTTP_STATUSES = new Set([400, 401, 403, 404, 422]);
  * Returns `false` for recognised non-retryable client errors (4xx).
  */
 export function isRetryableError(error) {
-    if (error == null)
+    if (error == null || isCallerInputError(error))
         return false;
     // --- code property (errno) -------------------------------------------
     const code = error.code;
@@ -142,6 +132,10 @@ function delay(ms, signal) {
  * promise rejects with an `AbortError`.
  */
 export async function withRetry(fn, options) {
+    // Disabling retries must not bypass the caller's cancellation boundary.
+    if (options?.abortSignal?.aborted) {
+        throw options.abortSignal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+    }
     // Kill switch: bypass retry entirely when disabled
     if (process.env.AQE_RETRY_DISABLED === 'true') {
         const result = await fn();

package/dist/shared/test-runner-process.d.ts

@@ -0,0 +1,10 @@
+import { type ChildProcess } from 'node:child_process';
+/** Keep detached runners subject to the CLI's synchronous exit handling. */
+export declare function trackTestRunnerExit(proc: ChildProcess): () => void;
+/**
+ * Stop a test runner spawned in its own POSIX process group. The returned
+ * promise waits for the group to stop before report files may be removed.
+ * Windows uses taskkill's tree operation while the root PID still exists.
+ */
+export declare function terminateTestRunner(proc: ChildProcess): Promise<void>;
+//# sourceMappingURL=test-runner-process.d.ts.map

package/dist/shared/test-runner-process.js

@@ -0,0 +1,210 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { readdirSync, readFileSync } from 'node:fs';
+/** Linux signal 0 also sees zombies, which can never execute or write files. */
+function hasLiveLinuxGroupMember(group) {
+    for (const pid of readdirSync('/proc')) {
+        if (!/^\d+$/.test(pid))
+            continue;
+        let stat;
+        try {
+            stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        }
+        catch (error) {
+            if (['ENOENT', 'ESRCH'].includes(error.code ?? ''))
+                continue;
+            throw error; // Unknown process state must not be claimed as stopped.
+        }
+        // The comm field can contain spaces and parentheses; its final ')' is the
+        // boundary before state, ppid and pgrp, not the first whitespace token.
+        const fields = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+        if (fields.length < 3 || !/^\d+$/.test(fields[2]))
+            throw new Error(`Invalid process stat for ${pid}`);
+        if (Number(fields[2]) === group && fields[0] !== 'Z' && fields[0] !== 'X')
+            return true;
+    }
+    return false;
+}
+/** Signal probes on Darwin may deny access while dead group members are reaped. */
+function hasLiveDarwinGroupMember(group) {
+    const snapshot = execFileSync('ps', ['-axo', 'pgid=,stat='], {
+        encoding: 'utf8', timeout: 1000, maxBuffer: 1024 * 1024,
+    });
+    for (const line of snapshot.split('\n')) {
+        if (!line.trim())
+            continue;
+        const match = /^\s*(\d+)\s+([A-Z?])\S*\s*$/.exec(line);
+        if (!match)
+            throw new Error('Could not determine Darwin process group state');
+        if (Number(match[1]) === group && match[2] !== 'Z')
+            return true;
+    }
+    return false;
+}
+const activeGroups = new Set();
+const stopGroupsOnExit = () => {
+    for (const pid of activeGroups) {
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch { /* Already exited. */ }
+    }
+};
+/** Keep detached runners subject to the CLI's synchronous exit handling. */
+export function trackTestRunnerExit(proc) {
+    const pid = proc.pid;
+    if (process.platform === 'win32' || pid === undefined)
+        return () => { };
+    if (activeGroups.size === 0)
+        process.once('exit', stopGroupsOnExit);
+    activeGroups.add(pid);
+    return () => {
+        activeGroups.delete(pid);
+        if (activeGroups.size === 0)
+            process.off('exit', stopGroupsOnExit);
+    };
+}
+/**
+ * Stop a test runner spawned in its own POSIX process group. The returned
+ * promise waits for the group to stop before report files may be removed.
+ * Windows uses taskkill's tree operation while the root PID still exists.
+ */
+export function terminateTestRunner(proc) {
+    return new Promise((resolve, reject) => {
+        const platform = process.platform;
+        const linux = platform === 'linux';
+        const grouped = process.platform !== 'win32' && proc.pid !== undefined;
+        const windowsTree = process.platform === 'win32' && proc.pid !== undefined;
+        let timer;
+        let finished = false;
+        let forceSent = false;
+        let closed = false;
+        let treeStopped = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            proc.off('close', onClose);
+            resolve();
+        };
+        const fail = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            proc.off('close', onClose);
+            reject(error);
+        };
+        const groupExists = () => {
+            try {
+                process.kill(-proc.pid, 0);
+                return forceSent && linux ? hasLiveLinuxGroupMember(proc.pid) : true;
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    return false;
+                // A delivered group signal is not proof every member died. Inspect
+                // actual states; failures/malformed snapshots remain unknown and reject.
+                if (platform === 'darwin' && error.code === 'EPERM') {
+                    return hasLiveDarwinGroupMember(proc.pid);
+                }
+                if (forceSent && linux && error.code === 'EPERM') {
+                    return hasLiveLinuxGroupMember(proc.pid);
+                }
+                throw error;
+            }
+        };
+        const signalGroup = (signal) => {
+            try {
+                process.kill(-proc.pid, signal);
+                return true;
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    return false;
+                throw error;
+            }
+        };
+        const onClose = () => {
+            closed = true;
+            try {
+                if (windowsTree) {
+                    if (treeStopped)
+                        finish();
+                    return;
+                }
+                // A root can exit before a TERM-resistant descendant. Keep escalation
+                // active while its owned group exists, even when stdio has closed.
+                if (!grouped || !groupExists())
+                    finish();
+            }
+            catch (error) {
+                fail(error);
+            }
+        };
+        proc.once('close', onClose);
+        try {
+            if (grouped) {
+                if (!signalGroup('SIGTERM')) {
+                    finish();
+                    return;
+                }
+                timer = setTimeout(() => {
+                    try {
+                        if (!signalGroup('SIGKILL')) {
+                            finish();
+                            return;
+                        }
+                        forceSent = true;
+                        const deadline = Date.now() + 1000;
+                        const poll = () => {
+                            try {
+                                // Do not discard report files while group exit is unknown.
+                                if (!groupExists())
+                                    finish();
+                                else if (Date.now() >= deadline)
+                                    fail(new Error(`Test runner group ${proc.pid} survived SIGKILL.`));
+                                else
+                                    timer = setTimeout(poll, 20);
+                            }
+                            catch (error) {
+                                fail(error);
+                            }
+                        };
+                        poll();
+                    }
+                    catch (error) {
+                        fail(error);
+                    }
+                }, 1000);
+            }
+            else if (windowsTree) {
+                const killer = spawn('taskkill', ['/PID', String(proc.pid), '/T', '/F'], {
+                    stdio: 'ignore', windowsHide: true, timeout: 2000,
+                });
+                killer.once('error', fail);
+                killer.once('close', code => {
+                    if (code !== 0) {
+                        fail(new Error(`Test runner tree termination failed (taskkill exit ${code}).`));
+                    }
+                    else {
+                        treeStopped = true;
+                        if (closed)
+                            finish();
+                    }
+                });
+            }
+            else {
+                // No PID is available before spawn failure (and in test doubles).
+                proc.kill('SIGTERM');
+                if (finished)
+                    return;
+                timer = setTimeout(() => { proc.kill('SIGKILL'); }, 1000);
+            }
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}
+//# sourceMappingURL=test-runner-process.js.map