@gajae-code/agent-core 0.1.1

package/src/telemetry.ts

@@ -0,0 +1,2018 @@
+/**
+ * OpenTelemetry instrumentation for the agent loop.
+ *
+ * Implements the OpenTelemetry GenAI semantic conventions
+ * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `pi.gen_ai.*`
+ * extension attributes for run summaries, dashboard summaries, and cost hints
+ * that are useful to downstream observability UIs.
+ *
+ * Span hierarchy emitted by the loop:
+ *
+ *   invoke_agent {agent.name}         (one per runLoop, gen_ai.operation.name=invoke_agent)
+ *   ├── chat {model}                  (one per LLM call, gen_ai.operation.name=chat)
+ *   ├── execute_tool {tool.name}      (one per tool call, gen_ai.operation.name=execute_tool)
+ *   └── ...
+ *
+ * The `handoff` operation is emitted via the public {@link recordHandoff}
+ * helper for hosts that route work between named agents.
+ *
+ * Activation is opt-in: callers pass an {@link AgentTelemetryConfig} on
+ * `AgentLoopConfig.telemetry`. When unset, every helper short-circuits and
+ * the loop performs zero tracer lookups. When set but no OTEL SDK is
+ * registered, `@opentelemetry/api` returns a no-op tracer and all calls are
+ * cheap pass-throughs.
+ */
+
+import {
+	type Api,
+	type AssistantMessage,
+	type Context,
+	completeSimple,
+	type Message,
+	type Model,
+	type ServiceTier,
+	type SimpleStreamOptions,
+	type StopReason,
+	shouldSendServiceTier,
+	type ToolChoice,
+	type Usage,
+} from "@gajae-code/ai";
+import {
+	type Attributes,
+	type AttributeValue,
+	context,
+	type Span,
+	SpanKind,
+	SpanStatusCode,
+	type Tracer,
+	trace,
+} from "@opentelemetry/api";
+import { AgentRunCollector, type AgentRunCoverage, type AgentRunSummary, type ToolStatus } from "./run-collector";
+import type { AgentTool } from "./types";
+
+/** Default tracer name. Override via {@link AgentTelemetryConfig.tracerName}. */
+export const DEFAULT_TRACER_NAME = "@gajae-code/agent-core";
+
+/** Env var matching the OTEL semconv content-capture toggle. */
+const CONTENT_CAPTURE_ENV = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT";
+
+const MAX_TELEMETRY_ARRAY_ITEMS = 64;
+const MAX_TELEMETRY_MESSAGE_COUNT = 16;
+const MAX_TELEMETRY_OBJECT_DEPTH = 3;
+const MAX_TELEMETRY_OBJECT_KEYS = 12;
+const MAX_TELEMETRY_TEXT_CHARS = 240;
+
+/**
+ * GenAI semantic-convention attribute keys grouped by operation. Hoisted so
+ * call sites stay typo-proof and easy to grep.
+ */
+export const enum GenAIAttr {
+	// Common identifiers
+	ProviderName = "gen_ai.provider.name",
+	OperationName = "gen_ai.operation.name",
+	ConversationId = "gen_ai.conversation.id",
+	OutputType = "gen_ai.output.type",
+	// Agent identity
+	AgentId = "gen_ai.agent.id",
+	AgentName = "gen_ai.agent.name",
+	AgentDescription = "gen_ai.agent.description",
+	// Request shape
+	RequestModel = "gen_ai.request.model",
+	RequestMaxTokens = "gen_ai.request.max_tokens",
+	RequestTemperature = "gen_ai.request.temperature",
+	RequestTopP = "gen_ai.request.top_p",
+	RequestTopK = "gen_ai.request.top_k",
+	RequestFrequencyPenalty = "gen_ai.request.frequency_penalty",
+	RequestPresencePenalty = "gen_ai.request.presence_penalty",
+	RequestStopSequences = "gen_ai.request.stop_sequences",
+	RequestSeed = "gen_ai.request.seed",
+	RequestChoiceCount = "gen_ai.request.choice.count",
+	RequestStream = "gen_ai.request.stream",
+	// Response shape
+	ResponseModel = "gen_ai.response.model",
+	ResponseId = "gen_ai.response.id",
+	ResponseFinishReasons = "gen_ai.response.finish_reasons",
+	ResponseTimeToFirstChunk = "gen_ai.response.time_to_first_chunk",
+	// Usage
+	UsageInputTokens = "gen_ai.usage.input_tokens",
+	UsageOutputTokens = "gen_ai.usage.output_tokens",
+	UsageCacheReadInputTokens = "gen_ai.usage.cache_read.input_tokens",
+	UsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens",
+	UsageReasoningOutputTokens = "gen_ai.usage.reasoning.output_tokens",
+	// Tools
+	ToolCallId = "gen_ai.tool.call.id",
+	ToolName = "gen_ai.tool.name",
+	ToolDescription = "gen_ai.tool.description",
+	ToolType = "gen_ai.tool.type",
+	ToolCallArguments = "gen_ai.tool.call.arguments",
+	ToolCallResult = "gen_ai.tool.call.result",
+	ToolDefinitions = "gen_ai.tool.definitions",
+	// Content capture (opt-in)
+	InputMessages = "gen_ai.input.messages",
+	OutputMessages = "gen_ai.output.messages",
+	SystemInstructions = "gen_ai.system_instructions",
+	// Errors
+	ErrorType = "error.type",
+}
+
+/** OpenAI semantic-convention attribute keys. */
+export const enum OpenAIAttr {
+	RequestServiceTier = "openai.request.service_tier",
+	ResponseServiceTier = "openai.response.service_tier",
+}
+
+/** Project extension attributes. Kept out of the reserved `gen_ai.*` namespace. */
+export const enum PiGenAIAttr {
+	AgentStepNumber = "pi.gen_ai.agent.step.number",
+	AgentStepCount = "pi.gen_ai.agent.step.count",
+	RequestReasoningEffort = "pi.gen_ai.request.reasoning.effort",
+	RequestToolChoice = "pi.gen_ai.request.tool.choice",
+	RequestAvailableTools = "pi.gen_ai.request.available_tools",
+	RequestMessages = "pi.gen_ai.request.messages",
+	ResponseText = "pi.gen_ai.response.text",
+	ResponseToolCalls = "pi.gen_ai.response.tool_calls",
+	UsageTotalTokens = "pi.gen_ai.usage.total_tokens",
+	UsageServerSideTools = "pi.gen_ai.usage.server_tool_requests",
+	CostEstimatedUsd = "pi.gen_ai.cost.estimated_usd",
+	CostInputUsd = "pi.gen_ai.cost.input_usd",
+	CostOutputUsd = "pi.gen_ai.cost.output_usd",
+	CostUnavailableReason = "pi.gen_ai.cost.unavailable_reason",
+	ToolStatus = "pi.gen_ai.tool.status",
+	ToolCallIntent = "pi.gen_ai.tool.call.intent",
+	HandoffFromAgentName = "pi.gen_ai.handoff.from_agent.name",
+	HandoffFromAgentId = "pi.gen_ai.handoff.from_agent.id",
+	HandoffToAgentName = "pi.gen_ai.handoff.to_agent.name",
+	HandoffToAgentId = "pi.gen_ai.handoff.to_agent.id",
+	// Marks chat spans emitted outside the agent loop (compaction, handoff, branch
+	// summary, image inspection, …). Lets dashboards split oneshot cost / latency
+	// from main-turn cost without overloading the semconv `gen_ai.operation.name`.
+	OneshotKind = "pi.gen_ai.oneshot.kind",
+	// Gateway / proxy (LiteLLM, Helicone, Portkey, …) — populated when a known
+	// gateway header pattern is detected on the upstream response. The base
+	// `gen_ai.provider.name` continues to track the *upstream* provider (e.g.
+	// `anthropic`) that the gateway routed to.
+	GatewayName = "pi.gen_ai.gateway.name",
+	GatewayEndpoint = "pi.gen_ai.gateway.endpoint",
+	GatewayCallId = "pi.gen_ai.gateway.call_id",
+	GatewayRoutedTo = "pi.gen_ai.gateway.routed_to",
+}
+
+/** GenAI operation names — values for {@link GenAIAttr.OperationName}. */
+export const GenAIOperation = {
+	Chat: "chat",
+	ExecuteTool: "execute_tool",
+	InvokeAgent: "invoke_agent",
+	Handoff: "handoff",
+	GenerateContent: "generate_content",
+	TextCompletion: "text_completion",
+	CreateAgent: "create_agent",
+	Embeddings: "embeddings",
+} as const;
+
+export type GenAIOperationName = (typeof GenAIOperation)[keyof typeof GenAIOperation];
+
+/** Identifies which agent span a callback is reporting on. */
+export type TelemetrySpanKind = "invoke_agent" | "chat" | "execute_tool" | "handoff";
+
+/**
+ * Aggregated usage + cost surface passed to {@link AgentTelemetryConfig.costEstimator}.
+ * Mirrors the bucketed shape we already emit as span attributes so the
+ * estimator never has to re-derive cache-read vs cache-write breakdowns.
+ */
+export interface ChatUsageSnapshot {
+	readonly inputTokens: number;
+	readonly outputTokens: number;
+	readonly totalTokens: number;
+	readonly cachedInputTokens: number | undefined;
+	readonly cacheWriteTokens: number | undefined;
+	readonly reasoningOutputTokens: number | undefined;
+}
+
+/** Context passed to the cost estimator. */
+export interface CostEstimatorContext {
+	readonly provider: string;
+	readonly model: string;
+	readonly serviceTier: ServiceTier | undefined;
+	readonly usage: ChatUsageSnapshot;
+}
+
+/**
+ * Cost estimator result.
+ *   { usd: number }                — cost is known; emitted as pi.gen_ai.cost.estimated_usd
+ *   { unavailable: string }        — cost is intentionally unknown; emitted as
+ *                                    pi.gen_ai.cost.unavailable_reason
+ *   undefined                      — no opinion; nothing emitted
+ */
+export type CostEstimate =
+	| { readonly usd: number; readonly inputUsd?: number; readonly outputUsd?: number }
+	| { readonly unavailable: string };
+
+export interface CostDelta {
+	readonly conversationId: string | undefined;
+	readonly agent: AgentIdentity | undefined;
+	readonly stepNumber: number | undefined;
+	readonly provider: string;
+	readonly model: string;
+	readonly serviceTier: ServiceTier | undefined;
+	readonly usage: ChatUsageSnapshot;
+	readonly costUsd: number | undefined;
+	readonly inputUsd: number | undefined;
+	readonly outputUsd: number | undefined;
+	readonly costUnavailableReason: string | undefined;
+}
+
+/**
+ * Event fired for every chat step that produced usage, regardless of whether
+ * a {@link AgentTelemetryConfig.costEstimator} is configured. Use this to
+ * forward token usage to metrics pipelines or dashboards without taking a
+ * dependency on the cost estimator path.
+ */
+export interface ChatUsageEvent {
+	readonly span: Span;
+	readonly agent: AgentIdentity | undefined;
+	readonly conversationId: string | undefined;
+	readonly stepNumber: number | undefined;
+	readonly model: string;
+	readonly provider: string | undefined;
+	readonly serviceTier: ServiceTier | undefined;
+	readonly usage: ChatUsageSnapshot;
+	readonly cost: CostEstimate | undefined;
+	/** Resolved dynamic attributes for this chat span (from `resolveAttributes`). */
+	readonly attributes: Attributes | undefined;
+	/**
+	 * Response headers captured from the upstream HTTP response, with keys
+	 * lowercased (mirrors {@link ProviderResponseMetadata.headers}). `undefined`
+	 * when the provider transport did not surface headers (non-HTTP providers,
+	 * mocked streams, requests that aborted before headers arrived).
+	 *
+	 * Use this to reconcile gateway-issued ids (e.g. `x-litellm-call-id`) with
+	 * downstream billing / spend dashboards. Known gateway patterns are also
+	 * auto-stamped on the chat span as `pi.gen_ai.gateway.*` attributes.
+	 */
+	readonly headers: Readonly<Record<string, string>> | undefined;
+}
+
+export type TelemetryContentCapture = boolean | "none" | "summary" | "full";
+
+export type ResolvedTelemetryContentCapture = "none" | "summary" | "full";
+
+export interface TelemetryContentSerializer {
+	readonly requestMessages?: (request: ChatRequestSnapshot) => string | undefined;
+	readonly responseText?: (message: AssistantMessage) => string | undefined;
+	readonly responseToolCalls?: (message: AssistantMessage) => string | undefined;
+	readonly toolCallArguments?: (args: unknown) => string | undefined;
+	readonly toolCallResult?: (result: unknown) => string | undefined;
+}
+
+/** Identity recorded on every invoke_agent and on emitted handoff spans. */
+export interface AgentIdentity {
+	readonly id?: string;
+	readonly name?: string;
+	readonly description?: string;
+}
+
+export interface AgentTelemetryWarning {
+	readonly code:
+		| "resolve_attributes_failed"
+		| "content_serializer_failed"
+		| "on_cost_delta_failed"
+		| "on_chat_usage_failed"
+		| "cost_estimator_failed"
+		| "on_run_end_failed"
+		| "on_span_start_failed"
+		| "on_span_end_failed"
+		| "normalize_agent_name_failed"
+		| "normalize_provider_failed"
+		| "on_telemetry_warning_failed";
+	readonly message: string;
+	readonly error?: unknown;
+}
+
+/** Context passed to attribute resolvers and lifecycle hooks. */
+export interface TelemetryAttributeContext {
+	readonly kind: TelemetrySpanKind;
+	readonly model: Model | undefined;
+	readonly agent: AgentIdentity | undefined;
+	readonly conversationId: string | undefined;
+	/** Per-step number on chat spans (0-indexed); undefined on other kinds. */
+	readonly stepNumber?: number;
+	/** Tool call info on execute_tool spans. */
+	readonly toolCallId?: string;
+	readonly toolName?: string;
+}
+
+/** Context passed to {@link AgentTelemetryConfig.onSpanStart} / `onSpanEnd`. */
+export interface TelemetryHookContext extends TelemetryAttributeContext {
+	readonly span: Span;
+}
+/**
+ * Opt-in OpenTelemetry configuration accepted by the agent loop.
+ *
+ * All fields are optional. Passing the empty object `{}` enables
+ * instrumentation with sensible defaults. Pass `undefined` (or omit the
+ * `telemetry` field entirely) to disable everything — the loop performs zero
+ * tracer lookups in that case.
+ */
+export interface AgentTelemetryConfig {
+	/**
+	 * Override the tracer instance. When omitted, the loop calls
+	 * `trace.getTracer(tracerName ?? DEFAULT_TRACER_NAME)` lazily on first use.
+	 */
+	readonly tracer?: Tracer;
+	/** Override the tracer name passed to `trace.getTracer`. */
+	readonly tracerName?: string;
+	/**
+	 * Capture request/response content. `true` preserves the historical full
+	 * payload capture; `"summary"` emits bounded dashboard-friendly summaries;
+	 * `"full"` emits both summaries and full OTEL message payloads.
+	 *
+	 * Defaults to the value of the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`
+	 * env var (`true`/`1`/`yes` => `"full"`, `"summary"` => `"summary"`).
+	 */
+	readonly captureMessageContent?: TelemetryContentCapture;
+	/** Extra attributes merged onto every emitted span. */
+	readonly attributes?: Attributes;
+	/**
+	 * Attribute resolver merged onto every emitted span after static
+	 * `attributes` and before span-specific attributes. Use this for ambient
+	 * run, tenant, deployment, or request metadata.
+	 */
+	readonly resolveAttributes?: (ctx: TelemetryAttributeContext) => Attributes | undefined;
+	/** Agent identity stamped onto invoke_agent + propagated to children. */
+	readonly agent?: AgentIdentity;
+	/**
+	 * Conversation identifier. When omitted, the loop falls back to
+	 * `AgentLoopConfig.sessionId` for the `gen_ai.conversation.id` attribute.
+	 */
+	readonly conversationId?: string;
+	/**
+	 * Per-step cost estimator. Synchronous on purpose — runs inside the chat
+	 * span's finish path. Return `undefined` to emit no cost attribute.
+	 */
+	readonly costEstimator?: (input: CostEstimatorContext) => CostEstimate | undefined;
+	/** Called after cost estimation for a chat step. */
+	readonly onCostDelta?: (delta: CostDelta) => void;
+	/**
+	 * Fired once per chat step that produced usage, regardless of whether a
+	 * {@link costEstimator} is configured. Use this for usage-only metrics
+	 * pipelines (token counters, cache-hit ratios) without paying the cost of
+	 * estimating dollars per call.
+	 *
+	 * **Non-fatal.** Synchronous and asynchronous failures are caught, surfaced
+	 * via {@link onTelemetryWarning}, and swallowed.
+	 */
+	readonly onChatUsage?: (event: ChatUsageEvent) => void | Promise<void>;
+	/** Override provider labels before they are emitted or passed to cost hooks. */
+	readonly normalizeProvider?: (provider: string | undefined) => string | undefined;
+	/** Override agent names before they are emitted on spans. */
+	readonly normalizeAgentName?: (name: string | undefined) => string | undefined;
+	/** Override the default bounded JSON serializers used by summary capture. */
+	readonly contentSerializer?: TelemetryContentSerializer;
+	/**
+	 * Called immediately after a span starts. Use to stamp request-side
+	 * context (user id, deployment id, route name) without forking the loop.
+	 */
+	readonly onSpanStart?: (ctx: TelemetryHookContext) => void;
+	/**
+	 * Called just before `span.end()`. Use to stamp response-side context
+	 * that depends on the final result.
+	 */
+	readonly onSpanEnd?: (ctx: TelemetryHookContext) => void;
+	/**
+	 * Fired once per `invoke_agent`, immediately after the run-level summary
+	 * is built and aggregate attributes are stamped on the `invoke_agent`
+	 * span. Use this to persist, log, or forward the {@link AgentRunSummary} /
+	 * {@link AgentRunCoverage} value without parsing OTEL spans.
+	 *
+	 * **Non-fatal.** Exceptions thrown from this callback are caught, logged
+	 * via `console.warn`, and swallowed — a misbehaving telemetry consumer can
+	 * NEVER turn a successful agent run into a failed one.
+	 */
+	readonly onRunEnd?: (summary: AgentRunSummary, coverage: AgentRunCoverage) => void;
+	/** Receives non-fatal telemetry callback failures and host-defined warnings. */
+	readonly onTelemetryWarning?: (warning: AgentTelemetryWarning) => void;
+}
+
+/**
+ * Public handle used internally to thread the resolved tracer + config
+ * through the loop. Constructed once per `agentLoop` invocation.
+ */
+export interface AgentTelemetry {
+	readonly config: AgentTelemetryConfig;
+	readonly tracer: Tracer;
+	readonly captureMessageContent: boolean;
+	readonly contentCapture: ResolvedTelemetryContentCapture;
+	readonly conversationId: string | undefined;
+	readonly agent: AgentIdentity | undefined;
+	/** Per-invocation event collector. See {@link AgentRunCollector}. */
+	readonly collector: AgentRunCollector;
+}
+
+/** Lazily resolve the {@link AgentTelemetry} handle. Returns `undefined` when disabled. */
+export function resolveTelemetry(
+	config: AgentTelemetryConfig | undefined,
+	sessionId: string | undefined,
+): AgentTelemetry | undefined {
+	if (!config) return undefined;
+	const tracer = config.tracer ?? trace.getTracer(config.tracerName ?? DEFAULT_TRACER_NAME);
+	const contentCapture = resolveContentCapture(config.captureMessageContent);
+	return {
+		config,
+		tracer,
+		captureMessageContent: contentCapture === "full",
+		contentCapture,
+		conversationId: config.conversationId ?? sessionId,
+		agent: config.agent,
+		collector: new AgentRunCollector(),
+	};
+}
+
+let contentCaptureEnvCache: ResolvedTelemetryContentCapture | undefined;
+function readContentCaptureEnv(): ResolvedTelemetryContentCapture {
+	if (contentCaptureEnvCache !== undefined) return contentCaptureEnvCache;
+	const raw = process.env[CONTENT_CAPTURE_ENV];
+	if (!raw) {
+		contentCaptureEnvCache = "none";
+		return "none";
+	}
+	const normalized = raw.trim().toLowerCase();
+	if (normalized === "summary") {
+		contentCaptureEnvCache = "summary";
+	} else {
+		contentCaptureEnvCache =
+			normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "full" ? "full" : "none";
+	}
+	return contentCaptureEnvCache;
+}
+
+function resolveContentCapture(value: TelemetryContentCapture | undefined): ResolvedTelemetryContentCapture {
+	const capture = value ?? readContentCaptureEnv();
+	if (capture === true || capture === "full") return "full";
+	if (capture === "summary") return "summary";
+	return "none";
+}
+
+/**
+ * Start a span with the standard attribute envelope (provider, operation,
+ * conversation, agent identity, user-supplied extras) pre-applied. Returns
+ * `undefined` when telemetry is disabled.
+ */
+function startSpan(
+	telemetry: AgentTelemetry | undefined,
+	kind: TelemetrySpanKind,
+	name: string,
+	options: {
+		readonly spanKind: SpanKind;
+		readonly model?: Model;
+		readonly parent?: Span;
+		readonly attributes?: Attributes;
+		readonly stepNumber?: number;
+		readonly toolCallId?: string;
+		readonly toolName?: string;
+	},
+): Span | undefined {
+	if (!telemetry) return undefined;
+	const attrCtx = buildTelemetryAttributeContext(telemetry, kind, options);
+	const attrs: Attributes = {};
+	const operation = kindToOperation(kind);
+	if (operation) attrs[GenAIAttr.OperationName] = operation;
+	if (options.model) {
+		attrs[GenAIAttr.RequestModel] = options.model.id;
+		const provider = normalizeProviderName(telemetry, options.model.provider);
+		if (provider) attrs[GenAIAttr.ProviderName] = provider;
+	}
+	if (telemetry.conversationId) {
+		attrs[GenAIAttr.ConversationId] = telemetry.conversationId;
+	}
+	if (attrCtx.agent) applyAgentAttributes(attrs, attrCtx.agent);
+	if (telemetry.config.attributes) Object.assign(attrs, telemetry.config.attributes);
+	const dynamicAttributes = resolveDynamicAttributes(telemetry, attrCtx);
+	if (dynamicAttributes) Object.assign(attrs, dynamicAttributes);
+	if (options.attributes) Object.assign(attrs, options.attributes);
+
+	const ctx = options.parent ? trace.setSpan(context.active(), options.parent) : context.active();
+	const span = telemetry.tracer.startSpan(name, { kind: options.spanKind, attributes: attrs }, ctx);
+	safeOnSpanStart(telemetry, { ...attrCtx, span });
+	return span;
+}
+
+function buildTelemetryAttributeContext(
+	telemetry: AgentTelemetry,
+	kind: TelemetrySpanKind,
+	options: {
+		readonly model?: Model;
+		readonly stepNumber?: number;
+		readonly toolCallId?: string;
+		readonly toolName?: string;
+	},
+): TelemetryAttributeContext {
+	return {
+		kind,
+		model: options.model,
+		agent: normalizedTelemetryAgent(telemetry),
+		conversationId: telemetry.conversationId,
+		stepNumber: options.stepNumber,
+		toolCallId: options.toolCallId,
+		toolName: options.toolName,
+	};
+}
+
+function resolveDynamicAttributes(telemetry: AgentTelemetry, ctx: TelemetryAttributeContext): Attributes | undefined {
+	const resolver = telemetry.config.resolveAttributes;
+	if (!resolver) return undefined;
+	try {
+		return resolver(ctx);
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "resolve_attributes_failed",
+			message: "resolveAttributes threw; ignoring dynamic telemetry attributes",
+			error: err,
+		});
+		return undefined;
+	}
+}
+
+function kindToOperation(kind: TelemetrySpanKind): GenAIOperationName | undefined {
+	switch (kind) {
+		case "invoke_agent":
+			return GenAIOperation.InvokeAgent;
+		case "chat":
+			return GenAIOperation.Chat;
+		case "execute_tool":
+			return GenAIOperation.ExecuteTool;
+		case "handoff":
+			return GenAIOperation.Handoff;
+	}
+}
+
+function applyAgentAttributes(attrs: Attributes, agent: AgentIdentity): void {
+	if (agent.id) attrs[GenAIAttr.AgentId] = agent.id;
+	if (agent.name) attrs[GenAIAttr.AgentName] = agent.name;
+	if (agent.description) attrs[GenAIAttr.AgentDescription] = agent.description;
+}
+
+function normalizeProviderName(
+	telemetry: AgentTelemetry | undefined,
+	provider: string | undefined,
+): string | undefined {
+	const otelProvider = mapProviderNameToOtel(provider);
+	const normalize = telemetry?.config.normalizeProvider;
+	if (!normalize) return otelProvider;
+	try {
+		return normalize(provider) ?? otelProvider;
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "normalize_provider_failed",
+			message: "normalizeProvider threw; using the OTEL provider label",
+			error: err,
+		});
+		return otelProvider;
+	}
+}
+
+function mapProviderNameToOtel(provider: string | undefined): string | undefined {
+	switch (provider) {
+		case undefined:
+		case "":
+			return provider;
+		case "amazon-bedrock":
+			return "aws.bedrock";
+		case "google":
+		case "google-antigravity":
+		case "google-gemini-cli":
+			return "gcp.gemini";
+		case "google-vertex":
+			return "gcp.vertex_ai";
+		case "mistral":
+			return "mistral_ai";
+		case "openai-codex":
+			return "openai";
+		case "xai":
+			return "x_ai";
+		default:
+			return provider;
+	}
+}
+
+function normalizeAgentIdentity(telemetry: AgentTelemetry, agent: AgentIdentity): AgentIdentity {
+	const normalize = telemetry.config.normalizeAgentName;
+	if (!normalize || !agent.name) return agent;
+	try {
+		const name = normalize(agent.name);
+		if (name === agent.name) return agent;
+		return {
+			...agent,
+			name,
+		};
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "normalize_agent_name_failed",
+			message: "normalizeAgentName threw; using the original agent name",
+			error: err,
+		});
+		return agent;
+	}
+}
+
+function normalizedTelemetryAgent(telemetry: AgentTelemetry | undefined): AgentIdentity | undefined {
+	return telemetry?.agent ? normalizeAgentIdentity(telemetry, telemetry.agent) : undefined;
+}
+
+export function recordTelemetryWarning(telemetry: AgentTelemetry | undefined, warning: AgentTelemetryWarning): void {
+	emitTelemetryWarning(telemetry, warning);
+}
+
+function emitTelemetryWarning(telemetry: AgentTelemetry | undefined, warning: AgentTelemetryWarning): void {
+	const hook = telemetry?.config.onTelemetryWarning;
+	if (!hook) {
+		if (warning.error === undefined) console.warn(`[pi-agent] ${warning.message}`);
+		else console.warn(`[pi-agent] ${warning.message}`, warning.error);
+		return;
+	}
+	try {
+		hook(warning);
+	} catch (err) {
+		console.warn("[pi-agent] onTelemetryWarning threw; swallowing:", err);
+	}
+}
+
+function safeOnSpanStart(telemetry: AgentTelemetry | undefined, ctx: TelemetryHookContext): void {
+	const hook = telemetry?.config.onSpanStart;
+	if (!hook) return;
+	try {
+		hook(ctx);
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "on_span_start_failed",
+			message: "onSpanStart threw; swallowing telemetry hook failure",
+			error: err,
+		});
+	}
+}
+
+function safeOnSpanEnd(telemetry: AgentTelemetry | undefined, ctx: TelemetryHookContext): void {
+	const hook = telemetry?.config.onSpanEnd;
+	if (!hook) return;
+	try {
+		hook(ctx);
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "on_span_end_failed",
+			message: "onSpanEnd threw; swallowing telemetry hook failure",
+			error: err,
+		});
+	}
+}
+
+/**
+ * Start the outer `invoke_agent` span that wraps a full `runLoop` invocation.
+ * Returns `undefined` when telemetry is disabled.
+ */
+export function startInvokeAgentSpan(telemetry: AgentTelemetry | undefined, model: Model): Span | undefined {
+	const agentName = telemetry?.agent ? normalizeAgentIdentity(telemetry, telemetry.agent).name : undefined;
+	const name = agentName ? `invoke_agent ${agentName}` : "invoke_agent";
+	return startSpan(telemetry, "invoke_agent", name, { spanKind: SpanKind.INTERNAL, model });
+}
+
+/** Stamp the final step count on the `invoke_agent` span. */
+export function applyInvokeAgentFinish(span: Span | undefined, stepCount: number): void {
+	if (!span) return;
+	span.setAttribute(PiGenAIAttr.AgentStepCount, stepCount);
+}
+
+/**
+ * Start a `chat` span representing one provider call. Parented under the
+ * supplied `invoke_agent` span (or whatever is active if none is passed).
+ */
+export function startChatSpan(
+	telemetry: AgentTelemetry | undefined,
+	model: Model,
+	options: {
+		readonly parent?: Span;
+		readonly stepNumber: number;
+		readonly request: ChatRequestSnapshot;
+	},
+): Span | undefined {
+	const span = startSpan(telemetry, "chat", `chat ${model.id}`, {
+		spanKind: SpanKind.CLIENT,
+		model,
+		parent: options.parent,
+		stepNumber: options.stepNumber,
+		attributes: buildChatRequestAttributes(options.stepNumber, options.request, model.provider),
+	});
+	if (span) {
+		telemetry?.collector.beginChat(span, {
+			stepNumber: options.stepNumber,
+			model,
+			provider: normalizeProviderName(telemetry, model.provider),
+		});
+		telemetry?.collector.noteAvailableTools(options.request.tools);
+		if (telemetry && telemetry.contentCapture !== "none") {
+			applyContentCaptureForRequest(telemetry, span, options.request);
+		}
+	}
+	return span;
+}
+
+/** Mutable snapshot of every request-side field worth recording. */
+export interface ChatRequestSnapshot {
+	readonly maxTokens?: number;
+	readonly temperature?: number;
+	readonly topP?: number;
+	readonly topK?: number;
+	readonly frequencyPenalty?: number;
+	readonly presencePenalty?: number;
+	readonly stopSequences?: readonly string[];
+	readonly seed?: number;
+	readonly serviceTier?: ServiceTier;
+	readonly reasoningEffort?: string;
+	readonly toolChoice?: ToolChoice;
+	readonly tools?: readonly { readonly name: string }[];
+	readonly systemPrompt?: readonly string[];
+	readonly messages?: readonly Message[];
+}
+
+function buildChatRequestAttributes(stepNumber: number, request: ChatRequestSnapshot, provider: string): Attributes {
+	const attrs: Attributes = {
+		[PiGenAIAttr.AgentStepNumber]: stepNumber,
+		[GenAIAttr.OutputType]: "text",
+		[GenAIAttr.RequestStream]: true,
+	};
+	if (request.maxTokens != null) attrs[GenAIAttr.RequestMaxTokens] = request.maxTokens;
+	if (request.temperature != null) attrs[GenAIAttr.RequestTemperature] = request.temperature;
+	if (request.topP != null) attrs[GenAIAttr.RequestTopP] = request.topP;
+	if (request.topK != null) attrs[GenAIAttr.RequestTopK] = request.topK;
+	if (request.frequencyPenalty != null) attrs[GenAIAttr.RequestFrequencyPenalty] = request.frequencyPenalty;
+	if (request.presencePenalty != null) attrs[GenAIAttr.RequestPresencePenalty] = request.presencePenalty;
+	if (request.seed != null) attrs[GenAIAttr.RequestSeed] = request.seed;
+	if (request.stopSequences && request.stopSequences.length > 0) {
+		attrs[GenAIAttr.RequestStopSequences] = [...request.stopSequences];
+	}
+	if (request.serviceTier && shouldSendServiceTier(request.serviceTier, provider)) {
+		attrs[OpenAIAttr.RequestServiceTier] = request.serviceTier;
+	}
+	if (request.reasoningEffort) attrs[PiGenAIAttr.RequestReasoningEffort] = request.reasoningEffort;
+	const toolChoice = serializeToolChoice(request.toolChoice);
+	if (toolChoice) attrs[PiGenAIAttr.RequestToolChoice] = toolChoice;
+	if (request.tools && request.tools.length > 0) {
+		attrs[PiGenAIAttr.RequestAvailableTools] = request.tools.map(tool => tool.name);
+	}
+	return attrs;
+}
+
+function serializeToolChoice(toolChoice: ToolChoice | undefined): string | undefined {
+	if (toolChoice == null) return undefined;
+	if (typeof toolChoice === "string") return toolChoice;
+	if (typeof toolChoice === "object") {
+		// `{ type: "tool", name: "foo" }` shapes used across providers.
+		if ("name" in toolChoice && typeof toolChoice.name === "string") return toolChoice.name;
+		if ("type" in toolChoice && typeof toolChoice.type === "string") return toolChoice.type;
+	}
+	return undefined;
+}
+
+function applyContentCaptureForRequest(telemetry: AgentTelemetry, span: Span, request: ChatRequestSnapshot): void {
+	const requestMessages = serializeRequestMessagesForTelemetry(telemetry, request);
+	if (requestMessages) span.setAttribute(PiGenAIAttr.RequestMessages, requestMessages);
+	if (telemetry.contentCapture !== "full") return;
+	const systemInstructions = serializeFullSystemInstructionsForTelemetry(request);
+	if (systemInstructions) span.setAttribute(GenAIAttr.SystemInstructions, systemInstructions);
+	const inputMessages = serializeFullInputMessagesForTelemetry(request);
+	if (inputMessages) span.setAttribute(GenAIAttr.InputMessages, inputMessages);
+}
+
+function applyContentCaptureForResponse(telemetry: AgentTelemetry, span: Span, message: AssistantMessage): void {
+	const responseText = serializeResponseTextForTelemetry(telemetry, message);
+	if (responseText) span.setAttribute(PiGenAIAttr.ResponseText, responseText);
+	const responseToolCalls = serializeResponseToolCallsForTelemetry(telemetry, message);
+	if (responseToolCalls) span.setAttribute(PiGenAIAttr.ResponseToolCalls, responseToolCalls);
+	if (telemetry.contentCapture === "full") {
+		const outputMessages = serializeFullOutputMessagesForTelemetry(message);
+		if (outputMessages) span.setAttribute(GenAIAttr.OutputMessages, outputMessages);
+	}
+}
+
+function serializeRequestMessagesForTelemetry(
+	telemetry: AgentTelemetry,
+	request: ChatRequestSnapshot,
+): string | undefined {
+	const serializer = telemetry.config.contentSerializer?.requestMessages;
+	if (serializer) return callContentSerializer(telemetry, "requestMessages", () => serializer(request));
+	const messages: TelemetryMessageSummary[] = [];
+	if (request.systemPrompt) {
+		for (const text of request.systemPrompt)
+			messages.push({ role: "system", content: summarizeTelemetryValue(text) });
+	}
+	if (request.messages) {
+		for (const message of request.messages) {
+			messages.push({ role: message.role, content: summarizeTelemetryValue(message.content) });
+		}
+	}
+	return messages.length === 0 ? undefined : stringifyJsonAttribute(limitTelemetryMessages(messages));
+}
+
+function serializeResponseTextForTelemetry(telemetry: AgentTelemetry, message: AssistantMessage): string | undefined {
+	const serializer = telemetry.config.contentSerializer?.responseText;
+	if (serializer) return callContentSerializer(telemetry, "responseText", () => serializer(message));
+	const texts: string[] = [];
+	for (const part of message.content) {
+		if (part.type === "text") texts.push(part.text);
+	}
+	return texts.length === 0 ? undefined : stringifyJsonAttribute(summarizeTelemetryTexts(texts));
+}
+
+function serializeResponseToolCallsForTelemetry(
+	telemetry: AgentTelemetry,
+	message: AssistantMessage,
+): string | undefined {
+	const serializer = telemetry.config.contentSerializer?.responseToolCalls;
+	if (serializer) return callContentSerializer(telemetry, "responseToolCalls", () => serializer(message));
+	const toolCalls: TelemetryToolCallSummary[] = [];
+	for (const part of message.content) {
+		if (part.type === "toolCall") {
+			toolCalls.push({
+				input: summarizeTelemetryValue(part.arguments),
+				toolCallId: part.id,
+				toolName: part.name,
+			});
+		}
+	}
+	return toolCalls.length === 0 ? undefined : stringifyJsonAttribute(limitTelemetryToolCalls(toolCalls));
+}
+
+interface TelemetryMessageSummary {
+	readonly role: string;
+	readonly content: unknown;
+}
+
+interface TelemetryToolCallSummary {
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly input: unknown;
+}
+
+type OtelMessagePart =
+	| { readonly type: "text"; readonly content: string }
+	| { readonly type: "reasoning"; readonly content: string }
+	| { readonly type: "blob"; readonly modality: "image"; readonly mime_type: string; readonly content: string }
+	| { readonly type: "tool_call"; readonly id?: string; readonly name: string; readonly arguments?: unknown }
+	| { readonly type: "tool_call_response"; readonly id?: string; readonly response: unknown }
+	| { readonly type: string; readonly [key: string]: unknown };
+
+interface OtelInputMessage {
+	readonly role: string;
+	readonly parts: readonly OtelMessagePart[];
+	readonly name?: string;
+}
+
+interface OtelOutputMessage extends OtelInputMessage {
+	readonly finish_reason: string;
+}
+
+function serializeFullSystemInstructionsForTelemetry(request: ChatRequestSnapshot): string | undefined {
+	const systemPrompt = request.systemPrompt;
+	if (!systemPrompt || systemPrompt.length === 0) return undefined;
+	return stringifyJsonAttribute(systemPrompt.map(text => ({ type: "text", content: text }) satisfies OtelMessagePart));
+}
+
+function serializeFullInputMessagesForTelemetry(request: ChatRequestSnapshot): string | undefined {
+	const messages = request.messages;
+	if (!messages || messages.length === 0) return undefined;
+	return stringifyJsonAttribute(messages.map(messageToOtelInputMessage));
+}
+
+function serializeFullOutputMessagesForTelemetry(message: AssistantMessage): string | undefined {
+	return stringifyJsonAttribute([assistantMessageToOtelOutputMessage(message)]);
+}
+
+function messageToOtelInputMessage(message: Message): OtelInputMessage {
+	switch (message.role) {
+		case "assistant":
+			return { role: "assistant", parts: assistantContentToOtelParts(message.content) };
+		case "toolResult":
+			return {
+				role: "tool",
+				name: message.toolName,
+				parts: [
+					{
+						type: "tool_call_response",
+						id: message.toolCallId,
+						response: {
+							content: textOrImageContentToOtelParts(message.content),
+							details: message.details,
+							is_error: message.isError,
+						},
+					},
+				],
+			};
+		default:
+			return { role: message.role, parts: textOrImageContentToOtelParts(message.content) };
+	}
+}
+
+function assistantMessageToOtelOutputMessage(message: AssistantMessage): OtelOutputMessage {
+	return {
+		role: "assistant",
+		parts: assistantContentToOtelParts(message.content),
+		finish_reason: mapStopReason(message.stopReason) ?? message.stopReason ?? "stop",
+	};
+}
+
+function textOrImageContentToOtelParts(content: Message["content"]): OtelMessagePart[] {
+	if (typeof content === "string") return [{ type: "text", content }];
+	const parts: OtelMessagePart[] = [];
+	for (const part of content) {
+		switch (part.type) {
+			case "text":
+				parts.push({ type: "text", content: part.text });
+				break;
+			case "image":
+				parts.push({ type: "blob", modality: "image", mime_type: part.mimeType, content: part.data });
+				break;
+			case "thinking":
+				parts.push({ type: "reasoning", content: part.thinking });
+				break;
+			case "redactedThinking":
+				parts.push({ type: "reasoning", content: part.data });
+				break;
+			case "toolCall":
+				parts.push({ type: "tool_call", id: part.id, name: part.name, arguments: part.arguments });
+				break;
+			default:
+				break;
+		}
+	}
+	return parts;
+}
+
+function assistantContentToOtelParts(content: AssistantMessage["content"]): OtelMessagePart[] {
+	const parts: OtelMessagePart[] = [];
+	for (const part of content) {
+		switch (part.type) {
+			case "text":
+				parts.push({ type: "text", content: part.text });
+				break;
+			case "thinking":
+				parts.push({ type: "reasoning", content: part.thinking });
+				break;
+			case "redactedThinking":
+				parts.push({ type: "reasoning", content: part.data });
+				break;
+			case "toolCall":
+				parts.push({ type: "tool_call", id: part.id, name: part.name, arguments: part.arguments });
+				break;
+		}
+	}
+	return parts;
+}
+
+function callContentSerializer(
+	telemetry: AgentTelemetry,
+	name: keyof TelemetryContentSerializer,
+	serialize: () => string | undefined,
+): string | undefined {
+	try {
+		return serialize();
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "content_serializer_failed",
+			message: `${name} content serializer threw; omitting telemetry content`,
+			error: err,
+		});
+		return undefined;
+	}
+}
+
+function limitTelemetryMessages(messages: readonly TelemetryMessageSummary[]): TelemetryMessageSummary[] {
+	const limited = messages.slice(0, MAX_TELEMETRY_MESSAGE_COUNT);
+	if (messages.length > MAX_TELEMETRY_MESSAGE_COUNT) {
+		limited.push({
+			role: "system",
+			content: { kind: "truncated", omittedMessages: messages.length - MAX_TELEMETRY_MESSAGE_COUNT },
+		});
+	}
+	return limited;
+}
+
+function limitTelemetryToolCalls(toolCalls: readonly TelemetryToolCallSummary[]): TelemetryToolCallSummary[] {
+	const limited = toolCalls.slice(0, MAX_TELEMETRY_ARRAY_ITEMS);
+	if (toolCalls.length > MAX_TELEMETRY_ARRAY_ITEMS) {
+		limited.push({
+			toolCallId: "[truncated]",
+			toolName: "[truncated]",
+			input: { kind: "truncated", omittedToolCalls: toolCalls.length - MAX_TELEMETRY_ARRAY_ITEMS },
+		});
+	}
+	return limited;
+}
+
+function summarizeTelemetryTexts(texts: readonly string[]): string[] {
+	const summarized = texts.slice(0, MAX_TELEMETRY_ARRAY_ITEMS).map(text => summarizeTelemetryText(text));
+	if (texts.length > MAX_TELEMETRY_ARRAY_ITEMS) {
+		summarized.push(`[${texts.length - MAX_TELEMETRY_ARRAY_ITEMS} additional text entries omitted]`);
+	}
+	return summarized;
+}
+
+function summarizeTelemetryText(text: string): string {
+	if (text.length <= MAX_TELEMETRY_TEXT_CHARS) return text;
+	return `${text.slice(0, MAX_TELEMETRY_TEXT_CHARS)} [${text.length - MAX_TELEMETRY_TEXT_CHARS} chars omitted]`;
+}
+
+function summarizeTelemetryValue(value: unknown, depth = 0, seen?: Set<object>): unknown {
+	if (typeof value === "string") return summarizeTelemetryText(value);
+	if (typeof value === "number" || typeof value === "boolean" || value == null) return value;
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "function") return "[Function]";
+	if (value instanceof Error) {
+		return { name: value.name, message: summarizeTelemetryText(value.message) };
+	}
+	if (Array.isArray(value)) {
+		// Cap array recursion at the same depth as plain-object recursion so
+		// pathological nested-array shapes (or arrays containing themselves)
+		// cannot blow the stack via `summarizeTelemetryValue`.
+		if (depth >= MAX_TELEMETRY_OBJECT_DEPTH) {
+			return { kind: "array", length: value.length };
+		}
+		const ancestors = seen ?? new Set<object>();
+		if (ancestors.has(value)) return "[Circular]";
+		ancestors.add(value);
+		const items = value
+			.slice(0, MAX_TELEMETRY_ARRAY_ITEMS)
+			.map(item => summarizeTelemetryValue(item, depth + 1, ancestors));
+		if (value.length > MAX_TELEMETRY_ARRAY_ITEMS) {
+			items.push({ kind: "truncated", omittedItems: value.length - MAX_TELEMETRY_ARRAY_ITEMS });
+		}
+		ancestors.delete(value);
+		return items;
+	}
+	if (!isPlainTelemetryRecord(value)) return String(value);
+	const ancestors = seen ?? new Set<object>();
+	if (ancestors.has(value)) return "[Circular]";
+	const entries = Object.entries(value);
+	if (depth >= MAX_TELEMETRY_OBJECT_DEPTH) {
+		return summarizeTelemetryObjectKeys(entries);
+	}
+	ancestors.add(value);
+	const summary: Record<string, unknown> = {};
+	for (const [key, item] of entries.slice(0, MAX_TELEMETRY_OBJECT_KEYS)) {
+		summary[key] = summarizeTelemetryValue(item, depth + 1, ancestors);
+	}
+	if (entries.length > MAX_TELEMETRY_OBJECT_KEYS) {
+		summary.telemetrySummary = { omittedKeys: entries.length - MAX_TELEMETRY_OBJECT_KEYS };
+	}
+	ancestors.delete(value);
+	return summary;
+}
+
+function summarizeTelemetryObjectKeys(entries: readonly (readonly [string, unknown])[]): Record<string, unknown> {
+	const keys = entries.slice(0, MAX_TELEMETRY_OBJECT_KEYS).map(([key]) => key);
+	return entries.length > MAX_TELEMETRY_OBJECT_KEYS
+		? { kind: "object", keys, telemetrySummary: { omittedKeys: entries.length - MAX_TELEMETRY_OBJECT_KEYS } }
+		: { kind: "object", keys };
+}
+
+function isPlainTelemetryRecord(value: unknown): value is Record<string, unknown> {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+function stringifyJsonAttribute(value: unknown): string | undefined {
+	const serialized = JSON.stringify(value);
+	return serialized === undefined ? undefined : serialized;
+}
+
+function serializeToolCallArgumentsForTelemetry(telemetry: AgentTelemetry, args: unknown): string | undefined {
+	const serializer = telemetry.config.contentSerializer?.toolCallArguments;
+	if (serializer) return callContentSerializer(telemetry, "toolCallArguments", () => serializer(args));
+	return telemetry.contentCapture === "full" ? safeJson(args) : stringifyJsonAttribute(summarizeTelemetryValue(args));
+}
+
+function serializeToolCallResultForTelemetry(telemetry: AgentTelemetry, result: unknown): string | undefined {
+	const serializer = telemetry.config.contentSerializer?.toolCallResult;
+	if (serializer) return callContentSerializer(telemetry, "toolCallResult", () => serializer(result));
+	return telemetry.contentCapture === "full"
+		? safeJson(result)
+		: stringifyJsonAttribute(summarizeTelemetryValue(result));
+}
+
+/**
+ * Stamp the final response onto a chat span, fire the cost estimator hook,
+ * and end the span. No-op when `span` is undefined.
+ */
+export async function finishChatSpan(
+	telemetry: AgentTelemetry | undefined,
+	span: Span | undefined,
+	message: AssistantMessage,
+	options: {
+		readonly stepNumber: number;
+		readonly serviceTier?: ServiceTier;
+		readonly responseHeaders?: Readonly<Record<string, string>>;
+		readonly baseUrl?: string;
+	},
+): Promise<void> {
+	if (!span) return;
+	applyChatResponseAttributes(span, message);
+	applyUsageAttributes(span, message.usage);
+	applyGatewayAttributes(span, options.responseHeaders, options.baseUrl);
+	const cost = applyCostEstimate(telemetry, span, message, options.serviceTier, options.stepNumber);
+	if (telemetry) {
+		await emitChatUsage(telemetry, span, {
+			model: message.model,
+			provider: message.provider,
+			serviceTier: options.serviceTier,
+			stepNumber: options.stepNumber,
+			usage: message.usage,
+			applied: cost,
+			headers: options.responseHeaders,
+		}).catch(err => {
+			emitTelemetryWarning(telemetry, {
+				code: "on_chat_usage_failed",
+				message: "onChatUsage rejected; swallowing telemetry callback failure",
+				error: err,
+			});
+		});
+	}
+	if (telemetry && telemetry.contentCapture !== "none") {
+		applyContentCaptureForResponse(telemetry, span, message);
+	}
+	safeOnSpanEnd(telemetry, {
+		span,
+		kind: "chat",
+		model: undefined,
+		agent: normalizedTelemetryAgent(telemetry),
+		conversationId: telemetry?.conversationId,
+		stepNumber: options.stepNumber,
+	});
+	applyTerminalStatus(span, message.stopReason, message.errorMessage);
+	telemetry?.collector.endChat(span, message, cost);
+	span.end();
+}
+
+/**
+ * Record a chat that failed before producing a final `AssistantMessage`
+ * (e.g. the provider stream threw mid-iteration). Mirrors `finishChatSpan`'s
+ * span-end side effects and pushes a failed `ChatRecord` to the collector so
+ * the run summary still reflects the failed step.
+ */
+export function failChatSpan(
+	telemetry: AgentTelemetry | undefined,
+	span: Span | undefined,
+	options: {
+		readonly errorObject: unknown;
+		readonly errorType?: string;
+		readonly responseHeaders?: Readonly<Record<string, string>>;
+		readonly baseUrl?: string;
+	},
+): void {
+	if (!span) return;
+	applyGatewayAttributes(span, options.responseHeaders, options.baseUrl);
+	const err = options.errorObject;
+	if (err instanceof Error) {
+		span.recordException(err);
+		span.setAttribute(GenAIAttr.ErrorType, options.errorType ?? err.name ?? "Error");
+		span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+	} else {
+		span.setAttribute(GenAIAttr.ErrorType, options.errorType ?? "Error");
+		span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+	}
+	telemetry?.collector.failChat(span, {
+		errorType: options.errorType ?? (err instanceof Error ? err.name || "Error" : "Error"),
+	});
+	span.end();
+}
+
+function applyChatResponseAttributes(span: Span, message: AssistantMessage): void {
+	span.setAttribute(GenAIAttr.ResponseModel, message.model);
+	if (message.responseId) span.setAttribute(GenAIAttr.ResponseId, message.responseId);
+	if (message.ttft != null) span.setAttribute(GenAIAttr.ResponseTimeToFirstChunk, message.ttft / 1000);
+	const finishReason = mapStopReason(message.stopReason);
+	if (finishReason) span.setAttribute(GenAIAttr.ResponseFinishReasons, [finishReason]);
+}
+
+function applyUsageAttributes(span: Span, usage: Usage | undefined): void {
+	if (!usage) return;
+	const cacheReadTokens = usage.cacheRead ?? 0;
+	const cacheCreationTokens = usage.cacheWrite ?? 0;
+	const inputTokens = (usage.input ?? 0) + cacheReadTokens + cacheCreationTokens;
+	const outputTokens = usage.output ?? 0;
+	span.setAttribute(GenAIAttr.UsageInputTokens, inputTokens);
+	span.setAttribute(GenAIAttr.UsageOutputTokens, outputTokens);
+	const total = usage.totalTokens ?? inputTokens + outputTokens;
+	span.setAttribute(PiGenAIAttr.UsageTotalTokens, total);
+	if (usage.cacheRead != null) span.setAttribute(GenAIAttr.UsageCacheReadInputTokens, usage.cacheRead);
+	if (usage.cacheWrite != null) span.setAttribute(GenAIAttr.UsageCacheCreationInputTokens, usage.cacheWrite);
+	if (usage.reasoningTokens != null) {
+		span.setAttribute(GenAIAttr.UsageReasoningOutputTokens, usage.reasoningTokens);
+	}
+	if (usage.server) {
+		const sums = (usage.server.webSearch ?? 0) + (usage.server.webFetch ?? 0);
+		if (sums > 0) span.setAttribute(PiGenAIAttr.UsageServerSideTools, sums);
+	}
+}
+
+/**
+ * Result of {@link detectGatewayFromHeaders}. `callId` and `routedTo` are
+ * populated only when the gateway surfaces them; consumers should treat
+ * `undefined` as "unknown for this gateway" rather than "no value".
+ */
+export interface GatewayHeaderDetection {
+	readonly name: string;
+	readonly callId: string | undefined;
+	readonly routedTo: string | undefined;
+}
+
+/**
+ * Identify a known LLM gateway / proxy from response headers (LiteLLM,
+ * Helicone, Portkey). Returns `undefined` when no recognizable pattern is
+ * present so direct-API traffic stays unaffected.
+ *
+ * Header keys are matched case-insensitively against the lowercased map that
+ * {@link ProviderResponseMetadata.headers} produces.
+ */
+export function detectGatewayFromHeaders(
+	headers: Readonly<Record<string, string>> | undefined,
+): GatewayHeaderDetection | undefined {
+	if (!headers) return undefined;
+	const litellmCallId = headers["x-litellm-call-id"];
+	if (litellmCallId) {
+		return {
+			name: "litellm",
+			callId: litellmCallId,
+			routedTo: headers["x-litellm-model-id"] ?? headers["x-litellm-model-group"],
+		};
+	}
+	const heliconeId = headers["helicone-id"];
+	if (heliconeId) {
+		return { name: "helicone", callId: heliconeId, routedTo: headers["helicone-target-provider"] };
+	}
+	const portkeyId = headers["x-portkey-trace-id"] ?? headers["x-portkey-request-id"];
+	if (portkeyId) {
+		return {
+			name: "portkey",
+			callId: portkeyId,
+			routedTo: headers["x-portkey-llm-provider"] ?? headers["x-portkey-provider"],
+		};
+	}
+	const openRouterGenerationId = headers["x-generation-id"];
+	if (openRouterGenerationId?.startsWith("gen-")) {
+		// OpenRouter does not surface the upstream provider in response headers
+		// (only the body's `provider` field carries it), so `routedTo` is left
+		// undefined here. The `gen-` prefix on `x-generation-id` is OpenRouter-
+		// specific and disambiguates from other proxies that also expose a
+		// `x-generation-id` header.
+		return { name: "openrouter", callId: openRouterGenerationId, routedTo: undefined };
+	}
+	return undefined;
+}
+
+function applyGatewayAttributes(
+	span: Span,
+	headers: Readonly<Record<string, string>> | undefined,
+	baseUrl: string | undefined,
+): void {
+	const gateway = detectGatewayFromHeaders(headers);
+	if (!gateway) return;
+	span.setAttribute(PiGenAIAttr.GatewayName, gateway.name);
+	if (baseUrl) span.setAttribute(PiGenAIAttr.GatewayEndpoint, baseUrl);
+	if (gateway.callId) span.setAttribute(PiGenAIAttr.GatewayCallId, gateway.callId);
+	if (gateway.routedTo) span.setAttribute(PiGenAIAttr.GatewayRoutedTo, gateway.routedTo);
+}
+
+interface AppliedCostEstimate {
+	readonly costUsd: number | undefined;
+	readonly inputUsd: number | undefined;
+	readonly outputUsd: number | undefined;
+	readonly costUnavailableReason: string | undefined;
+}
+
+function applyCostEstimate(
+	telemetry: AgentTelemetry | undefined,
+	span: Span,
+	message: AssistantMessage,
+	serviceTier: ServiceTier | undefined,
+	stepNumber: number | undefined,
+): AppliedCostEstimate {
+	if (!telemetry) return EMPTY_COST;
+	return applyCostEstimateForUsage(telemetry, span, {
+		model: message.model,
+		provider: message.provider,
+		serviceTier,
+		stepNumber,
+		usage: message.usage,
+	});
+}
+
+function applyCostEstimateForUsage(
+	telemetry: AgentTelemetry,
+	span: Span,
+	input: {
+		readonly model: string;
+		readonly provider: string | undefined;
+		readonly serviceTier: ServiceTier | undefined;
+		readonly stepNumber: number | undefined;
+		readonly usage: Usage | undefined;
+	},
+): AppliedCostEstimate {
+	const estimator = telemetry.config.costEstimator;
+	if (!estimator || !input.usage) return EMPTY_COST;
+	const provider = normalizeProviderName(telemetry, input.provider);
+	if (!provider) return EMPTY_COST;
+	const usage = buildUsageSnapshot(input.usage);
+	let result: CostEstimate | undefined;
+	try {
+		result = estimator({
+			provider,
+			model: input.model,
+			serviceTier: input.serviceTier,
+			usage,
+		});
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "cost_estimator_failed",
+			message: "costEstimator threw; omitting cost telemetry",
+			error: err,
+		});
+		return EMPTY_COST;
+	}
+	if (!result) return EMPTY_COST;
+	if ("unavailable" in result) {
+		span.setAttribute(PiGenAIAttr.CostUnavailableReason, result.unavailable);
+		const cost: AppliedCostEstimate = {
+			costUsd: undefined,
+			inputUsd: undefined,
+			outputUsd: undefined,
+			costUnavailableReason: result.unavailable,
+		};
+		emitCostDelta(telemetry, {
+			agent: normalizedTelemetryAgent(telemetry),
+			conversationId: telemetry.conversationId,
+			costUsd: undefined,
+			costUnavailableReason: result.unavailable,
+			inputUsd: undefined,
+			model: input.model,
+			outputUsd: undefined,
+			provider,
+			serviceTier: input.serviceTier,
+			stepNumber: input.stepNumber,
+			usage,
+		});
+		return cost;
+	}
+	span.setAttribute(PiGenAIAttr.CostEstimatedUsd, result.usd);
+	if (result.inputUsd != null) span.setAttribute(PiGenAIAttr.CostInputUsd, result.inputUsd);
+	if (result.outputUsd != null) span.setAttribute(PiGenAIAttr.CostOutputUsd, result.outputUsd);
+	const cost: AppliedCostEstimate = {
+		costUsd: result.usd,
+		inputUsd: result.inputUsd,
+		outputUsd: result.outputUsd,
+		costUnavailableReason: undefined,
+	};
+	emitCostDelta(telemetry, {
+		agent: normalizedTelemetryAgent(telemetry),
+		conversationId: telemetry.conversationId,
+		costUsd: result.usd,
+		costUnavailableReason: undefined,
+		inputUsd: result.inputUsd,
+		model: input.model,
+		outputUsd: result.outputUsd,
+		provider,
+		serviceTier: input.serviceTier,
+		stepNumber: input.stepNumber,
+		usage,
+	});
+	return cost;
+}
+
+function buildUsageSnapshot(usage: Usage): ChatUsageSnapshot {
+	return {
+		inputTokens: (usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0),
+		outputTokens: usage.output ?? 0,
+		totalTokens:
+			usage.totalTokens ??
+			(usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0) + (usage.output ?? 0),
+		cachedInputTokens: usage.cacheRead,
+		cacheWriteTokens: usage.cacheWrite,
+		reasoningOutputTokens: usage.reasoningTokens,
+	};
+}
+
+function emitCostDelta(telemetry: AgentTelemetry, delta: CostDelta): void {
+	const hook = telemetry.config.onCostDelta;
+	if (!hook) return;
+	try {
+		hook(delta);
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "on_cost_delta_failed",
+			message: "onCostDelta threw; swallowing telemetry callback failure",
+			error: err,
+		});
+	}
+}
+
+async function emitChatUsage(
+	telemetry: AgentTelemetry,
+	span: Span,
+	input: {
+		readonly model: string;
+		readonly provider: string | undefined;
+		readonly serviceTier: ServiceTier | undefined;
+		readonly stepNumber: number | undefined;
+		readonly usage: Usage | undefined;
+		readonly applied: AppliedCostEstimate;
+		readonly headers: Readonly<Record<string, string>> | undefined;
+	},
+): Promise<void> {
+	const hook = telemetry.config.onChatUsage;
+	if (!hook || !input.usage) return;
+	const event: ChatUsageEvent = {
+		span,
+		agent: normalizedTelemetryAgent(telemetry),
+		conversationId: telemetry.conversationId,
+		stepNumber: input.stepNumber,
+		model: input.model,
+		provider: normalizeProviderName(telemetry, input.provider),
+		serviceTier: input.serviceTier,
+		usage: buildUsageSnapshot(input.usage),
+		cost: costEstimateFromApplied(input.applied),
+		attributes: resolveDynamicAttributes(
+			telemetry,
+			buildTelemetryAttributeContext(telemetry, "chat", { stepNumber: input.stepNumber }),
+		),
+		headers: input.headers,
+	};
+	try {
+		await hook(event);
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "on_chat_usage_failed",
+			message: "onChatUsage threw; swallowing telemetry callback failure",
+			error: err,
+		});
+	}
+}
+
+function costEstimateFromApplied(applied: AppliedCostEstimate): CostEstimate | undefined {
+	if (applied.costUsd != null) {
+		return { usd: applied.costUsd, inputUsd: applied.inputUsd, outputUsd: applied.outputUsd };
+	}
+	if (applied.costUnavailableReason != null) {
+		return { unavailable: applied.costUnavailableReason };
+	}
+	return undefined;
+}
+
+const EMPTY_COST: AppliedCostEstimate = Object.freeze({
+	costUsd: undefined,
+	inputUsd: undefined,
+	outputUsd: undefined,
+	costUnavailableReason: undefined,
+});
+
+function mapStopReason(reason: StopReason | undefined): string | undefined {
+	switch (reason) {
+		case "stop":
+			return "stop";
+		case "length":
+			return "length";
+		case "toolUse":
+			return "tool_calls";
+		case "error":
+		case "aborted":
+			return "error";
+		default:
+			return undefined;
+	}
+}
+
+function applyTerminalStatus(span: Span, stopReason: StopReason | undefined, errorMessage: string | undefined): void {
+	if (stopReason === "error" || stopReason === "aborted") {
+		span.setAttribute(GenAIAttr.ErrorType, stopReason);
+		span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage ?? stopReason });
+	}
+}
+
+export interface ManualChatToolCallTelemetry {
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly input?: unknown;
+}
+
+export interface ManualChatTelemetryOptions {
+	readonly span?: Span;
+	readonly parent?: Span;
+	readonly model: Model;
+	readonly usage?: Usage;
+	readonly finishReason?: StopReason;
+	readonly serviceTier?: ServiceTier;
+	readonly stepNumber?: number;
+	readonly responseId?: string;
+	readonly responseModel?: string;
+	readonly responseText?: string;
+	readonly responseToolCalls?: readonly ManualChatToolCallTelemetry[];
+	readonly attributes?: Attributes;
+	readonly responseHeaders?: Readonly<Record<string, string>>;
+	readonly endSpan?: boolean;
+}
+
+export async function recordManualChatTelemetry(
+	telemetry: AgentTelemetry | undefined,
+	options: ManualChatTelemetryOptions,
+): Promise<Span | undefined> {
+	const span =
+		options.span ??
+		startSpan(telemetry, "chat", `chat ${options.model.id}`, {
+			spanKind: SpanKind.CLIENT,
+			model: options.model,
+			parent: options.parent,
+			stepNumber: options.stepNumber,
+			attributes: options.attributes,
+		});
+	if (!span) return undefined;
+	if (options.span && options.attributes) span.setAttributes(options.attributes);
+	if (options.stepNumber != null) span.setAttribute(PiGenAIAttr.AgentStepNumber, options.stepNumber);
+	span.setAttribute(GenAIAttr.ResponseModel, options.responseModel ?? options.model.name);
+	if (options.responseId) span.setAttribute(GenAIAttr.ResponseId, options.responseId);
+	const finishReason = mapStopReason(options.finishReason);
+	if (finishReason) span.setAttribute(GenAIAttr.ResponseFinishReasons, [finishReason]);
+	applyUsageAttributes(span, options.usage);
+	applyGatewayAttributes(span, options.responseHeaders, options.model.baseUrl);
+	if (telemetry) {
+		const applied = applyCostEstimateForUsage(telemetry, span, {
+			model: options.responseModel ?? options.model.id,
+			provider: options.model.provider,
+			serviceTier: options.serviceTier,
+			stepNumber: options.stepNumber,
+			usage: options.usage,
+		});
+		await emitChatUsage(telemetry, span, {
+			model: options.responseModel ?? options.model.id,
+			provider: options.model.provider,
+			serviceTier: options.serviceTier,
+			stepNumber: options.stepNumber,
+			usage: options.usage,
+			applied,
+			headers: options.responseHeaders,
+		}).catch(err => {
+			emitTelemetryWarning(telemetry, {
+				code: "on_chat_usage_failed",
+				message: "onChatUsage rejected; swallowing telemetry callback failure",
+				error: err,
+			});
+		});
+	}
+	if (options.responseText) {
+		const responseText = stringifyJsonAttribute(summarizeTelemetryTexts([options.responseText]));
+		if (responseText) span.setAttribute(PiGenAIAttr.ResponseText, responseText);
+	}
+	if (options.responseToolCalls && options.responseToolCalls.length > 0) {
+		const calls = options.responseToolCalls.map(call => ({
+			toolCallId: call.toolCallId,
+			toolName: call.toolName,
+			input: summarizeTelemetryValue(call.input),
+		}));
+		const responseToolCalls = stringifyJsonAttribute(limitTelemetryToolCalls(calls));
+		if (responseToolCalls) span.setAttribute(PiGenAIAttr.ResponseToolCalls, responseToolCalls);
+	}
+	applyTerminalStatus(span, options.finishReason, undefined);
+	if (options.endSpan ?? options.span === undefined) span.end();
+	return span;
+}
+
+/**
+ * Options accepted by {@link instrumentedCompleteSimple}. Mirrors the
+ * `streamAssistantResponse` chat-span lifecycle for oneshot LLM calls
+ * (compaction summaries, handoff document, branch summary, inspect_image).
+ */
+export interface InstrumentedChatSpanOptions {
+	readonly telemetry: AgentTelemetry | undefined;
+	/** Optional explicit parent span. Defaults to `context.active()`. */
+	readonly parent?: Span;
+	/** Step index recorded on the span; defaults to `-1` for non-loop calls. */
+	readonly stepNumber?: number;
+	/**
+	 * Tag stamped onto `pi.gen_ai.oneshot.kind`. Values used by the agent:
+	 * `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`,
+	 * `handoff`, `branch_summary`, `inspect_image`. Free-form to allow callers
+	 * outside this package to add new kinds without bumping the helper.
+	 */
+	readonly oneshotKind?: string;
+	/** Extra span attributes applied verbatim. */
+	readonly attributes?: Attributes;
+	/**
+	 * Override for the underlying {@link completeSimple} call. Defaults to
+	 * `completeSimple` from `@gajae-code/ai`. Use to retain a test injection
+	 * seam while still going through the chat-span lifecycle.
+	 */
+	readonly completeImpl?: <TApi extends Api>(
+		model: Model<TApi>,
+		ctx: Context,
+		options: SimpleStreamOptions,
+	) => Promise<AssistantMessage>;
+}
+
+/**
+ * Wrap a {@link completeSimple} round-trip with the same chat-span lifecycle
+ * the agent loop uses for streamed turns: `startChatSpan` → run inside the
+ * active span → `finishChatSpan` on success, `failChatSpan` on throw.
+ *
+ * Short-circuits when `telemetry` is `undefined` so cost / overhead stays at
+ * zero for installations without an OTEL SDK.
+ */
+export async function instrumentedCompleteSimple<TApi extends Api>(
+	model: Model<TApi>,
+	ctx: Context,
+	options: SimpleStreamOptions,
+	span: InstrumentedChatSpanOptions,
+): Promise<AssistantMessage> {
+	const { telemetry, parent, oneshotKind } = span;
+	const stepNumber = span.stepNumber ?? -1;
+	const reasoning = options.reasoning;
+	const chatSpan = startChatSpan(telemetry, model, {
+		parent,
+		stepNumber,
+		request: {
+			maxTokens: options.maxTokens,
+			temperature: options.temperature,
+			topP: options.topP,
+			topK: options.topK,
+			presencePenalty: options.presencePenalty,
+			serviceTier: options.serviceTier,
+			reasoningEffort: typeof reasoning === "string" ? reasoning : undefined,
+			toolChoice: options.toolChoice,
+			tools: ctx.tools,
+			systemPrompt: ctx.systemPrompt,
+			messages: ctx.messages,
+		},
+	});
+	if (chatSpan) {
+		if (oneshotKind) chatSpan.setAttribute(PiGenAIAttr.OneshotKind, oneshotKind);
+		if (span.attributes) chatSpan.setAttributes(span.attributes);
+	}
+
+	// Wrap the user-supplied onResponse so we always capture response headers
+	// for the cost / gateway hooks without stealing them from the caller.
+	let capturedHeaders: Readonly<Record<string, string>> | undefined;
+	const userOnResponse = options.onResponse;
+	const captureOnResponse: NonNullable<SimpleStreamOptions["onResponse"]> = (response, modelInfo) => {
+		capturedHeaders = response.headers;
+		return userOnResponse?.(response, modelInfo);
+	};
+
+	try {
+		return await runInActiveSpan(chatSpan, async () => {
+			const complete = span.completeImpl ?? completeSimple;
+			const message = await complete(model, ctx, {
+				...options,
+				onResponse: captureOnResponse,
+			});
+			await finishChatSpan(telemetry, chatSpan, message, {
+				stepNumber,
+				serviceTier: options.serviceTier,
+				responseHeaders: capturedHeaders,
+				baseUrl: model.baseUrl,
+			});
+			return message;
+		});
+	} catch (err) {
+		failChatSpan(telemetry, chatSpan, {
+			errorObject: err,
+			responseHeaders: capturedHeaders,
+			baseUrl: model.baseUrl,
+		});
+		throw err;
+	}
+}
+
+/**
+ * Start an `execute_tool` span representing one tool invocation. Parented
+ * under the supplied `invoke_agent` span by default — pass `parent` to
+ * override.
+ */
+export function startExecuteToolSpan(
+	telemetry: AgentTelemetry | undefined,
+	options: {
+		readonly tool: AgentTool | undefined;
+		readonly toolName: string;
+		readonly toolCallId: string;
+		readonly args: unknown;
+		readonly parent?: Span;
+	},
+): Span | undefined {
+	const attrs: Attributes = {
+		[GenAIAttr.ToolName]: options.toolName,
+		[GenAIAttr.ToolCallId]: options.toolCallId,
+		[GenAIAttr.ToolType]: "function",
+	};
+	if (options.tool?.description) attrs[GenAIAttr.ToolDescription] = options.tool.description;
+	const span = startSpan(telemetry, "execute_tool", `execute_tool ${options.toolName}`, {
+		spanKind: SpanKind.INTERNAL,
+		parent: options.parent,
+		toolCallId: options.toolCallId,
+		toolName: options.toolName,
+		attributes: attrs,
+	});
+	if (span) {
+		telemetry?.collector.beginTool(span, { toolCallId: options.toolCallId, toolName: options.toolName });
+		if (telemetry && telemetry.contentCapture !== "none") {
+			const args = serializeToolCallArgumentsForTelemetry(telemetry, options.args);
+			if (args) span.setAttribute(GenAIAttr.ToolCallArguments, args);
+		}
+	}
+	return span;
+}
+
+/**
+ * End an `execute_tool` span. Pass `status` to specify the terminal status
+ * explicitly (`"ok" | "error" | "skipped" | "blocked" | "timeout" |
+ * "aborted"`); when omitted, `status` is derived from `isError`. Passing
+ * `errorObject` (the thrown value) additionally records an exception with
+ * stack.
+ */
+export function finishExecuteToolSpan(
+	telemetry: AgentTelemetry | undefined,
+	span: Span | undefined,
+	options: {
+		readonly result?: unknown;
+		readonly isError: boolean;
+		readonly status?: ToolStatus;
+		readonly errorMessage?: string;
+		readonly errorObject?: unknown;
+		readonly toolCallId: string;
+		readonly toolName: string;
+	},
+): void {
+	if (!span) return;
+	if (telemetry && telemetry.contentCapture !== "none" && options.result !== undefined) {
+		const result = serializeToolCallResultForTelemetry(telemetry, options.result);
+		if (result) span.setAttribute(GenAIAttr.ToolCallResult, result);
+	}
+	safeOnSpanEnd(telemetry, {
+		span,
+		kind: "execute_tool",
+		model: undefined,
+		agent: normalizedTelemetryAgent(telemetry),
+		conversationId: telemetry?.conversationId,
+		toolCallId: options.toolCallId,
+		toolName: options.toolName,
+	});
+	const status: ToolStatus = options.status ?? (options.isError ? "error" : "ok");
+	let errorType: string | undefined;
+	// `status` is the source of truth for the wire-level `error.type`. The
+	// underlying `errorObject` (if any) still gets a `recordException` so the
+	// stack trace is preserved, but the attribute reflects the run-level
+	// category (`tool_blocked`, `tool_aborted`, …) instead of the JS class
+	// name. This keeps dashboards groupable on one column.
+	if (status !== "ok") {
+		errorType =
+			status === "error" && options.errorObject instanceof Error
+				? options.errorObject.name || "Error"
+				: STATUS_ERROR_TYPE[status];
+		span.setAttribute(GenAIAttr.ErrorType, errorType);
+		span.setAttribute(EXECUTE_TOOL_STATUS_ATTR, status);
+		const msg =
+			options.errorObject instanceof Error ? options.errorObject.message : (options.errorMessage ?? errorType);
+		span.setStatus({ code: SpanStatusCode.ERROR, message: msg });
+	} else {
+		span.setAttribute(EXECUTE_TOOL_STATUS_ATTR, status);
+	}
+	if (options.errorObject instanceof Error) {
+		span.recordException(options.errorObject);
+	}
+	telemetry?.collector.endTool(span, { status, errorType });
+	span.end();
+}
+
+/** Span attribute carrying the terminal {@link ToolStatus}. */
+export const EXECUTE_TOOL_STATUS_ATTR = PiGenAIAttr.ToolStatus;
+
+/**
+ * Mapping from non-ok {@link ToolStatus} values to the `error.type` attribute
+ * string written on the span when no thrown error is available. The wire
+ * format intentionally matches the status string so dashboards can group on
+ * one column.
+ */
+const STATUS_ERROR_TYPE: Record<Exclude<ToolStatus, "ok">, string> = {
+	error: "tool_error",
+	skipped: "tool_skipped",
+	blocked: "tool_blocked",
+	timeout: "tool_timeout",
+	aborted: "tool_aborted",
+};
+
+/**
+ * Record a tool that bypassed the span lifecycle entirely (pre-run
+ * interrupt, post-execution tail sweep for calls that never produced a
+ * result message). The LLM still asked for the tool, so it counts toward
+ * coverage and toward the relevant `tools.<status>` counter; no span is
+ * emitted because the loop never started one.
+ */
+export function recordSkippedTool(
+	telemetry: AgentTelemetry | undefined,
+	options: {
+		readonly toolCallId: string;
+		readonly toolName: string;
+		readonly status: Extract<ToolStatus, "skipped" | "aborted" | "error">;
+	},
+): void {
+	telemetry?.collector.recordOrphanTool(options);
+}
+
+/**
+ * End an `invoke_agent` span. Snapshots the run collector, stamps aggregate
+ * `gen_ai.agent.*` attributes on the span, fires the non-fatal
+ * {@link AgentTelemetryConfig.onRunEnd} hook, then records any uncaught
+ * error and ends the span.
+ */
+export function finishInvokeAgentSpan(
+	telemetry: AgentTelemetry | undefined,
+	span: Span | undefined,
+	options: { readonly stepCount: number; readonly errorObject?: unknown },
+): { readonly summary: AgentRunSummary; readonly coverage: AgentRunCoverage } | undefined {
+	if (!span) return undefined;
+	applyInvokeAgentFinish(span, options.stepCount);
+	let snapshot: { readonly summary: AgentRunSummary; readonly coverage: AgentRunCoverage } | undefined;
+	if (telemetry) {
+		snapshot = telemetry.collector.snapshot({ stepCount: options.stepCount });
+		applyAggregateAttributes(span, snapshot.summary, snapshot.coverage);
+	}
+	safeOnSpanEnd(telemetry, {
+		span,
+		kind: "invoke_agent",
+		model: undefined,
+		agent: normalizedTelemetryAgent(telemetry),
+		conversationId: telemetry?.conversationId,
+	});
+	if (telemetry && snapshot && telemetry.collector.markRunEnded()) {
+		fireOnRunEnd(telemetry, snapshot.summary, snapshot.coverage);
+	}
+	if (options.errorObject instanceof Error) {
+		span.recordException(options.errorObject);
+		span.setAttribute(GenAIAttr.ErrorType, options.errorObject.name || "Error");
+		span.setStatus({ code: SpanStatusCode.ERROR, message: options.errorObject.message });
+	}
+	span.end();
+	return snapshot;
+}
+
+/**
+ * Invoke {@link AgentTelemetryConfig.onRunEnd} on `telemetry` if set. Throws
+ are caught and logged via `console.warn` — telemetry callbacks NEVER turn a
+ * successful agent run into a failed one. Idempotent at the call site via
+ * {@link AgentRunCollector.markRunEnded}; callers must check that before
+ * calling this helper.
+ */
+export function fireOnRunEnd(telemetry: AgentTelemetry, summary: AgentRunSummary, coverage: AgentRunCoverage): void {
+	const hook = telemetry.config.onRunEnd;
+	if (!hook) return;
+	try {
+		hook(summary, coverage);
+	} catch (err) {
+		emitTelemetryWarning(telemetry, {
+			code: "on_run_end_failed",
+			message: "onRunEnd threw; swallowing telemetry callback failure",
+			error: err,
+		});
+	}
+}
+
+/** Aggregate `pi.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
+export const enum PiGenAIAggregateAttr {
+	ChatsCount = "pi.gen_ai.agent.chats.count",
+	ChatsTotalLatencyMs = "pi.gen_ai.agent.chats.total_latency_ms",
+	ChatsStopReasonPrefix = "pi.gen_ai.agent.chats.stop_reason.",
+	ToolsCount = "pi.gen_ai.agent.tools.count",
+	ToolsOkCount = "pi.gen_ai.agent.tools.ok.count",
+	ToolsErrorCount = "pi.gen_ai.agent.tools.error.count",
+	ToolsSkippedCount = "pi.gen_ai.agent.tools.skipped.count",
+	ToolsBlockedCount = "pi.gen_ai.agent.tools.blocked.count",
+	ToolsTimeoutCount = "pi.gen_ai.agent.tools.timeout.count",
+	ToolsAbortedCount = "pi.gen_ai.agent.tools.aborted.count",
+	ToolsTotalLatencyMs = "pi.gen_ai.agent.tools.total_latency_ms",
+	ToolsInvoked = "pi.gen_ai.agent.tools.invoked",
+	ToolsAvailable = "pi.gen_ai.agent.tools.available",
+	ToolsUnused = "pi.gen_ai.agent.tools.unused",
+	UsageInputTokensTotal = "pi.gen_ai.agent.usage.input_tokens.total",
+	UsageOutputTokensTotal = "pi.gen_ai.agent.usage.output_tokens.total",
+	UsageCacheReadInputTokensTotal = "pi.gen_ai.agent.usage.cache_read.input_tokens.total",
+	UsageCacheCreationInputTokensTotal = "pi.gen_ai.agent.usage.cache_creation.input_tokens.total",
+	UsageReasoningOutputTokensTotal = "pi.gen_ai.agent.usage.reasoning.output_tokens.total",
+	UsageTotalTokensTotal = "pi.gen_ai.agent.usage.total_tokens.total",
+	CostEstimatedUsdTotal = "pi.gen_ai.agent.cost.estimated_usd.total",
+	ErrorsCount = "pi.gen_ai.agent.errors.count",
+}
+
+/** Stamp the aggregate `pi.gen_ai.agent.*` attributes on the given span. */
+function applyAggregateAttributes(span: Span, summary: AgentRunSummary, coverage: AgentRunCoverage): void {
+	span.setAttribute(PiGenAIAggregateAttr.ChatsCount, summary.chats.total);
+	span.setAttribute(PiGenAIAggregateAttr.ChatsTotalLatencyMs, summary.chats.totalLatencyMs);
+	for (const [reason, count] of Object.entries(summary.chats.byStopReason)) {
+		span.setAttribute(`${PiGenAIAggregateAttr.ChatsStopReasonPrefix}${reason}.count`, count);
+	}
+	span.setAttribute(PiGenAIAggregateAttr.ToolsCount, summary.tools.total);
+	span.setAttribute(PiGenAIAggregateAttr.ToolsOkCount, summary.tools.ok);
+	span.setAttribute(PiGenAIAggregateAttr.ToolsErrorCount, summary.tools.error);
+	span.setAttribute(PiGenAIAggregateAttr.ToolsSkippedCount, summary.tools.skipped);
+	span.setAttribute(PiGenAIAggregateAttr.ToolsBlockedCount, summary.tools.blocked);
+	span.setAttribute(PiGenAIAggregateAttr.ToolsTimeoutCount, summary.tools.timeout);
+	span.setAttribute(PiGenAIAggregateAttr.ToolsAbortedCount, summary.tools.aborted);
+	span.setAttribute(PiGenAIAggregateAttr.ToolsTotalLatencyMs, summary.tools.totalLatencyMs);
+	if (coverage.toolsInvoked.length > 0) {
+		span.setAttribute(PiGenAIAggregateAttr.ToolsInvoked, [...coverage.toolsInvoked]);
+	}
+	if (coverage.toolsAvailable.length > 0) {
+		span.setAttribute(PiGenAIAggregateAttr.ToolsAvailable, [...coverage.toolsAvailable]);
+	}
+	if (coverage.toolsUnused.length > 0) {
+		span.setAttribute(PiGenAIAggregateAttr.ToolsUnused, [...coverage.toolsUnused]);
+	}
+	span.setAttribute(PiGenAIAggregateAttr.UsageInputTokensTotal, summary.usage.inputTokens);
+	span.setAttribute(PiGenAIAggregateAttr.UsageOutputTokensTotal, summary.usage.outputTokens);
+	span.setAttribute(PiGenAIAggregateAttr.UsageCacheReadInputTokensTotal, summary.usage.cachedInputTokens);
+	span.setAttribute(PiGenAIAggregateAttr.UsageCacheCreationInputTokensTotal, summary.usage.cacheWriteTokens);
+	span.setAttribute(PiGenAIAggregateAttr.UsageReasoningOutputTokensTotal, summary.usage.reasoningOutputTokens);
+	span.setAttribute(PiGenAIAggregateAttr.UsageTotalTokensTotal, summary.usage.totalTokens);
+	if (summary.cost.estimatedUsd > 0) {
+		span.setAttribute(PiGenAIAggregateAttr.CostEstimatedUsdTotal, summary.cost.estimatedUsd);
+	}
+	span.setAttribute(PiGenAIAggregateAttr.ErrorsCount, summary.errors.total);
+}
+
+/**
+ * Run `fn` with `span` activated on the OTEL context. Spans created
+ * downstream (provider HTTP clients, MCP tools, user code) attach as
+ * children. No-op when `span` is undefined.
+ *
+ * Required because `tracer.startSpan` creates the span object but does not
+ * activate it — without this wrapper, downstream spans attach to whatever
+ * context was active before and the parent linkage we advertise is lost.
+ */
+export function runInActiveSpan<T>(span: Span | undefined, fn: () => Promise<T>): Promise<T> {
+	if (!span) return fn();
+	return context.with(trace.setSpan(context.active(), span), fn);
+}
+
+/**
+ * Emit a one-shot `handoff` span describing a transition between two named
+ * agents. Pass `parent` to make the span a child of an in-flight
+ * invoke_agent span; otherwise the active context's span is used.
+ */
+export function recordHandoff(
+	telemetry: AgentTelemetry | undefined,
+	options: {
+		readonly fromAgent: AgentIdentity | undefined;
+		readonly toAgent: AgentIdentity;
+		readonly parent?: Span;
+		readonly attributes?: Attributes;
+	},
+): void {
+	if (!telemetry) return;
+	const attrs: Attributes = {};
+	const fromAgent = options.fromAgent ? normalizeAgentIdentity(telemetry, options.fromAgent) : undefined;
+	const toAgent = normalizeAgentIdentity(telemetry, options.toAgent);
+	if (fromAgent?.name) attrs[PiGenAIAttr.HandoffFromAgentName] = fromAgent.name;
+	if (fromAgent?.id) attrs[PiGenAIAttr.HandoffFromAgentId] = fromAgent.id;
+	if (toAgent.name) attrs[PiGenAIAttr.HandoffToAgentName] = toAgent.name;
+	if (toAgent.id) attrs[PiGenAIAttr.HandoffToAgentId] = toAgent.id;
+	const name = toAgent.name
+		? fromAgent?.name
+			? `handoff ${fromAgent.name} → ${toAgent.name}`
+			: `handoff to ${toAgent.name}`
+		: "handoff";
+	const span = startSpan(telemetry, "handoff", name, {
+		spanKind: SpanKind.INTERNAL,
+		parent: options.parent,
+		attributes: { ...attrs, ...options.attributes },
+	});
+	if (!span) return;
+	safeOnSpanEnd(telemetry, {
+		span,
+		kind: "handoff",
+		model: undefined,
+		agent: toAgent,
+		conversationId: telemetry.conversationId,
+	});
+	span.end();
+}
+
+/**
+ * Set a single attribute on a possibly-undefined span. Use when the caller
+ * needs to attach context outside the standard helpers without a branch.
+ */
+export function setSpanAttribute(span: Span | undefined, key: string, value: AttributeValue): void {
+	if (!span) return;
+	span.setAttribute(key, value);
+}
+
+/** Re-exports so consumers can write hooks without depending on @opentelemetry/api directly. */
+export { type Attributes, type Span, SpanKind, SpanStatusCode, type Tracer, trace };
+
+function safeJson(value: unknown): string {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}