agentic-qe 3.14.5 → 3.14.7

package/dist/coordination/services/task-audit-logger.d.ts

@@ -21,6 +21,34 @@ export interface TaskAuditEntry {
     readonly domain?: DomainName;
     readonly details?: Record<string, unknown>;
 }
+/** An entry produced by this logger, positioned within its generation. */
+export interface TaskAuditSequencedEntry extends TaskAuditEntry {
+    readonly sequence: number;
+}
+/** Filters select retained entries; they do not change retention metadata. */
+export interface TaskAuditFilter {
+    operation?: TaskOperation;
+    taskId?: string;
+    agentId?: string;
+    domain?: DomainName;
+    fromTimestamp?: Date;
+    toTimestamp?: Date;
+    limit?: number;
+}
+/** Completeness of the bounded observation window since construction/clear. */
+export interface TaskAuditWindow {
+    generation: string;
+    recordedEntries: number;
+    retainedEntries: number;
+    droppedEntries: number;
+    firstRetainedSequence: number | null;
+    lastRetainedSequence: number | null;
+    disposition: 'complete' | 'truncated';
+}
+/** Filtered entries with metadata for the entire retained window. */
+export interface TaskAuditSnapshot extends TaskAuditWindow {
+    entries: TaskAuditSequencedEntry[];
+}
 /**
  * Configuration for task audit logger
  */
