agentic-qe 3.7.21 → 3.8.0

package/dist/coordination/coherence-action-gate.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Coherence-Gated Agent Actions (Task 3.2, ADR-083)
+ *
+ * Evaluates agent actions through three stacked filters with
+ * heuristic scoring with CUSUM drift detection:
+ *   1. Structural filter: Action type familiarity and context completeness check
+ *   2. Shift filter: Confidence-risk alignment with CUSUM change detection
+ *   3. Evidence filter: Multiplicative context evidence accumulation score
+ *
+ * Decisions: PERMIT / DEFER / DENY
+ *   - PERMIT: all filters pass (scores above permit thresholds)
+ *   - DEFER: one or more filters marginal (needs human review)
+ *   - DENY: one or more filters clearly fail
+ *
+ * Advisory mode by default: logs decisions but does not block execution.
+ *
+ * TypeScript implementation (no native package exists for this —
+ * heuristic filters work well without native computation).
+ *
+ * @module coordination/coherence-action-gate
+ * @see ADR-083-coherence-gated-agent-actions.md
+ */
+/**
+ * An action that an agent intends to perform.
+ */
+export interface AgentAction {
+    /** Action type identifier */
+    type: string;
+    /** Domain the action belongs to */
+    domain: string;
+    /** Agent's confidence in the action (0-1) */
+    confidence: number;
+    /** Arbitrary context for the action */
+    context: Record<string, unknown>;
+    /** Risk classification */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+}
+/**
+ * Gate decision: PERMIT, DEFER, or DENY.
+ */
+export type GateDecision = 'PERMIT' | 'DEFER' | 'DENY';
+/**
+ * Full evaluation result from the three-filter pipeline.
+ */
+export interface GateEvaluation {
+    /** Final decision */
+    decision: GateDecision;
+    /** Structural filter score (0-1, higher = better fit) */
+    structuralScore: number;
+    /** Shift filter score (0-1, higher = less shift) */
+    shiftScore: number;
+    /** Evidence filter score (0-1, higher = more evidence) */
+    evidenceScore: number;
+    /** Weighted combined score (0-1) */
+    combinedScore: number;
+    /** Human-readable reasoning for the decision */
+    reasoning: string;
+    /** Whether this was advisory-only (logged, not enforced) */
+    advisory: boolean;
+}
+/**
+ * Configurable thresholds for the three filters.
+ */
+export interface ThresholdConfig {
+    /** Structural filter: minimum score to pass (default: 0.4) */
+    structuralPermit?: number;
+    /** Structural filter: below this score = DENY (default: 0.2) */
+    structuralDeny?: number;
+    /** Shift filter: minimum score to pass (default: 0.5) */
+    shiftPermit?: number;
+    /** Shift filter: below this score = DENY (default: 0.25) */
+    shiftDeny?: number;
+    /** Evidence filter: minimum score to pass (default: 0.5) */
+    evidencePermit?: number;
+    /** Evidence filter: below this score = DENY (default: 0.2) */
+    evidenceDeny?: number;
+    /** Combined score: minimum to PERMIT (default: 0.5) */
+    combinedPermit?: number;
+    /** Combined score: below this = DENY (default: 0.25) */
+    combinedDeny?: number;
+}
+/**
+ * Aggregate statistics for observability.
+ */
+export interface GateStats {
+    /** Total evaluations performed */
+    totalEvaluations: number;
+    /** Count of PERMIT decisions */
+    permitCount: number;
+    /** Count of DEFER decisions */
+    deferCount: number;
+    /** Count of DENY decisions */
+    denyCount: number;
+    /** Average combined score */
+    averageCombinedScore: number;
+    /** Average structural filter score */
+    averageStructuralScore: number;
+    /** Average shift filter score */
+    averageShiftScore: number;
+    /** Average evidence filter score */
+    averageEvidenceScore: number;
+    /** Whether advisory mode is active */
+    advisoryMode: boolean;
+}
+/**
+ * Internal resolved thresholds (all required).
+ */
+interface ResolvedThresholds {
+    structuralPermit: number;
+    structuralDeny: number;
+    shiftPermit: number;
+    shiftDeny: number;
+    evidencePermit: number;
+    evidenceDeny: number;
+    combinedPermit: number;
+    combinedDeny: number;
+}
+/**
+ * Three-filter coherence gate for agent action evaluation.
+ *
+ * Evaluates whether an agent action should proceed by running it through
+ * structural, shift, and evidence filters. Advisory mode by default.
+ *
+ * @example
+ * ```typescript
+ * const gate = new CoherenceActionGate();
+ * const evaluation = gate.evaluate({
+ *   type: 'generate-test',
+ *   domain: 'test-generation',
+ *   confidence: 0.85,
+ *   context: { filePath: 'src/service.ts' },
+ *   riskLevel: 'medium',
+ * });
+ * if (evaluation.decision === 'DENY') {
+ *   console.warn('Action denied:', evaluation.reasoning);
+ * }
+ * ```
+ */
+export declare class CoherenceActionGate {
+    private thresholds;
+    private readonly advisoryMode;
+    private nativeAvailable;
+    private evaluationHistory;
+    private permitCount;
+    private deferCount;
+    private denyCount;
+    private totalCombinedScore;
+    private totalStructuralScore;
+    private totalShiftScore;
+    private totalEvidenceScore;
+    private cusumHigh;
+    private cusumLow;
+    private cusumMean;
+    private cusumK;
+    private cusumH;
+    private cusumSampleCount;
+    private cusumAlertActive;
+    constructor(options?: {
+        advisory?: boolean;
+        thresholds?: ThresholdConfig;
+    });
+    /**
+     * Evaluate an agent action through the three-filter pipeline.
+     *
+     * @param action - The agent action to evaluate
+     * @returns Full evaluation with decision, scores, and reasoning
+     */
+    evaluate(action: AgentAction): GateEvaluation;
+    /**
+     * Get aggregate statistics for observability.
+     */
+    getStatistics(): GateStats;
+    /**
+     * Update thresholds at runtime.
+     *
+     * @param config - Partial threshold overrides
+     */
+    configureThresholds(config: ThresholdConfig): void;
+    /**
+     * Get the current threshold configuration.
+     */
+    getThresholds(): Readonly<ResolvedThresholds>;
+    /**
+     * Whether advisory mode is active.
+     */
+    isAdvisory(): boolean;
+    /**
+     * Get the evaluation history (bounded).
+     */
+    getEvaluationHistory(): GateEvaluation[];
+    /**
+     * Clear evaluation history and reset statistics.
+     */
+    resetStatistics(): void;
+    /**
+     * Reset CUSUM change detection state.
+     */
+    resetCusum(): void;
+    /**
+     * Structural filter: Action type familiarity and context completeness check.
+     *
+     * Considers:
+     * - Action type familiarity (known vs unknown action types)
+     * - Domain alignment (is the action appropriate for this domain?)
+     * - Context completeness (does the action have sufficient context?)
+     *
+     * Higher score = better structural fit.
+     */
+    private computeStructuralScore;
+    /**
+     * Shift filter: Confidence-risk alignment with CUSUM change detection.
+     *
+     * Considers:
+     * - Confidence level (low confidence suggests distributional shift)
+     * - Risk level alignment (high risk with low confidence = shift)
+     * - Context consistency (presence of contradictory signals)
+     * - CUSUM cumulative sum control chart for persistent drift detection
+     *
+     * Higher score = less distributional shift detected.
+     */
+    private computeShiftScore;
+    /**
+     * Evidence filter: Multiplicative context evidence accumulation score.
+     *
+     * Uses multiplicative accumulation where each piece of evidence
+     * compounds on the previous score. Multiple negative signals compound
+     * more aggressively than additive scoring.
+     *
+     * Considers:
+     * - Supporting evidence in context (test results, coverage data, etc.)
+     * - Evidence against (errors, failures, warnings)
+     * - Risk-level specific evidence requirements
+     *
+     * Higher score = more evidence supporting the action.
+     */
+    private computeEvidenceScore;
+    /**
+     * Determine the final PERMIT/DEFER/DENY decision from filter scores.
+     *
+     * Logic:
+     * - DENY if any individual filter is below its deny threshold
+     * - DENY if combined score is below combined deny threshold
+     * - PERMIT if all filters are above their permit thresholds AND
+     *   combined score is above combined permit threshold
+     * - DEFER otherwise (marginal - needs human review)
+     */
+    private computeDecision;
+    /**
+     * Build a human-readable reasoning string.
+     */
+    private buildReasoning;
+    /**
+     * Record an evaluation for statistics tracking.
+     */
+    private recordEvaluation;
+}
+/**
+ * Create a CoherenceActionGate instance.
+ *
+ * @param options - Optional configuration
+ * @returns A new CoherenceActionGate instance
+ */
+export declare function createCoherenceActionGate(options?: {
+    advisory?: boolean;
+    thresholds?: ThresholdConfig;
+}): CoherenceActionGate;
+/**
+ * Evaluate a task execution action through the coherence gate.
+ *
+ * This is the integration point called by the task executor. It checks
+ * the feature flag, creates an AgentAction from task metadata, and
+ * returns the evaluation result.
+ *
+ * @param taskType - The type of task being executed
+ * @param domain - The domain the task targets
+ * @param confidence - Confidence level (0-1)
+ * @param riskLevel - Risk classification
+ * @param context - Additional context
+ * @param gate - Optional pre-existing gate instance (for reuse)
+ * @returns The gate evaluation, or null if the feature flag is off
+ */
+export declare function evaluateTaskAction(taskType: string, domain: string, confidence: number, riskLevel: 'low' | 'medium' | 'high' | 'critical', context: Record<string, unknown>, gate?: CoherenceActionGate): GateEvaluation | null;
+export {};
+//# sourceMappingURL=coherence-action-gate.d.ts.map