@seanhogg/builderforce-memory 2026.7.14 → 2026.9.28

package/dist/telemetry/Tracer.js

@@ -0,0 +1,244 @@
+/**
+ * telemetry/Tracer.ts — granular tracing for agent runs.
+ *
+ * A production agent failure is almost never "the LLM was wrong"; it is "the
+ * retrieval returned nothing, so the LLM was asked to answer from an empty
+ * context". You can only see that with a span tree covering the WHOLE request —
+ * ingest, retrieval, each graph node, each model call — under one trace id.
+ *
+ * `now` and `newId` are injected so traces are deterministic under test; the
+ * defaults use wall-clock and a random hex id.
+ */
+import { estimateCostUsd, DEFAULT_PRICE_BOOK } from './pricing.js';
+import { formatTraceparent } from './traceparent.js';
+/**
+ * A live span. Mutating methods are no-ops once `end()`/`fail()` has run, so a
+ * late callback (a stream resolving after a timeout) cannot corrupt a span that
+ * has already been exported.
+ */
+export class Span {
+    _tracer;
+    _data;
+    _closed = false;
+    _recorded;
+    /** @internal — construct via {@link Tracer.startSpan}. */
+    constructor(tracer, data, recorded) {
+        this._tracer = tracer;
+        this._data = data;
+        this._recorded = recorded;
+    }
+    get traceId() { return this._data.traceId; }
+    get spanId() { return this._data.spanId; }
+    get name() { return this._data.name; }
+    get closed() { return this._closed; }
+    /** False when this trace was dropped by sampling — nothing will be exported. */
+    get recorded() { return this._recorded; }
+    /** A snapshot copy; mutating it does not affect the span. */
+    get data() {
+        return { ...this._data, attributes: { ...this._data.attributes }, events: [...this._data.events] };
+    }
+    setAttribute(key, value) {
+        if (!this._closed)
+            this._data.attributes[key] = value;
+        return this;
+    }
+    setAttributes(attrs) {
+        for (const [k, v] of Object.entries(attrs)) {
+            if (v !== undefined)
+                this.setAttribute(k, v);
+        }
+        return this;
+    }
+    addEvent(name, attributes) {
+        if (this._closed)
+            return this;
+        const event = { name, at: this._tracer.now() };
+        if (attributes)
+            event.attributes = attributes;
+        this._data.events.push(event);
+        return this;
+    }
+    /** Records token usage and prices it with the tracer's price book. */
+    recordUsage(usage) {
+        if (this._closed)
+            return this;
+        this._data.usage = usage;
+        const cost = estimateCostUsd(usage, this._tracer.pricing);
+        if (cost !== undefined)
+            this._data.costUsd = cost;
+        return this;
+    }
+    /** Marks time-to-first-token; call when a stream yields its first chunk. */
+    recordFirstToken() {
+        if (this._closed)
+            return this;
+        this._data.timeToFirstTokenMs = this._tracer.now() - this._data.startedAt;
+        return this.addEvent('first-token');
+    }
+    /** Opens a child span inside this one (same trace, this span as parent). */
+    child(name, opts = {}) {
+        return this._tracer.startSpan(name, { ...opts, parent: this });
+    }
+    /**
+     * This span's position, for handing to another process. The sampling flag is the
+     * span's OWN `recorded` verdict, so the next hop inherits the decision already
+     * taken rather than making a second, possibly contradictory one.
+     */
+    context() {
+        return { traceId: this._data.traceId, spanId: this._data.spanId, sampled: this._recorded };
+    }
+    /**
+     * The `traceparent` header value to send on an outbound request made inside this
+     * span. Set it and the callee's root span becomes this span's child.
+     */
+    traceparent() {
+        return formatTraceparent(this.context());
+    }
+    end(status = 'ok') {
+        return this._close(status);
+    }
+    /** Ends the span as failed, recording the error message. */
+    fail(error) {
+        if (!this._closed) {
+            this._data.error = error instanceof Error ? error.message : String(error);
+        }
+        return this._close('error');
+    }
+    _close(status) {
+        if (this._closed)
+            return this.data;
+        this._closed = true;
+        this._data.status = status;
+        this._data.endedAt = this._tracer.now();
+        this._data.durationMs = this._data.endedAt - this._data.startedAt;
+        this._tracer._finish(this._data, this._recorded);
+        return this.data;
+    }
+}
+export class Tracer {
+    pricing;
+    _exporter;
+    _now;
+    _newId;
+    _maxBatch;
+    _sampleRate;
+    _random;
+    _buffer = [];
+    _finished = [];
+    /** traceId -> sampling decision, so children inherit the root's verdict. */
+    _sampled = new Map();
+    constructor(opts = {}) {
+        if (opts.exporter)
+            this._exporter = opts.exporter;
+        this.pricing = opts.pricing ?? DEFAULT_PRICE_BOOK;
+        this._now = opts.now ?? (() => Date.now());
+        this._newId = opts.newId ?? defaultIdFactory();
+        this._maxBatch = Math.max(1, opts.maxBatchSize ?? 64);
+        this._sampleRate = clamp01(opts.sampleRate ?? 1);
+        this._random = opts.random ?? Math.random;
+    }
+    now() { return this._now(); }
+    startSpan(name, opts = {}) {
+        // An in-process parent beats a remote one: if both are present the remote
+        // header is stale context that the live parent already descends from.
+        const remote = opts.parent ? undefined : opts.remoteParent;
+        const traceId = opts.parent?.traceId ?? remote?.traceId ?? opts.traceId ?? this._newId(16);
+        const recorded = remote
+            ? this._adoptSampling(traceId, remote.sampled)
+            : this._decideSampling(traceId, Boolean(opts.parent));
+        const data = {
+            traceId,
+            spanId: this._newId(8),
+            name,
+            kind: opts.kind ?? 'internal',
+            startedAt: this._now(),
+            attributes: { ...(opts.attributes ?? {}) },
+            events: [],
+            status: 'unset',
+        };
+        if (opts.parent)
+            data.parentSpanId = opts.parent.spanId;
+        else if (remote)
+            data.parentSpanId = remote.spanId;
+        return new Span(this, data, recorded);
+    }
+    /**
+     * Runs `fn` inside a span, ending it `ok` on resolve and `error` on throw.
+     * Every subsystem uses this rather than hand-pairing start/end, so a thrown
+     * error can never leak an un-ended span into the trace tree.
+     */
+    async withSpan(name, opts, fn) {
+        const span = this.startSpan(name, opts);
+        try {
+            const out = await fn(span);
+            span.end('ok');
+            return out;
+        }
+        catch (err) {
+            span.fail(err);
+            throw err;
+        }
+    }
+    /** All spans finished since construction (recorded ones only). */
+    finished() { return this._finished; }
+    /** Spans of one trace, in completion order. */
+    trace(traceId) {
+        return this._finished.filter((s) => s.traceId === traceId);
+    }
+    /** Pushes any buffered spans to the exporter. */
+    async flush() {
+        if (this._buffer.length === 0)
+            return;
+        const batch = this._buffer;
+        this._buffer = [];
+        await this._exporter?.export(batch);
+    }
+    async shutdown() {
+        await this.flush();
+        await this._exporter?.shutdown?.();
+    }
+    /** @internal */
+    _finish(data, recorded) {
+        if (!recorded)
+            return;
+        this._finished.push(data);
+        this._buffer.push(data);
+        if (this._buffer.length >= this._maxBatch)
+            void this.flush();
+    }
+    /**
+     * Take the upstream hop's sampling verdict verbatim and record it against the
+     * trace, so every later span in this process inherits it too. Head-based
+     * sampling only works if it is decided ONCE, at the head.
+     */
+    _adoptSampling(traceId, sampled) {
+        const known = this._sampled.get(traceId);
+        if (known !== undefined)
+            return known;
+        this._sampled.set(traceId, sampled);
+        return sampled;
+    }
+    _decideSampling(traceId, hasParent) {
+        const known = this._sampled.get(traceId);
+        if (known !== undefined)
+            return known;
+        // A child whose parent's decision is unknown defaults to recorded rather
+        // than re-rolling the dice, which would tear a trace in half.
+        const decision = hasParent || this._sampleRate >= 1 || this._random() < this._sampleRate;
+        this._sampled.set(traceId, decision);
+        return decision;
+    }
+}
+function clamp01(n) {
+    return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 1;
+}
+function defaultIdFactory() {
+    return (bytes) => {
+        let out = '';
+        for (let i = 0; i < bytes; i++) {
+            out += Math.floor(Math.random() * 256).toString(16).padStart(2, '0');
+        }
+        return out;
+    };
+}
+//# sourceMappingURL=Tracer.js.map

