agentic-qe 3.7.21 → 3.8.0

package/dist/coordination/behavior-tree/nodes.js

@@ -0,0 +1,338 @@
+/**
+ * Behavior Tree Core Nodes
+ *
+ * Composable behavior tree nodes for agent orchestration.
+ * Each node implements a tick-based evaluation model returning
+ * SUCCESS, FAILURE, or RUNNING.
+ */
+// ============================================================================
+// Abstract Base
+// ============================================================================
+class BaseNode {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    serialize() {
+        return { type: this.type, name: this.name };
+    }
+}
+class CompositeNode extends BaseNode {
+    children;
+    constructor(name, children) {
+        super(name);
+        this.children = children;
+    }
+    reset() {
+        for (const child of this.children) {
+            child.reset();
+        }
+    }
+    serialize() {
+        return {
+            type: this.type,
+            name: this.name,
+            children: this.children.map((c) => c.serialize()),
+        };
+    }
+}
+// ============================================================================
+// Composite Nodes
+// ============================================================================
+/**
+ * Sequence node - AND logic.
+ *
+ * Runs children in order from left to right:
+ * - Returns FAILURE immediately when any child fails
+ * - Returns RUNNING if a child is still running
+ * - Returns SUCCESS only when all children succeed
+ */
+export class SequenceNode extends CompositeNode {
+    type = 'Sequence';
+    currentIndex = 0;
+    constructor(name, children) {
+        super(name, children);
+    }
+    async tick() {
+        while (this.currentIndex < this.children.length) {
+            const child = this.children[this.currentIndex];
+            const status = await child.tick();
+            if (status === 'FAILURE') {
+                return 'FAILURE';
+            }
+            if (status === 'RUNNING') {
+                return 'RUNNING';
+            }
+            // SUCCESS - move to next child
+            this.currentIndex++;
+        }
+        return 'SUCCESS';
+    }
+    reset() {
+        this.currentIndex = 0;
+        super.reset();
+    }
+}
+/**
+ * Selector node - OR logic.
+ *
+ * Runs children in order from left to right:
+ * - Returns SUCCESS immediately when any child succeeds
+ * - Returns RUNNING if a child is still running
+ * - Returns FAILURE only when all children fail
+ */
+export class SelectorNode extends CompositeNode {
+    type = 'Selector';
+    currentIndex = 0;
+    constructor(name, children) {
+        super(name, children);
+    }
+    async tick() {
+        while (this.currentIndex < this.children.length) {
+            const child = this.children[this.currentIndex];
+            const status = await child.tick();
+            if (status === 'SUCCESS') {
+                return 'SUCCESS';
+            }
+            if (status === 'RUNNING') {
+                return 'RUNNING';
+            }
+            // FAILURE - try next child
+            this.currentIndex++;
+        }
+        return 'FAILURE';
+    }
+    reset() {
+        this.currentIndex = 0;
+        super.reset();
+    }
+}
+/**
+ * Parallel node - concurrent execution.
+ *
+ * Runs all children concurrently:
+ * - Returns SUCCESS when successThreshold children succeed
+ * - Returns FAILURE when it becomes impossible to meet the threshold
+ * - Returns RUNNING while children are still executing
+ */
+export class ParallelNode extends CompositeNode {
+    type = 'Parallel';
+    config;
+    constructor(name, children, config) {
+        super(name, children);
+        this.config = {
+            successThreshold: config.successThreshold,
+            waitForAll: config.waitForAll ?? false,
+        };
+    }
+    async tick() {
+        const results = await Promise.all(this.children.map((child) => child.tick()));
+        let successCount = 0;
+        let failureCount = 0;
+        let runningCount = 0;
+        for (const status of results) {
+            if (status === 'SUCCESS')
+                successCount++;
+            else if (status === 'FAILURE')
+                failureCount++;
+            else
+                runningCount++;
+        }
+        // Enough successes to meet threshold
+        if (successCount >= this.config.successThreshold) {
+            if (this.config.waitForAll && runningCount > 0) {
+                return 'RUNNING';
+            }
+            return 'SUCCESS';
+        }
+        // Impossible to reach threshold
+        const maxPossibleSuccesses = successCount + runningCount;
+        if (maxPossibleSuccesses < this.config.successThreshold) {
+            return 'FAILURE';
+        }
+        return 'RUNNING';
+    }
+    serialize() {
+        return {
+            type: this.type,
+            name: this.name,
+            children: this.children.map((c) => c.serialize()),
+            config: {
+                successThreshold: this.config.successThreshold,
+                waitForAll: this.config.waitForAll,
+            },
+        };
+    }
+}
+// ============================================================================
+// Leaf Nodes
+// ============================================================================
+/**
+ * Action node - leaf node that executes a function.
+ *
+ * Wraps an async function that returns a NodeStatus.
+ * Use for side-effectful operations like running tests or generating code.
+ */
+export class ActionNode extends BaseNode {
+    type = 'Action';
+    action;
+    actionId;
+    constructor(name, action, actionId) {
+        super(name);
+        this.action = action;
+        this.actionId = actionId ?? name;
+    }
+    async tick() {
+        try {
+            return await this.action();
+        }
+        catch {
+            return 'FAILURE';
+        }
+    }
+    reset() {
+        // Leaf nodes have no state to reset
+    }
+    serialize() {
+        return {
+            type: this.type,
+            name: this.name,
+            config: { actionId: this.actionId },
+        };
+    }
+}
+/**
+ * Condition node - leaf node that checks a predicate.
+ *
+ * Wraps an async predicate that returns boolean.
+ * Returns SUCCESS if predicate is true, FAILURE if false.
+ * Use for checking preconditions or guard clauses.
+ */
+export class ConditionNode extends BaseNode {
+    type = 'Condition';
+    predicate;
+    conditionId;
+    constructor(name, predicate, conditionId) {
+        super(name);
+        this.predicate = predicate;
+        this.conditionId = conditionId ?? name;
+    }
+    async tick() {
+        try {
+            const result = await this.predicate();
+            return result ? 'SUCCESS' : 'FAILURE';
+        }
+        catch {
+            return 'FAILURE';
+        }
+    }
+    reset() {
+        // Leaf nodes have no state to reset
+    }
+    serialize() {
+        return {
+            type: this.type,
+            name: this.name,
+            config: { conditionId: this.conditionId },
+        };
+    }
+}
+/**
+ * Deserialize a serialized node tree back into executable BehaviorNodes.
+ *
+ * Requires a handler registry to reconstruct Action and Condition nodes
+ * since functions cannot be serialized directly.
+ *
+ * Supports both core nodes (Sequence, Selector, Parallel, Action, Condition)
+ * and decorator nodes (Inverter, Repeat, UntilFail, Timeout, Retry).
+ * Decorator classes must be registered via registerDecoratorTypes() before
+ * deserialization of trees containing decorators.
+ */
+export function deserializeNode(data, registry) {
+    switch (data.type) {
+        case 'Sequence': {
+            const children = (data.children ?? []).map((c) => deserializeNode(c, registry));
+            return new SequenceNode(data.name, children);
+        }
+        case 'Selector': {
+            const children = (data.children ?? []).map((c) => deserializeNode(c, registry));
+            return new SelectorNode(data.name, children);
+        }
+        case 'Parallel': {
+            const children = (data.children ?? []).map((c) => deserializeNode(c, registry));
+            const config = {
+                successThreshold: data.config?.successThreshold ?? children.length,
+                waitForAll: data.config?.waitForAll ?? false,
+            };
+            return new ParallelNode(data.name, children, config);
+        }
+        case 'Action': {
+            const actionId = data.config?.actionId ?? data.name;
+            const handler = registry.actions.get(actionId);
+            if (!handler) {
+                throw new Error(`Action handler not found in registry: '${actionId}'`);
+            }
+            return new ActionNode(data.name, handler, actionId);
+        }
+        case 'Condition': {
+            const conditionId = data.config?.conditionId ?? data.name;
+            const handler = registry.conditions.get(conditionId);
+            if (!handler) {
+                throw new Error(`Condition handler not found in registry: '${conditionId}'`);
+            }
+            return new ConditionNode(data.name, handler, conditionId);
+        }
+        // Decorator types - require exactly one child
+        case 'Inverter':
+        case 'Repeat':
+        case 'UntilFail':
+        case 'Timeout':
+        case 'Retry': {
+            const decoratorFactory = _decoratorFactories.get(data.type);
+            if (!decoratorFactory) {
+                throw new Error(`Decorator type '${data.type}' not registered. ` +
+                    `Call registerDecoratorTypes() before deserializing trees with decorators.`);
+            }
+            const children = data.children ?? [];
+            if (children.length !== 1) {
+                throw new Error(`Decorator '${data.type}' requires exactly 1 child, got ${children.length}`);
+            }
+            const child = deserializeNode(children[0], registry);
+            return decoratorFactory(data.name, child, data.config ?? {});
+        }
+        default:
+            throw new Error(`Unknown node type: '${data.type}'`);
+    }
+}
+const _decoratorFactories = new Map();
+/**
+ * Register decorator type factories for deserialization.
+ * Called automatically when decorators module is imported via the barrel export.
+ */
+export function registerDecoratorFactory(type, factory) {
+    _decoratorFactories.set(type, factory);
+}
+// ============================================================================
+// Factory Helpers
+// ============================================================================
+/** Create a Sequence node */
+export function sequence(name, children) {
+    return new SequenceNode(name, children);
+}
+/** Create a Selector node */
+export function selector(name, children) {
+    return new SelectorNode(name, children);
+}
+/** Create a Parallel node */
+export function parallel(name, children, config) {
+    return new ParallelNode(name, children, config);
+}
+/** Create an Action node */
+export function action(name, fn, actionId) {
+    return new ActionNode(name, fn, actionId);
+}
+/** Create a Condition node */
+export function condition(name, predicate, conditionId) {
+    return new ConditionNode(name, predicate, conditionId);
+}
+//# sourceMappingURL=nodes.js.map

