aegis-bridge 2.2.2

package/dist/metrics.d.ts

@@ -0,0 +1,104 @@
+/**
+ * metrics.ts — Usage metrics and counters.
+ *
+ * Issue #40: Global and per-session metrics for monitoring.
+ * Counters are in-memory, persisted to disk on shutdown, loaded on startup.
+ */
+export interface GlobalMetrics {
+    sessionsCreated: number;
+    sessionsCompleted: number;
+    sessionsFailed: number;
+    totalMessages: number;
+    totalToolCalls: number;
+    autoApprovals: number;
+    webhooksSent: number;
+    webhooksFailed: number;
+    screenshotsTaken: number;
+    pipelinesCreated: number;
+    batchesCreated: number;
+    promptsSent: number;
+    promptsDelivered: number;
+    promptsFailed: number;
+}
+export interface SessionMetrics {
+    durationSec: number;
+    messages: number;
+    toolCalls: number;
+    approvals: number;
+    autoApprovals: number;
+    statusChanges: string[];
+}
+/** Issue #87: Per-session latency samples (rolling window). */
+export interface SessionLatency {
+    hook_latency_ms: number[];
+    state_change_detection_ms: number[];
+    permission_response_ms: number[];
+    channel_delivery_ms: number[];
+}
+/** Issue #87: Aggregated latency summary for a session. */
+export interface SessionLatencySummary {
+    hook_latency_ms: {
+        min: number | null;
+        max: number | null;
+        avg: number | null;
+        count: number;
+    };
+    state_change_detection_ms: {
+        min: number | null;
+        max: number | null;
+        avg: number | null;
+        count: number;
+    };
+    permission_response_ms: {
+        min: number | null;
+        max: number | null;
+        avg: number | null;
+        count: number;
+    };
+    channel_delivery_ms: {
+        min: number | null;
+        max: number | null;
+        avg: number | null;
+        count: number;
+    };
+}
+export declare class MetricsCollector {
+    private metricsFile;
+    private global;
+    private perSession;
+    private latency;
+    private startTime;
+    /** Maximum samples per latency type per session (rolling window). */
+    static readonly MAX_LATENCY_SAMPLES = 100;
+    constructor(metricsFile: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    sessionCreated(sessionId: string): void;
+    sessionCompleted(sessionId: string): void;
+    sessionFailed(sessionId: string): void;
+    messageReceived(sessionId: string): void;
+    toolCallReceived(sessionId: string): void;
+    approvalGranted(sessionId: string, auto?: boolean): void;
+    statusChanged(sessionId: string, status: string): void;
+    webhookSent(): void;
+    webhookFailed(): void;
+    screenshotTaken(): void;
+    pipelineCreated(): void;
+    batchCreated(): void;
+    promptSent(delivered: boolean): void;
+    private getOrCreateLatency;
+    private pushSample;
+    recordHookLatency(sessionId: string, latencyMs: number): void;
+    recordStateChangeDetection(sessionId: string, latencyMs: number): void;
+    recordPermissionResponse(sessionId: string, latencyMs: number): void;
+    recordChannelDelivery(sessionId: string, latencyMs: number): void;
+    private summarizeSamples;
+    getSessionLatency(sessionId: string): SessionLatencySummary | null;
+    /** Clean up latency data for a session (called on session kill). */
+    clearSessionLatency(sessionId: string): void;
+    /** #357: Clean up all per-session data (call on session destroy). */
+    cleanupSession(sessionId: string): void;
+    getGlobalMetrics(activeSessionCount: number): Record<string, unknown>;
+    getSessionMetrics(sessionId: string): SessionMetrics | null;
+    getTotalSessionsCreated(): number;
+}

package/dist/metrics.js

@@ -0,0 +1,226 @@
+/**
+ * metrics.ts — Usage metrics and counters.
+ *
+ * Issue #40: Global and per-session metrics for monitoring.
+ * Counters are in-memory, persisted to disk on shutdown, loaded on startup.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { metricsFileSchema } from './validation.js';
+export class MetricsCollector {
+    metricsFile;
+    global = {
+        sessionsCreated: 0,
+        sessionsCompleted: 0,
+        sessionsFailed: 0,
+        totalMessages: 0,
+        totalToolCalls: 0,
+        autoApprovals: 0,
+        webhooksSent: 0,
+        webhooksFailed: 0,
+        screenshotsTaken: 0,
+        pipelinesCreated: 0,
+        batchesCreated: 0,
+        promptsSent: 0,
+        promptsDelivered: 0,
+        promptsFailed: 0,
+    };
+    perSession = new Map();
+    latency = new Map();
+    startTime = Date.now();
+    /** Maximum samples per latency type per session (rolling window). */
+    static MAX_LATENCY_SAMPLES = 100;
+    constructor(metricsFile) {
+        this.metricsFile = metricsFile;
+    }
+    async load() {
+        if (existsSync(this.metricsFile)) {
+            try {
+                const raw = await readFile(this.metricsFile, 'utf-8');
+                const parsed = metricsFileSchema.safeParse(JSON.parse(raw));
+                if (parsed.success && parsed.data.global) {
+                    this.global = { ...this.global, ...parsed.data.global };
+                }
+            }
+            catch { /* ignore corrupt file */ }
+        }
+    }
+    async save() {
+        const dir = dirname(this.metricsFile);
+        if (!existsSync(dir)) {
+            await mkdir(dir, { recursive: true });
+        }
+        await writeFile(this.metricsFile, JSON.stringify({ global: this.global, savedAt: Date.now() }, null, 2));
+    }
+    sessionCreated(sessionId) {
+        this.global.sessionsCreated++;
+        this.perSession.set(sessionId, {
+            durationSec: 0, messages: 0, toolCalls: 0,
+            approvals: 0, autoApprovals: 0, statusChanges: [],
+        });
+    }
+    sessionCompleted(sessionId) {
+        this.global.sessionsCompleted++;
+    }
+    sessionFailed(sessionId) {
+        this.global.sessionsFailed++;
+    }
+    messageReceived(sessionId) {
+        this.global.totalMessages++;
+        const m = this.perSession.get(sessionId);
+        if (m)
+            m.messages++;
+    }
+    toolCallReceived(sessionId) {
+        this.global.totalToolCalls++;
+        const m = this.perSession.get(sessionId);
+        if (m)
+            m.toolCalls++;
+    }
+    approvalGranted(sessionId, auto = false) {
+        if (auto)
+            this.global.autoApprovals++;
+        const m = this.perSession.get(sessionId);
+        if (m) {
+            m.approvals++;
+            if (auto)
+                m.autoApprovals++;
+        }
+    }
+    statusChanged(sessionId, status) {
+        const m = this.perSession.get(sessionId);
+        if (m)
+            m.statusChanges.push(status);
+    }
+    webhookSent() { this.global.webhooksSent++; }
+    webhookFailed() { this.global.webhooksFailed++; }
+    screenshotTaken() { this.global.screenshotsTaken++; }
+    pipelineCreated() { this.global.pipelinesCreated++; }
+    batchCreated() { this.global.batchesCreated++; }
+    promptSent(delivered) {
+        this.global.promptsSent++;
+        if (delivered) {
+            this.global.promptsDelivered++;
+        }
+        else {
+            this.global.promptsFailed++;
+        }
+    }
+    // ── Issue #87: Latency metric recording ─────────────────────────────
+    getOrCreateLatency(sessionId) {
+        let lat = this.latency.get(sessionId);
+        if (!lat) {
+            lat = { hook_latency_ms: [], state_change_detection_ms: [], permission_response_ms: [], channel_delivery_ms: [] };
+            this.latency.set(sessionId, lat);
+        }
+        return lat;
+    }
+    pushSample(arr, value) {
+        arr.push(value);
+        if (arr.length > MetricsCollector.MAX_LATENCY_SAMPLES) {
+            arr.shift();
+        }
+    }
+    recordHookLatency(sessionId, latencyMs) {
+        this.pushSample(this.getOrCreateLatency(sessionId).hook_latency_ms, latencyMs);
+    }
+    recordStateChangeDetection(sessionId, latencyMs) {
+        this.pushSample(this.getOrCreateLatency(sessionId).state_change_detection_ms, latencyMs);
+    }
+    recordPermissionResponse(sessionId, latencyMs) {
+        this.pushSample(this.getOrCreateLatency(sessionId).permission_response_ms, latencyMs);
+    }
+    recordChannelDelivery(sessionId, latencyMs) {
+        this.pushSample(this.getOrCreateLatency(sessionId).channel_delivery_ms, latencyMs);
+    }
+    summarizeSamples(samples) {
+        if (samples.length === 0) {
+            return { min: null, max: null, avg: null, count: 0 };
+        }
+        let min = samples[0];
+        let max = samples[0];
+        let sum = 0;
+        for (const s of samples) {
+            if (s < min)
+                min = s;
+            if (s > max)
+                max = s;
+            sum += s;
+        }
+        return { min, max, avg: Math.round(sum / samples.length), count: samples.length };
+    }
+    getSessionLatency(sessionId) {
+        const lat = this.latency.get(sessionId);
+        if (!lat)
+            return null;
+        return {
+            hook_latency_ms: this.summarizeSamples(lat.hook_latency_ms),
+            state_change_detection_ms: this.summarizeSamples(lat.state_change_detection_ms),
+            permission_response_ms: this.summarizeSamples(lat.permission_response_ms),
+            channel_delivery_ms: this.summarizeSamples(lat.channel_delivery_ms),
+        };
+    }
+    /** Clean up latency data for a session (called on session kill). */
+    clearSessionLatency(sessionId) {
+        this.latency.delete(sessionId);
+    }
+    /** #357: Clean up all per-session data (call on session destroy). */
+    cleanupSession(sessionId) {
+        this.perSession.delete(sessionId);
+        this.latency.delete(sessionId);
+    }
+    getGlobalMetrics(activeSessionCount) {
+        const avgMessages = this.global.sessionsCreated > 0
+            ? Math.round(this.global.totalMessages / this.global.sessionsCreated) : 0;
+        // Issue #87: Aggregate latency across all sessions
+        const allHookLatency = [];
+        const allStateChange = [];
+        const allPermissionResponse = [];
+        const allChannelDelivery = [];
+        for (const lat of this.latency.values()) {
+            allHookLatency.push(...lat.hook_latency_ms);
+            allStateChange.push(...lat.state_change_detection_ms);
+            allPermissionResponse.push(...lat.permission_response_ms);
+            allChannelDelivery.push(...lat.channel_delivery_ms);
+        }
+        return {
+            uptime: Math.round((Date.now() - this.startTime) / 1000),
+            sessions: {
+                total_created: this.global.sessionsCreated,
+                currently_active: activeSessionCount,
+                completed: this.global.sessionsCompleted,
+                failed: this.global.sessionsFailed,
+                avg_duration_sec: 0,
+                avg_messages_per_session: avgMessages,
+            },
+            auto_approvals: this.global.autoApprovals,
+            webhooks_sent: this.global.webhooksSent,
+            webhooks_failed: this.global.webhooksFailed,
+            screenshots_taken: this.global.screenshotsTaken,
+            pipelines_created: this.global.pipelinesCreated,
+            batches_created: this.global.batchesCreated,
+            prompt_delivery: {
+                sent: this.global.promptsSent,
+                delivered: this.global.promptsDelivered,
+                failed: this.global.promptsFailed,
+                success_rate: this.global.promptsSent > 0
+                    ? Math.round((this.global.promptsDelivered / this.global.promptsSent) * 100) : null,
+            },
+            // Issue #87: Aggregate latency metrics
+            latency: {
+                hook_latency_ms: this.summarizeSamples(allHookLatency),
+                state_change_detection_ms: this.summarizeSamples(allStateChange),
+                permission_response_ms: this.summarizeSamples(allPermissionResponse),
+                channel_delivery_ms: this.summarizeSamples(allChannelDelivery),
+            },
+        };
+    }
+    getSessionMetrics(sessionId) {
+        return this.perSession.get(sessionId) || null;
+    }
+    getTotalSessionsCreated() {
+        return this.global.sessionsCreated;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/monitor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * monitor.ts — Background monitor that polls sessions and routes events to channels.
+ *
+ * Runs a polling loop that:
+ * 1. Checks each active session for new JSONL entries
+ * 2. Detects status changes (working → idle, permission prompts, etc.)
+ * 3. Routes events to the ChannelManager (which fans out to Telegram, webhooks, etc.)
+ */
+import { type SessionManager } from './session.js';
+import { type ChannelManager } from './channels/index.js';
+import { type SessionEventBus } from './events.js';
+import { type JsonlWatcher } from './jsonl-watcher.js';
+export interface MonitorConfig {
+    pollIntervalMs: number;
+    fastPollIntervalMs: number;
+    hookQuietMs: number;
+    stallThresholdMs: number;
+    stallCheckIntervalMs: number;
+    deadCheckIntervalMs: number;
+    permissionStallMs: number;
+    unknownStallMs: number;
+    permissionTimeoutMs: number;
+}
+export declare const DEFAULT_MONITOR_CONFIG: MonitorConfig;
+export declare class SessionMonitor {
+    private sessions;
+    private channels;
+    private config;
+    private running;
+    private lastStatus;
+    private lastBytesSeen;
+    private stallNotified;
+    private lastStallCheck;
+    private lastDeadCheck;
+    private idleNotified;
+    private idleSince;
+    private processedStopSignals;
+    private static readonly MAX_PROCESSED_STOP_SIGNALS;
+    private stateSince;
+    private deadNotified;
+    private prevStatusForStall;
+    private rateLimitedSessions;
+    /** Issue #89 L4: Debounce status change broadcasts per session.
+     *  If multiple status changes happen within 500ms, only emit the last one.
+     *  Prevents rapid-fire notifications during state transitions. */
+    private statusChangeDebounce;
+    /** Issue #32: Optional SSE event bus for real-time streaming. */
+    private eventBus?;
+    /** Issue #84: fs.watch-based JSONL watcher for near-instant message detection. */
+    private jsonlWatcher?;
+    constructor(sessions: SessionManager, channels: ChannelManager, config?: MonitorConfig);
+    /** Issue #32: Set the event bus for SSE streaming. */
+    setEventBus(bus: SessionEventBus): void;
+    /** Issue #84: Set the JSONL watcher for fs.watch-based message detection. */
+    setJsonlWatcher(watcher: JsonlWatcher): void;
+    start(): void;
+    stop(): void;
+    private loop;
+    /** Check if any active session hasn't received a hook recently. */
+    private needsFastPolling;
+    private poll;
+    /** Smart stall detection: multiple stall types with graduated thresholds.
+     *
+     * Detects 4 types of stalls:
+     * 1. JSONL stall: "working" but no new JSONL bytes for stallThresholdMs
+     * 2. Permission stall: permission_prompt/bash_approval for permissionStallMs
+     * 3. Unknown stall: unknown state for unknownStallMs (CC stuck in transition)
+     * 4. State duration stall: any non-idle state for 2x its threshold
+     */
+    private checkForStalls;
+    /** Issue #15: Check for Stop/StopFailure signals written by hook.ts. */
+    private checkStopSignals;
+    /** Issue #84: Handle new entries from the fs.watch-based JSONL watcher.
+     *  Forwards messages to channels and updates stall tracking. */
+    private handleWatcherEvent;
+    private checkSession;
+    private forwardMessage;
+    private broadcastStatusChange;
+    private makePayload;
+    /** Check for dead tmux windows and notify via channels. */
+    private checkDeadSessions;
+    /** Clean up tracking for a killed session. */
+    removeSession(sessionId: string): void;
+}