@wrongstack/core 0.1.9 → 0.2.0

package/dist/observability/index.d.ts

@@ -0,0 +1,353 @@
+import { e as MetricsSink, M as MetricLabels, f as MetricsSnapshot, b as HealthRegistry, H as HealthCheck, A as AggregateHealth, T as Tracer, S as Span } from '../observability-BhnVLBLS.js';
+import { E as EventBus } from '../events-B6Q03pTu.js';
+import '../context-u0bryklF.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;
+    });
+    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;
+        name?: string;
+    }): unknown;
+    setStatus?(status: {
+        code: number;
+        message?: string;
+    }): 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;
+    sink: MetricsSink;
+    /** Path to serve on. Defaults to /metrics. */
+    path?: string;
+    /**
+     * 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;
+    /** Path to serve health JSON on. Defaults to /healthz. */
+    healthPath?: string;
+    /** Enable HTTPS by providing TLS key/cert. Both required. */
+    tls?: MetricsTlsOptions;
+}
+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;
+    /** Optional bearer token / API key (sent as `Authorization`). */
+    authorization?: string;
+    /** 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;
+    /** Per-request timeout. Defaults to 10s. */
+    timeoutMs?: number;
+    /** Override fetch (for tests). Defaults to global `fetch`. */
+    fetchImpl?: typeof globalThis.fetch;
+    /** Called when a push fails. Defaults to silent (telemetry must never crash the host). */
+    onError?: (err: unknown) => void;
+}
+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;
+    asInt?: string;
+    count?: string;
+    sum?: number;
+    quantileValues?: {
+        quantile: number;
+        value: number;
+    }[];
+}
+interface OtlpMetric {
+    name: string;
+    description?: string;
+    unit?: string;
+    sum?: {
+        dataPoints: OtlpDataPoint[];
+        aggregationTemporality: 2;
+        isMonotonic: true;
+    };
+    gauge?: {
+        dataPoints: OtlpDataPoint[];
+    };
+    summary?: {
+        dataPoints: OtlpDataPoint[];
+    };
+}
+interface OtlpExportRequest {
+    resourceMetrics: {
+        resource: {
+            attributes: OtlpAttribute$1[];
+        };
+        scopeMetrics: {
+            scope: {
+                name: string;
+                version?: string;
+            };
+            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;
+}): 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;
+    attributes: Record<string, SpanAttrValue>;
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+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;
+    /** Hard cap on buffered spans. When exceeded, oldest are dropped. Defaults to 2048. */
+    maxBufferedSpans?: number;
+    /** Authorization header. */
+    authorization?: string;
+    /** 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;
+    /** Per-request timeout in ms. Default 10s. */
+    timeoutMs?: number;
+    /** Override fetch (for tests). */
+    fetchImpl?: typeof globalThis.fetch;
+    /** Called on push failure. Defaults to silent. */
+    onError?: (err: unknown) => void;
+}
+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;
+    };
+}
+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;
+}): 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 };