package/dist/coordination/behavior-tree/qe-trees.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Pre-built Behavior Trees for Common QE Workflows
+ *
+ * Provides ready-to-use behavior tree templates for:
+ * - Test generation pipeline
+ * - Regression suite execution
+ * - Security audit workflow
+ *
+ * Each tree is constructed using the core nodes and decorators,
+ * and can be serialized to JSON for persistence/transfer.
+ */
+import { type BehaviorNode, type ActionFunction, type ConditionPredicate, type NodeHandlerRegistry } from './nodes.js';
+/** Well-known action IDs for QE behavior trees */
+export declare const QEActionIds: {
+    readonly ANALYZE_CODE: "qe.analyze-code";
+    readonly GENERATE_TESTS: "qe.generate-tests";
+    readonly VALIDATE_TESTS: "qe.validate-tests";
+    readonly COMMIT_TESTS: "qe.commit-tests";
+    readonly LOAD_TESTS: "qe.load-tests";
+    readonly EXECUTE_TESTS: "qe.execute-tests";
+    readonly COLLECT_RESULTS: "qe.collect-results";
+    readonly GENERATE_REPORT: "qe.generate-report";
+    readonly SCAN_VULNERABILITIES: "qe.scan-vulnerabilities";
+    readonly CLASSIFY_FINDINGS: "qe.classify-findings";
+    readonly GENERATE_SECURITY_REPORT: "qe.generate-security-report";
+    readonly REMEDIATE_ISSUES: "qe.remediate-issues";
+};
+/** Well-known condition IDs for QE behavior trees */
+export declare const QEConditionIds: {
+    readonly HAS_SOURCE_FILES: "qe.has-source-files";
+    readonly TESTS_ARE_VALID: "qe.tests-are-valid";
+    readonly HAS_TEST_FILES: "qe.has-test-files";
+    readonly ALL_TESTS_PASSED: "qe.all-tests-passed";
+    readonly HAS_CRITICAL_FINDINGS: "qe.has-critical-findings";
+    readonly SCAN_COMPLETE: "qe.scan-complete";
+};
+/**
+ * Context for building QE behavior trees with injectable handlers.
+ *
+ * When building trees for actual execution, provide real action/condition
+ * implementations. For testing or serialization, provide stubs.
+ */
+export interface QETreeHandlers {
+    actions: Partial<Record<string, ActionFunction>>;
+    conditions: Partial<Record<string, ConditionPredicate>>;
+}
+/**
+ * Build a test generation pipeline behavior tree.
+ *
+ * Flow:
+ *   Sequence("Test Generation Pipeline")
+ *     Condition("Has Source Files")
+ *     Retry("Analyze Code with Retry", maxRetries=2)
+ *       Action("Analyze Code")
+ *     Action("Generate Tests")
+ *     Sequence("Validate and Commit")
+ *       Action("Validate Tests")
+ *       Condition("Tests Are Valid")
+ *       Action("Commit Tests")
+ */
+export declare function buildTestGenerationPipeline(handlers: QETreeHandlers): BehaviorNode;
+/**
+ * Build a regression suite execution behavior tree.
+ *
+ * Flow:
+ *   Sequence("Regression Suite")
+ *     Condition("Has Test Files")
+ *     Action("Load Tests")
+ *     Timeout("Execute Tests with Timeout", 300000ms)
+ *       Parallel("Execute Tests in Parallel", threshold=all)
+ *         Action("Execute Tests")
+ *     Action("Collect Results")
+ *     Action("Generate Report")
+ */
+export declare function buildRegressionSuite(handlers: QETreeHandlers, testTimeoutMs?: number): BehaviorNode;
+/**
+ * Build a security audit behavior tree.
+ *
+ * Flow:
+ *   Sequence("Security Audit")
+ *     Retry("Scan with Retry", maxRetries=3)
+ *       Action("Scan Vulnerabilities")
+ *     Action("Classify Findings")
+ *     Action("Generate Security Report")
+ *     Selector("Handle Findings")
+ *       Sequence("Remediate if Critical")
+ *         Condition("Has Critical Findings")
+ *         Action("Remediate Issues")
+ *       Action("Generate Security Report")  // fallback: just report
+ */
+export declare function buildSecurityAudit(handlers: QETreeHandlers): BehaviorNode;
+/**
+ * Create a NodeHandlerRegistry from QETreeHandlers.
+ * Maps QE-specific handler maps to the generic deserialization registry.
+ */
+export declare function createQEHandlerRegistry(handlers: QETreeHandlers): NodeHandlerRegistry;
+/**
+ * Serialize a QE behavior tree to a JSON string.
+ */
+export declare function serializeQETree(tree: BehaviorNode): string;
+/**
+ * Deserialize a QE behavior tree from a JSON string.
+ */
+export declare function deserializeQETree(json: string, handlers: QETreeHandlers): BehaviorNode;
+//# sourceMappingURL=qe-trees.d.ts.map

