@inference/tracing 0.0.20 → 0.0.21

package/dist/agent-span.d.ts

@@ -1,5 +1,6 @@
 import { SpanKind, type Span, type Tracer } from "@opentelemetry/api";
 import { type SpanKindValue } from "./semconv.ts";
+import { type TokenUsage } from "./span-helpers.ts";
 /**
  * Options accepted by {@link agentSpan}. The minimum useful call is
  * `agentSpan(tracer, { agentId: "support-agent" }, fn)`.
@@ -56,10 +57,70 @@ export interface AgentSpanOptions {
      */
     sessionId?: string;
 }
+/**
+ * Options accepted by {@link manualSpan}.
+ *
+ * `manualSpan` is the general-purpose helper for framework gaps: custom
+ * routers, provider failover attempts, tool executors, evaluators,
+ * postprocessors, or high-level agent loops. {@link agentSpan} is the
+ * AGENT-flavored wrapper around it.
+ */
+export interface ManualSpanOptions {
+    /** Operation span name — appears as the row label in the trace viewer. */
+    spanName: string;
+    /**
+     * OpenInference span kind. Defaults to `CHAIN` — pass `TOOL`, `RETRIEVER`,
+     * `AGENT`, etc. when authoring the equivalent shape by hand.
+     */
+    spanKind?: SpanKindValue;
+    /** OTel-level span kind. Defaults to `INTERNAL`. */
+    otelKind?: SpanKind;
+    /**
+     * Provider identifier — e.g. `"openai"`, `"anthropic"`. Becomes
+     * `gen_ai.system` when set.
+     */
+    system?: string;
+    /** Stable agent identifier for AGENT-flavored manual spans. */
+    agentId?: string;
+    /** Optional display label. */
+    agentName?: string;
+    /** Optional role within a multi-agent workflow. */
+    agentRole?: string;
+    /**
+     * Stable id for one conversation. Becomes this span's `session.id`
+     * so downstream viewers can group manual spans by conversation.
+     */
+    sessionId?: string;
+    /** Convenience: set `input.value` from the callback. Strings pass through; objects are JSON-stringified. */
+    input?: unknown;
+    /** Convenience: set `output.value` before the callback runs (rare — usually set inside the callback). */
+    output?: unknown;
+    /** Convenience: set `llm.model_name`. */
+    model?: string;
+    /**
+     * Provider-shaped usage object. Accepted shapes match
+     * {@link normalizeUsage} (OpenAI Chat/Responses and Anthropic).
+     */
+    usage?: unknown;
+    /** Convenience: set `tool.name` on a TOOL-kind manual span. */
+    toolName?: string;
+    /** Convenience: set `tool_call.id` on a TOOL-kind manual span. */
+    toolCallId?: string;
+    /**
+     * Custom attributes applied with OTel-safe normalization — primitives and
+     * primitive arrays pass through; objects and mixed arrays are
+     * JSON-stringified.
+     */
+    attributes?: Record<string, unknown>;
+    /** Free-form metadata bag — JSON-stringified onto the `metadata` attribute. */
+    metadata?: Record<string, unknown>;
+    /** Free-form string tags — set on the `tags` attribute as a string array. */
+    tags?: readonly string[];
+}
 /**
  * The handle passed into the callback function. Provides type-safe
- * helpers for the OI attribute set the agent span should carry, plus
- * a `raw` escape hatch for callers that need the underlying OTel
+ * helpers for the OI attribute set the agent/manual span should carry,
+ * plus a `raw` escape hatch for callers that need the underlying OTel
  * `Span` (e.g. to add custom attributes outside the OI vocabulary).
  */
 export interface AgentSpanHandle {
@@ -67,18 +128,18 @@ export interface AgentSpanHandle {
      * Record the agent's input. Strings are stored as-is on
      * `input.value`; non-strings are JSON-stringified.
      */
-    setInput(value: string | object): void;
+    setInput(value: unknown): void;
     /**
      * Record the agent's final output. Same string-vs-JSON rule as
      * {@link AgentSpanHandle.setInput}.
      */
-    setOutput(value: string | object): void;
+    setOutput(value: unknown): void;
     /**
-     * Record token usage on the agent span. Any of `prompt`,
-     * `completion`, `total` may be omitted; only the provided fields
-     * are written. Use this when you have aggregated counts across
-     * multiple LLM calls inside the agent loop — per-call counts are
-     * captured separately by the LLM-level instrumentation.
+     * Record token usage on the span. Any of `prompt`, `completion`,
+     * `total` may be omitted; only the provided fields are written. Use this
+     * when you have aggregated counts across multiple LLM calls inside the
+     * agent loop — per-call counts are captured separately by the LLM-level
+     * instrumentation.
      */
     recordTokens(tokens: {
         prompt?: number;
@@ -86,12 +147,88 @@ export interface AgentSpanHandle {
         total?: number;
     }): void;
     /**
-     * Record the model name the agent used. Becomes `llm.model_name`.
+     * Record token usage from a provider-shaped usage object (OpenAI Chat /
+     * Responses, or Anthropic). Returns the normalized {@link TokenUsage}.
+     */
+    recordUsage(usage: unknown): TokenUsage;
+    /**
+     * Record the model name. Becomes `llm.model_name`.
      */
     setModel(model: string): void;
+    /**
+     * Record tool identity on a TOOL-kind span.
+     */
+    setTool(options: {
+        name: string;
+        callId?: string;
+    }): void;
+    /**
+     * Set one span attribute with OTel-safe value normalization. Mixed
+     * arrays and plain objects are JSON-stringified; primitives and
+     * primitive arrays pass through.
+     */
+    setAttribute(key: string, value: unknown): void;
+    /**
+     * Set many span attributes with the same normalization as
+     * {@link AgentSpanHandle.setAttribute}.
+     */
+    setAttributes(attributes: Record<string, unknown>): void;
     /** Escape hatch — the underlying OTel `Span`. */
     raw: Span;
 }
+/**
+ * Wrap custom work in an OpenInference-shaped manual span.
+ *
+ * Use this for framework gaps: custom routers, provider failover attempts,
+ * tool executors, evaluators, postprocessors, or high-level agent loops.
+ * Sets the OpenInference span kind, normalizes input/output values, accepts
+ * provider-shaped usage payloads, and keeps the body inside the active
+ * OTel context so SDK auto-instrumentation nests under it.
+ *
+ * Status semantics:
+ * - On callback success: span ends with `OK`.
+ * - On thrown error: the error is recorded as a span event, the
+ *   span ends with `ERROR`, and the original exception re-throws.
+ *
+ * @example A custom TOOL span around a function the SDK can't see
+ * ```ts
+ * await manualSpan(
+ *   tracing.tracer,
+ *   {
+ *     spanName: "submit_question",
+ *     spanKind: SpanKindValues.TOOL,
+ *     toolName: "submit_question",
+ *     toolCallId: callId,
+ *     input: { question },
+ *   },
+ *   async (span) => {
+ *     const result = await submitQuestion(question);
+ *     span.setOutput(result);
+ *   },
+ * );
+ * ```
+ *
+ * @example A CHAIN step that aggregates usage across several LLM calls
+ * ```ts
+ * await manualSpan(
+ *   tracing.tracer,
+ *   {
+ *     spanName: "question_generation/bloom",
+ *     spanKind: SpanKindValues.CHAIN,
+ *     system: "fireworks",
+ *     model: "accounts/fireworks/models/gpt-oss-120b",
+ *     usage: aggregatedUsage,
+ *     metadata: { deckId: "deck-123" },
+ *     tags: ["question-gen-agent", "template:bloom"],
+ *   },
+ *   async (span) => {
+ *     const questions = await generateQuestions();
+ *     span.setOutput({ questionCount: questions.length });
+ *   },
+ * );
+ * ```
+ */
+export declare function manualSpan<T>(tracer: Tracer, options: ManualSpanOptions, fn: (span: AgentSpanHandle) => Promise<T> | T): Promise<T>;
 /**
  * Wrap a chunk of agent work in an OpenInference-shaped AGENT span.
  *

package/dist/agent-span.js

@@ -1,6 +1,123 @@
 import { context, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { Attr, SpanKindValues } from "./semconv.js";
-import { contextWithAgentIdentity } from "./active-agent-context.js";
+import { contextWithAgentIdentity, getActiveAgentIdentity, } from "./active-agent-context.js";
+import { recordSpanUsage, setSpanAttribute, setSpanAttributes, stringifyValue, } from "./span-helpers.js";
+/**
+ * Wrap custom work in an OpenInference-shaped manual span.
+ *
+ * Use this for framework gaps: custom routers, provider failover attempts,
+ * tool executors, evaluators, postprocessors, or high-level agent loops.
+ * Sets the OpenInference span kind, normalizes input/output values, accepts
+ * provider-shaped usage payloads, and keeps the body inside the active
+ * OTel context so SDK auto-instrumentation nests under it.
+ *
+ * Status semantics:
+ * - On callback success: span ends with `OK`.
+ * - On thrown error: the error is recorded as a span event, the
+ *   span ends with `ERROR`, and the original exception re-throws.
+ *
+ * @example A custom TOOL span around a function the SDK can't see
+ * ```ts
+ * await manualSpan(
+ *   tracing.tracer,
+ *   {
+ *     spanName: "submit_question",
+ *     spanKind: SpanKindValues.TOOL,
+ *     toolName: "submit_question",
+ *     toolCallId: callId,
+ *     input: { question },
+ *   },
+ *   async (span) => {
+ *     const result = await submitQuestion(question);
+ *     span.setOutput(result);
+ *   },
+ * );
+ * ```
+ *
+ * @example A CHAIN step that aggregates usage across several LLM calls
+ * ```ts
+ * await manualSpan(
+ *   tracing.tracer,
+ *   {
+ *     spanName: "question_generation/bloom",
+ *     spanKind: SpanKindValues.CHAIN,
+ *     system: "fireworks",
+ *     model: "accounts/fireworks/models/gpt-oss-120b",
+ *     usage: aggregatedUsage,
+ *     metadata: { deckId: "deck-123" },
+ *     tags: ["question-gen-agent", "template:bloom"],
+ *   },
+ *   async (span) => {
+ *     const questions = await generateQuestions();
+ *     span.setOutput({ questionCount: questions.length });
+ *   },
+ * );
+ * ```
+ */
+export async function manualSpan(tracer, options, fn) {
+    const spanKind = options.spanKind ?? SpanKindValues.CHAIN;
+    const otelKind = options.otelKind ?? SpanKind.INTERNAL;
+    const spanName = options.spanName;
+    const activeIdentity = getActiveAgentIdentity();
+    const agentId = options.agentId ?? activeIdentity?.id;
+    const agentName = options.agentName ?? activeIdentity?.name;
+    const agentRole = options.agentRole ?? activeIdentity?.role;
+    const startAttributes = {
+        [Attr.SPAN_KIND]: spanKind,
+    };
+    if (agentId != null)
+        startAttributes[Attr.AGENT_ID] = agentId;
+    if (agentName != null)
+        startAttributes[Attr.AGENT_NAME] = agentName;
+    if (agentRole != null)
+        startAttributes[Attr.AGENT_ROLE] = agentRole;
+    if (options.system != null)
+        startAttributes[Attr.SYSTEM] = options.system;
+    if (options.toolName != null)
+        startAttributes[Attr.TOOL_NAME] = options.toolName;
+    if (options.toolCallId != null)
+        startAttributes[Attr.TOOL_CALL_ID] = options.toolCallId;
+    const sessionId = options.sessionId?.trim();
+    if (sessionId)
+        startAttributes[Attr.SESSION_ID] = sessionId;
+    if (options.attributes)
+        Object.assign(startAttributes, options.attributes);
+    if (options.metadata && Object.keys(options.metadata).length > 0) {
+        startAttributes.metadata = options.metadata;
+    }
+    if (options.tags && options.tags.length > 0) {
+        startAttributes.tags = Array.from(options.tags);
+    }
+    const span = tracer.startSpan(spanName, { kind: otelKind });
+    setSpanAttributes(span, startAttributes);
+    const handle = makeHandle(span);
+    if (options.input !== undefined)
+        handle.setInput(options.input);
+    if (options.output !== undefined)
+        handle.setOutput(options.output);
+    if (options.model != null)
+        handle.setModel(options.model);
+    if (options.usage !== undefined)
+        handle.recordUsage(options.usage);
+    const ctx = contextWithAgentIdentity(trace.setSpan(context.active(), span), {
+        id: agentId,
+        name: agentName,
+        role: agentRole,
+    });
+    try {
+        const result = await context.with(ctx, () => fn(handle));
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    }
+    catch (err) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+        throw err;
+    }
+    finally {
+        span.end();
+    }
+}
 /**
  * Wrap a chunk of agent work in an OpenInference-shaped AGENT span.
  *
@@ -61,35 +178,31 @@ import { contextWithAgentIdentity } from "./active-agent-context.js";
  * ```
  */
 export async function agentSpan(tracer, options, fn) {
-    const spanKind = options.spanKind ?? SpanKindValues.AGENT;
-    const otelKind = options.otelKind ?? SpanKind.INTERNAL;
     const agentId = options.agentId ?? options.id;
     const agentName = options.agentName ?? options.name;
     const spanName = resolveAgentSpanName(options, agentId, agentName);
-    const attributes = {
-        [Attr.SPAN_KIND]: spanKind,
-    };
-    if (agentId != null)
-        attributes[Attr.AGENT_ID] = agentId;
-    if (agentName != null)
-        attributes[Attr.AGENT_NAME] = agentName;
-    if (options.role != null)
-        attributes[Attr.AGENT_ROLE] = options.role;
-    if (options.system != null)
-        attributes[Attr.SYSTEM] = options.system;
-    const sessionId = options.sessionId?.trim();
-    if (sessionId)
-        attributes[Attr.SESSION_ID] = sessionId;
-    const span = tracer.startSpan(spanName, {
-        kind: otelKind,
-        attributes,
-    });
-    const handle = {
+    return manualSpan(tracer, {
+        spanName,
+        spanKind: options.spanKind ?? SpanKindValues.AGENT,
+        otelKind: options.otelKind ?? SpanKind.INTERNAL,
+        system: options.system,
+        agentId,
+        agentName,
+        agentRole: options.role,
+        sessionId: options.sessionId,
+    }, fn);
+}
+function makeHandle(span) {
+    return {
         setInput(value) {
-            span.setAttribute(Attr.INPUT_VALUE, typeof value === "string" ? value : JSON.stringify(value));
+            if (value === undefined)
+                return;
+            span.setAttribute(Attr.INPUT_VALUE, stringifyValue(value));
         },
         setOutput(value) {
-            span.setAttribute(Attr.OUTPUT_VALUE, typeof value === "string" ? value : JSON.stringify(value));
+            if (value === undefined)
+                return;
+            span.setAttribute(Attr.OUTPUT_VALUE, stringifyValue(value));
         },
         recordTokens({ prompt, completion, total }) {
             if (prompt != null)
@@ -99,34 +212,25 @@ export async function agentSpan(tracer, options, fn) {
             if (total != null)
                 span.setAttribute(Attr.TOKEN_COUNT_TOTAL, total);
         },
+        recordUsage(usage) {
+            return recordSpanUsage(span, usage);
+        },
         setModel(model) {
             span.setAttribute(Attr.MODEL_NAME, model);
         },
+        setTool({ name, callId }) {
+            span.setAttribute(Attr.TOOL_NAME, name);
+            if (callId != null)
+                span.setAttribute(Attr.TOOL_CALL_ID, callId);
+        },
+        setAttribute(key, value) {
+            setSpanAttribute(span, key, value);
+        },
+        setAttributes(attributes) {
+            setSpanAttributes(span, attributes);
+        },
         raw: span,
     };
-    // Run the callback inside the span's active context so any child
-    // spans created during it (LLM calls, tool calls, custom spans)
-    // auto-parent to the AGENT span. Without this, downstream
-    // instrumentation creates orphan spans that don't visually nest in
-    // the trace tree.
-    const ctx = contextWithAgentIdentity(trace.setSpan(context.active(), span), {
-        id: agentId,
-        name: agentName,
-        role: options.role,
-    });
-    try {
-        const result = await context.with(ctx, () => fn(handle));
-        span.setStatus({ code: SpanStatusCode.OK });
-        return result;
-    }
-    catch (err) {
-        span.recordException(err);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
-        throw err;
-    }
-    finally {
-        span.end();
-    }
 }
 function resolveAgentSpanName(options, agentId, agentName) {
     const explicitName = normalize(options.spanName);

package/dist/index.d.ts

@@ -29,7 +29,8 @@
  * - **First-party OpenInference instrumentation** for openai,
  *   anthropic, langchain, langgraph, langsmith, openai-agents, claude-agent-sdk,
  *   cursor-sdk, ai-sdk, livekit-agents, and pi-ai.
- * - **Helpers**: {@link agentSpan} for manual AGENT spans;
+ * - **Helpers**: {@link manualSpan} for custom CHAIN/TOOL/RETRIEVER spans,
+ *   {@link agentSpan} for manual AGENT spans;
  *   {@link wrapClaudeAgentSdkQuery} for the one SDK whose ESM
  *   namespace can't be patched in place.
  *
@@ -45,8 +46,10 @@
  */
 export { setup } from "./setup.ts";
 export type { CatalystTracing, InstrumentModules, SetupOptions, } from "./setup.ts";
-export { agentSpan } from "./agent-span.ts";
-export type { AgentSpanHandle, AgentSpanOptions } from "./agent-span.ts";
+export { agentSpan, manualSpan } from "./agent-span.ts";
+export type { AgentSpanHandle, AgentSpanOptions, ManualSpanOptions, } from "./agent-span.ts";
+export { normalizeUsage, recordSpanUsage, setSpanAttribute, setSpanAttributes, stringifyValue, } from "./span-helpers.ts";
+export type { TokenUsage } from "./span-helpers.ts";
 export { agentIdentityAttributes, applyActiveAgentIdentity, contextWithAgentIdentity, getActiveAgentIdentity, } from "./active-agent-context.ts";
 export type { AgentIdentity } from "./active-agent-context.ts";
 export { wrapClaudeAgentSdkQuery } from "./instrumentation/claude-agent-sdk.ts";

package/dist/index.js

@@ -29,7 +29,8 @@
  * - **First-party OpenInference instrumentation** for openai,
  *   anthropic, langchain, langgraph, langsmith, openai-agents, claude-agent-sdk,
  *   cursor-sdk, ai-sdk, livekit-agents, and pi-ai.
- * - **Helpers**: {@link agentSpan} for manual AGENT spans;
+ * - **Helpers**: {@link manualSpan} for custom CHAIN/TOOL/RETRIEVER spans,
+ *   {@link agentSpan} for manual AGENT spans;
  *   {@link wrapClaudeAgentSdkQuery} for the one SDK whose ESM
  *   namespace can't be patched in place.
  *
@@ -44,7 +45,8 @@
  * @packageDocumentation
  */
 export { setup } from "./setup.js";
-export { agentSpan } from "./agent-span.js";
+export { agentSpan, manualSpan } from "./agent-span.js";
+export { normalizeUsage, recordSpanUsage, setSpanAttribute, setSpanAttributes, stringifyValue, } from "./span-helpers.js";
 export { agentIdentityAttributes, applyActiveAgentIdentity, contextWithAgentIdentity, getActiveAgentIdentity, } from "./active-agent-context.js";
 export { wrapClaudeAgentSdkQuery } from "./instrumentation/claude-agent-sdk.js";
 export { instrumentElevenLabs } from "./entrypoints/elevenlabs.js";

package/dist/span-helpers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Public helpers for authoring rich manual spans.
+ *
+ * The SDK's auto-instrumentations normalize JSON-ish values, usage objects,
+ * and OTel-safe attributes internally. These helpers expose the same
+ * ergonomics to manual span authors so applications do not have to copy
+ * small coercion utilities into every integration.
+ */
+import type { Span } from "@opentelemetry/api";
+/**
+ * Normalized token usage extracted from provider-shaped usage payloads.
+ *
+ * Fields are optional; only the ones present in the source payload are set.
+ */
+export interface TokenUsage {
+    prompt?: number;
+    completion?: number;
+    total?: number;
+    promptCacheWrite?: number;
+    promptCacheRead?: number;
+    completionReasoning?: number;
+}
+/**
+ * Return the string representation used for OpenInference IO attributes.
+ *
+ * Strings pass through; `undefined` and `null` both serialize to `"null"`
+ * (matching Python's `json.dumps(None)` behavior so equivalent payloads
+ * produce equivalent attributes across SDKs). Everything else is
+ * `JSON.stringify`ed. If stringification throws (e.g. circular reference),
+ * falls back to `String()`.
+ */
+export declare function stringifyValue(value: unknown): string;
+/**
+ * Set one OTel attribute, JSON-encoding unsupported structured values.
+ *
+ * `null`/`undefined` are dropped. Primitives and primitive arrays are set as-is;
+ * mixed arrays and plain objects are JSON-stringified.
+ */
+export declare function setSpanAttribute(span: Span, key: string, value: unknown): void;
+/**
+ * Set several OTel attributes with the same normalization as one value.
+ *
+ * `null`/`undefined` values are skipped.
+ */
+export declare function setSpanAttributes(span: Span, attributes: Record<string, unknown>): void;
+/**
+ * Record token attributes from OpenAI- and Anthropic-shaped usage objects.
+ *
+ * Supported input keys include OpenAI Chat Completions/Responses style
+ * `prompt_tokens` / `completion_tokens` / `total_tokens`, newer
+ * `input_tokens` / `output_tokens` spellings, OpenAI detail objects such as
+ * `prompt_tokens_details.cached_tokens` and
+ * `completion_tokens_details.reasoning_tokens`, and Anthropic cache accounting
+ * keys such as `cache_creation_input_tokens` and `cache_read_input_tokens`.
+ *
+ * Returns the normalized {@link TokenUsage} so callers can read the numbers
+ * back without re-parsing.
+ */
+export declare function recordSpanUsage(span: Span, usage: unknown): TokenUsage;
+/**
+ * Normalize common provider usage payloads without touching a span.
+ *
+ * Same key support as {@link recordSpanUsage}. Returns an empty
+ * {@link TokenUsage} for non-object input.
+ */
+export declare function normalizeUsage(usage: unknown): TokenUsage;

package/dist/span-helpers.js

@@ -0,0 +1,191 @@
+import { Attr } from "./semconv.js";
+/**
+ * Return the string representation used for OpenInference IO attributes.
+ *
+ * Strings pass through; `undefined` and `null` both serialize to `"null"`
+ * (matching Python's `json.dumps(None)` behavior so equivalent payloads
+ * produce equivalent attributes across SDKs). Everything else is
+ * `JSON.stringify`ed. If stringification throws (e.g. circular reference),
+ * falls back to `String()`.
+ */
+export function stringifyValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === undefined)
+        return "null";
+    try {
+        return JSON.stringify(value) ?? "null";
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Set one OTel attribute, JSON-encoding unsupported structured values.
+ *
+ * `null`/`undefined` are dropped. Primitives and primitive arrays are set as-is;
+ * mixed arrays and plain objects are JSON-stringified.
+ */
+export function setSpanAttribute(span, key, value) {
+    const coerced = coerceAttributeValue(value);
+    if (coerced !== undefined) {
+        span.setAttribute(key, coerced);
+    }
+}
+/**
+ * Set several OTel attributes with the same normalization as one value.
+ *
+ * `null`/`undefined` values are skipped.
+ */
+export function setSpanAttributes(span, attributes) {
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value != null) {
+            setSpanAttribute(span, key, value);
+        }
+    }
+}
+/**
+ * Record token attributes from OpenAI- and Anthropic-shaped usage objects.
+ *
+ * Supported input keys include OpenAI Chat Completions/Responses style
+ * `prompt_tokens` / `completion_tokens` / `total_tokens`, newer
+ * `input_tokens` / `output_tokens` spellings, OpenAI detail objects such as
+ * `prompt_tokens_details.cached_tokens` and
+ * `completion_tokens_details.reasoning_tokens`, and Anthropic cache accounting
+ * keys such as `cache_creation_input_tokens` and `cache_read_input_tokens`.
+ *
+ * Returns the normalized {@link TokenUsage} so callers can read the numbers
+ * back without re-parsing.
+ */
+export function recordSpanUsage(span, usage) {
+    const normalized = normalizeUsage(usage);
+    if (normalized.prompt !== undefined) {
+        span.setAttribute(Attr.TOKEN_COUNT_PROMPT, normalized.prompt);
+    }
+    if (normalized.completion !== undefined) {
+        span.setAttribute(Attr.TOKEN_COUNT_COMPLETION, normalized.completion);
+    }
+    if (normalized.total !== undefined) {
+        span.setAttribute(Attr.TOKEN_COUNT_TOTAL, normalized.total);
+    }
+    if (normalized.promptCacheWrite !== undefined) {
+        span.setAttribute(Attr.TOKEN_COUNT_PROMPT_CACHE_WRITE, normalized.promptCacheWrite);
+    }
+    if (normalized.promptCacheRead !== undefined) {
+        span.setAttribute(Attr.TOKEN_COUNT_PROMPT_CACHE_READ, normalized.promptCacheRead);
+    }
+    if (normalized.completionReasoning !== undefined) {
+        span.setAttribute(Attr.TOKEN_COUNT_COMPLETION_REASONING, normalized.completionReasoning);
+    }
+    return normalized;
+}
+/**
+ * Normalize common provider usage payloads without touching a span.
+ *
+ * Same key support as {@link recordSpanUsage}. Returns an empty
+ * {@link TokenUsage} for non-object input.
+ */
+export function normalizeUsage(usage) {
+    const source = asRecord(usage);
+    if (source == null)
+        return {};
+    let prompt = firstInt(source, "prompt_tokens", "input_tokens");
+    const completion = firstInt(source, "completion_tokens", "output_tokens");
+    let total = firstInt(source, "total_tokens");
+    const promptDetails = firstRecord(source, "prompt_tokens_details", "input_tokens_details") ?? {};
+    const completionDetails = firstRecord(source, "completion_tokens_details", "output_tokens_details") ?? {};
+    const promptCacheWrite = firstInt(source, "cache_creation_input_tokens");
+    const promptCacheRead = firstInt(source, "cache_read_input_tokens") ??
+        firstInt(promptDetails, "cached_tokens");
+    const completionReasoning = firstInt(completionDetails, "reasoning_tokens");
+    if (hasAnthropicCacheUsage(source) && prompt !== undefined) {
+        prompt = prompt + (promptCacheWrite ?? 0) + (promptCacheRead ?? 0);
+    }
+    if (total === undefined && prompt !== undefined && completion !== undefined) {
+        total = prompt + completion;
+    }
+    const out = {};
+    if (prompt !== undefined)
+        out.prompt = prompt;
+    if (completion !== undefined)
+        out.completion = completion;
+    if (total !== undefined)
+        out.total = total;
+    if (promptCacheWrite !== undefined)
+        out.promptCacheWrite = promptCacheWrite;
+    if (promptCacheRead !== undefined)
+        out.promptCacheRead = promptCacheRead;
+    if (completionReasoning !== undefined)
+        out.completionReasoning = completionReasoning;
+    return out;
+}
+function coerceAttributeValue(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : stringifyValue(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return [];
+        if (value.every((item) => typeof item === "string"))
+            return value;
+        if (value.every((item) => typeof item === "boolean"))
+            return value;
+        if (value.every((item) => typeof item === "number" && Number.isFinite(item))) {
+            return value;
+        }
+        return stringifyValue(value);
+    }
+    if (typeof value === "object")
+        return stringifyValue(value);
+    return stringifyValue(value);
+}
+function asRecord(value) {
+    if (value == null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function firstRecord(source, ...keys) {
+    for (const key of keys) {
+        const candidate = asRecord(source[key]);
+        if (candidate != null)
+            return candidate;
+    }
+    return undefined;
+}
+function firstInt(source, ...keys) {
+    if (source == null)
+        return undefined;
+    for (const key of keys) {
+        const coerced = coerceInt(source[key]);
+        if (coerced !== undefined)
+            return coerced;
+    }
+    return undefined;
+}
+function coerceInt(value) {
+    if (value == null || typeof value === "boolean")
+        return undefined;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return undefined;
+        if (Number.isInteger(value))
+            return value;
+        return undefined;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed === "")
+            return undefined;
+        if (!/^-?\d+$/.test(trimmed))
+            return undefined;
+        const parsed = Number.parseInt(trimmed, 10);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function hasAnthropicCacheUsage(source) {
+    return (source.cache_creation_input_tokens != null || source.cache_read_input_tokens != null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inference/tracing",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
   "description": "First-party OpenInference-shaped tracing for TypeScript LLM and agent applications on Catalyst by Inference.net.",
   "homepage": "https://inference.net",