@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.13

package/dist/otel.cjs

@@ -0,0 +1,268 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _opentelemetry_api = require("@opentelemetry/api");
+//#region src/otel/index.ts
+/**
+* OpenTelemetry bridge — maps the versioned `AgentTraceEvent` stream onto
+* GenAI-semconv spans.
+*
+* `createOtelTraceHandler({ tracer })` returns a plain `onTrace` handler, so
+* every OTLP-ingesting backend (Braintrust, Langfuse, LangSmith, Honeycomb,
+* Datadog, Grafana Tempo) is an endpoint + headers away. The bridge is the
+* MAPPING only: it ships no exporter and owns no SDK lifecycle. You bring the
+* `Tracer` from your own OpenTelemetry setup.
+*
+* `@opentelemetry/api` (^1) is an optional peer dependency — installed only by
+* apps that import this subpath.
+*/
+/** Instrumentation scope name used when the handler resolves its own tracer. */
+const TRACER_NAME = "@statelyai/agent";
+/** `AgentCallUsage` → `gen_ai.usage.*`. `totalTokens` has no semconv key. */
+const USAGE_ATTRIBUTES = {
+	inputTokens: "gen_ai.usage.input_tokens",
+	outputTokens: "gen_ai.usage.output_tokens",
+	reasoningTokens: "gen_ai.usage.reasoning.output_tokens",
+	cachedInputTokens: "gen_ai.usage.cache_read.input_tokens",
+	totalTokens: "agent.usage.total_tokens"
+};
+function usageAttributes(usage) {
+	const attributes = {};
+	if (!usage) return attributes;
+	for (const [field, key] of Object.entries(USAGE_ATTRIBUTES)) {
+		const value = usage[field];
+		if (typeof value === "number") attributes[key] = value;
+	}
+	return attributes;
+}
+/** The model ref a request targets: text/plan carry it on `input`, a decision inline. */
+function requestModel(request) {
+	const model = request.kind === "decision" ? request.model : request.input?.model;
+	return typeof model === "string" ? model : void 0;
+}
+/** The `src` a text/plan invoke was declared with; a decision has none. */
+function requestSrc(request) {
+	return "src" in request && typeof request.src === "string" ? request.src : void 0;
+}
+/**
+* `gen_ai.operation.name` for a request. A plan request drives the machine
+* through a sequence of events, which semconv names `plan`; text and decision
+* requests are both single chat completions.
+*/
+function operationName(request) {
+	return request.kind === "plan" ? "plan" : "chat";
+}
+/** Best-effort JSON, never throws — content capture must not break a run. */
+function toJson(value) {
+	try {
+		const json = JSON.stringify(value);
+		return typeof json === "string" ? json : void 0;
+	} catch {
+		return;
+	}
+}
+function errorType(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return typeof code === "string" ? code : error.name;
+	}
+	return typeof error;
+}
+/** `recordException` wants an `Exception`; trace errors are `unknown`. */
+function toException(error) {
+	return error instanceof Error ? error : {
+		name: "Error",
+		message: String(error)
+	};
+}
+/**
+* Builds an `onTrace` handler that maps the trace stream onto OpenTelemetry
+* GenAI spans: one `invoke_agent` span per run, one child span per model call,
+* transitions and emissions as span events.
+*
+* Works on both paths. On the controlled path (`runAgent`) the run span opens
+* on `run.start` and closes on `run.end`. On the uncontrolled path
+* (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
+* run span opens lazily on the first event of a `runId` and stays open until
+* you call `dispose()` — always dispose when the actor stops.
+*
+* @example
+* ```ts
+* import { trace } from '@opentelemetry/api';
+* import { createOtelTraceHandler } from '@statelyai/agent/otel';
+*
+* const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
+* try {
+*   await runAgent(machine, { input, executors, onTrace });
+* } finally {
+*   onTrace.dispose();
+* }
+* ```
+*/
+function createOtelTraceHandler(options) {
+	const tracer = options.tracer ?? options.tracerProvider?.getTracer(TRACER_NAME);
+	if (!tracer) throw new TypeError("createOtelTraceHandler: pass a `tracer` (or a `tracerProvider` to take one from).");
+	const baseAttributes = options.attributes ?? {};
+	const runs = /* @__PURE__ */ new Map();
+	const requests = /* @__PURE__ */ new Map();
+	/**
+	* The run span for an event, created on first sight. Lazy rather than
+	* `run.start`-only so the uncontrolled path (no run boundary) and any
+	* out-of-order delivery still produce a well-formed tree.
+	*/
+	const runFor = (event) => {
+		const existing = runs.get(event.runId);
+		if (existing) return existing;
+		const agentName = options.agentName ?? event.machineId;
+		const span = tracer.startSpan(agentName ? `invoke_agent ${agentName}` : "invoke_agent", {
+			kind: _opentelemetry_api.SpanKind.INTERNAL,
+			attributes: {
+				...baseAttributes,
+				"gen_ai.operation.name": "invoke_agent",
+				"gen_ai.agent.name": agentName,
+				"gen_ai.agent.version": event.machineVersion,
+				"agent.run_id": event.runId,
+				"agent.machine_id": event.machineId,
+				"agent.machine_version": event.machineVersion,
+				"agent.trace_schema_version": event.schemaVersion
+			}
+		}, _opentelemetry_api.context.active());
+		const state = {
+			span,
+			context: _opentelemetry_api.trace.setSpan(_opentelemetry_api.context.active(), span)
+		};
+		runs.set(event.runId, state);
+		return state;
+	};
+	/** Span events all carry `seq`, so a consumer can re-order them downstream. */
+	const addRunEvent = (event, name, attributes) => {
+		runFor(event).span.addEvent(name, {
+			"agent.seq": event.seq,
+			...attributes
+		});
+	};
+	const endRequest = (id, finish) => {
+		const state = requests.get(id);
+		if (!state) return;
+		requests.delete(id);
+		if (state.chunks > 0) state.span.setAttribute("agent.stream_chunks", state.chunks);
+		finish(state.span);
+		state.span.end();
+	};
+	const handler = (event) => {
+		switch (event.type) {
+			case "run.start": {
+				const { span } = runFor(event);
+				if (options.captureContent && event.input !== void 0) {
+					const input = toJson(event.input);
+					if (input !== void 0) span.setAttribute("agent.input", input);
+				}
+				if (event.snapshot) span.setAttribute("agent.resumed", true);
+				break;
+			}
+			case "request.start": {
+				const request = event.request;
+				endRequest(request.id, () => {});
+				const model = requestModel(request);
+				const operation = operationName(request);
+				const attributes = {
+					...baseAttributes,
+					"gen_ai.operation.name": operation,
+					"agent.run_id": event.runId,
+					"agent.request_id": request.id,
+					"agent.request_kind": request.kind
+				};
+				if (model !== void 0) attributes["gen_ai.request.model"] = model;
+				if (options.providerName !== void 0) attributes["gen_ai.provider.name"] = options.providerName;
+				const src = requestSrc(request);
+				if (src !== void 0) attributes["agent.request_src"] = src;
+				if (request.kind === "decision" && request.attempts.length > 0) attributes["agent.request_attempt"] = request.attempts.length;
+				if (options.captureContent) {
+					const input = request.kind === "decision" ? request : request.input;
+					const system = input.system;
+					if (typeof system === "string") attributes["gen_ai.system_instructions"] = system;
+					const json = toJson(input.messages ?? input.prompt);
+					if (json !== void 0) attributes["gen_ai.input.messages"] = json;
+				}
+				const name = operation === "plan" ? `plan ${options.agentName ?? event.machineId}` : `chat ${model ?? request.kind}`;
+				const span = tracer.startSpan(name, {
+					kind: operation === "plan" ? _opentelemetry_api.SpanKind.INTERNAL : _opentelemetry_api.SpanKind.CLIENT,
+					attributes
+				}, runFor(event).context);
+				requests.set(request.id, {
+					span,
+					chunks: 0
+				});
+				break;
+			}
+			case "stream.chunk": {
+				const state = requests.get(event.request.id);
+				if (state) state.chunks += 1;
+				break;
+			}
+			case "request.end":
+				endRequest(event.request.id, (span) => {
+					span.setAttributes(usageAttributes(event.usage));
+					span.setAttribute("agent.output_length", toJson(event.output ?? "")?.length ?? 0);
+					if (options.captureContent) {
+						const output = toJson(event.output);
+						if (output !== void 0) span.setAttribute("gen_ai.output.messages", output);
+					}
+					span.setStatus({ code: _opentelemetry_api.SpanStatusCode.OK });
+				});
+				break;
+			case "request.error":
+				endRequest(event.request.id, (span) => {
+					span.recordException(toException(event.error));
+					span.setAttribute("error.type", errorType(event.error));
+					span.setStatus({
+						code: _opentelemetry_api.SpanStatusCode.ERROR,
+						message: event.error instanceof Error ? event.error.message : void 0
+					});
+				});
+				break;
+			case "machine.transition": {
+				const attributes = {
+					"agent.event_type": event.event.type,
+					"agent.state": toJson(event.snapshot.value) ?? ""
+				};
+				if (event.eventId !== void 0) attributes["agent.event_id"] = event.eventId;
+				addRunEvent(event, "agent.transition", attributes);
+				break;
+			}
+			case "emit":
+				addRunEvent(event, "agent.emit", { "agent.event_type": event.event.type });
+				break;
+			case "usage.dropped": {
+				const dropped = event.event;
+				addRunEvent(event, "agent.usage.dropped", {
+					"agent.drop_reason": event.reason,
+					...usageAttributes(dropped.usage)
+				});
+				break;
+			}
+			case "run.end": {
+				const { span } = runFor(event);
+				runs.delete(event.runId);
+				span.setAttribute("agent.status", event.status);
+				if (event.status === "error") {
+					span.recordException(toException(event.error));
+					span.setAttribute("error.type", errorType(event.error));
+					span.setAttribute("agent.error_cause", event.cause);
+					span.setStatus({ code: _opentelemetry_api.SpanStatusCode.ERROR });
+				} else span.setStatus({ code: _opentelemetry_api.SpanStatusCode.OK });
+				span.end();
+				break;
+			}
+		}
+	};
+	handler.dispose = () => {
+		for (const [id] of requests) endRequest(id, (span) => span.setAttribute("agent.unfinished", true));
+		for (const { span } of runs.values()) {
+			span.setAttribute("agent.unfinished", true);
+			span.end();
+		}
+		runs.clear();
+	};
+	return handler;
+}
+//#endregion
+exports.createOtelTraceHandler = createOtelTraceHandler;

