@runcore-sh/runcore 0.1.2

package/dist/metrics/middleware.js

@@ -0,0 +1,47 @@
+/**
+ * Hono middleware for automatic HTTP request metrics collection.
+ * Measures request duration, status codes, and concurrent requests.
+ * Records to both the time-series collector and Prometheus instruments.
+ */
+import { recordHttp, recordConcurrentRequests } from "./collector.js";
+import { apiCallsTotal, apiCallDuration, httpRequestsTotal, httpRequestDurationSeconds, concurrentRequests, } from "./prometheus.js";
+/**
+ * Metrics middleware — records request duration, status code, and concurrent requests.
+ * Attach early in the middleware chain (before routes).
+ */
+export function metricsMiddleware() {
+    return async (c, next) => {
+        // Track concurrent requests
+        concurrentRequests.inc();
+        recordConcurrentRequests(1);
+        const start = performance.now();
+        try {
+            await next();
+        }
+        finally {
+            const durationMs = performance.now() - start;
+            const status = c.res.status;
+            const method = c.req.method;
+            const endpoint = normalizePath(c.req.path);
+            // Decrement concurrent requests
+            concurrentRequests.dec();
+            recordConcurrentRequests(-1);
+            // Time-series store (JSONL)
+            recordHttp(Math.round(durationMs), status, method, endpoint);
+            // Legacy Prometheus instruments
+            apiCallsTotal.inc({ method, path: endpoint, status: String(status) });
+            apiCallDuration.observe({ method, path: endpoint }, durationMs / 1000);
+            // DASH-43: New HTTP request instruments
+            httpRequestsTotal.inc({ endpoint, method, status: String(status) });
+            httpRequestDurationSeconds.observe({ endpoint, method }, durationMs / 1000);
+        }
+    };
+}
+/** Normalize path to avoid high-cardinality label values. */
+function normalizePath(path) {
+    // Replace UUIDs and numeric IDs with placeholders
+    return path
+        .replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "/:id")
+        .replace(/\/\d+/g, "/:id");
+}
+//# sourceMappingURL=middleware.js.map

package/dist/metrics/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/metrics/middleware.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,4BAA4B;QAC5B,kBAAkB,CAAC,GAAG,EAAE,CAAC;QACzB,wBAAwB,CAAC,CAAC,CAAC,CAAC;QAE5B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,IAAI,EAAE,CAAC;QACf,CAAC;gBAAS,CAAC;YACT,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;YAC7C,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;YAC5B,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;YAC5B,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAE3C,gCAAgC;YAChC,kBAAkB,CAAC,GAAG,EAAE,CAAC;YACzB,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC;YAE7B,4BAA4B;YAC5B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;YAE7D,gCAAgC;YAChC,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACtE,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC;YAEvE,wCAAwC;YACxC,iBAAiB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACpE,0BAA0B,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,SAAS,aAAa,CAAC,IAAY;IACjC,kDAAkD;IAClD,OAAO,IAAI;SACR,OAAO,CAAC,kEAAkE,EAAE,MAAM,CAAC;SACnF,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC/B,CAAC"}

