@loompad/cli 0.1.0 → 1.1.2

package/dist/observability/metrics.js

@@ -0,0 +1,303 @@
+/**
+ * Loom → OpenTelemetry metrics (OTLP/HTTP JSON, `/v1/metrics`).
+ *
+ * Same shape as the trace exporter next door: aggregate in memory, flush on a
+ * short timer, POST, never throw. What differs is that a metric is a fold, not
+ * an event — several turns collapse into one datapoint — so this holds a small
+ * aggregation table keyed by metric name + attribute set instead of a list.
+ *
+ * Every number here is derived from a LoomEvent that actually happened. There
+ * is no periodic "emit 0 so the chart has a line" path, because a flat zero and
+ * "nothing happened" look identical on a graph and only one of them is true.
+ *
+ * ── Naming ──────────────────────────────────────────────────────────────────
+ * `gen_ai.*` names and attributes follow the OpenTelemetry GenAI semantic
+ * conventions (semantic-conventions-genai, the GenAI metrics doc split out of
+ * the main semconv repo): `gen_ai.client.token.usage` with a
+ * `gen_ai.token.type` of `input`/`output`, `gen_ai.client.operation.duration`
+ * in seconds, dimensioned by `gen_ai.operation.name`, `gen_ai.system` and
+ * `gen_ai.request.model`. `loom.*` names are ours — nothing in the convention
+ * covers batons, routes or a per-agent daily spend cap — and follow its style.
+ *
+ * One deliberate deviation: the convention models `gen_ai.client.token.usage`
+ * as a *histogram* (a distribution of tokens-per-request). Loom emits it as a
+ * monotonic sum. A histogram earns its keep when you want percentiles over many
+ * requests; Loom reports exactly one input/output pair per turn, and what
+ * anyone asks this data is "how many tokens did this agent burn today" — a sum
+ * answers that exactly, and a histogram's `sum` field only approximates it once
+ * you start dropping buckets. `gen_ai.client.operation.duration` stays a
+ * histogram, as specified, because turn latency genuinely is a distribution.
+ *
+ * ── Temporality ─────────────────────────────────────────────────────────────
+ * Delta, everywhere (AGGREGATION_TEMPORALITY_DELTA). Cumulative asks the
+ * *client* to remember every counter's running total for the life of the
+ * process and expects the backend to detect resets. Loom's daemon restarts
+ * whenever you edit a config or upgrade the CLI, so cumulative would mean a
+ * counter reset every few minutes — the exact case cumulative handles worst.
+ * Delta makes each export self-contained: what happened since the last flush,
+ * nothing remembered, nothing to reset. Collectors accept both.
+ */
+import { encodeAttributes, postOtlp, resourceAttributes, } from "./otlp.js";
+/** OTLP AggregationTemporality. 1 = CUMULATIVE, 2 = DELTA. See the header. */
+const TEMPORALITY_DELTA = 2;
+/** Flush window, matched to the trace exporter's so signals land together. */
+const FLUSH_MS = 1500;
+/** Hard cap on distinct series held between flushes; see `guardCardinality`. */
+const MAX_SERIES = 512;
+/**
+ * Bucket boundaries for `gen_ai.client.operation.duration`, in seconds, as
+ * specified by the GenAI metrics convention. Kept verbatim rather than tuned:
+ * matching the convention is what lets a GenAI dashboard built for any
+ * other instrumented service read Loom's turns too.
+ */
+const DURATION_BUCKETS_S = [
+    0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92,
+];
+const META = {
+    "gen_ai.client.token.usage": { unit: "{token}", description: "Tokens consumed by an agent turn, by token type." },
+    "gen_ai.client.operation.duration": { unit: "s", description: "Duration of a completed agent turn." },
+    "loom.turns": { unit: "{turn}", description: "Agent turns that reached completion, by outcome." },
+    "loom.cost.usd": { unit: "USD", description: "Money an adapter reported spending on a turn." },
+    "loom.agents.active": { unit: "{agent}", description: "Agents currently executing a turn." },
+    "loom.handoffs": { unit: "{handoff}", description: "Baton handoffs between agents." },
+};
+export class LoomMetrics {
+    cfg;
+    series = new Map();
+    timer = null;
+    metricsUrl;
+    resource;
+    /**
+     * Start of the current delta window. A delta datapoint's
+     * `startTimeUnixNano`..`timeUnixNano` must bracket exactly the interval the
+     * value accumulated over, and consecutive windows must not overlap — so this
+     * advances to the previous flush's end rather than being re-read from the
+     * clock each time.
+     */
+    windowStartNs;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.metricsUrl = `${cfg.endpoint}/v1/metrics`;
+        this.resource = resourceAttributes(cfg);
+        this.windowStartNs = nowNs();
+    }
+    get enabled() {
+        return this.cfg.metricsEnabled && typeof globalThis.fetch === "function";
+    }
+    /** Add to a monotonic counter. Negative or non-finite deltas are ignored. */
+    addCount(name, value, attributes, isInt = true) {
+        if (!this.enabled || !Number.isFinite(value) || value < 0)
+            return;
+        const bag = this.bag(name);
+        const attrs = encodeAttributes(attributes);
+        const key = seriesKey(attrs);
+        const existing = bag.get(key);
+        if (existing?.kind === "sum")
+            existing.value += value;
+        else if (this.guardCardinality(bag))
+            bag.set(key, { kind: "sum", attributes: attrs, value, isInt });
+        this.ensureTimer();
+    }
+    /** Record one observation into a histogram. */
+    record(name, value, attributes, bounds = DURATION_BUCKETS_S) {
+        if (!this.enabled || !Number.isFinite(value) || value < 0)
+            return;
+        const bag = this.bag(name);
+        const attrs = encodeAttributes(attributes);
+        const key = seriesKey(attrs);
+        let s = bag.get(key);
+        if (s?.kind !== "histogram") {
+            if (!this.guardCardinality(bag))
+                return;
+            s = {
+                kind: "histogram",
+                attributes: attrs,
+                bounds,
+                // One bucket per boundary plus the +Inf overflow bucket — OTLP requires
+                // bucketCounts.length === explicitBounds.length + 1.
+                counts: new Array(bounds.length + 1).fill(0),
+                count: 0,
+                sum: 0,
+                min: value,
+                max: value,
+            };
+            bag.set(key, s);
+        }
+        let i = 0;
+        while (i < s.bounds.length && value > s.bounds[i])
+            i++;
+        s.counts[i] += 1;
+        s.count += 1;
+        s.sum += value;
+        s.min = Math.min(s.min, value);
+        s.max = Math.max(s.max, value);
+        this.ensureTimer();
+    }
+    /** Observe a gauge's current value, as of now. */
+    setGauge(name, value, attributes = {}) {
+        if (!this.enabled || !Number.isFinite(value))
+            return;
+        const bag = this.bag(name);
+        const attrs = encodeAttributes(attributes);
+        const key = seriesKey(attrs);
+        if (!bag.has(key) && !this.guardCardinality(bag))
+            return;
+        bag.set(key, { kind: "gauge", attributes: attrs, value, observedNs: nowNs() });
+        this.ensureTimer();
+    }
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.drain();
+    }
+    /**
+     * Build the OTLP payload for everything accumulated so far and clear the
+     * window. Exported for tests: asserting on the JSON we would send beats
+     * asserting on a mocked fetch, and the payload shape is the part a collector
+     * actually rejects.
+     */
+    collect(nowOverrideNs) {
+        if (this.series.size === 0)
+            return null;
+        const endNs = nowOverrideNs ?? nowNs();
+        const startNs = this.windowStartNs;
+        const metrics = [];
+        for (const [name, bag] of this.series) {
+            if (bag.size === 0)
+                continue;
+            const meta = META[name] ?? { unit: "1", description: "" };
+            metrics.push({
+                name,
+                unit: meta.unit,
+                description: meta.description,
+                ...body([...bag.values()], startNs, endNs),
+            });
+        }
+        this.series.clear();
+        this.windowStartNs = endNs;
+        if (metrics.length === 0)
+            return null;
+        return {
+            resourceMetrics: [
+                {
+                    resource: { attributes: this.resource },
+                    scopeMetrics: [{ scope: { name: "loom" }, metrics }],
+                },
+            ],
+        };
+    }
+    bag(name) {
+        let b = this.series.get(name);
+        if (!b)
+            this.series.set(name, (b = new Map()));
+        return b;
+    }
+    /**
+     * Refuse to open a new series past the cap.
+     *
+     * Metric attributes come from agent ids and model names, which are bounded in
+     * practice — but a misbehaving adapter reporting a unique model string per
+     * turn would otherwise turn this map into an unbounded leak and the backend's
+     * index into a mess. Dropping the *new* series keeps the ones already being
+     * measured intact and correct; the alternative (evicting) would silently
+     * discard counts that were already recorded.
+     */
+    guardCardinality(bag) {
+        return bag.size < MAX_SERIES;
+    }
+    ensureTimer() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.drain();
+        }, FLUSH_MS);
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    drain() {
+        const payload = this.collect();
+        if (!payload)
+            return;
+        postOtlp(this.metricsUrl, this.cfg.headers, payload);
+    }
+}
+/** The `sum` / `histogram` / `gauge` body for one metric's worth of series. */
+function body(all, startNs, endNs) {
+    const start = startNs.toString();
+    const time = endNs.toString();
+    const first = all[0];
+    if (first.kind === "gauge") {
+        // No temporality and no start time on a gauge: it is a reading, not an
+        // interval. The timestamp is when we actually observed it.
+        return {
+            gauge: {
+                dataPoints: all
+                    .filter((s) => s.kind === "gauge")
+                    .map((s) => ({
+                    attributes: s.attributes,
+                    timeUnixNano: s.observedNs.toString(),
+                    ...numeric(s.value, true),
+                })),
+            },
+        };
+    }
+    if (first.kind === "histogram") {
+        return {
+            histogram: {
+                aggregationTemporality: TEMPORALITY_DELTA,
+                dataPoints: all
+                    .filter((s) => s.kind === "histogram")
+                    .map((s) => ({
+                    attributes: s.attributes,
+                    startTimeUnixNano: start,
+                    timeUnixNano: time,
+                    count: String(s.count),
+                    sum: s.sum,
+                    bucketCounts: s.counts.map(String),
+                    explicitBounds: s.bounds,
+                    min: s.min,
+                    max: s.max,
+                })),
+            },
+        };
+    }
+    return {
+        sum: {
+            aggregationTemporality: TEMPORALITY_DELTA,
+            // Every counter Loom emits only ever goes up within a window — turns
+            // completed, tokens spent, dollars burned, batons passed. None of them
+            // can be undone, so isMonotonic is the truth and lets a backend offer rate().
+            isMonotonic: true,
+            dataPoints: all
+                .filter((s) => s.kind === "sum")
+                .map((s) => ({
+                attributes: s.attributes,
+                startTimeUnixNano: start,
+                timeUnixNano: time,
+                ...numeric(s.value, s.isInt),
+            })),
+        },
+    };
+}
+/**
+ * `asInt` (int64, string-encoded per the proto3 JSON mapping) or `asDouble`.
+ * Counts are integers; money and seconds are not, and rounding either to an int
+ * would report $0 for a real three-cent turn.
+ */
+function numeric(value, isInt) {
+    return isInt ? { asInt: String(Math.round(value)) } : { asDouble: value };
+}
+/** Stable identity for an attribute set, so repeat observations coalesce. */
+function seriesKey(attrs) {
+    return attrs
+        .map((a) => `${a.key}=${Object.values(a.value)[0]}`)
+        .sort()
+        .join("
");
+}
+function nowNs() {
+    return BigInt(Date.now()) * 1000000n;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"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"}

package/dist/observability/otlp.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Loom → OpenTelemetry.
+ *
+ * A self-contained OTLP/HTTP (JSON) trace exporter — no OpenTelemetry SDK
+ * dependency, just `fetch`. Loom's agent lifecycle is already a stream of
+ * LoomEvents (turns, routes, baton handoffs, memory folds); this maps the
+ * notable ones to spans using the OpenTelemetry GenAI semantic conventions
+ * (`gen_ai.*`) so they land in the LLM/GenAI views every OTLP backend builds
+ * on those conventions.
+ *
+ * Backend-agnostic on purpose: this speaks OTLP/HTTP and nothing else, so it
+ * works against a plain OpenTelemetry Collector, Grafana/Tempo, Jaeger, SigNoz,
+ * Honeycomb — anything with a `/v1/traces` endpoint. Point
+ * OTEL_EXPORTER_OTLP_ENDPOINT at yours.
+ *
+ * This module owns traces plus the pieces every signal shares: the resolved
+ * config, the resource attributes, and the OTLP attribute encoding. The
+ * metrics (`./metrics.ts`) and logs (`./logs.ts`) exporters import those rather
+ * than growing their own copy, so a service.name change lands on all three at
+ * once and a span, a datapoint and a log line always agree about who emitted
+ * them.
+ *
+ * Egress is best-effort and consent-gated: if no collector is reachable the
+ * POST fails silently and never surfaces in the instrumented operation. Turn
+ * it off with DO_NOT_TRACK=1 or LOOM_TELEMETRY_DISABLED=1.
+ */
+export type KeyValue = {
+    key: string;
+    value: {
+        stringValue: string;
+    } | {
+        intValue: string;
+    } | {
+        doubleValue: number;
+    } | {
+        boolValue: boolean;
+    };
+};
+/** Anything we know how to put on an OTLP attribute. */
+export type AttrValue = string | number | boolean | undefined | null;
+export type TelemetryConfig = {
+    /** Collector base URL, e.g. http://localhost:4318. */
+    endpoint: string;
+    /** Logical service name reported to the backend. */
+    serviceName: string;
+    /** Outgoing headers, including any ingestion key the backend wants. */
+    headers: Record<string, string>;
+    enabled: boolean;
+    /**
+     * Per-signal switches, ANDed with `enabled`.
+     *
+     * The consent opt-outs (DO_NOT_TRACK, LOOM_TELEMETRY_DISABLED, LOOM_OTEL=0)
+     * kill everything — consent is not per-signal. These two are a different
+     * thing: volume control for someone who wants traces but not the log firehose
+     * (Loom ships every agent message as a log record, which is the point, and
+     * also a lot of bytes). Off means off for that signal only.
+     */
+    metricsEnabled: boolean;
+    logsEnabled: boolean;
+};
+/** Resolve config from the environment; disabled under standard opt-outs. */
+export declare function resolveTelemetryConfig(env?: NodeJS.ProcessEnv): TelemetryConfig;
+/**
+ * The `resource` block every signal carries. Identical across traces, metrics
+ * and logs on purpose: a backend keys a service off `service.name`, so a
+ * mismatch here is what makes a trace and its own logs look like two different
+ * apps.
+ */
+export declare function resourceAttributes(cfg: TelemetryConfig): KeyValue[];
+/**
+ * Encode an attribute bag, dropping empties.
+ *
+ * Absent is not the same as zero or "": a datapoint tagged
+ * `gen_ai.request.model=""` claims we know the model and it is the empty
+ * string. Leaving the key off says we don't know, which is the truth for
+ * adapters that never report one.
+ */
+export declare function encodeAttributes(attributes: Record<string, AttrValue>): KeyValue[];
+/** 16-byte trace id / 8-byte span id as lowercase hex (no crypto dep needed). */
+export declare function hexId(bytes: number): string;
+export type SpanInput = {
+    name: string;
+    startNs: bigint;
+    endNs: bigint;
+    attributes: Record<string, string | number | boolean | undefined | null>;
+    error?: string;
+    /** Correlate related spans (a turn + its tool calls) under one trace. */
+    traceId?: string;
+};
+/** A fresh 16-byte trace id — used to group a turn's spans into one trace. */
+export declare function newTraceId(): string;
+/**
+ * The exporter. Batches spans in a short window and POSTs OTLP/HTTP JSON.
+ * Failures are swallowed by design so tracing never breaks the app.
+ */
+export declare class LoomTelemetry {
+    private readonly cfg;
+    private buffer;
+    private timer;
+    private readonly tracesUrl;
+    private readonly resourceAttributes;
+    constructor(cfg: TelemetryConfig);
+    get enabled(): boolean;
+    /**
+     * Emit one span, returning the span id it was given — or undefined when
+     * telemetry is off and no span exists.
+     *
+     * The id goes back to the caller so a log record covering the same event can
+     * carry the same `spanId` and be clickable from that exact span, rather than
+     * only from the trace as a whole. Undefined rather than "" for the same
+     * reason turnTraceId() is: an empty span id is a link to nothing.
+     */
+    span(input: SpanInput): string | undefined;
+    private ensureTimer;
+    private drain;
+    flush(): void;
+}
+/**
+ * Fire one OTLP/HTTP JSON payload at the collector and forget about it.
+ *
+ * Deliberately not awaited and deliberately swallowing everything: telemetry is
+ * a side channel, and a collector that is down, slow or returning 400 must not
+ * become an unhandled rejection in an agent turn. Shared by all three signals
+ * so they fail the same silent way.
+ */
+export declare function postOtlp(url: string, headers: Record<string, string>, payload: unknown): void;
+export declare function kv(key: string, v: string | number | boolean): KeyValue;

package/dist/observability/otlp.js

@@ -0,0 +1,242 @@
+/**
+ * Loom → OpenTelemetry.
+ *
+ * A self-contained OTLP/HTTP (JSON) trace exporter — no OpenTelemetry SDK
+ * dependency, just `fetch`. Loom's agent lifecycle is already a stream of
+ * LoomEvents (turns, routes, baton handoffs, memory folds); this maps the
+ * notable ones to spans using the OpenTelemetry GenAI semantic conventions
+ * (`gen_ai.*`) so they land in the LLM/GenAI views every OTLP backend builds
+ * on those conventions.
+ *
+ * Backend-agnostic on purpose: this speaks OTLP/HTTP and nothing else, so it
+ * works against a plain OpenTelemetry Collector, Grafana/Tempo, Jaeger, SigNoz,
+ * Honeycomb — anything with a `/v1/traces` endpoint. Point
+ * OTEL_EXPORTER_OTLP_ENDPOINT at yours.
+ *
+ * This module owns traces plus the pieces every signal shares: the resolved
+ * config, the resource attributes, and the OTLP attribute encoding. The
+ * metrics (`./metrics.ts`) and logs (`./logs.ts`) exporters import those rather
+ * than growing their own copy, so a service.name change lands on all three at
+ * once and a span, a datapoint and a log line always agree about who emitted
+ * them.
+ *
+ * Egress is best-effort and consent-gated: if no collector is reachable the
+ * POST fails silently and never surfaces in the instrumented operation. Turn
+ * it off with DO_NOT_TRACK=1 or LOOM_TELEMETRY_DISABLED=1.
+ */
+const SPAN_KIND_INTERNAL = 1;
+const STATUS_OK = 1;
+const STATUS_ERROR = 2;
+/**
+ * Parse OTEL_EXPORTER_OTLP_HEADERS — the standard `k=v,k2=v2` form.
+ *
+ * This is how a backend's ingestion key reaches us without Loom knowing which
+ * backend it is. Hardcoding one vendor's header name would have meant a code
+ * change per destination.
+ */
+function parseOtlpHeaders(raw) {
+    const out = {};
+    if (!raw)
+        return out;
+    for (const pair of raw.split(",")) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const k = pair.slice(0, eq).trim();
+        const v = pair.slice(eq + 1).trim();
+        if (k && v)
+            out[k.toLowerCase()] = decodeURIComponent(v);
+    }
+    return out;
+}
+/** Resolve config from the environment; disabled under standard opt-outs. */
+export function resolveTelemetryConfig(env = process.env) {
+    const optedOut = truthy(env.DO_NOT_TRACK) ||
+        truthy(env.LOOM_TELEMETRY_DISABLED) ||
+        env.LOOM_OTEL === "0";
+    const endpoint = (env.LOOM_OTEL_ENDPOINT ||
+        env.OTEL_EXPORTER_OTLP_ENDPOINT ||
+        "http://localhost:4318").replace(/\/+$/, "");
+    const headers = {
+        "content-type": "application/json",
+        ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS),
+    };
+    const enabled = !optedOut;
+    return {
+        endpoint,
+        serviceName: env.LOOM_SERVICE_NAME || env.OTEL_SERVICE_NAME || "loom",
+        headers,
+        enabled,
+        metricsEnabled: enabled && env.LOOM_OTEL_METRICS !== "0",
+        logsEnabled: enabled && env.LOOM_OTEL_LOGS !== "0",
+    };
+}
+/**
+ * The `resource` block every signal carries. Identical across traces, metrics
+ * and logs on purpose: a backend keys a service off `service.name`, so a
+ * mismatch here is what makes a trace and its own logs look like two different
+ * apps.
+ */
+export function resourceAttributes(cfg) {
+    return [
+        kv("service.name", cfg.serviceName),
+        kv("service.namespace", "loom"),
+        kv("telemetry.sdk.name", "loom-otlp"),
+        kv("telemetry.sdk.language", "nodejs"),
+    ];
+}
+/**
+ * Encode an attribute bag, dropping empties.
+ *
+ * Absent is not the same as zero or "": a datapoint tagged
+ * `gen_ai.request.model=""` claims we know the model and it is the empty
+ * string. Leaving the key off says we don't know, which is the truth for
+ * adapters that never report one.
+ */
+export function encodeAttributes(attributes) {
+    const out = [];
+    for (const [k, v] of Object.entries(attributes)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        out.push(kv(k, v));
+    }
+    return out;
+}
+function truthy(v) {
+    return v === "1" || v === "true" || v === "yes";
+}
+/** 16-byte trace id / 8-byte span id as lowercase hex (no crypto dep needed). */
+export function hexId(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes; i++)
+        s += ((Math.random() * 256) | 0).toString(16).padStart(2, "0");
+    return s;
+}
+function str(v) {
+    return typeof v === "string" ? v : v == null ? "" : JSON.stringify(v);
+}
+/** A fresh 16-byte trace id — used to group a turn's spans into one trace. */
+export function newTraceId() {
+    return hexId(16);
+}
+/**
+ * The exporter. Batches spans in a short window and POSTs OTLP/HTTP JSON.
+ * Failures are swallowed by design so tracing never breaks the app.
+ */
+export class LoomTelemetry {
+    cfg;
+    buffer = [];
+    timer = null;
+    tracesUrl;
+    resourceAttributes;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.tracesUrl = `${cfg.endpoint}/v1/traces`;
+        this.resourceAttributes = resourceAttributes(cfg);
+    }
+    get enabled() {
+        return this.cfg.enabled && typeof globalThis.fetch === "function";
+    }
+    /**
+     * Emit one span, returning the span id it was given — or undefined when
+     * telemetry is off and no span exists.
+     *
+     * The id goes back to the caller so a log record covering the same event can
+     * carry the same `spanId` and be clickable from that exact span, rather than
+     * only from the trace as a whole. Undefined rather than "" for the same
+     * reason turnTraceId() is: an empty span id is a link to nothing.
+     */
+    span(input) {
+        if (!this.enabled)
+            return undefined;
+        const spanId = hexId(8);
+        this.buffer.push({
+            traceId: input.traceId ?? hexId(16),
+            spanId,
+            name: input.name,
+            kind: SPAN_KIND_INTERNAL,
+            startTimeUnixNano: input.startNs.toString(),
+            endTimeUnixNano: input.endNs.toString(),
+            attributes: encodeAttributes(input.attributes),
+            status: input.error
+                ? { code: STATUS_ERROR, message: input.error }
+                : { code: STATUS_OK },
+        });
+        if (this.buffer.length >= 64)
+            this.drain();
+        else
+            this.ensureTimer();
+        return spanId;
+    }
+    ensureTimer() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.drain();
+        }, 1500);
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    drain() {
+        if (this.buffer.length === 0)
+            return;
+        const spans = this.buffer;
+        this.buffer = [];
+        const payload = {
+            resourceSpans: [
+                {
+                    resource: { attributes: this.resourceAttributes },
+                    scopeSpans: [{ scope: { name: "loom" }, spans }],
+                },
+            ],
+        };
+        postOtlp(this.tracesUrl, this.cfg.headers, payload);
+    }
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.drain();
+    }
+}
+/**
+ * Fire one OTLP/HTTP JSON payload at the collector and forget about it.
+ *
+ * Deliberately not awaited and deliberately swallowing everything: telemetry is
+ * a side channel, and a collector that is down, slow or returning 400 must not
+ * become an unhandled rejection in an agent turn. Shared by all three signals
+ * so they fail the same silent way.
+ */
+export function postOtlp(url, headers, payload) {
+    void Promise.resolve()
+        .then(async () => {
+        const res = await globalThis.fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+            // a collector that accepts and stalls would hold every payload for minutes
+            signal: AbortSignal.timeout(10_000),
+        });
+        // Drain the response even though we don't care what it says. undici keeps
+        // a pooled socket checked out until its body is consumed, so a fire-and-
+        // forget POST that never reads the reply holds a connection open until
+        // GC. One signal got away with that; three signals on a busy event stream
+        // exhaust the pool and start queueing — which shows up as the *agent*
+        // getting slower, i.e. exactly the thing telemetry must never do.
+        await res.arrayBuffer().catch(() => undefined);
+    })
+        .catch(() => {
+        /* best-effort: an unreachable collector must never surface */
+    });
+}
+export function kv(key, v) {
+    if (typeof v === "number") {
+        return Number.isInteger(v) ? { key, value: { intValue: String(v) } } : { key, value: { doubleValue: v } };
+    }
+    if (typeof v === "boolean")
+        return { key, value: { boolValue: v } };
+    return { key, value: { stringValue: str(v) } };
+}
+//# sourceMappingURL=otlp.js.map