package/dist/telemetry/Tracer.js.map

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

package/dist/telemetry/exporters.d.ts

@@ -0,0 +1,68 @@
+/**
+ * telemetry/exporters.ts — where finished spans go.
+ *
+ * Three sinks cover the deployment spectrum without a vendor dependency:
+ *   • {@link InMemorySpanExporter} — tests and in-process dashboards.
+ *   • {@link ConsoleSpanExporter}  — local development.
+ *   • {@link OtlpHttpSpanExporter} — any OTLP/HTTP collector, which includes
+ *     Google Cloud Trace, Datadog, Honeycomb, Grafana Tempo and the OpenTelemetry
+ *     Collector. It speaks the protocol over `fetch` rather than importing the
+ *     OpenTelemetry SDK, so the package stays zero-dependency and still runs in a
+ *     browser or a Cloudflare Worker where the Node SDK cannot.
+ */
+import type { SpanData, SpanExporter } from './types.js';
+export declare class InMemorySpanExporter implements SpanExporter {
+    private readonly _spans;
+    export(spans: readonly SpanData[]): void;
+    get spans(): readonly SpanData[];
+    /** Spans belonging to one trace, oldest first. */
+    trace(traceId: string): SpanData[];
+    reset(): void;
+}
+export interface ConsoleSpanExporterOptions {
+    /** Sink for the rendered lines. Default `console.log`. */
+    write?: (line: string) => void;
+    /** Include span attributes. Default false — one line per span. */
+    verbose?: boolean;
+}
+export declare class ConsoleSpanExporter implements SpanExporter {
+    private readonly _write;
+    private readonly _verbose;
+    constructor(opts?: ConsoleSpanExporterOptions);
+    export(spans: readonly SpanData[]): void;
+}
+export interface OtlpHttpSpanExporterOptions {
+    /** Collector endpoint, e.g. `https://otlp.example.com/v1/traces`. */
+    url: string;
+    /** Extra headers (auth token, GCP project header, …). */
+    headers?: Record<string, string>;
+    /** `service.name` reported on the resource. Default `evermind`. */
+    serviceName?: string;
+    /** Injected for test. Default global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Called when an export request fails. Default: swallow. Telemetry must never
+     * take down the request it is measuring, so failures are reported, not thrown.
+     */
+    onError?: (err: unknown) => void;
+}
+export declare class OtlpHttpSpanExporter implements SpanExporter {
+    private readonly _url;
+    private readonly _headers;
+    private readonly _serviceName;
+    private readonly _fetch;
+    private readonly _onError;
+    constructor(opts: OtlpHttpSpanExporterOptions);
+    export(spans: readonly SpanData[]): Promise<void>;
+}
+/** Wraps spans in the OTLP/HTTP JSON envelope. */
+export declare function toOtlpPayload(spans: readonly SpanData[], serviceName?: string): unknown;
+/**
+ * Converts one span to the OTLP wire shape. The mapping is a rename, not a
+ * re-model, because {@link SpanData} was designed against this schema.
+ *
+ * LLM attributes follow the OpenTelemetry GenAI semantic conventions
+ * (`gen_ai.*`) so a stock trace viewer renders token counts without config.
+ */
+export declare function toOtlpSpan(span: SpanData): unknown;
+//# sourceMappingURL=exporters.d.ts.map

