monomind 1.19.0 → 2.0.0

package/packages/@monomind/guidance/dist/coherence.d.ts

@@ -1,233 +0,0 @@
-/**
- * Coherence Scheduler & Economic Governor
- *
- * Detects drift in agent behavior and enforces resource budgets.
- *
- * CoherenceScheduler:
- * - Computes a coherence score from violation rate, rework, and intent drift
- * - Maps scores to privilege levels (full, restricted, read-only, suspended)
- * - Tracks score history and provides human-readable recommendations
- *
- * EconomicGovernor:
- * - Tracks token usage, tool calls, storage, and time
- * - Checks budgets and emits alerts when thresholds are crossed
- * - Estimates remaining capacity and costs
- *
- * @module @monomind/guidance/coherence
- */
-import type { RunEvent, OptimizationMetrics } from './types.js';
-/**
- * Coherence score computed from recent run metrics and events
- */
-export interface CoherenceScore {
-    /** Overall coherence (0-1, 1 = perfectly coherent) */
-    overall: number;
-    /** Violation component (0-1, lower violations = higher score) */
-    violationComponent: number;
-    /** Rework component (0-1, lower rework = higher score) */
-    reworkComponent: number;
-    /** Drift component (0-1, consistent intents = higher score) */
-    driftComponent: number;
-    /** Timestamp when this score was computed */
-    timestamp: number;
-    /** Number of events evaluated in the window */
-    windowSize: number;
-}
-/**
- * Thresholds for privilege level determination
- */
-export interface CoherenceThresholds {
-    /** Below this overall score the agent is restricted to read-only */
-    readOnlyThreshold: number;
-    /** Below this overall score warnings are emitted */
-    warningThreshold: number;
-    /** Above this overall score the agent has full privileges */
-    healthyThreshold: number;
-    /** Above this overall score privilege escalation is allowed */
-    privilegeEscalationThreshold: number;
-}
-/**
- * Privilege level derived from a coherence score
- */
-export type PrivilegeLevel = 'full' | 'restricted' | 'read-only' | 'suspended';
-/**
- * Budget usage breakdown across all tracked dimensions
- */
-export interface BudgetUsage {
-    tokens: {
-        used: number;
-        limit: number;
-        percentage: number;
-    };
-    toolCalls: {
-        used: number;
-        limit: number;
-        percentage: number;
-    };
-    storage: {
-        usedBytes: number;
-        limitBytes: number;
-        percentage: number;
-    };
-    time: {
-        usedMs: number;
-        limitMs: number;
-        percentage: number;
-    };
-    cost: {
-        totalUsd: number;
-        limitUsd: number;
-        percentage: number;
-    };
-}
-export interface CoherenceSchedulerConfig {
-    thresholds?: Partial<CoherenceThresholds>;
-    windowSize?: number;
-    checkIntervalMs?: number;
-}
-/**
- * Computes coherence scores from run metrics and events, determines privilege
- * levels, and provides recommendations when drift is detected.
- */
-export declare class CoherenceScheduler {
-    private readonly thresholds;
-    private readonly windowSize;
-    private readonly checkIntervalMs;
-    private readonly scoreHistory;
-    private static readonly MAX_HISTORY;
-    constructor(config?: CoherenceSchedulerConfig);
-    /**
-     * Compute a coherence score from optimization metrics and recent events.
-     *
-     * Components:
-     * - violationComponent: 1 - (violationRate / 10) clamped to [0, 1]
-     * - reworkComponent: 1 - (reworkLines / 100) clamped to [0, 1]
-     * - driftComponent: intent consistency (fewer unique intents relative to window = higher)
-     * - overall: weighted average (0.4 * violation + 0.3 * rework + 0.3 * drift)
-     */
-    computeCoherence(metrics: OptimizationMetrics, recentEvents: RunEvent[]): CoherenceScore;
-    /**
-     * Determine the privilege level from a coherence score.
-     *
-     * - overall >= healthyThreshold (0.7): 'full'
-     * - overall >= warningThreshold (0.5): 'restricted'
-     * - overall >= readOnlyThreshold (0.3): 'read-only'
-     * - below readOnlyThreshold: 'suspended'
-     */
-    getPrivilegeLevel(score: CoherenceScore): PrivilegeLevel;
-    /**
-     * Return the last 100 coherence scores (most recent last).
-     */
-    getScoreHistory(): CoherenceScore[];
-    /**
-     * Whether the score indicates healthy coherence.
-     */
-    isHealthy(score: CoherenceScore): boolean;
-    /**
-     * Whether the score indicates drift (below warning threshold).
-     */
-    isDrifting(score: CoherenceScore): boolean;
-    /**
-     * Whether the score warrants restricting agent actions.
-     */
-    shouldRestrict(score: CoherenceScore): boolean;
-    /**
-     * Produce a human-readable recommendation based on the coherence score.
-     */
-    getRecommendation(score: CoherenceScore): string;
-    /**
-     * Get the configured check interval in milliseconds.
-     */
-    get interval(): number;
-    /**
-     * Get the configured thresholds.
-     */
-    getThresholds(): CoherenceThresholds;
-}
-export interface EconomicGovernorConfig {
-    tokenLimit?: number;
-    toolCallLimit?: number;
-    storageLimit?: number;
-    timeLimit?: number;
-    costPerToken?: number;
-    costPerToolCall?: number;
-    costLimit?: number;
-}
-interface ToolCallRecord {
-    toolName: string;
-    durationMs: number;
-    timestamp: number;
-}
-/**
- * Tracks resource consumption (tokens, tool calls, storage, time, cost)
- * and enforces budget limits with alerts.
- */
-export declare class EconomicGovernor {
-    private readonly config;
-    private tokensUsed;
-    private toolCallsUsed;
-    private storageUsed;
-    private readonly toolCallLog;
-    private readonly startTime;
-    private periodStart;
-    private static readonly ALERT_THRESHOLDS;
-    constructor(config?: EconomicGovernorConfig);
-    /**
-     * Record token consumption.
-     */
-    recordTokenUsage(count: number): void;
-    /**
-     * Record a tool call with its name and duration.
-     */
-    recordToolCall(toolName: string, durationMs: number): void;
-    /**
-     * Record storage usage in bytes.
-     */
-    recordStorageUsage(bytes: number): void;
-    /**
-     * Check whether current usage is within budget limits.
-     * Returns a summary with alerts for any limits that are near or exceeded.
-     */
-    checkBudget(): {
-        withinBudget: boolean;
-        usage: BudgetUsage;
-        alerts: string[];
-    };
-    /**
-     * Get a full usage summary across all tracked dimensions.
-     */
-    getUsageSummary(): BudgetUsage;
-    /**
-     * Reset all counters for a new billing/tracking period.
-     */
-    resetPeriod(): void;
-    /**
-     * Estimate remaining capacity before hitting limits.
-     */
-    estimateRemainingCapacity(): {
-        tokensRemaining: number;
-        callsRemaining: number;
-        timeRemainingMs: number;
-    };
-    /**
-     * Compute a cost estimate with a breakdown by category.
-     */
-    getCostEstimate(): {
-        totalCost: number;
-        breakdown: Record<string, number>;
-    };
-    /**
-     * Get the raw tool call log.
-     */
-    getToolCallLog(): ReadonlyArray<ToolCallRecord>;
-}
-/**
- * Create a CoherenceScheduler with optional configuration.
- */
-export declare function createCoherenceScheduler(config?: CoherenceSchedulerConfig): CoherenceScheduler;
-/**
- * Create an EconomicGovernor with optional configuration.
- */
-export declare function createEconomicGovernor(config?: EconomicGovernorConfig): EconomicGovernor;
-export {};
-//# sourceMappingURL=coherence.d.ts.map

