monomind 1.19.0 → 2.0.1

package/packages/@monomind/guidance/dist/continue-gate.d.ts

@@ -1,214 +0,0 @@
-/**
- * Continue Gate - Long-Running Agent Control
- *
- * Evaluates whether a long-running agent should continue its next step.
- * Prevents runaway loops, budget exhaustion, and coherence degradation.
- *
- * Problem:
- * Current gates are tool-centric (PreToolUse, PreCommand, PreEdit).
- * Long-run loops are often internally generated — the agent keeps going
- * without a single obviously bad tool call. There is no gate for "should
- * this agent continue at all?"
- *
- * ContinueGate provides step-level evaluation with:
- * - Hard limits on consecutive steps without checkpoints
- * - Budget acceleration detection via linear regression
- * - Coherence threshold enforcement
- * - Uncertainty threshold enforcement
- * - Rework ratio tracking
- * - Automatic checkpoint intervals
- * - Cooldown between evaluations
- *
- * Decision types:
- * - continue: Agent may proceed to next step
- * - checkpoint: Agent must save state before continuing
- * - throttle: Agent should slow down or wait
- * - pause: Agent should stop and await human review
- * - stop: Agent must halt immediately
- *
- * @module @monomind/guidance/continue-gate
- */
-/**
- * Configuration for the ContinueGate
- */
-export interface ContinueGateConfig {
-    /** Hard limit on consecutive steps without checkpoint (default 100) */
-    maxConsecutiveSteps: number;
-    /** Maximum budget slope per step (cost acceleration threshold, default 0.02) */
-    maxBudgetSlopePerStep: number;
-    /** Minimum coherence score to continue (default 0.4) */
-    minCoherenceForContinue: number;
-    /** Maximum uncertainty score to continue (default 0.8) */
-    maxUncertaintyForContinue: number;
-    /** Maximum rework/total steps ratio (default 0.3) */
-    maxReworkRatio: number;
-    /** Force checkpoint every N steps (default 25) */
-    checkpointIntervalSteps: number;
-    /** Minimum time between evaluations in milliseconds (default 5000) */
-    cooldownMs: number;
-}
-/**
- * Context for a single step evaluation
- */
-export interface StepContext {
-    /** Current step number in the run */
-    stepNumber: number;
-    /** Total tokens consumed so far */
-    totalTokensUsed: number;
-    /** Total tool calls made so far */
-    totalToolCalls: number;
-    /** Number of steps that redid previous work */
-    reworkCount: number;
-    /** Coherence score from CoherenceScheduler (0-1) */
-    coherenceScore: number;
-    /** Uncertainty score from UncertaintyAggregator (0-1) */
-    uncertaintyScore: number;
-    /** Elapsed time in milliseconds since run start */
-    elapsedMs: number;
-    /** Step number of the last checkpoint */
-    lastCheckpointStep: number;
-    /** Remaining budget across all dimensions */
-    budgetRemaining: {
-        tokens: number;
-        toolCalls: number;
-        timeMs: number;
-    };
-    /** Recent evaluation decisions (last 10) */
-    recentDecisions: Array<{
-        step: number;
-        decision: 'allow' | 'deny' | 'warn';
-    }>;
-}
-/**
- * Decision outcome from the continue gate
- */
-export interface ContinueDecision {
-    /** The decision type */
-    decision: 'continue' | 'checkpoint' | 'throttle' | 'pause' | 'stop';
-    /** Human-readable reasons for the decision */
-    reasons: string[];
-    /** Computed metrics for this evaluation */
-    metrics: {
-        /** Budget acceleration rate (tokens per step slope) */
-        budgetSlope: number;
-        /** Ratio of rework steps to total steps */
-        reworkRatio: number;
-        /** Steps until next required checkpoint */
-        stepsUntilCheckpoint: number;
-        /** Coherence health level */
-        coherenceLevel: 'healthy' | 'degraded' | 'critical';
-        /** Uncertainty level */
-        uncertaintyLevel: 'low' | 'moderate' | 'high' | 'extreme';
-    };
-    /** Recommended action for the agent */
-    recommendedAction?: string;
-}
-/**
- * Gate that evaluates whether a long-running agent should continue.
- *
- * Prevents runaway execution by checking:
- * - Step limits
- * - Budget exhaustion and acceleration
- * - Coherence degradation
- * - Uncertainty thresholds
- * - Rework ratios
- * - Checkpoint intervals
- *
- * Maintains history of evaluations and provides aggregate statistics.
- */
-export declare class ContinueGate {
-    private readonly config;
-    private readonly history;
-    private lastEvaluationTime;
-    private readonly tokenHistory;
-    constructor(config?: Partial<ContinueGateConfig>);
-    /**
-     * Evaluate whether the agent should continue.
-     *
-     * Applies decision logic in priority order:
-     * 1. Coherence below threshold → stop
-     * 2. Step limit exceeded → stop
-     * 3. Budget exhausted → stop
-     * 4. High rework ratio → pause
-     * 5. High uncertainty → pause
-     * 6. Budget acceleration → throttle
-     * 7. Checkpoint interval reached → checkpoint
-     * 8. Otherwise → continue
-     *
-     * @param context - Current step context
-     * @returns Decision with reasons and metrics
-     */
-    evaluate(context: StepContext): ContinueDecision;
-    /**
-     * Evaluate and record the decision in history.
-     *
-     * This method also checks the cooldown period — if called too soon
-     * after the last evaluation, it returns a 'continue' decision without
-     * full evaluation to prevent excessive overhead.
-     *
-     * @param context - Current step context
-     * @returns Decision with reasons and metrics
-     */
-    evaluateWithHistory(context: StepContext): ContinueDecision;
-    /**
-     * Get the full evaluation history.
-     *
-     * Returns up to MAX_HISTORY_SIZE most recent evaluations.
-     *
-     * @returns Array of evaluation records ordered oldest to newest
-     */
-    getHistory(): Array<{
-        step: number;
-        decision: ContinueDecision;
-        timestamp: number;
-    }>;
-    /**
-     * Get aggregate statistics across all evaluations.
-     *
-     * @returns Statistics including total evaluations, decision counts, and average budget slope
-     */
-    getStats(): {
-        totalEvaluations: number;
-        decisions: Record<string, number>;
-        averageBudgetSlope: number;
-    };
-    /**
-     * Reset all internal state.
-     *
-     * Clears history, token tracking, and last evaluation time.
-     */
-    reset(): void;
-    /**
-     * Get the current configuration.
-     */
-    getConfig(): ContinueGateConfig;
-    /**
-     * Compute the budget slope (rate of token consumption per step)
-     * using linear regression on the last N steps.
-     *
-     * Returns the slope coefficient (tokens per step). A positive slope
-     * indicates increasing token usage. A slope above the configured
-     * threshold indicates budget acceleration.
-     */
-    private computeBudgetSlope;
-    /**
-     * Map coherence score to a health level.
-     */
-    private getCoherenceLevel;
-    /**
-     * Map uncertainty score to a level.
-     */
-    private getUncertaintyLevel;
-    /**
-     * Create a standardized decision object.
-     */
-    private createDecision;
-}
-/**
- * Create a ContinueGate instance with optional configuration.
- *
- * @param config - Partial configuration; unspecified values use defaults
- * @returns A fresh ContinueGate instance
- */
-export declare function createContinueGate(config?: Partial<ContinueGateConfig>): ContinueGate;
-//# sourceMappingURL=continue-gate.d.ts.map

