@iflow-mcp/jkheadley-instar 0.26.2

package/dist/monitoring/SystemReviewer.d.ts

@@ -0,0 +1,243 @@
+/**
+ * System Reviewer (`instar doctor`) — functional verification for agent infrastructure.
+ *
+ * The existing monitoring (HealthChecker, CoherenceMonitor, etc.) tells us if the
+ * engine is running. The SystemReviewer tells us if the car can drive.
+ *
+ * Runs lightweight probes that verify features work end-to-end at runtime.
+ * Distinct from unit tests (build-time), health checks (liveness), and
+ * integration tests (wiring). Probes test actual feature functionality.
+ *
+ * Key design decisions (from spec review):
+ *   - Startup sweep: deletes orphaned __probe_* artifacts on init
+ *   - Dead-letter fallback: file-append error path independent of all monitored infra
+ *   - Own timer: does NOT depend on the scheduler (which it tests)
+ *   - History persistence: JSONL file survives restarts for trend analysis
+ *   - Concurrency: parallel within tier, serial for same serialGroup
+ *   - Feedback: opt-in only (autoSubmitFeedback defaults to false)
+ *
+ * Born from the insight: "A system can be healthy while being broken."
+ */
+import { EventEmitter } from 'node:events';
+export interface ProbeResult {
+    /** Probe identifier */
+    probeId: string;
+    /** Human-readable name */
+    name: string;
+    /** Which tier this probe belongs to */
+    tier: 1 | 2 | 3 | 4 | 5;
+    /** Pass or fail */
+    passed: boolean;
+    /** What was tested */
+    description: string;
+    /** How long the probe took (ms) */
+    durationMs: number;
+    /** On failure: what went wrong */
+    error?: string;
+    /** On failure: the full error stack */
+    stack?: string;
+    /** On failure: what was expected vs. what happened */
+    expected?: string;
+    actual?: string;
+    /** On failure: suggested remediation steps */
+    remediation?: string[];
+    /** Probe-specific diagnostic data */
+    diagnostics?: Record<string, unknown>;
+}
+export interface ReviewReport {
+    /** When the review ran */
+    timestamp: string;
+    /** Overall result */
+    status: 'all-clear' | 'degraded' | 'critical';
+    /** Probes that ran */
+    results: ProbeResult[];
+    /** Probes that were skipped (prerequisites not met) */
+    skipped: Array<{
+        probeId: string;
+        reason: string;
+    }>;
+    /** Aggregate stats */
+    stats: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        durationMs: number;
+    };
+    /** For failed probes: structured summary for feedback submission */
+    failureSummary?: string;
+}
+export interface ReviewTrend {
+    /** How many reviews in the analysis window */
+    window: number;
+    /** Is health score improving, stable, or declining? */
+    direction: 'improving' | 'stable' | 'declining';
+    /** Probes that are consistently failing (3+ consecutive) */
+    persistentFailures: string[];
+    /** Probes that recently started failing */
+    newFailures: string[];
+    /** Probes that recently recovered */
+    recovered: string[];
+}
+export interface Probe {
+    /** Unique probe identifier (namespaced, e.g., 'instar.session.list') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Criticality tier (1 = most critical) */
+    tier: 1 | 2 | 3 | 4 | 5;
+    /** Which feature/module this probes */
+    feature: string;
+    /**
+     * Serialization group. Probes in the same group run sequentially
+     * to avoid resource contention (e.g., SQLite write locks).
+     * Probes in different groups run concurrently within a tier.
+     */
+    serialGroup?: string;
+    /** Per-probe timeout override (ms). Falls back to config.probeTimeoutMs. */
+    timeoutMs?: number;
+    /**
+     * Whether this probe requires specific infrastructure to be active.
+     * Probes with unmet prerequisites are skipped (not failed).
+     */
+    prerequisites: () => boolean;
+    /** Run the probe. Must clean up after itself. */
+    run: () => Promise<ProbeResult>;
+}
+export interface SystemReviewerConfig {
+    /** Whether the system reviewer is enabled */
+    enabled: boolean;
+    /** How often to run a full review (ms). Default: 6 hours */
+    scheduleMs: number;
+    /** Which tiers to include in scheduled runs */
+    scheduledTiers: number[];
+    /** Maximum time for a single probe (ms) */
+    probeTimeoutMs: number;
+    /** Maximum time for a full review run (ms) */
+    reviewTimeoutMs: number;
+    /** How many past reports to keep */
+    historyLimit: number;
+    /** Whether to auto-submit failures as feedback (requires feedbackConsentGiven) */
+    autoSubmitFeedback: boolean;
+    /** Whether the operator has explicitly consented to feedback submission */
+    feedbackConsentGiven: boolean;
+    /** Whether to send Telegram alerts for critical failures */
+    alertOnCritical: boolean;
+    /** Cooldown between repeated alerts for same probe (ms) */
+    alertCooldownMs: number;
+    /** Probes to skip (by probe ID) */
+    disabledProbes: string[];
+}
+export interface ReviewOptions {
+    tiers?: number[];
+    probeIds?: string[];
+    dryRun?: boolean;
+}
+export interface SystemReviewerEvents {
+    'review:complete': (report: ReviewReport) => void;
+    'review:probe-failed': (result: ProbeResult) => void;
+    'review:error': (error: Error) => void;
+}
+export declare const DEFAULT_SYSTEM_REVIEWER_CONFIG: SystemReviewerConfig;
+export interface SystemReviewerDeps {
+    stateDir: string;
+    /** Optional: submit feedback items */
+    submitFeedback?: (item: {
+        type: 'bug';
+        title: string;
+        description: string;
+        agentName: string;
+        instarVersion: string;
+        nodeVersion: string;
+    }) => Promise<unknown>;
+    /** Optional: send Telegram alert */
+    sendAlert?: (topicId: number | undefined, text: string) => Promise<unknown>;
+    /** Optional: redact secrets from strings */
+    redactSecrets?: (text: string) => string;
+}
+export declare class SystemReviewer extends EventEmitter {
+    private probes;
+    private history;
+    private config;
+    private deps;
+    private historyFile;
+    private deadLetterFile;
+    private reviewInProgress;
+    private timer;
+    private lastAlertTimes;
+    constructor(config: Partial<SystemReviewerConfig>, deps: SystemReviewerDeps);
+    /** Register a probe */
+    register(probe: Probe): void;
+    /** Register multiple probes */
+    registerAll(probes: Probe[]): void;
+    /** Get all registered probes with their status */
+    getProbes(): Array<{
+        id: string;
+        name: string;
+        tier: number;
+        feature: string;
+        disabled: boolean;
+        prerequisitesMet: boolean;
+    }>;
+    /**
+     * Run a review. Returns the report.
+     *
+     * Probes within a tier run concurrently (via Promise.allSettled),
+     * except probes sharing a serialGroup which run sequentially.
+     * Tiers run in order (1 → 2 → 3 → 4 → 5).
+     */
+    review(options?: ReviewOptions): Promise<ReviewReport>;
+    private runTier;
+    private runProbe;
+    private createTimeout;
+    /** Get the last N review reports */
+    getHistory(limit?: number): ReviewReport[];
+    /** Get the number of registered probes */
+    getProbeCount(): number;
+    /** Get the most recent review report */
+    getLatest(): ReviewReport | null;
+    /** Analyze trend across recent reviews */
+    getTrend(): ReviewTrend;
+    /** Start the independent review timer (does NOT use the job scheduler) */
+    start(): void;
+    /** Stop the review timer */
+    stop(): void;
+    /** Whether a review is currently in progress */
+    isReviewing(): boolean;
+    /**
+     * Clean up orphaned probe artifacts from all state stores.
+     * Called on construction and before each review run.
+     *
+     * Uses the `cleanupProbeArtifacts` callback if provided.
+     * Falls back to no-op if no cleanup mechanism is available.
+     */
+    private cleanupCallbacks;
+    /** Register a cleanup callback for probe artifacts */
+    registerCleanup(fn: () => Promise<void>): void;
+    runStartupSweep(): Promise<number>;
+    /** Get health status for HealthChecker integration */
+    getHealthStatus(): {
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        message: string;
+        lastCheck: string;
+    };
+    private getEligibleProbes;
+    private groupByTier;
+    private buildReport;
+    private buildDryRunReport;
+    private buildTimeoutResult;
+    private loadHistory;
+    private addToHistory;
+    private persistHistory;
+    private compactHistory;
+    /**
+     * Write to the dead-letter file. This is the ONE error path that
+     * does not depend on any monitored infrastructure. Uses only
+     * fs.appendFileSync — no Telegram, no feedback, no SQLite.
+     */
+    private writeDeadLetter;
+    private processFailures;
+    private isAlertCoolingDown;
+    private wasRecentlyReported;
+}
+//# sourceMappingURL=SystemReviewer.d.ts.map

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

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