package/dist/otel.d.cts

@@ -0,0 +1,67 @@
+import { c as AgentTraceEvent } from "./run-agent-DnvtcnTZ.cjs";
+import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
+
+//#region src/otel/index.d.ts
+/** Options for {@link createOtelTraceHandler}. */
+interface OtelTraceHandlerOptions {
+  /** The tracer to record with. Pass this OR {@link tracerProvider}. */
+  tracer?: Tracer;
+  /** A provider to take a `@statelyai/agent`-scoped tracer from. */
+  tracerProvider?: TracerProvider;
+  /**
+   * `gen_ai.provider.name` for model-call spans (`openai`, `anthropic`,
+   * `aws.bedrock`, …). Semconv requires it on inference spans, but the trace
+   * stream only carries a model ref, so the bridge cannot infer it — set it
+   * when your run targets one provider, leave it off otherwise.
+   */
+  providerName?: string;
+  /** `gen_ai.agent.name`, and the run span's name. Defaults to the machine's `id`. */
+  agentName?: string;
+  /**
+   * Record prompts and outputs on spans (`gen_ai.input.messages`,
+   * `gen_ai.output.messages`, `gen_ai.system_instructions`), JSON-stringified.
+   * Off by default: semconv marks message content Opt-In, and bodies are large
+   * and frequently sensitive. Sizes (`agent.output_length`) are always recorded.
+   */
+  captureContent?: boolean;
+  /** Extra attributes set on every span the bridge creates. */
+  attributes?: Attributes;
+}
+/**
+ * An `onTrace` handler that writes OpenTelemetry spans, plus `dispose()` to
+ * close any span still open (a run that never emitted `run.end`).
+ */
+type OtelTraceHandler = ((event: AgentTraceEvent) => void) & {
+  /**
+   * Ends every span the handler still holds open and drops its state. Idempotent.
+   * Required on the uncontrolled path, where no `run.end` ever arrives.
+   */
+  dispose(): void;
+};
+/**
+ * Builds an `onTrace` handler that maps the trace stream onto OpenTelemetry
+ * GenAI spans: one `invoke_agent` span per run, one child span per model call,
+ * transitions and emissions as span events.
+ *
+ * Works on both paths. On the controlled path (`runAgent`) the run span opens
+ * on `run.start` and closes on `run.end`. On the uncontrolled path
+ * (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
+ * run span opens lazily on the first event of a `runId` and stays open until
+ * you call `dispose()` — always dispose when the actor stops.
+ *
+ * @example
+ * ```ts
+ * import { trace } from '@opentelemetry/api';
+ * import { createOtelTraceHandler } from '@statelyai/agent/otel';
+ *
+ * const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
+ * try {
+ *   await runAgent(machine, { input, executors, onTrace });
+ * } finally {
+ *   onTrace.dispose();
+ * }
+ * ```
+ */
+declare function createOtelTraceHandler(options: OtelTraceHandlerOptions): OtelTraceHandler;
+//#endregion
+export { OtelTraceHandler, OtelTraceHandlerOptions, createOtelTraceHandler };

