@vinhnt-sdk/trace 0.4.2 → 0.11.0

package/dist/otlp-exporter.d.ts

@@ -0,0 +1,141 @@
+/**
+ * OTLP/HTTP span exporter — maps custom Span → OTLP ExportTraceServiceRequest.
+ *
+ * Zero hard deps: pure JSON encoding over fetch (no @opentelemetry/* runtime dep).
+ * Endpoint/headers/service name resolved from config first, then standard OTEL env vars.
+ * Default path (no createOtlpSpanExporter call) remains unchanged — no-op / console telemetry.
+ *
+ * Env (read unless overridden in config):
+ *   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT  full URL for /v1/traces
+ *   OTEL_EXPORTER_OTLP_ENDPOINT         base URL → <base>/v1/traces
+ *   OTEL_EXPORTER_OTLP_HEADERS          k1=v1,k2=v2
+ *   OTEL_SERVICE_NAME                   resource attribute service.name
+ */
+import type { Span } from "./tracing.js";
+/** Minimal fetch shape (injectable for tests / custom runtimes). */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Config for createOtlpSpanExporter — all fields optional; env fills gaps. */
+export interface OtlpExporterConfig {
+    /** Full OTLP/HTTP traces endpoint (overrides env). */
+    endpoint?: string;
+    /** Extra HTTP headers merged over env headers. */
+    headers?: Record<string, string>;
+    /** Resource attributes (service.name etc.). */
+    resourceAttributes?: Record<string, unknown>;
+    /** Export timeout in ms (default 10000). */
+    timeoutMs?: number;
+    /** Instrumentation scope name (default @vinhnt-sdk/trace). */
+    scopeName?: string;
+    /** Instrumentation scope version. */
+    scopeVersion?: string;
+    /** Env source for resolution (default process.env). Injectable for tests. */
+    env?: Record<string, string | undefined>;
+    /** Custom fetch (default globalThis.fetch). */
+    fetch?: FetchLike;
+}
+/** Span exporter seam — default path stays no-op unless an exporter is wired. */
+export interface SpanExporter {
+    export(spans: readonly Span[]): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export type OtlpAnyValue = {
+    stringValue: string;
+} | {
+    boolValue: boolean;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    arrayValue: {
+        values: OtlpAnyValue[];
+    };
+} | {
+    kvlistValue: {
+        values: Array<{
+            key: string;
+            value: OtlpAnyValue;
+        }>;
+    };
+};
+export interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+export interface OtlpSpanEvent {
+    timeUnixNano: string;
+    name: string;
+    attributes?: OtlpKeyValue[];
+}
+export interface OtlpSpanStatus {
+    code: number;
+    message?: string;
+}
+export interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpKeyValue[];
+    events: OtlpSpanEvent[];
+    status: OtlpSpanStatus;
+}
+export interface OtlpResourceSpans {
+    resource: {
+        attributes: OtlpKeyValue[];
+    };
+    scopeSpans: Array<{
+        scope: {
+            name: string;
+            version?: string;
+        };
+        spans: OtlpSpan[];
+    }>;
+}
+export interface OtlpExportTraceRequest {
+    resourceSpans: OtlpResourceSpans[];
+}
+/** OTLP span kind codes (proto Span.Kind). */
+export declare const OTLP_SPAN_KIND: Record<string, number>;
+/** OTLP status codes (proto Status.StatusCode). */
+export declare const OTLP_STATUS_OK = 1;
+export declare const OTLP_STATUS_ERROR = 2;
+export declare const OTLP_STATUS_UNSET = 0;
+/**
+ * Resolve OTLP traces endpoint: config.endpoint > OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+ * > OTEL_EXPORTER_OTLP_ENDPOINT + "/v1/traces". Returns undefined if none set.
+ */
+export declare function resolveOtlpEndpoint(config?: Pick<OtlpExporterConfig, "endpoint" | "env">): string | undefined;
+/** Parse OTEL_EXPORTER_OTLP_HEADERS format `k1=v1,k2=v2`. */
+export declare function parseOtlpHeaders(raw: string | undefined): Record<string, string>;
+/** Deterministic FNV-1a → hex string of `length` chars (span/trace id wire form). */
+export declare function toOtlpId(id: string, length: number): string;
+/** Convert ms epoch → OTLP timeUnixNano string. */
+export declare function msToUnixNano(ms: number): string;
+/** Map a JS value to OTLP AnyValue. */
+export declare function toOtlpAnyValue(value: unknown): OtlpAnyValue;
+/** Convert attributes record → OTLP key-value list. */
+export declare function toOtlpAttributes(attributes: Record<string, unknown>): OtlpKeyValue[];
+/** Map a custom Span → OTLP JSON span. Exported for unit tests / custom pipelines. */
+export declare function mapSpanToOtlp(span: Span): OtlpSpan;
+/** Build full ExportTraceServiceRequest body. */
+export declare function buildOtlpExportRequest(spans: readonly Span[], config?: Pick<OtlpExporterConfig, "resourceAttributes" | "scopeName" | "scopeVersion">): OtlpExportTraceRequest;
+/**
+ * Create an OTLP/HTTP span exporter (JSON encoding).
+ *
+ * @throws ConfigurationError if no endpoint in config or env.
+ *
+ * @example
+ * ```typescript
+ * const exporter = createOtlpSpanExporter({
+ *   endpoint: "http://localhost:4318/v1/traces",
+ * });
+ * await exporter.export(recorder.getSpans());
+ * await exporter.shutdown();
+ * ```
+ */
+export declare function createOtlpSpanExporter(config?: OtlpExporterConfig): SpanExporter;
+//# sourceMappingURL=otlp-exporter.d.ts.map

