@wrongstack/core 0.284.1 → 0.286.0

package/dist/observability/index.d.ts

@@ -1,354 +1,9 @@
-import { M as MetricsSink, d as MetricLabels, f as MetricsSnapshot, H as HealthRegistry, a as HealthCheck, A as AggregateHealth, T as Tracer, S as Span } from '../observability-D-HZN_mF.js';
-import { E as EventBus } from '../events-Bgnh43r9.js';
-import '../tool-BNlnIJvo.js';
-import '../permission-ByDKXEcG.js';
-
-/**
- * In-memory metrics sink. Suitable for embedded use, tests, and /metrics
- * scrape over HTTP. For production push-based pipelines, write an adapter
- * that implements MetricsSink and forwards to OTLP/StatsD/Prometheus.
- */
-declare class InMemoryMetricsSink implements MetricsSink {
-    private counters;
-    private gauges;
-    private histograms;
-    counter(name: string, value?: number, labels?: MetricLabels): void;
-    gauge(name: string, value: number, labels?: MetricLabels): void;
-    histogram(name: string, value: number, labels?: MetricLabels): void;
-    snapshot(): MetricsSnapshot;
-    reset(): void;
-    private getOrCreate;
-}
-/** Cheap noop sink — drop-in default when observability is not configured. */
-declare class NoopMetricsSink implements MetricsSink {
-    counter(): void;
-    gauge(): void;
-    histogram(): void;
-    snapshot(): MetricsSnapshot;
-    reset(): void;
-}
-
-/**
- * Aggregates registered health checks. Worst status wins — one unhealthy check
- * makes the whole system unhealthy. Use timeouts so a slow probe can't stall
- * the response.
- */
-declare class DefaultHealthRegistry implements HealthRegistry {
-    private checks;
-    private readonly timeoutMs;
-    constructor(opts?: {
-        timeoutMs?: number | undefined;
-    });
-    register(check: HealthCheck): void;
-    unregister(name: string): void;
-    run(): Promise<AggregateHealth>;
-    private runOne;
-}
-
-/**
- * Default tracer is a noop — zero overhead when observability is not wired up.
- * Replace at runtime with an OpenTelemetry-backed Tracer to enable real spans.
- */
-declare class NoopTracer implements Tracer {
-    startSpan(): Span;
-}
-
-/**
- * Lightweight OTel adapter. Doesn't pull in `@opentelemetry/api` directly —
- * the user passes their already-initialized OTel Tracer through, and this
- * wrapper translates our minimal Span surface onto theirs.
- *
- * Usage:
- *   import { trace } from '@opentelemetry/api';
- *   const tracer = trace.getTracer('wrongstack', '1.0');
- *   const wrappedTracer = new OTelTracer(tracer);
- *   // pass `wrappedTracer` as Agent.tracer / ToolExecutor.tracer.
- *
- * The shape of the upstream Tracer is intentionally typed loosely so we
- * don't need a build-time dependency. Anything OTel-compatible works,
- * including OpenInference, Tempo, etc.
- */
-
-interface OTelLikeSpan {
-    setAttribute(key: string, value: string | number | boolean): unknown;
-    recordException(err: {
-        message: string;
-        stack?: string | undefined;
-        name?: string | undefined;
-    }): unknown;
-    setStatus?(status: {
-        code: number;
-        message?: string | undefined;
-    }): unknown;
-    end(): unknown;
-}
-interface OTelLikeTracer {
-    startSpan(name: string, options?: {
-        attributes?: Record<string, string | number | boolean>;
-    }): OTelLikeSpan;
-}
-declare class OTelTracer implements Tracer {
-    private readonly upstream;
-    constructor(upstream: OTelLikeTracer);
-    startSpan(name: string, attrs?: Record<string, string | number | boolean>): Span;
-}
-
-/**
- * Subscribes a MetricsSink to the EventBus. Returns an unsubscribe function
- * that detaches all listeners. This is the single integration point between
- * the agent's event stream and the observability layer — no metric calls
- * leak into core call sites.
- */
-declare function wireMetricsToEvents(events: EventBus, sink: MetricsSink): () => void;
-
-/** TLS options for HTTPS metrics endpoint. */
-interface MetricsTlsOptions {
-    cert: string;
-    key: string;
-}
-/**
- * Render a `MetricsSnapshot` as Prometheus text-format bytes. The output
- * always ends with a trailing newline (Prometheus requires it).
- */
-declare function renderPrometheus(snapshot: MetricsSnapshot): string;
-/** MIME type Prometheus servers must respond with on /metrics. */
-declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
-interface MetricsServerOptions {
-    port: number;
-    /** Bind address. Defaults to 127.0.0.1 so we don't accidentally expose metrics publicly. */
-    host?: string | undefined;
-    sink: MetricsSink;
-    /** Path to serve on. Defaults to /metrics. */
-    path?: string | undefined;
-    /**
-     * V2-C: optional health registry. When provided, the server also responds
-     * on `/healthz` (configurable via `healthPath`) with a JSON aggregate of
-     * every registered health check. K8s probes expect a single HTTP server
-     * exposing both `/metrics` and `/healthz`, so we mount them on the same
-     * port rather than opening a sibling listener.
-     */
-    healthRegistry?: HealthRegistry | undefined;
-    /** Path to serve health JSON on. Defaults to /healthz. */
-    healthPath?: string | undefined;
-    /** Enable HTTPS by providing TLS key/cert. Both required. */
-    tls?: MetricsTlsOptions | undefined;
-}
-interface MetricsServerHandle {
-    port: number;
-    url: string;
-    close(): Promise<void>;
-}
-/**
- * Start an HTTP server that exposes a Prometheus scrape endpoint.
- * Uses node:http directly to avoid pulling a framework into the core graph.
- *
- * Why bind to 127.0.0.1 by default: telemetry endpoints inside an agent
- * process can leak prompt content via metric labels (tool name, error
- * message, etc.). The default keeps that on the loopback interface;
- * operators who want network scraping opt in explicitly with host: '0.0.0.0'.
- */
-declare function startMetricsServer(opts: MetricsServerOptions): Promise<MetricsServerHandle>;
-
-/**
- * V2-A: OTLP/JSON metrics push exporter.
- *
- * Periodically POSTs `MetricsSink.snapshot()` to an OTLP HTTP receiver
- * (the OpenTelemetry Collector, vendor agents like Honeycomb, Datadog,
- * Grafana Cloud, etc.). The wire format is OTLP/JSON v1.0 — covered by
- * the spec at github.com/open-telemetry/opentelemetry-proto.
- *
- * Why no `@opentelemetry/*` dep: the core graph is intentionally
- * dependency-free. The JSON shape is well-defined and stable; bringing
- * in the official SDK would add ~3MB and pin us to its release cadence.
- * Operators who need the OTLP gRPC transport or vendor-specific quirks
- * can wrap an `@opentelemetry/exporter-metrics-otlp-grpc` in a custom
- * `MetricsSink` instead — the seam exists.
- */
-interface OtlpMetricsExporterOptions {
-    /** Source of metric data. The exporter reads `snapshot()` per interval. */
-    sink: MetricsSink;
-    /**
-     * OTLP HTTP endpoint base URL. Path `/v1/metrics` is appended unless
-     * the URL already ends with `/v1/metrics` (idempotent).
-     * Example: `http://otel-collector:4318` or `https://otlp.example.com`.
-     */
-    endpoint: string;
-    /** Push interval in milliseconds. Defaults to 30s (Prometheus default). */
-    intervalMs?: number | undefined;
-    /** Optional bearer token / API key (sent as `Authorization`). */
-    authorization?: string | undefined;
-    /** Extra request headers (vendor-specific keys go here). */
-    headers?: Record<string, string>;
-    /** Resource attributes attached to every export. Defaults: `service.name=wrongstack`. */
-    resourceAttributes?: Record<string, string>;
-    /** Instrumentation scope. Default: `wrongstack`. */
-    scopeName?: string | undefined;
-    /** Per-request timeout. Defaults to 10s. */
-    timeoutMs?: number | undefined;
-    /** Override fetch (for tests). Defaults to global `fetch`. */
-    fetchImpl?: typeof globalThis.fetch | undefined;
-    /** Called when a push fails. Defaults to silent (telemetry must never crash the host). */
-    onError?: ((err: unknown) => void) | undefined;
-}
-interface OtlpMetricsExporterHandle {
-    /** Push immediately (in addition to the scheduled interval). */
-    flush(): Promise<void>;
-    /** Stop the timer, attempt a final flush, then resolve. */
-    stop(): Promise<void>;
-}
-interface OtlpAttribute$1 {
-    key: string;
-    value: {
-        stringValue: string;
-    };
-}
-interface OtlpDataPoint {
-    attributes: OtlpAttribute$1[];
-    timeUnixNano: string;
-    asDouble?: number | undefined;
-    asInt?: string | undefined;
-    count?: string | undefined;
-    sum?: number | undefined;
-    quantileValues?: {
-        quantile: number | undefined;
-        value: number;
-    }[];
-}
-interface OtlpMetric {
-    name: string;
-    description?: string | undefined;
-    unit?: string | undefined;
-    sum?: {
-        dataPoints: OtlpDataPoint[] | undefined;
-        aggregationTemporality: 2;
-        isMonotonic: true;
-    };
-    gauge?: {
-        dataPoints: OtlpDataPoint[] | undefined;
-    };
-    summary?: {
-        dataPoints: OtlpDataPoint[] | undefined;
-    };
-}
-interface OtlpExportRequest {
-    resourceMetrics: {
-        resource: {
-            attributes: OtlpAttribute$1[];
-        };
-        scopeMetrics: {
-            scope: {
-                name: string;
-                version?: string | undefined;
-            };
-            metrics: OtlpMetric[];
-        }[];
-    }[];
-}
-/**
- * Build the OTLP/JSON export body from a sink snapshot. Exported for tests
- * and for callers that want to ship via their own transport.
- */
-declare function buildOtlpMetricsRequest(sink: MetricsSink, opts?: {
-    resourceAttributes?: Record<string, string>;
-    scopeName?: string | undefined;
-}): OtlpExportRequest;
-/**
- * Start pushing metrics to an OTLP HTTP receiver. Returns a handle with
- * `flush()` and `stop()`.
- */
-declare function startOtlpMetricsExporter(opts: OtlpMetricsExporterOptions): OtlpMetricsExporterHandle;
-
-type SpanAttrValue = string | number | boolean;
-interface RecordedSpan {
-    traceId: string;
-    spanId: string;
-    name: string;
-    startTimeUnixNano: bigint;
-    endTimeUnixNano?: bigint | undefined;
-    attributes: Record<string, SpanAttrValue>;
-    status: {
-        code: number;
-        message?: string | undefined;
-    };
-}
-interface OtlpTraceExporterOptions {
-    /** OTLP HTTP endpoint base URL. `/v1/traces` is appended unless already present. */
-    endpoint: string;
-    /** Push interval in milliseconds. Defaults to 5s (traces are bursty). */
-    intervalMs?: number | undefined;
-    /** Hard cap on buffered spans. When exceeded, oldest are dropped. Defaults to 2048. */
-    maxBufferedSpans?: number | undefined;
-    /** Authorization header. */
-    authorization?: string | undefined;
-    /** Extra request headers. */
-    headers?: Record<string, string>;
-    /** Resource attributes. Defaults to `service.name=wrongstack`. */
-    resourceAttributes?: Record<string, string>;
-    /** Instrumentation scope name. Default `wrongstack`. */
-    scopeName?: string | undefined;
-    /** Per-request timeout in ms. Default 10s. */
-    timeoutMs?: number | undefined;
-    /** Override fetch (for tests). */
-    fetchImpl?: typeof globalThis.fetch | undefined;
-    /** Called on push failure. Defaults to silent. */
-    onError?: ((err: unknown) => void) | undefined;
-}
-interface OtlpTraceExporterHandle {
-    /** The Tracer to install on Agent / ToolExecutor. */
-    readonly tracer: Tracer;
-    /** Push buffered spans immediately. */
-    flush(): Promise<void>;
-    /** Stop the timer, push remaining spans, resolve. */
-    stop(): Promise<void>;
-    /** Test helper: snapshot of spans currently in the buffer (not yet pushed). */
-    readonly buffered: () => readonly RecordedSpan[];
-}
-interface OtlpAttribute {
-    key: string;
-    value: {
-        stringValue: string;
-    } | {
-        boolValue: boolean;
-    } | {
-        doubleValue: number;
-    } | {
-        intValue: string;
-    };
-}
-interface OtlpSpan {
-    traceId: string;
-    spanId: string;
-    name: string;
-    kind: 1;
-    startTimeUnixNano: string;
-    endTimeUnixNano: string;
-    attributes: OtlpAttribute[];
-    status: {
-        code: number;
-        message?: string | undefined;
-    };
-}
-interface OtlpTracesRequest {
-    resourceSpans: {
-        resource: {
-            attributes: OtlpAttribute[];
-        };
-        scopeSpans: {
-            scope: {
-                name: string;
-            };
-            spans: OtlpSpan[];
-        }[];
-    }[];
-}
-declare function buildOtlpTracesRequest(spans: readonly RecordedSpan[], opts?: {
-    resourceAttributes?: Record<string, string>;
-    scopeName?: string | undefined;
-}): OtlpTracesRequest;
-/**
- * Start the OTLP trace exporter. Returns a `Tracer` to install on the
- * runtime (`Agent.run` etc.) and `flush()`/`stop()` controls.
- */
-declare function startOtlpTraceExporter(opts: OtlpTraceExporterOptions): OtlpTraceExporterHandle;
-
-export { DefaultHealthRegistry, InMemoryMetricsSink, type MetricsServerHandle, type MetricsServerOptions, type MetricsTlsOptions, NoopMetricsSink, NoopTracer, OTelTracer, type OtlpMetricsExporterHandle, type OtlpMetricsExporterOptions, type OtlpTraceExporterHandle, type OtlpTraceExporterOptions, PROMETHEUS_CONTENT_TYPE, buildOtlpMetricsRequest, buildOtlpTracesRequest, renderPrometheus, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, wireMetricsToEvents };
+export { InMemoryMetricsSink, NoopMetricsSink } from './metrics.js';
+export { DefaultHealthRegistry } from './health.js';
+export { NoopTracer } from './tracer.js';
+export { OTelTracer } from './otel-tracer.js';
+export { wireMetricsToEvents } from './event-bridge.js';
+export { renderPrometheus, startMetricsServer, PROMETHEUS_CONTENT_TYPE, type MetricsServerOptions, type MetricsServerHandle, type MetricsTlsOptions, } from './prometheus.js';
+export { buildOtlpMetricsRequest, startOtlpMetricsExporter, type OtlpMetricsExporterOptions, type OtlpMetricsExporterHandle, } from './otlp-metrics.js';
+export { buildOtlpTracesRequest, startOtlpTraceExporter, type OtlpTraceExporterOptions, type OtlpTraceExporterHandle, } from './otlp-traces.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAC"}