package/dist/otel.d.mts

@@ -0,0 +1,67 @@
+import { c as AgentTraceEvent } from "./run-agent-C3mFDGTf.mjs";
+import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
+
+//#region src/otel/index.d.ts
+/** Options for {@link createOtelTraceHandler}. */
+interface OtelTraceHandlerOptions {
+  /** The tracer to record with. Pass this OR {@link tracerProvider}. */
+  tracer?: Tracer;
+  /** A provider to take a `@statelyai/agent`-scoped tracer from. */
+  tracerProvider?: TracerProvider;
+  /**
+   * `gen_ai.provider.name` for model-call spans (`openai`, `anthropic`,
+   * `aws.bedrock`, …). Semconv requires it on inference spans, but the trace
+   * stream only carries a model ref, so the bridge cannot infer it — set it
+   * when your run targets one provider, leave it off otherwise.
+   */
+  providerName?: string;
+  /** `gen_ai.agent.name`, and the run span's name. Defaults to the machine's `id`. */
+  agentName?: string;
+  /**
+   * Record prompts and outputs on spans (`gen_ai.input.messages`,
+   * `gen_ai.output.messages`, `gen_ai.system_instructions`), JSON-stringified.
+   * Off by default: semconv marks message content Opt-In, and bodies are large
+   * and frequently sensitive. Sizes (`agent.output_length`) are always recorded.
+   */
+  captureContent?: boolean;
+  /** Extra attributes set on every span the bridge creates. */
+  attributes?: Attributes;
+}
+/**
+ * An `onTrace` handler that writes OpenTelemetry spans, plus `dispose()` to
+ * close any span still open (a run that never emitted `run.end`).
+ */
+type OtelTraceHandler = ((event: AgentTraceEvent) => void) & {
+  /**
+   * Ends every span the handler still holds open and drops its state. Idempotent.
+   * Required on the uncontrolled path, where no `run.end` ever arrives.
+   */
+  dispose(): void;
+};
+/**
+ * Builds an `onTrace` handler that maps the trace stream onto OpenTelemetry
+ * GenAI spans: one `invoke_agent` span per run, one child span per model call,
+ * transitions and emissions as span events.
+ *
+ * Works on both paths. On the controlled path (`runAgent`) the run span opens
+ * on `run.start` and closes on `run.end`. On the uncontrolled path
+ * (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
+ * run span opens lazily on the first event of a `runId` and stays open until
+ * you call `dispose()` — always dispose when the actor stops.
+ *
+ * @example
+ * ```ts
+ * import { trace } from '@opentelemetry/api';
+ * import { createOtelTraceHandler } from '@statelyai/agent/otel';
+ *
+ * const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
+ * try {
+ *   await runAgent(machine, { input, executors, onTrace });
+ * } finally {
+ *   onTrace.dispose();
+ * }
+ * ```
+ */
+declare function createOtelTraceHandler(options: OtelTraceHandlerOptions): OtelTraceHandler;
+//#endregion
+export { OtelTraceHandler, OtelTraceHandlerOptions, createOtelTraceHandler };