package/packages/@monomind/guidance/dist/continue-gate.js

@@ -1,353 +0,0 @@
-/**
- * Continue Gate - Long-Running Agent Control
- *
- * Evaluates whether a long-running agent should continue its next step.
- * Prevents runaway loops, budget exhaustion, and coherence degradation.
- *
- * Problem:
- * Current gates are tool-centric (PreToolUse, PreCommand, PreEdit).
- * Long-run loops are often internally generated — the agent keeps going
- * without a single obviously bad tool call. There is no gate for "should
- * this agent continue at all?"
- *
- * ContinueGate provides step-level evaluation with:
- * - Hard limits on consecutive steps without checkpoints
- * - Budget acceleration detection via linear regression
- * - Coherence threshold enforcement
- * - Uncertainty threshold enforcement
- * - Rework ratio tracking
- * - Automatic checkpoint intervals
- * - Cooldown between evaluations
- *
- * Decision types:
- * - continue: Agent may proceed to next step
- * - checkpoint: Agent must save state before continuing
- * - throttle: Agent should slow down or wait
- * - pause: Agent should stop and await human review
- * - stop: Agent must halt immediately
- *
- * @module @monomind/guidance/continue-gate
- */
-// ============================================================================
-// Default Configuration
-// ============================================================================
-const DEFAULT_CONFIG = {
-    maxConsecutiveSteps: 100,
-    maxBudgetSlopePerStep: 0.02,
-    minCoherenceForContinue: 0.4,
-    maxUncertaintyForContinue: 0.8,
-    maxReworkRatio: 0.3,
-    checkpointIntervalSteps: 25,
-    cooldownMs: 5000,
-};
-const MAX_HISTORY_SIZE = 10000;
-const SLOPE_WINDOW_SIZE = 10; // Number of recent steps to use for budget slope calculation
-// ============================================================================
-// ContinueGate
-// ============================================================================
-/**
- * Gate that evaluates whether a long-running agent should continue.
- *
- * Prevents runaway execution by checking:
- * - Step limits
- * - Budget exhaustion and acceleration
- * - Coherence degradation
- * - Uncertainty thresholds
- * - Rework ratios
- * - Checkpoint intervals
- *
- * Maintains history of evaluations and provides aggregate statistics.
- */
-export class ContinueGate {
-    config;
-    history = [];
-    lastEvaluationTime = 0;
-    tokenHistory = [];
-    constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
-    }
-    /**
-     * Evaluate whether the agent should continue.
-     *
-     * Applies decision logic in priority order:
-     * 1. Coherence below threshold → stop
-     * 2. Step limit exceeded → stop
-     * 3. Budget exhausted → stop
-     * 4. High rework ratio → pause
-     * 5. High uncertainty → pause
-     * 6. Budget acceleration → throttle
-     * 7. Checkpoint interval reached → checkpoint
-     * 8. Otherwise → continue
-     *
-     * @param context - Current step context
-     * @returns Decision with reasons and metrics
-     */
-    evaluate(context) {
-        const now = Date.now();
-        const reasons = [];
-        // Track token usage for slope calculation
-        this.tokenHistory.push({
-            step: context.stepNumber,
-            tokens: context.totalTokensUsed,
-        });
-        if (this.tokenHistory.length > SLOPE_WINDOW_SIZE) {
-            this.tokenHistory.shift();
-        }
-        // Compute metrics
-        const budgetSlope = this.computeBudgetSlope();
-        const reworkRatio = context.stepNumber > 0
-            ? context.reworkCount / context.stepNumber
-            : 0;
-        const stepsUntilCheckpoint = this.config.checkpointIntervalSteps -
-            (context.stepNumber - context.lastCheckpointStep);
-        const coherenceLevel = this.getCoherenceLevel(context.coherenceScore);
-        const uncertaintyLevel = this.getUncertaintyLevel(context.uncertaintyScore);
-        const metrics = {
-            budgetSlope,
-            reworkRatio,
-            stepsUntilCheckpoint,
-            coherenceLevel,
-            uncertaintyLevel,
-        };
-        // Decision logic (priority order)
-        // 1. Coherence below threshold → stop
-        if (context.coherenceScore < this.config.minCoherenceForContinue) {
-            reasons.push(`Coherence below threshold (${context.coherenceScore.toFixed(2)} < ${this.config.minCoherenceForContinue})`);
-            return this.createDecision('stop', reasons, metrics, 'Halt execution and review coherence issues');
-        }
-        // 2. Step limit exceeded → stop
-        if (context.stepNumber >= this.config.maxConsecutiveSteps &&
-            context.stepNumber - context.lastCheckpointStep >= this.config.checkpointIntervalSteps) {
-            reasons.push(`Step limit exceeded (${context.stepNumber} >= ${this.config.maxConsecutiveSteps}) without recent checkpoint`);
-            return this.createDecision('stop', reasons, metrics, 'Create checkpoint and review progress');
-        }
-        // 3. Budget exhausted → stop
-        if (context.budgetRemaining.tokens <= 0 ||
-            context.budgetRemaining.toolCalls <= 0 ||
-            context.budgetRemaining.timeMs <= 0) {
-            const exhausted = [];
-            if (context.budgetRemaining.tokens <= 0)
-                exhausted.push('tokens');
-            if (context.budgetRemaining.toolCalls <= 0)
-                exhausted.push('tool calls');
-            if (context.budgetRemaining.timeMs <= 0)
-                exhausted.push('time');
-            reasons.push(`Budget exhausted: ${exhausted.join(', ')}`);
-            return this.createDecision('stop', reasons, metrics, 'Increase budget or simplify task scope');
-        }
-        // 4. High rework ratio → pause
-        if (reworkRatio > this.config.maxReworkRatio) {
-            reasons.push(`Rework ratio too high (${(reworkRatio * 100).toFixed(1)}% > ${(this.config.maxReworkRatio * 100).toFixed(1)}%)`);
-            return this.createDecision('pause', reasons, metrics, 'Review recent work for repeated errors or unclear objectives');
-        }
-        // 5. High uncertainty → pause
-        if (context.uncertaintyScore > this.config.maxUncertaintyForContinue) {
-            reasons.push(`Uncertainty too high (${context.uncertaintyScore.toFixed(2)} > ${this.config.maxUncertaintyForContinue})`);
-            return this.createDecision('pause', reasons, metrics, 'Resolve uncertain beliefs or gather more evidence before continuing');
-        }
-        // 6. Budget acceleration → throttle
-        if (budgetSlope > this.config.maxBudgetSlopePerStep) {
-            reasons.push(`Budget acceleration detected (slope: ${budgetSlope.toFixed(4)} > ${this.config.maxBudgetSlopePerStep})`);
-            return this.createDecision('throttle', reasons, metrics, 'Slow down execution or optimize token usage');
-        }
-        // 7. Checkpoint interval reached → checkpoint
-        if (stepsUntilCheckpoint <= 0) {
-            reasons.push(`Checkpoint interval reached (${context.stepNumber - context.lastCheckpointStep} >= ${this.config.checkpointIntervalSteps})`);
-            return this.createDecision('checkpoint', reasons, metrics, 'Save current state before continuing');
-        }
-        // 8. Otherwise → continue
-        reasons.push('All checks passed');
-        return this.createDecision('continue', reasons, metrics);
-    }
-    /**
-     * Evaluate and record the decision in history.
-     *
-     * This method also checks the cooldown period — if called too soon
-     * after the last evaluation, it returns a 'continue' decision without
-     * full evaluation to prevent excessive overhead.
-     *
-     * @param context - Current step context
-     * @returns Decision with reasons and metrics
-     */
-    evaluateWithHistory(context) {
-        const now = Date.now();
-        // Cooldown check — but always evaluate critical stop conditions
-        // to prevent agents from timing steps to bypass safety checks
-        if (now - this.lastEvaluationTime < this.config.cooldownMs) {
-            // Even during cooldown, check hard-stop conditions
-            if (context.coherenceScore < this.config.minCoherenceForContinue) {
-                return this.createDecision('stop', ['Coherence below threshold (checked during cooldown)'], { budgetSlope: 0, reworkRatio: 0, stepsUntilCheckpoint: 0, coherenceLevel: 'critical', uncertaintyLevel: 'low' }, 'Halt execution and review coherence issues');
-            }
-            if (context.budgetRemaining.tokens <= 0 || context.budgetRemaining.toolCalls <= 0 || context.budgetRemaining.timeMs <= 0) {
-                return this.createDecision('stop', ['Budget exhausted (checked during cooldown)'], { budgetSlope: 0, reworkRatio: 0, stepsUntilCheckpoint: 0, coherenceLevel: 'healthy', uncertaintyLevel: 'low' }, 'Increase budget or simplify task scope');
-            }
-            // Non-critical checks can be skipped during cooldown
-            return {
-                decision: 'continue',
-                reasons: ['Cooldown period active; skipping full evaluation'],
-                metrics: {
-                    budgetSlope: 0,
-                    reworkRatio: 0,
-                    stepsUntilCheckpoint: 0,
-                    coherenceLevel: this.getCoherenceLevel(context.coherenceScore),
-                    uncertaintyLevel: this.getUncertaintyLevel(context.uncertaintyScore),
-                },
-            };
-        }
-        this.lastEvaluationTime = now;
-        const decision = this.evaluate(context);
-        // Record in history
-        const record = {
-            step: context.stepNumber,
-            decision,
-            timestamp: now,
-            tokensUsed: context.totalTokensUsed,
-        };
-        this.history.push(record);
-        // Evict oldest if exceeding max size
-        if (this.history.length > MAX_HISTORY_SIZE) {
-            this.history.shift();
-        }
-        return decision;
-    }
-    /**
-     * Get the full evaluation history.
-     *
-     * Returns up to MAX_HISTORY_SIZE most recent evaluations.
-     *
-     * @returns Array of evaluation records ordered oldest to newest
-     */
-    getHistory() {
-        return this.history.map(r => ({
-            step: r.step,
-            decision: { ...r.decision },
-            timestamp: r.timestamp,
-        }));
-    }
-    /**
-     * Get aggregate statistics across all evaluations.
-     *
-     * @returns Statistics including total evaluations, decision counts, and average budget slope
-     */
-    getStats() {
-        const decisions = {
-            continue: 0,
-            checkpoint: 0,
-            throttle: 0,
-            pause: 0,
-            stop: 0,
-        };
-        let totalSlope = 0;
-        let slopeCount = 0;
-        for (const record of this.history) {
-            decisions[record.decision.decision]++;
-            totalSlope += record.decision.metrics.budgetSlope;
-            slopeCount++;
-        }
-        return {
-            totalEvaluations: this.history.length,
-            decisions,
-            averageBudgetSlope: slopeCount > 0 ? totalSlope / slopeCount : 0,
-        };
-    }
-    /**
-     * Reset all internal state.
-     *
-     * Clears history, token tracking, and last evaluation time.
-     */
-    reset() {
-        this.history.length = 0;
-        this.tokenHistory.length = 0;
-        this.lastEvaluationTime = 0;
-    }
-    /**
-     * Get the current configuration.
-     */
-    getConfig() {
-        return { ...this.config };
-    }
-    // =========================================================================
-    // Private Helpers
-    // =========================================================================
-    /**
-     * Compute the budget slope (rate of token consumption per step)
-     * using linear regression on the last N steps.
-     *
-     * Returns the slope coefficient (tokens per step). A positive slope
-     * indicates increasing token usage. A slope above the configured
-     * threshold indicates budget acceleration.
-     */
-    computeBudgetSlope() {
-        if (this.tokenHistory.length < 2) {
-            // Need at least 2 points for regression
-            return 0;
-        }
-        const n = this.tokenHistory.length;
-        let sumX = 0;
-        let sumY = 0;
-        let sumXY = 0;
-        let sumXX = 0;
-        for (const point of this.tokenHistory) {
-            const x = point.step;
-            const y = point.tokens;
-            sumX += x;
-            sumY += y;
-            sumXY += x * y;
-            sumXX += x * x;
-        }
-        // Linear regression: slope = (n*sumXY - sumX*sumY) / (n*sumXX - sumX*sumX)
-        const denominator = n * sumXX - sumX * sumX;
-        if (denominator === 0) {
-            // All x values are the same (shouldn't happen, but guard)
-            return 0;
-        }
-        const slope = (n * sumXY - sumX * sumY) / denominator;
-        return slope;
-    }
-    /**
-     * Map coherence score to a health level.
-     */
-    getCoherenceLevel(score) {
-        if (score >= 0.7)
-            return 'healthy';
-        if (score >= 0.4)
-            return 'degraded';
-        return 'critical';
-    }
-    /**
-     * Map uncertainty score to a level.
-     */
-    getUncertaintyLevel(score) {
-        if (score <= 0.3)
-            return 'low';
-        if (score <= 0.6)
-            return 'moderate';
-        if (score <= 0.8)
-            return 'high';
-        return 'extreme';
-    }
-    /**
-     * Create a standardized decision object.
-     */
-    createDecision(decision, reasons, metrics, recommendedAction) {
-        return {
-            decision,
-            reasons,
-            metrics,
-            recommendedAction,
-        };
-    }
-}
-// ============================================================================
-// Factory Function
-// ============================================================================
-/**
- * Create a ContinueGate instance with optional configuration.
- *
- * @param config - Partial configuration; unspecified values use defaults
- * @returns A fresh ContinueGate instance
- */
-export function createContinueGate(config) {
-    return new ContinueGate(config);
-}
-//# sourceMappingURL=continue-gate.js.map