package/dist/observability/index.js

@@ -1,5 +1,3 @@
-import * as crypto from 'crypto';
-
 // src/observability/metrics.ts
 var RESERVOIR_SIZE = 1024;
 function labelKey(labels) {
@@ -259,34 +257,35 @@ function wireMetricsToEvents(events, sink) {
         retryable: String(e.retryable)
       })
     ),
-    events.on("tool.started", (e) => sink.counter("tool.starts.total", 1, { tool: e.name })),
+    events.on(
+      "tool.started",
+      (e) => sink.counter("tool.starts.total", 1, { tool: metricToolName(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 });
+      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);
     }),
-    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 })
-    ),
+    // 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
 var NUMBER_FORMAT_INFINITY = "NaN";
@@ -395,14 +394,14 @@ async function startMetricsServer(opts) {
   };
   let server;
   if (useHttps && tls) {
-    const { createServer } = await import('https');
-    const { readFileSync } = await import('fs');
+    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('http');
+    const { createServer } = await import("node:http");
     server = createServer(listener);
   }
   await new Promise((resolve, reject) => {
@@ -547,6 +546,9 @@ function startOtlpMetricsExporter(opts) {
     }
   };
 }
+
+// src/observability/otlp-traces.ts
+import * as crypto from "node:crypto";
 var SPAN_STATUS_CODE_UNSET = 0;
 var SPAN_STATUS_CODE_OK = 1;
 var SPAN_STATUS_CODE_ERROR = 2;
@@ -690,7 +692,19 @@ function startOtlpTraceExporter(opts) {
     buffered: () => [...buffer]
   };
 }
-
-export { DefaultHealthRegistry, InMemoryMetricsSink, NoopMetricsSink, NoopTracer, OTelTracer, PROMETHEUS_CONTENT_TYPE, buildOtlpMetricsRequest, buildOtlpTracesRequest, renderPrometheus, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, wireMetricsToEvents };
+export {
+  DefaultHealthRegistry,
+  InMemoryMetricsSink,
+  NoopMetricsSink,
+  NoopTracer,
+  OTelTracer,
+  PROMETHEUS_CONTENT_TYPE,
+  buildOtlpMetricsRequest,
+  buildOtlpTracesRequest,
+  renderPrometheus,
+  startMetricsServer,
+  startOtlpMetricsExporter,
+  startOtlpTraceExporter,
+  wireMetricsToEvents
+};
 //# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map