package/dist/metrics/prometheus.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Prometheus metrics integration.
+ * Registers standard Core metrics and provides a collection function
+ * that updates gauges from process stats before exposition.
+ *
+ * Usage in server.ts:
+ *   import { initPrometheus, collectPrometheus, prometheusRegistry } from "./metrics/prometheus.js";
+ *   initPrometheus();
+ *   app.get("/metrics", (c) => {
+ *     const body = collectPrometheus();
+ *     return c.text(body, 200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+ *   });
+ */
+import { MetricRegistry } from "./registry.js";
+import { Counter, Gauge, Histogram } from "./instruments.js";
+export declare const prometheusRegistry: MetricRegistry;
+export declare const agentSpawnsTotal: Counter;
+export declare const agentExecutionsTotal: Counter;
+export declare const apiCallsTotal: Counter;
+export declare const httpRequestsTotal: Counter;
+export declare const httpRequestDurationSeconds: Histogram;
+export declare const concurrentRequests: Gauge;
+export declare const errorsTotal: Counter;
+export declare const agentExecutionDuration: Histogram;
+export declare const apiCallDuration: Histogram;
+export declare const memoryUsageBytes: Gauge;
+export declare const agentExecutionsInFlight: Gauge;
+export declare const agentSuccessRate: Gauge;
+export declare const agentMemoryUsageBytes: Gauge;
+export declare const uptimeSeconds: Gauge;
+export declare const cpuUsagePercent: Gauge;
+export declare const eventLoopDriftSeconds: Gauge;
+export declare const diskUsageBytes: Gauge;
+/**
+ * Collect all Prometheus metrics, updating process gauges first.
+ * Returns Prometheus text exposition format.
+ */
+export declare function collectPrometheus(): string;
+//# sourceMappingURL=prometheus.d.ts.map

package/dist/metrics/prometheus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prometheus.d.ts","sourceRoot":"","sources":["../../src/metrics/prometheus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAI7D,eAAO,MAAM,kBAAkB,gBAAuB,CAAC;AAGvD,eAAO,MAAM,gBAAgB,SAG3B,CAAC;AAEH,eAAO,MAAM,oBAAoB,SAI/B,CAAC;AAEH,eAAO,MAAM,aAAa,SAIxB,CAAC;AAGH,eAAO,MAAM,iBAAiB,SAI5B,CAAC;AAEH,eAAO,MAAM,0BAA0B,WAKrC,CAAC;AAEH,eAAO,MAAM,kBAAkB,OAG7B,CAAC;AAEH,eAAO,MAAM,WAAW,SAItB,CAAC;AAGH,eAAO,MAAM,sBAAsB,WAKjC,CAAC;AAEH,eAAO,MAAM,eAAe,WAK1B,CAAC;AAGH,eAAO,MAAM,gBAAgB,OAI3B,CAAC;AAEH,eAAO,MAAM,uBAAuB,OAGlC,CAAC;AAEH,eAAO,MAAM,gBAAgB,OAG3B,CAAC;AAEH,eAAO,MAAM,qBAAqB,OAGhC,CAAC;AAEH,eAAO,MAAM,aAAa,OAGxB,CAAC;AAEH,eAAO,MAAM,eAAe,OAG1B,CAAC;AAEH,eAAO,MAAM,qBAAqB,OAGhC,CAAC;AAEH,eAAO,MAAM,cAAc,OAGzB,CAAC;AAIH;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C"}

package/dist/metrics/prometheus.js

@@ -0,0 +1,115 @@
+/**
+ * Prometheus metrics integration.
+ * Registers standard Core metrics and provides a collection function
+ * that updates gauges from process stats before exposition.
+ *
+ * Usage in server.ts:
+ *   import { initPrometheus, collectPrometheus, prometheusRegistry } from "./metrics/prometheus.js";
+ *   initPrometheus();
+ *   app.get("/metrics", (c) => {
+ *     const body = collectPrometheus();
+ *     return c.text(body, 200, { "Content-Type": "text/plain; version=0.0.4; charset=utf-8" });
+ *   });
+ */
+import { MetricRegistry } from "./registry.js";
+// ─── Global registry and instruments ─────────────────────────────────────────
+export const prometheusRegistry = new MetricRegistry();
+// Counters
+export const agentSpawnsTotal = prometheusRegistry.registerCounter({
+    name: "agent_spawns_total",
+    help: "Total number of agent spawns",
+});
+export const agentExecutionsTotal = prometheusRegistry.registerCounter({
+    name: "agent_executions_total",
+    help: "Total number of agent executions",
+    labelNames: ["status"],
+});
+export const apiCallsTotal = prometheusRegistry.registerCounter({
+    name: "api_calls_total",
+    help: "Total number of API calls",
+    labelNames: ["method", "path", "status"],
+});
+// DASH-43: HTTP request metrics for API performance monitoring
+export const httpRequestsTotal = prometheusRegistry.registerCounter({
+    name: "http_requests_total",
+    help: "Total HTTP requests by endpoint, method, and status",
+    labelNames: ["endpoint", "method", "status"],
+});
+export const httpRequestDurationSeconds = prometheusRegistry.registerHistogram({
+    name: "http_request_duration_seconds",
+    help: "HTTP request duration in seconds",
+    labelNames: ["endpoint", "method"],
+    buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+});
+export const concurrentRequests = prometheusRegistry.registerGauge({
+    name: "concurrent_requests",
+    help: "Number of HTTP requests currently in flight",
+});
+export const errorsTotal = prometheusRegistry.registerCounter({
+    name: "errors_total",
+    help: "Total number of errors",
+    labelNames: ["source"],
+});
+// Histograms
+export const agentExecutionDuration = prometheusRegistry.registerHistogram({
+    name: "agent_execution_duration_seconds",
+    help: "Duration of agent executions in seconds",
+    labelNames: ["status"],
+    buckets: [0.1, 0.5, 1, 5, 10, 30, 60, 120, 300, 600],
+});
+export const apiCallDuration = prometheusRegistry.registerHistogram({
+    name: "api_call_duration_seconds",
+    help: "Duration of API calls in seconds",
+    labelNames: ["method", "path"],
+    buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+});
+// Gauges
+export const memoryUsageBytes = prometheusRegistry.registerGauge({
+    name: "memory_usage_bytes",
+    help: "Process memory usage in bytes",
+    labelNames: ["type"],
+});
+export const agentExecutionsInFlight = prometheusRegistry.registerGauge({
+    name: "agent_executions_in_flight",
+    help: "Number of agent executions currently in progress",
+});
+export const agentSuccessRate = prometheusRegistry.registerGauge({
+    name: "agent_success_rate",
+    help: "Agent execution success rate (0-1)",
+});
+export const agentMemoryUsageBytes = prometheusRegistry.registerGauge({
+    name: "agent_memory_usage_bytes",
+    help: "Process memory usage during agent execution in bytes",
+});
+export const uptimeSeconds = prometheusRegistry.registerGauge({
+    name: "process_uptime_seconds",
+    help: "Process uptime in seconds",
+});
+export const cpuUsagePercent = prometheusRegistry.registerGauge({
+    name: "cpu_usage_percent",
+    help: "CPU usage percentage",
+});
+export const eventLoopDriftSeconds = prometheusRegistry.registerGauge({
+    name: "event_loop_drift_seconds",
+    help: "Event loop drift in seconds",
+});
+export const diskUsageBytes = prometheusRegistry.registerGauge({
+    name: "disk_usage_bytes",
+    help: "Total size of the brain/ directory in bytes",
+});
+// ─── Collection ──────────────────────────────────────────────────────────────
+/**
+ * Collect all Prometheus metrics, updating process gauges first.
+ * Returns Prometheus text exposition format.
+ */
+export function collectPrometheus() {
+    // Update process gauges before collection
+    const mem = process.memoryUsage();
+    memoryUsageBytes.set({ type: "heap_used" }, mem.heapUsed);
+    memoryUsageBytes.set({ type: "heap_total" }, mem.heapTotal);
+    memoryUsageBytes.set({ type: "rss" }, mem.rss);
+    memoryUsageBytes.set({ type: "external" }, mem.external);
+    uptimeSeconds.set(undefined, process.uptime());
+    return prometheusRegistry.collect();
+}
+//# sourceMappingURL=prometheus.js.map

package/dist/metrics/prometheus.js.map

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

package/dist/metrics/registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Prometheus-style metric registry.
+ * Holds all registered instruments and provides collection + format output.
+ *
+ * Pluggable: default is in-memory (instruments hold their own state).
+ * Swap the store backend to persist to a different system.
+ */
+import { Counter, Gauge, Histogram, type Labels } from "./instruments.js";
+/** Backend store for metric values. Default: in-memory (Map inside each instrument). */
+export interface MetricStoreBackend {
+    /** Called when a counter is incremented. */
+    counterInc(name: string, labels: Labels, value: number): void;
+    /** Called when a gauge is set. */
+    gaugeSet(name: string, labels: Labels, value: number): void;
+    /** Called when a histogram observation is recorded. */
+    histogramObserve(name: string, labels: Labels, value: number): void;
+}
+export type MetricType = "counter" | "gauge" | "histogram";
+interface RegisteredMetric {
+    type: MetricType;
+    instrument: Counter | Gauge | Histogram;
+}
+export declare class MetricRegistry {
+    private metrics;
+    private backend;
+    constructor(backend?: MetricStoreBackend);
+    /** Register and return a new Counter. */
+    registerCounter(opts: {
+        name: string;
+        help: string;
+        labelNames?: string[];
+    }): Counter;
+    /** Register and return a new Gauge. */
+    registerGauge(opts: {
+        name: string;
+        help: string;
+        labelNames?: string[];
+    }): Gauge;
+    /** Register and return a new Histogram. */
+    registerHistogram(opts: {
+        name: string;
+        help: string;
+        labelNames?: string[];
+        buckets?: number[];
+    }): Histogram;
+    /** Get a registered metric by name. */
+    getMetric(name: string): RegisteredMetric | undefined;
+    /** List all registered metric names. */
+    getMetricNames(): string[];
+    /** Swap the store backend at runtime. */
+    setBackend(backend: MetricStoreBackend): void;
+    /** Collect all metrics and return Prometheus text exposition format. */
+    collect(): string;
+    /** Reset all metrics. */
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/metrics/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/metrics/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,MAAM,EAAsC,MAAM,kBAAkB,CAAC;AAI9G,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5D,uDAAuD;IACvD,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACrE;AAWD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;AAE3D,UAAU,gBAAgB;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;CACzC;AAID,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,OAAO,CAAqB;gBAExB,OAAO,CAAC,EAAE,kBAAkB;IAIxC,yCAAyC;IACzC,eAAe,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO;IAWrF,uCAAuC;IACvC,aAAa,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,KAAK;IAWjF,2CAA2C;IAC3C,iBAAiB,CAAC,IAAI,EAAE;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,GAAG,SAAS;IAWb,uCAAuC;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIrD,wCAAwC;IACxC,cAAc,IAAI,MAAM,EAAE;IAI1B,yCAAyC;IACzC,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAI7C,wEAAwE;IACxE,OAAO,IAAI,MAAM;IA6CjB,yBAAyB;IACzB,KAAK,IAAI,IAAI;CAKd"}

package/dist/metrics/registry.js

@@ -0,0 +1,145 @@
+/**
+ * Prometheus-style metric registry.
+ * Holds all registered instruments and provides collection + format output.
+ *
+ * Pluggable: default is in-memory (instruments hold their own state).
+ * Swap the store backend to persist to a different system.
+ */
+import { Counter, Gauge, Histogram } from "./instruments.js";
+/** Default no-op backend — instruments manage their own in-memory state. */
+class InMemoryBackend {
+    counterInc() { }
+    gaugeSet() { }
+    histogramObserve() { }
+}
+// ─── Registry ────────────────────────────────────────────────────────────────
+export class MetricRegistry {
+    metrics = new Map();
+    backend;
+    constructor(backend) {
+        this.backend = backend ?? new InMemoryBackend();
+    }
+    /** Register and return a new Counter. */
+    registerCounter(opts) {
+        if (this.metrics.has(opts.name)) {
+            const existing = this.metrics.get(opts.name);
+            if (existing.type !== "counter")
+                throw new Error(`Metric "${opts.name}" already registered as ${existing.type}`);
+            return existing.instrument;
+        }
+        const counter = new Counter(opts);
+        this.metrics.set(opts.name, { type: "counter", instrument: counter });
+        return counter;
+    }
+    /** Register and return a new Gauge. */
+    registerGauge(opts) {
+        if (this.metrics.has(opts.name)) {
+            const existing = this.metrics.get(opts.name);
+            if (existing.type !== "gauge")
+                throw new Error(`Metric "${opts.name}" already registered as ${existing.type}`);
+            return existing.instrument;
+        }
+        const gauge = new Gauge(opts);
+        this.metrics.set(opts.name, { type: "gauge", instrument: gauge });
+        return gauge;
+    }
+    /** Register and return a new Histogram. */
+    registerHistogram(opts) {
+        if (this.metrics.has(opts.name)) {
+            const existing = this.metrics.get(opts.name);
+            if (existing.type !== "histogram")
+                throw new Error(`Metric "${opts.name}" already registered as ${existing.type}`);
+            return existing.instrument;
+        }
+        const histogram = new Histogram(opts);
+        this.metrics.set(opts.name, { type: "histogram", instrument: histogram });
+        return histogram;
+    }
+    /** Get a registered metric by name. */
+    getMetric(name) {
+        return this.metrics.get(name);
+    }
+    /** List all registered metric names. */
+    getMetricNames() {
+        return Array.from(this.metrics.keys());
+    }
+    /** Swap the store backend at runtime. */
+    setBackend(backend) {
+        this.backend = backend;
+    }
+    /** Collect all metrics and return Prometheus text exposition format. */
+    collect() {
+        const lines = [];
+        for (const [name, { type, instrument }] of this.metrics) {
+            lines.push(`# HELP ${name} ${instrument.help}`);
+            lines.push(`# TYPE ${name} ${type}`);
+            if (instrument instanceof Counter || instrument instanceof Gauge) {
+                const samples = instrument.collect();
+                if (samples.length === 0) {
+                    // Emit a zero-value sample for metrics with no observations
+                    lines.push(`${name} 0`);
+                }
+                else {
+                    for (const sample of samples) {
+                        lines.push(formatSample(name, sample.labels, sample.value));
+                    }
+                }
+            }
+            else if (instrument instanceof Histogram) {
+                const data = instrument.collect();
+                if (data.counts.length === 0) {
+                    // No observations yet
+                    lines.push(`${name}_bucket{le="+Inf"} 0`);
+                    lines.push(`${name}_sum 0`);
+                    lines.push(`${name}_count 0`);
+                }
+                else {
+                    for (const bucket of data.buckets) {
+                        const leStr = bucket.le === Infinity ? "+Inf" : String(bucket.le);
+                        const labelStr = formatLabels({ ...bucket.labels, le: leStr });
+                        lines.push(`${name}_bucket${labelStr} ${bucket.count}`);
+                    }
+                    for (const s of data.sums) {
+                        lines.push(formatSample(`${name}_sum`, s.labels, s.value));
+                    }
+                    for (const s of data.counts) {
+                        lines.push(formatSample(`${name}_count`, s.labels, s.value));
+                    }
+                }
+            }
+            lines.push(""); // blank line between metrics
+        }
+        return lines.join("\n");
+    }
+    /** Reset all metrics. */
+    reset() {
+        for (const { instrument } of this.metrics.values()) {
+            instrument.reset();
+        }
+    }
+}
+// ─── Format helpers ──────────────────────────────────────────────────────────
+function formatLabels(labels) {
+    const entries = Object.entries(labels);
+    if (entries.length === 0)
+        return "";
+    const parts = entries.map(([k, v]) => `${k}="${escapeLabel(v)}"`);
+    return `{${parts.join(",")}}`;
+}
+function formatSample(name, labels, value) {
+    const labelStr = formatLabels(labels);
+    return `${name}${labelStr} ${formatValue(value)}`;
+}
+function formatValue(v) {
+    if (v === Infinity)
+        return "+Inf";
+    if (v === -Infinity)
+        return "-Inf";
+    if (Number.isNaN(v))
+        return "NaN";
+    return String(v);
+}
+function escapeLabel(v) {
+    return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+//# sourceMappingURL=registry.js.map

package/dist/metrics/registry.js.map

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

package/dist/metrics/reporter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Metrics reporter — dashboard snapshots and alert evaluation.
+ * Follows health/checker.ts pattern: configurable thresholds, aggregated output.
+ */
+import type { AlertThreshold, Alert, DashboardSnapshot } from "./types.js";
+import { MetricsStore } from "./store.js";
+/** Register built-in alert thresholds for common system metrics. */
+export declare function registerDefaultThresholds(): void;
+/** Register an alert threshold. */
+export declare function registerThreshold(t: AlertThreshold): void;
+/** Clear all thresholds. */
+export declare function clearThresholds(): void;
+/** Get all registered thresholds. */
+export declare function getThresholds(): readonly AlertThreshold[];
+/** Evaluate all thresholds against current data. Returns newly fired alerts. */
+export declare function evaluateAlerts(store: MetricsStore): Promise<Alert[]>;
+/** Get recent alerts. */
+export declare function getRecentAlerts(limit?: number): Alert[];
+/** Build a dashboard snapshot from the metrics store. */
+export declare function buildDashboard(store: MetricsStore): Promise<DashboardSnapshot>;
+//# sourceMappingURL=reporter.d.ts.map

package/dist/metrics/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../src/metrics/reporter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EAEL,iBAAiB,EAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAgB1C,oEAAoE;AACpE,wBAAgB,yBAAyB,IAAI,IAAI,CAoChD;AAID,mCAAmC;AACnC,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI,CAEzD;AAED,4BAA4B;AAC5B,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,qCAAqC;AACrC,wBAAgB,aAAa,IAAI,SAAS,cAAc,EAAE,CAEzD;AAID,gFAAgF;AAChF,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CA+D1E;AAED,yBAAyB;AACzB,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE,CAGvD;AAID,yDAAyD;AACzD,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+DpF"}