@wrongstack/core 0.313.1 → 0.316.2

package/dist/observability/index.js

@@ -10,10 +10,151 @@ import {
   runWithNetworkTelemetry,
   startNetworkTelemetryMonitor
 } from "../chunk-HA4ZYA6T.js";
+import "../chunk-PFZO3C6H.js";
 import {
   toErrorMessage
 } from "../chunk-TBRL2RCC.js";
-import "../chunk-PFZO3C6H.js";
+
+// src/observability/event-bridge.ts
+function wireMetricsToEvents(events, sink) {
+  const unsubs = [];
+  const toolUsage = /* @__PURE__ */ new Map();
+  const record = (name, ok, durationMs) => {
+    const metricName = metricToolName(name);
+    const now = Date.now();
+    const existing = toolUsage.get(metricName);
+    if (existing) {
+      existing.invocations += 1;
+      if (!ok) existing.failures += 1;
+      existing.durationMsTotal += durationMs;
+      existing.lastInvokedAt = now;
+    } else {
+      toolUsage.set(metricName, {
+        invocations: 1,
+        failures: ok ? 0 : 1,
+        durationMsTotal: durationMs,
+        lastInvokedAt: now,
+        firstInvokedAt: now
+      });
+    }
+  };
+  unsubs.push(
+    events.on("session.started", () => sink.counter("agent.sessions.started")),
+    events.on("session.ended", (e) => {
+      sink.counter("agent.sessions.ended");
+      sink.histogram("agent.session.tokens.input", e.usage.input);
+      sink.histogram("agent.session.tokens.output", e.usage.output);
+    }),
+    events.on("session.damaged", () => sink.counter("agent.sessions.damaged")),
+    events.on("iteration.completed", () => sink.counter("agent.iterations.total")),
+    events.on("iteration.limit_reached", () => sink.counter("agent.iteration_limit.hit")),
+    events.on("provider.response", (e) => {
+      sink.counter("provider.responses.total", 1, { stop_reason: e.stopReason });
+      sink.counter("provider.tokens.input", e.usage.input);
+      sink.counter("provider.tokens.output", e.usage.output);
+      if (e.usage.cacheRead) sink.counter("provider.tokens.cache_read", e.usage.cacheRead);
+      if (e.usage.cacheWrite) sink.counter("provider.tokens.cache_write", e.usage.cacheWrite);
+    }),
+    events.on(
+      "provider.retry",
+      (e) => sink.counter("provider.retries.total", 1, {
+        provider: e.providerId,
+        status: String(e.status)
+      })
+    ),
+    events.on(
+      "provider.error",
+      (e) => sink.counter("provider.errors.total", 1, {
+        provider: e.providerId,
+        status: String(e.status),
+        retryable: String(e.retryable)
+      })
+    ),
+    events.on("tool.started", (e) => {
+      sink.counter("tool.starts.total", 1, { tool: metricToolName(e.name) });
+      record(e.name, true, 0);
+    }),
+    events.on("tool.executed", (e) => {
+      const tool = metricToolName(e.name);
+      sink.counter("tool.executions.total", 1, { tool, ok: String(e.ok) });
+      sink.histogram("tool.duration_ms", e.durationMs, { tool });
+      record(e.name, e.ok, e.durationMs);
+    }),
+    events.on("token.threshold", (e) => sink.gauge("agent.tokens.used", e.used)),
+    events.on("compaction.fired", (e) => {
+      sink.counter("compaction.fired.total");
+      sink.histogram("compaction.reduction_tokens", e.report.before - e.report.after);
+    }),
+    // MCP server names are user-controlled and may contain tenant/project
+    // identifiers. Keep them out of metric labels to bound cardinality and
+    // prevent operational metadata leaks.
+    events.on("mcp.server.connected", () => sink.counter("mcp.connects.total")),
+    events.on("mcp.server.reconnected", () => sink.counter("mcp.reconnects.total")),
+    events.on("mcp.server.disconnected", () => sink.counter("mcp.disconnects.total")),
+    events.on("error", (e) => sink.counter("agent.errors.total", 1, { phase: e.phase }))
+  );
+  return {
+    sink,
+    getToolUsage() {
+      return toolUsage;
+    },
+    dispose() {
+      for (const u of unsubs) u();
+    }
+  };
+}
+function metricToolName(name) {
+  return name.startsWith("mcp__") ? "mcp_proxy" : name;
+}
+
+// src/observability/health.ts
+var SEVERITY = {
+  healthy: 0,
+  degraded: 1,
+  unhealthy: 2
+};
+var DefaultHealthRegistry = class {
+  checks = /* @__PURE__ */ new Map();
+  timeoutMs;
+  constructor(opts = {}) {
+    this.timeoutMs = opts.timeoutMs ?? 5e3;
+  }
+  register(check) {
+    this.checks.set(check.name, check);
+  }
+  unregister(name) {
+    this.checks.delete(name);
+  }
+  async run() {
+    const results = await Promise.all(
+      Array.from(this.checks.values()).map(async (c) => {
+        const result = await this.runOne(c);
+        return { name: c.name, ...result };
+      })
+    );
+    let status = "healthy";
+    for (const r of results) {
+      if (SEVERITY[r.status] > SEVERITY[status]) status = r.status;
+    }
+    return { status, timestamp: Date.now(), checks: results };
+  }
+  async runOne(check) {
+    let timer = null;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(
+        () => resolve({ status: "unhealthy", detail: `timeout after ${this.timeoutMs}ms` }),
+        this.timeoutMs
+      );
+    });
+    try {
+      return await Promise.race([check.check(), timeout]);
+    } catch (err) {
+      return { status: "unhealthy", detail: toErrorMessage(err) };
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+};
 
 // src/observability/metrics.ts
 var RESERVOIR_SIZE = 1024;
