@wrongstack/core 0.1.9 → 0.1.10

package/dist/observability/index.js

@@ -0,0 +1,691 @@
+import * as crypto from 'crypto';
+
+// src/observability/metrics.ts
+var RESERVOIR_SIZE = 1024;
+function labelKey(labels) {
+  if (!labels) return "";
+  const keys = Object.keys(labels).sort();
+  return keys.map((k) => `${k}=${labels[k]}`).join(",");
+}
+function quantile(sorted, q) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.floor(q * sorted.length));
+  return sorted[idx] ?? 0;
+}
+var InMemoryMetricsSink = class {
+  counters = /* @__PURE__ */ new Map();
+  gauges = /* @__PURE__ */ new Map();
+  histograms = /* @__PURE__ */ new Map();
+  counter(name, value = 1, labels) {
+    const series = this.getOrCreate(this.counters, name);
+    const key = labelKey(labels);
+    const state = series.get(key) ?? { value: 0 };
+    state.value += value;
+    series.set(key, state);
+  }
+  gauge(name, value, labels) {
+    const series = this.getOrCreate(this.gauges, name);
+    series.set(labelKey(labels), { value });
+  }
+  histogram(name, value, labels) {
+    const series = this.getOrCreate(this.histograms, name);
+    const key = labelKey(labels);
+    let state = series.get(key);
+    if (!state) {
+      state = { count: 0, sum: 0, min: value, max: value, samples: [] };
+      series.set(key, state);
+    }
+    state.count++;
+    state.sum += value;
+    if (value < state.min) state.min = value;
+    if (value > state.max) state.max = value;
+    if (state.samples.length < RESERVOIR_SIZE) {
+      state.samples.push(value);
+    } else {
+      const r = Math.floor(Math.random() * state.count);
+      if (r < RESERVOIR_SIZE) state.samples[r] = value;
+    }
+  }
+  snapshot() {
+    const series = [];
+    for (const [name, byLabel] of this.counters) {
+      for (const [key, state] of byLabel) {
+        series.push({
+          name,
+          type: "counter",
+          labels: parseLabelKey(key),
+          values: { value: state.value }
+        });
+      }
+    }
+    for (const [name, byLabel] of this.gauges) {
+      for (const [key, state] of byLabel) {
+        series.push({
+          name,
+          type: "gauge",
+          labels: parseLabelKey(key),
+          values: { value: state.value }
+        });
+      }
+    }
+    for (const [name, byLabel] of this.histograms) {
+      for (const [key, state] of byLabel) {
+        const sorted = [...state.samples].sort((a, b) => a - b);
+        series.push({
+          name,
+          type: "histogram",
+          labels: parseLabelKey(key),
+          values: {
+            count: state.count,
+            sum: state.sum,
+            min: state.min,
+            max: state.max,
+            p50: quantile(sorted, 0.5),
+            p95: quantile(sorted, 0.95),
+            p99: quantile(sorted, 0.99)
+          }
+        });
+      }
+    }
+    return { timestamp: Date.now(), series };
+  }
+  reset() {
+    this.counters.clear();
+    this.gauges.clear();
+    this.histograms.clear();
+  }
+  getOrCreate(bag, name) {
+    let series = bag.get(name);
+    if (!series) {
+      series = /* @__PURE__ */ new Map();
+      bag.set(name, series);
+    }
+    return series;
+  }
+};
+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: [] };
+  }
+  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: err instanceof Error ? err.message : String(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: e.name })),
+    events.on("tool.executed", (e) => {
+      sink.counter("tool.executions.total", 1, { tool: e.name, ok: String(e.ok) });
+      sink.histogram("tool.duration_ms", e.durationMs, { tool: e.name });
+    }),
+    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.before - e.after);
+    }),
+    events.on(
+      "mcp.server.connected",
+      (e) => sink.counter("mcp.connects.total", 1, { server: e.name })
+    ),
+    events.on(
+      "mcp.server.reconnected",
+      (e) => sink.counter("mcp.reconnects.total", 1, { server: e.name })
+    ),
+    events.on(
+      "mcp.server.disconnected",
+      (e) => sink.counter("mcp.disconnects.total", 1, { server: e.name })
+    ),
+    events.on("error", (e) => sink.counter("agent.errors.total", 1, { phase: e.phase }))
+  );
+  return () => {
+    for (const u of unsubs) u();
+  };
+}
+
+// src/observability/prometheus.ts
+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";
+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 listener = (req, res) => {
+    if (!req.url || req.method !== "GET") {
+      res.statusCode = req.url ? 405 : 400;
+      res.end();
+      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: ${err instanceof Error ? err.message : String(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: ${err instanceof Error ? err.message : String(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('https');
+    const { readFileSync } = await import('fs');
+    server = createServer(
+      { cert: readFileSync(tls.cert), key: readFileSync(tls.key) },
+      listener
+    );
+  } else {
+    const { createServer } = await import('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/otlp-metrics.ts
+var DEFAULT_INTERVAL_MS = 3e4;
+var DEFAULT_TIMEOUT_MS = 1e4;
+function joinEndpoint(base) {
+  if (/\/v1\/metrics\/?$/.test(base)) return base;
+  return base.replace(/\/$/, "") + "/v1/metrics";
+}
+function attributesFor(labels) {
+  return Object.entries(labels).map(([key, value]) => ({
+    key,
+    value: { stringValue: value }
+  }));
+}
+function buildExportBody(opts) {
+  const metrics = [];
+  for (const s of opts.series) {
+    const dp = {
+      attributes: attributesFor(s.labels),
+      timeUnixNano: opts.timeUnixNano
+    };
+    if (s.type === "counter") {
+      dp.asDouble = s.values.value ?? 0;
+      metrics.push({
+        name: s.name,
+        sum: { dataPoints: [dp], aggregationTemporality: 2, isMonotonic: true }
+      });
+    } else if (s.type === "gauge") {
+      dp.asDouble = s.values.value ?? 0;
+      metrics.push({ name: s.name, gauge: { dataPoints: [dp] } });
+    } else {
+      dp.count = String(s.values.count ?? 0);
+      dp.sum = s.values.sum ?? 0;
+      dp.quantileValues = [
+        { quantile: 0.5, value: s.values.p50 ?? 0 },
+        { quantile: 0.95, value: s.values.p95 ?? 0 },
+        { quantile: 0.99, value: s.values.p99 ?? 0 }
+      ];
+      metrics.push({ name: s.name, summary: { dataPoints: [dp] } });
+    }
+  }
+  return {
+    resourceMetrics: [
+      {
+        resource: { attributes: attributesFor(opts.resourceAttributes) },
+        scopeMetrics: [
+          {
+            scope: { name: opts.scopeName },
+            metrics
+          }
+        ]
+      }
+    ]
+  };
+}
+function buildOtlpMetricsRequest(sink, opts = {}) {
+  return buildExportBody({
+    series: sink.snapshot().series,
+    resourceAttributes: opts.resourceAttributes ?? { "service.name": "wrongstack" },
+    scopeName: opts.scopeName ?? "wrongstack",
+    timeUnixNano: String(BigInt(Date.now()) * 1000000n)
+  });
+}
+function startOtlpMetricsExporter(opts) {
+  const url = joinEndpoint(opts.endpoint);
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const onError = opts.onError ?? (() => {
+  });
+  const resourceAttributes = opts.resourceAttributes ?? { "service.name": "wrongstack" };
+  const scopeName = opts.scopeName ?? "wrongstack";
+  let stopped = false;
+  const headers = {
+    "content-type": "application/json",
+    ...opts.headers ?? {}
+  };
+  if (opts.authorization) headers.authorization = opts.authorization;
+  async function pushOnce() {
+    if (stopped) return;
+    const body = buildExportBody({
+      series: opts.sink.snapshot().series,
+      resourceAttributes,
+      scopeName,
+      timeUnixNano: String(BigInt(Date.now()) * 1000000n)
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        onError(new Error(`OTLP push failed: ${res.status} ${res.statusText} ${text}`));
+      }
+    } catch (err) {
+      onError(err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  const handle = setInterval(() => {
+    void pushOnce();
+  }, intervalMs);
+  handle.unref?.();
+  return {
+    flush: pushOnce,
+    async stop() {
+      stopped = true;
+      clearInterval(handle);
+      await pushOnce().catch(onError);
+    }
+  };
+}
+var SPAN_STATUS_CODE_UNSET = 0;
+var SPAN_STATUS_CODE_OK = 1;
+var SPAN_STATUS_CODE_ERROR = 2;
+function hex(bytes) {
+  return crypto.randomBytes(bytes).toString("hex");
+}
+function nowNs() {
+  return BigInt(Date.now()) * 1000000n;
+}
+var CapturingSpan = class {
+  constructor(state, onEnd) {
+    this.state = state;
+    this.onEnd = onEnd;
+  }
+  state;
+  onEnd;
+  setAttribute(key, value) {
+    this.state.attributes[key] = value;
+  }
+  recordError(err) {
+    this.state.status = { code: SPAN_STATUS_CODE_ERROR, message: err.message };
+    this.state.attributes["exception.message"] = err.message;
+    if (err.name) this.state.attributes["exception.type"] = err.name;
+  }
+  end() {
+    if (this.state.endTimeUnixNano !== void 0) return;
+    this.state.endTimeUnixNano = nowNs();
+    if (this.state.status.code === SPAN_STATUS_CODE_UNSET) {
+      this.state.status.code = SPAN_STATUS_CODE_OK;
+    }
+    this.onEnd(this.state);
+  }
+};
+var DEFAULT_INTERVAL_MS2 = 5e3;
+var DEFAULT_BUFFER_CAP = 2048;
+var DEFAULT_TIMEOUT_MS2 = 1e4;
+function joinEndpoint2(base) {
+  if (/\/v1\/traces\/?$/.test(base)) return base;
+  return base.replace(/\/$/, "") + "/v1/traces";
+}
+function encodeAttr(key, value) {
+  if (typeof value === "boolean") return { key, value: { boolValue: value } };
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? { key, value: { intValue: String(value) } } : { key, value: { doubleValue: value } };
+  }
+  return { key, value: { stringValue: value } };
+}
+function buildOtlpTracesRequest(spans, opts = {}) {
+  const resourceAttributes = opts.resourceAttributes ?? { "service.name": "wrongstack" };
+  const scopeName = opts.scopeName ?? "wrongstack";
+  const otlpSpans = spans.map((s) => ({
+    traceId: s.traceId,
+    spanId: s.spanId,
+    name: s.name,
+    kind: 1,
+    // SPAN_KIND_INTERNAL
+    startTimeUnixNano: s.startTimeUnixNano.toString(),
+    endTimeUnixNano: (s.endTimeUnixNano ?? s.startTimeUnixNano).toString(),
+    attributes: Object.entries(s.attributes).map(([k, v]) => encodeAttr(k, v)),
+    status: s.status
+  }));
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: Object.entries(resourceAttributes).map(([k, v]) => encodeAttr(k, v))
+        },
+        scopeSpans: [{ scope: { name: scopeName }, spans: otlpSpans }]
+      }
+    ]
+  };
+}
+function startOtlpTraceExporter(opts) {
+  const url = joinEndpoint2(opts.endpoint);
+  const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS2;
+  const maxBuffered = opts.maxBufferedSpans ?? DEFAULT_BUFFER_CAP;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const onError = opts.onError ?? (() => {
+  });
+  const resourceAttributes = opts.resourceAttributes ?? { "service.name": "wrongstack" };
+  const scopeName = opts.scopeName ?? "wrongstack";
+  let stopped = false;
+  const buffer = [];
+  const headers = {
+    "content-type": "application/json",
+    ...opts.headers ?? {}
+  };
+  if (opts.authorization) headers.authorization = opts.authorization;
+  const tracer = {
+    startSpan(name, attrs) {
+      const state = {
+        traceId: hex(16),
+        spanId: hex(8),
+        name,
+        startTimeUnixNano: nowNs(),
+        attributes: { ...attrs ?? {} },
+        status: { code: SPAN_STATUS_CODE_UNSET }
+      };
+      return new CapturingSpan(state, (ended) => {
+        if (buffer.length >= maxBuffered) buffer.shift();
+        buffer.push(ended);
+      });
+    }
+  };
+  async function pushOnce() {
+    if (buffer.length === 0) return;
+    const batch = buffer.splice(0, buffer.length);
+    const body = buildOtlpTracesRequest(batch, { resourceAttributes, scopeName });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        onError(new Error(`OTLP traces push failed: ${res.status} ${res.statusText} ${text}`));
+      }
+    } catch (err) {
+      onError(err);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  const handle = setInterval(() => {
+    if (!stopped) void pushOnce();
+  }, intervalMs);
+  handle.unref?.();
+  return {
+    tracer,
+    flush: pushOnce,
+    async stop() {
+      stopped = true;
+      clearInterval(handle);
+      await pushOnce().catch(onError);
+    },
+    buffered: () => [...buffer]
+  };
+}
+
+export { DefaultHealthRegistry, InMemoryMetricsSink, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, buildOtlpMetricsRequest, buildOtlpTracesRequest, renderPrometheus, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, wireMetricsToEvents };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map