@@ -41,6 +69,9 @@ export interface TaskAuditConfig {
 export declare class TaskAuditLogger {
     private readonly entries;
     private readonly config;
+    private generation;
+    private recordedEntries;
+    private droppedEntries;
     constructor(config?: Partial<TaskAuditConfig>);
     /**
      * Log a task operation
@@ -65,19 +96,13 @@ export declare class TaskAuditLogger {
     /**
      * Get audit entries with optional filtering
      */
-    getEntries(filter?: {
-        operation?: TaskOperation;
-        taskId?: string;
-        agentId?: string;
-        domain?: DomainName;
-        fromTimestamp?: Date;
-        toTimestamp?: Date;
-        limit?: number;
-    }): TaskAuditEntry[];
-    /**
-     * Get statistics about task operations
-     */
-    getStatistics(): {
+    getEntries(filter?: TaskAuditFilter): TaskAuditSequencedEntry[];
+    /** Get selected entries without losing evidence of earlier evictions/resets. */
+    getSnapshot(filter?: TaskAuditFilter): TaskAuditSnapshot;
+    private getWindow;
+    /** Get counts for the retained window, with its completeness metadata. */
+    getStatistics(): TaskAuditWindow & {
+        basis: 'retained-window';
         totalEntries: number;
         operationCounts: Record<TaskOperation, number>;
         taskCount: number;

package/dist/coordination/services/task-audit-logger.js

@@ -5,6 +5,7 @@
  * This replaces the full authorization service with simple audit logging
  * for a local CLI tool where all agents are trusted.
  */
+import { randomUUID } from 'node:crypto';
 const DEFAULT_CONFIG = {
     enableConsoleLog: true,
     maxEntries: 1000,
@@ -19,14 +20,21 @@ const DEFAULT_CONFIG = {
 export class TaskAuditLogger {
     entries = [];
     config;
+    generation = randomUUID();
+    recordedEntries = 0;
+    droppedEntries = 0;
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
+        if (!Number.isSafeInteger(this.config.maxEntries) || this.config.maxEntries < 0) {
+            throw new RangeError('maxEntries must be a non-negative safe integer');
+        }
     }
     /**
      * Log a task operation
      */
     log(operation, taskId, options) {
         const entry = {
+            sequence: ++this.recordedEntries,
             timestamp: new Date(),
             operation,
             taskId,
@@ -37,7 +45,9 @@ export class TaskAuditLogger {
         this.entries.push(entry);
         // Trim if exceeds max
         if (this.entries.length > this.config.maxEntries) {
-            this.entries.splice(0, this.entries.length - this.config.maxEntries);
+            const dropped = this.entries.length - this.config.maxEntries;
+            this.entries.splice(0, dropped);
+            this.droppedEntries += dropped;
         }
         // Console log if enabled
         if (this.config.enableConsoleLog) {
@@ -102,11 +112,24 @@ export class TaskAuditLogger {
             }
         }
         const limit = filter?.limit ?? result.length;
-        return result.slice(-limit);
+        return limit === 0 ? [] : result.slice(-limit);
     }
-    /**
-     * Get statistics about task operations
-     */
+    /** Get selected entries without losing evidence of earlier evictions/resets. */
+    getSnapshot(filter) {
+        return { ...this.getWindow(), entries: this.getEntries(filter) };
+    }
+    getWindow() {
+        return {
+            generation: this.generation,
+            recordedEntries: this.recordedEntries,
+            retainedEntries: this.entries.length,
+            droppedEntries: this.droppedEntries,
+            firstRetainedSequence: this.entries[0]?.sequence ?? null,
+            lastRetainedSequence: this.entries[this.entries.length - 1]?.sequence ?? null,
+            disposition: this.droppedEntries > 0 ? 'truncated' : 'complete',
+        };
+    }
+    /** Get counts for the retained window, with its completeness metadata. */
     getStatistics() {
         const operationCounts = {
             submit: 0,
@@ -129,6 +152,8 @@ export class TaskAuditLogger {
             }
         }
         return {
+            ...this.getWindow(),
+            basis: 'retained-window',
             totalEntries: this.entries.length,
             operationCounts,
             taskCount: taskIds.size,
@@ -140,6 +165,9 @@ export class TaskAuditLogger {
      */
     clear() {
         this.entries.length = 0;
+        this.generation = randomUUID();
+        this.recordedEntries = 0;
+        this.droppedEntries = 0;
     }
 }
 /**

package/dist/coordination/task-executor.d.ts

@@ -154,6 +154,11 @@ export declare class DomainTaskExecutor implements TaskHandlerContext {
     private getTaskDomain;
     private timeout;
     private publishTaskCompleted;
+    /**
+     * @param callerError true when the task was rejected because of invalid
+     *   caller input; the queen then neither retries it nor counts it toward
+     *   the domain circuit breaker.
+     */
     private publishTaskFailed;
 }
 export declare function createTaskExecutor(kernel: QEKernel, config?: Partial<TaskExecutorConfig>): DomainTaskExecutor;

package/dist/coordination/task-executor.js

@@ -13,7 +13,7 @@
  * Handler implementations are extracted into ./handlers/ modules.
  */
 import { v4 as uuidv4 } from 'uuid';
-import { toErrorMessage } from '../shared/error-utils.js';
+import { isCallerInputError, toErrorMessage } from '../shared/error-utils.js';
 import { createResultSaver } from './result-saver.js';
 import { createLogger } from '../logging/logger-factory.js';
 import { getClaudeModelForTier } from '../shared/llm/model-registry.js';
@@ -436,7 +436,7 @@ export class DomainTaskExecutor {
             ]);
             if (!result.success) {
                 const errorMsg = 'error' in result ? result.error.message : 'Unknown error';
-                await this.publishTaskFailed(task.id, errorMsg, domain);
+                await this.publishTaskFailed(task.id, errorMsg, domain, 'error' in result && isCallerInputError(result.error));
                 // ADR-051: Record failed outcome
                 this.recordOutcome(task, routingTier, false, Date.now() - startTime).catch((e) => { logger.warn('recordOutcome failed', { error: e instanceof Error ? e.message : String(e), taskId: task.id }); });
                 return {
@@ -486,7 +486,7 @@ export class DomainTaskExecutor {
         }
         catch (error) {
             const errorMessage = toErrorMessage(error);
-            await this.publishTaskFailed(task.id, errorMessage, domain);
+            await this.publishTaskFailed(task.id, errorMessage, domain, isCallerInputError(error));
             // ADR-051: Record failed outcome
             this.recordOutcome(task, routingTier, false, Date.now() - startTime).catch((e) => { logger.warn('recordOutcome failed', { error: e instanceof Error ? e.message : String(e), taskId: task.id }); });
             return {
@@ -655,13 +655,18 @@ export class DomainTaskExecutor {
             payload: { taskId, result },
         });
     }
-    async publishTaskFailed(taskId, error, domain) {
+    /**
+     * @param callerError true when the task was rejected because of invalid
+     *   caller input; the queen then neither retries it nor counts it toward
+     *   the domain circuit breaker.
+     */
+    async publishTaskFailed(taskId, error, domain, callerError = false) {
         await this.eventBus.publish({
             id: uuidv4(),
             type: 'TaskFailed',
             timestamp: new Date(),
             source: domain,
-            payload: { taskId, error },
+            payload: { taskId, error, ...(callerError ? { callerError: true } : {}) },
         });
     }
 }

package/dist/domains/test-generation/coordinator.js

@@ -249,7 +249,7 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
             this.startWorkflow(workflowId, 'generate');
             // Opt-in (plan 06, D7-wire): try the FREE local model first with a repair
             // loop. Fully guarded — any miss falls through to the normal LLM path.
-            if (this.freeTierExecutor) {
+            if (this.freeTierExecutor && !request.behaviorExamples?.length) {
                 try {
                     const ft = await this.tryFreeTierGeneration(request);
                     if (ft) {
@@ -354,11 +354,12 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
                     }
                 }
                 // Three-loop protocol: instantAdapt must precede recordOutcome
-                if (isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()) {
+                const coverageEstimate = result.value.coverageEstimate;
+                if (coverageEstimate !== null && isSONAThreeLoopEnabled() && this.qesona?.isThreeLoopEnabled()) {
                     const tests = result.value;
                     this.qesona.instantAdapt([
                         tests.tests.length / 20,
-                        tests.coverageEstimate / 100,
+                        coverageEstimate / 100,
                         tests.patternsUsed.length / 10,
                         request.sourceFiles.length / 20,
                         (request.coverageTarget ?? 80) / 100,
@@ -476,7 +477,7 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
             framework,
             llmEnhanced: true,
         };
-        return { tests: [test], coverageEstimate: 0, patternsUsed: ['free-tier-local', `tier:${r.tierUsed}`] };
+        return { tests: [test], coverageEstimate: null, patternsUsed: ['free-tier-local', `tier:${r.tierUsed}`] };
     }
     /**
      * Generate tests using TDD workflow
@@ -953,7 +954,7 @@ export class TestGenerationCoordinator extends BaseDomainCoordinator {
      * Per ADR-040: Store test generation patterns in SONA
      */
     async storeTestGenerationPattern(tests, request) {
-        if (!this.qesona) {
+        if (!this.qesona || tests.coverageEstimate === null) {
             return;
         }
         try {

package/dist/domains/test-generation/interfaces.d.ts

@@ -16,7 +16,14 @@ export interface ITestGenerationAPI {
     /** Learn patterns from existing tests */
     learnPatterns(request: ILearnPatternsRequest): Promise<Result<ILearnedPatterns, Error>>;
 }
+/** Caller-owned specifications; expected values are never inferred from source. */
+export interface BehaviorExample {
+    functionName: string;
+    args: unknown[];
+    expected: unknown;
+}
 export interface IGenerateTestsRequest {
+    behaviorExamples?: BehaviorExample[];
     sourceFiles: string[];
     testType: 'unit' | 'integration' | 'e2e';
     framework?: TestFramework;
@@ -41,7 +48,8 @@ export interface IGenerateTestsRequest {
 }
 export interface IGeneratedTests {
     tests: IGeneratedTest[];
-    coverageEstimate: number;
+    /** null means unmeasured; never coerce unknown coverage to measured zero. */
+    coverageEstimate: number | null;
     /** Human-readable pattern names, for display (reports, CLI output). */
     patternsUsed: string[];
     /** Real qe_patterns.id values for the same patterns, for usage/ADR-110 tracking. */
@@ -61,6 +69,8 @@ export interface IGeneratedTest {
     compilationErrors?: string[];
     /** ADR-051: Whether test was enhanced by LLM */
     llmEnhanced?: boolean;
+    generationMode?: 'behavior-examples' | 'scaffolding';
+    generationLimits?: string[];
     /** Test quality gate validation result (loki-mode Gates 8 & 9) */
     qualityGateResult?: TestQualityGateResult;
     /** ADR-062: Whether this test is a holdout test (not shown to developer, runs in CI only) */

package/dist/domains/test-generation/services/behavior-example-validation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Boundary validation for caller-supplied behavior examples (#787 / #795).
+ *
+ * Shared by the MCP handlers, the CLI `--behavior-examples` path and the
+ * domain service so every entry point rejects the same malformed input with
+ * the same message. Failures are `CallerInputError`s: they are the caller's
+ * problem, not a sign of an unhealthy test-generation domain, and must never
+ * count toward its circuit breaker.
+ *
+ * Only the shape is checked here. Whether `functionName` exists in the source
+ * and whether `args` matches its arity can only be decided against the parsed
+ * source (see behavior-examples.ts), which also throws `CallerInputError`.
+ *
+ * Kept free of heavy imports (no `typescript`) so boundary layers can use it.
+ */
+import type { BehaviorExample } from '../interfaces.js';
+/**
+ * JSON Schema for one `behaviorExamples` element. Single source of truth for
+ * every tool definition that advertises `behaviorExamples` (protocol server
+ * `test_generate_enhanced` and `qe/tests/generate`).
+ */
+export declare const BEHAVIOR_EXAMPLE_ITEM_SCHEMA: Record<string, unknown>;
+/**
+ * Throw unless `value` is plain JSON data that can be emitted as a literal:
+ * finite numbers (no -0), strings, booleans, null, arrays and plain objects,
+ * without cycles.
+ */
+export declare function assertBehaviorJsonValue(value: unknown, label?: string): void;
+/**
+ * Validate the shape of `behaviorExamples` at a system boundary.
+ *
+ * @returns the examples typed as `BehaviorExample[]`, or `undefined` when omitted
+ * @throws CallerInputError describing the first invalid entry
+ */
+export declare function validateBehaviorExamples(value: unknown): BehaviorExample[] | undefined;
+//# sourceMappingURL=behavior-example-validation.d.ts.map

package/dist/domains/test-generation/services/behavior-example-validation.js

@@ -0,0 +1,89 @@
+/**
+ * Boundary validation for caller-supplied behavior examples (#787 / #795).
+ *
+ * Shared by the MCP handlers, the CLI `--behavior-examples` path and the
+ * domain service so every entry point rejects the same malformed input with
+ * the same message. Failures are `CallerInputError`s: they are the caller's
+ * problem, not a sign of an unhealthy test-generation domain, and must never
+ * count toward its circuit breaker.
+ *
+ * Only the shape is checked here. Whether `functionName` exists in the source
+ * and whether `args` matches its arity can only be decided against the parsed
+ * source (see behavior-examples.ts), which also throws `CallerInputError`.
+ *
+ * Kept free of heavy imports (no `typescript`) so boundary layers can use it.
+ */
+import { CallerInputError } from '../../../shared/error-utils.js';
+const SHAPE_HINT = 'expected [{ "functionName": "add", "args": [2, 3], "expected": 5 }]';
+/**
+ * JSON Schema for one `behaviorExamples` element. Single source of truth for
+ * every tool definition that advertises `behaviorExamples` (protocol server
+ * `test_generate_enhanced` and `qe/tests/generate`).
+ */
+export const BEHAVIOR_EXAMPLE_ITEM_SCHEMA = {
+    type: 'object',
+    description: 'One caller-owned specification example',
+    properties: {
+        functionName: { type: 'string', description: 'Named export of the source file to call' },
+        args: { type: 'array', description: 'Positional JSON arguments; length must equal the function arity', items: {} },
+        expected: { description: 'Expected JSON return value (use null for a null result)' },
+    },
+    required: ['functionName', 'args', 'expected'],
+};
+/**
+ * Throw unless `value` is plain JSON data that can be emitted as a literal:
+ * finite numbers (no -0), strings, booleans, null, arrays and plain objects,
+ * without cycles.
+ */
+export function assertBehaviorJsonValue(value, label = 'Behavior example value') {
+    const visit = (v, seen) => {
+        if (v === null || typeof v === 'string' || typeof v === 'boolean')
+            return;
+        if (typeof v === 'number' && Number.isFinite(v) && !Object.is(v, -0))
+            return;
+        if (typeof v !== 'object' || seen.has(v)) {
+            throw new CallerInputError(`${label} must be finite JSON data (no undefined, functions, NaN/Infinity, cycles, or negative zero)`);
+        }
+        if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) {
+            throw new CallerInputError(`${label} must contain only plain JSON objects`);
+        }
+        seen.add(v);
+        for (const item of Array.isArray(v) ? Array.from(v) : Object.values(v))
+            visit(item, seen);
+        seen.delete(v);
+    };
+    visit(value, new Set());
+}
+/**
+ * Validate the shape of `behaviorExamples` at a system boundary.
+ *
+ * @returns the examples typed as `BehaviorExample[]`, or `undefined` when omitted
+ * @throws CallerInputError describing the first invalid entry
+ */
+export function validateBehaviorExamples(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new CallerInputError(`behaviorExamples must be an array; ${SHAPE_HINT}`);
+    }
+    value.forEach((example, index) => {
+        const at = `behaviorExamples[${index}]`;
+        if (typeof example !== 'object' || example === null || Array.isArray(example)) {
+            throw new CallerInputError(`${at} must be an object; ${SHAPE_HINT}`);
+        }
+        const record = example;
+        if (typeof record.functionName !== 'string' || record.functionName.trim() === '') {
+            throw new CallerInputError(`${at}.functionName must be a non-empty string`);
+        }
+        if (!Array.isArray(record.args)) {
+            throw new CallerInputError(`${at}.args must be an array of arguments`);
+        }
+        if (!Object.prototype.hasOwnProperty.call(record, 'expected')) {
+            throw new CallerInputError(`${at}.expected is required (use null for a null result)`);
+        }
+        assertBehaviorJsonValue(record.args, `${at}.args`);
+        assertBehaviorJsonValue(record.expected, `${at}.expected`);
+    });
+    return value;
+}
+//# sourceMappingURL=behavior-example-validation.js.map

package/dist/domains/test-generation/services/behavior-examples.d.ts

@@ -0,0 +1,8 @@
+import type { BehaviorExample } from '../interfaces.js';
+export declare function generateBehaviorExamples(source: string, sourceFile: string, importPath: string, framework: string, examples: BehaviorExample[] | undefined, testType: string): {
+    code: string;
+    limits: string[];
+    assertions: number;
+    mode: "behavior-examples" | "scaffolding";
+};
+//# sourceMappingURL=behavior-examples.d.ts.map

package/dist/domains/test-generation/services/behavior-examples.js

@@ -0,0 +1,65 @@
+import ts from 'typescript';
+import { CallerInputError } from '../../../shared/error-utils.js';
+import { assertBehaviorJsonValue, validateBehaviorExamples } from './behavior-example-validation.js';
+/** JSON-only data is emitted as a parsed string, never interpolated as source. */
+function literal(value) {
+    assertBehaviorJsonValue(value);
+    return `JSON.parse(${JSON.stringify(JSON.stringify(value))})`;
+}
+export function generateBehaviorExamples(source, sourceFile, importPath, framework, examples, testType) {
+    const supported = ['vitest', 'jest', 'node-test'].includes(framework) && testType === 'unit';
+    const ast = ts.createSourceFile(sourceFile, source, ts.ScriptTarget.Latest, true);
+    const diagnostics = ast.parseDiagnostics;
+    if (diagnostics.length)
+        throw new CallerInputError('Cannot generate behavior examples from syntactically invalid source');
+    const exports = new Map();
+    for (const node of ast.statements) {
+        if (!ts.canHaveModifiers(node) || !ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        if (ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword))
+            continue;
+        const add = (name, fn) => {
+            if (fn.body && !fn.asteriskToken && fn.parameters.every(p => ts.isIdentifier(p.name) && p.name.text !== 'this' && !p.dotDotDotToken && !p.questionToken && !p.initializer))
+                exports.set(name, fn.parameters.length);
+        };
+        if (ts.isFunctionDeclaration(node) && node.name)
+            add(node.name.text, node);
+        if (ts.isVariableStatement(node))
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name) && decl.initializer && (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)))
+                    add(decl.name.text, decl.initializer);
+            }
+    }
+    validateBehaviorExamples(examples);
+    if (examples?.length && !supported)
+        throw new CallerInputError('Behavior examples support unit tests with vitest, jest, or node-test only');
+    const limits = [];
+    if (importPath === './module-under-test')
+        limits.push('Inline source: save the source and replace ./module-under-test with its real import path before running.');
+    const lines = [framework === 'node-test' ? "import { test } from 'node:test';\nimport assert from 'node:assert/strict';" : framework === 'vitest' ? "import { test, expect } from 'vitest';" : "import { test, expect } from '@jest/globals';"];
+    if (!examples?.length) {
+        limits.push('Scaffolding only: supply behaviorExamples from a specification or trusted fixtures. No behavior or coverage has been verified.');
+        lines.push(`test.skip('Scaffolding: behaviorExamples required for ${exports.size} supported named exports', () => {});`);
+    }
+    else {
+        lines.push(`import * as subject from ${JSON.stringify(importPath)};`);
+        for (const [index, example] of examples.entries()) {
+            if (!example || typeof example.functionName !== 'string' || !exports.has(example.functionName))
+                throw new CallerInputError(`Behavior example ${index + 1} must target a named exported function with required simple parameters; '${String(example?.functionName)}' is not one (supported: ${[...exports.keys()].join(', ') || 'none'})`);
+            if (!Array.isArray(example.args) || example.args.length !== exports.get(example.functionName))
+                throw new CallerInputError(`Behavior example argument count does not match ${example.functionName}`);
+            if (!Object.prototype.hasOwnProperty.call(example, 'expected'))
+                throw new CallerInputError('Behavior example requires an explicit expected value');
+            const call = `await subject[${JSON.stringify(example.functionName)}](${Array.from(example.args).map(a => literal(a)).join(', ')})`;
+            const assertion = framework === 'node-test' ? `assert.deepStrictEqual(${call}, ${literal(example.expected)});` : `expect(${call}).toStrictEqual(${literal(example.expected)});`;
+            lines.push(`test(${JSON.stringify(`${example.functionName}: specification example ${index + 1}`)}, async () => { ${assertion} });`);
+        }
+        const uncovered = [...exports.keys()].filter(name => !examples.some(e => e.functionName === name));
+        if (uncovered.length)
+            limits.push(`No supplied behavior examples for: ${uncovered.join(', ')}`);
+        limits.push('Only supplied examples are asserted; coverage is unmeasured. Re-exports, default exports, classes, rest/default/destructured/optional parameters and thrown-error specifications are unsupported.');
+    }
+    return { code: `// ${limits.join('\n// ')}\n${lines.join('\n')}\n`, limits, assertions: examples?.length ?? 0,
+        mode: examples?.length ? 'behavior-examples' : 'scaffolding' };
+}
+//# sourceMappingURL=behavior-examples.js.map

package/dist/domains/test-generation/services/test-generator.d.ts

@@ -70,6 +70,7 @@ export declare class TestGeneratorService implements ITestGenerationService {
     private readonly config;
     private readonly memory;
     private readonly generatorFactory;
+    private readonly usesDefaultGenerator;
     private readonly tddGenerator;
     private readonly propertyTestGenerator;
     private readonly testDataGenerator;
@@ -164,7 +165,6 @@ export declare class TestGeneratorService implements ITestGenerationService {
     private extractModuleName;
     private getImportPath;
     private countAssertions;
-    private estimateCoverage;
     private storeGenerationMetadata;
 }
 /**