package/packages/@monomind/guidance/dist/coherence.js

@@ -1,378 +0,0 @@
-/**
- * Coherence Scheduler & Economic Governor
- *
- * Detects drift in agent behavior and enforces resource budgets.
- *
- * CoherenceScheduler:
- * - Computes a coherence score from violation rate, rework, and intent drift
- * - Maps scores to privilege levels (full, restricted, read-only, suspended)
- * - Tracks score history and provides human-readable recommendations
- *
- * EconomicGovernor:
- * - Tracks token usage, tool calls, storage, and time
- * - Checks budgets and emits alerts when thresholds are crossed
- * - Estimates remaining capacity and costs
- *
- * @module @monomind/guidance/coherence
- */
-// ============================================================================
-// Default Configurations
-// ============================================================================
-const DEFAULT_THRESHOLDS = {
-    readOnlyThreshold: 0.3,
-    warningThreshold: 0.5,
-    healthyThreshold: 0.7,
-    privilegeEscalationThreshold: 0.9,
-};
-const DEFAULT_ECONOMIC_CONFIG = {
-    tokenLimit: 1_000_000,
-    toolCallLimit: 10_000,
-    storageLimit: 1_073_741_824, // 1 GiB
-    timeLimit: 3_600_000, // 1 hour
-    costPerToken: 0.000003, // $3 per million tokens
-    costPerToolCall: 0.0001,
-    costLimit: 10, // $10 USD
-};
-/**
- * Computes coherence scores from run metrics and events, determines privilege
- * levels, and provides recommendations when drift is detected.
- */
-export class CoherenceScheduler {
-    thresholds;
-    windowSize;
-    checkIntervalMs;
-    scoreHistory = [];
-    static MAX_HISTORY = 100;
-    constructor(config = {}) {
-        this.thresholds = { ...DEFAULT_THRESHOLDS, ...config.thresholds };
-        this.windowSize = config.windowSize ?? 20;
-        this.checkIntervalMs = config.checkIntervalMs ?? 30_000;
-    }
-    /**
-     * Compute a coherence score from optimization metrics and recent events.
-     *
-     * Components:
-     * - violationComponent: 1 - (violationRate / 10) clamped to [0, 1]
-     * - reworkComponent: 1 - (reworkLines / 100) clamped to [0, 1]
-     * - driftComponent: intent consistency (fewer unique intents relative to window = higher)
-     * - overall: weighted average (0.4 * violation + 0.3 * rework + 0.3 * drift)
-     */
-    computeCoherence(metrics, recentEvents) {
-        const window = recentEvents.slice(-this.windowSize);
-        const windowLen = window.length;
-        // Violation component: fewer violations per 10 tasks = better
-        const violationComponent = clamp(1 - metrics.violationRate / 10, 0, 1);
-        // Rework component: fewer rework lines on average = better
-        const reworkComponent = clamp(1 - metrics.reworkLines / 100, 0, 1);
-        // Drift component: consistent intents = better
-        // A single unique intent across N events means perfect consistency
-        let driftComponent;
-        if (windowLen === 0) {
-            driftComponent = 1; // No events, assume no drift
-        }
-        else {
-            const uniqueIntents = new Set(window.map(e => e.intent)).size;
-            // 1 unique intent / N events = score 1; N unique / N events = score approaches 0
-            driftComponent = clamp(1 - (uniqueIntents - 1) / Math.max(windowLen - 1, 1), 0, 1);
-        }
-        const overall = 0.4 * violationComponent +
-            0.3 * reworkComponent +
-            0.3 * driftComponent;
-        const score = {
-            overall,
-            violationComponent,
-            reworkComponent,
-            driftComponent,
-            timestamp: Date.now(),
-            windowSize: windowLen,
-        };
-        this.scoreHistory.push(score);
-        if (this.scoreHistory.length > CoherenceScheduler.MAX_HISTORY) {
-            this.scoreHistory.shift();
-        }
-        return score;
-    }
-    /**
-     * Determine the privilege level from a coherence score.
-     *
-     * - overall >= healthyThreshold (0.7): 'full'
-     * - overall >= warningThreshold (0.5): 'restricted'
-     * - overall >= readOnlyThreshold (0.3): 'read-only'
-     * - below readOnlyThreshold: 'suspended'
-     */
-    getPrivilegeLevel(score) {
-        if (score.overall >= this.thresholds.healthyThreshold) {
-            return 'full';
-        }
-        if (score.overall >= this.thresholds.warningThreshold) {
-            return 'restricted';
-        }
-        if (score.overall >= this.thresholds.readOnlyThreshold) {
-            return 'read-only';
-        }
-        return 'suspended';
-    }
-    /**
-     * Return the last 100 coherence scores (most recent last).
-     */
-    getScoreHistory() {
-        return [...this.scoreHistory];
-    }
-    /**
-     * Whether the score indicates healthy coherence.
-     */
-    isHealthy(score) {
-        return score.overall >= this.thresholds.healthyThreshold;
-    }
-    /**
-     * Whether the score indicates drift (below warning threshold).
-     */
-    isDrifting(score) {
-        return score.overall < this.thresholds.warningThreshold;
-    }
-    /**
-     * Whether the score warrants restricting agent actions.
-     */
-    shouldRestrict(score) {
-        return score.overall < this.thresholds.warningThreshold;
-    }
-    /**
-     * Produce a human-readable recommendation based on the coherence score.
-     */
-    getRecommendation(score) {
-        const level = this.getPrivilegeLevel(score);
-        const parts = [];
-        switch (level) {
-            case 'full':
-                parts.push(`Coherence is healthy at ${(score.overall * 100).toFixed(1)}%.`);
-                if (score.overall >= this.thresholds.privilegeEscalationThreshold) {
-                    parts.push('Privilege escalation is permitted.');
-                }
-                break;
-            case 'restricted':
-                parts.push(`Coherence is degraded at ${(score.overall * 100).toFixed(1)}%. Agent privileges are restricted.`);
-                break;
-            case 'read-only':
-                parts.push(`Coherence is critically low at ${(score.overall * 100).toFixed(1)}%. Agent is limited to read-only operations.`);
-                break;
-            case 'suspended':
-                parts.push(`Coherence has collapsed to ${(score.overall * 100).toFixed(1)}%. Agent operations are suspended.`);
-                break;
-        }
-        // Add component-specific advice
-        if (score.violationComponent < 0.5) {
-            parts.push(`High violation rate detected (component: ${(score.violationComponent * 100).toFixed(0)}%). Review and strengthen enforcement gates.`);
-        }
-        if (score.reworkComponent < 0.5) {
-            parts.push(`Excessive rework detected (component: ${(score.reworkComponent * 100).toFixed(0)}%). Consider more prescriptive guidance or smaller task scopes.`);
-        }
-        if (score.driftComponent < 0.5) {
-            parts.push(`Intent drift detected (component: ${(score.driftComponent * 100).toFixed(0)}%). Agent is switching between too many task types. Focus on a single objective.`);
-        }
-        return parts.join(' ');
-    }
-    /**
-     * Get the configured check interval in milliseconds.
-     */
-    get interval() {
-        return this.checkIntervalMs;
-    }
-    /**
-     * Get the configured thresholds.
-     */
-    getThresholds() {
-        return { ...this.thresholds };
-    }
-}
-/**
- * Tracks resource consumption (tokens, tool calls, storage, time, cost)
- * and enforces budget limits with alerts.
- */
-export class EconomicGovernor {
-    config;
-    tokensUsed = 0;
-    toolCallsUsed = 0;
-    storageUsed = 0;
-    toolCallLog = [];
-    startTime;
-    periodStart;
-    static ALERT_THRESHOLDS = [0.75, 0.9, 0.95, 1.0];
-    constructor(config = {}) {
-        this.config = {
-            tokenLimit: config.tokenLimit ?? DEFAULT_ECONOMIC_CONFIG.tokenLimit,
-            toolCallLimit: config.toolCallLimit ?? DEFAULT_ECONOMIC_CONFIG.toolCallLimit,
-            storageLimit: config.storageLimit ?? DEFAULT_ECONOMIC_CONFIG.storageLimit,
-            timeLimit: config.timeLimit ?? DEFAULT_ECONOMIC_CONFIG.timeLimit,
-            costPerToken: config.costPerToken ?? DEFAULT_ECONOMIC_CONFIG.costPerToken,
-            costPerToolCall: config.costPerToolCall ?? DEFAULT_ECONOMIC_CONFIG.costPerToolCall,
-            costLimit: config.costLimit ?? DEFAULT_ECONOMIC_CONFIG.costLimit,
-        };
-        this.startTime = Date.now();
-        this.periodStart = Date.now();
-    }
-    /**
-     * Record token consumption.
-     */
-    recordTokenUsage(count) {
-        this.tokensUsed += count;
-    }
-    /**
-     * Record a tool call with its name and duration.
-     */
-    recordToolCall(toolName, durationMs) {
-        this.toolCallsUsed++;
-        this.toolCallLog.push({
-            toolName,
-            durationMs,
-            timestamp: Date.now(),
-        });
-        // Cap log to prevent unbounded growth on long-lived governor instances
-        if (this.toolCallLog.length > 1000) {
-            this.toolCallLog.splice(0, this.toolCallLog.length - 1000);
-        }
-    }
-    /**
-     * Record storage usage in bytes.
-     */
-    recordStorageUsage(bytes) {
-        if (bytes < 0)
-            return;
-        this.storageUsed += bytes;
-    }
-    /**
-     * Check whether current usage is within budget limits.
-     * Returns a summary with alerts for any limits that are near or exceeded.
-     */
-    checkBudget() {
-        const usage = this.getUsageSummary();
-        const alerts = [];
-        // Check each dimension against alert thresholds
-        const dimensions = [
-            { name: 'tokens', percentage: usage.tokens.percentage },
-            { name: 'tool calls', percentage: usage.toolCalls.percentage },
-            { name: 'storage', percentage: usage.storage.percentage },
-            { name: 'time', percentage: usage.time.percentage },
-            { name: 'cost', percentage: usage.cost.percentage },
-        ];
-        let withinBudget = true;
-        for (const dim of dimensions) {
-            if (dim.percentage >= 100) {
-                alerts.push(`BUDGET EXCEEDED: ${dim.name} at ${dim.percentage.toFixed(1)}% of limit`);
-                withinBudget = false;
-            }
-            else if (dim.percentage >= 95) {
-                alerts.push(`CRITICAL: ${dim.name} at ${dim.percentage.toFixed(1)}% of limit`);
-            }
-            else if (dim.percentage >= 90) {
-                alerts.push(`WARNING: ${dim.name} at ${dim.percentage.toFixed(1)}% of limit`);
-            }
-            else if (dim.percentage >= 75) {
-                alerts.push(`NOTICE: ${dim.name} at ${dim.percentage.toFixed(1)}% of limit`);
-            }
-        }
-        return { withinBudget, usage, alerts };
-    }
-    /**
-     * Get a full usage summary across all tracked dimensions.
-     */
-    getUsageSummary() {
-        const elapsedMs = Date.now() - this.periodStart;
-        const costEstimate = this.getCostEstimate();
-        return {
-            tokens: {
-                used: this.tokensUsed,
-                limit: this.config.tokenLimit,
-                percentage: safePercentage(this.tokensUsed, this.config.tokenLimit),
-            },
-            toolCalls: {
-                used: this.toolCallsUsed,
-                limit: this.config.toolCallLimit,
-                percentage: safePercentage(this.toolCallsUsed, this.config.toolCallLimit),
-            },
-            storage: {
-                usedBytes: this.storageUsed,
-                limitBytes: this.config.storageLimit,
-                percentage: safePercentage(this.storageUsed, this.config.storageLimit),
-            },
-            time: {
-                usedMs: elapsedMs,
-                limitMs: this.config.timeLimit,
-                percentage: safePercentage(elapsedMs, this.config.timeLimit),
-            },
-            cost: {
-                totalUsd: costEstimate.totalCost,
-                limitUsd: this.config.costLimit,
-                percentage: safePercentage(costEstimate.totalCost, this.config.costLimit),
-            },
-        };
-    }
-    /**
-     * Reset all counters for a new billing/tracking period.
-     */
-    resetPeriod() {
-        this.tokensUsed = 0;
-        this.toolCallsUsed = 0;
-        this.storageUsed = 0;
-        this.toolCallLog.length = 0;
-        this.periodStart = Date.now();
-    }
-    /**
-     * Estimate remaining capacity before hitting limits.
-     */
-    estimateRemainingCapacity() {
-        const elapsedMs = Date.now() - this.periodStart;
-        return {
-            tokensRemaining: Math.max(0, this.config.tokenLimit - this.tokensUsed),
-            callsRemaining: Math.max(0, this.config.toolCallLimit - this.toolCallsUsed),
-            timeRemainingMs: Math.max(0, this.config.timeLimit - elapsedMs),
-        };
-    }
-    /**
-     * Compute a cost estimate with a breakdown by category.
-     */
-    getCostEstimate() {
-        const tokenCost = this.tokensUsed * this.config.costPerToken;
-        const toolCallCost = this.toolCallsUsed * this.config.costPerToolCall;
-        const breakdown = {
-            tokens: tokenCost,
-            toolCalls: toolCallCost,
-        };
-        return {
-            totalCost: tokenCost + toolCallCost,
-            breakdown,
-        };
-    }
-    /**
-     * Get the raw tool call log.
-     */
-    getToolCallLog() {
-        return this.toolCallLog;
-    }
-}
-// ============================================================================
-// Factory Functions
-// ============================================================================
-/**
- * Create a CoherenceScheduler with optional configuration.
- */
-export function createCoherenceScheduler(config) {
-    return new CoherenceScheduler(config);
-}
-/**
- * Create an EconomicGovernor with optional configuration.
- */
-export function createEconomicGovernor(config) {
-    return new EconomicGovernor(config);
-}
-// ============================================================================
-// Helpers
-// ============================================================================
-function clamp(value, min, max) {
-    return Math.min(max, Math.max(min, value));
-}
-function safePercentage(used, limit) {
-    if (limit <= 0)
-        return 100;
-    return (used / limit) * 100;
-}
-//# sourceMappingURL=coherence.js.map

