@namzu/sdk 2.0.0 → 3.0.0

package/dist/telemetry/__tests__/latency-instruments.test.js

@@ -0,0 +1,82 @@
+import { metrics } from '@opentelemetry/api';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { recordTimeToFirstToken, recordToolCall, resetRuntimeMetrics } from '../metrics.js';
+function fakeMeterProvider(written) {
+    const instrument = (name) => ({
+        add: (value, attributes = {}) => written.push({ instrument: name, value, attributes }),
+        record: (value, attributes = {}) => written.push({ instrument: name, value, attributes }),
+    });
+    const meter = {
+        createCounter: (name) => instrument(name),
+        createHistogram: (name) => instrument(name),
+        createUpDownCounter: (name) => instrument(name),
+        createObservableGauge: (name) => instrument(name),
+        createObservableCounter: (name) => instrument(name),
+        createObservableUpDownCounter: (name) => instrument(name),
+        addBatchObservableCallback: () => { },
+        removeBatchObservableCallback: () => { },
+    };
+    return { getMeter: () => meter };
+}
+let written;
+beforeEach(() => {
+    written = [];
+    resetRuntimeMetrics();
+    metrics.setGlobalMeterProvider(fakeMeterProvider(written));
+});
+afterEach(() => {
+    metrics.disable();
+    resetRuntimeMetrics();
+});
+const writesTo = (name) => written.filter((w) => w.instrument === name);
+const TTFT = 'gen_ai.client.time_to_first_token';
+const TOOL_DURATION = 'gen_ai.tool.call.duration';
+describe('time to first token', () => {
+    it('is recorded in seconds, like every other duration here', async () => {
+        recordTimeToFirstToken('m-1', 250);
+        // A histogram that silently used milliseconds would look right and
+        // aggregate wrong next to the request-duration one.
+        expect(writesTo(TTFT)[0]?.value).toBeCloseTo(0.25);
+    });
+    it('is keyed by model, so a slow model is attributable', () => {
+        recordTimeToFirstToken('fast', 100);
+        recordTimeToFirstToken('slow', 4_000);
+        expect(writesTo(TTFT).map((w) => w.attributes['gen_ai.request.model'])).toEqual([
+            'fast',
+            'slow',
+        ]);
+    });
+    it('is a separate instrument from the whole-request duration', () => {
+        // The point of the gap: one number cannot answer both questions.
+        recordTimeToFirstToken('m-1', 250);
+        expect(writesTo('gen_ai.client.operation.duration')).toHaveLength(0);
+        expect(writesTo(TTFT)).toHaveLength(1);
+    });
+});
+describe('tool duration', () => {
+    it('is recorded when the caller supplies it', () => {
+        recordToolCall('read', true, undefined, 1_500);
+        expect(writesTo(TOOL_DURATION)[0]?.value).toBeCloseTo(1.5);
+    });
+    it('shares the attributes of the count, so slow and failing join up', () => {
+        recordToolCall('fetch', false, 'ETIMEDOUT', 2_000);
+        expect(writesTo(TOOL_DURATION)[0]?.attributes).toMatchObject({
+            'gen_ai.tool.name': 'fetch',
+            'namzu.tool.success': false,
+            'namzu.tool.error': 'ETIMEDOUT',
+        });
+    });
+    it('still counts the call when no duration is supplied', () => {
+        recordToolCall('read', true);
+        expect(writesTo('gen_ai.tool.call.count')).toHaveLength(1);
+        // No duration write rather than a fabricated zero, which would drag
+        // every percentile down.
+        expect(writesTo(TOOL_DURATION)).toHaveLength(0);
+    });
+    it('counts and times in one call, not two that could diverge', () => {
+        recordToolCall('read', true, undefined, 900);
+        expect(writesTo('gen_ai.tool.call.count')).toHaveLength(1);
+        expect(writesTo(TOOL_DURATION)).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=latency-instruments.test.js.map

package/dist/telemetry/__tests__/latency-instruments.test.js.map

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

package/dist/telemetry/__tests__/metrics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metrics.test.d.ts.map

package/dist/telemetry/__tests__/metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.test.d.ts","sourceRoot":"","sources":["../../../src/telemetry/__tests__/metrics.test.ts"],"names":[],"mappings":""}

package/dist/telemetry/__tests__/metrics.test.js

@@ -0,0 +1,112 @@
+import { metrics } from '@opentelemetry/api';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { recordModelDuration, recordRunDuration, recordTokenUsage, recordToolCall, resetRuntimeMetrics, } from '../metrics.js';
+function fakeMeterProvider(written) {
+    const instrument = (name) => ({
+        add: (value, attributes = {}) => written.push({ instrument: name, value, attributes }),
+        record: (value, attributes = {}) => written.push({ instrument: name, value, attributes }),
+    });
+    const meter = {
+        createCounter: (name) => instrument(name),
+        createHistogram: (name) => instrument(name),
+        createUpDownCounter: (name) => instrument(name),
+        createObservableGauge: (name) => instrument(name),
+        createObservableCounter: (name) => instrument(name),
+        createObservableUpDownCounter: (name) => instrument(name),
+        addBatchObservableCallback: () => { },
+        removeBatchObservableCallback: () => { },
+    };
+    return { getMeter: () => meter };
+}
+let written;
+beforeEach(() => {
+    written = [];
+    resetRuntimeMetrics();
+    metrics.setGlobalMeterProvider(fakeMeterProvider(written));
+});
+afterEach(() => {
+    metrics.disable();
+    resetRuntimeMetrics();
+});
+const attributesOf = (name) => written.filter((w) => w.instrument === name);
+describe('token usage', () => {
+    it('records every kind under ONE metric, split by type', () => {
+        recordTokenUsage('m', {
+            promptTokens: 100,
+            completionTokens: 20,
+            cachedTokens: 500,
+            cacheWriteTokens: 40,
+        });
+        const writes = attributesOf('gen_ai.client.token.usage');
+        // It was two metrics under two names, the second invented — so a
+        // dashboard aggregating the conventional name saw input only.
+        expect(writes).toHaveLength(4);
+        expect(new Set(writes.map((w) => w.attributes['gen_ai.token.type']))).toEqual(new Set(['input', 'output', 'cache_read', 'cache_write']));
+        expect(writes.reduce((sum, w) => sum + w.value, 0)).toBe(660);
+    });
+    it('records cache traffic as its own types rather than folding it into input', () => {
+        recordTokenUsage('m', { promptTokens: 10, completionTokens: 0, cachedTokens: 900 });
+        const input = attributesOf('gen_ai.client.token.usage').find((w) => w.attributes['gen_ai.token.type'] === 'input');
+        // A read bills at a fraction of the input rate; summing them would
+        // make the total unable to explain a bill.
+        expect(input?.value).toBe(10);
+    });
+    it('writes nothing for a kind that was zero', () => {
+        recordTokenUsage('m', { promptTokens: 5, completionTokens: 0 });
+        expect(attributesOf('gen_ai.client.token.usage')).toHaveLength(1);
+    });
+    it('carries the model on every write', () => {
+        recordTokenUsage('some-model', { promptTokens: 1, completionTokens: 1 });
+        for (const write of attributesOf('gen_ai.client.token.usage')) {
+            expect(write.attributes['gen_ai.request.model']).toBe('some-model');
+        }
+    });
+});
+describe('tool calls', () => {
+    it('records the outcome and why it failed', () => {
+        recordToolCall('read', false, 'ENOENT');
+        const write = attributesOf('gen_ai.tool.call.count')[0];
+        expect(write?.attributes['gen_ai.tool.name']).toBe('read');
+        expect(write?.attributes['namzu.tool.success']).toBe(false);
+        // A flat success rate cannot separate a broken tool from one whose
+        // input the model keeps getting wrong.
+        expect(write?.attributes['namzu.tool.error']).toBe('ENOENT');
+    });
+    it('leaves the error attribute off a success', () => {
+        recordToolCall('read', true);
+        expect(attributesOf('gen_ai.tool.call.count')[0]?.attributes).not.toHaveProperty('namzu.tool.error');
+    });
+});
+describe('durations', () => {
+    it('records a run in seconds, keyed by how it settled', () => {
+        recordRunDuration('completed', 2500);
+        const write = attributesOf('namzu.run.duration')[0];
+        expect(write?.value).toBe(2.5);
+        expect(write?.attributes['namzu.run.status']).toBe('completed');
+    });
+    it('records a model call in seconds', () => {
+        recordModelDuration('m', 1500);
+        expect(attributesOf('gen_ai.client.operation.duration')[0]?.value).toBe(1.5);
+    });
+});
+describe('binding', () => {
+    it('records through a provider installed AFTER the first write', () => {
+        // The bug this replaces: an instrument bound before registration
+        // captured the no-op meter and threw every write away forever.
+        metrics.disable();
+        resetRuntimeMetrics();
+        recordToolCall('early', true);
+        const late = [];
+        metrics.setGlobalMeterProvider(fakeMeterProvider(late));
+        recordToolCall('late', true);
+        expect(late.map((w) => w.attributes['gen_ai.tool.name'])).toEqual(['late']);
+    });
+    it('reuses instruments while the meter is unchanged', () => {
+        recordToolCall('a', true);
+        recordToolCall('b', true);
+        // Rebuilding per call would allocate on a hot path; both writes must
+        // still land.
+        expect(attributesOf('gen_ai.tool.call.count')).toHaveLength(2);
+    });
+});
+//# sourceMappingURL=metrics.test.js.map

package/dist/telemetry/__tests__/metrics.test.js.map

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

package/dist/telemetry/__tests__/span-hierarchy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=span-hierarchy.test.d.ts.map

package/dist/telemetry/__tests__/span-hierarchy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-hierarchy.test.d.ts","sourceRoot":"","sources":["../../../src/telemetry/__tests__/span-hierarchy.test.ts"],"names":[],"mappings":""}

package/dist/telemetry/__tests__/span-hierarchy.test.js

@@ -0,0 +1,84 @@
+import { SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api';
+import { describe, expect, it } from 'vitest';
+import { parentContext } from '../attributes.js';
+/**
+ * OTel's GenAI conventions define a strict hierarchy —
+ * `invoke_agent` → `chat {model}` → `execute_tool` — and vendor dashboards
+ * (Langfuse, Braintrust, Phoenix, Datadog) rely on it. namzu emitted every
+ * span as a ROOT: a repo-wide grep for `context.with` / `trace.setSpan`
+ * returned zero hits, so a single 20-iteration run produced 21 disconnected
+ * traces with no waterfall and no LLM latency at all.
+ *
+ * The subtlety this file exists to pin: `startActiveSpan` does NOT hold
+ * context across `yield`. Every span-owning body in the run loop is an async
+ * generator, and a generator resumes on its CONSUMER's async context — so
+ * the naive conversion silently fails to parent anything, and the only fix
+ * that works is passing the parent explicitly.
+ */
+/** Minimal in-memory span capture; avoids pulling in the SDK exporter. */
+function fakeSpan(name) {
+    return {
+        spanContext: () => ({ traceId: name, spanId: name, traceFlags: 1 }),
+        setAttribute: () => fakeSpan(name),
+        setAttributes: () => fakeSpan(name),
+        addEvent: () => fakeSpan(name),
+        setStatus: () => fakeSpan(name),
+        updateName: () => fakeSpan(name),
+        end: () => { },
+        isRecording: () => true,
+        recordException: () => { },
+        addLink: () => fakeSpan(name),
+        addLinks: () => fakeSpan(name),
+    };
+}
+describe('parentContext', () => {
+    it('returns the ambient context when there is no parent', () => {
+        expect(parentContext(undefined)).toBe(otelContext.active());
+    });
+    it('puts the given span into the returned context', () => {
+        const parent = fakeSpan('run');
+        const ctx = parentContext(parent);
+        expect(trace.getSpan(ctx)).toBe(parent);
+    });
+    it('does not mutate the ambient context', () => {
+        const before = trace.getSpan(otelContext.active());
+        parentContext(fakeSpan('run'));
+        expect(trace.getSpan(otelContext.active())).toBe(before);
+    });
+    it('survives an await — which is exactly what the ambient context does not', async () => {
+        // This is the whole reason the helper exists. An explicit context is
+        // a value; the ambient one is per-async-scope and is gone by the time
+        // a generator resumes on its consumer's stack.
+        const parent = fakeSpan('run');
+        const ctx = parentContext(parent);
+        await Promise.resolve();
+        await new Promise((r) => setTimeout(r, 0));
+        expect(trace.getSpan(ctx)).toBe(parent);
+    });
+    it('demonstrates the failure mode it replaces', async () => {
+        // `context.with` establishes an ambient parent only for the
+        // synchronous body plus awaited continuations it owns. Reading it
+        // from a *separately scheduled* task sees nothing — which is the
+        // position every async generator in the run loop is in.
+        const parent = fakeSpan('run');
+        let observedInsideDetachedTask;
+        await otelContext.with(trace.setSpan(otelContext.active(), parent), async () => {
+            await new Promise((resolve) => {
+                setTimeout(() => {
+                    observedInsideDetachedTask = trace.getSpan(otelContext.active());
+                    resolve();
+                }, 0);
+            });
+        });
+        expect(observedInsideDetachedTask).toBeUndefined();
+        // …while the explicit context still carries the parent.
+        expect(trace.getSpan(parentContext(parent))).toBe(parent);
+    });
+});
+describe('span status constants are the ones we stamp', () => {
+    it('uses OK / ERROR rather than ad-hoc strings', () => {
+        expect(SpanStatusCode.OK).toBeDefined();
+        expect(SpanStatusCode.ERROR).toBeDefined();
+    });
+});
+//# sourceMappingURL=span-hierarchy.test.js.map

package/dist/telemetry/__tests__/span-hierarchy.test.js.map

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

package/dist/telemetry/attributes.d.ts

@@ -2,4 +2,48 @@ export { GENAI, NAMZU } from '../constants/telemetry/index.js';
 export declare function agentRunSpanName(agentName: string): string;
 export declare function agentIterationSpanName(iteration: number): string;
 export declare function toolSpanName(toolName: string): string;
+/**
+ * OTel GenAI semconv names the model-call span `chat {model}`.
+ *
+ * There was no span around the model call at all — `chatSpanName` existed
+ * in `@namzu/telemetry` with zero call sites — so a run's traces carried
+ * no LLM latency whatsoever, and the token attributes landed on the
+ * iteration span instead of the operation that produced them.
+ */
+export declare function chatSpanName(model: string): string;
+/**
+ * Build a context that parents a new span to `parent`.
+ *
+ * Async generators cannot use `startActiveSpan` for parenting: a generator
+ * body resumes on its CONSUMER's async context, so whatever was active when
+ * the parent span was created is gone by the time the child is made. Every
+ * span-owning body in the run loop is a generator, which is why a 20-turn
+ * run emitted 21 disconnected root spans. Passing the parent explicitly is
+ * the only thing that works here.
+ */
+export declare function parentContext(parent?: import('@opentelemetry/api').Span | SerializedSpanContext): import("@opentelemetry/api").Context;
+/**
+ * A span context flattened for storage.
+ *
+ * `parentContext` used to accept only a live in-memory span, so a parent
+ * that had to survive a process boundary could not be expressed at all — a
+ * run that crashed at iteration 12 and resumed produced two traces with
+ * different trace ids and no link between them, and the crash and its
+ * recovery could not be put on one timeline. Every span carries
+ * `namzu.run.id`, which is enough to FIND both traces by query and not
+ * enough to see one waterfall; and that much disappears for a replay fork,
+ * which mints a new run id.
+ *
+ * Flat strings rather than the OTel type so it survives `JSON.stringify`
+ * into a checkpoint unchanged.
+ */
+export interface SerializedSpanContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: number;
+    /** Whether the parent lives in a different process. Always true on read. */
+    readonly isRemote?: boolean;
+}
+/** Flatten a live span for storage, or `undefined` when there is nothing real to store. */
+export declare function serializeSpan(span?: import('@opentelemetry/api').Span): SerializedSpanContext | undefined;
 //# sourceMappingURL=attributes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/telemetry/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAA;AAE9D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/telemetry/attributes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAA;AAE9D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,oBAAoB,EAAE,IAAI,GAAG,qBAAqB,wCAY/F;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC3B;AAoCD,2FAA2F;AAC3F,wBAAgB,aAAa,CAC5B,IAAI,CAAC,EAAE,OAAO,oBAAoB,EAAE,IAAI,GACtC,qBAAqB,GAAG,SAAS,CAUnC"}

package/dist/telemetry/attributes.js

@@ -1,3 +1,4 @@
+import { context as otelContext, trace } from '@opentelemetry/api';
 export { GENAI, NAMZU } from '../constants/telemetry/index.js';
 export function agentRunSpanName(agentName) {
     return `namzu.agent.run ${agentName}`;
@@ -8,4 +9,83 @@ export function agentIterationSpanName(iteration) {
 export function toolSpanName(toolName) {
     return `namzu.tool.execute ${toolName}`;
 }
+/**
+ * OTel GenAI semconv names the model-call span `chat {model}`.
+ *
+ * There was no span around the model call at all — `chatSpanName` existed
+ * in `@namzu/telemetry` with zero call sites — so a run's traces carried
+ * no LLM latency whatsoever, and the token attributes landed on the
+ * iteration span instead of the operation that produced them.
+ */
+export function chatSpanName(model) {
+    return `chat ${model}`;
+}
+/**
+ * Build a context that parents a new span to `parent`.
+ *
+ * Async generators cannot use `startActiveSpan` for parenting: a generator
+ * body resumes on its CONSUMER's async context, so whatever was active when
+ * the parent span was created is gone by the time the child is made. Every
+ * span-owning body in the run loop is a generator, which is why a 20-turn
+ * run emitted 21 disconnected root spans. Passing the parent explicitly is
+ * the only thing that works here.
+ */
+export function parentContext(parent) {
+    const active = otelContext.active();
+    if (!parent)
+        return active;
+    // A live span goes in as itself. Round-tripping it through
+    // `wrapSpanContext` would replace a recording span with a non-recording
+    // stand-in — same ids, but the parent stops being the object callers
+    // hold, and anything reading it back gets a hollow one.
+    if (!isSerialized(parent))
+        return trace.setSpan(active, parent);
+    const context = toSpanContext(parent);
+    if (!context)
+        return active;
+    return trace.setSpan(active, trace.wrapSpanContext(context));
+}
+function isSerialized(value) {
+    return typeof value.traceId === 'string';
+}
+const HEX_TRACE_ID = /^[0-9a-f]{32}$/;
+const HEX_SPAN_ID = /^[0-9a-f]{16}$/;
+/**
+ * Rebuild an OTel span context, or return `undefined` for one that is not
+ * usable.
+ *
+ * Both ids are validated: an exporter given a malformed or all-zero id
+ * silently drops the span, so an unchecked value turns "the resume is
+ * linked to the crash" into "there is no resume trace at all" — a strictly
+ * worse outcome than the disconnected traces this replaces.
+ */
+function toSpanContext(serialized) {
+    const { traceId, spanId } = serialized;
+    if (!HEX_TRACE_ID.test(traceId) || !HEX_SPAN_ID.test(spanId))
+        return undefined;
+    if (/^0+$/.test(traceId) || /^0+$/.test(spanId))
+        return undefined;
+    return {
+        traceId,
+        spanId,
+        traceFlags: serialized.traceFlags,
+        // The parent was recorded in another process, whatever that process
+        // was; saying otherwise makes a sampler treat it as locally sampled.
+        isRemote: true,
+    };
+}
+/** Flatten a live span for storage, or `undefined` when there is nothing real to store. */
+export function serializeSpan(span) {
+    const context = span?.spanContext();
+    if (!context)
+        return undefined;
+    if (!HEX_TRACE_ID.test(context.traceId) || /^0+$/.test(context.traceId))
+        return undefined;
+    return {
+        traceId: context.traceId,
+        spanId: context.spanId,
+        traceFlags: context.traceFlags,
+        isRemote: false,
+    };
+}
 //# sourceMappingURL=attributes.js.map

package/dist/telemetry/attributes.js.map

@@ -1 +1 @@
-{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../src/telemetry/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAA;AAE9D,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IACjD,OAAO,mBAAmB,SAAS,EAAE,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACvD,OAAO,yBAAyB,SAAS,EAAE,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC5C,OAAO,sBAAsB,QAAQ,EAAE,CAAA;AACxC,CAAC"}
+{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../src/telemetry/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAA;AAE9D,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IACjD,OAAO,mBAAmB,SAAS,EAAE,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACvD,OAAO,yBAAyB,SAAS,EAAE,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC5C,OAAO,sBAAsB,QAAQ,EAAE,CAAA;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACzC,OAAO,QAAQ,KAAK,EAAE,CAAA;AACvB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,MAAkE;IAC/F,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,CAAA;IACnC,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,CAAA;IAC1B,2DAA2D;IAC3D,wEAAwE;IACxE,qEAAqE;IACrE,wDAAwD;IACxD,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE/D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,MAAM,CAAA;IAC3B,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAA;AAC7D,CAAC;AAyBD,SAAS,YAAY,CACpB,KAAgE;IAEhE,OAAO,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,CAAA;AACpE,CAAC;AAED,MAAM,YAAY,GAAG,gBAAgB,CAAA;AACrC,MAAM,WAAW,GAAG,gBAAgB,CAAA;AAEpC;;;;;;;;GAQG;AACH,SAAS,aAAa,CACrB,UAAiC;IAEjC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,CAAA;IACtC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAA;IAC9E,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAA;IACjE,OAAO;QACN,OAAO;QACP,MAAM;QACN,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,oEAAoE;QACpE,qEAAqE;QACrE,QAAQ,EAAE,IAAI;KACd,CAAA;AACF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAC5B,IAAwC;IAExC,MAAM,OAAO,GAAG,IAAI,EAAE,WAAW,EAAE,CAAA;IACnC,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IAC9B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAA;IACzF,OAAO;QACN,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ,EAAE,KAAK;KACf,CAAA;AACF,CAAC"}

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,41 @@
+/** Drop the cache. Tests that swap the global provider need this. */
+export declare function resetRuntimeMetrics(): void;
+export interface TokenUsageSample {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    /** Prompt tokens served from the provider's cache. */
+    readonly cachedTokens?: number;
+    /** Prompt tokens written into the provider's cache. */
+    readonly cacheWriteTokens?: number;
+}
+/**
+ * Record what a turn cost, split by token type.
+ *
+ * Cache reads and writes are recorded as their own types rather than
+ * folded into `input`. They bill differently — a read is a fraction of the
+ * input rate and a write is a premium on it — so a total that hides them
+ * cannot explain a bill, which is the main thing anyone asks a token
+ * metric.
+ */
+export declare function recordTokenUsage(model: string, usage: TokenUsageSample): void;
+/**
+ * Record a tool call.
+ *
+ * `errorType` carries WHY a call failed rather than only that it did. A
+ * flat success rate cannot separate a tool that is broken from one whose
+ * input the model keeps getting wrong, and those need different fixes.
+ */
+export declare function recordToolCall(toolName: string, success: boolean, errorType?: string, durationMs?: number): void;
+/**
+ * Record how long the first content delta took to arrive.
+ *
+ * Recorded at the first delta rather than at the end of the request,
+ * because the two are not the same measurement and only this one tracks
+ * what a person waiting actually experiences.
+ */
+export declare function recordTimeToFirstToken(model: string, durationMs: number): void;
+/** Record how long a whole run took, keyed by how it settled. */
+export declare function recordRunDuration(status: string, durationMs: number): void;
+/** Record how long one model request took. */
+export declare function recordModelDuration(model: string, durationMs: number, errorType?: string): void;
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AA0FA,qEAAqE;AACrE,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CA0B7E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI,CAYN;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAE9E;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAE1E;AAED,8CAA8C;AAC9C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAK/F"}