@seanhogg/builderforce-memory 2026.7.14 → 2026.9.28

package/dist/runtime/SSMRuntime.d.ts

@@ -156,7 +156,7 @@ export declare class SSMRuntime {
      * Escape hatch to the underlying MambaSession internals.
      * Use sparingly — the SSMRuntime API covers the common cases.
      */
-    get internals(): import("../session/session.js").SessionInternals;
+    get internals(): import("../index.js").SessionInternals;
     /**
      * Destroys the underlying MambaSession and releases all GPU resources.
      * After calling this, all methods throw SSMError('RUNTIME_DESTROYED').

package/dist/runtime/SSMRuntime.d.ts.map

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

package/dist/telemetry/InstrumentedBridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * telemetry/InstrumentedBridge.ts — one decorator that makes ANY bridge observable.
+ *
+ * The alternative — instrumenting Anthropic, OpenAI, Vertex, Fetch, Caching and
+ * SemanticCaching bridges each in their own way — guarantees six subtly different
+ * definitions of "a call". This is a single decorator over the
+ * {@link TransformerBridge} port, so a bridge added tomorrow is observable the
+ * moment it satisfies the interface, and the caching bridges are measured at the
+ * same seam as the provider bridges (which is how the cache-hit rate becomes a
+ * real number rather than an anecdote).
+ *
+ * Token counts come from the provider when the inner bridge reports them via
+ * `lastCall`, and are estimated from characters otherwise — with `estimated: true`
+ * carried through to the metric snapshot so a dashboard never mixes measured and
+ * inferred spend without saying so.
+ */
+import type { TransformerBridge, BridgeGenerateOptions } from '../bridges/TransformerBridge.js';
+import { Tracer, type Span } from './Tracer.js';
+import type { LlmUsage } from './types.js';
+export interface InstrumentedBridgeOptions {
+    /** Tracer that receives the spans. */
+    tracer: Tracer;
+    /** Model label used when the inner bridge reports none. Default `'unknown'`. */
+    model?: string;
+    /** Span name. Default `'llm.generate'`. */
+    spanName?: string;
+    /**
+     * Parent span, so a model call nests under the agent/graph node that made it.
+     * A function is accepted for the common case where the parent changes per call.
+     */
+    parent?: Span | (() => Span | undefined);
+    /** Static attributes stamped on every span (tenant, environment, route). */
+    attributes?: Record<string, string | number | boolean>;
+    /**
+     * Token counter, when an exact one is available (e.g. the provider's
+     * count_tokens endpoint). Default: ~4 chars per token.
+     */
+    countTokens?: (text: string) => number;
+}
+export declare class InstrumentedBridge implements TransformerBridge {
+    readonly supportsStreaming: boolean;
+    private readonly _inner;
+    private readonly _tracer;
+    private readonly _model;
+    private readonly _spanName;
+    private readonly _parent?;
+    private readonly _attributes;
+    private readonly _count;
+    private _lastCall;
+    constructor(inner: TransformerBridge, opts: InstrumentedBridgeOptions);
+    /** Usage/cache info for the most recent call — makes the decorator chainable. */
+    get lastCall(): {
+        usage?: LlmUsage;
+        cacheHit?: boolean;
+        cacheTier?: string;
+    } | undefined;
+    generate(prompt: string, opts?: BridgeGenerateOptions): Promise<string>;
+    stream(prompt: string, opts?: BridgeGenerateOptions): AsyncIterable<string>;
+    private _startSpan;
+    private _finish;
+}
+//# sourceMappingURL=InstrumentedBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InstrumentedBridge.d.ts","sourceRoot":"","sources":["../../src/telemetry/InstrumentedBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAEhG,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,yBAAyB;IACtC,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC;IACzC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACvD;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1C;AAED,qBAAa,kBAAmB,YAAW,iBAAiB;IACxD,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4C;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,OAAO,CAAC,SAAS,CAA2E;gBAEhF,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,yBAAyB;IAWrE,iFAAiF;IACjF,IAAI,QAAQ,IAAI;QAAE,KAAK,CAAC,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAEvF;IAEK,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,MAAM,CAAC;IAa1E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,aAAa,CAAC,MAAM,CAAC;IAwBtF,OAAO,CAAC,UAAU;IAiBlB,OAAO,CAAC,OAAO;CAyBlB"}

package/dist/telemetry/InstrumentedBridge.js

@@ -0,0 +1,120 @@
+/**
+ * telemetry/InstrumentedBridge.ts — one decorator that makes ANY bridge observable.
+ *
+ * The alternative — instrumenting Anthropic, OpenAI, Vertex, Fetch, Caching and
+ * SemanticCaching bridges each in their own way — guarantees six subtly different
+ * definitions of "a call". This is a single decorator over the
+ * {@link TransformerBridge} port, so a bridge added tomorrow is observable the
+ * moment it satisfies the interface, and the caching bridges are measured at the
+ * same seam as the provider bridges (which is how the cache-hit rate becomes a
+ * real number rather than an anecdote).
+ *
+ * Token counts come from the provider when the inner bridge reports them via
+ * `lastCall`, and are estimated from characters otherwise — with `estimated: true`
+ * carried through to the metric snapshot so a dashboard never mixes measured and
+ * inferred spend without saying so.
+ */
+import { estimateTokens } from './pricing.js';
+export class InstrumentedBridge {
+    supportsStreaming;
+    _inner;
+    _tracer;
+    _model;
+    _spanName;
+    _parent;
+    _attributes;
+    _count;
+    _lastCall;
+    constructor(inner, opts) {
+        this._inner = inner;
+        this._tracer = opts.tracer;
+        this._model = opts.model ?? 'unknown';
+        this._spanName = opts.spanName ?? 'llm.generate';
+        if (opts.parent)
+            this._parent = opts.parent;
+        this._attributes = opts.attributes ?? {};
+        this._count = opts.countTokens ?? estimateTokens;
+        this.supportsStreaming = inner.supportsStreaming;
+    }
+    /** Usage/cache info for the most recent call — makes the decorator chainable. */
+    get lastCall() {
+        return this._lastCall;
+    }
+    async generate(prompt, opts = {}) {
+        const span = this._startSpan(prompt, opts, false);
+        try {
+            const reply = await this._inner.generate(prompt, opts);
+            this._finish(span, prompt, reply, opts);
+            span.end('ok');
+            return reply;
+        }
+        catch (err) {
+            span.fail(err);
+            throw err;
+        }
+    }
+    async *stream(prompt, opts = {}) {
+        if (!this._inner.stream) {
+            throw new Error('InstrumentedBridge: the wrapped bridge does not support streaming.');
+        }
+        const span = this._startSpan(prompt, opts, true);
+        let reply = '';
+        let first = true;
+        try {
+            for await (const chunk of this._inner.stream(prompt, opts)) {
+                if (first) {
+                    span.recordFirstToken();
+                    first = false;
+                }
+                reply += chunk;
+                yield chunk;
+            }
+            this._finish(span, prompt, reply, opts);
+            span.end('ok');
+        }
+        catch (err) {
+            span.fail(err);
+            throw err;
+        }
+    }
+    _startSpan(prompt, opts, streaming) {
+        const parent = typeof this._parent === 'function' ? this._parent() : this._parent;
+        const span = this._tracer.startSpan(this._spanName, {
+            kind: 'llm',
+            ...(parent ? { parent } : {}),
+        });
+        span.setAttributes({
+            ...this._attributes,
+            'llm.model': opts.model ?? this._model,
+            'llm.streaming': streaming,
+            'llm.prompt_chars': prompt.length,
+            'llm.max_tokens': opts.maxTokens,
+            'llm.temperature': opts.temperature,
+        });
+        return span;
+    }
+    _finish(span, prompt, reply, opts) {
+        const reported = this._inner.lastCall;
+        const model = reported?.usage?.model ?? opts.model ?? this._model;
+        const usage = reported?.usage ?? {
+            model,
+            inputTokens: this._count(prompt),
+            outputTokens: this._count(reply),
+            estimated: true,
+        };
+        if (reported?.cacheHit)
+            usage.localCacheHit = true;
+        span.recordUsage(usage);
+        span.setAttributes({
+            'llm.response_chars': reply.length,
+            'llm.cache_hit': reported?.cacheHit ?? false,
+            'llm.cache_tier': reported?.cacheTier,
+        });
+        this._lastCall = {
+            usage,
+            ...(reported?.cacheHit !== undefined ? { cacheHit: reported.cacheHit } : {}),
+            ...(reported?.cacheTier !== undefined ? { cacheTier: reported.cacheTier } : {}),
+        };
+    }
+}
+//# sourceMappingURL=InstrumentedBridge.js.map

package/dist/telemetry/InstrumentedBridge.js.map

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

package/dist/telemetry/MetricsRegistry.d.ts

@@ -0,0 +1,88 @@
+/**
+ * telemetry/MetricsRegistry.ts — LLM-native metrics, aggregated from spans.
+ *
+ * The registry is itself a {@link SpanExporter}. That is the DRY move: every
+ * subsystem already emits spans for tracing, so metrics are a *projection* of the
+ * trace stream rather than a second instrumentation path that can drift out of
+ * agreement with it. Attach it to a tracer and tokens/sec, cost-per-request, TTFT
+ * and cache-hit rate fall out of the traffic that is already being traced.
+ *
+ * Metrics that matter for an LLM system, and why the usual web ones do not:
+ *   • tokens/sec        — throughput the user actually feels, not requests/sec.
+ *   • cost per request  — the only unit that ties spend to a product decision.
+ *   • TTFT              — perceived latency for streamed answers; p95 latency
+ *                         hides it entirely.
+ *   • cache-hit rate    — the lever that moves cost, split local vs provider.
+ *   • unpriced calls    — honesty: a model missing from the rate card is counted,
+ *                         never billed at a silent zero.
+ */
+import type { SpanData, SpanExporter, SpanKind } from './types.js';
+export interface LlmMetricSnapshot {
+    /** Model id, or `'*'` for the all-models roll-up. */
+    model: string;
+    calls: number;
+    errors: number;
+    errorRate: number;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    /** Sum of priced calls, USD. Calls on unpriced models contribute 0 here. */
+    costUsd: number;
+    avgCostPerRequestUsd: number;
+    /** Calls whose model was absent from the price book — excluded from `costUsd`. */
+    unpricedCalls: number;
+    /** Calls whose token counts were estimated rather than provider-reported. */
+    estimatedCalls: number;
+    totalDurationMs: number;
+    avgLatencyMs: number;
+    p50LatencyMs: number;
+    p95LatencyMs: number;
+    /** Output tokens per second of wall-clock spent generating them. */
+    tokensPerSecond: number;
+    /** Mean time-to-first-token over streamed calls; 0 when none streamed. */
+    avgTimeToFirstTokenMs: number;
+    streamedCalls: number;
+    /** Share of calls served without reaching a provider (exact/semantic cache). */
+    localCacheHitRate: number;
+    /** Share of input tokens served from the provider's prompt cache. */
+    providerCacheHitRate: number;
+}
+export interface KindMetricSnapshot {
+    kind: SpanKind;
+    count: number;
+    errors: number;
+    totalDurationMs: number;
+    avgLatencyMs: number;
+    p95LatencyMs: number;
+}
+export interface MetricsRegistryOptions {
+    /**
+     * Max latency samples retained per series for percentiles. Default 2048 —
+     * bounded so a long-lived process cannot grow the registry without limit.
+     */
+    maxSamples?: number;
+}
+export declare class MetricsRegistry implements SpanExporter {
+    private readonly _maxSamples;
+    private readonly _byModel;
+    private readonly _byKind;
+    constructor(opts?: MetricsRegistryOptions);
+    /** {@link SpanExporter} — attach this registry directly to a {@link Tracer}. */
+    export(spans: readonly SpanData[]): void;
+    /** Folds one finished span into the aggregates. */
+    record(span: SpanData): void;
+    /** Snapshot for one model, or the `'*'` roll-up when omitted. */
+    llm(model?: string): LlmMetricSnapshot;
+    /** Snapshots for every model seen, excluding the `'*'` roll-up. */
+    models(): LlmMetricSnapshot[];
+    /** Latency/error snapshots per span kind — retrieval, ingest, graph, tool. */
+    kinds(): KindMetricSnapshot[];
+    reset(): void;
+    private _model;
+    private _kind;
+}
+/** Nearest-rank percentile over an unsorted sample array. */
+export declare function percentile(samples: readonly number[], q: number): number;
+//# sourceMappingURL=MetricsRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MetricsRegistry.d.ts","sourceRoot":"","sources":["../../src/telemetry/MetricsRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAC9B,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IAEpB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC;IAEvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IAErB,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IAEtB,gFAAgF;IAChF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACnC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AA0BD,qBAAa,eAAgB,YAAW,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;gBAEpD,IAAI,GAAE,sBAA2B;IAI7C,gFAAgF;IAChF,MAAM,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI;IAIxC,mDAAmD;IACnD,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAuC5B,iEAAiE;IACjE,GAAG,CAAC,KAAK,SAAM,GAAG,iBAAiB;IAInC,mEAAmE;IACnE,MAAM,IAAI,iBAAiB,EAAE;IAO7B,8EAA8E;IAC9E,KAAK,IAAI,kBAAkB,EAAE;IAa7B,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,KAAK;CAQhB;AAoDD,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMxE"}

package/dist/telemetry/MetricsRegistry.js

@@ -0,0 +1,167 @@
+/**
+ * telemetry/MetricsRegistry.ts — LLM-native metrics, aggregated from spans.
+ *
+ * The registry is itself a {@link SpanExporter}. That is the DRY move: every
+ * subsystem already emits spans for tracing, so metrics are a *projection* of the
+ * trace stream rather than a second instrumentation path that can drift out of
+ * agreement with it. Attach it to a tracer and tokens/sec, cost-per-request, TTFT
+ * and cache-hit rate fall out of the traffic that is already being traced.
+ *
+ * Metrics that matter for an LLM system, and why the usual web ones do not:
+ *   • tokens/sec        — throughput the user actually feels, not requests/sec.
+ *   • cost per request  — the only unit that ties spend to a product decision.
+ *   • TTFT              — perceived latency for streamed answers; p95 latency
+ *                         hides it entirely.
+ *   • cache-hit rate    — the lever that moves cost, split local vs provider.
+ *   • unpriced calls    — honesty: a model missing from the rate card is counted,
+ *                         never billed at a silent zero.
+ */
+export class MetricsRegistry {
+    _maxSamples;
+    _byModel = new Map();
+    _byKind = new Map();
+    constructor(opts = {}) {
+        this._maxSamples = Math.max(1, opts.maxSamples ?? 2048);
+    }
+    /** {@link SpanExporter} — attach this registry directly to a {@link Tracer}. */
+    export(spans) {
+        for (const span of spans)
+            this.record(span);
+    }
+    /** Folds one finished span into the aggregates. */
+    record(span) {
+        const duration = span.durationMs ?? 0;
+        const failed = span.status === 'error';
+        const kindAcc = this._kind(span.kind);
+        kindAcc.count += 1;
+        if (failed)
+            kindAcc.errors += 1;
+        kindAcc.totalDurationMs += duration;
+        push(kindAcc.latencies, duration, this._maxSamples);
+        if (span.kind !== 'llm' && span.kind !== 'embedding')
+            return;
+        const model = span.usage?.model ?? String(span.attributes['llm.model'] ?? 'unknown');
+        for (const acc of [this._model(model), this._model('*')]) {
+            acc.calls += 1;
+            if (failed)
+                acc.errors += 1;
+            acc.totalDurationMs += duration;
+            push(acc.latencies, duration, this._maxSamples);
+            if (span.timeToFirstTokenMs !== undefined) {
+                acc.streamedCalls += 1;
+                acc.ttftTotalMs += span.timeToFirstTokenMs;
+            }
+            const usage = span.usage;
+            if (!usage)
+                continue;
+            acc.inputTokens += usage.inputTokens;
+            acc.outputTokens += usage.outputTokens;
+            acc.cachedInputTokens += usage.cachedInputTokens ?? 0;
+            acc.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
+            if (usage.estimated)
+                acc.estimatedCalls += 1;
+            if (usage.localCacheHit)
+                acc.localCacheHits += 1;
+            if (span.costUsd === undefined)
+                acc.unpricedCalls += 1;
+            else
+                acc.costUsd += span.costUsd;
+        }
+    }
+    /** Snapshot for one model, or the `'*'` roll-up when omitted. */
+    llm(model = '*') {
+        return summarize(model, this._byModel.get(model) ?? emptyLlm());
+    }
+    /** Snapshots for every model seen, excluding the `'*'` roll-up. */
+    models() {
+        return [...this._byModel.entries()]
+            .filter(([model]) => model !== '*')
+            .map(([model, acc]) => summarize(model, acc))
+            .sort((a, b) => b.costUsd - a.costUsd || b.calls - a.calls);
+    }
+    /** Latency/error snapshots per span kind — retrieval, ingest, graph, tool. */
+    kinds() {
+        return [...this._byKind.entries()]
+            .map(([kind, acc]) => ({
+            kind,
+            count: acc.count,
+            errors: acc.errors,
+            totalDurationMs: acc.totalDurationMs,
+            avgLatencyMs: acc.count ? acc.totalDurationMs / acc.count : 0,
+            p95LatencyMs: percentile(acc.latencies, 0.95),
+        }))
+            .sort((a, b) => b.count - a.count);
+    }
+    reset() {
+        this._byModel.clear();
+        this._byKind.clear();
+    }
+    _model(model) {
+        let acc = this._byModel.get(model);
+        if (!acc) {
+            acc = emptyLlm();
+            this._byModel.set(model, acc);
+        }
+        return acc;
+    }
+    _kind(kind) {
+        let acc = this._byKind.get(kind);
+        if (!acc) {
+            acc = { count: 0, errors: 0, totalDurationMs: 0, latencies: [] };
+            this._byKind.set(kind, acc);
+        }
+        return acc;
+    }
+}
+function emptyLlm() {
+    return {
+        calls: 0, errors: 0,
+        inputTokens: 0, outputTokens: 0, cachedInputTokens: 0, cacheWriteTokens: 0,
+        costUsd: 0, unpricedCalls: 0, estimatedCalls: 0, localCacheHits: 0,
+        totalDurationMs: 0, ttftTotalMs: 0, streamedCalls: 0, latencies: [],
+    };
+}
+function summarize(model, acc) {
+    const totalTokens = acc.inputTokens + acc.outputTokens + acc.cachedInputTokens + acc.cacheWriteTokens;
+    const seconds = acc.totalDurationMs / 1000;
+    const billableInput = acc.inputTokens + acc.cachedInputTokens;
+    return {
+        model,
+        calls: acc.calls,
+        errors: acc.errors,
+        errorRate: acc.calls ? acc.errors / acc.calls : 0,
+        inputTokens: acc.inputTokens,
+        outputTokens: acc.outputTokens,
+        cachedInputTokens: acc.cachedInputTokens,
+        cacheWriteTokens: acc.cacheWriteTokens,
+        totalTokens,
+        costUsd: acc.costUsd,
+        avgCostPerRequestUsd: acc.calls ? acc.costUsd / acc.calls : 0,
+        unpricedCalls: acc.unpricedCalls,
+        estimatedCalls: acc.estimatedCalls,
+        totalDurationMs: acc.totalDurationMs,
+        avgLatencyMs: acc.calls ? acc.totalDurationMs / acc.calls : 0,
+        p50LatencyMs: percentile(acc.latencies, 0.5),
+        p95LatencyMs: percentile(acc.latencies, 0.95),
+        tokensPerSecond: seconds > 0 ? acc.outputTokens / seconds : 0,
+        avgTimeToFirstTokenMs: acc.streamedCalls ? acc.ttftTotalMs / acc.streamedCalls : 0,
+        streamedCalls: acc.streamedCalls,
+        localCacheHitRate: acc.calls ? acc.localCacheHits / acc.calls : 0,
+        providerCacheHitRate: billableInput ? acc.cachedInputTokens / billableInput : 0,
+    };
+}
+function push(samples, value, cap) {
+    samples.push(value);
+    if (samples.length > cap)
+        samples.shift();
+}
+/** Nearest-rank percentile over an unsorted sample array. */
+export function percentile(samples, q) {
+    if (samples.length === 0)
+        return 0;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const rank = Math.ceil(q * sorted.length);
+    const idx = Math.min(sorted.length - 1, Math.max(0, rank - 1));
+    return sorted[idx];
+}
+//# sourceMappingURL=MetricsRegistry.js.map

package/dist/telemetry/MetricsRegistry.js.map

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

package/dist/telemetry/Tracer.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 { type PriceBook } from './pricing.js';
+import { type TraceContext } from './traceparent.js';
+import type { AttributeValue, LlmUsage, SpanData, SpanExporter, SpanKind, SpanStatus } from './types.js';
+export interface SpanOptions {
+    kind?: SpanKind;
+    attributes?: Record<string, AttributeValue>;
+    /** Parent span. Omit for a root span (starts a new trace). */
+    parent?: Span;
+    /** Force a trace id (e.g. to continue a trace propagated from an HTTP header). */
+    traceId?: string;
+    /**
+     * A parent span in ANOTHER process, decoded from a `traceparent` header. Adopts
+     * its trace id, links to it as parent, and — crucially — obeys its sampling
+     * flag, so the four hops of a cloud run are one tree or none, never a tree with
+     * a hole where a hop re-rolled the dice. Ignored when `parent` is given (an
+     * in-process parent is always the more specific answer).
+     */
+    remoteParent?: TraceContext;
+}
+export interface TracerOptions {
+    /** Where finished spans go. Omit to buffer only (readable via `finished()`). */
+    exporter?: SpanExporter;
+    /** Rates used to price `llm` spans. Default {@link DEFAULT_PRICE_BOOK}. */
+    pricing?: PriceBook;
+    /** Clock, injected for determinism. Default `Date.now`. */
+    now?: () => number;
+    /** Id factory, injected for determinism. Default random hex. */
+    newId?: (bytes: number) => string;
+    /**
+     * Export once this many spans have finished. Default 64. Set 1 to export
+     * eagerly, when a downstream collector wants a live stream.
+     */
+    maxBatchSize?: number;
+    /**
+     * Fraction of ROOT traces recorded, 0..1. Default 1. Sampling is decided once
+     * per trace and inherited by children, so a sampled trace is never a tree with
+     * holes in it.
+     */
+    sampleRate?: number;
+    /** Sampling dice, injected for test. Default `Math.random`. */
+    random?: () => number;
+}
+/**
+ * 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 declare class Span {
+    private readonly _tracer;
+    private readonly _data;
+    private _closed;
+    private readonly _recorded;
+    /** @internal — construct via {@link Tracer.startSpan}. */
+    constructor(tracer: Tracer, data: SpanData, recorded: boolean);
+    get traceId(): string;
+    get spanId(): string;
+    get name(): string;
+    get closed(): boolean;
+    /** False when this trace was dropped by sampling — nothing will be exported. */
+    get recorded(): boolean;
+    /** A snapshot copy; mutating it does not affect the span. */
+    get data(): SpanData;
+    setAttribute(key: string, value: AttributeValue): this;
+    setAttributes(attrs: Record<string, AttributeValue | undefined>): this;
+    addEvent(name: string, attributes?: Record<string, AttributeValue>): this;
+    /** Records token usage and prices it with the tracer's price book. */
+    recordUsage(usage: LlmUsage): this;
+    /** Marks time-to-first-token; call when a stream yields its first chunk. */
+    recordFirstToken(): this;
+    /** Opens a child span inside this one (same trace, this span as parent). */
+    child(name: string, opts?: Omit<SpanOptions, 'parent' | 'traceId' | 'remoteParent'>): Span;
+    /**
+     * 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(): TraceContext;
+    /**
+     * 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(): string;
+    end(status?: SpanStatus): SpanData;
+    /** Ends the span as failed, recording the error message. */
+    fail(error: unknown): SpanData;
+    private _close;
+}
+export declare class Tracer {
+    readonly pricing: PriceBook;
+    private readonly _exporter?;
+    private readonly _now;
+    private readonly _newId;
+    private readonly _maxBatch;
+    private readonly _sampleRate;
+    private readonly _random;
+    private _buffer;
+    private readonly _finished;
+    /** traceId -> sampling decision, so children inherit the root's verdict. */
+    private readonly _sampled;
+    constructor(opts?: TracerOptions);
+    now(): number;
+    startSpan(name: string, opts?: SpanOptions): Span;
+    /**
+     * 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.
+     */
+    withSpan<T>(name: string, opts: SpanOptions, fn: (span: Span) => Promise<T> | T): Promise<T>;
+    /** All spans finished since construction (recorded ones only). */
+    finished(): readonly SpanData[];
+    /** Spans of one trace, in completion order. */
+    trace(traceId: string): readonly SpanData[];
+    /** Pushes any buffered spans to the exporter. */
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    /** @internal */
+    _finish(data: SpanData, recorded: boolean): void;
+    /**
+     * 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.
+     */
+    private _adoptSampling;
+    private _decideSampling;
+}
+//# sourceMappingURL=Tracer.d.ts.map

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

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