zidane 5.4.1 → 5.4.3

package/dist/index.js

@@ -1,18 +1,1037 @@
-import { A as readStateKey, C as PERSISTENCE_PREVIEW_BYTES, D as resolvePersistDir, E as maybePersistToolResult, O as getReadState, S as PERSISTED_STUB_PREFIX, T as cleanupPersistedSession, _ as createSkillsReadTool, a as multiEdit, b as TOOL_USE_SKIPPED_MESSAGE, c as grep, g as createSkillsRunScriptTool, h as createSkillsUseTool, j as resolveReadStateMap, l as glob, n as createSpawnTool, p as createAgent, s as createInteractionTool, u as edit, v as INTERRUPT_MESSAGE_FOR_TOOL_USE, w as buildPersistedStub, x as validateToolArgs, y as SHELL_CASCADE_CANCEL_MESSAGE } from "./tools-PQH1Ge4M.js";
+import { C as PERSISTED_STUB_PREFIX, D as maybePersistToolResult, E as cleanupPersistedSession, M as resolveReadStateMap, O as resolvePersistDir, S as validateToolArgs, T as buildPersistedStub, _ as createSkillsReadTool, a as multiEdit, b as TOOL_USE_CANCELLED_MESSAGE, c as grep, g as createSkillsRunScriptTool, h as createSkillsUseTool, j as readStateKey, k as getReadState, l as glob, n as createSpawnTool, p as createAgent, s as createInteractionTool, u as edit, v as INTERRUPT_MESSAGE_FOR_TOOL_USE, w as PERSISTENCE_PREVIEW_BYTES, x as TOOL_USE_SKIPPED_MESSAGE, y as SHELL_CASCADE_CANCEL_MESSAGE } from "./tools-BK2vG9UX.js";
 import { n as createProcessContext, t as createSandboxContext } from "./contexts-BwiHIr2w.js";
-import { a as AgentToolPairingError, c as matchesContextExceeded, i as AgentToolNotAllowedError, l as toTypedError, n as AgentContextExceededError, o as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, r as AgentProviderError, s as errorMessage, t as AgentAbortedError } from "./errors-Byb0F8B9.js";
+import { a as AgentToolPairingError, c as matchesContextExceeded, i as AgentToolNotAllowedError, l as toTypedError, n as AgentContextExceededError, o as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, r as AgentProviderError, s as errorMessage, t as AgentAbortedError } from "./errors-CDwtPIMX.js";
 import { n as toolResultToText, t as toolOutputByteLength } from "./types-IcokUOyC.js";
-import { a as detectTurnInterruption, b as sanitizeToolSpecs, c as fromAnthropic, d as toOpenAI, f as OpenAICompatHttpError, g as openaiCompat, h as mapOAIFinishReason, i as autoDetectAndConvert, l as fromOpenAI, m as classifyOpenAICompatError, n as SYNTHETIC_TOOL_RESULT_PLACEHOLDER, o as ensureToolResultPairing, r as TOOL_USE_INTERRUPTED_MARKER, s as filterUnresolvedToolUses, t as ORPHANED_TOOL_RESULT_MARKER, u as toAnthropic, y as sanitizeToolSchema } from "./messages-D0xT979U.js";
-import { c as createMemoryMcpCredentialStore, i as resultToString, l as hasAuthorizationHeader, n as normalizeMcpBlocks, r as normalizeMcpServers, s as McpOAuthProvider, t as connectMcpServers } from "./mcp-DhmmJfxK.js";
-import { _ as validateResourcePath, a as discoverSkills, b as createSkillActivationState, f as IMPLICITLY_ALLOWED_SKILL_TOOLS, g as parseAllowedToolPattern, h as matchesAllowedTool, i as writeSkillsToDisk, l as parseSkillFile, m as isToolAllowedByUnion, n as resolveSkills, p as installAllowedToolsGate, r as writeSkillToDisk, t as interpolateShellCommands, u as buildCatalog, v as validateSkillForWrite, y as validateSkillName } from "./interpolate-ERgZUxgg.js";
-import { C as summaryToTurn, E as CompactPromptTooLongError, S as stripImagesFromTurns, T as CompactInvalidInputError, _ as buildTailCompactPrompt, a as selectFilesFromSession, b as anchorPreviewFor, c as BYTES_PER_TOKEN, d as BASE_INSTRUCTIONS, f as NO_TOOLS_PREAMBLE, g as buildFullCompactPrompt, h as buildFromCompactPrompt, i as selectFilesFromReadState, l as estimateTokens, m as buildCompactPrompt, n as startOAuthCallback, o as selectRecentFiles, p as TRAILER, r as buildPostCompactAttachments, s as compactConversation, t as loginMcpServer, u as utf8ByteLength, v as buildUpToCompactPrompt, w as truncateHeadForPtlRetry, x as sliceForCompaction, y as ANCHOR_PREVIEW_MAX_CHARS } from "./login-8c5C0FYq.js";
+import { a as detectTurnInterruption, b as sanitizeToolSpecs, c as fromAnthropic, d as toOpenAI, f as OpenAICompatHttpError, g as openaiCompat, h as mapOAIFinishReason, i as autoDetectAndConvert, l as fromOpenAI, m as classifyOpenAICompatError, n as SYNTHETIC_TOOL_RESULT_PLACEHOLDER, o as ensureToolResultPairing, r as TOOL_USE_INTERRUPTED_MARKER, s as filterUnresolvedToolUses, t as ORPHANED_TOOL_RESULT_MARKER, u as toAnthropic, y as sanitizeToolSchema } from "./messages-fTR19Ga6.js";
+import { c as createMemoryMcpCredentialStore, i as resultToString, l as hasAuthorizationHeader, n as normalizeMcpBlocks, r as normalizeMcpServers, s as McpOAuthProvider, t as connectMcpServers } from "./mcp-CNUbvbsy.js";
+import { _ as validateResourcePath, a as discoverSkills, b as createSkillActivationState, f as IMPLICITLY_ALLOWED_SKILL_TOOLS, g as parseAllowedToolPattern, h as matchesAllowedTool, i as writeSkillsToDisk, l as parseSkillFile, m as isToolAllowedByUnion, n as resolveSkills, p as installAllowedToolsGate, r as writeSkillToDisk, t as interpolateShellCommands, u as buildCatalog, v as validateSkillForWrite, y as validateSkillName } from "./interpolate-CmtjEyRJ.js";
+import { C as summaryToTurn, E as CompactPromptTooLongError, S as stripImagesFromTurns, T as CompactInvalidInputError, _ as buildTailCompactPrompt, a as selectFilesFromSession, b as anchorPreviewFor, c as BYTES_PER_TOKEN, d as BASE_INSTRUCTIONS, f as NO_TOOLS_PREAMBLE, g as buildFullCompactPrompt, h as buildFromCompactPrompt, i as selectFilesFromReadState, l as estimateTokens, m as buildCompactPrompt, n as startOAuthCallback, o as selectRecentFiles, p as TRAILER, r as buildPostCompactAttachments, s as compactConversation, t as loginMcpServer, u as utf8ByteLength, v as buildUpToCompactPrompt, w as truncateHeadForPtlRetry, x as sliceForCompaction, y as ANCHOR_PREVIEW_MAX_CHARS } from "./login-DxyAERe1.js";
 import { r as statsByModel, t as flattenTurns } from "./stats-DgOvY7wd.js";
-import { i as basic_default, n as definePreset, r as basicTools } from "./presets-Ck4VusTo.js";
-import { i as anthropic, n as openai, r as cerebras, t as openrouter } from "./providers-x3LZByR5.js";
-import { a as createFileMapStore, i as createMemoryStore, n as loadSession, r as createRemoteStore, t as createSession } from "./session-BHZwxmfr.js";
+import { i as basic_default, n as definePreset, r as basicTools } from "./presets-D9IbaI40.js";
+import { i as anthropic, n as openai, r as cerebras, t as openrouter } from "./providers-CEzRFYtS.js";
+import { a as createFileMapStore, i as createMemoryStore, n as loadSession, r as createRemoteStore, t as createSession } from "./session-kwsNnOmt.js";
 import { defineSkill } from "./skills.js";