package/packages/@monomind/guidance/dist/compiler.d.ts

@@ -1,87 +0,0 @@
-/**
- * Guidance Compiler
- *
- * Parses root CLAUDE.md and optional CLAUDE.local.md into a compiled policy bundle:
- * 1. A small always-loaded constitution (first 30-60 lines of invariants)
- * 2. A set of task-scoped rule shards tagged by intent, risk, domain, repo path, tool class
- * 3. A machine-readable manifest with rule IDs, triggers, and verifiers
- *
- * @module @monomind/guidance/compiler
- */
-import type { GuidanceRule, PolicyBundle, RiskClass } from './types.js';
-export interface CompilerConfig {
-    /** Maximum lines for constitution */
-    maxConstitutionLines: number;
-    /** Default risk class */
-    defaultRiskClass: RiskClass;
-    /** Default priority */
-    defaultPriority: number;
-    /** Auto-generate rule IDs for untagged rules */
-    autoGenerateIds: boolean;
-}
-export declare class GuidanceCompiler {
-    private config;
-    private nextAutoId;
-    constructor(config?: Partial<CompilerConfig>);
-    /**
-     * Compile guidance files into a policy bundle
-     */
-    compile(rootContent: string, localContent?: string): PolicyBundle;
-    /**
-     * Parse a guidance markdown file into rules
-     */
-    parseGuidanceFile(content: string, source: 'root' | 'local'): GuidanceRule[];
-    /**
-     * Extract rules from a content block
-     */
-    private extractRulesFromBlock;
-    /**
-     * Extract implicit rules from bullet points and paragraphs
-     */
-    private extractImplicitRules;
-    /**
-     * Check if text represents an actionable rule
-     */
-    private isActionableRule;
-    /**
-     * Parse a single rule from its text content
-     */
-    private parseRule;
-    /**
-     * Infer intents from rule text
-     */
-    private inferIntents;
-    /**
-     * Infer domains from rule text
-     */
-    private inferDomains;
-    /**
-     * Merge root and local rules, local overrides root for same ID
-     */
-    private mergeRules;
-    /**
-     * Build the constitution from constitution-class rules
-     */
-    private buildConstitution;
-    /**
-     * Build shards from non-constitution rules
-     */
-    private buildShards;
-    /**
-     * Build compact text for a shard
-     */
-    private buildCompactShardText;
-    /**
-     * Build the manifest
-     */
-    private buildManifest;
-    /**
-     * Hash content for change detection
-     */
-    private hashContent;
-}
-/**
- * Create a compiler instance
- */
-export declare function createCompiler(config?: Partial<CompilerConfig>): GuidanceCompiler;
-//# sourceMappingURL=compiler.d.ts.map