@@ -187,357 +328,59 @@ var InMemoryMetricsSink = class {
   }
 };
 function parseLabelKey(key) {
-  if (!key) return {};
-  const labels = {};
-  for (const pair of key.split(",")) {
-    const eq = pair.indexOf("=");
-    if (eq > 0) labels[pair.slice(0, eq)] = pair.slice(eq + 1);
-  }
-  return labels;
-}
-var NoopMetricsSink = class {
-  counter() {
-  }
-  gauge() {
-  }
-  histogram() {
-  }
-  snapshot() {
-    return { timestamp: Date.now(), series: [] };
-  }
-  droppedObservations() {
-    return 0;
-  }
-  reset() {
-  }
-};
-
-// src/observability/health.ts
-var SEVERITY = {
-  healthy: 0,
-  degraded: 1,
-  unhealthy: 2
-};
-var DefaultHealthRegistry = class {
-  checks = /* @__PURE__ */ new Map();
-  timeoutMs;
-  constructor(opts = {}) {
-    this.timeoutMs = opts.timeoutMs ?? 5e3;
-  }
-  register(check) {
-    this.checks.set(check.name, check);
-  }
-  unregister(name) {
-    this.checks.delete(name);
-  }
-  async run() {
-    const results = await Promise.all(
-      Array.from(this.checks.values()).map(async (c) => {
-        const result = await this.runOne(c);
-        return { name: c.name, ...result };
-      })
-    );
-    let status = "healthy";
-    for (const r of results) {
-      if (SEVERITY[r.status] > SEVERITY[status]) status = r.status;
-    }
-    return { status, timestamp: Date.now(), checks: results };
-  }
-  async runOne(check) {
-    let timer = null;
-    const timeout = new Promise((resolve) => {
-      timer = setTimeout(
-        () => resolve({ status: "unhealthy", detail: `timeout after ${this.timeoutMs}ms` }),
-        this.timeoutMs
-      );
-    });
-    try {
-      return await Promise.race([check.check(), timeout]);
-    } catch (err) {
-      return { status: "unhealthy", detail: toErrorMessage(err) };
-    } finally {
-      if (timer) clearTimeout(timer);
-    }
-  }
-};
-
-// src/observability/tracer.ts
-var NoopTracer = class {
-  startSpan() {
-    return NOOP_SPAN;
-  }
-};
-var NOOP_SPAN = {
-  setAttribute() {
-  },
-  recordError() {
-  },
-  end() {
-  }
-};
-
-// src/observability/otel-tracer.ts
-var OTEL_STATUS_ERROR = 2;
-var OTelTracer = class {
-  constructor(upstream) {
-    this.upstream = upstream;
-  }
-  upstream;
-  startSpan(name, attrs) {
-    const otelSpan = this.upstream.startSpan(name, attrs ? { attributes: attrs } : void 0);
-    return new OTelSpan(otelSpan);
-  }
-};
-var OTelSpan = class {
-  constructor(span) {
-    this.span = span;
-  }
-  span;
-  setAttribute(key, value) {
-    this.span.setAttribute(key, value);
-  }
-  recordError(err) {
-    this.span.recordException(err);
-    this.span.setStatus?.({ code: OTEL_STATUS_ERROR, message: err.message });
-  }
-  end() {
-    this.span.end();
-  }
-};
-
-// src/observability/event-bridge.ts
-function wireMetricsToEvents(events, sink) {
-  const unsubs = [];
-  unsubs.push(
-    events.on("session.started", () => sink.counter("agent.sessions.started")),
-    events.on("session.ended", (e) => {
-      sink.counter("agent.sessions.ended");
-      sink.histogram("agent.session.tokens.input", e.usage.input);
-      sink.histogram("agent.session.tokens.output", e.usage.output);
-    }),
-    events.on("session.damaged", () => sink.counter("agent.sessions.damaged")),
-    events.on("iteration.completed", () => sink.counter("agent.iterations.total")),
-    events.on("iteration.limit_reached", () => sink.counter("agent.iteration_limit.hit")),
-    events.on("provider.response", (e) => {
-      sink.counter("provider.responses.total", 1, { stop_reason: e.stopReason });
-      sink.counter("provider.tokens.input", e.usage.input);
-      sink.counter("provider.tokens.output", e.usage.output);
-      if (e.usage.cacheRead) sink.counter("provider.tokens.cache_read", e.usage.cacheRead);
-      if (e.usage.cacheWrite) sink.counter("provider.tokens.cache_write", e.usage.cacheWrite);
-    }),
-    events.on(
-      "provider.retry",
-      (e) => sink.counter("provider.retries.total", 1, {
-        provider: e.providerId,
-        status: String(e.status)
-      })
-    ),
-    events.on(
-      "provider.error",
-      (e) => sink.counter("provider.errors.total", 1, {
-        provider: e.providerId,
-        status: String(e.status),
-        retryable: String(e.retryable)
-      })
-    ),
-    events.on(
-      "tool.started",
-      (e) => sink.counter("tool.starts.total", 1, { tool: metricToolName(e.name) })
-    ),
-    events.on("tool.executed", (e) => {
-      const tool = metricToolName(e.name);
-      sink.counter("tool.executions.total", 1, { tool, ok: String(e.ok) });
-      sink.histogram("tool.duration_ms", e.durationMs, { tool });
-    }),
-    events.on("token.threshold", (e) => sink.gauge("agent.tokens.used", e.used)),
-    events.on("compaction.fired", (e) => {
-      sink.counter("compaction.fired.total");
-      sink.histogram("compaction.reduction_tokens", e.report.before - e.report.after);
-    }),
-    // MCP server names are user-controlled and may contain tenant/project
-    // identifiers. Keep them out of metric labels to bound cardinality and
-    // prevent operational metadata leaks.
-    events.on("mcp.server.connected", () => sink.counter("mcp.connects.total")),
-    events.on("mcp.server.reconnected", () => sink.counter("mcp.reconnects.total")),
-    events.on("mcp.server.disconnected", () => sink.counter("mcp.disconnects.total")),
-    events.on("error", (e) => sink.counter("agent.errors.total", 1, { phase: e.phase }))
-  );
-  return () => {
-    for (const u of unsubs) u();
-  };
-}
-function metricToolName(name) {
-  return name.startsWith("mcp__") ? "mcp_proxy" : name;
-}
-
-// src/observability/prometheus.ts
-import { timingSafeEqual } from "node:crypto";
-var NUMBER_FORMAT_INFINITY = "NaN";
-function escapeLabelValue(v) {
-  return v.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
-}
-function formatLabels(labels) {
-  const keys = Object.keys(labels);
-  if (keys.length === 0) return "";
-  const parts = keys.map((k) => `${k}="${escapeLabelValue(labels[k] ?? "")}"`);
-  return `{${parts.join(",")}}`;
-}
-function formatNumber(n) {
-  if (!Number.isFinite(n)) return NUMBER_FORMAT_INFINITY;
-  return Number.isInteger(n) ? n.toString() : n.toString();
-}
-function joinLabels(base, extra) {
-  return { ...base, ...extra };
-}
-function renderPrometheus(snapshot) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const s of snapshot.series) {
-    let g = groups.get(s.name);
-    if (!g) {
-      g = { type: s.type, rows: [] };
-      groups.set(s.name, g);
-    }
-    g.rows.push({ labels: s.labels, values: s.values });
-  }
-  const lines = [];
-  for (const [name, g] of groups) {
-    const promType = g.type === "histogram" ? "summary" : g.type;
-    lines.push(`# HELP ${name} ${name}`);
-    lines.push(`# TYPE ${name} ${promType}`);
-    if (g.type === "counter" || g.type === "gauge") {
-      for (const row of g.rows) {
-        lines.push(`${name}${formatLabels(row.labels)} ${formatNumber(row.values.value ?? 0)}`);
-      }
-    } else {
-      for (const row of g.rows) {
-        const { count = 0, sum = 0, p50 = 0, p95 = 0, p99 = 0 } = row.values;
-        lines.push(
-          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.5" }))} ${formatNumber(p50)}`
-        );
-        lines.push(
-          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.95" }))} ${formatNumber(p95)}`
-        );
-        lines.push(
-          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.99" }))} ${formatNumber(p99)}`
-        );
-        lines.push(`${name}_sum${formatLabels(row.labels)} ${formatNumber(sum)}`);
-        lines.push(`${name}_count${formatLabels(row.labels)} ${formatNumber(count)}`);
-      }
-    }
-  }
-  return lines.join("\n") + "\n";
-}
-var PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
-function isLoopbackBindHost(host) {
-  const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
-  return h === "127.0.0.1" || h === "localhost" || h === "::1" || h.startsWith("127.");
-}
-function bearerMatches(header, token) {
-  if (!header) return false;
-  const prefix = "bearer ";
-  if (!header.toLowerCase().startsWith(prefix)) return false;
-  const supplied = Buffer.from(header.slice(prefix.length).trim(), "utf8");
-  const expected = Buffer.from(token, "utf8");
-  if (supplied.length !== expected.length) return false;
-  return timingSafeEqual(supplied, expected);
-}
-async function startMetricsServer(opts) {
-  const tls = opts.tls;
-  const useHttps = !!(tls?.cert && tls?.key);
-  const host = opts.host ?? "127.0.0.1";
-  const path = opts.path ?? "/metrics";
-  const healthPath = opts.healthPath ?? "/healthz";
-  const healthRegistry = opts.healthRegistry;
-  const token = opts.token;
-  if (!isLoopbackBindHost(host) && !token) {
-    throw new Error(
-      `startMetricsServer: refusing to bind to non-loopback host "${host}" without a token \u2014 pass a token to expose metrics to the network, or bind to 127.0.0.1.`
-    );
-  }
-  const listener = (req, res) => {
-    if (!req.url || req.method !== "GET") {
-      res.statusCode = req.url ? 405 : 400;
-      res.end();
-      return;
-    }
-    if (token && !bearerMatches(req.headers.authorization, token)) {
-      res.statusCode = 401;
-      res.setHeader("www-authenticate", "Bearer");
-      res.setHeader("content-type", "text/plain; charset=utf-8");
-      res.end("Unauthorized");
-      return;
-    }
-    const url = req.url.split("?")[0];
-    if (url === path) {
-      let body;
-      try {
-        body = renderPrometheus(opts.sink.snapshot());
-      } catch (err) {
-        res.statusCode = 500;
-        res.setHeader("content-type", "text/plain; charset=utf-8");
-        res.end(`metrics render failed: ${toErrorMessage(err)}`);
-        return;
-      }
-      res.statusCode = 200;
-      res.setHeader("content-type", PROMETHEUS_CONTENT_TYPE);
-      res.end(body);
-      return;
-    }
-    if (healthRegistry && url === healthPath) {
-      healthRegistry.run().then(
-        (agg) => {
-          res.statusCode = agg.status === "unhealthy" ? 503 : 200;
-          res.setHeader("content-type", "application/json; charset=utf-8");
-          res.end(JSON.stringify(agg, null, 2));
-        },
-        (err) => {
-          res.statusCode = 500;
-          res.setHeader("content-type", "text/plain; charset=utf-8");
-          res.end(`health run failed: ${toErrorMessage(err)}`);
-        }
-      );
-      return;
-    }
-    res.statusCode = 404;
-    res.setHeader("content-type", "text/plain; charset=utf-8");
-    res.end("Not Found");
-  };
-  let server;
-  if (useHttps && tls) {
-    const { createServer } = await import("node:https");
-    const { readFileSync } = await import("node:fs");
-    server = createServer(
-      { cert: readFileSync(tls.cert), key: readFileSync(tls.key) },
-      listener
-    );
-  } else {
-    const { createServer } = await import("node:http");
-    server = createServer(listener);
-  }
-  await new Promise((resolve, reject) => {
-    const onError = (err) => {
-      server.off("listening", onListening);
-      reject(err);
-    };
-    const onListening = () => {
-      server.off("error", onError);
-      resolve();
-    };
-    server.once("error", onError);
-    server.once("listening", onListening);
-    server.listen(opts.port, host);
-  });
-  const addr = server.address();
-  const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
-  const protocol = useHttps ? "https" : "http";
-  return {
-    port: boundPort,
-    url: `${protocol}://${host}:${boundPort}${path}`,
-    close: () => new Promise((resolve, reject) => {
-      server.close((err) => err ? reject(err) : resolve());
-    })
-  };
+  if (!key) return {};
+  const labels = {};
+  for (const pair of key.split(",")) {
+    const eq = pair.indexOf("=");
+    if (eq > 0) labels[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return labels;
 }
+var NoopMetricsSink = class {
+  counter() {
+  }
+  gauge() {
+  }
+  histogram() {
+  }
+  snapshot() {
+    return { timestamp: Date.now(), series: [] };
+  }
+  droppedObservations() {
+    return 0;
+  }
+  reset() {
+  }
+};
+
+// src/observability/otel-tracer.ts
+var OTEL_STATUS_ERROR = 2;
+var OTelTracer = class {
+  constructor(upstream) {
+    this.upstream = upstream;
+  }
+  upstream;
+  startSpan(name, attrs) {
+    const otelSpan = this.upstream.startSpan(name, attrs ? { attributes: attrs } : void 0);
+    return new OTelSpan(otelSpan);
+  }
+};
+var OTelSpan = class {
+  constructor(span) {
+    this.span = span;
+  }
+  span;
+  setAttribute(key, value) {
+    this.span.setAttribute(key, value);
+  }
+  recordError(err) {
+    this.span.recordException(err);
+    this.span.setStatus?.({ code: OTEL_STATUS_ERROR, message: err.message });
+  }
+  end() {
+    this.span.end();
+  }
+};
 
 // src/observability/otlp-metrics.ts
 var DEFAULT_INTERVAL_MS = 3e4;
@@ -802,6 +645,269 @@ function startOtlpTraceExporter(opts) {
     buffered: () => [...buffer]
   };
 }
+
+// src/observability/prometheus.ts
+import { timingSafeEqual } from "node:crypto";
+var NUMBER_FORMAT_INFINITY = "NaN";
+function escapeLabelValue(v) {
+  return v.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
+}
+function formatLabels(labels) {
+  const keys = Object.keys(labels);
+  if (keys.length === 0) return "";
+  const parts = keys.map((k) => `${k}="${escapeLabelValue(labels[k] ?? "")}"`);
+  return `{${parts.join(",")}}`;
+}
+function formatNumber(n) {
+  if (!Number.isFinite(n)) return NUMBER_FORMAT_INFINITY;
+  return Number.isInteger(n) ? n.toString() : n.toString();
+}
+function joinLabels(base, extra) {
+  return { ...base, ...extra };
+}
+function renderPrometheus(snapshot) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const s of snapshot.series) {
+    let g = groups.get(s.name);
+    if (!g) {
+      g = { type: s.type, rows: [] };
+      groups.set(s.name, g);
+    }
+    g.rows.push({ labels: s.labels, values: s.values });
+  }
+  const lines = [];
+  for (const [name, g] of groups) {
+    const promType = g.type === "histogram" ? "summary" : g.type;
+    lines.push(`# HELP ${name} ${name}`);
+    lines.push(`# TYPE ${name} ${promType}`);
+    if (g.type === "counter" || g.type === "gauge") {
+      for (const row of g.rows) {
+        lines.push(`${name}${formatLabels(row.labels)} ${formatNumber(row.values.value ?? 0)}`);
+      }
+    } else {
+      for (const row of g.rows) {
+        const { count = 0, sum = 0, p50 = 0, p95 = 0, p99 = 0 } = row.values;
+        lines.push(
+          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.5" }))} ${formatNumber(p50)}`
+        );
+        lines.push(
+          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.95" }))} ${formatNumber(p95)}`
+        );
+        lines.push(
+          `${name}${formatLabels(joinLabels(row.labels, { quantile: "0.99" }))} ${formatNumber(p99)}`
+        );
+        lines.push(`${name}_sum${formatLabels(row.labels)} ${formatNumber(sum)}`);
+        lines.push(`${name}_count${formatLabels(row.labels)} ${formatNumber(count)}`);
+      }
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+var PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+function isLoopbackBindHost(host) {
+  const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+  return h === "127.0.0.1" || h === "localhost" || h === "::1" || h.startsWith("127.");
+}
+function bearerMatches(header, token) {
+  if (!header) return false;
+  const prefix = "bearer ";
+  if (!header.toLowerCase().startsWith(prefix)) return false;
+  const supplied = Buffer.from(header.slice(prefix.length).trim(), "utf8");
+  const expected = Buffer.from(token, "utf8");
+  if (supplied.length !== expected.length) return false;
+  return timingSafeEqual(supplied, expected);
+}
+async function startMetricsServer(opts) {
+  const tls = opts.tls;
+  const useHttps = !!(tls?.cert && tls?.key);
+  const host = opts.host ?? "127.0.0.1";
+  const path = opts.path ?? "/metrics";
+  const healthPath = opts.healthPath ?? "/healthz";
+  const healthRegistry = opts.healthRegistry;
+  const token = opts.token;
+  if (!isLoopbackBindHost(host) && !token) {
+    throw new Error(
+      `startMetricsServer: refusing to bind to non-loopback host "${host}" without a token \u2014 pass a token to expose metrics to the network, or bind to 127.0.0.1.`
+    );
+  }
+  const listener = (req, res) => {
+    if (!req.url || req.method !== "GET") {
+      res.statusCode = req.url ? 405 : 400;
+      res.end();
+      return;
+    }
+    if (token && !bearerMatches(req.headers.authorization, token)) {
+      res.statusCode = 401;
+      res.setHeader("www-authenticate", "Bearer");
+      res.setHeader("content-type", "text/plain; charset=utf-8");
+      res.end("Unauthorized");
+      return;
+    }
+    const url = req.url.split("?")[0];
+    if (url === path) {
+      let body;
+      try {
+        body = renderPrometheus(opts.sink.snapshot());
+      } catch (err) {
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end(`metrics render failed: ${toErrorMessage(err)}`);
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader("content-type", PROMETHEUS_CONTENT_TYPE);
+      res.end(body);
+      return;
+    }
+    if (healthRegistry && url === healthPath) {
+      healthRegistry.run().then(
+        (agg) => {
+          res.statusCode = agg.status === "unhealthy" ? 503 : 200;
+          res.setHeader("content-type", "application/json; charset=utf-8");
+          res.end(JSON.stringify(agg, null, 2));
+        },
+        (err) => {
+          res.statusCode = 500;
+          res.setHeader("content-type", "text/plain; charset=utf-8");
+          res.end(`health run failed: ${toErrorMessage(err)}`);
+        }
+      );
+      return;
+    }
+    res.statusCode = 404;
+    res.setHeader("content-type", "text/plain; charset=utf-8");
+    res.end("Not Found");
+  };
+  let server;
+  if (useHttps && tls) {
+    const { createServer } = await import("node:https");
+    const { readFileSync } = await import("node:fs");
+    server = createServer(
+      { cert: readFileSync(tls.cert), key: readFileSync(tls.key) },
+      listener
+    );
+  } else {
+    const { createServer } = await import("node:http");
+    server = createServer(listener);
+  }
+  await new Promise((resolve, reject) => {
+    const onError = (err) => {
+      server.off("listening", onListening);
+      reject(err);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(opts.port, host);
+  });
+  const addr = server.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : opts.port;
+  const protocol = useHttps ? "https" : "http";
+  return {
+    port: boundPort,
+    url: `${protocol}://${host}:${boundPort}${path}`,
+    close: () => new Promise((resolve, reject) => {
+      server.close((err) => err ? reject(err) : resolve());
+    })
+  };
+}
+
+// src/observability/tool-usage-source.ts
+var DEFAULT_LIMIT = 500;
+function daysBetween(later, earlier) {
+  return Math.max(0, Math.floor((later - earlier) / 864e5));
+}
+function chronicleCandidates(store, opts, now) {
+  const rows = store.underusedTools({
+    ...opts.fromDay !== void 0 ? { from: opts.fromDay } : {},
+    ...opts.toDay !== void 0 ? { to: opts.toDay } : {},
+    limit: opts.limit ?? DEFAULT_LIMIT
+  });
+  return rows.map((row) => ({
+    name: row.toolName,
+    invocations: row.invocations,
+    failures: row.failures,
+    durationMsTotal: row.durationMsTotal,
+    lastInvokedAt: row.lastInvokedAt,
+    daysSinceLastUse: row.lastInvokedAt === null ? null : daysBetween(now, row.lastInvokedAt),
+    source: "chronicle"
+  }));
+}
+function inProcessCandidates(usage, opts, now) {
+  const windowStart = now - opts.idleDays * 864e5;
+  const out = [];
+  for (const [name, rec] of usage) {
+    if (rec.lastInvokedAt >= windowStart) continue;
+    out.push({
+      name,
+      invocations: rec.invocations,
+      failures: rec.failures,
+      durationMsTotal: rec.durationMsTotal,
+      lastInvokedAt: rec.lastInvokedAt,
+      daysSinceLastUse: daysBetween(now, rec.lastInvokedAt),
+      source: "in-process"
+    });
+  }
+  out.sort((a, b) => a.invocations - b.invocations || a.name.localeCompare(b.name));
+  return out.slice(0, opts.limit ?? DEFAULT_LIMIT);
+}
+function createToolUsageSource(deps) {
+  const now = deps.now ?? (() => Date.now());
+  if (deps.chronicle) {
+    const store = deps.chronicle;
+    return {
+      kind: "chronicle",
+      async candidates(opts) {
+        await store.refresh();
+        return chronicleCandidates(store, opts, now());
+      },
+      async refresh() {
+        await store.refresh();
+      }
+    };
+  }
+  if (deps.bridge) {
+    const usage = deps.bridge;
+    return {
+      kind: "in-process",
+      async candidates(opts) {
+        return inProcessCandidates(usage, opts, now());
+      }
+    };
+  }
+  return {
+    kind: "in-process",
+    async candidates() {
+      return [];
+    }
+  };
+}
+function filterUnderused(candidates, opts, now = Date.now()) {
+  const windowStart = now - opts.idleDays * 864e5;
+  return candidates.filter((c) => {
+    if (c.invocations > opts.minInvocations) return false;
+    if (c.lastInvokedAt === null) return true;
+    return c.lastInvokedAt < windowStart;
+  });
+}
+
+// src/observability/tracer.ts
+var NoopTracer = class {
+  startSpan() {
+    return NOOP_SPAN;
+  }
+};
+var NOOP_SPAN = {
+  setAttribute() {
+  },
+  recordError() {
+  },
+  end() {
+  }
+};
 export {
   DefaultHealthRegistry,
   InMemoryMetricsSink,
@@ -811,9 +917,11 @@ export {
   PROMETHEUS_CONTENT_TYPE,
   buildOtlpMetricsRequest,
   buildOtlpTracesRequest,
+  createToolUsageSource,
   emitProcessCompleted,
   emitProcessOutput,
   emitProcessStarted,
+  filterUnderused,
   redactCommand,
   redactCommandArgs,
   renderPrometheus,