+//#region src/logger.ts
+/**
+* Build a Logger from a sink. Stateless and cheap; create one per agent
+* (or per app) and use `.with()` to attach correlation ids per-call.
+*/
+function createLogger(sink, baseAttributes = {}) {
+	function emit(level, message, attrs) {
+		try {
+			sink.emit({
+				level,
+				timestamp: Date.now(),
+				message,
+				attrs: attrs ? {
+					...baseAttributes,
+					...attrs
+				} : { ...baseAttributes }
+			});
+		} catch {}
+	}
+	return {
+		debug: (m, a) => emit("debug", m, a),
+		info: (m, a) => emit("info", m, a),
+		warn: (m, a) => emit("warn", m, a),
+		error: (m, a) => emit("error", m, a),
+		with: (extra) => createLogger(sink, {
+			...baseAttributes,
+			...extra
+		}),
+		baseAttributes
+	};
+}
+const LEVEL_ORDER = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+/**
+* Human-readable terminal sink. Renders each record as
+* `<ISO timestamp> <LEVEL> <message> <attrs as kv pairs>`.
+*
+* Honors `process.stderr` by default so log lines don't interleave with
+* the agent's stdout-bound output (chat responses, JSON results).
+*/
+function consoleSink(options = {}) {
+	const min = LEVEL_ORDER[options.minLevel ?? "info"];
+	const stream = options.stream ?? process.stderr;
+	return { emit(record) {
+		if (LEVEL_ORDER[record.level] < min) return;
+		const ts = new Date(record.timestamp).toISOString();
+		const kv = Object.entries(record.attrs).filter(([, v]) => v !== void 0).map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ");
+		stream.write(`${ts} ${record.level.toUpperCase().padEnd(5)} ${record.message}${kv ? ` ${kv}` : ""}\n`);
+	} };
+}
+/**
+* One-JSON-object-per-line sink. Suitable for piping into log aggregators
+* (Datadog Agent, Fluent Bit, Loki, Vector) that expect JSONL.
+*/
+function jsonSink(options = {}) {
+	const min = LEVEL_ORDER[options.minLevel ?? "info"];
+	const stream = options.stream ?? process.stderr;
+	return { emit(record) {
+		if (LEVEL_ORDER[record.level] < min) return;
+		try {
+			stream.write(`${JSON.stringify(record)}\n`);
+		} catch {}
+	} };
+}
+/**
+* Install a bundle of hook handlers that emit a structured line per
+* relevant lifecycle event, automatically attaching correlation ids
+* (`runId`, `turnId`, `callId`, `childId`, `depth`, `agentName`).
+*
+* @example
+* ```ts
+* const logger = createLogger(consoleSink({ minLevel: 'debug' }), { service: 'tui' })
+* const lh = createLoggingHooks({ logger })
+* const uninstall = lh.install(agent.hooks)
+* try { await agent.run({ prompt }) }
+* finally { uninstall() }
+* ```
+*/
+function createLoggingHooks(options) {
+	const root = options.logger;
+	const includeLifecycle = options.includeLifecycle ?? true;
+	const minLevel = LEVEL_ORDER[options.level ?? "info"];
+	/**
+	* Wrap a Logger so emissions below `minLevel` are dropped before they
+	* hit the sink. Lets us gate harness chatter without forcing every
+	* `LogSink` to re-implement level filtering. Preserves `.with()`
+	* composition (children inherit the filter).
+	*/
+	function gateLevel(logger) {
+		const skip = (level) => LEVEL_ORDER[level] < minLevel;
+		const wrap = (l) => ({
+			debug: (m, a) => {
+				if (!skip("debug")) l.debug(m, a);
+			},
+			info: (m, a) => {
+				if (!skip("info")) l.info(m, a);
+			},
+			warn: (m, a) => {
+				if (!skip("warn")) l.warn(m, a);
+			},
+			error: (m, a) => {
+				if (!skip("error")) l.error(m, a);
+			},
+			with: (extra) => wrap(l.with(extra)),
+			baseAttributes: l.baseAttributes
+		});
+		return wrap(logger);
+	}
+	return { install(hooks) {
+		const unregisters = [];
+		const gatedRoot = gateLevel(root);
+		let runLogger = gatedRoot;
+		let turnLogger = gatedRoot;
+		unregisters.push(hooks.hook("agent:start", (ctx) => {
+			runLogger = gatedRoot.with({
+				runId: ctx.runId,
+				...ctx.parentRunId ? { parentRunId: ctx.parentRunId } : {},
+				depth: ctx.depth,
+				...ctx.agentName ? { agentName: ctx.agentName } : {}
+			});
+			turnLogger = runLogger;
+			if (includeLifecycle) runLogger.debug("agent run started");
+		}));
+		unregisters.push(hooks.hook("agent:done", (stats) => {
+			runLogger.info("agent run completed", {
+				turns: stats.turns,
+				totalIn: stats.totalIn,
+				totalOut: stats.totalOut,
+				...typeof stats.cost === "number" ? { cost: stats.cost } : {},
+				elapsedMs: stats.elapsed,
+				...typeof stats.timeTillFirstTokenMs === "number" ? { ttftMs: stats.timeTillFirstTokenMs } : {}
+			});
+		}));
+		unregisters.push(hooks.hook("agent:abort", () => {
+			runLogger.warn("agent run aborted");
+		}));
+		unregisters.push(hooks.hook("turn:before", (ctx) => {
+			turnLogger = runLogger.with({
+				turnId: ctx.turnId,
+				turn: ctx.turn
+			});
+			if (includeLifecycle) turnLogger.debug("turn started");
+		}));
+		unregisters.push(hooks.hook("turn:after", (ctx) => {
+			turnLogger.debug("turn ended", {
+				inputTokens: ctx.usage.input,
+				outputTokens: ctx.usage.output,
+				...ctx.usage.finishReason ? { finishReason: ctx.usage.finishReason } : {},
+				...ctx.usage.modelId ? { modelId: ctx.usage.modelId } : {},
+				...typeof ctx.usage.timeToFirstTokenMs === "number" ? { ttftMs: ctx.usage.timeToFirstTokenMs } : {}
+			});
+		}));
+		unregisters.push(hooks.hook("stream:error", (ctx) => {
+			turnLogger.error("stream error", {
+				message: ctx.err instanceof Error ? ctx.err.message : String(ctx.err),
+				...ctx.statusCode !== void 0 ? { statusCode: ctx.statusCode } : {},
+				...ctx.requestId !== void 0 ? { requestId: ctx.requestId } : {}
+			});
+		}));
+		unregisters.push(hooks.hook("tool:before", (ctx) => {
+			if (!includeLifecycle) return;
+			turnLogger.debug("tool started", {
+				toolName: ctx.name,
+				displayName: ctx.displayName,
+				callId: ctx.callId
+			});
+		}));
+		unregisters.push(hooks.hook("tool:after", (ctx) => {
+			if (!includeLifecycle) return;
+			turnLogger.debug("tool ended", {
+				toolName: ctx.name,
+				callId: ctx.callId,
+				outputBytes: ctx.outputBytes
+			});
+		}));
+		unregisters.push(hooks.hook("tool:error", (ctx) => {
+			turnLogger.error("tool error", {
+				toolName: ctx.name,
+				callId: ctx.callId,
+				message: ctx.error.message
+			});
+		}));
+		unregisters.push(hooks.hook("tool:dispatched", (ctx) => {
+			const isAnomaly = ctx.outcome === "gate-block" || ctx.outcome === "unknown" || ctx.outcome === "invalid-input";
+			if (!isAnomaly && !includeLifecycle) return;
+			turnLogger[isAnomaly ? "warn" : "debug"]("tool dispatched", {
+				toolName: ctx.name,
+				callId: ctx.callId,
+				outcome: ctx.outcome,
+				...ctx.reason ? { reason: ctx.reason } : {}
+			});
+		}));
+		unregisters.push(hooks.hook("validation:reject", (ctx) => {
+			turnLogger.warn("tool input rejected", {
+				toolName: ctx.name,
+				callId: ctx.callId,
+				reason: ctx.reason
+			});
+		}));
+		unregisters.push(hooks.hook("budget:exceeded", (ctx) => {
+			turnLogger.warn("byte budget exceeded", {
+				bytes: ctx.bytes,
+				budget: ctx.budget
+			});
+		}));
+		unregisters.push(hooks.hook("tool-budget:exceeded", (ctx) => {
+			turnLogger.warn("tool budget exceeded", {
+				toolName: ctx.tool,
+				count: ctx.count,
+				max: ctx.max,
+				mode: ctx.mode
+			});
+		}));
+		unregisters.push(hooks.hook("mcp:bootstrap:end", (ctx) => {
+			if (ctx.ok) {
+				if (includeLifecycle) runLogger.debug("mcp bootstrap ok", {
+					server: ctx.name,
+					transport: ctx.transport,
+					durationMs: ctx.durationMs,
+					toolCount: ctx.toolCount,
+					...ctx.lazy ? { lazy: true } : {},
+					...ctx.cached ? { cached: true } : {}
+				});
+			} else runLogger.warn("mcp bootstrap failed", {
+				server: ctx.name,
+				transport: ctx.transport,
+				durationMs: ctx.durationMs,
+				message: ctx.error.message
+			});
+		}));
+		unregisters.push(hooks.hook("mcp:error", (ctx) => {
+			runLogger.error("mcp error", {
+				server: ctx.name,
+				message: ctx.error.message
+			});
+		}));
+		unregisters.push(hooks.hook("mcp:auth:required", (ctx) => {
+			runLogger.warn("mcp auth required", {
+				server: ctx.name,
+				transport: ctx.transport,
+				reason: ctx.reason
+			});
+		}));
+		unregisters.push(hooks.hook("mcp:tool:error", (ctx) => {
+			turnLogger.error("mcp tool error", {
+				server: ctx.server,
+				tool: ctx.displayName,
+				callId: ctx.callId,
+				message: ctx.error.message
+			});
+		}));
+		unregisters.push(hooks.hook("spawn:before", (ctx) => {
+			if (!includeLifecycle) return;
+			runLogger.debug("spawn started", {
+				childId: ctx.id,
+				depth: ctx.depth
+			});
+		}));
+		unregisters.push(hooks.hook("spawn:complete", (ctx) => {
+			runLogger.info("spawn completed", {
+				childId: ctx.id,
+				...ctx.depth ? { depth: ctx.depth } : {},
+				status: ctx.status ?? "completed",
+				turns: ctx.stats.turns,
+				totalIn: ctx.stats.totalIn,
+				totalOut: ctx.stats.totalOut,
+				...typeof ctx.stats.cost === "number" ? { cost: ctx.stats.cost } : {}
+			});
+		}));
+		unregisters.push(hooks.hook("spawn:error", (ctx) => {
+			runLogger.error("spawn error", {
+				childId: ctx.id,
+				...ctx.depth ? { depth: ctx.depth } : {},
+				message: ctx.error.message
+			});
+		}));
+		let disposed = false;
+		return function uninstall() {
+			if (disposed) return;
+			disposed = true;
+			for (const un of unregisters) try {
+				un();
+			} catch {}
+		};
+	} };
+}
+//#endregion
+//#region src/metrics.ts
+function prefixed$1(prefix, name) {
+	return prefix ? `${prefix}${name}` : name;
+}
+/**
+* Drop `undefined` entries before handing attributes to a metrics
+* backend. OTel's `@opentelemetry/api` rejects `undefined` attribute
+* values (and Prometheus / StatsD adapters silently mis-label them); the
+* helper's own API surface allows `undefined` for ergonomic call sites
+* (`{...(cond ? { foo } : {})}`-style spreads), so we strip here at the
+* boundary.
+*/
+function mergeAttrs(base, extra) {
+	const out = {};
+	if (base) {
+		for (const [k, v] of Object.entries(base)) if (v !== void 0) out[k] = v;
+	}
+	for (const [k, v] of Object.entries(extra)) if (v !== void 0) out[k] = v;
+	return out;
+}
+/**
+* Build a set of metrics hook handlers that can be installed on an agent.
+*
+* @example OpenTelemetry
+* ```ts
+* import { metrics } from '@opentelemetry/api'
+* const meter = metrics.getMeter('zidane')
+* const m = createMetricsHooks({ meter, baseAttributes: { service: 'tui' } })
+* const uninstall = m.install(agent.hooks)
+* try { await agent.run({ prompt }) }
+* finally { uninstall() }
+* ```
+*/
+function createMetricsHooks(options) {
+	const ns = options.namespace;
+	const base = options.baseAttributes;
+	const onError = options.onError ?? (() => {});
+	const make = {
+		counter: (name, opts) => safeFactory(() => options.meter.createCounter(prefixed$1(ns, name), opts), name, onError),
+		histogram: (name, opts) => safeFactory(() => options.meter.createHistogram(prefixed$1(ns, name), opts), name, onError),
+		upDown: (name, opts) => safeFactory(() => options.meter.createUpDownCounter(prefixed$1(ns, name), opts), name, onError)
+	};
+	const turnDuration = make.histogram("gen_ai.client.operation.duration", {
+		unit: "ms",
+		description: "Per-turn LLM operation duration."
+	});
+	const tokenUsage = make.histogram("gen_ai.client.token.usage", {
+		unit: "tokens",
+		description: "Per-turn token usage (tagged by gen_ai.token.type)."
+	});
+	const ttft = make.histogram("gen_ai.client.time_to_first_token", {
+		unit: "ms",
+		description: "Per-turn time to first token."
+	});
+	const toolDuration = make.histogram("gen_ai.tool.duration", {
+		unit: "ms",
+		description: "Native tool execution wall clock."
+	});
+	const toolOutput = make.histogram("gen_ai.tool.output_bytes", {
+		unit: "By",
+		description: "Native tool output bytes."
+	});
+	const mcpToolDuration = make.histogram("gen_ai.mcp.tool.duration", {
+		unit: "ms",
+		description: "MCP tool execution wall clock."
+	});
+	const mcpBootstrapDuration = make.histogram("gen_ai.mcp.bootstrap.duration", {
+		unit: "ms",
+		description: "MCP server bootstrap duration."
+	});
+	const runsStarted = make.counter("gen_ai.agent.runs", { description: "Runs started." });
+	const runsCompleted = make.counter("gen_ai.agent.runs.completed", { description: "Runs completed." });
+	const aborts = make.counter("gen_ai.agent.aborts", { description: "Run abort events." });
+	const toolCalls = make.counter("gen_ai.tool.calls", { description: "Tool dispatches (tagged by outcome)." });
+	const toolErrors = make.counter("gen_ai.tool.errors", { description: "Native tool errors." });
+	const mcpToolErrors = make.counter("gen_ai.mcp.tool.errors", { description: "MCP tool errors." });
+	const streamErrors = make.counter("gen_ai.stream.errors", { description: "Provider stream errors." });
+	const validationRejects = make.counter("gen_ai.validation.rejects", { description: "Tool input validation rejects." });
+	const validationCoercions = make.counter("gen_ai.validation.coercions", { description: "Tool input auto-coercions." });
+	const gateBlocks = make.counter("gen_ai.gate.blocks", { description: "Tool-gate refusals." });
+	const budgetExceeded = make.counter("gen_ai.budget.exceeded", { description: "Per-turn byte budget exceedances." });
+	const toolBudgetExceeded = make.counter("gen_ai.tool_budget.exceeded", { description: "Per-tool dispatch budget exceedances." });
+	const pairingRepairs = make.counter("gen_ai.pairing.repairs", { description: "Tool-pairing repair counts." });
+	const oauthRefreshes = make.counter("gen_ai.oauth.refreshes", { description: "Provider OAuth credential refreshes." });
+	const mcpErrors = make.counter("gen_ai.mcp.errors", { description: "MCP server errors." });
+	const mcpAuthRequired = make.counter("gen_ai.mcp.auth.required", { description: "MCP bootstrap blocked on missing auth." });
+	const costMeter = make.counter("gen_ai.cost_usd", {
+		unit: "USD",
+		description: "Cumulative cost across turns."
+	});
+	const runsActive = make.upDown("gen_ai.agent.runs.active", { description: "In-flight agent runs." });
+	return { install(hooks) {
+		const turnStart = /* @__PURE__ */ new Map();
+		const toolStart = /* @__PURE__ */ new Map();
+		const mcpStart = /* @__PURE__ */ new Map();
+		const unregisters = [];
+		const record = (instrument, value, attrs, kind) => {
+			if (!instrument) return;
+			try {
+				instrument.record(value, mergeAttrs(base, attrs));
+			} catch (err) {
+				try {
+					onError(kind, err);
+				} catch {}
+			}
+		};
+		const add = (instrument, value, attrs, kind) => {
+			if (!instrument) return;
+			try {
+				instrument.add(value, mergeAttrs(base, attrs));
+			} catch (err) {
+				try {
+					onError(kind, err);
+				} catch {}
+			}
+		};
+		unregisters.push(hooks.hook("agent:start", (ctx) => {
+			const attrs = {
+				"gen_ai.agent.depth": ctx.depth,
+				...ctx.agentName ? { "gen_ai.agent.name": ctx.agentName } : {}
+			};
+			add(runsStarted, 1, attrs, "runs");
+			add(runsActive, 1, attrs, "runs.active");
+		}));
+		unregisters.push(hooks.hook("agent:done", () => {
+			add(runsCompleted, 1, {}, "runs.completed");
+			add(runsActive, -1, {}, "runs.active");
+		}));
+		unregisters.push(hooks.hook("agent:abort", () => {
+			add(aborts, 1, {}, "aborts");
+		}));
+		unregisters.push(hooks.hook("turn:before", (ctx) => {
+			turnStart.set(ctx.turnId, Date.now());
+		}));
+		unregisters.push(hooks.hook("turn:after", (ctx) => {
+			const started = turnStart.get(ctx.turnId);
+			turnStart.delete(ctx.turnId);
+			const tagsBase = {
+				"gen_ai.operation.name": "chat",
+				...ctx.usage.modelId ? { "gen_ai.response.model": ctx.usage.modelId } : {},
+				...ctx.usage.finishReason ? { "gen_ai.response.finish_reason": ctx.usage.finishReason } : {}
+			};
+			if (typeof started === "number") record(turnDuration, Date.now() - started, tagsBase, "turn.duration");
+			if (typeof ctx.usage.timeToFirstTokenMs === "number") record(ttft, ctx.usage.timeToFirstTokenMs, tagsBase, "ttft");
+			record(tokenUsage, ctx.usage.input, {
+				...tagsBase,
+				"gen_ai.token.type": "input"
+			}, "token.input");
+			record(tokenUsage, ctx.usage.output, {
+				...tagsBase,
+				"gen_ai.token.type": "output"
+			}, "token.output");
+			if (typeof ctx.usage.cacheRead === "number" && ctx.usage.cacheRead > 0) record(tokenUsage, ctx.usage.cacheRead, {
+				...tagsBase,
+				"gen_ai.token.type": "cache_read"
+			}, "token.cache_read");
+			if (typeof ctx.usage.cacheCreation === "number" && ctx.usage.cacheCreation > 0) record(tokenUsage, ctx.usage.cacheCreation, {
+				...tagsBase,
+				"gen_ai.token.type": "cache_creation"
+			}, "token.cache_creation");
+			if (typeof ctx.usage.cost === "number" && ctx.usage.cost > 0) add(costMeter, ctx.usage.cost, tagsBase, "cost");
+		}));
+		unregisters.push(hooks.hook("stream:error", (ctx) => {
+			add(streamErrors, 1, {
+				"http.response.status_code": ctx.statusCode,
+				"error.type": ctx.err instanceof Error ? ctx.err.name : "unknown"
+			}, "stream.error");
+		}));
+		unregisters.push(hooks.hook("tool:before", (ctx) => {
+			toolStart.set(ctx.callId, Date.now());
+		}));
+		unregisters.push(hooks.hook("tool:after", (ctx) => {
+			const started = toolStart.get(ctx.callId);
+			toolStart.delete(ctx.callId);
+			const tags = { "gen_ai.tool.name": ctx.name };
+			if (typeof started === "number") record(toolDuration, Date.now() - started, tags, "tool.duration");
+			record(toolOutput, ctx.outputBytes, tags, "tool.output_bytes");
+		}));
+		unregisters.push(hooks.hook("tool:error", (ctx) => {
+			toolStart.delete(ctx.callId);
+			add(toolErrors, 1, {
+				"gen_ai.tool.name": ctx.name,
+				"error.type": ctx.error.name
+			}, "tool.errors");
+		}));
+		unregisters.push(hooks.hook("tool:dispatched", (ctx) => {
+			add(toolCalls, 1, {
+				"gen_ai.tool.name": ctx.name,
+				"outcome": ctx.outcome
+			}, "tool.calls");
+			if (ctx.outcome === "gate-block") add(gateBlocks, 1, {
+				"gen_ai.tool.name": ctx.name,
+				...ctx.reason ? { reason: ctx.reason } : {}
+			}, "gate.blocks");
+		}));
+		unregisters.push(hooks.hook("validation:reject", (ctx) => {
+			add(validationRejects, 1, { "gen_ai.tool.name": ctx.name }, "validation.rejects");
+		}));
+		unregisters.push(hooks.hook("validation:coerce", (ctx) => {
+			add(validationCoercions, 1, {
+				"gen_ai.tool.name": ctx.name,
+				"coercions": ctx.coercions.length
+			}, "validation.coercions");
+		}));
+		unregisters.push(hooks.hook("budget:exceeded", (ctx) => {
+			add(budgetExceeded, 1, {
+				bytes: ctx.bytes,
+				budget: ctx.budget
+			}, "budget.exceeded");
+		}));
+		unregisters.push(hooks.hook("tool-budget:exceeded", (ctx) => {
+			add(toolBudgetExceeded, 1, {
+				"gen_ai.tool.name": ctx.tool,
+				"mode": ctx.mode,
+				"count": ctx.count,
+				"max": ctx.max
+			}, "tool_budget.exceeded");
+		}));
+		unregisters.push(hooks.hook("pairing:repair", (ctx) => {
+			add(pairingRepairs, 1, { mode: ctx.mode }, "pairing.repairs");
+		}));
+		unregisters.push(hooks.hook("oauth:refresh", (ctx) => {
+			add(oauthRefreshes, 1, {
+				provider: ctx.provider,
+				source: ctx.source
+			}, "oauth.refreshes");
+		}));
+		unregisters.push(hooks.hook("mcp:tool:before", (ctx) => {
+			mcpStart.set(ctx.callId, Date.now());
+		}));
+		unregisters.push(hooks.hook("mcp:tool:after", (ctx) => {
+			const started = mcpStart.get(ctx.callId);
+			mcpStart.delete(ctx.callId);
+			const tags = {
+				"gen_ai.mcp.server": ctx.server,
+				"gen_ai.tool.name": ctx.displayName
+			};
+			if (typeof started === "number") record(mcpToolDuration, Date.now() - started, tags, "mcp.tool.duration");
+		}));
+		unregisters.push(hooks.hook("mcp:tool:error", (ctx) => {
+			mcpStart.delete(ctx.callId);
+			add(mcpToolErrors, 1, {
+				"gen_ai.mcp.server": ctx.server,
+				"gen_ai.tool.name": ctx.displayName,
+				"error.type": ctx.error.name
+			}, "mcp.tool.errors");
+		}));
+		unregisters.push(hooks.hook("mcp:bootstrap:end", (ctx) => {
+			record(mcpBootstrapDuration, ctx.durationMs, {
+				"gen_ai.mcp.server": ctx.name,
+				"ok": ctx.ok
+			}, "mcp.bootstrap.duration");
+		}));
+		unregisters.push(hooks.hook("mcp:error", (ctx) => {
+			add(mcpErrors, 1, {
+				"gen_ai.mcp.server": ctx.name,
+				"error.type": ctx.error.name
+			}, "mcp.errors");
+		}));
+		unregisters.push(hooks.hook("mcp:auth:required", (ctx) => {
+			add(mcpAuthRequired, 1, {
+				"gen_ai.mcp.server": ctx.name,
+				"transport": ctx.transport,
+				"reason": ctx.reason
+			}, "mcp.auth.required");
+		}));
+		let disposed = false;
+		return function uninstall() {
+			if (disposed) return;
+			disposed = true;
+			for (const un of unregisters) try {
+				un();
+			} catch {}
+			turnStart.clear();
+			toolStart.clear();
+			mcpStart.clear();
+		};
+	} };
+}
+/**
+* Defensive factory wrapper — returns undefined when meter creation
+* throws. Lets a half-broken meter (one unsupported instrument) still
+* give partial metrics rather than collapsing the whole install.
+*/
+function safeFactory(factory, name, onError) {
+	try {
+		return factory();
+	} catch (err) {
+		try {
+			onError(`createInstrument:${name}`, err);
+		} catch {}
+		return;
+	}
+}
+//#endregion
+//#region src/run-summary.ts
+/**
+* Build a run-summary collector. State is created fresh inside each
+* `install()` call, so a single collector instance can be installed
+* across multiple agents without attribution cross-talk. `latest()`
+* returns the most-recent summary across **any** install — install
+* per-agent collectors if you need separate post-run snapshots.
+*
+* @example
+* ```ts
+* const collector = createRunSummaryCollector({
+*   onSummary: s => console.log(JSON.stringify(s)),
+* })
+* const uninstall = collector.install(agent.hooks)
+* try { await agent.run({ prompt }) }
+* finally { uninstall() }
+* ```
+*/
+function createRunSummaryCollector(options = {}) {
+	let last;
+	return {
+		latest: () => last,
+		install(hooks) {
+			let runId;
+			let parentRunId;
+			let depth = 0;
+			let agentName;
+			let startedAt = Date.now();
+			let aborted = false;
+			const errors = [];
+			const blocks = [];
+			const validationRejects = [];
+			const budgetEvents = [];
+			const pairingRepairs = {};
+			const children = [];
+			function resetForNewRun() {
+				aborted = false;
+				errors.length = 0;
+				blocks.length = 0;
+				validationRejects.length = 0;
+				budgetEvents.length = 0;
+				for (const k of Object.keys(pairingRepairs)) delete pairingRepairs[k];
+				children.length = 0;
+			}
+			const unregisters = [];
+			unregisters.push(hooks.hook("agent:start", (ctx) => {
+				resetForNewRun();
+				runId = ctx.runId;
+				parentRunId = ctx.parentRunId;
+				depth = ctx.depth;
+				agentName = ctx.agentName;
+				startedAt = ctx.startedAt;
+			}));
+			unregisters.push(hooks.hook("agent:abort", () => {
+				aborted = true;
+			}));
+			unregisters.push(hooks.hook("stream:error", (ctx) => {
+				const msg = ctx.err instanceof Error ? ctx.err.message : String(ctx.err);
+				const errorType = ctx.err instanceof Error ? ctx.err.name : "unknown";
+				errors.push({
+					kind: "stream",
+					message: msg,
+					errorType,
+					turnId: ctx.turnId,
+					...ctx.statusCode !== void 0 ? { statusCode: ctx.statusCode } : {},
+					...ctx.requestId !== void 0 ? { requestId: ctx.requestId } : {}
+				});
+			}));
+			unregisters.push(hooks.hook("tool:error", (ctx) => {
+				errors.push({
+					kind: "tool",
+					message: ctx.error.message,
+					errorType: ctx.error.name,
+					turnId: ctx.turnId,
+					callId: ctx.callId,
+					toolName: ctx.name
+				});
+			}));
+			unregisters.push(hooks.hook("mcp:tool:error", (ctx) => {
+				errors.push({
+					kind: "mcp-tool",
+					message: ctx.error.message,
+					errorType: ctx.error.name,
+					turnId: ctx.turnId,
+					callId: ctx.callId,
+					server: ctx.server,
+					toolName: ctx.displayName
+				});
+			}));
+			unregisters.push(hooks.hook("mcp:error", (ctx) => {
+				errors.push({
+					kind: "mcp",
+					message: ctx.error.message,
+					errorType: ctx.error.name,
+					server: ctx.name
+				});
+			}));
+			unregisters.push(hooks.hook("spawn:error", (ctx) => {
+				errors.push({
+					kind: "spawn",
+					message: ctx.error.message,
+					errorType: ctx.error.name,
+					childId: ctx.id
+				});
+			}));
+			unregisters.push(hooks.hook("tool:dispatched", (ctx) => {
+				if (ctx.outcome === "gate-block" || ctx.outcome === "unknown" || ctx.outcome === "invalid-input") blocks.push({
+					callId: ctx.callId,
+					toolName: ctx.name,
+					outcome: ctx.outcome,
+					...ctx.reason ? { reason: ctx.reason } : {}
+				});
+			}));
+			unregisters.push(hooks.hook("validation:reject", (ctx) => {
+				validationRejects.push({
+					callId: ctx.callId,
+					toolName: ctx.name,
+					reason: ctx.reason
+				});
+			}));
+			unregisters.push(hooks.hook("budget:exceeded", (ctx) => {
+				budgetEvents.push({
+					kind: "bytes",
+					observed: ctx.bytes,
+					limit: ctx.budget,
+					turnId: ctx.turnId
+				});
+			}));
+			unregisters.push(hooks.hook("tool-budget:exceeded", (ctx) => {
+				budgetEvents.push({
+					kind: "tool-count",
+					toolName: ctx.tool,
+					mode: ctx.mode,
+					observed: ctx.count,
+					limit: ctx.max,
+					turnId: ctx.turnId
+				});
+			}));
+			unregisters.push(hooks.hook("pairing:repair", (ctx) => {
+				pairingRepairs[ctx.mode] = (pairingRepairs[ctx.mode] ?? 0) + 1;
+			}));
+			unregisters.push(hooks.hook("agent:done", (stats) => {
+				const endedAt = Date.now();
+				const byModel = [];
+				for (const [modelId, usage] of statsByModel(stats)) byModel.push({
+					modelId,
+					input: usage.input,
+					output: usage.output,
+					cacheRead: usage.cacheRead,
+					cacheCreation: usage.cacheCreation,
+					cost: usage.cost,
+					turns: usage.turns
+				});
+				for (const c of stats.children ?? []) children.push(minimalSummaryFromStats(c.stats, {
+					depth: c.depth ?? depth + 1,
+					status: c.status === "aborted" ? "aborted" : "completed"
+				}));
+				const summary = {
+					...runId ? { runId } : {},
+					...parentRunId ? { parentRunId } : {},
+					depth,
+					...agentName ? { agentName } : {},
+					startedAt,
+					endedAt,
+					durationMs: endedAt - startedAt,
+					status: aborted ? "aborted" : "completed",
+					turns: stats.turns,
+					totals: buildTotals(stats),
+					byModel,
+					errors: errors.slice(),
+					blocks: blocks.slice(),
+					validationRejects: validationRejects.slice(),
+					budgetEvents: budgetEvents.slice(),
+					pairingRepairs: { ...pairingRepairs },
+					...children.length > 0 ? { children: children.slice() } : {}
+				};
+				last = summary;
+				try {
+					options.onSummary?.(summary);
+				} catch {}
+			}));
+			let disposed = false;
+			return function uninstall() {
+				if (disposed) return;
+				disposed = true;
+				for (const un of unregisters) try {
+					un();
+				} catch {}
+			};
+		}
+	};
+}
+function buildTotals(stats) {
+	return {
+		input: stats.totalIn,
+		output: stats.totalOut,
+		cacheRead: stats.totalCacheRead,
+		cacheCreation: stats.totalCacheCreation,
+		...typeof stats.cost === "number" ? { cost: stats.cost } : {},
+		...typeof stats.timeTillFirstTokenMs === "number" ? { ttftMs: stats.timeTillFirstTokenMs } : {}
+	};
+}
+function minimalSummaryFromStats(stats, meta) {
+	const byModel = [];
+	for (const [modelId, usage] of statsByModel(stats)) byModel.push({
+		modelId,
+		input: usage.input,
+		output: usage.output,
+		cacheRead: usage.cacheRead,
+		cacheCreation: usage.cacheCreation,
+		cost: usage.cost,
+		turns: usage.turns
+	});
+	const children = [];
+	for (const c of stats.children ?? []) children.push(minimalSummaryFromStats(c.stats, {
+		depth: c.depth ?? meta.depth + 1,
+		status: c.status === "aborted" ? "aborted" : "completed"
+	}));
+	return {
+		depth: meta.depth,
+		startedAt: 0,
+		endedAt: 0,
+		durationMs: stats.elapsed,
+		status: meta.status,
+		turns: stats.turns,
+		totals: buildTotals(stats),
+		byModel,
+		errors: [],
+		blocks: [],
+		validationRejects: [],
+		budgetEvents: [],
+		pairingRepairs: {},
+		...children.length > 0 ? { children } : {}
+	};
+}
+//#endregion
 //#region src/tracing.ts
 /**
+* Stable keys we emit unconditionally — present in BOTH Sentry and OTel
+* conventions with identical semantics, so no `conventions` branching is
+* needed at the call site.
+*/
+const GEN_AI = {
+	system: "gen_ai.system",
+	operationName: "gen_ai.operation.name",
+	requestModel: "gen_ai.request.model",
+	responseModel: "gen_ai.response.model",
+	responseFinishReasons: "gen_ai.response.finish_reasons",
+	responseId: "gen_ai.response.id",
+	responseStreaming: "gen_ai.response.streaming",
+	responseTokensPerSecond: "gen_ai.response.tokens_per_second",
+	responseTimeToFirstTokenSeconds: "gen_ai.response.time_to_first_token",
+	responseTimeToFirstTokenMs: "gen_ai.client.time_to_first_token",
+	usageInputTokens: "gen_ai.usage.input_tokens",
+	usageOutputTokens: "gen_ai.usage.output_tokens",
+	usageTotalTokens: "gen_ai.usage.total_tokens",
+	usageInputTokensCached: "gen_ai.usage.input_tokens.cached",
+	usageInputTokensCacheWrite: "gen_ai.usage.input_tokens.cache_write",
+	usageOutputTokensReasoning: "gen_ai.usage.output_tokens.reasoning",
+	usageCacheReadInputTokens: "gen_ai.usage.cache_read_input_tokens",
+	usageCacheCreationInputTokens: "gen_ai.usage.cache_creation_input_tokens",
+	usageReasoningTokens: "gen_ai.usage.reasoning_tokens",
+	costTotalTokens: "gen_ai.cost.total_tokens",
+	costInputTokens: "gen_ai.cost.input_tokens",
+	costOutputTokens: "gen_ai.cost.output_tokens",
+	usageCostUsd: "gen_ai.usage.cost_usd",
+	toolName: "gen_ai.tool.name",
+	toolDescription: "gen_ai.tool.description",
+	toolType: "gen_ai.tool.type",
+	toolCallId: "gen_ai.tool.call.id",
+	toolCallArguments: "gen_ai.tool.call.arguments",
+	toolCallResult: "gen_ai.tool.call.result",
+	toolMessage: "gen_ai.tool.message",
+	toolInputDeprecated: "gen_ai.tool.input",
+	toolOutputDeprecated: "gen_ai.tool.output",
+	requestMaxTokens: "gen_ai.request.max_tokens",
+	requestTemperature: "gen_ai.request.temperature",
+	requestTopP: "gen_ai.request.top_p",
+	requestTopK: "gen_ai.request.top_k",
+	requestSeed: "gen_ai.request.seed",
+	requestFrequencyPenalty: "gen_ai.request.frequency_penalty",
+	requestPresencePenalty: "gen_ai.request.presence_penalty",
+	inputMessages: "gen_ai.input.messages",
+	outputMessages: "gen_ai.output.messages",
+	systemInstructions: "gen_ai.system_instructions",
+	toolDefinitions: "gen_ai.tool.definitions",
+	agentName: "gen_ai.agent.name",
+	agentRunId: "gen_ai.agent.run.id",
+	agentParentRunId: "gen_ai.agent.parent_run.id",
+	agentDepth: "gen_ai.agent.depth",
+	pipelineName: "gen_ai.pipeline.name",
+	turn: "gen_ai.agent.turn",
+	mcpServer: "gen_ai.mcp.server",
+	mcpToolCount: "gen_ai.mcp.tool_count"
+};
+/** Compose namespace prefix once. */
+function prefixed(namespace, name) {
+	return namespace ? `${namespace}/${name}` : name;
+}
+/** Drop undefined entries — tracers vary on how they render `undefined`. */
+function compact(attrs) {
+	const out = {};
+	for (const [k, v] of Object.entries(attrs)) if (v !== void 0) out[k] = v;
+	return out;
+}
+function blockToParts(block) {
+	switch (block.type) {
+		case "text": return [{
+			type: "text",
+			content: typeof block.text === "string" ? block.text : ""
+		}];
+		case "image": return [{
+			type: "text",
+			content: "[Blob substitute]"
+		}];
+		case "tool_call": return [{
+			type: "tool_call",
+			...typeof block.name === "string" ? { name: block.name } : {},
+			...typeof block.id === "string" ? { call_id: block.id } : {},
+			arguments: safeJson(block.input)
+		}];
+		case "tool_result": {
+			const output = block.output;
+			const text = typeof output === "string" ? output : Array.isArray(output) ? output.map((b) => b.type === "image" ? "[Blob substitute]" : b.text ?? "").join("\n") : "";
+			return [{
+				type: "tool_result",
+				...typeof block.callId === "string" ? { call_id: block.callId } : {},
+				content: text
+			}];
+		}
+		case "thinking": return [{
+			type: "reasoning",
+			content: typeof block.text === "string" ? block.text : ""
+		}];
+		default: return [];
+	}
+}
+function messageToSentry(msg) {
+	const parts = [];
+	for (const block of msg.content) parts.push(...blockToParts(block));
+	return {
+		role: msg.role,
+		parts
+	};
+}
+function safeJson(value) {
+	try {
+		return JSON.stringify(value ?? null);
+	} catch {
+		return "\"[unserializable]\"";
+	}
+}
+/**
+* Stringify an array of `SessionMessage`s into Sentry's `gen_ai.input.messages`
+* format. Each entry's role + content is mapped via `messageToSentry`.
+* Returns `undefined` when the input is empty or unserializable.
+*/
+function stringifyMessages(messages) {
+	if (messages.length === 0) return void 0;
+	try {
+		const sentry = messages.map((m) => messageToSentry({
+			role: m.role,
+			content: m.content
+		}));
+		return JSON.stringify(sentry);
+	} catch {
+		return;
+	}
+}
+/**
+* Stringify a `StreamOptions.tools` array into Sentry's
+* `gen_ai.tool.definitions` format: `[{name, description?, parameters?}, …]`.
+*
+* The input is `unknown[]` because `StreamOptions.tools` carries the
+* provider-formatted shape (Anthropic / OpenAI / OpenAI-compat all
+* differ). We probe the three names that overlap (`name`, `description`,
+* `inputSchema` / `parameters`) and degrade gracefully otherwise.
+*/
+function stringifyToolDefs(tools) {
+	if (!tools || tools.length === 0) return void 0;
+	try {
+		return JSON.stringify(tools.map((raw) => {
+			if (!raw || typeof raw !== "object") return { name: "anonymous" };
+			const t = raw;
+			const name = typeof t.name === "string" ? t.name : "anonymous";
+			const description = typeof t.description === "string" ? t.description : void 0;
+			const parameters = t.parameters ?? t.input_schema ?? t.inputSchema;
+			return {
+				name,
+				...description ? { description } : {},
+				...parameters !== void 0 ? { parameters } : {}
+			};
+		}));
+	} catch {
+		return;
+	}
+}
+/**
+* Build the usage attribute set per the configured conventions. Sentry
+* expects `input_tokens` to include cached, with `input_tokens.cached`
+* + `input_tokens.cache_write` subkeys; OTel splits cache into
+* separate top-level keys. `'both'` emits everything.
+*/
+function buildUsageAttrs(usage, conventions) {
+	const cacheRead = usage.cacheRead ?? 0;
+	const cacheWrite = usage.cacheCreation ?? 0;
+	const inputInclCache = usage.input + cacheRead + cacheWrite;
+	const totalTokens = inputInclCache + usage.output;
+	const wantSentry = conventions === "sentry" || conventions === "both";
+	const wantOtel = conventions === "otel" || conventions === "both";
+	const out = {
+		[GEN_AI.responseModel]: usage.modelId,
+		[GEN_AI.responseFinishReasons]: usage.finishReason ? [usage.finishReason] : void 0,
+		[GEN_AI.usageOutputTokens]: usage.output,
+		[GEN_AI.usageTotalTokens]: totalTokens
+	};
+	if (wantSentry) {
+		out[GEN_AI.usageInputTokens] = inputInclCache;
+		if (cacheRead > 0) out[GEN_AI.usageInputTokensCached] = cacheRead;
+		if (cacheWrite > 0) out[GEN_AI.usageInputTokensCacheWrite] = cacheWrite;
+		if (typeof usage.thinking === "number" && usage.thinking > 0) out[GEN_AI.usageOutputTokensReasoning] = usage.thinking;
+		if (typeof usage.cost === "number") out[GEN_AI.costTotalTokens] = usage.cost;
+		if (typeof usage.timeToFirstTokenMs === "number") out[GEN_AI.responseTimeToFirstTokenSeconds] = usage.timeToFirstTokenMs / 1e3;
+	}
+	if (wantOtel) {
+		if (!wantSentry) out[GEN_AI.usageInputTokens] = usage.input;
+		if (cacheRead > 0) out[GEN_AI.usageCacheReadInputTokens] = cacheRead;
+		if (cacheWrite > 0) out[GEN_AI.usageCacheCreationInputTokens] = cacheWrite;
+		if (typeof usage.thinking === "number" && usage.thinking > 0) out[GEN_AI.usageReasoningTokens] = usage.thinking;
+		if (typeof usage.cost === "number") out[GEN_AI.usageCostUsd] = usage.cost;
+		if (typeof usage.timeToFirstTokenMs === "number") out[GEN_AI.responseTimeToFirstTokenMs] = usage.timeToFirstTokenMs;
+	}
+	return out;
+}
+/**
 * Build a set of tracing hook handlers that can be installed on an agent.
 *
 * @example Sentry
@@ -24,85 +1043,530 @@ import { defineSkill } from "./skills.js";
 * try { await agent.run({ prompt }) }
 * finally { uninstall() }
 * ```
+*
+* @example OpenTelemetry with parent-context propagation
+* ```ts
+* import { trace, context, propagation } from '@opentelemetry/api'
+*
+* const tracer = trace.getTracer('zidane')
+* const tracing = createTracingHooks({
+*   startSpan: (name, attrs, parentCtx) => {
+*     const ctx = parentCtx ? propagation.extract(context.active(), parentCtx) : context.active()
+*     return tracer.startSpan(name, { attributes: attrs }, ctx)
+*   },
+*   getActiveTraceContext: () => {
+*     const carrier: Record<string, string> = {}
+*     propagation.inject(context.active(), carrier)
+*     return carrier
+*   },
+* })
+* ```
 */
 function createTracingHooks(options) {
-	const prefix = options.namespace ? `${options.namespace}/` : "";
+	const namespace = options.namespace;
+	const legacy = options.legacyAttributes ?? true;
+	const conventions = options.conventions ?? "sentry";
+	const wantSentry = conventions === "sentry" || conventions === "both";
+	const captureContent = options.captureMessageContent ?? true;
+	const onError = options.onError ?? (() => {});
 	return { install(hooks) {
+		const runSpans = /* @__PURE__ */ new Map();
 		const turnSpans = /* @__PURE__ */ new Map();
 		const toolSpans = /* @__PURE__ */ new Map();
 		const mcpSpans = /* @__PURE__ */ new Map();
-		function endSpan(map, key) {
+		const spawnSpans = /* @__PURE__ */ new Map();
+		const bootstrapSpans = /* @__PURE__ */ new Map();
+		let activeSystem;
+		const turnTrack = /* @__PURE__ */ new Map();
+		let activeRunSpan;
+		function safeStartSpan(name, attrs, parentContext) {
+			try {
+				return options.startSpan(prefixed(namespace, name), compact(attrs), parentContext);
+			} catch (err) {
+				try {
+					onError("startSpan", err);
+				} catch {}
+				return;
+			}
+		}
+		function safeSetAttrs(span, attrs) {
+			if (!span?.setAttributes) return;
+			try {
+				span.setAttributes(compact(attrs));
+			} catch (err) {
+				try {
+					onError("setAttributes", err);
+				} catch {}
+			}
+		}
+		function safeEnd(map, key) {
 			const span = map.get(key);
-			if (span) {
+			if (!span) return;
+			try {
+				span.end();
+			} catch (err) {
 				try {
-					span.end();
+					onError("end", err);
 				} catch {}
-				map.delete(key);
 			}
+			map.delete(key);
 		}
 		function endAll(map) {
 			for (const [, span] of map) try {
 				span.end();
-			} catch {}
+			} catch (err) {
+				try {
+					onError("end", err);
+				} catch {}
+			}
 			map.clear();
 		}
-		const unregisters = [];
-		unregisters.push(hooks.hook("turn:before", (ctx) => {
-			const span = options.startSpan(`${prefix}turn:${ctx.turn}`, { turnId: ctx.turnId });
-			turnSpans.set(ctx.turnId, span);
-		}));
-		function safeSetAttrs(span, attrs) {
+		function safeAddEvent(span, name, attrs) {
 			if (!span) return;
+			if (typeof span.addEvent === "function") {
+				try {
+					span.addEvent(name, compact(attrs));
+				} catch (err) {
+					try {
+						onError("addEvent", err);
+					} catch {}
+				}
+				return;
+			}
+			safeSetAttrs(span, Object.fromEntries(Object.entries(compact(attrs)).map(([k, v]) => [`event.${name}.${k}`, v])));
+		}
+		function redact(kind, value, meta) {
+			if (typeof options.redact !== "function") return value;
 			try {
-				span.setAttributes?.(attrs);
-			} catch {}
+				return options.redact(kind, value, meta);
+			} catch (err) {
+				try {
+					onError("redact", err);
+				} catch {}
+				return value;
+			}
 		}
+		const unregisters = [];
+		unregisters.push(hooks.hook("agent:start", (ctx) => {
+			activeSystem = ctx.providerName;
+			const span = safeStartSpan(`invoke_agent ${ctx.agentName && ctx.agentName.length > 0 ? ctx.agentName : "agent"}`, {
+				[GEN_AI.operationName]: "invoke_agent",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.agentName]: ctx.agentName,
+				[GEN_AI.agentRunId]: ctx.runId,
+				[GEN_AI.agentParentRunId]: ctx.parentRunId,
+				[GEN_AI.agentDepth]: ctx.depth,
+				"sentry.op": "gen_ai.invoke_agent",
+				...legacy ? {
+					runId: ctx.runId,
+					parentRunId: ctx.parentRunId,
+					agentName: ctx.agentName,
+					depth: ctx.depth
+				} : {}
+			}, ctx.tracingContext);
+			if (span) {
+				runSpans.set(ctx.runId, span);
+				activeRunSpan = span;
+			}
+		}));
+		unregisters.push(hooks.hook("agent:done", (stats) => {
+			const usageAttrs = buildUsageAttrs({
+				input: stats.totalIn,
+				output: stats.totalOut,
+				cacheRead: stats.totalCacheRead,
+				cacheCreation: stats.totalCacheCreation,
+				cost: stats.cost,
+				timeToFirstTokenMs: stats.timeTillFirstTokenMs
+			}, conventions);
+			for (const [, span] of runSpans) safeSetAttrs(span, {
+				...usageAttrs,
+				[GEN_AI.turn]: stats.turns,
+				"gen_ai.agent.elapsed_ms": stats.elapsed,
+				...legacy ? {
+					totalIn: stats.totalIn,
+					totalOut: stats.totalOut,
+					totalCacheRead: stats.totalCacheRead,
+					totalCacheCreation: stats.totalCacheCreation,
+					cost: stats.cost,
+					turns: stats.turns,
+					elapsed: stats.elapsed
+				} : {}
+			});
+			endAll(runSpans);
+			endAll(turnSpans);
+			endAll(toolSpans);
+			endAll(mcpSpans);
+			endAll(spawnSpans);
+			endAll(bootstrapSpans);
+			activeRunSpan = void 0;
+			activeSystem = void 0;
+			turnTrack.clear();
+		}));
+		unregisters.push(hooks.hook("agent:abort", () => {
+			for (const [, span] of runSpans) safeSetAttrs(span, { "gen_ai.agent.status": "aborted" });
+		}));
+		unregisters.push(hooks.hook("turn:before", (ctx) => {
+			const requestedModel = ctx.options.model;
+			const baseAttrs = {
+				[GEN_AI.operationName]: "chat",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.requestModel]: requestedModel,
+				[GEN_AI.turn]: ctx.turn,
+				[GEN_AI.responseStreaming]: true,
+				[GEN_AI.requestMaxTokens]: ctx.options.maxTokens,
+				"sentry.op": "gen_ai.chat",
+				"gen_ai.agent.turn_id": ctx.turnId,
+				...legacy ? {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				} : {}
+			};
+			if (captureContent) {
+				const systemText = ctx.options.system;
+				if (systemText) baseAttrs[GEN_AI.systemInstructions] = redact("system", systemText, {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				});
+				const inputMsgs = stringifyMessages(ctx.options.messages);
+				if (inputMsgs) baseAttrs[GEN_AI.inputMessages] = redact("prompt", inputMsgs, {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				});
+				const toolDefs = stringifyToolDefs(ctx.options.tools);
+				if (toolDefs) baseAttrs[GEN_AI.toolDefinitions] = toolDefs;
+			}
+			const span = safeStartSpan(`chat${requestedModel ? ` ${requestedModel}` : ""}`, baseAttrs);
+			if (span) {
+				turnSpans.set(ctx.turnId, span);
+				turnTrack.set(ctx.turnId, { startedAt: Date.now() });
+			}
+		}));
+		unregisters.push(hooks.hook("stream:start", (ctx) => {
+			safeAddEvent(turnSpans.get(ctx.turnId), "gen_ai.stream.start", { startedAt: ctx.startedAt });
+		}));
 		unregisters.push(hooks.hook("turn:after", (ctx) => {
-			safeSetAttrs(turnSpans.get(ctx.turnId), {
-				inputTokens: ctx.usage.input,
-				outputTokens: ctx.usage.output,
-				...ctx.usage.finishReason ? { finishReason: ctx.usage.finishReason } : {},
-				...ctx.usage.modelId ? { modelId: ctx.usage.modelId } : {}
+			const span = turnSpans.get(ctx.turnId);
+			const tracked = turnTrack.get(ctx.turnId);
+			turnTrack.delete(ctx.turnId);
+			let tokensPerSecond;
+			if (tracked && ctx.usage.output > 0) {
+				const elapsedMs = Date.now() - tracked.startedAt;
+				if (elapsedMs > 0) tokensPerSecond = ctx.usage.output / elapsedMs * 1e3;
+			}
+			const usageAttrs = buildUsageAttrs(ctx.usage, conventions);
+			const cumInputTokens = wantSentry ? ctx.cumulativeUsage.input + ctx.cumulativeUsage.cacheRead + ctx.cumulativeUsage.cacheCreation : ctx.cumulativeUsage.input;
+			const attrs = {
+				...usageAttrs,
+				[GEN_AI.responseTokensPerSecond]: tokensPerSecond,
+				"gen_ai.agent.cumulative.input_tokens": cumInputTokens,
+				"gen_ai.agent.cumulative.output_tokens": ctx.cumulativeUsage.output,
+				"gen_ai.agent.cumulative.total_tokens": cumInputTokens + ctx.cumulativeUsage.output,
+				"gen_ai.agent.cumulative.cache_read_input_tokens": ctx.cumulativeUsage.cacheRead,
+				"gen_ai.agent.cumulative.cache_creation_input_tokens": ctx.cumulativeUsage.cacheCreation,
+				"gen_ai.agent.cumulative.cost_usd": ctx.cumulativeUsage.cost,
+				"gen_ai.agent.cumulative.turns": ctx.cumulativeUsage.turns,
+				...legacy ? {
+					inputTokens: ctx.usage.input,
+					outputTokens: ctx.usage.output,
+					finishReason: ctx.usage.finishReason,
+					modelId: ctx.usage.modelId
+				} : {}
+			};
+			if (captureContent && ctx.message && ctx.message.role !== "system") {
+				const outputMsgs = stringifyMessages([{
+					role: ctx.message.role,
+					content: ctx.message.content
+				}]);
+				if (outputMsgs) attrs[GEN_AI.outputMessages] = redact("stream-text", outputMsgs, {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				});
+			}
+			safeSetAttrs(span, attrs);
+			safeEnd(turnSpans, ctx.turnId);
+		}));
+		unregisters.push(hooks.hook("stream:error", (ctx) => {
+			const span = turnSpans.get(ctx.turnId);
+			const message = ctx.err instanceof Error ? ctx.err.message : String(ctx.err);
+			safeSetAttrs(span, {
+				"error.type": ctx.err instanceof Error ? ctx.err.name : "unknown",
+				"error.message": message,
+				"http.response.status_code": ctx.statusCode,
+				"gen_ai.request.id": ctx.requestId
+			});
+			safeAddEvent(span, "gen_ai.stream.error", {
+				"error.type": ctx.err instanceof Error ? ctx.err.name : "unknown",
+				"error.message": message,
+				"http.response.status_code": ctx.statusCode,
+				"gen_ai.request.id": ctx.requestId
 			});
-			endSpan(turnSpans, ctx.turnId);
 		}));
 		unregisters.push(hooks.hook("tool:before", (ctx) => {
-			const span = options.startSpan(`${prefix}tool:${ctx.displayName}`, {
-				toolName: ctx.name,
-				displayName: ctx.displayName,
-				turnId: ctx.turnId,
-				callId: ctx.callId
+			const span = safeStartSpan(`execute_tool ${ctx.displayName}`, {
+				[GEN_AI.operationName]: "execute_tool",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolType]: "function",
+				[GEN_AI.toolCallId]: ctx.callId,
+				"sentry.op": "gen_ai.execute_tool",
+				"gen_ai.tool.display_name": ctx.displayName,
+				"gen_ai.agent.turn_id": ctx.turnId,
+				"gen_ai.agent.depth": ctx.depth,
+				"gen_ai.agent.run.id": ctx.runId,
+				"gen_ai.agent.parent_run.id": ctx.parentRunId,
+				...legacy ? {
+					toolName: ctx.name,
+					displayName: ctx.displayName,
+					turnId: ctx.turnId,
+					callId: ctx.callId
+				} : {}
 			});
-			toolSpans.set(ctx.callId, span);
+			if (span) {
+				toolSpans.set(ctx.callId, span);
+				if (captureContent) try {
+					const redacted = redact("tool-input", JSON.stringify(ctx.input), {
+						toolName: ctx.name,
+						displayName: ctx.displayName,
+						callId: ctx.callId,
+						turnId: ctx.turnId
+					});
+					const attrs = {};
+					if (wantSentry) attrs[GEN_AI.toolCallArguments] = redacted;
+					if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolInputDeprecated] = redacted;
+					safeSetAttrs(span, attrs);
+				} catch {}
+			}
 		}));
 		unregisters.push(hooks.hook("tool:after", (ctx) => {
-			endSpan(toolSpans, ctx.callId);
+			const span = toolSpans.get(ctx.callId);
+			safeSetAttrs(span, {
+				"gen_ai.tool.output_bytes": ctx.outputBytes,
+				"gen_ai.tool.coercions": ctx.coercions?.length ?? 0
+			});
+			if (captureContent && typeof ctx.result === "string") {
+				const redacted = redact("tool-result", ctx.result, {
+					toolName: ctx.name,
+					callId: ctx.callId
+				});
+				const attrs = {};
+				if (wantSentry) attrs[GEN_AI.toolCallResult] = redacted;
+				if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolOutputDeprecated] = redacted;
+				safeSetAttrs(span, attrs);
+			}
+			safeEnd(toolSpans, ctx.callId);
 		}));
 		unregisters.push(hooks.hook("tool:error", (ctx) => {
-			safeSetAttrs(toolSpans.get(ctx.callId), { error: ctx.error.message });
-			endSpan(toolSpans, ctx.callId);
+			safeSetAttrs(toolSpans.get(ctx.callId), {
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+			safeEnd(toolSpans, ctx.callId);
 		}));
-		unregisters.push(hooks.hook("mcp:tool:before", (ctx) => {
-			const span = options.startSpan(`${prefix}mcp:${ctx.server}:${ctx.tool}`, {
-				server: ctx.server,
-				tool: ctx.tool,
-				displayName: ctx.displayName,
+		unregisters.push(hooks.hook("tool:dispatched", (ctx) => {
+			if (ctx.outcome === "gate-block") safeAddEvent(activeRunSpan, "gen_ai.gate.block", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId,
+				reason: ctx.reason
+			});
+			else if (ctx.outcome === "gate-substitute") safeAddEvent(activeRunSpan, "gen_ai.gate.substitute", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId
+			});
+			else if (ctx.outcome === "unknown") safeAddEvent(activeRunSpan, "gen_ai.tool.unknown", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId
+			});
+			else if (ctx.outcome === "invalid-input") safeAddEvent(activeRunSpan, "gen_ai.tool.invalid_input", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId
+			});
+		}));
+		unregisters.push(hooks.hook("validation:reject", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.validation.reject", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId,
+				reason: ctx.reason
+			});
+		}));
+		unregisters.push(hooks.hook("validation:coerce", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.validation.coerce", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId,
+				coercions: ctx.coercions
+			});
+		}));
+		unregisters.push(hooks.hook("budget:exceeded", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.budget.exceeded", {
 				turnId: ctx.turnId,
-				callId: ctx.callId
+				bytes: ctx.bytes,
+				budget: ctx.budget
+			});
+		}));
+		unregisters.push(hooks.hook("tool-budget:exceeded", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.tool_budget.exceeded", {
+				[GEN_AI.toolName]: ctx.tool,
+				turnId: ctx.turnId,
+				count: ctx.count,
+				max: ctx.max,
+				mode: ctx.mode
+			});
+		}));
+		unregisters.push(hooks.hook("pairing:repair", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.pairing.repair", {
+				mode: ctx.mode,
+				callId: ctx.callId,
+				turnId: ctx.turnId
+			});
+		}));
+		unregisters.push(hooks.hook("oauth:refresh", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.oauth.refresh", {
+				provider: ctx.provider,
+				providerId: ctx.providerId,
+				source: ctx.source
 			});
