@iflow-mcp/jkheadley-instar 0.26.2

package/dist/monitoring/CommitmentSentinel.js

@@ -0,0 +1,251 @@
+/**
+ * Commitment Sentinel — LLM-powered scanner that detects unregistered commitments.
+ *
+ * Periodically scans Telegram topic messages to find commitments the agent
+ * made but didn't register via the CommitmentTracker API. Closes the gap
+ * between "the agent said it would" and "the system knows about it."
+ *
+ * Uses IntelligenceProvider (Haiku by default) for lightweight scanning.
+ * Tracks a high-water mark per topic so it only reads new messages each cycle.
+ *
+ * This is the "trust but verify" layer — instead of brittle string matching,
+ * an LLM reads the conversation and understands intent.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DegradationReporter } from './DegradationReporter.js';
+// ── Implementation ────────────────────────────────────────────────
+export class CommitmentSentinel {
+    config;
+    scanState;
+    scanStatePath;
+    messagesPath;
+    interval = null;
+    isScanning = false;
+    constructor(config) {
+        this.config = config;
+        this.scanStatePath = path.join(config.stateDir, 'state', 'commitment-sentinel.json');
+        this.messagesPath = path.join(config.stateDir, 'telegram-messages.jsonl');
+        this.scanState = this.loadScanState();
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────
+    start() {
+        if (this.interval)
+            return;
+        const intervalMs = this.config.scanIntervalMs ?? 300_000;
+        // First scan after a delay (let messages accumulate)
+        setTimeout(() => this.scan(), 60_000);
+        this.interval = setInterval(() => this.scan(), intervalMs);
+        this.interval.unref();
+        console.log(`[CommitmentSentinel] Started (every ${Math.round(intervalMs / 60_000)}m)`);
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+    // ── Scanning ───────────────────────────────────────────────────
+    /**
+     * Scan recent messages for unregistered commitments.
+     */
+    async scan() {
+        if (this.isScanning)
+            return 0;
+        this.isScanning = true;
+        try {
+            const messages = this.readNewMessages();
+            if (messages.length === 0) {
+                this.isScanning = false;
+                return 0;
+            }
+            // Group messages by topic for context
+            const byTopic = new Map();
+            for (const msg of messages) {
+                const existing = byTopic.get(msg.topicId) ?? [];
+                existing.push(msg);
+                byTopic.set(msg.topicId, existing);
+            }
+            let detected = 0;
+            for (const [topicId, topicMessages] of byTopic) {
+                // Look for conversation pairs: user request → agent response
+                const pairs = this.extractConversationPairs(topicMessages);
+                if (pairs.length === 0)
+                    continue;
+                // Ask LLM to identify commitments in these pairs
+                const commitments = await this.detectCommitments(pairs, topicId);
+                for (const c of commitments) {
+                    // Check if this commitment is already registered
+                    const existing = this.config.commitmentTracker.getActive();
+                    const isDuplicate = existing.some(e => e.topicId === topicId &&
+                        e.userRequest.toLowerCase().includes(c.userRequest.toLowerCase().slice(0, 30)));
+                    if (!isDuplicate) {
+                        this.config.commitmentTracker.record({
+                            ...c,
+                            topicId,
+                            source: 'sentinel',
+                        });
+                        detected++;
+                        console.log(`[CommitmentSentinel] Detected commitment in topic ${topicId}: "${c.userRequest}"`);
+                    }
+                }
+                // Update high-water mark for this topic
+                const maxMsgId = Math.max(...topicMessages.map(m => m.messageId));
+                this.scanState.topicHighWaterMark[topicId] = maxMsgId;
+            }
+            this.scanState.lastScanAt = new Date().toISOString();
+            this.saveScanState();
+            this.isScanning = false;
+            if (detected > 0) {
+                console.log(`[CommitmentSentinel] Scan complete: ${detected} new commitment(s) detected`);
+            }
+            return detected;
+        }
+        catch (err) {
+            this.isScanning = false;
+            DegradationReporter.getInstance().report({
+                feature: 'CommitmentSentinel.scan',
+                primary: 'Scan messages for unregistered commitments',
+                fallback: 'Scan skipped, returning 0 detected',
+                reason: `Scan error: ${err instanceof Error ? err.message : String(err)}`,
+                impact: 'Unregistered commitments may go undetected until next successful scan',
+            });
+            console.error(`[CommitmentSentinel] Scan error:`, err);
+            return 0;
+        }
+    }
+    // ── Message Reading ────────────────────────────────────────────
+    /**
+     * Read messages newer than the high-water mark from the JSONL log.
+     */
+    readNewMessages() {
+        if (!fs.existsSync(this.messagesPath))
+            return [];
+        try {
+            const content = fs.readFileSync(this.messagesPath, 'utf-8');
+            const lines = content.trim().split('\n');
+            const messages = [];
+            const maxPerScan = this.config.maxMessagesPerScan ?? 20;
+            // Read from the end to get the most recent messages
+            for (let i = lines.length - 1; i >= 0 && messages.length < maxPerScan * 10; i--) {
+                try {
+                    const msg = JSON.parse(lines[i]);
+                    if (!msg.messageId || !msg.topicId || !msg.text)
+                        continue;
+                    // Skip if we've already scanned past this message
+                    const hwm = this.scanState.topicHighWaterMark[msg.topicId] ?? 0;
+                    if (msg.messageId <= hwm)
+                        continue;
+                    messages.push(msg);
+                }
+                catch {
+                    // @silent-fallback-ok — skip individual malformed JSONL lines, other lines still parsed
+                }
+            }
+            return messages.reverse(); // Chronological order
+        }
+        catch (err) {
+            DegradationReporter.getInstance().report({
+                feature: 'CommitmentSentinel.readNewMessages',
+                primary: 'Read new Telegram messages from JSONL log',
+                fallback: 'Returning empty array, no messages processed',
+                reason: `Read failed: ${err instanceof Error ? err.message : String(err)}`,
+                impact: 'Commitment detection skipped for this cycle',
+            });
+            return [];
+        }
+    }
+    /**
+     * Extract user→agent conversation pairs from messages.
+     */
+    extractConversationPairs(messages) {
+        const pairs = [];
+        for (let i = 0; i < messages.length - 1; i++) {
+            if (messages[i].fromUser && !messages[i + 1].fromUser) {
+                pairs.push({
+                    user: messages[i].text,
+                    agent: messages[i + 1].text,
+                });
+            }
+        }
+        return pairs;
+    }
+    // ── LLM Detection ─────────────────────────────────────────────
+    /**
+     * Ask the LLM to detect commitments in conversation pairs.
+     */
+    async detectCommitments(pairs, topicId) {
+        if (pairs.length === 0)
+            return [];
+        const conversationText = pairs.map((p, i) => `--- Exchange ${i + 1} ---\nUser: ${p.user}\nAgent: ${p.agent}`).join('\n\n');
+        const prompt = `You are analyzing agent-user conversations to detect commitments the agent made.
+
+A "commitment" is when:
+1. The user asks the agent to change a setting, behavior, or perform a durable action
+2. The agent acknowledges and agrees to do it
+
+Types of commitments:
+- "config-change": User asks to change a setting (e.g., "turn off auto-updates", "set max sessions to 5")
+- "behavioral": User asks agent to change ongoing behavior (e.g., "always check with me before deploying", "stop sending daily reports")
+- "one-time-action": User asks agent to do something once (e.g., "deploy the latest version", "clean up old logs")
+
+Analyze these conversation exchanges and identify any commitments:
+
+${conversationText}
+
+Respond in JSON format. If no commitments found, return an empty array.
+Example response:
+[{"type":"config-change","userRequest":"turn off auto-updates","agentResponse":"Turning off auto-updates now","configPath":"updates.autoApply","configExpectedValue":false}]
+
+For behavioral commitments, include a "behavioralRule" field with a clear imperative rule.
+For one-time-action, omit configPath.
+
+IMPORTANT: Only return genuine commitments where the agent explicitly agreed. Do not flag questions, status updates, or informational responses. Return ONLY the JSON array, nothing else.`;
+        try {
+            const response = await this.config.intelligence.evaluate(prompt, {
+                model: 'fast',
+                maxTokens: 500,
+                temperature: 0,
+            });
+            // Parse JSON from response
+            const trimmed = response.trim();
+            // Handle case where LLM wraps in markdown code block
+            const jsonStr = trimmed.startsWith('```')
+                ? trimmed.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '')
+                : trimmed;
+            const parsed = JSON.parse(jsonStr);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed.filter((c) => c.type && c.userRequest && c.agentResponse &&
+                ['config-change', 'behavioral', 'one-time-action'].includes(c.type));
+        }
+        catch (err) {
+            // @silent-fallback-ok — LLM detection is best-effort; infrastructure enforcement still works
+            console.error(`[CommitmentSentinel] LLM detection failed:`, err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    // ── Persistence ────────────────────────────────────────────────
+    loadScanState() {
+        try {
+            if (fs.existsSync(this.scanStatePath)) {
+                return JSON.parse(fs.readFileSync(this.scanStatePath, 'utf-8'));
+            }
+        }
+        catch { /* start fresh */ }
+        return { topicHighWaterMark: {}, lastScanAt: null };
+    }
+    saveScanState() {
+        try {
+            const dir = path.dirname(this.scanStatePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${this.scanStatePath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpPath, JSON.stringify(this.scanState, null, 2));
+            fs.renameSync(tmpPath, this.scanStatePath);
+        }
+        catch {
+            // @silent-fallback-ok — scan state loss just means re-scanning some messages
+        }
+    }
+}
+//# sourceMappingURL=CommitmentSentinel.js.map

package/dist/monitoring/CommitmentSentinel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommitmentSentinel.js","sourceRoot":"","sources":["../../src/monitoring/CommitmentSentinel.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/CommitmentTracker.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Commitment Tracker — durable promise enforcement for agent infrastructure.
+ *
+ * When a user asks an agent to change something, the agent says "done" — but
+ * often the change doesn't stick. Sessions compact, configs revert, behavioral
+ * promises get forgotten. This module closes that gap.
+ *
+ * Three commitment types:
+ *   1. config-change  — enforced by code (auto-corrects config drift)
+ *   2. behavioral     — injected into every session via hooks
+ *   3. one-time-action — tracked until verified, then closed
+ *
+ * The CommitmentTracker runs as a server-side monitor. It does NOT depend on
+ * the LLM following instructions — it enforces commitments independently.
+ *
+ * Lifecycle:
+ *   record → verify → (auto-correct if needed) → monitor → resolve
+ */
+import { EventEmitter } from 'node:events';
+import type { LiveConfig } from '../config/LiveConfig.js';
+import type { ComponentHealth } from '../core/types.js';
+export type CommitmentType = 'config-change' | 'behavioral' | 'one-time-action';
+export type CommitmentStatus = 'pending' | 'verified' | 'violated' | 'expired' | 'withdrawn';
+export interface Commitment {
+    /** Unique identifier (CMT-xxx) */
+    id: string;
+    /** What the user asked for, in their words */
+    userRequest: string;
+    /** What the agent committed to */
+    agentResponse: string;
+    /** Commitment type determines verification strategy */
+    type: CommitmentType;
+    /** Current status */
+    status: CommitmentStatus;
+    /** When the commitment was made */
+    createdAt: string;
+    /** When the commitment was last verified */
+    lastVerifiedAt?: string;
+    /** When the commitment was fulfilled or violated */
+    resolvedAt?: string;
+    /** Resolution details */
+    resolution?: string;
+    /** Number of consecutive successful verifications */
+    verificationCount: number;
+    /** Number of violations detected */
+    violationCount: number;
+    /** Telegram topic ID where the commitment was made */
+    topicId?: number;
+    /** Source: 'agent' (self-registered) or 'sentinel' (detected by LLM scanner) */
+    source?: 'agent' | 'sentinel' | 'manual';
+    /** For config-change: the config path and expected value */
+    configPath?: string;
+    configExpectedValue?: unknown;
+    /** For behavioral: the rule text injected into sessions */
+    behavioralRule?: string;
+    /** For behavioral/one-time: when this commitment expires (null = forever) */
+    expiresAt?: string;
+    /** For one-time-action: verification method */
+    verificationMethod?: 'config-value' | 'file-exists' | 'manual';
+    /** For one-time-action with file-exists: the path to check */
+    verificationPath?: string;
+    /** Number of times auto-correction has fired for this commitment */
+    correctionCount: number;
+    /** Timestamps of recent corrections (for pattern detection) */
+    correctionHistory: string[];
+    /** Whether this commitment has been escalated as a potential bug */
+    escalated: boolean;
+    /** Escalation details */
+    escalationDetail?: string;
+}
+export interface CommitmentStore {
+    version: 1;
+    commitments: Commitment[];
+    lastModified: string;
+}
+export interface CommitmentVerificationReport {
+    timestamp: string;
+    active: number;
+    verified: number;
+    violated: number;
+    pending: number;
+    violations: Array<{
+        id: string;
+        userRequest: string;
+        detail: string;
+        autoCorrected: boolean;
+    }>;
+}
+export interface CommitmentTrackerConfig {
+    stateDir: string;
+    liveConfig: LiveConfig;
+    /** Check interval in ms. Default: 60_000 (1 minute) */
+    checkIntervalMs?: number;
+    /** Callback when a violation is detected */
+    onViolation?: (commitment: Commitment, detail: string) => void;
+    /** Callback when a commitment is verified for the first time */
+    onVerified?: (commitment: Commitment) => void;
+    /** Callback when repeated corrections suggest a bug. */
+    onEscalation?: (commitment: Commitment, detail: string) => void;
+    /** Number of corrections within the window that triggers escalation. Default: 3 */
+    escalationThreshold?: number;
+    /** Time window for counting corrections (ms). Default: 3_600_000 (1 hour) */
+    escalationWindowMs?: number;
+}
+export declare class CommitmentTracker extends EventEmitter {
+    private config;
+    private store;
+    private storePath;
+    private rulesPath;
+    private interval;
+    private nextId;
+    constructor(config: CommitmentTrackerConfig);
+    start(): void;
+    stop(): void;
+    /**
+     * Record a new commitment. Returns the created commitment.
+     */
+    record(input: {
+        userRequest: string;
+        agentResponse: string;
+        type: CommitmentType;
+        topicId?: number;
+        source?: 'agent' | 'sentinel' | 'manual';
+        configPath?: string;
+        configExpectedValue?: unknown;
+        behavioralRule?: string;
+        expiresAt?: string;
+        verificationMethod?: 'config-value' | 'file-exists' | 'manual';
+        verificationPath?: string;
+    }): Commitment;
+    /**
+     * Withdraw a commitment (user changed their mind).
+     */
+    withdraw(id: string, reason: string): boolean;
+    /**
+     * Get all active commitments (pending or verified, not expired).
+     */
+    getActive(): Commitment[];
+    /**
+     * Get all commitments (including resolved).
+     */
+    getAll(): Commitment[];
+    /**
+     * Get a single commitment by ID.
+     */
+    get(id: string): Commitment | null;
+    /**
+     * Run verification on all active commitments.
+     */
+    verify(): CommitmentVerificationReport;
+    /**
+     * Verify a single commitment. Returns null if commitment not found or not active.
+     */
+    verifyOne(id: string): {
+        passed: boolean;
+        detail: string;
+    } | null;
+    /**
+     * Get behavioral commitments formatted for session injection.
+     * This is what hooks read and inject into new sessions.
+     */
+    getBehavioralContext(): string;
+    /**
+     * Get ComponentHealth for integration with HealthChecker.
+     */
+    getHealth(): ComponentHealth;
+    private verifyConfigChange;
+    private verifyBehavioral;
+    private verifyOneTimeAction;
+    private attemptAutoCorrection;
+    /**
+     * Check if a commitment has been auto-corrected too many times,
+     * suggesting a bug rather than simple drift.
+     */
+    private checkForEscalation;
+    /**
+     * Write the commitment-rules.md file for hook injection.
+     */
+    private writeBehavioralRules;
+    private expireCommitments;
+    private loadStore;
+    private saveStore;
+    private computeNextId;
+    private deepEqual;
+}
+//# sourceMappingURL=CommitmentTracker.d.ts.map

package/dist/monitoring/CommitmentTracker.d.ts.map

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