package/dist/otel.mjs

@@ -0,0 +1,267 @@
+import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+//#region src/otel/index.ts
+/**
+* OpenTelemetry bridge — maps the versioned `AgentTraceEvent` stream onto
+* GenAI-semconv spans.
+*
+* `createOtelTraceHandler({ tracer })` returns a plain `onTrace` handler, so
+* every OTLP-ingesting backend (Braintrust, Langfuse, LangSmith, Honeycomb,
+* Datadog, Grafana Tempo) is an endpoint + headers away. The bridge is the
+* MAPPING only: it ships no exporter and owns no SDK lifecycle. You bring the
+* `Tracer` from your own OpenTelemetry setup.
+*
+* `@opentelemetry/api` (^1) is an optional peer dependency — installed only by
+* apps that import this subpath.
+*/
+/** Instrumentation scope name used when the handler resolves its own tracer. */
+const TRACER_NAME = "@statelyai/agent";
+/** `AgentCallUsage` → `gen_ai.usage.*`. `totalTokens` has no semconv key. */
+const USAGE_ATTRIBUTES = {
+	inputTokens: "gen_ai.usage.input_tokens",
+	outputTokens: "gen_ai.usage.output_tokens",
+	reasoningTokens: "gen_ai.usage.reasoning.output_tokens",
+	cachedInputTokens: "gen_ai.usage.cache_read.input_tokens",
+	totalTokens: "agent.usage.total_tokens"
+};
+function usageAttributes(usage) {
+	const attributes = {};
+	if (!usage) return attributes;
+	for (const [field, key] of Object.entries(USAGE_ATTRIBUTES)) {
+		const value = usage[field];
+		if (typeof value === "number") attributes[key] = value;
+	}
+	return attributes;
+}
+/** The model ref a request targets: text/plan carry it on `input`, a decision inline. */
+function requestModel(request) {
+	const model = request.kind === "decision" ? request.model : request.input?.model;
+	return typeof model === "string" ? model : void 0;
+}
+/** The `src` a text/plan invoke was declared with; a decision has none. */
+function requestSrc(request) {
+	return "src" in request && typeof request.src === "string" ? request.src : void 0;
+}
+/**
+* `gen_ai.operation.name` for a request. A plan request drives the machine
+* through a sequence of events, which semconv names `plan`; text and decision
+* requests are both single chat completions.
+*/
+function operationName(request) {
+	return request.kind === "plan" ? "plan" : "chat";
+}
+/** Best-effort JSON, never throws — content capture must not break a run. */
+function toJson(value) {
+	try {
+		const json = JSON.stringify(value);
+		return typeof json === "string" ? json : void 0;
+	} catch {
+		return;
+	}
+}
+function errorType(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return typeof code === "string" ? code : error.name;
+	}
+	return typeof error;
+}
+/** `recordException` wants an `Exception`; trace errors are `unknown`. */
+function toException(error) {
+	return error instanceof Error ? error : {
+		name: "Error",
+		message: String(error)
+	};
+}
+/**
+* Builds an `onTrace` handler that maps the trace stream onto OpenTelemetry
+* GenAI spans: one `invoke_agent` span per run, one child span per model call,
+* transitions and emissions as span events.
+*
+* Works on both paths. On the controlled path (`runAgent`) the run span opens
+* on `run.start` and closes on `run.end`. On the uncontrolled path
+* (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
+* run span opens lazily on the first event of a `runId` and stays open until
+* you call `dispose()` — always dispose when the actor stops.
+*
+* @example
+* ```ts
+* import { trace } from '@opentelemetry/api';
+* import { createOtelTraceHandler } from '@statelyai/agent/otel';
+*
+* const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
+* try {
+*   await runAgent(machine, { input, executors, onTrace });
+* } finally {
+*   onTrace.dispose();
+* }
+* ```
+*/
+function createOtelTraceHandler(options) {
+	const tracer = options.tracer ?? options.tracerProvider?.getTracer(TRACER_NAME);
+	if (!tracer) throw new TypeError("createOtelTraceHandler: pass a `tracer` (or a `tracerProvider` to take one from).");
+	const baseAttributes = options.attributes ?? {};
+	const runs = /* @__PURE__ */ new Map();
+	const requests = /* @__PURE__ */ new Map();
+	/**
+	* The run span for an event, created on first sight. Lazy rather than
+	* `run.start`-only so the uncontrolled path (no run boundary) and any
+	* out-of-order delivery still produce a well-formed tree.
+	*/
+	const runFor = (event) => {
+		const existing = runs.get(event.runId);
+		if (existing) return existing;
+		const agentName = options.agentName ?? event.machineId;
+		const span = tracer.startSpan(agentName ? `invoke_agent ${agentName}` : "invoke_agent", {
+			kind: SpanKind.INTERNAL,
+			attributes: {
+				...baseAttributes,
+				"gen_ai.operation.name": "invoke_agent",
+				"gen_ai.agent.name": agentName,
+				"gen_ai.agent.version": event.machineVersion,
+				"agent.run_id": event.runId,
+				"agent.machine_id": event.machineId,
+				"agent.machine_version": event.machineVersion,
+				"agent.trace_schema_version": event.schemaVersion
+			}
+		}, context.active());
+		const state = {
+			span,
+			context: trace.setSpan(context.active(), span)
+		};
+		runs.set(event.runId, state);
+		return state;
+	};
+	/** Span events all carry `seq`, so a consumer can re-order them downstream. */
+	const addRunEvent = (event, name, attributes) => {
+		runFor(event).span.addEvent(name, {
+			"agent.seq": event.seq,
+			...attributes
+		});
+	};
+	const endRequest = (id, finish) => {
+		const state = requests.get(id);
+		if (!state) return;
+		requests.delete(id);
+		if (state.chunks > 0) state.span.setAttribute("agent.stream_chunks", state.chunks);
+		finish(state.span);
+		state.span.end();
+	};
+	const handler = (event) => {
+		switch (event.type) {
+			case "run.start": {
+				const { span } = runFor(event);
+				if (options.captureContent && event.input !== void 0) {
+					const input = toJson(event.input);
+					if (input !== void 0) span.setAttribute("agent.input", input);
+				}
+				if (event.snapshot) span.setAttribute("agent.resumed", true);
+				break;
+			}
+			case "request.start": {
+				const request = event.request;
+				endRequest(request.id, () => {});
+				const model = requestModel(request);
+				const operation = operationName(request);
+				const attributes = {
+					...baseAttributes,
+					"gen_ai.operation.name": operation,
+					"agent.run_id": event.runId,
+					"agent.request_id": request.id,
+					"agent.request_kind": request.kind
+				};
+				if (model !== void 0) attributes["gen_ai.request.model"] = model;
+				if (options.providerName !== void 0) attributes["gen_ai.provider.name"] = options.providerName;
+				const src = requestSrc(request);
+				if (src !== void 0) attributes["agent.request_src"] = src;
+				if (request.kind === "decision" && request.attempts.length > 0) attributes["agent.request_attempt"] = request.attempts.length;
+				if (options.captureContent) {
+					const input = request.kind === "decision" ? request : request.input;
+					const system = input.system;
+					if (typeof system === "string") attributes["gen_ai.system_instructions"] = system;
+					const json = toJson(input.messages ?? input.prompt);
+					if (json !== void 0) attributes["gen_ai.input.messages"] = json;
+				}
+				const name = operation === "plan" ? `plan ${options.agentName ?? event.machineId}` : `chat ${model ?? request.kind}`;
+				const span = tracer.startSpan(name, {
+					kind: operation === "plan" ? SpanKind.INTERNAL : SpanKind.CLIENT,
+					attributes
+				}, runFor(event).context);
+				requests.set(request.id, {
+					span,
+					chunks: 0
+				});
+				break;
+			}
+			case "stream.chunk": {
+				const state = requests.get(event.request.id);
+				if (state) state.chunks += 1;
+				break;
+			}
+			case "request.end":
+				endRequest(event.request.id, (span) => {
+					span.setAttributes(usageAttributes(event.usage));
+					span.setAttribute("agent.output_length", toJson(event.output ?? "")?.length ?? 0);
+					if (options.captureContent) {
+						const output = toJson(event.output);
+						if (output !== void 0) span.setAttribute("gen_ai.output.messages", output);
+					}
+					span.setStatus({ code: SpanStatusCode.OK });
+				});
+				break;
+			case "request.error":
+				endRequest(event.request.id, (span) => {
+					span.recordException(toException(event.error));
+					span.setAttribute("error.type", errorType(event.error));
+					span.setStatus({
+						code: SpanStatusCode.ERROR,
+						message: event.error instanceof Error ? event.error.message : void 0
+					});
+				});
+				break;
+			case "machine.transition": {
+				const attributes = {
+					"agent.event_type": event.event.type,
+					"agent.state": toJson(event.snapshot.value) ?? ""
+				};
+				if (event.eventId !== void 0) attributes["agent.event_id"] = event.eventId;
+				addRunEvent(event, "agent.transition", attributes);
+				break;
+			}
+			case "emit":
+				addRunEvent(event, "agent.emit", { "agent.event_type": event.event.type });
+				break;
+			case "usage.dropped": {
+				const dropped = event.event;
+				addRunEvent(event, "agent.usage.dropped", {
+					"agent.drop_reason": event.reason,
+					...usageAttributes(dropped.usage)
+				});
+				break;
+			}
+			case "run.end": {
+				const { span } = runFor(event);
+				runs.delete(event.runId);
+				span.setAttribute("agent.status", event.status);
+				if (event.status === "error") {
+					span.recordException(toException(event.error));
+					span.setAttribute("error.type", errorType(event.error));
+					span.setAttribute("agent.error_cause", event.cause);
+					span.setStatus({ code: SpanStatusCode.ERROR });
+				} else span.setStatus({ code: SpanStatusCode.OK });
+				span.end();
+				break;
+			}
+		}
+	};
+	handler.dispose = () => {
+		for (const [id] of requests) endRequest(id, (span) => span.setAttribute("agent.unfinished", true));
+		for (const { span } of runs.values()) {
+			span.setAttribute("agent.unfinished", true);
+			span.end();
+		}
+		runs.clear();
+	};
+	return handler;
+}
+//#endregion
+export { createOtelTraceHandler };