package/dist/telemetry/exporters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporters.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAkB,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzE,qBAAa,oBAAqB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,MAAM,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI;IAIxC,IAAI,KAAK,IAAI,SAAS,QAAQ,EAAE,CAAwB;IAExD,kDAAkD;IAClD,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE;IAIlC,KAAK,IAAI,IAAI;CAChB;AAED,MAAM,WAAW,0BAA0B;IACvC,0DAA0D;IAC1D,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,mBAAoB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,IAAI,GAAE,0BAA+B;IAKjD,MAAM,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI;CAc3C;AAED,MAAM,WAAW,2BAA2B;IACxC,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAMD,qBAAa,oBAAqB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAEtC,IAAI,EAAE,2BAA2B;IAQvC,MAAM,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAa1D;AAED,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,WAAW,SAAa,GAAG,OAAO,CAU3F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAqClD"}

package/dist/telemetry/exporters.js

@@ -0,0 +1,145 @@
+/**
+ * telemetry/exporters.ts — where finished spans go.
+ *
+ * Three sinks cover the deployment spectrum without a vendor dependency:
+ *   • {@link InMemorySpanExporter} — tests and in-process dashboards.
+ *   • {@link ConsoleSpanExporter}  — local development.
+ *   • {@link OtlpHttpSpanExporter} — any OTLP/HTTP collector, which includes
+ *     Google Cloud Trace, Datadog, Honeycomb, Grafana Tempo and the OpenTelemetry
+ *     Collector. It speaks the protocol over `fetch` rather than importing the
+ *     OpenTelemetry SDK, so the package stays zero-dependency and still runs in a
+ *     browser or a Cloudflare Worker where the Node SDK cannot.
+ */
+export class InMemorySpanExporter {
+    _spans = [];
+    export(spans) {
+        this._spans.push(...spans);
+    }
+    get spans() { return this._spans; }
+    /** Spans belonging to one trace, oldest first. */
+    trace(traceId) {
+        return this._spans.filter((s) => s.traceId === traceId);
+    }
+    reset() { this._spans.length = 0; }
+}
+export class ConsoleSpanExporter {
+    _write;
+    _verbose;
+    constructor(opts = {}) {
+        this._write = opts.write ?? ((line) => console.log(line));
+        this._verbose = opts.verbose ?? false;
+    }
+    export(spans) {
+        for (const span of spans) {
+            const cost = span.costUsd !== undefined ? ` $${span.costUsd.toFixed(6)}` : '';
+            const tokens = span.usage ? ` ${span.usage.inputTokens}in/${span.usage.outputTokens}out` : '';
+            const status = span.status === 'error' ? ` ERROR: ${span.error ?? ''}` : '';
+            this._write(`[${span.traceId.slice(0, 8)}] ${span.kind.padEnd(9)} ${span.name} ` +
+                `${Math.round(span.durationMs ?? 0)}ms${tokens}${cost}${status}`);
+            if (this._verbose && Object.keys(span.attributes).length > 0) {
+                this._write(`         ${JSON.stringify(span.attributes)}`);
+            }
+        }
+    }
+}
+/** OTLP span kind codes: UNSPECIFIED 0, INTERNAL 1, SERVER 2, CLIENT 3. */
+const OTLP_CLIENT = 3;
+const OTLP_INTERNAL = 1;
+export class OtlpHttpSpanExporter {
+    _url;
+    _headers;
+    _serviceName;
+    _fetch;
+    _onError;
+    constructor(opts) {
+        this._url = opts.url;
+        this._headers = opts.headers ?? {};
+        this._serviceName = opts.serviceName ?? 'evermind';
+        this._fetch = opts.fetchImpl ?? ((...args) => fetch(...args));
+        this._onError = opts.onError ?? (() => { });
+    }
+    async export(spans) {
+        if (spans.length === 0)
+            return;
+        try {
+            const res = await this._fetch(this._url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...this._headers },
+                body: JSON.stringify(toOtlpPayload(spans, this._serviceName)),
+            });
+            if (!res.ok)
+                this._onError(new Error(`OTLP export failed: ${res.status}`));
+        }
+        catch (err) {
+            this._onError(err);
+        }
+    }
+}
+/** Wraps spans in the OTLP/HTTP JSON envelope. */
+export function toOtlpPayload(spans, serviceName = 'evermind') {
+    return {
+        resourceSpans: [{
+                resource: { attributes: [otlpAttr('service.name', serviceName)] },
+                scopeSpans: [{
+                        scope: { name: '@seanhogg/builderforce-memory' },
+                        spans: spans.map(toOtlpSpan),
+                    }],
+            }],
+    };
+}
+/**
+ * Converts one span to the OTLP wire shape. The mapping is a rename, not a
+ * re-model, because {@link SpanData} was designed against this schema.
+ *
+ * LLM attributes follow the OpenTelemetry GenAI semantic conventions
+ * (`gen_ai.*`) so a stock trace viewer renders token counts without config.
+ */
+export function toOtlpSpan(span) {
+    const attributes = Object.entries(span.attributes).map(([k, v]) => otlpAttr(k, v));
+    if (span.usage) {
+        attributes.push(otlpAttr('gen_ai.request.model', span.usage.model), otlpAttr('gen_ai.usage.input_tokens', span.usage.inputTokens), otlpAttr('gen_ai.usage.output_tokens', span.usage.outputTokens));
+        if (span.usage.cachedInputTokens !== undefined) {
+            attributes.push(otlpAttr('gen_ai.usage.cached_input_tokens', span.usage.cachedInputTokens));
+        }
+    }
+    if (span.costUsd !== undefined)
+        attributes.push(otlpAttr('gen_ai.usage.cost_usd', span.costUsd));
+    if (span.timeToFirstTokenMs !== undefined) {
+        attributes.push(otlpAttr('gen_ai.server.time_to_first_token_ms', span.timeToFirstTokenMs));
+    }
+    const out = {
+        traceId: span.traceId,
+        spanId: span.spanId,
+        name: span.name,
+        kind: span.kind === 'llm' || span.kind === 'embedding' ? OTLP_CLIENT : OTLP_INTERNAL,
+        startTimeUnixNano: msToNano(span.startedAt),
+        endTimeUnixNano: msToNano(span.endedAt ?? span.startedAt),
+        attributes,
+        events: span.events.map((e) => ({
+            name: e.name,
+            timeUnixNano: msToNano(e.at),
+            attributes: Object.entries(e.attributes ?? {}).map(([k, v]) => otlpAttr(k, v)),
+        })),
+        status: span.status === 'error'
+            ? { code: 2, message: span.error ?? '' }
+            : { code: span.status === 'ok' ? 1 : 0 },
+    };
+    if (span.parentSpanId)
+        out['parentSpanId'] = span.parentSpanId;
+    return out;
+}
+function otlpAttr(key, value) {
+    if (typeof value === 'number') {
+        return Number.isInteger(value)
+            ? { key, value: { intValue: value } }
+            : { key, value: { doubleValue: value } };
+    }
+    if (typeof value === 'boolean')
+        return { key, value: { boolValue: value } };
+    return { key, value: { stringValue: value } };
+}
+/** OTLP timestamps are nanoseconds since the epoch, as a decimal string. */
+function msToNano(ms) {
+    return `${Math.round(ms)}000000`;
+}
+//# sourceMappingURL=exporters.js.map