package/dist/otlp-exporter.d.ts.map

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

package/dist/otlp-exporter.js

@@ -0,0 +1,238 @@
+/**
+ * OTLP/HTTP span exporter — maps custom Span → OTLP ExportTraceServiceRequest.
+ *
+ * Zero hard deps: pure JSON encoding over fetch (no @opentelemetry/* runtime dep).
+ * Endpoint/headers/service name resolved from config first, then standard OTEL env vars.
+ * Default path (no createOtlpSpanExporter call) remains unchanged — no-op / console telemetry.
+ *
+ * Env (read unless overridden in config):
+ *   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT  full URL for /v1/traces
+ *   OTEL_EXPORTER_OTLP_ENDPOINT         base URL → <base>/v1/traces
+ *   OTEL_EXPORTER_OTLP_HEADERS          k1=v1,k2=v2
+ *   OTEL_SERVICE_NAME                   resource attribute service.name
+ */
+import { ConfigurationError, NetworkError } from "@vinhnt-sdk/schema";
+/** OTLP span kind codes (proto Span.Kind). */
+export const OTLP_SPAN_KIND = {
+    internal: 1,
+    server: 2,
+    client: 3,
+    producer: 4,
+    consumer: 5,
+};
+/** OTLP status codes (proto Status.StatusCode). */
+export const OTLP_STATUS_OK = 1;
+export const OTLP_STATUS_ERROR = 2;
+export const OTLP_STATUS_UNSET = 0;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_SCOPE_NAME = "@vinhnt-sdk/trace";
+/**
+ * Resolve OTLP traces endpoint: config.endpoint > OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+ * > OTEL_EXPORTER_OTLP_ENDPOINT + "/v1/traces". Returns undefined if none set.
+ */
+export function resolveOtlpEndpoint(config) {
+    const env = config?.env ?? (typeof process !== "undefined" ? process.env : undefined);
+    if (config?.endpoint)
+        return config.endpoint;
+    const traces = env?.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+    if (traces)
+        return traces;
+    const base = env?.OTEL_EXPORTER_OTLP_ENDPOINT;
+    if (base) {
+        return base.endsWith("/v1/traces") ? base : `${base.replace(/\/+$/, "")}/v1/traces`;
+    }
+    return undefined;
+}
+/** Parse OTEL_EXPORTER_OTLP_HEADERS format `k1=v1,k2=v2`. */
+export function parseOtlpHeaders(raw) {
+    if (!raw)
+        return {};
+    const out = {};
+    for (const pair of raw.split(",")) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = pair.slice(0, eq).trim();
+        const value = pair.slice(eq + 1).trim();
+        if (key)
+            out[key] = value;
+    }
+    return out;
+}
+/** Deterministic FNV-1a → hex string of `length` chars (span/trace id wire form). */
+export function toOtlpId(id, length) {
+    let hex = "";
+    let seed = 0x811c9dc5;
+    let round = 0;
+    while (hex.length < length) {
+        let h = seed;
+        const input = `${id}#${round++}`;
+        for (let i = 0; i < input.length; i++) {
+            h ^= input.charCodeAt(i);
+            h = Math.imul(h, 0x01000193) >>> 0;
+        }
+        hex += (h >>> 0).toString(16).padStart(8, "0");
+        seed = (h ^ 0x9e3779b9) >>> 0;
+    }
+    return hex.slice(0, length);
+}
+/** Convert ms epoch → OTLP timeUnixNano string. */
+export function msToUnixNano(ms) {
+    return `${BigInt(Math.max(0, Math.trunc(ms))) * 1000000n}`;
+}
+/** Map a JS value to OTLP AnyValue. */
+export function toOtlpAnyValue(value) {
+    if (value === null || value === undefined)
+        return { stringValue: "" };
+    if (typeof value === "string")
+        return { stringValue: value };
+    if (typeof value === "boolean")
+        return { boolValue: value };
+    if (typeof value === "number") {
+        return Number.isInteger(value) && Number.isSafeInteger(value)
+            ? { intValue: String(value) }
+            : { doubleValue: value };
+    }
+    if (typeof value === "bigint")
+        return { intValue: value.toString() };
+    if (Array.isArray(value)) {
+        return { arrayValue: { values: value.map(toOtlpAnyValue) } };
+    }
+    if (typeof value === "object") {
+        const values = Object.entries(value).map(([key, v]) => ({ key, value: toOtlpAnyValue(v) }));
+        return { kvlistValue: { values } };
+    }
+    return { stringValue: String(value) };
+}
+/** Convert attributes record → OTLP key-value list. */
+export function toOtlpAttributes(attributes) {
+    return Object.entries(attributes).map(([key, value]) => ({
+        key,
+        value: toOtlpAnyValue(value),
+    }));
+}
+function mapStatus(status) {
+    if (status === "ok")
+        return { code: OTLP_STATUS_OK };
+    if (status === "" || status === "unset")
+        return { code: OTLP_STATUS_UNSET };
+    // error | cancelled | timeout | custom → ERROR with message
+    const result = { code: OTLP_STATUS_ERROR };
+    if (status !== "error")
+        result.message = status;
+    return result;
+}
+/** Map a custom Span → OTLP JSON span. Exported for unit tests / custom pipelines. */
+export function mapSpanToOtlp(span) {
+    const endMs = span.endTimeMs > 0 ? span.endTimeMs : span.startTimeMs;
+    const out = {
+        traceId: toOtlpId(span.traceId ?? span.id, 32),
+        spanId: toOtlpId(span.id, 16),
+        name: span.name,
+        kind: OTLP_SPAN_KIND[span.kind] ?? OTLP_SPAN_KIND.internal,
+        startTimeUnixNano: msToUnixNano(span.startTimeMs),
+        endTimeUnixNano: msToUnixNano(endMs),
+        attributes: toOtlpAttributes(span.attributes),
+        events: span.events.map((event) => ({
+            timeUnixNano: msToUnixNano(event.timestampMs),
+            name: event.name,
+            attributes: toOtlpAttributes(event.attributes),
+        })),
+        status: mapStatus(span.status),
+    };
+    if (span.parentId) {
+        out.parentSpanId = toOtlpId(span.parentId, 16);
+    }
+    return out;
+}
+/** Build full ExportTraceServiceRequest body. */
+export function buildOtlpExportRequest(spans, config) {
+    const resourceAttrs = {
+        ...(config?.resourceAttributes ?? {}),
+    };
+    if (resourceAttrs["service.name"] === undefined) {
+        resourceAttrs["service.name"] = "vinhnt-sdk";
+    }
+    const scope = {
+        name: config?.scopeName ?? DEFAULT_SCOPE_NAME,
+    };
+    if (config?.scopeVersion !== undefined) {
+        scope.version = config.scopeVersion;
+    }
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: toOtlpAttributes(resourceAttrs) },
+                scopeSpans: [
+                    {
+                        scope,
+                        spans: spans.map(mapSpanToOtlp),
+                    },
+                ],
+            },
+        ],
+    };
+}
+/**
+ * Create an OTLP/HTTP span exporter (JSON encoding).
+ *
+ * @throws ConfigurationError if no endpoint in config or env.
+ *
+ * @example
+ * ```typescript
+ * const exporter = createOtlpSpanExporter({
+ *   endpoint: "http://localhost:4318/v1/traces",
+ * });
+ * await exporter.export(recorder.getSpans());
+ * await exporter.shutdown();
+ * ```
+ */
+export function createOtlpSpanExporter(config = {}) {
+    const endpoint = resolveOtlpEndpoint(config);
+    if (!endpoint) {
+        throw new ConfigurationError("OTLP endpoint not configured: set config.endpoint, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, or OTEL_EXPORTER_OTLP_ENDPOINT");
+    }
+    const env = config.env ?? (typeof process !== "undefined" ? process.env : undefined);
+    const headers = {
+        "content-type": "application/json",
+        ...parseOtlpHeaders(env?.OTEL_EXPORTER_OTLP_HEADERS),
+        ...(config.headers ?? {}),
+    };
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchImpl = config.fetch ??
+        ((input, init) => {
+            if (typeof globalThis.fetch !== "function") {
+                throw new NetworkError("globalThis.fetch is not available; pass config.fetch");
+            }
+            return globalThis.fetch(input, init);
+        });
+    let closed = false;
+    return {
+        async export(spans) {
+            if (closed)
+                return;
+            if (spans.length === 0)
+                return;
+            const body = JSON.stringify(buildOtlpExportRequest(spans, config));
+            let response;
+            try {
+                response = await fetchImpl(endpoint, {
+                    method: "POST",
+                    headers,
+                    body,
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (cause) {
+                throw new NetworkError(`OTLP export failed: ${String(cause)}`, { cause });
+            }
+            if (!response.ok) {
+                throw new NetworkError(`OTLP export failed: HTTP ${response.status} ${response.statusText}`);
+            }
+        },
+        async shutdown() {
+            closed = true;
+        },
+    };
+}
+//# sourceMappingURL=otlp-exporter.js.map

package/dist/otlp-exporter.js.map

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

package/dist/telemetry.d.ts

@@ -75,4 +75,31 @@ export interface ContextPressure {
  * Calculate context pressure.
  */
 export declare function calculateContextPressure(currentTokens: number, maxTokens: number, compactThreshold?: number): ContextPressure;
+/**
+ * Telemetry provider interface — export telemetry data to external systems.
+ *
+ * Inspired by Vercel AI SDK's telemetry pattern.
+ */
+export interface TelemetryProvider {
+    exportTrace(trace: {
+        traceId: string;
+        spans: Array<{
+            spanId: string;
+            name: string;
+            startTime: number;
+            endTime?: number;
+            attributes?: Record<string, unknown>;
+        }>;
+    }): Promise<void> | void;
+    exportMetric(metric: {
+        name: string;
+        value: number;
+        unit: string;
+        attributes?: Record<string, unknown>;
+    }): Promise<void> | void;
+}
+/**
+ * Default telemetry provider — logs to console.
+ */
+export declare const ConsoleTelemetryProvider: TelemetryProvider;
 //# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAO9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,8BAAwB,CAAC;AAEnD;;GAEG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,YAA8B,GACtC,MAAM,CAIR;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;gBAEhD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAIvD,iCAAiC;IACjC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU;IAe/E,sBAAsB;IACtB,QAAQ,IAAI,UAAU;IAUtB,0BAA0B;IAC1B,iBAAiB,IAAI,MAAM;IAI3B,8BAA8B;IAC9B,aAAa,IAAI,SAAS,UAAU,EAAE;IAItC,sBAAsB;IACtB,KAAK,IAAI,IAAI;CAKd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,gBAAgB,SAAM,GACrB,eAAe,CAQjB"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAO9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,8BAAwB,CAAC;AAEnD;;GAEG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,YAA8B,GACtC,MAAM,CAIR;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;gBAEhD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAIvD,iCAAiC;IACjC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU;IAe/E,sBAAsB;IACtB,QAAQ,IAAI,UAAU;IAUtB,0BAA0B;IAC1B,iBAAiB,IAAI,MAAM;IAI3B,8BAA8B;IAC9B,aAAa,IAAI,SAAS,UAAU,EAAE;IAItC,sBAAsB;IACtB,KAAK,IAAI,IAAI;CAKd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,gBAAgB,SAAM,GACrB,eAAe,CAQjB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,KAAK,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,KAAK,CAAC;YACX,MAAM,EAAE,MAAM,CAAC;YACf,IAAI,EAAE,MAAM,CAAC;YACb,SAAS,EAAE,MAAM,CAAC;YAClB,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACtC,CAAC,CAAC;KACJ,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACzB,YAAY,CAAC,MAAM,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAWtC,CAAC"}

package/dist/telemetry.js

@@ -98,4 +98,19 @@ export function calculateContextPressure(currentTokens, maxTokens, compactThresh
         shouldCompact: pressure >= compactThreshold,
     };
 }
+/**
+ * Default telemetry provider — logs to console.
+ */
+export const ConsoleTelemetryProvider = {
+    exportTrace(trace) {
+        if (typeof console !== "undefined") {
+            console.log("[trace]", trace);
+        }
+    },
+    exportMetric(metric) {
+        if (typeof console !== "undefined") {
+            console.log("[metric]", metric);
+        }
+    },
+};
 //# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/dist/timeline.d.ts

@@ -7,9 +7,31 @@
  * The timeline is a linear sequence of events that can be replayed
  * to reconstruct the full conversation history.
  */
-/** Timeline event types — maps to KnownRunEvent from schema */
-export type TimelineEventType = "run.started" | "run.completed" | "run.failed" | "step.started" | "step.completed" | "step.failed" | "turn.started" | "turn.ended" | "tool.invoked" | "tool.completed" | "tool.failed" | "tool.cancelled" | "approval.asked" | "approval.decided" | "llm.retry" | "llm.retry_started" | "assistant.chunk" | "token.compressed" | "context.compressed" | "permission.asked" | "permission.decided" | (string & {});
-export declare const KNOWN_TIMELINE_EVENT_TYPES: readonly TimelineEventType[];
+import type { KnownRunEvent } from "@vinhnt-sdk/schema";
+/**
+ * Timeline event types — DERIVED from `KnownRunEvent["type"]` (the canonical
+ * run-event vocabulary). There is intentionally no `(string & {})` escape
+ * hatch: a name that is not emitted by the SDK cannot enter the timeline, so
+ * phantom names (`turn.ended`, `permission.asked`, `assistant.chunk`, …) are
+ * rejected at compile time.
+ */
+export type TimelineEventType = KnownRunEvent["type"];
+/**
+ * Every timeline event type the SDK emits, in emission order.
+ *
+ * Checked both ways at compile time:
+ * - `satisfies` → an unknown name fails typecheck (no phantoms);
+ * - {@link TimelineCoversAllRunEvents} → a missing name fails typecheck
+ *   (adding a `KnownRunEvent` without updating this list is a build error).
+ */
+export declare const KNOWN_TIMELINE_EVENT_TYPES: readonly ["run.started", "step.started", "token.streamed", "thinking.started", "thinking.content", "thinking.completed", "context.compressed", "token.counted", "tool.invoked", "tool.completed", "tool.failed", "tool.cancelled", "tool.self_correcting", "step.completed", "step.failed", "run.completed", "permission.requested", "permission.replied", "step.type_changed", "model.cost", "turn.started", "turn.end", "agent.handoff", "llm.retry", "llm.retry_started", "llm.failover", "approval.asked", "approval.decided", "request.header", "request.context", "llm.request", "llm.response"];
+/** Compile-time helper: constrains `T` to `never` (errors on anything else). */
+type AssertNever<T extends never> = T;
+/**
+ * Compile-time drift check: fails to typecheck when a `KnownRunEvent` type
+ * is missing from {@link KNOWN_TIMELINE_EVENT_TYPES}.
+ */
+export type TimelineCoversAllRunEvents = AssertNever<Exclude<KnownRunEvent["type"], (typeof KNOWN_TIMELINE_EVENT_TYPES)[number]>>;
 /** A single timeline event */
 export interface TimelineEvent {
     /** Event type */
@@ -60,4 +82,5 @@ export interface TranscriptEntry {
     output?: unknown;
     timestampMs: number;
 }
+export {};
 //# sourceMappingURL=timeline.d.ts.map

package/dist/timeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,eAAe,GACf,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,WAAW,GACX,mBAAmB,GACnB,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GACpB,kBAAkB,GAClB,oBAAoB,GACpB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAClB,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EAsBlE,CAAC;AAEF,8BAA8B;AAC9B,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,GAAG,CAAK;IAEhB,sBAAsB;IACtB,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAW7E,qBAAqB;IACrB,SAAS,IAAI,SAAS,aAAa,EAAE;IAIrC,kCAAkC;IAClC,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,aAAa,EAAE;IAIlE,iCAAiC;IACjC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE;IAI1E,sBAAsB;IACtB,KAAK,IAAI,MAAM;IAIf,mCAAmC;IACnC,aAAa,IAAI,MAAM;IAKvB,sCAAsC;IAChC,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7E,4BAA4B;IAC5B,MAAM,IAAI,aAAa,EAAE;IAIzB,8BAA8B;IAC9B,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI;CAOtC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,eAAe,EAAE,CAuCnF;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,wkBAiCc,CAAC;AAEtD,gFAAgF;AAChF,KAAK,WAAW,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,WAAW,CAClD,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC,CAC5E,CAAC;AAEF,8BAA8B;AAC9B,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,GAAG,CAAK;IAEhB,sBAAsB;IACtB,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAW7E,qBAAqB;IACrB,SAAS,IAAI,SAAS,aAAa,EAAE;IAIrC,kCAAkC;IAClC,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,aAAa,EAAE;IAIlE,iCAAiC;IACjC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE;IAI1E,sBAAsB;IACtB,KAAK,IAAI,MAAM;IAIf,mCAAmC;IACnC,aAAa,IAAI,MAAM;IAKvB,sCAAsC;IAChC,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7E,4BAA4B;IAC5B,MAAM,IAAI,aAAa,EAAE;IAIzB,8BAA8B;IAC9B,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI;CAOtC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,eAAe,EAAE,CAuCnF;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/timeline.js

@@ -7,28 +7,47 @@
  * The timeline is a linear sequence of events that can be replayed
  * to reconstruct the full conversation history.
  */
+/**
+ * Every timeline event type the SDK emits, in emission order.
+ *
+ * Checked both ways at compile time:
+ * - `satisfies` → an unknown name fails typecheck (no phantoms);
+ * - {@link TimelineCoversAllRunEvents} → a missing name fails typecheck
+ *   (adding a `KnownRunEvent` without updating this list is a build error).
+ */
 export const KNOWN_TIMELINE_EVENT_TYPES = [
     "run.started",
-    "run.completed",
-    "run.failed",
     "step.started",
-    "step.completed",
-    "step.failed",
-    "turn.started",
-    "turn.ended",
+    "token.streamed",
+    "thinking.started",
+    "thinking.content",
+    "thinking.completed",
+    "context.compressed",
+    "token.counted",
     "tool.invoked",
     "tool.completed",
     "tool.failed",
     "tool.cancelled",
-    "approval.asked",
-    "approval.decided",
+    "tool.self_correcting",
+    "step.completed",
+    "step.failed",
+    "run.completed",
+    "permission.requested",
+    "permission.replied",
+    "step.type_changed",
+    "model.cost",
+    "turn.started",
+    "turn.end",
+    "agent.handoff",
     "llm.retry",
     "llm.retry_started",
-    "assistant.chunk",
-    "token.compressed",
-    "context.compressed",
-    "permission.asked",
-    "permission.decided",
+    "llm.failover",
+    "approval.asked",
+    "approval.decided",
+    "request.header",
+    "request.context",
+    "llm.request",
+    "llm.response",
 ];
 /**
  * Timeline — ordered sequence of events for a session.
@@ -103,7 +122,7 @@ export function buildTranscript(events) {
                     timestampMs: event.timestampMs,
                 });
                 break;
-            case "assistant.chunk":
+            case "token.streamed":
                 entries.push({
                     type: "assistant",
                     content: event.data.content,

package/dist/timeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0BH,MAAM,CAAC,MAAM,0BAA0B,GAAiC;IACtE,aAAa;IACb,eAAe;IACf,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,aAAa;IACb,cAAc;IACd,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,kBAAkB;IAClB,WAAW;IACX,mBAAmB;IACnB,iBAAiB;IACjB,kBAAkB;IAClB,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;CACrB,CAAC;AAcF;;GAEG;AACH,MAAM,OAAO,QAAQ;IACF,MAAM,GAAoB,EAAE,CAAC;IACtC,GAAG,GAAG,CAAC,CAAC;IAEhB,sBAAsB;IACtB,MAAM,CAAC,IAAuB,EAAE,IAA6B;QAC3D,MAAM,KAAK,GAAkB;YAC3B,IAAI;YACJ,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;YACvB,IAAI;YACJ,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;SAChB,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,qBAAqB;IACrB,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,kCAAkC;IAClC,eAAe,CAAC,IAAuB;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACpD,CAAC;IAED,iCAAiC;IACjC,gBAAgB,CAAC,OAAe,EAAE,KAAa;QAC7C,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,OAAO,IAAI,CAAC,CAAC,WAAW,IAAI,KAAK,CAAC,CAAC;IACvF,CAAC;IAED,sBAAsB;IACtB,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,mCAAmC;IACnC,aAAa;QACX,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,WAAW,CAAC;IACxF,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,MAAM,CAAC,OAAgD;QAC3D,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,8BAA8B;IAC9B,MAAM,CAAC,MAAuB;QAC5B,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAgC;IAC9D,MAAM,OAAO,GAAsB,EAAE,CAAC;IAEtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,aAAa;gBAChB,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,MAAgB;oBACpC,WAAW,EAAE,KAAK,CAAC,WAAW;iBAC/B,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,iBAAiB;gBACpB,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,WAAW;oBACjB,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAiB;oBACrC,WAAW,EAAE,KAAK,CAAC,WAAW;iBAC/B,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,cAAc;gBACjB,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,WAAW;oBACjB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAkB;oBACvC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK;oBACvB,WAAW,EAAE,KAAK,CAAC,WAAW;iBAC/B,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,gBAAgB;gBACnB,OAAO,CAAC,IAAI,CAAC;oBACX,IAAI,EAAE,aAAa;oBACnB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAkB;oBACvC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;oBACzB,WAAW,EAAE,KAAK,CAAC,WAAW;iBAC/B,CAAC,CAAC;gBACH,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"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"}

package/dist/tracing.d.ts

@@ -53,8 +53,11 @@ export interface TraceContext {
 export declare function generateTraceId(): string;
 /**
  * Create a new span.
+ *
+ * `startTimeMs` back-dates the span — used when a span is recorded after the
+ * work finished (e.g. tool batches, failed calls) but must keep its real start.
  */
-export declare function createSpan(name: string, kind: SpanKind, parentId?: string, traceId?: string): Span;
+export declare function createSpan(name: string, kind: SpanKind, parentId?: string, traceId?: string, startTimeMs?: number): Span;
 /**
  * End a span with a status.
  */
@@ -70,8 +73,8 @@ export declare class SpanRecorder {
     private readonly spans;
     private readonly traceId;
     constructor(traceId?: string);
-    /** Start a new span */
-    startSpan(name: string, kind: SpanKind, parentId?: string): Span;
+    /** Start a new span — `startTimeMs` optionally back-dates the start. */
+    startSpan(name: string, kind: SpanKind, parentId?: string, startTimeMs?: number): Span;
     /** End a span */
     endSpan(span: Span, status?: SpanStatus): void;
     /** Get all recorded spans */