agentic-qe 3.6.0 → 3.6.2

package/v3/dist/coordination/competing-hypotheses/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Agentic QE v3 - Competing Hypotheses Types
+ * ADR-064 Phase 4A: Multi-Agent Investigation via Competing Hypotheses
+ *
+ * Defines types for the competing hypotheses pattern where N agents
+ * investigate a defect from different angles in parallel, collect
+ * evidence, and the system converges on the strongest hypothesis
+ * via evidence scoring.
+ */
+/**
+ * A hypothesis to investigate.
+ * Each hypothesis is assigned to an agent that investigates from a specific angle.
+ */
+export interface Hypothesis {
+    readonly id: string;
+    readonly description: string;
+    readonly investigatorAgentId?: string;
+    readonly strategy: InvestigationStrategy;
+    readonly status: HypothesisStatus;
+    readonly evidence: Evidence[];
+    readonly confidenceScore: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/**
+ * Lifecycle status of a hypothesis.
+ * - pending: Awaiting investigation start
+ * - investigating: Agent actively gathering evidence
+ * - completed: Agent finished investigation
+ * - rejected: Auto-rejected due to low confidence
+ */
+export type HypothesisStatus = 'pending' | 'investigating' | 'completed' | 'rejected';
+/**
+ * Strategy an agent uses to investigate a hypothesis.
+ * Each strategy represents a different investigation angle.
+ */
+export type InvestigationStrategy = 'code-analysis' | 'test-execution' | 'log-analysis' | 'dependency-tracing' | 'historical-pattern' | 'adversarial';
+/**
+ * Evidence gathered during hypothesis investigation.
+ * Each piece of evidence either supports or refutes the hypothesis,
+ * with a weight indicating how strongly it does so.
+ */
+export interface Evidence {
+    readonly id: string;
+    readonly hypothesisId: string;
+    readonly type: EvidenceType;
+    readonly description: string;
+    /** Weight from 0 to 1 indicating strength of this evidence */
+    readonly weight: number;
+    /** Whether this evidence supports (true) or refutes (false) the hypothesis */
+    readonly supports: boolean;
+    /** Agent or tool that produced this evidence */
+    readonly source: string;
+    /** Raw evidence data, if any */
+    readonly data?: unknown;
+    readonly timestamp: number;
+}
+/**
+ * Classification of evidence by origin.
+ */
+export type EvidenceType = 'test-result' | 'code-match' | 'log-entry' | 'dependency-chain' | 'pattern-match' | 'counter-example';
+/**
+ * An investigation session grouping multiple competing hypotheses.
+ * Created when a defect or issue needs root cause analysis from
+ * multiple angles.
+ */
+export interface Investigation {
+    readonly id: string;
+    readonly taskId: string;
+    readonly domain: string;
+    readonly description: string;
+    readonly hypotheses: Hypothesis[];
+    readonly status: InvestigationStatus;
+    readonly convergenceResult?: ConvergenceResult;
+    readonly maxHypotheses: number;
+    readonly convergenceThreshold: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/**
+ * Lifecycle status of an investigation session.
+ * - open: Accepting new hypotheses
+ * - investigating: Agents actively collecting evidence
+ * - converging: Convergence in progress
+ * - converged: A winning hypothesis was determined
+ * - inconclusive: No clear winner could be determined
+ */
+export type InvestigationStatus = 'open' | 'investigating' | 'converging' | 'converged' | 'inconclusive';
+/**
+ * Result of hypothesis convergence.
+ * Produced when the system evaluates all hypotheses and evidence
+ * to determine the most likely root cause.
+ */
+export interface ConvergenceResult {
+    /** ID of the winning hypothesis, or null if inconclusive */
+    readonly winningHypothesisId: string | null;
+    /** Confidence score of the winning hypothesis */
+    readonly confidence: number;
+    /** Human-readable summary of evidence across all hypotheses */
+    readonly evidenceSummary: string;
+    /** IDs of hypotheses that were rejected */
+    readonly rejectedHypotheses: string[];
+    /** Method used for convergence */
+    readonly method: ConvergenceMethod;
+}
+/**
+ * Method used to converge on a winning hypothesis.
+ * - evidence-scoring: Winner determined by confidence gap between top two
+ * - unanimous: Only one non-rejected hypothesis remained
+ * - majority: Multiple hypotheses, but one has clear majority evidence
+ * - timeout: Investigation timed out, best available selected
+ */
+export type ConvergenceMethod = 'evidence-scoring' | 'unanimous' | 'majority' | 'timeout';
+/**
+ * Configuration for the HypothesisManager.
+ * Controls how investigations are run and when convergence is triggered.
+ */
+export interface CompetingHypothesesConfig {
+    /** Maximum number of hypotheses per investigation (default: 5) */
+    readonly maxHypothesesPerInvestigation: number;
+    /** Minimum confidence gap between top two hypotheses to declare a winner (default: 0.2) */
+    readonly convergenceThreshold: number;
+    /** Maximum time in ms for an investigation before timeout (default: 300000) */
+    readonly investigationTimeoutMs: number;
+    /** Minimum evidence pieces needed before convergence can succeed (default: 3) */
+    readonly minEvidenceForConvergence: number;
+    /** Confidence score below which a hypothesis is auto-rejected (default: 0.15) */
+    readonly autoRejectThreshold: number;
+}
+/**
+ * Default configuration for the competing hypotheses system.
+ */
+export declare const DEFAULT_COMPETING_HYPOTHESES_CONFIG: CompetingHypothesesConfig;
+//# sourceMappingURL=types.d.ts.map

package/v3/dist/coordination/competing-hypotheses/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/coordination/competing-hypotheses/types.ts"],"names":[],"mappings":"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"}

package/v3/dist/coordination/competing-hypotheses/types.js

@@ -0,0 +1,20 @@
+/**
+ * Agentic QE v3 - Competing Hypotheses Types
+ * ADR-064 Phase 4A: Multi-Agent Investigation via Competing Hypotheses
+ *
+ * Defines types for the competing hypotheses pattern where N agents
+ * investigate a defect from different angles in parallel, collect
+ * evidence, and the system converges on the strongest hypothesis
+ * via evidence scoring.
+ */
+/**
+ * Default configuration for the competing hypotheses system.
+ */
+export const DEFAULT_COMPETING_HYPOTHESES_CONFIG = {
+    maxHypothesesPerInvestigation: 5,
+    convergenceThreshold: 0.2,
+    investigationTimeoutMs: 300_000, // 5 minutes
+    minEvidenceForConvergence: 3,
+    autoRejectThreshold: 0.15,
+};
+//# sourceMappingURL=types.js.map

package/v3/dist/coordination/competing-hypotheses/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/coordination/competing-hypotheses/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6KH;;GAEG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAA8B;IAC5E,6BAA6B,EAAE,CAAC;IAChC,oBAAoB,EAAE,GAAG;IACzB,sBAAsB,EAAE,OAAO,EAAE,YAAY;IAC7C,yBAAyB,EAAE,CAAC;IAC5B,mBAAmB,EAAE,IAAI;CAC1B,CAAC"}

package/v3/dist/coordination/dynamic-scaling/dynamic-scaler.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Agentic QE v3 - Dynamic Scaler
+ * ADR-064 Phase 4C: Reactive Auto-Scaling Based on Workload Metrics
+ *
+ * Monitors workload metrics (queue depth, agent utilization, error rates)
+ * and produces scaling decisions to adjust agent count within policy bounds.
+ * Supports pluggable ScaleExecutor callbacks for integration with the
+ * Queen Coordinator or any other agent lifecycle manager.
+ *
+ * @example
+ * ```typescript
+ * import { createDynamicScaler } from './coordination/dynamic-scaling';
+ *
+ * const scaler = createDynamicScaler(4); // start with 4 agents
+ *
+ * // Feed metrics periodically
+ * scaler.recordMetrics({
+ *   queueDepth: 15,
+ *   activeAgents: 4,
+ *   idleAgents: 0,
+ *   avgTaskDurationMs: 2000,
+ *   errorRate: 0.05,
+ *   throughput: 12,
+ *   timestamp: Date.now(),
+ * });
+ *
+ * // Evaluate and optionally execute
+ * const decision = scaler.evaluate();
+ * if (decision.action !== 'maintain') {
+ *   await scaler.execute(decision, async (current, target) => {
+ *     // Integrate with Queen Coordinator to spawn/terminate agents
+ *     return true;
+ *   });
+ * }
+ * ```
+ */
+import type { WorkloadMetrics, ScalingDecision, ScalingPolicy, ScalingEvent, ScalerStats, DynamicScalingConfig } from './types';
+/**
+ * Callback invoked to execute a scaling action.
+ * Returns `true` if the scaling was successful, `false` otherwise.
+ *
+ * @param currentAgents - Current number of active agents
+ * @param targetAgents - Desired number of agents after scaling
+ */
+export type ScaleExecutor = (currentAgents: number, targetAgents: number) => Promise<boolean>;
+/**
+ * Reactive auto-scaler that evaluates workload metrics against a configurable
+ * policy and produces scaling decisions with cooldown protection.
+ *
+ * Lifecycle:
+ * 1. Feed metrics via {@link recordMetrics}
+ * 2. Call {@link evaluate} to get a scaling decision
+ * 3. Optionally call {@link execute} to apply the decision
+ *
+ * The scaler maintains sliding-window metric averages and enforces cooldown
+ * between scaling actions to prevent oscillation.
+ */
+export declare class DynamicScaler {
+    private readonly config;
+    private policy;
+    private readonly metricsHistory;
+    private readonly events;
+    private lastScaleTime;
+    private scaleUpCount;
+    private scaleDownCount;
+    private totalDecisions;
+    private currentAgents;
+    private lastDecision?;
+    /**
+     * Create a new DynamicScaler.
+     *
+     * @param initialAgents - Starting agent count (defaults to policy minAgents)
+     * @param config - Optional partial config to override defaults
+     */
+    constructor(initialAgents?: number, config?: Partial<DynamicScalingConfig>);
+    /**
+     * Record a workload metrics sample.
+     * Oldest samples are evicted when the history exceeds the configured limit.
+     *
+     * @param metrics - The metrics snapshot to record
+     */
+    recordMetrics(metrics: WorkloadMetrics): void;
+    /**
+     * Evaluate current averaged metrics against the active policy and produce
+     * a scaling decision.
+     *
+     * Decision priority:
+     * 1. If cooldown is active, return `maintain`
+     * 2. If error rate exceeds threshold, scale up by 2
+     * 3. If queue-to-agent ratio exceeds threshold, scale up to meet demand
+     * 4. If idle ratio exceeds threshold, scale down by removing half the idle
+     * 5. Otherwise, maintain current count
+     *
+     * Target agent count is always clamped to `[minAgents, maxAgents]`.
+     *
+     * @returns The scaling decision (does not execute it)
+     */
+    evaluate(): ScalingDecision;
+    /**
+     * Execute a scaling decision, optionally delegating to an external executor.
+     *
+     * If the decision is `maintain`, the event is recorded but no executor is
+     * called. For `scale-up` or `scale-down`, the executor is called (if
+     * provided) and the internal agent count is updated on success.
+     *
+     * @param decision - The decision to execute
+     * @param executor - Optional callback to perform the actual scaling
+     * @returns The scaling event recording the outcome
+     */
+    execute(decision: ScalingDecision, executor?: ScaleExecutor): Promise<ScalingEvent>;
+    /**
+     * Replace the active scaling policy.
+     * Takes effect on the next {@link evaluate} call.
+     *
+     * @param policy - The new policy to apply
+     */
+    setPolicy(policy: ScalingPolicy): void;
+    /**
+     * Get a snapshot of the current scaling policy.
+     *
+     * @returns A copy of the active policy
+     */
+    getPolicy(): ScalingPolicy;
+    /**
+     * Get the current agent count tracked by this scaler.
+     */
+    getCurrentAgents(): number;
+    /**
+     * Get aggregated scaler statistics.
+     *
+     * @returns Current stats including counts, recent events, and last decision
+     */
+    getStats(): ScalerStats;
+    /**
+     * Get a copy of the full metrics history.
+     *
+     * @returns Array of recorded WorkloadMetrics snapshots
+     */
+    getMetricsHistory(): readonly WorkloadMetrics[];
+    /**
+     * Release internal buffers. The scaler should not be used after disposal.
+     */
+    dispose(): void;
+    /**
+     * Compute averaged metrics over the most recent `sampleWindowSize` samples.
+     * Returns zero-valued metrics if no samples have been recorded.
+     */
+    private getAverageMetrics;
+    /**
+     * Record a scaling event, evicting the oldest when the history cap is hit.
+     */
+    private recordEvent;
+}
+/**
+ * Create a new DynamicScaler instance.
+ *
+ * @param initialAgents - Starting agent count (defaults to 2)
+ * @param config - Optional partial config to override defaults
+ * @returns A new DynamicScaler instance
+ *
+ * @example
+ * ```typescript
+ * // Use all defaults
+ * const scaler = createDynamicScaler();
+ *
+ * // Start with 6 agents, custom history size
+ * const customScaler = createDynamicScaler(6, {
+ *   metricsHistorySize: 200,
+ * });
+ * ```
+ */
+export declare function createDynamicScaler(initialAgents?: number, config?: Partial<DynamicScalingConfig>): DynamicScaler;
+//# sourceMappingURL=dynamic-scaler.d.ts.map

package/v3/dist/coordination/dynamic-scaling/dynamic-scaler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-scaler.d.ts","sourceRoot":"","sources":["../../../src/coordination/dynamic-scaling/dynamic-scaler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,aAAa,EACb,YAAY,EACZ,WAAW,EACX,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAOjB;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,KACjB,OAAO,CAAC,OAAO,CAAC,CAAC;AAMtB;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAC,CAAkB;IAEvC;;;;;OAKG;gBAED,aAAa,GAAE,MAAU,EACzB,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC;IAWxC;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAW7C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,IAAI,eAAe;IAgG3B;;;;;;;;;;OAUG;IACG,OAAO,CACX,QAAQ,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,YAAY,CAAC;IA0DxB;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAItC;;;;OAIG;IACH,SAAS,IAAI,aAAa;IAQ1B;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,QAAQ,IAAI,WAAW;IAYvB;;;;OAIG;IACH,iBAAiB,IAAI,SAAS,eAAe,EAAE;IAQ/C;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,WAAW;CAMpB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GACrC,aAAa,CAEf"}