package/dist/telemetry/exporters.js.map

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

package/dist/telemetry/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * telemetry — granular tracing plus LLM-native metrics (tokens/sec, TTFT,
+ * cost-per-request, cache-hit rate), built on ONE span stream so the trace view
+ * and the metric view can never disagree.
+ */
+export { Tracer, Span } from './Tracer.js';
+export type { TracerOptions, SpanOptions } from './Tracer.js';
+export { parseTraceparent, formatTraceparent } from './traceparent.js';
+export type { TraceContext } from './traceparent.js';
+export { MetricsRegistry, percentile } from './MetricsRegistry.js';
+export type { LlmMetricSnapshot, KindMetricSnapshot, MetricsRegistryOptions, } from './MetricsRegistry.js';
+export { InstrumentedBridge } from './InstrumentedBridge.js';
+export type { InstrumentedBridgeOptions } from './InstrumentedBridge.js';
+export { InMemorySpanExporter, ConsoleSpanExporter, OtlpHttpSpanExporter, toOtlpPayload, toOtlpSpan, } from './exporters.js';
+export type { ConsoleSpanExporterOptions, OtlpHttpSpanExporterOptions, } from './exporters.js';
+export { estimateCostUsd, estimateTokens, resolveRate, DEFAULT_PRICE_BOOK, ANTHROPIC_PRICE_BOOK, EVERMIND_PRICE_BOOK, DEFAULT_CACHE_READ_MULTIPLIER, DEFAULT_CACHE_WRITE_MULTIPLIER, } from './pricing.js';
+export type { ModelRate, PriceBook } from './pricing.js';
+export type { AttributeValue, SpanKind, SpanStatus, SpanEvent, SpanData, SpanExporter, LlmUsage, BridgeCallInfo, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACvE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACnE,YAAY,EACR,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAEzE,OAAO,EACH,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,UAAU,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACR,0BAA0B,EAC1B,2BAA2B,GAC9B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACH,eAAe,EACf,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,6BAA6B,EAC7B,8BAA8B,GACjC,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzD,YAAY,EACR,cAAc,EACd,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,cAAc,GACjB,MAAM,YAAY,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,12 @@
+/**
+ * telemetry — granular tracing plus LLM-native metrics (tokens/sec, TTFT,
+ * cost-per-request, cache-hit rate), built on ONE span stream so the trace view
+ * and the metric view can never disagree.
+ */
+export { Tracer, Span } from './Tracer.js';
+export { parseTraceparent, formatTraceparent } from './traceparent.js';
+export { MetricsRegistry, percentile } from './MetricsRegistry.js';
+export { InstrumentedBridge } from './InstrumentedBridge.js';
+export { InMemorySpanExporter, ConsoleSpanExporter, OtlpHttpSpanExporter, toOtlpPayload, toOtlpSpan, } from './exporters.js';
+export { estimateCostUsd, estimateTokens, resolveRate, DEFAULT_PRICE_BOOK, ANTHROPIC_PRICE_BOOK, EVERMIND_PRICE_BOOK, DEFAULT_CACHE_READ_MULTIPLIER, DEFAULT_CACHE_WRITE_MULTIPLIER, } from './pricing.js';
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAOnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EACH,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,UAAU,GACb,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EACH,eAAe,EACf,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,6BAA6B,EAC7B,8BAA8B,GACjC,MAAM,cAAc,CAAC"}

package/dist/telemetry/pricing.d.ts

@@ -0,0 +1,74 @@
+/**
+ * telemetry/pricing.ts — cost-per-request, computed from real token counts.
+ *
+ * "Cost per request" is an LLM-native metric that cannot be derived from latency
+ * or call count: it depends on the model, the input/output split, AND how much of
+ * the input was a cache read (cheap) versus a cache write (dear). This module is
+ * the ONE place that arithmetic lives, so the bridges, the metrics registry, and
+ * the eval harness cannot disagree about what a run cost.
+ *
+ * Rates are DATA, not code: an enterprise on a negotiated rate card, a partner
+ * platform (Bedrock/Vertex bill separately from the first-party API), or a model
+ * released after this file was written is handled by passing a {@link PriceBook},
+ * never by editing a branch. Unknown models cost `undefined` — reported as an
+ * `unpricedCalls` count rather than silently billed at zero, because a silent
+ * zero is how cost dashboards lie.
+ */
+import type { LlmUsage } from './types.js';
+export interface ModelRate {
+    /** USD per 1M input tokens. */
+    inputPerMTok: number;
+    /** USD per 1M output tokens. */
+    outputPerMTok: number;
+    /**
+     * Multiplier applied to `inputPerMTok` for tokens READ from the provider's
+     * prompt cache. Anthropic bills cache reads at 10% of input. Default 0.1.
+     */
+    cacheReadMultiplier?: number;
+    /**
+     * Multiplier applied to `inputPerMTok` for tokens WRITTEN to the prompt
+     * cache. Anthropic bills a 5-minute cache write at 125% of input. Default 1.25.
+     */
+    cacheWriteMultiplier?: number;
+}
+/** Model id → rate. Keys match exactly, or by longest prefix (see {@link resolveRate}). */
+export type PriceBook = Record<string, ModelRate>;
+export declare const DEFAULT_CACHE_READ_MULTIPLIER = 0.1;
+export declare const DEFAULT_CACHE_WRITE_MULTIPLIER = 1.25;
+/**
+ * First-party Anthropic API rates (USD / 1M tokens), current as of 2026-08-20.
+ *
+ * Bedrock and Vertex are partner-operated and priced separately — supply those
+ * rates via a custom {@link PriceBook} rather than assuming these apply.
+ */
+export declare const ANTHROPIC_PRICE_BOOK: PriceBook;
+/**
+ * Evermind serves `evermind/<ref>` traffic on-device, so it has no per-token
+ * vendor bill. It is priced explicitly at zero rather than left unknown — the
+ * whole point of routing to Evermind is that the saving is *measurable*.
+ */
+export declare const EVERMIND_PRICE_BOOK: PriceBook;
+export declare const DEFAULT_PRICE_BOOK: PriceBook;
+/**
+ * Resolves a model id to a rate: exact match first, then the longest key the
+ * model id starts with. Prefix matching is what makes dated snapshots
+ * (`claude-opus-4-5@20251101`) and platform-prefixed ids (`anthropic.claude-opus-5`)
+ * resolve without a per-variant entry.
+ */
+export declare function resolveRate(model: string, book?: PriceBook): ModelRate | undefined;
+/**
+ * Cost in USD for one call, or `undefined` when the model is not in the book.
+ *
+ * A locally-served call (`localCacheHit`) is free by construction — it never
+ * reached a provider — so it costs 0 even for an unpriced model.
+ */
+export declare function estimateCostUsd(usage: LlmUsage, book?: PriceBook): number | undefined;
+/**
+ * Character-based token estimate — the fallback when a provider reports no usage.
+ *
+ * ~4 characters per token is the standard English approximation. Estimates are
+ * flagged (`estimated: true`) all the way through to the metric snapshot so a
+ * cost figure never silently mixes measured and guessed numbers.
+ */
+export declare function estimateTokens(text: string): number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/telemetry/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/telemetry/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,SAAS;IACtB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,2FAA2F;AAC3F,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAElD,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAUlC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAGjC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,SAA+D,CAAC;AAEjG;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,SAA8B,GAAG,SAAS,GAAG,SAAS,CAatG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,GAAE,SAA8B,GAAG,MAAM,GAAG,SAAS,CAiBzG;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD"}