package/packages/@monomind/guidance/dist/crypto-utils.d.ts

@@ -1,17 +0,0 @@
-/**
- * Shared Cryptographic Utilities
- *
- * Centralises timing-safe comparison so every module that verifies
- * HMAC signatures uses the same constant-time implementation.
- *
- * @module @monomind/guidance/crypto-utils
- */
-/**
- * Constant-time string comparison to prevent timing attacks on HMAC signatures.
- *
- * Delegates to Node.js `crypto.timingSafeEqual` via `Buffer.from` for
- * encoding-safe comparison. Falls back to a manual XOR loop when the
- * buffers have different byte lengths (which the native function rejects).
- */
-export declare function timingSafeEqual(a: string, b: string): boolean;
-//# sourceMappingURL=crypto-utils.d.ts.map

package/packages/@monomind/guidance/dist/crypto-utils.js

@@ -1,24 +0,0 @@
-/**
- * Shared Cryptographic Utilities
- *
- * Centralises timing-safe comparison so every module that verifies
- * HMAC signatures uses the same constant-time implementation.
- *
- * @module @monomind/guidance/crypto-utils
- */
-import { timingSafeEqual as nodeTimingSafeEqual } from 'node:crypto';
-/**
- * Constant-time string comparison to prevent timing attacks on HMAC signatures.
- *
- * Delegates to Node.js `crypto.timingSafeEqual` via `Buffer.from` for
- * encoding-safe comparison. Falls back to a manual XOR loop when the
- * buffers have different byte lengths (which the native function rejects).
- */
-export function timingSafeEqual(a, b) {
-    const bufA = Buffer.from(a, 'utf-8');
-    const bufB = Buffer.from(b, 'utf-8');
-    if (bufA.length !== bufB.length)
-        return false;
-    return nodeTimingSafeEqual(bufA, bufB);
-}
-//# sourceMappingURL=crypto-utils.js.map