-			mcpSpans.set(ctx.callId, span);
+		}));
+		unregisters.push(hooks.hook("mcp:tool:before", (ctx) => {
+			const span = safeStartSpan(`execute_tool ${ctx.server}.${ctx.tool}`, {
+				[GEN_AI.operationName]: "execute_tool",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.toolName]: ctx.displayName,
+				[GEN_AI.toolType]: "extension",
+				[GEN_AI.toolCallId]: ctx.callId,
+				[GEN_AI.mcpServer]: ctx.server,
+				"sentry.op": "gen_ai.execute_tool",
+				"gen_ai.mcp.tool": ctx.tool,
+				"gen_ai.agent.turn_id": ctx.turnId,
+				"gen_ai.agent.run.id": ctx.runId,
+				...legacy ? {
+					server: ctx.server,
+					tool: ctx.tool,
+					displayName: ctx.displayName,
+					turnId: ctx.turnId,
+					callId: ctx.callId
+				} : {}
+			});
+			if (span) {
+				mcpSpans.set(ctx.callId, span);
+				if (captureContent) try {
+					const redacted = redact("mcp-tool-input", JSON.stringify(ctx.input), {
+						server: ctx.server,
+						tool: ctx.tool,
+						callId: ctx.callId
+					});
+					const attrs = {};
+					if (wantSentry) attrs[GEN_AI.toolCallArguments] = redacted;
+					if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolInputDeprecated] = redacted;
+					safeSetAttrs(span, attrs);
+				} catch {}
+			}
 		}));
 		unregisters.push(hooks.hook("mcp:tool:after", (ctx) => {
-			endSpan(mcpSpans, ctx.callId);
+			const span = mcpSpans.get(ctx.callId);
+			safeSetAttrs(span, { "gen_ai.tool.output_bytes": ctx.outputBytes });
+			if (captureContent && typeof ctx.result === "string") {
+				const redacted = redact("mcp-tool-result", ctx.result, {
+					server: ctx.server,
+					tool: ctx.tool,
+					callId: ctx.callId
+				});
+				const attrs = {};
+				if (wantSentry) attrs[GEN_AI.toolCallResult] = redacted;
+				if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolOutputDeprecated] = redacted;
+				safeSetAttrs(span, attrs);
+			}
+			safeEnd(mcpSpans, ctx.callId);
 		}));
 		unregisters.push(hooks.hook("mcp:tool:error", (ctx) => {
-			safeSetAttrs(mcpSpans.get(ctx.callId), { error: ctx.error.message });
-			endSpan(mcpSpans, ctx.callId);
+			safeSetAttrs(mcpSpans.get(ctx.callId), {
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+			safeEnd(mcpSpans, ctx.callId);
 		}));
-		unregisters.push(hooks.hook("agent:done", () => {
-			endAll(turnSpans);
-			endAll(toolSpans);
-			endAll(mcpSpans);
+		unregisters.push(hooks.hook("mcp:bootstrap:start", (ctx) => {
+			const span = safeStartSpan(`mcp.bootstrap ${ctx.name}`, {
+				[GEN_AI.operationName]: "mcp.bootstrap",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.mcpServer]: ctx.name,
+				"gen_ai.mcp.transport": ctx.transport
+			});
+			if (span) bootstrapSpans.set(ctx.name, span);
+		}));
+		unregisters.push(hooks.hook("mcp:bootstrap:end", (ctx) => {
+			const span = bootstrapSpans.get(ctx.name);
+			const ok = ctx.ok;
+			safeSetAttrs(span, {
+				"gen_ai.mcp.bootstrap.duration_ms": ctx.durationMs,
+				"gen_ai.mcp.bootstrap.ok": ok,
+				...ok ? {
+					[GEN_AI.mcpToolCount]: ctx.toolCount,
+					"gen_ai.mcp.lazy": ctx.lazy,
+					"gen_ai.mcp.cached": ctx.cached
+				} : {
+					"error.type": ctx.error.name,
+					"error.message": ctx.error.message
+				}
+			});
+			safeEnd(bootstrapSpans, ctx.name);
+		}));
+		unregisters.push(hooks.hook("mcp:auth:required", (ctx) => {
+			safeAddEvent(bootstrapSpans.get(ctx.name) ?? activeRunSpan, "gen_ai.mcp.auth.required", {
+				server: ctx.name,
+				transport: ctx.transport,
+				reason: ctx.reason
+			});
+		}));
+		unregisters.push(hooks.hook("mcp:error", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.mcp.error", {
+				"server": ctx.name,
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+		}));
+		unregisters.push(hooks.hook("spawn:before", (ctx) => {
+			const span = safeStartSpan(`handoff to ${ctx.task.length > 60 ? `${ctx.task.slice(0, 57)}…` : ctx.task}`, {
+				[GEN_AI.operationName]: "handoff",
+				[GEN_AI.system]: activeSystem,
+				"sentry.op": "gen_ai.handoff",
+				"gen_ai.agent.spawn.id": ctx.id,
+				"gen_ai.agent.spawn.task": ctx.task,
+				"gen_ai.agent.depth": ctx.depth
+			});
+			if (span) spawnSpans.set(ctx.id, span);
+			if (typeof options.getActiveTraceContext === "function" && ctx.tracingContext) {
+				let carrier;
+				try {
+					carrier = options.getActiveTraceContext();
+				} catch (err) {
+					try {
+						onError("getActiveTraceContext", err);
+					} catch {}
+				}
+				if (carrier) for (const [k, v] of Object.entries(carrier)) ctx.tracingContext[k] = v;
+			}
+		}));
+		unregisters.push(hooks.hook("spawn:complete", (ctx) => {
+			const span = spawnSpans.get(ctx.id);
+			const childUsage = buildUsageAttrs({
+				input: ctx.stats.totalIn,
+				output: ctx.stats.totalOut,
+				cacheRead: ctx.stats.totalCacheRead,
+				cacheCreation: ctx.stats.totalCacheCreation,
+				cost: ctx.stats.cost
+			}, conventions);
+			safeSetAttrs(span, {
+				"gen_ai.agent.spawn.status": ctx.status ?? "completed",
+				"gen_ai.agent.spawn.depth": ctx.depth,
+				...childUsage
+			});
+			safeEnd(spawnSpans, ctx.id);
+		}));
+		unregisters.push(hooks.hook("spawn:error", (ctx) => {
+			safeSetAttrs(spawnSpans.get(ctx.id), {
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+			safeEnd(spawnSpans, ctx.id);
 		}));
 		let disposed = false;
 		return function uninstall() {
@@ -111,12 +1575,23 @@ function createTracingHooks(options) {
 			for (const un of unregisters) try {
 				un();
 			} catch {}
+			endAll(runSpans);
 			endAll(turnSpans);
 			endAll(toolSpans);
 			endAll(mcpSpans);
+			endAll(spawnSpans);
+			endAll(bootstrapSpans);
+			activeRunSpan = void 0;
 		};
 	} };
 }
+/**
+* OpenTelemetry Gen AI semantic-convention attribute keys used by the
+* built-in tracer. Exported so consumers integrating with raw OTel SDKs
+* (instead of going through `createTracingHooks`) can stay aligned with
+* the names the harness itself emits.
+*/
+const GEN_AI_ATTRIBUTES = GEN_AI;
 //#endregion
 //#region src/zod.ts
 /**
@@ -141,6 +1616,6 @@ function zodToJsonSchema(jsonSchema) {
 	return rest;
 }
 //#endregion
-export { ANCHOR_PREVIEW_MAX_CHARS, AgentAbortedError, AgentContextExceededError, AgentProviderError, AgentToolNotAllowedError, AgentToolPairingError, BASE_INSTRUCTIONS, BYTES_PER_TOKEN, CONTEXT_EXCEEDED_MESSAGE_PATTERNS, CompactInvalidInputError, CompactPromptTooLongError, IMPLICITLY_ALLOWED_SKILL_TOOLS, INTERRUPT_MESSAGE_FOR_TOOL_USE, McpOAuthProvider, NO_TOOLS_PREAMBLE, ORPHANED_TOOL_RESULT_MARKER, OpenAICompatHttpError, PERSISTED_STUB_PREFIX, PERSISTENCE_PREVIEW_BYTES, SHELL_CASCADE_CANCEL_MESSAGE, SYNTHETIC_TOOL_RESULT_PLACEHOLDER, TOOL_USE_INTERRUPTED_MARKER, TOOL_USE_SKIPPED_MESSAGE, TRAILER, anchorPreviewFor, anthropic, autoDetectAndConvert, basic_default as basic, basicTools, buildCatalog, buildCompactPrompt, buildFromCompactPrompt, buildFullCompactPrompt, buildPersistedStub, buildPostCompactAttachments, buildTailCompactPrompt, buildUpToCompactPrompt, cerebras, classifyOpenAICompatError, cleanupPersistedSession, compactConversation, connectMcpServers, createAgent, createFileMapStore, createInteractionTool, createMemoryMcpCredentialStore, createMemoryStore, createProcessContext, createRemoteStore, createSandboxContext, createSession, createSkillActivationState, createSkillsReadTool, createSkillsRunScriptTool, createSkillsUseTool, createSpawnTool, createTracingHooks, definePreset, defineSkill, detectTurnInterruption, discoverSkills, edit, ensureToolResultPairing, errorMessage, estimateTokens, filterUnresolvedToolUses, flattenTurns, fromAnthropic, fromOpenAI, getReadState, glob, grep, hasAuthorizationHeader, installAllowedToolsGate, interpolateShellCommands, isToolAllowedByUnion, loadSession, loginMcpServer, mapOAIFinishReason, matchesAllowedTool, matchesContextExceeded, maybePersistToolResult, multiEdit, normalizeMcpBlocks, normalizeMcpServers, openai, openaiCompat, openrouter, parseAllowedToolPattern, parseSkillFile, readStateKey, resolvePersistDir, resolveReadStateMap, resolveSkills, resultToString, sanitizeToolSchema, sanitizeToolSpecs, selectFilesFromReadState, selectFilesFromSession, selectRecentFiles, sliceForCompaction, startOAuthCallback, statsByModel, stripImagesFromTurns, summaryToTurn, toAnthropic, toOpenAI, toTypedError, toolOutputByteLength, toolResultToText, truncateHeadForPtlRetry, utf8ByteLength, validateResourcePath, validateSkillForWrite, validateSkillName, validateToolArgs, writeSkillToDisk, writeSkillsToDisk, zodToJsonSchema };
+export { ANCHOR_PREVIEW_MAX_CHARS, AgentAbortedError, AgentContextExceededError, AgentProviderError, AgentToolNotAllowedError, AgentToolPairingError, BASE_INSTRUCTIONS, BYTES_PER_TOKEN, CONTEXT_EXCEEDED_MESSAGE_PATTERNS, CompactInvalidInputError, CompactPromptTooLongError, GEN_AI_ATTRIBUTES, IMPLICITLY_ALLOWED_SKILL_TOOLS, INTERRUPT_MESSAGE_FOR_TOOL_USE, McpOAuthProvider, NO_TOOLS_PREAMBLE, ORPHANED_TOOL_RESULT_MARKER, OpenAICompatHttpError, PERSISTED_STUB_PREFIX, PERSISTENCE_PREVIEW_BYTES, SHELL_CASCADE_CANCEL_MESSAGE, SYNTHETIC_TOOL_RESULT_PLACEHOLDER, TOOL_USE_CANCELLED_MESSAGE, TOOL_USE_INTERRUPTED_MARKER, TOOL_USE_SKIPPED_MESSAGE, TRAILER, anchorPreviewFor, anthropic, autoDetectAndConvert, basic_default as basic, basicTools, buildCatalog, buildCompactPrompt, buildFromCompactPrompt, buildFullCompactPrompt, buildPersistedStub, buildPostCompactAttachments, buildTailCompactPrompt, buildUpToCompactPrompt, cerebras, classifyOpenAICompatError, cleanupPersistedSession, compactConversation, connectMcpServers, consoleSink, createAgent, createFileMapStore, createInteractionTool, createLogger, createLoggingHooks, createMemoryMcpCredentialStore, createMemoryStore, createMetricsHooks, createProcessContext, createRemoteStore, createRunSummaryCollector, createSandboxContext, createSession, createSkillActivationState, createSkillsReadTool, createSkillsRunScriptTool, createSkillsUseTool, createSpawnTool, createTracingHooks, definePreset, defineSkill, detectTurnInterruption, discoverSkills, edit, ensureToolResultPairing, errorMessage, estimateTokens, filterUnresolvedToolUses, flattenTurns, fromAnthropic, fromOpenAI, getReadState, glob, grep, hasAuthorizationHeader, installAllowedToolsGate, interpolateShellCommands, isToolAllowedByUnion, jsonSink, loadSession, loginMcpServer, mapOAIFinishReason, matchesAllowedTool, matchesContextExceeded, maybePersistToolResult, multiEdit, normalizeMcpBlocks, normalizeMcpServers, openai, openaiCompat, openrouter, parseAllowedToolPattern, parseSkillFile, readStateKey, resolvePersistDir, resolveReadStateMap, resolveSkills, resultToString, sanitizeToolSchema, sanitizeToolSpecs, selectFilesFromReadState, selectFilesFromSession, selectRecentFiles, sliceForCompaction, startOAuthCallback, statsByModel, stripImagesFromTurns, summaryToTurn, toAnthropic, toOpenAI, toTypedError, toolOutputByteLength, toolResultToText, truncateHeadForPtlRetry, utf8ByteLength, validateResourcePath, validateSkillForWrite, validateSkillName, validateToolArgs, writeSkillToDisk, writeSkillsToDisk, zodToJsonSchema };
 
 //# sourceMappingURL=index.js.map