@wrongstack/core 0.313.0 → 0.316.1

package/dist/observability/index.js

@@ -1,3 +1,161 @@
+import {
+  emitProcessCompleted,
+  emitProcessOutput,
+  emitProcessStarted,
+  redactCommand,
+  redactCommandArgs,
+  runWithProcessTelemetry
+} from "../chunk-NDBIPFNY.js";
+import {
+  runWithNetworkTelemetry,
+  startNetworkTelemetryMonitor
+} from "../chunk-HA4ZYA6T.js";
+import "../chunk-PFZO3C6H.js";
+import {
+  toErrorMessage
+} from "../chunk-TBRL2RCC.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;
 function labelKey(labels) {
@@ -168,638 +326,61 @@ var InMemoryMetricsSink = class {
   recordDrop(name) {
     this.droppedByMetric.set(name, (this.droppedByMetric.get(name) ?? 0) + 1);
   }
-};
-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/utils/error.ts
-function toErrorMessage(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-
-// 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/process-telemetry.ts
-import { AsyncLocalStorage } from "node:async_hooks";
-import { createHash } from "node:crypto";
-
-// src/utils/expect-defined.ts
-function expectDefined(value, label) {
-  if (value === null || value === void 0) {
-    const err = new Error(label ? `Expected ${label} to be defined` : "Expected value to be defined");
-    err.name = "ExpectDefinedError";
-    throw err;
-  }
-  return value;
-}
-
-// src/observability/redact-command.ts
-var SENSITIVE_FLAG_PATTERNS = [
-  // --flag=value  or  --flag "value"  (value captured up to next space or comma)
-  /--(?:token|password|passwd|pwd|secret|api[-_]?key|api[-_]?secret|auth|credential|private[-_]?key|access[-_]?key|github[-_]?token|gh[-_]?token|bearer|jwt|oauth|pin|pincode|passphrase|access[-_]?token)(?:[=\s,][^\s]*)?/gi,
-  // -t short flag (token): attached (-tVALUE), separated (-t VALUE), or -t=VALUE.
-  // The separator group is optional so the attached form (the common one) matches.
-  // (?<![-\w]) anchors to a token start so we don't match the `-t` inside `--token`.
-  // The value must be token-like (>= 8 chars) so ordinary combined flags such
-  // as `tar -tf` / `ssh -tt` are not eaten. Global flag: EVERY occurrence is
-  // redacted, not just the first. Synced with packages/tools _redact-command.ts.
-  /(?<![-\w])-t(?:[=\s]+)?[^\s,-]{8,}/g,
-  // -p|-password|-a (redis auth) short flags: attached + separated + =value.
-  // Same token-start anchor; over-redaction is an accepted tradeoff for a
-  // redaction function (false positive = cosmetic noise; false negative = leak).
-  /(?<![-\w])-(?:password|p|a)(?:[=\s]+)?[^\s,-]+/gi,
-  // env var–style secrets: TOKEN=x, API_KEY=y, etc.
-  /(?:TOKEN|API_KEY|API_SECRET|AUTH_TOKEN|GITHUB_TOKEN|GH_TOKEN|BEARER|JWT|OAUTH|CREDENTIAL|SECRET|PRIVATE_KEY|PASSWORD|PASSWD|PASSPHRASE)\s*[=:]\s*[^\s,]+/gi,
-  // Generic high-entropy look: base64 strings >32 chars or hex strings >32 digits — but only
-  // when preceded by a flag name (e.g. --github-token=EyJ...). Global flag so
-  // every such flag in the command line is redacted, not just the first.
-  /--\w*(?:token|key|secret|password|passwd|auth|credential)\w*[=\s,][A-Za-z0-9+/=]{32,}/g
-];
-function redactCommand(cmd) {
-  let result = cmd;
-  for (const pattern of SENSITIVE_FLAG_PATTERNS) {
-    result = result.replace(pattern, (match) => {
-      const eq = match.indexOf("=");
-      const sp = match.search(/\s/);
-      const delim = eq !== -1 ? "=" : sp !== -1 ? match[sp] : null;
-      if (delim !== null) {
-        const flag = match.slice(0, match.indexOf(expectDefined(delim)) + 1);
-        return `${flag}[REDACTED]`;
-      }
-      if (match.startsWith("--")) {
-        return match;
-      }
-      return `${match.slice(0, 2)}[REDACTED]`;
-    });
-  }
-  return result;
-}
-var BARE_SENSITIVE_LONG_FLAG = /^--(?:token|password|passwd|pwd|secret|api[-_]?key|api[-_]?secret|auth|credential|private[-_]?key|access[-_]?key|github[-_]?token|gh[-_]?token|bearer|jwt|oauth|pin|pincode|passphrase|access[-_]?token)$/i;
-var BARE_SENSITIVE_SHORT_FLAG = /^-(?:p|t|a)$/i;
-function redactCommandArgs(command, args) {
-  const redactedCommand = redactCommand(command);
-  const redactedArgs = args.map((a) => redactCommand(a));
-  for (let i = 0; i < redactedArgs.length - 1; i++) {
-    const flag = redactedArgs[i];
-    const next = redactedArgs[i + 1];
-    if (flag === void 0 || next === void 0) continue;
-    const isBareSensitive = (BARE_SENSITIVE_LONG_FLAG.test(flag) || BARE_SENSITIVE_SHORT_FLAG.test(flag)) && !flag.includes("[REDACTED]");
-    if (isBareSensitive && !next.startsWith("-")) {
-      redactedArgs[i + 1] = "[REDACTED]";
-    }
-  }
-  return { command: redactedCommand, args: redactedArgs };
-}
-
-// src/observability/process-telemetry.ts
-var storage = new AsyncLocalStorage();
-function runWithProcessTelemetry(context, run) {
-  return storage.run(context, run);
-}
-function emitProcessStarted(event) {
-  const { command, args } = redactCommandArgs(event.command, event.args);
-  emit("process.started", { ...event, command, args });
-}
-function emitProcessOutput(input) {
-  const bytes = Buffer.byteLength(input.chunk);
-  emit("process.output", {
-    ...input.pid !== void 0 ? { pid: input.pid } : {},
-    stream: input.stream,
-    bytes,
-    chunkHash: createHash("sha256").update(input.chunk).digest("hex"),
-    at: (/* @__PURE__ */ new Date()).toISOString()
-  });
-}
-function emitProcessCompleted(event) {
-  emit("process.completed", event);
-}
-function emit(name, event) {
-  const context = storage.getStore();
-  if (!context) return;
-  const { events, ...identity2 } = context;
-  events.emit(name, { ...identity2, ...event });
-}
-
-// src/observability/network-telemetry.ts
-import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
-import { createHash as createHash2, randomUUID } from "node:crypto";
-import { channel } from "node:diagnostics_channel";
-var storage2 = new AsyncLocalStorage2();
-var requests = /* @__PURE__ */ new WeakMap();
-var users = 0;
-var unsubscribe;
-function runWithNetworkTelemetry(context, run) {
-  return storage2.run(context, run);
-}
-function startNetworkTelemetryMonitor() {
-  users++;
-  if (!unsubscribe) unsubscribe = subscribe();
-  let stopped = false;
-  return () => {
-    if (stopped) return;
-    stopped = true;
-    users--;
-    if (users <= 0) {
-      unsubscribe?.();
-      unsubscribe = void 0;
-      users = 0;
-    }
-  };
-}
-function subscribe() {
-  const create = channel("undici:request:create");
-  const headers = channel("undici:request:headers");
-  const error = channel("undici:request:error");
-  const onCreate = (message) => {
-    const context = storage2.getStore();
-    const request = objectField(message, "request");
-    if (!context || !request) return;
-    const target = safeTarget(request);
-    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-    const requestBytes = numberField(request, "contentLength");
-    const state = {
-      ...context,
-      requestId: randomUUID(),
-      ...target,
-      ...requestBytes !== void 0 ? { requestBytes } : {},
-      startedAt,
-      startedNs: process.hrtime.bigint()
-    };
-    requests.set(request, state);
-    context.events.emit("network.request.started", {
-      ...identity(state),
-      requestId: state.requestId,
-      method: state.method,
-      scheme: state.scheme,
-      serverAddress: state.serverAddress,
-      ...state.serverPort !== void 0 ? { serverPort: state.serverPort } : {},
-      pathHash: state.pathHash,
-      queryKeys: queryKeys(request),
-      ...state.requestBytes !== void 0 ? { requestBytes: state.requestBytes } : {},
-      startedAt
-    });
-  };
-  const onHeaders = (message) => {
-    const request = objectField(message, "request");
-    if (!request) return;
-    const state = requests.get(request);
-    if (!state) return;
-    requests.delete(request);
-    const response = objectField(message, "response");
-    const responseBytes = contentLength(response);
-    state.events.emit("network.request.completed", {
-      ...identity(state),
-      requestId: state.requestId,
-      method: state.method,
-      scheme: state.scheme,
-      serverAddress: state.serverAddress,
-      ...state.serverPort !== void 0 ? { serverPort: state.serverPort } : {},
-      pathHash: state.pathHash,
-      statusCode: numberField(response, "statusCode") ?? 0,
-      durationMs: elapsed(state.startedNs),
-      ...state.requestBytes !== void 0 ? { requestBytes: state.requestBytes } : {},
-      ...responseBytes !== void 0 ? { responseBytes } : {},
-      completedAt: (/* @__PURE__ */ new Date()).toISOString()
-    });
-  };
-  const onError = (message) => {
-    const request = objectField(message, "request");
-    if (!request) return;
-    const state = requests.get(request);
-    if (!state) return;
-    requests.delete(request);
-    const err = objectField(message, "error");
-    const errorCode = stringField(err, "code");
-    state.events.emit("network.request.failed", {
-      ...identity(state),
-      requestId: state.requestId,
-      method: state.method,
-      scheme: state.scheme,
-      serverAddress: state.serverAddress,
-      ...state.serverPort !== void 0 ? { serverPort: state.serverPort } : {},
-      pathHash: state.pathHash,
-      durationMs: elapsed(state.startedNs),
-      errorName: stringField(err, "name") ?? "Error",
-      ...errorCode ? { errorCode } : {},
-      failedAt: (/* @__PURE__ */ new Date()).toISOString()
-    });
-  };
-  create.subscribe(onCreate);
-  headers.subscribe(onHeaders);
-  error.subscribe(onError);
-  return () => {
-    create.unsubscribe(onCreate);
-    headers.unsubscribe(onHeaders);
-    error.unsubscribe(onError);
-  };
-}
-function identity(state) {
-  return {
-    sessionId: state.sessionId,
-    ...state.traceId ? { traceId: state.traceId } : {},
-    ...state.agentId ? { agentId: state.agentId } : {},
-    ...state.toolCallId ? { toolCallId: state.toolCallId } : {},
-    ...state.attemptId ? { attemptId: state.attemptId } : {},
-    initiator: state.initiator,
-    operationName: state.operationName
-  };
-}
-function safeTarget(request) {
-  const origin = String(request.origin ?? "");
-  const path = String(request.path ?? "");
-  let url;
-  try {
-    url = new URL(path, origin);
-  } catch {
-    url = new URL("http://invalid.local/");
-  }
-  return {
-    method: String(request.method ?? "GET").toUpperCase(),
-    scheme: url.protocol.replace(":", ""),
-    serverAddress: url.hostname,
-    ...url.port ? { serverPort: Number(url.port) } : {},
-    pathHash: hash(url.pathname)
-  };
-}
-function queryKeys(request) {
-  try {
-    return [...new URL(String(request.path ?? ""), String(request.origin ?? "")).searchParams.keys()].filter((v, i, a) => a.indexOf(v) === i).slice(0, 50);
-  } catch {
-    return [];
-  }
-}
-function contentLength(response) {
-  const raw = response?.headers;
-  if (!Array.isArray(raw)) return void 0;
-  for (let index = 0; index < raw.length - 1; index += 2) if (String(raw[index]).toLowerCase() === "content-length") {
-    const value = Number(String(raw[index + 1]));
-    return Number.isFinite(value) ? value : void 0;
-  }
-  return void 0;
-}
-function objectField(value, key) {
-  return value && typeof value === "object" && value[key] && typeof value[key] === "object" ? value[key] : void 0;
-}
-function stringField(value, key) {
-  return typeof value?.[key] === "string" ? value[key] : void 0;
-}
-function numberField(value, key) {
-  return typeof value?.[key] === "number" ? value[key] : void 0;
-}
-function elapsed(start) {
-  return Number(process.hrtime.bigint() - start) / 1e6;
-}
-function hash(value) {
-  return createHash2("sha256").update(value).digest("hex");
-}
-
-// 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());
-    })
-  };
+};
+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/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;
@@ -1064,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,
@@ -1073,9 +917,11 @@ export {
   PROMETHEUS_CONTENT_TYPE,
   buildOtlpMetricsRequest,
   buildOtlpTracesRequest,
+  createToolUsageSource,
   emitProcessCompleted,
   emitProcessOutput,
   emitProcessStarted,
+  filterUnderused,
   redactCommand,
   redactCommandArgs,
   renderPrometheus,