enpilink 1.0.2

package/dist/server/observability.js

@@ -0,0 +1,340 @@
+import express, {} from "express";
+import { getActiveStorage } from "./log-sink.js";
+/**
+ * Percentile of a numeric sample using nearest-rank (lower) interpolation.
+ * Returns `0` for an empty sample. `p` is in `[0, 1]`. Tolerates `ms === 0`
+ * (a zero-latency call is a real data point, not a missing one).
+ */
+export function percentile(sorted, p) {
+    if (sorted.length === 0) {
+        return 0;
+    }
+    const rank = p * (sorted.length - 1);
+    const lo = Math.floor(rank);
+    const hi = Math.ceil(rank);
+    const loVal = sorted[lo] ?? 0;
+    if (lo === hi) {
+        return loVal;
+    }
+    const hiVal = sorted[hi] ?? loVal;
+    const frac = rank - lo;
+    return loVal + (hiVal - loVal) * frac;
+}
+/**
+ * Fixed latency-histogram bucket edges (ms). Each pair `[edges[i], edges[i+1])`
+ * is a bucket; the final bucket is open-ended (`>= last edge`). Chosen to span
+ * sub-ms lookups through multi-second LLM/report calls.
+ */
+const HISTOGRAM_EDGES = [0, 10, 25, 50, 100, 250, 500, 1000, 2500];
+/** Bucket a sorted/unsorted latency sample into {@link HISTOGRAM_EDGES}. */
+function buildHistogram(latencies) {
+    const edges = [...HISTOGRAM_EDGES];
+    const counts = new Array(edges.length).fill(0);
+    for (const ms of latencies) {
+        let idx = 0;
+        for (let i = 0; i < edges.length; i++) {
+            if (ms >= edges[i]) {
+                idx = i;
+            }
+        }
+        counts[idx] = (counts[idx] ?? 0) + 1;
+    }
+    return edges.map((from, i) => ({
+        from,
+        to: i + 1 < edges.length ? edges[i + 1] : null,
+        count: counts[i] ?? 0,
+    }));
+}
+/** Mean of a numeric sample, or `0` when empty. */
+function mean(xs) {
+    if (xs.length === 0) {
+        return 0;
+    }
+    return xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+/**
+ * Aggregate raw events into a {@link ObservabilitySummary}. Pure + deterministic
+ * (no clock, no I/O) so it is unit-testable with injected events. The storage
+ * adapter intentionally does NOT aggregate — all rollups happen here.
+ *
+ * - Latency percentiles only consider events with a numeric `ms` (including
+ *   `ms === 0`); events without timing are excluded from p50/p95 but still
+ *   counted toward totals + error rate.
+ * - `ok === false` (or a present `error`) counts as an error.
+ * - Tools group by `tool`, falling back to `method`, then `"unknown"`.
+ */
+export function summarize(events, opts) {
+    const bucketMs = opts.bucketMs ?? 60_000;
+    const topLimit = opts.topLimit ?? 10;
+    const isError = (e) => e.ok === false || (e.ok === undefined && e.error !== undefined);
+    const allLatencies = [];
+    const buckets = new Map();
+    const tools = new Map();
+    const methods = new Map();
+    let minTs = Number.POSITIVE_INFINITY;
+    let maxTs = Number.NEGATIVE_INFINITY;
+    let errors = 0;
+    for (const e of events) {
+        const errored = isError(e);
+        if (errored) {
+            errors += 1;
+        }
+        if (typeof e.ms === "number" && Number.isFinite(e.ms)) {
+            allLatencies.push(e.ms);
+        }
+        if (e.ts < minTs) {
+            minTs = e.ts;
+        }
+        if (e.ts > maxTs) {
+            maxTs = e.ts;
+        }
+        const methodName = e.method ?? "unknown";
+        const mStat = methods.get(methodName) ?? { count: 0, errors: 0 };
+        mStat.count += 1;
+        if (errored) {
+            mStat.errors += 1;
+        }
+        methods.set(methodName, mStat);
+        const bucketTs = Math.floor(e.ts / bucketMs) * bucketMs;
+        const bucket = buckets.get(bucketTs) ?? {
+            ts: bucketTs,
+            count: 0,
+            errors: 0,
+        };
+        bucket.count += 1;
+        if (errored) {
+            bucket.errors += 1;
+        }
+        buckets.set(bucketTs, bucket);
+        const name = e.tool ?? e.method ?? "unknown";
+        const stat = tools.get(name) ?? { count: 0, errors: 0, latencies: [] };
+        stat.count += 1;
+        if (errored) {
+            stat.errors += 1;
+        }
+        if (typeof e.ms === "number" && Number.isFinite(e.ms)) {
+            stat.latencies.push(e.ms);
+        }
+        tools.set(name, stat);
+    }
+    allLatencies.sort((a, b) => a - b);
+    const total = events.length;
+    const toolStats = [...tools.entries()].map(([name, s]) => {
+        const sorted = s.latencies.slice().sort((a, b) => a - b);
+        return {
+            name,
+            count: s.count,
+            errors: s.errors,
+            errorRate: s.count === 0 ? 0 : s.errors / s.count,
+            p50: percentile(sorted, 0.5),
+            p95: percentile(sorted, 0.95),
+            p99: percentile(sorted, 0.99),
+            avg: mean(sorted),
+        };
+    });
+    const topTools = toolStats
+        .slice()
+        .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+        .slice(0, topLimit);
+    // Slowest by p95, considering only tools that actually have timing data.
+    const slowestTools = toolStats
+        .filter((t) => t.p95 > 0)
+        .sort((a, b) => b.p95 - a.p95 || a.name.localeCompare(b.name))
+        .slice(0, topLimit);
+    const byMethod = [...methods.entries()]
+        .map(([method, s]) => ({ method, count: s.count, errors: s.errors }))
+        .sort((a, b) => b.count - a.count || a.method.localeCompare(b.method));
+    const callsOverTime = [...buckets.values()].sort((a, b) => a.ts - b.ts);
+    // Throughput: calls / minute over the observed span. Use the actual event
+    // span (since → newest event) so a long default window with little data
+    // doesn't dilute the rate to ~0. Falls back to 0 for empty input.
+    const spanMs = total === 0 ? 0 : Math.max(maxTs - opts.since, maxTs - minTs);
+    const throughputPerMin = spanMs > 0 ? total / (spanMs / 60_000) : total > 0 ? total : 0;
+    return {
+        enabled: true,
+        since: opts.since,
+        total,
+        errors,
+        errorRate: total === 0 ? 0 : errors / total,
+        p50: percentile(allLatencies, 0.5),
+        p95: percentile(allLatencies, 0.95),
+        p99: percentile(allLatencies, 0.99),
+        avg: mean(allLatencies),
+        throughputPerMin,
+        bucketMs,
+        callsOverTime,
+        topTools,
+        slowestTools,
+        byMethod,
+        latencyHistogram: buildHistogram(allLatencies),
+    };
+}
+/** Empty 200 payload returned when there is no active storage. */
+function disabledSummary(bucketMs) {
+    return {
+        enabled: false,
+        total: 0,
+        errors: 0,
+        errorRate: 0,
+        p50: 0,
+        p95: 0,
+        p99: 0,
+        avg: 0,
+        throughputPerMin: 0,
+        bucketMs,
+        callsOverTime: [],
+        topTools: [],
+        slowestTools: [],
+        byMethod: [],
+        latencyHistogram: [],
+    };
+}
+/** Parse a non-negative integer query param, or `undefined` if absent/invalid. */
+function intParam(raw) {
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function strParam(raw) {
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+const DEFAULT_SUMMARY_WINDOW_MS = 60 * 60 * 1000; // 1h
+const DEFAULT_LIMIT = 200;
+const STREAM_POLL_MS = 1000;
+/**
+ * Build the observability read API router. All routes read storage
+ * per-request via {@link getActiveStorage} (overridable for tests) so the
+ * disabled / not-yet-installed path returns a 200 empty payload, never a 500.
+ */
+export function createObservabilityRouter(getStorage = getActiveStorage) {
+    const router = express.Router();
+    const base = "/__enpilink/observability";
+    // GET /summary — aggregate from queryEvents (counts, error rate, p50/p95,
+    // top tools, calls over time). Aggregation happens here, not in the adapter.
+    router.get(`${base}/summary`, async (req, res) => {
+        const bucketMs = intParam(req.query.bucketMs) || 60_000;
+        const storage = getStorage();
+        if (!storage) {
+            res.json(disabledSummary(bucketMs));
+            return;
+        }
+        const sinceParam = intParam(req.query.since);
+        const since = sinceParam !== undefined
+            ? sinceParam
+            : Date.now() - DEFAULT_SUMMARY_WINDOW_MS;
+        try {
+            // limit:0 from memory means "no events"; pass a large cap so the summary
+            // reflects the full window. queryEvents returns most-recent-first.
+            const events = await storage.queryEvents({
+                since,
+                type: strParam(req.query.type),
+                tool: strParam(req.query.tool),
+                limit: intParam(req.query.limit) ?? 5000,
+            });
+            res.json(summarize(events, { since, bucketMs }));
+        }
+        catch {
+            res.json(disabledSummary(bucketMs));
+        }
+    });
+    // GET /events?since&type&tool&limit — pass-through to storage.queryEvents.
+    router.get(`${base}/events`, async (req, res) => {
+        const storage = getStorage();
+        if (!storage) {
+            res.json({ enabled: false, events: [] });
+            return;
+        }
+        try {
+            const events = await storage.queryEvents({
+                since: intParam(req.query.since),
+                type: strParam(req.query.type),
+                tool: strParam(req.query.tool),
+                limit: intParam(req.query.limit) ?? DEFAULT_LIMIT,
+            });
+            res.json({ enabled: true, events });
+        }
+        catch {
+            res.json({ enabled: false, events: [] });
+        }
+    });
+    // GET /logs?since&level&limit — pass-through to storage.queryLogs.
+    router.get(`${base}/logs`, async (req, res) => {
+        const storage = getStorage();
+        if (!storage) {
+            res.json({ enabled: false, logs: [] });
+            return;
+        }
+        try {
+            const logs = await storage.queryLogs({
+                since: intParam(req.query.since),
+                level: strParam(req.query.level),
+                limit: intParam(req.query.limit) ?? DEFAULT_LIMIT,
+            });
+            res.json({ enabled: true, logs });
+        }
+        catch {
+            res.json({ enabled: false, logs: [] });
+        }
+    });
+    // GET /stream — poll-based SSE. Mirrors the tunnel SSE style: set the
+    // event-stream headers, push frames, and clean up the interval on client
+    // disconnect. We poll storage on an interval using a `since` cursor and push
+    // only events/logs newer than the cursor. Resilient to storage being absent.
+    router.get(`${base}/stream`, async (req, res) => {
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache, no-transform");
+        res.setHeader("Connection", "keep-alive");
+        res.flushHeaders?.();
+        // Start the cursor at request time so we only stream NEW activity.
+        let cursor = intParam(req.query.since) ?? Date.now();
+        const send = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        // Immediately tell the client whether analytics is live.
+        send("status", { enabled: getStorage() !== null });
+        let stopped = false;
+        const poll = async () => {
+            if (stopped) {
+                return;
+            }
+            const storage = getStorage();
+            if (!storage) {
+                // Heartbeat keeps the connection (and proxies) alive while OFF.
+                send("status", { enabled: false });
+                return;
+            }
+            try {
+                const [events, logs] = await Promise.all([
+                    storage.queryEvents({ since: cursor, limit: 200 }),
+                    storage.queryLogs({ since: cursor, limit: 200 }),
+                ]);
+                // queryEvents/queryLogs are most-recent-first; advance the cursor past
+                // the newest ts so the next poll doesn't re-send the same rows.
+                const newest = Math.max(events[0]?.ts ?? 0, logs[0]?.ts ?? 0, cursor);
+                // Use `> cursor` so the same-ms boundary isn't dropped on the first
+                // pass but isn't re-sent afterward (cursor advances to newest + 1).
+                if (events.length > 0) {
+                    send("events", events);
+                }
+                if (logs.length > 0) {
+                    send("logs", logs);
+                }
+                if (newest >= cursor) {
+                    cursor = newest + 1;
+                }
+            }
+            catch {
+                // Swallow — a transient storage error must not kill the stream.
+            }
+        };
+        const timer = setInterval(() => void poll(), STREAM_POLL_MS);
+        const cleanup = () => {
+            stopped = true;
+            clearInterval(timer);
+            res.end();
+        };
+        req.on("close", cleanup);
+    });
+    return router;
+}
+//# sourceMappingURL=observability.js.map

package/dist/server/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../../src/server/observability.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAe,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AA4HjD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAAgB,EAAE,CAAS;IACpD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACd,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;IACvB,OAAO,KAAK,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,eAAe,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;AAE5E,4EAA4E;AAC5E,SAAS,cAAc,CAAC,SAAmB;IACzC,MAAM,KAAK,GAAa,CAAC,GAAG,eAAe,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,KAAK,CAAS,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,EAAE,IAAK,KAAK,CAAC,CAAC,CAAY,EAAE,CAAC;gBAC/B,GAAG,GAAG,CAAC,CAAC;YACV,CAAC;QACH,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7B,IAAI;QACJ,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAY,CAAC,CAAC,CAAC,IAAI;QAC1D,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;KACtB,CAAC,CAAC,CAAC;AACN,CAAC;AAED,mDAAmD;AACnD,SAAS,IAAI,CAAC,EAAY;IACxB,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC;AACnD,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CACvB,MAAwB,EACxB,IAAsB;IAEtB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IAErC,MAAM,OAAO,GAAG,CAAC,CAAiB,EAAW,EAAE,CAC7C,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;IAElE,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,GAAG,EAGlB,CAAC;IACJ,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6C,CAAC;IACrE,IAAI,KAAK,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACrC,IAAI,KAAK,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAErC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,IAAI,CAAC,CAAC;QACd,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YACtD,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;YACjB,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;QACf,CAAC;QACD,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;YACjB,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;QACf,CAAC;QAED,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,IAAI,SAAS,CAAC;QACzC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QACjE,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QACjB,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAE/B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC,GAAG,QAAQ,CAAC;QACxD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI;YACtC,EAAE,EAAE,QAAQ;YACZ,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,CAAC;SACV,CAAC;QACF,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;QAClB,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAE9B,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,SAAS,CAAC;QAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QACvE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAChB,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACnB,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YACtD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;IAE5B,MAAM,SAAS,GAAe,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE;QACnE,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,SAAS,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK;YACjD,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC;YAC5B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC;YAC7B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC;YAC7B,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC;SAClB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,SAAS;SACvB,KAAK,EAAE;SACP,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SACjE,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAEtB,yEAAyE;IACzE,MAAM,YAAY,GAAG,SAAS;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;SACxB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAC7D,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAEtB,MAAM,QAAQ,GAAiB,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;SAClD,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;SACpE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAEzE,MAAM,aAAa,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAExE,0EAA0E;IAC1E,wEAAwE;IACxE,kEAAkE;IAClE,MAAM,MAAM,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;IAC7E,MAAM,gBAAgB,GACpB,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEjE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK;QACL,MAAM;QACN,SAAS,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,KAAK;QAC3C,GAAG,EAAE,UAAU,CAAC,YAAY,EAAE,GAAG,CAAC;QAClC,GAAG,EAAE,UAAU,CAAC,YAAY,EAAE,IAAI,CAAC;QACnC,GAAG,EAAE,UAAU,CAAC,YAAY,EAAE,IAAI,CAAC;QACnC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC;QACvB,gBAAgB;QAChB,QAAQ;QACR,aAAa;QACb,QAAQ;QACR,YAAY;QACZ,QAAQ;QACR,gBAAgB,EAAE,cAAc,CAAC,YAAY,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,SAAS,eAAe,CAAC,QAAgB;IACvC,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,CAAC;QACZ,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,CAAC;QACN,gBAAgB,EAAE,CAAC;QACnB,QAAQ;QACR,aAAa,EAAE,EAAE;QACjB,QAAQ,EAAE,EAAE;QACZ,YAAY,EAAE,EAAE;QAChB,QAAQ,EAAE,EAAE;QACZ,gBAAgB,EAAE,EAAE;KACrB,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,SAAS,QAAQ,CAAC,GAAY;IAC5B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,GAAY;IAC5B,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,KAAK;AACvD,MAAM,aAAa,GAAG,GAAG,CAAC;AAC1B,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,aAA0C,gBAAgB;IAE1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,2BAA2B,CAAC;IAEzC,0EAA0E;IAC1E,6EAA6E;IAC7E,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC/C,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC;QACxD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;YACpC,OAAO;QACT,CAAC;QACD,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7C,MAAM,KAAK,GACT,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,yBAAyB,CAAC;QAC7C,IAAI,CAAC;YACH,yEAAyE;YACzE,mEAAmE;YACnE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC;gBACvC,KAAK;gBACL,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC9B,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC9B,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI;aACzC,CAAC,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC9C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;YACzC,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC;gBACvC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;gBAChC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC9B,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC9B,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,aAAa;aAClD,CAAC,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,mEAAmE;IACnE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC5C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YACvC,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC;gBACnC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;gBAChC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;gBAChC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,aAAa;aAClD,CAAC,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,sEAAsE;IACtE,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC9C,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;QACnD,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC;QACzD,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC1C,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC;QAErB,mEAAmE;QACnE,IAAI,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QAErD,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,IAAa,EAAW,EAAE,CACrD,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,WAAW,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAElE,yDAAyD;QACzD,IAAI,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAEnD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE;YACtB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YACD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;YAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,gEAAgE;gBAChE,IAAI,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnC,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;oBACvC,OAAO,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;oBAClD,OAAO,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;iBACjD,CAAC,CAAC;gBACH,uEAAuE;gBACvE,gEAAgE;gBAChE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;gBACtE,oEAAoE;gBACpE,oEAAoE;gBACpE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACtB,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBACzB,CAAC;gBACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACpB,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACrB,CAAC;gBACD,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;oBACrB,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,gEAAgE;YAClE,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,EAAE,cAAc,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,OAAO,GAAG,IAAI,CAAC;YACf,aAAa,CAAC,KAAK,CAAC,CAAC;YACrB,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import express, { type Router } from \"express\";\nimport { getActiveStorage } from \"./log-sink.js\";\nimport type { AnalyticsEvent, StorageAdapter } from \"./storage/types.js\";\n\n/**\n * Observability read API (M3). Pure core — reads the SAME active\n * {@link StorageAdapter} the analytics middleware + log sink write to, via\n * {@link getActiveStorage}. It does NOT depend on `@enpilink/console`.\n *\n * Mounted dev-only (under the `NODE_ENV !== \"production\"` block in\n * `express.ts`) at `/__enpilink/observability/`. The `/__enpilink/` prefix\n * avoids colliding with user-defined routes; the dev-only mount keeps prod\n * surface unchanged (prod admin is M5).\n *\n * Graceful when analytics is OFF: storage is read PER-REQUEST (it may be `null`\n * when disabled or before the server applies middleware). When there is no\n * active storage every route returns a 200 with `{ enabled: false }` / an empty\n * payload — NEVER a 500. The storage may also change between requests, so we\n * never cache it.\n */\n\n/** A single point on the calls-over-time series. */\nexport interface TimeBucket {\n  /** Bucket start, epoch ms (aligned to `bucketMs`). */\n  ts: number;\n  /** Total calls in the bucket. */\n  count: number;\n  /** Errored calls in the bucket. */\n  errors: number;\n}\n\n/** Per-tool (or per-method) aggregate row. */\nexport interface ToolStat {\n  /** Tool name, or the method name when there is no tool (non-`tools/call`). */\n  name: string;\n  /** Total calls. */\n  count: number;\n  /** Errored calls. */\n  errors: number;\n  /** Error rate in `[0, 1]`. */\n  errorRate: number;\n  /** Median latency (ms). */\n  p50: number;\n  /** 95th-percentile latency (ms). */\n  p95: number;\n  /** 99th-percentile latency (ms). */\n  p99: number;\n  /** Average latency (ms) over events with timing. */\n  avg: number;\n}\n\n/** Per-MCP-method aggregate row (e.g. `tools/call`, `tools/list`). */\nexport interface MethodStat {\n  /** MCP method name, or `\"unknown\"`. */\n  method: string;\n  /** Total calls. */\n  count: number;\n  /** Errored calls. */\n  errors: number;\n}\n\n/** A single bar of the latency histogram. */\nexport interface LatencyBucket {\n  /** Inclusive lower bound of the bucket (ms). */\n  from: number;\n  /** Exclusive upper bound of the bucket (ms), or `null` for the open top bin. */\n  to: number | null;\n  /** Number of events whose latency fell in this bucket. */\n  count: number;\n}\n\n/** The aggregate returned by `GET /summary` when analytics is enabled. */\nexport interface ObservabilitySummary {\n  enabled: true;\n  /** Window the summary was computed over (epoch ms). */\n  since: number;\n  /** Total events considered. */\n  total: number;\n  /** Errored events. */\n  errors: number;\n  /** Error rate in `[0, 1]`. */\n  errorRate: number;\n  /** Median latency across all events (ms). */\n  p50: number;\n  /** 95th-percentile latency across all events (ms). */\n  p95: number;\n  /** 99th-percentile latency across all events (ms). */\n  p99: number;\n  /** Average latency across all timed events (ms). */\n  avg: number;\n  /** Throughput: calls per minute over the window `[since, latest event]`. */\n  throughputPerMin: number;\n  /** Bucket width used for {@link callsOverTime} (ms). */\n  bucketMs: number;\n  /** Calls-over-time series, oldest bucket first. */\n  callsOverTime: TimeBucket[];\n  /** Top tools/methods by call count (descending). */\n  topTools: ToolStat[];\n  /** Slowest tools/methods by p95 latency (descending). Only timed tools. */\n  slowestTools: ToolStat[];\n  /** Calls grouped by MCP method (descending by count). */\n  byMethod: MethodStat[];\n  /** Latency distribution histogram (fixed buckets). */\n  latencyHistogram: LatencyBucket[];\n}\n\n/** The disabled/no-storage shape — a valid 200 payload, never a 500. */\nexport interface ObservabilityDisabled {\n  enabled: false;\n  total: 0;\n  errors: 0;\n  errorRate: 0;\n  p50: 0;\n  p95: 0;\n  p99: 0;\n  avg: 0;\n  throughputPerMin: 0;\n  bucketMs: number;\n  callsOverTime: [];\n  topTools: [];\n  slowestTools: [];\n  byMethod: [];\n  latencyHistogram: [];\n}\n\n/**\n * Percentile of a numeric sample using nearest-rank (lower) interpolation.\n * Returns `0` for an empty sample. `p` is in `[0, 1]`. Tolerates `ms === 0`\n * (a zero-latency call is a real data point, not a missing one).\n */\nexport function percentile(sorted: number[], p: number): number {\n  if (sorted.length === 0) {\n    return 0;\n  }\n  const rank = p * (sorted.length - 1);\n  const lo = Math.floor(rank);\n  const hi = Math.ceil(rank);\n  const loVal = sorted[lo] ?? 0;\n  if (lo === hi) {\n    return loVal;\n  }\n  const hiVal = sorted[hi] ?? loVal;\n  const frac = rank - lo;\n  return loVal + (hiVal - loVal) * frac;\n}\n\n/**\n * Fixed latency-histogram bucket edges (ms). Each pair `[edges[i], edges[i+1])`\n * is a bucket; the final bucket is open-ended (`>= last edge`). Chosen to span\n * sub-ms lookups through multi-second LLM/report calls.\n */\nconst HISTOGRAM_EDGES = [0, 10, 25, 50, 100, 250, 500, 1000, 2500] as const;\n\n/** Bucket a sorted/unsorted latency sample into {@link HISTOGRAM_EDGES}. */\nfunction buildHistogram(latencies: number[]): LatencyBucket[] {\n  const edges: number[] = [...HISTOGRAM_EDGES];\n  const counts = new Array<number>(edges.length).fill(0);\n  for (const ms of latencies) {\n    let idx = 0;\n    for (let i = 0; i < edges.length; i++) {\n      if (ms >= (edges[i] as number)) {\n        idx = i;\n      }\n    }\n    counts[idx] = (counts[idx] ?? 0) + 1;\n  }\n  return edges.map((from, i) => ({\n    from,\n    to: i + 1 < edges.length ? (edges[i + 1] as number) : null,\n    count: counts[i] ?? 0,\n  }));\n}\n\n/** Mean of a numeric sample, or `0` when empty. */\nfunction mean(xs: number[]): number {\n  if (xs.length === 0) {\n    return 0;\n  }\n  return xs.reduce((a, b) => a + b, 0) / xs.length;\n}\n\n/** Options for {@link summarize}. */\nexport interface SummarizeOptions {\n  /** Lower bound used in the response (epoch ms). */\n  since: number;\n  /** Bucket width for the calls-over-time series (ms). Defaults to 60_000. */\n  bucketMs?: number;\n  /** Max tools in `topTools`. Defaults to 10. */\n  topLimit?: number;\n}\n\n/**\n * Aggregate raw events into a {@link ObservabilitySummary}. Pure + deterministic\n * (no clock, no I/O) so it is unit-testable with injected events. The storage\n * adapter intentionally does NOT aggregate — all rollups happen here.\n *\n * - Latency percentiles only consider events with a numeric `ms` (including\n *   `ms === 0`); events without timing are excluded from p50/p95 but still\n *   counted toward totals + error rate.\n * - `ok === false` (or a present `error`) counts as an error.\n * - Tools group by `tool`, falling back to `method`, then `\"unknown\"`.\n */\nexport function summarize(\n  events: AnalyticsEvent[],\n  opts: SummarizeOptions,\n): ObservabilitySummary {\n  const bucketMs = opts.bucketMs ?? 60_000;\n  const topLimit = opts.topLimit ?? 10;\n\n  const isError = (e: AnalyticsEvent): boolean =>\n    e.ok === false || (e.ok === undefined && e.error !== undefined);\n\n  const allLatencies: number[] = [];\n  const buckets = new Map<number, TimeBucket>();\n  const tools = new Map<\n    string,\n    { count: number; errors: number; latencies: number[] }\n  >();\n  const methods = new Map<string, { count: number; errors: number }>();\n  let minTs = Number.POSITIVE_INFINITY;\n  let maxTs = Number.NEGATIVE_INFINITY;\n\n  let errors = 0;\n  for (const e of events) {\n    const errored = isError(e);\n    if (errored) {\n      errors += 1;\n    }\n    if (typeof e.ms === \"number\" && Number.isFinite(e.ms)) {\n      allLatencies.push(e.ms);\n    }\n    if (e.ts < minTs) {\n      minTs = e.ts;\n    }\n    if (e.ts > maxTs) {\n      maxTs = e.ts;\n    }\n\n    const methodName = e.method ?? \"unknown\";\n    const mStat = methods.get(methodName) ?? { count: 0, errors: 0 };\n    mStat.count += 1;\n    if (errored) {\n      mStat.errors += 1;\n    }\n    methods.set(methodName, mStat);\n\n    const bucketTs = Math.floor(e.ts / bucketMs) * bucketMs;\n    const bucket = buckets.get(bucketTs) ?? {\n      ts: bucketTs,\n      count: 0,\n      errors: 0,\n    };\n    bucket.count += 1;\n    if (errored) {\n      bucket.errors += 1;\n    }\n    buckets.set(bucketTs, bucket);\n\n    const name = e.tool ?? e.method ?? \"unknown\";\n    const stat = tools.get(name) ?? { count: 0, errors: 0, latencies: [] };\n    stat.count += 1;\n    if (errored) {\n      stat.errors += 1;\n    }\n    if (typeof e.ms === \"number\" && Number.isFinite(e.ms)) {\n      stat.latencies.push(e.ms);\n    }\n    tools.set(name, stat);\n  }\n\n  allLatencies.sort((a, b) => a - b);\n  const total = events.length;\n\n  const toolStats: ToolStat[] = [...tools.entries()].map(([name, s]) => {\n    const sorted = s.latencies.slice().sort((a, b) => a - b);\n    return {\n      name,\n      count: s.count,\n      errors: s.errors,\n      errorRate: s.count === 0 ? 0 : s.errors / s.count,\n      p50: percentile(sorted, 0.5),\n      p95: percentile(sorted, 0.95),\n      p99: percentile(sorted, 0.99),\n      avg: mean(sorted),\n    };\n  });\n\n  const topTools = toolStats\n    .slice()\n    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))\n    .slice(0, topLimit);\n\n  // Slowest by p95, considering only tools that actually have timing data.\n  const slowestTools = toolStats\n    .filter((t) => t.p95 > 0)\n    .sort((a, b) => b.p95 - a.p95 || a.name.localeCompare(b.name))\n    .slice(0, topLimit);\n\n  const byMethod: MethodStat[] = [...methods.entries()]\n    .map(([method, s]) => ({ method, count: s.count, errors: s.errors }))\n    .sort((a, b) => b.count - a.count || a.method.localeCompare(b.method));\n\n  const callsOverTime = [...buckets.values()].sort((a, b) => a.ts - b.ts);\n\n  // Throughput: calls / minute over the observed span. Use the actual event\n  // span (since → newest event) so a long default window with little data\n  // doesn't dilute the rate to ~0. Falls back to 0 for empty input.\n  const spanMs = total === 0 ? 0 : Math.max(maxTs - opts.since, maxTs - minTs);\n  const throughputPerMin =\n    spanMs > 0 ? total / (spanMs / 60_000) : total > 0 ? total : 0;\n\n  return {\n    enabled: true,\n    since: opts.since,\n    total,\n    errors,\n    errorRate: total === 0 ? 0 : errors / total,\n    p50: percentile(allLatencies, 0.5),\n    p95: percentile(allLatencies, 0.95),\n    p99: percentile(allLatencies, 0.99),\n    avg: mean(allLatencies),\n    throughputPerMin,\n    bucketMs,\n    callsOverTime,\n    topTools,\n    slowestTools,\n    byMethod,\n    latencyHistogram: buildHistogram(allLatencies),\n  };\n}\n\n/** Empty 200 payload returned when there is no active storage. */\nfunction disabledSummary(bucketMs: number): ObservabilityDisabled {\n  return {\n    enabled: false,\n    total: 0,\n    errors: 0,\n    errorRate: 0,\n    p50: 0,\n    p95: 0,\n    p99: 0,\n    avg: 0,\n    throughputPerMin: 0,\n    bucketMs,\n    callsOverTime: [],\n    topTools: [],\n    slowestTools: [],\n    byMethod: [],\n    latencyHistogram: [],\n  };\n}\n\n/** Parse a non-negative integer query param, or `undefined` if absent/invalid. */\nfunction intParam(raw: unknown): number | undefined {\n  if (typeof raw !== \"string\") {\n    return undefined;\n  }\n  const n = Number.parseInt(raw, 10);\n  return Number.isFinite(n) && n >= 0 ? n : undefined;\n}\n\nfunction strParam(raw: unknown): string | undefined {\n  return typeof raw === \"string\" && raw.length > 0 ? raw : undefined;\n}\n\nconst DEFAULT_SUMMARY_WINDOW_MS = 60 * 60 * 1000; // 1h\nconst DEFAULT_LIMIT = 200;\nconst STREAM_POLL_MS = 1000;\n\n/**\n * Build the observability read API router. All routes read storage\n * per-request via {@link getActiveStorage} (overridable for tests) so the\n * disabled / not-yet-installed path returns a 200 empty payload, never a 500.\n */\nexport function createObservabilityRouter(\n  getStorage: () => StorageAdapter | null = getActiveStorage,\n): Router {\n  const router = express.Router();\n  const base = \"/__enpilink/observability\";\n\n  // GET /summary — aggregate from queryEvents (counts, error rate, p50/p95,\n  // top tools, calls over time). Aggregation happens here, not in the adapter.\n  router.get(`${base}/summary`, async (req, res) => {\n    const bucketMs = intParam(req.query.bucketMs) || 60_000;\n    const storage = getStorage();\n    if (!storage) {\n      res.json(disabledSummary(bucketMs));\n      return;\n    }\n    const sinceParam = intParam(req.query.since);\n    const since =\n      sinceParam !== undefined\n        ? sinceParam\n        : Date.now() - DEFAULT_SUMMARY_WINDOW_MS;\n    try {\n      // limit:0 from memory means \"no events\"; pass a large cap so the summary\n      // reflects the full window. queryEvents returns most-recent-first.\n      const events = await storage.queryEvents({\n        since,\n        type: strParam(req.query.type),\n        tool: strParam(req.query.tool),\n        limit: intParam(req.query.limit) ?? 5000,\n      });\n      res.json(summarize(events, { since, bucketMs }));\n    } catch {\n      res.json(disabledSummary(bucketMs));\n    }\n  });\n\n  // GET /events?since&type&tool&limit — pass-through to storage.queryEvents.\n  router.get(`${base}/events`, async (req, res) => {\n    const storage = getStorage();\n    if (!storage) {\n      res.json({ enabled: false, events: [] });\n      return;\n    }\n    try {\n      const events = await storage.queryEvents({\n        since: intParam(req.query.since),\n        type: strParam(req.query.type),\n        tool: strParam(req.query.tool),\n        limit: intParam(req.query.limit) ?? DEFAULT_LIMIT,\n      });\n      res.json({ enabled: true, events });\n    } catch {\n      res.json({ enabled: false, events: [] });\n    }\n  });\n\n  // GET /logs?since&level&limit — pass-through to storage.queryLogs.\n  router.get(`${base}/logs`, async (req, res) => {\n    const storage = getStorage();\n    if (!storage) {\n      res.json({ enabled: false, logs: [] });\n      return;\n    }\n    try {\n      const logs = await storage.queryLogs({\n        since: intParam(req.query.since),\n        level: strParam(req.query.level),\n        limit: intParam(req.query.limit) ?? DEFAULT_LIMIT,\n      });\n      res.json({ enabled: true, logs });\n    } catch {\n      res.json({ enabled: false, logs: [] });\n    }\n  });\n\n  // GET /stream — poll-based SSE. Mirrors the tunnel SSE style: set the\n  // event-stream headers, push frames, and clean up the interval on client\n  // disconnect. We poll storage on an interval using a `since` cursor and push\n  // only events/logs newer than the cursor. Resilient to storage being absent.\n  router.get(`${base}/stream`, async (req, res) => {\n    res.setHeader(\"Content-Type\", \"text/event-stream\");\n    res.setHeader(\"Cache-Control\", \"no-cache, no-transform\");\n    res.setHeader(\"Connection\", \"keep-alive\");\n    res.flushHeaders?.();\n\n    // Start the cursor at request time so we only stream NEW activity.\n    let cursor = intParam(req.query.since) ?? Date.now();\n\n    const send = (event: string, data: unknown): boolean =>\n      res.write(`event: ${event}\\ndata: ${JSON.stringify(data)}\\n\\n`);\n\n    // Immediately tell the client whether analytics is live.\n    send(\"status\", { enabled: getStorage() !== null });\n\n    let stopped = false;\n    const poll = async () => {\n      if (stopped) {\n        return;\n      }\n      const storage = getStorage();\n      if (!storage) {\n        // Heartbeat keeps the connection (and proxies) alive while OFF.\n        send(\"status\", { enabled: false });\n        return;\n      }\n      try {\n        const [events, logs] = await Promise.all([\n          storage.queryEvents({ since: cursor, limit: 200 }),\n          storage.queryLogs({ since: cursor, limit: 200 }),\n        ]);\n        // queryEvents/queryLogs are most-recent-first; advance the cursor past\n        // the newest ts so the next poll doesn't re-send the same rows.\n        const newest = Math.max(events[0]?.ts ?? 0, logs[0]?.ts ?? 0, cursor);\n        // Use `> cursor` so the same-ms boundary isn't dropped on the first\n        // pass but isn't re-sent afterward (cursor advances to newest + 1).\n        if (events.length > 0) {\n          send(\"events\", events);\n        }\n        if (logs.length > 0) {\n          send(\"logs\", logs);\n        }\n        if (newest >= cursor) {\n          cursor = newest + 1;\n        }\n      } catch {\n        // Swallow — a transient storage error must not kill the stream.\n      }\n    };\n\n    const timer = setInterval(() => void poll(), STREAM_POLL_MS);\n    const cleanup = () => {\n      stopped = true;\n      clearInterval(timer);\n      res.end();\n    };\n    req.on(\"close\", cleanup);\n  });\n\n  return router;\n}\n"]}

package/dist/server/observability.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/observability.test.js

@@ -0,0 +1,251 @@
+import express from "express";
+import { afterEach, describe, expect, it } from "vitest";
+import { createObservabilityRouter, percentile, summarize, } from "./observability.js";
+import { MemoryStorageAdapter } from "./storage/memory.js";
+function ev(p) {
+    return { ts: 0, type: "tool_call", ...p };
+}
+describe("percentile", () => {
+    it("returns 0 for an empty sample", () => {
+        expect(percentile([], 0.5)).toBe(0);
+        expect(percentile([], 0.95)).toBe(0);
+    });
+    it("returns the single value for a one-element sample", () => {
+        expect(percentile([42], 0.5)).toBe(42);
+    });
+    it("computes p50/p95 by nearest-rank interpolation", () => {
+        const s = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
+        expect(percentile(s, 0.5)).toBeCloseTo(55, 5);
+        expect(percentile(s, 0.95)).toBeCloseTo(95.5, 5);
+    });
+    it("tolerates a zero-latency sample (ms === 0)", () => {
+        expect(percentile([0, 0, 0], 0.5)).toBe(0);
+        expect(percentile([0, 10], 0.5)).toBe(5);
+    });
+});
+describe("summarize", () => {
+    it("aggregates totals, error rate, p50/p95, top tools, and buckets", () => {
+        const base = 1_000_000;
+        const events = [
+            ev({ ts: base + 0, tool: "echo", ms: 10, ok: true }),
+            ev({ ts: base + 1000, tool: "echo", ms: 20, ok: true }),
+            ev({ ts: base + 2000, tool: "echo", ms: 30, ok: false }),
+            ev({ ts: base + 70_000, tool: "search", ms: 100, ok: true }),
+            ev({ ts: base + 71_000, tool: "search", ms: 0, ok: true }),
+        ];
+        const s = summarize(events, { since: base, bucketMs: 60_000 });
+        expect(s.enabled).toBe(true);
+        expect(s.total).toBe(5);
+        expect(s.errors).toBe(1);
+        expect(s.errorRate).toBeCloseTo(0.2, 5);
+        // overall latencies sorted: [0,10,20,30,100]
+        expect(s.p50).toBe(20);
+        // Two 60s buckets: first has 3 (1 error), second has 2.
+        expect(s.callsOverTime).toHaveLength(2);
+        const [b0, b1] = s.callsOverTime;
+        expect(b0).toMatchObject({ count: 3, errors: 1 });
+        expect(b1).toMatchObject({ count: 2, errors: 0 });
+        // Buckets oldest-first.
+        expect(b0?.ts ?? 0).toBeLessThan(b1?.ts ?? 0);
+        // Top tools: echo (3) then search (2).
+        expect(s.topTools.map((t) => t.name)).toEqual(["echo", "search"]);
+        const [t0, t1] = s.topTools;
+        expect(t0).toMatchObject({ count: 3, errors: 1 });
+        expect(t0?.errorRate ?? 0).toBeCloseTo(1 / 3, 5);
+        expect(t1).toMatchObject({ count: 2, errors: 0 });
+    });
+    it("counts a thrown error (ok undefined + error set) as an error", () => {
+        const s = summarize([ev({ ts: 1, error: "boom" }), ev({ ts: 2, ok: true, ms: 5 })], { since: 0 });
+        expect(s.errors).toBe(1);
+        expect(s.errorRate).toBe(0.5);
+    });
+    it("excludes timing-less events from percentiles but counts them in totals", () => {
+        const s = summarize([ev({ ts: 1, ok: true }), ev({ ts: 2, ok: true, ms: 50 })], { since: 0 });
+        expect(s.total).toBe(2);
+        // Only one event has ms → p50 is that value.
+        expect(s.p50).toBe(50);
+    });
+    it("returns zeroed aggregates (not NaN) for no events", () => {
+        const s = summarize([], { since: 0 });
+        expect(s).toMatchObject({
+            total: 0,
+            errors: 0,
+            errorRate: 0,
+            p50: 0,
+            p95: 0,
+            p99: 0,
+            avg: 0,
+            throughputPerMin: 0,
+            callsOverTime: [],
+            topTools: [],
+            slowestTools: [],
+            byMethod: [],
+        });
+        // The histogram always has fixed buckets; they're just all zero.
+        expect(s.latencyHistogram.every((b) => b.count === 0)).toBe(true);
+    });
+    it("computes p99 + avg overall and per-tool", () => {
+        const events = [];
+        // echo: latencies 1..100 → avg 50.5, p99 ~99
+        for (let i = 1; i <= 100; i++) {
+            events.push(ev({ ts: i, tool: "echo", ms: i, ok: true }));
+        }
+        const s = summarize(events, { since: 0 });
+        expect(s.avg).toBeCloseTo(50.5, 5);
+        // nearest-rank: p99 of 1..100 → 99 + 0.01 interp
+        expect(s.p99).toBeCloseTo(99, 0);
+        const echo = s.topTools.find((t) => t.name === "echo");
+        expect(echo?.avg).toBeCloseTo(50.5, 5);
+        expect(echo?.p99).toBeGreaterThan(echo?.p95 ?? 0);
+    });
+    it("groups calls by method and ranks slowest tools by p95", () => {
+        const s = summarize([
+            ev({ ts: 1, tool: "fast", method: "tools/call", ms: 5, ok: true }),
+            ev({ ts: 2, tool: "fast", method: "tools/call", ms: 7, ok: true }),
+            ev({ ts: 3, tool: "slow", method: "tools/call", ms: 900, ok: true }),
+            ev({ ts: 4, method: "tools/list", ms: 2, ok: true }),
+        ], { since: 0 });
+        // byMethod descending by count: tools/call (3) then tools/list (1)
+        expect(s.byMethod.map((m) => m.method)).toEqual([
+            "tools/call",
+            "tools/list",
+        ]);
+        expect(s.byMethod[0]?.count).toBe(3);
+        // slowest by p95: slow first
+        expect(s.slowestTools[0]?.name).toBe("slow");
+    });
+    it("buckets latencies into a fixed histogram", () => {
+        const s = summarize([
+            ev({ ts: 1, tool: "a", ms: 5, ok: true }), // [0,10)
+            ev({ ts: 2, tool: "a", ms: 5, ok: true }), // [0,10)
+            ev({ ts: 3, tool: "a", ms: 30, ok: true }), // [25,50)
+            ev({ ts: 4, tool: "a", ms: 3000, ok: true }), // >=2500
+        ], { since: 0 });
+        const total = s.latencyHistogram.reduce((n, b) => n + b.count, 0);
+        expect(total).toBe(4);
+        const first = s.latencyHistogram.find((b) => b.from === 0);
+        expect(first?.count).toBe(2);
+        const top = s.latencyHistogram.find((b) => b.to === null);
+        expect(top?.count).toBe(1);
+    });
+    it("falls back to method then 'unknown' for the tool name", () => {
+        const s = summarize([ev({ ts: 1, method: "initialize", ms: 1 }), ev({ ts: 2, ms: 1 })], { since: 0 });
+        const names = s.topTools.map((t) => t.name).sort();
+        expect(names).toEqual(["initialize", "unknown"]);
+    });
+});
+describe("summarize — bucket size per range (M9)", () => {
+    const MINUTE = 60_000;
+    const HOUR = 60 * MINUTE;
+    const DAY = 24 * HOUR;
+    const base = 1_700_000_000_000;
+    // One event at the start of each of 14 consecutive days.
+    const daily = Array.from({ length: 14 }, (_, i) => ev({ ts: base + i * DAY, tool: "echo", ms: 5, ok: true }));
+    it("echoes the chosen bucketMs and aligns buckets to it", () => {
+        for (const bucketMs of [MINUTE, HOUR, 6 * HOUR, DAY]) {
+            const s = summarize(daily, { since: base, bucketMs });
+            expect(s.bucketMs).toBe(bucketMs);
+            // Every bucket start is aligned to bucketMs.
+            for (const b of s.callsOverTime) {
+                expect(b.ts % bucketMs).toBe(0);
+            }
+        }
+    });
+    it("daily buckets (30d range): 14 daily events → 14 buckets", () => {
+        const s = summarize(daily, { since: base, bucketMs: DAY });
+        expect(s.callsOverTime).toHaveLength(14);
+        expect(s.callsOverTime.every((b) => b.count === 1)).toBe(true);
+    });
+    it("6h buckets (7d range) keep each daily event in its own bucket", () => {
+        const s = summarize(daily, { since: base, bucketMs: 6 * HOUR });
+        // Events are a full day apart, so no two share a 6h bucket.
+        expect(s.callsOverTime).toHaveLength(14);
+    });
+    it("coarser buckets merge sub-bucket events; finer buckets split them", () => {
+        // Two events 90 minutes apart.
+        const pair = [
+            ev({ ts: base, tool: "echo", ms: 1, ok: true }),
+            ev({ ts: base + 90 * MINUTE, tool: "echo", ms: 1, ok: true }),
+        ];
+        // Minute buckets (1h range): two distinct buckets.
+        expect(summarize(pair, { since: base, bucketMs: MINUTE }).callsOverTime).toHaveLength(2);
+        // Hourly buckets (24h range): still two (they straddle the hour boundary).
+        expect(summarize(pair, { since: base, bucketMs: HOUR }).callsOverTime).toHaveLength(2);
+        // Daily buckets (30d range): both fall in one day → a single bucket of 2.
+        const dayBuckets = summarize(pair, {
+            since: base,
+            bucketMs: DAY,
+        }).callsOverTime;
+        expect(dayBuckets).toHaveLength(1);
+        expect(dayBuckets[0]?.count).toBe(2);
+    });
+});
+// --- Router behaviour (incl. the disabled/no-storage path) ---
+const servers = [];
+afterEach(async () => {
+    while (servers.length > 0) {
+        await servers.pop()?.close();
+    }
+});
+async function mount(getStorage) {
+    const app = express();
+    app.use(createObservabilityRouter(getStorage));
+    const server = app.listen(0, "127.0.0.1");
+    await new Promise((resolve) => server.once("listening", resolve));
+    const port = server.address().port;
+    servers.push({
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections?.();
+            server.close(() => resolve());
+        }),
+    });
+    return `http://127.0.0.1:${port}`;
+}
+describe("createObservabilityRouter (disabled / no storage)", () => {
+    it("returns 200 { enabled: false } empty payloads, never 500", async () => {
+        const url = await mount(() => null);
+        const summary = await fetch(`${url}/__enpilink/observability/summary`);
+        expect(summary.status).toBe(200);
+        expect(await summary.json()).toMatchObject({
+            enabled: false,
+            total: 0,
+            callsOverTime: [],
+            topTools: [],
+        });
+        const events = await fetch(`${url}/__enpilink/observability/events`);
+        expect(events.status).toBe(200);
+        expect(await events.json()).toEqual({ enabled: false, events: [] });
+        const logs = await fetch(`${url}/__enpilink/observability/logs`);
+        expect(logs.status).toBe(200);
+        expect(await logs.json()).toEqual({ enabled: false, logs: [] });
+    });
+});
+describe("createObservabilityRouter (with storage)", () => {
+    it("serves a real summary + events from the active adapter", async () => {
+        const storage = new MemoryStorageAdapter();
+        await storage.init();
+        await storage.recordEvent(ev({ ts: Date.now(), tool: "echo", ms: 5, ok: true }));
+        await storage.recordEvent(ev({ ts: Date.now(), tool: "echo", ms: 15, ok: false }));
+        const url = await mount(() => storage);
+        const summary = await (await fetch(`${url}/__enpilink/observability/summary?since=0`)).json();
+        expect(summary.enabled).toBe(true);
+        expect(summary.total).toBe(2);
+        expect(summary.errors).toBe(1);
+        expect(summary.topTools[0].name).toBe("echo");
+        const events = await (await fetch(`${url}/__enpilink/observability/events?since=0`)).json();
+        expect(events.enabled).toBe(true);
+        expect(events.events).toHaveLength(2);
+    });
+    it("returns a 200 empty summary (not 500) when storage throws", async () => {
+        const broken = {
+            queryEvents: async () => {
+                throw new Error("db down");
+            },
+        };
+        const url = await mount(() => broken);
+        const res = await fetch(`${url}/__enpilink/observability/summary`);
+        expect(res.status).toBe(200);
+        expect(await res.json()).toMatchObject({ enabled: false, total: 0 });
+    });
+});
+//# sourceMappingURL=observability.test.js.map