package/dist/coordination/behavior-tree/qe-trees.js

@@ -0,0 +1,181 @@
+/**
+ * Pre-built Behavior Trees for Common QE Workflows
+ *
+ * Provides ready-to-use behavior tree templates for:
+ * - Test generation pipeline
+ * - Regression suite execution
+ * - Security audit workflow
+ *
+ * Each tree is constructed using the core nodes and decorators,
+ * and can be serialized to JSON for persistence/transfer.
+ */
+import { SequenceNode, SelectorNode, ParallelNode, ActionNode, ConditionNode, deserializeNode, } from './nodes.js';
+import { RetryNode, TimeoutNode } from './decorators.js';
+// ============================================================================
+// QE Action/Condition IDs (used for serialization registry)
+// ============================================================================
+/** Well-known action IDs for QE behavior trees */
+export const QEActionIds = {
+    // Test Generation Pipeline
+    ANALYZE_CODE: 'qe.analyze-code',
+    GENERATE_TESTS: 'qe.generate-tests',
+    VALIDATE_TESTS: 'qe.validate-tests',
+    COMMIT_TESTS: 'qe.commit-tests',
+    // Regression Suite
+    LOAD_TESTS: 'qe.load-tests',
+    EXECUTE_TESTS: 'qe.execute-tests',
+    COLLECT_RESULTS: 'qe.collect-results',
+    GENERATE_REPORT: 'qe.generate-report',
+    // Security Audit
+    SCAN_VULNERABILITIES: 'qe.scan-vulnerabilities',
+    CLASSIFY_FINDINGS: 'qe.classify-findings',
+    GENERATE_SECURITY_REPORT: 'qe.generate-security-report',
+    REMEDIATE_ISSUES: 'qe.remediate-issues',
+};
+/** Well-known condition IDs for QE behavior trees */
+export const QEConditionIds = {
+    HAS_SOURCE_FILES: 'qe.has-source-files',
+    TESTS_ARE_VALID: 'qe.tests-are-valid',
+    HAS_TEST_FILES: 'qe.has-test-files',
+    ALL_TESTS_PASSED: 'qe.all-tests-passed',
+    HAS_CRITICAL_FINDINGS: 'qe.has-critical-findings',
+    SCAN_COMPLETE: 'qe.scan-complete',
+};
+function getAction(handlers, id) {
+    const fn = handlers.actions[id];
+    if (fn)
+        return fn;
+    return async () => 'SUCCESS';
+}
+function getCondition(handlers, id) {
+    const fn = handlers.conditions[id];
+    if (fn)
+        return fn;
+    return async () => true;
+}
+// ============================================================================
+// Test Generation Pipeline
+// ============================================================================
+/**
+ * Build a test generation pipeline behavior tree.
+ *
+ * Flow:
+ *   Sequence("Test Generation Pipeline")
+ *     Condition("Has Source Files")
+ *     Retry("Analyze Code with Retry", maxRetries=2)
+ *       Action("Analyze Code")
+ *     Action("Generate Tests")
+ *     Sequence("Validate and Commit")
+ *       Action("Validate Tests")
+ *       Condition("Tests Are Valid")
+ *       Action("Commit Tests")
+ */
+export function buildTestGenerationPipeline(handlers) {
+    return new SequenceNode('Test Generation Pipeline', [
+        new ConditionNode('Has Source Files', getCondition(handlers, QEConditionIds.HAS_SOURCE_FILES), QEConditionIds.HAS_SOURCE_FILES),
+        new RetryNode('Analyze Code with Retry', new ActionNode('Analyze Code', getAction(handlers, QEActionIds.ANALYZE_CODE), QEActionIds.ANALYZE_CODE), 2),
+        new ActionNode('Generate Tests', getAction(handlers, QEActionIds.GENERATE_TESTS), QEActionIds.GENERATE_TESTS),
+        new SequenceNode('Validate and Commit', [
+            new ActionNode('Validate Tests', getAction(handlers, QEActionIds.VALIDATE_TESTS), QEActionIds.VALIDATE_TESTS),
+            new ConditionNode('Tests Are Valid', getCondition(handlers, QEConditionIds.TESTS_ARE_VALID), QEConditionIds.TESTS_ARE_VALID),
+            new ActionNode('Commit Tests', getAction(handlers, QEActionIds.COMMIT_TESTS), QEActionIds.COMMIT_TESTS),
+        ]),
+    ]);
+}
+// ============================================================================
+// Regression Suite
+// ============================================================================
+/**
+ * Build a regression suite execution behavior tree.
+ *
+ * Flow:
+ *   Sequence("Regression Suite")
+ *     Condition("Has Test Files")
+ *     Action("Load Tests")
+ *     Timeout("Execute Tests with Timeout", 300000ms)
+ *       Parallel("Execute Tests in Parallel", threshold=all)
+ *         Action("Execute Tests")
+ *     Action("Collect Results")
+ *     Action("Generate Report")
+ */
+export function buildRegressionSuite(handlers, testTimeoutMs = 300000) {
+    return new SequenceNode('Regression Suite', [
+        new ConditionNode('Has Test Files', getCondition(handlers, QEConditionIds.HAS_TEST_FILES), QEConditionIds.HAS_TEST_FILES),
+        new ActionNode('Load Tests', getAction(handlers, QEActionIds.LOAD_TESTS), QEActionIds.LOAD_TESTS),
+        new TimeoutNode('Execute Tests with Timeout', new ParallelNode('Execute Tests in Parallel', [
+            new ActionNode('Execute Tests', getAction(handlers, QEActionIds.EXECUTE_TESTS), QEActionIds.EXECUTE_TESTS),
+        ], { successThreshold: 1 }), testTimeoutMs),
+        new ActionNode('Collect Results', getAction(handlers, QEActionIds.COLLECT_RESULTS), QEActionIds.COLLECT_RESULTS),
+        new ActionNode('Generate Report', getAction(handlers, QEActionIds.GENERATE_REPORT), QEActionIds.GENERATE_REPORT),
+    ]);
+}
+// ============================================================================
+// Security Audit
+// ============================================================================
+/**
+ * Build a security audit behavior tree.
+ *
+ * Flow:
+ *   Sequence("Security Audit")
+ *     Retry("Scan with Retry", maxRetries=3)
+ *       Action("Scan Vulnerabilities")
+ *     Action("Classify Findings")
+ *     Action("Generate Security Report")
+ *     Selector("Handle Findings")
+ *       Sequence("Remediate if Critical")
+ *         Condition("Has Critical Findings")
+ *         Action("Remediate Issues")
+ *       Action("Generate Security Report")  // fallback: just report
+ */
+export function buildSecurityAudit(handlers) {
+    return new SequenceNode('Security Audit', [
+        new RetryNode('Scan with Retry', new ActionNode('Scan Vulnerabilities', getAction(handlers, QEActionIds.SCAN_VULNERABILITIES), QEActionIds.SCAN_VULNERABILITIES), 3),
+        new ActionNode('Classify Findings', getAction(handlers, QEActionIds.CLASSIFY_FINDINGS), QEActionIds.CLASSIFY_FINDINGS),
+        new ActionNode('Generate Security Report', getAction(handlers, QEActionIds.GENERATE_SECURITY_REPORT), QEActionIds.GENERATE_SECURITY_REPORT),
+        new SelectorNode('Handle Findings', [
+            new SequenceNode('Remediate if Critical', [
+                new ConditionNode('Has Critical Findings', getCondition(handlers, QEConditionIds.HAS_CRITICAL_FINDINGS), QEConditionIds.HAS_CRITICAL_FINDINGS),
+                new ActionNode('Remediate Issues', getAction(handlers, QEActionIds.REMEDIATE_ISSUES), QEActionIds.REMEDIATE_ISSUES),
+            ]),
+            // Fallback: always succeed (no critical findings = no remediation needed)
+            new ActionNode('No Remediation Needed', async () => 'SUCCESS', 'qe.no-remediation-needed'),
+        ]),
+    ]);
+}
+// ============================================================================
+// Serialization Utilities
+// ============================================================================
+/**
+ * Create a NodeHandlerRegistry from QETreeHandlers.
+ * Maps QE-specific handler maps to the generic deserialization registry.
+ */
+export function createQEHandlerRegistry(handlers) {
+    const actions = new Map();
+    const conditions = new Map();
+    for (const [id, fn] of Object.entries(handlers.actions)) {
+        if (fn)
+            actions.set(id, fn);
+    }
+    for (const [id, fn] of Object.entries(handlers.conditions)) {
+        if (fn)
+            conditions.set(id, fn);
+    }
+    // Add the no-remediation-needed fallback
+    actions.set('qe.no-remediation-needed', async () => 'SUCCESS');
+    return { actions, conditions };
+}
+/**
+ * Serialize a QE behavior tree to a JSON string.
+ */
+export function serializeQETree(tree) {
+    return JSON.stringify(tree.serialize(), null, 2);
+}
+/**
+ * Deserialize a QE behavior tree from a JSON string.
+ */
+export function deserializeQETree(json, handlers) {
+    const data = JSON.parse(json);
+    const registry = createQEHandlerRegistry(handlers);
+    return deserializeNode(data, registry);
+}
+//# sourceMappingURL=qe-trees.js.map