@cursor/bdk 0.2.1

package/src/internal/otel/collector.ts

@@ -0,0 +1,937 @@
+/**
+ * Maps the durable session event stream onto OTel traces / metrics / logs.
+ *
+ * Attribute names reuse Cursor enterprise wire keys where they overlap
+ * (`cursor.conversation.id`, `cursor.token.*`, `cursor.tool.*`,
+ * `cursor.cost.usage`, `cursor.model.name`) so Agent SDK traces join org
+ * metrics/logs in the same collector. Agent-SDK-only fields use `agent_sdk.*`.
+ */
+
+import {
+  type Context,
+  type Counter,
+  context,
+  type Meter,
+  ROOT_CONTEXT,
+  type Span,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+} from "@opentelemetry/api";
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import type { SessionEvent, SessionInfo } from "../../types.js";
+import { classifyExpectedDeliveryFailure } from "../expected-delivery-failure.js";
+import { type AttrValue, attrs } from "./attrs.js";
+import type { OtelRuntime } from "./runtime.js";
+
+const CONTENT_MAX = 2_048;
+
+export interface OtelTurnContext {
+  sessionId: string;
+  session: SessionInfo;
+  turnId: string;
+}
+
+export interface OtelCallContext extends OtelTurnContext {
+  callId: string;
+  toolName: string;
+}
+
+export interface OtelCollector {
+  onEvent(event: SessionEvent, session: SessionInfo): void;
+  close(): void;
+  /**
+   * Run `fn` under the turn span so outbound inject sees that context.
+   * Host files / VFS / Factory RPCs during `runner.runTurn` are not
+   * inside `runInCall`. Opens the turn if `turn.started` has not been
+   * applied yet (dispatch is async).
+   */
+  runInTurn<T>(args: OtelTurnContext, fn: () => T | Promise<T>): Promise<T>;
+  /**
+   * Run `fn` under the tool span so outbound inject sees that context.
+   * Opens the turn / tool span if the event stream has not reached
+   * `actions.requested` yet (dispatch is async).
+   */
+  runInCall<T>(args: OtelCallContext, fn: () => T | Promise<T>): Promise<T>;
+  /** Merge author tags onto the session; paints open spans immediately. */
+  setSessionAttributes(sessionId: string, attributes: Record<string, AttrValue>): void;
+  /** Session tags previously set by {@link setSessionAttributes}. */
+  getSessionAttributes(sessionId: string): Record<string, AttrValue> | undefined;
+}
+
+interface TurnState {
+  span: Span;
+  tools: Map<string, Span>;
+  subagents: Map<string, Span>;
+  /** True when opened without `turn.started` (restore / direct callTool). */
+  synthetic: boolean;
+}
+
+/** Per-conversation bag for in-flight turns. No session span — those
+ * stay open across `session.waiting` and never export on hosted
+ * conversational agents. Each turn is its own root. */
+interface SessionState {
+  turns: Map<string, TurnState>;
+}
+
+export function createOtelCollector(
+  runtime: OtelRuntime,
+  agentName: string,
+  log: (line: string) => void,
+): OtelCollector {
+  const sessions = new Map<string, SessionState>();
+  const extraBySession = new Map<string, Record<string, AttrValue>>();
+  const metrics = runtime.meter ? buildMetrics(runtime.meter) : undefined;
+  const logOpts = runtime.config.logs === false ? undefined : runtime.config.logs;
+
+  return {
+    onEvent(event, session) {
+      try {
+        handle(event, session);
+      } catch (error) {
+        log(
+          `[agent-sdk:otel] collector failed on ${event.type}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    },
+    close() {
+      for (const [sessionId, state] of sessions) {
+        for (const turn of state.turns.values()) {
+          endOpenChildren(turn, undefined);
+          turn.span.setStatus({ code: SpanStatusCode.UNSET });
+          turn.span.end();
+        }
+        sessions.delete(sessionId);
+      }
+      extraBySession.clear();
+    },
+    setSessionAttributes(sessionId, attributes) {
+      const bag = extraBySession.get(sessionId) ?? {};
+      Object.assign(bag, attributes);
+      extraBySession.set(sessionId, bag);
+      paintOpenSpans(sessionId, attributes);
+    },
+    getSessionAttributes(sessionId) {
+      const bag = extraBySession.get(sessionId);
+      return bag === undefined ? undefined : { ...bag };
+    },
+    runInTurn(args, fn) {
+      const span = ensureTurnSpan(args);
+      return context.with(trace.setSpan(context.active(), span), () => Promise.resolve(fn()));
+    },
+    runInCall(args, fn) {
+      const span = ensureCallSpan(args);
+      return context.with(trace.setSpan(context.active(), span), () => Promise.resolve(fn()));
+    },
+  };
+
+  function handle(event: SessionEvent, session: SessionInfo): void {
+    const at = Date.parse(event.at);
+    const startTime = Number.isFinite(at) ? at : undefined;
+
+    switch (event.type) {
+      case "session.started": {
+        if (sessions.has(event.sessionId)) {
+          return;
+        }
+        sessionState(event.sessionId);
+        metrics?.sessions.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.channel": event.data.channelId,
+          }),
+        );
+        return;
+      }
+      case "agent.bound": {
+        const painted = attrs({
+          "agent_sdk.sdk_agent_id": event.data.sdkAgentId,
+          "agent_sdk.sdk_agent_url": logOpts?.toolContent === true ? event.data.url : undefined,
+        });
+        if (Object.keys(painted).length === 0) {
+          return;
+        }
+        const bag = extraBySession.get(event.sessionId) ?? {};
+        Object.assign(bag, painted);
+        extraBySession.set(event.sessionId, bag);
+        paintOpenSpans(event.sessionId, painted);
+        return;
+      }
+      case "message.received": {
+        emitLog(
+          "message.received",
+          SeverityNumber.INFO,
+          attrs({
+            ...baseLog(event, session),
+            "agent_sdk.user_prompt":
+              logOpts?.userPrompts === true ? truncate(event.data.text) : undefined,
+          }),
+        );
+        return;
+      }
+      case "turn.started": {
+        if (event.turnId === undefined) {
+          return;
+        }
+        const state = sessionState(event.sessionId);
+        // `runInCall` can open a synthetic turn before this event is
+        // applied. Keep that entry (and its in-flight tool spans) and
+        // just mark it real so `action.result` will not auto-close it.
+        const existing = state.turns.get(event.turnId);
+        if (existing !== undefined) {
+          existing.synthetic = false;
+          existing.span.setAttribute("agent_sdk.turn_synthetic", false);
+          return;
+        }
+        openTurn({
+          state,
+          sessionId: event.sessionId,
+          turnId: event.turnId,
+          session,
+          startTime,
+          synthetic: false,
+        });
+        return;
+      }
+      case "step.started":
+      case "step.completed": {
+        ensureTurn(event, session, startTime)?.span.addEvent(
+          event.type,
+          attrs({
+            "agent_sdk.step_id": event.data.stepId,
+            "agent_sdk.duration_ms":
+              event.type === "step.completed" ? event.data.durationMs : undefined,
+          }),
+          startTime,
+        );
+        return;
+      }
+      case "reasoning.completed": {
+        ensureTurn(event, session, startTime)?.span.addEvent(
+          "reasoning.completed",
+          attrs({
+            "agent_sdk.duration_ms": event.data.durationMs,
+            "agent_sdk.parent_call_id": event.data.parentCallId,
+          }),
+          startTime,
+        );
+        return;
+      }
+      case "message.completed": {
+        ensureTurn(event, session, startTime)?.span.addEvent(
+          "message.completed",
+          attrs({
+            "agent_sdk.finish_reason": event.data.finishReason,
+            "agent_sdk.parent_call_id": event.data.parentCallId,
+          }),
+          startTime,
+        );
+        return;
+      }
+      case "actions.requested": {
+        const turn = ensureTurn(event, session, startTime);
+        if (turn === undefined) {
+          return;
+        }
+        for (const call of event.data.calls) {
+          openToolSpan({
+            turn,
+            sessionId: event.sessionId,
+            turnId: event.turnId,
+            call,
+            parentCallId: event.data.parentCallId ?? call.parentCallId,
+            startTime,
+          });
+        }
+        return;
+      }
+      case "action.approval_requested": {
+        ensureTurn(event, session, startTime)
+          ?.tools.get(event.data.callId)
+          ?.addEvent("approval_requested", undefined, startTime);
+        emitLog(
+          "action.approval_requested",
+          SeverityNumber.INFO,
+          attrs({
+            ...baseLog(event, session),
+            "cursor.tool.name": event.data.toolName,
+            "agent_sdk.call_id": event.data.callId,
+          }),
+        );
+        return;
+      }
+      case "action.approval_resolved": {
+        ensureTurn(event, session, startTime)
+          ?.tools.get(event.data.callId)
+          ?.addEvent(
+            "approval_resolved",
+            attrs({
+              "agent_sdk.decision": event.data.decision,
+              "agent_sdk.decision_by": event.data.by,
+            }),
+            startTime,
+          );
+        return;
+      }
+      case "action.auth_requested": {
+        ensureTurn(event, session, startTime)
+          ?.tools.get(event.data.callId)
+          ?.addEvent("auth_requested", undefined, startTime);
+        emitLog(
+          "action.auth_requested",
+          SeverityNumber.INFO,
+          attrs({
+            ...baseLog(event, session),
+            "cursor.tool.name": event.data.toolName,
+            "agent_sdk.call_id": event.data.callId,
+            "agent_sdk.mcp_connection": event.data.connection,
+          }),
+        );
+        return;
+      }
+      case "action.auth_resolved": {
+        ensureTurn(event, session, startTime)
+          ?.tools.get(event.data.callId)
+          ?.addEvent(
+            "auth_resolved",
+            attrs({
+              "agent_sdk.decision": event.data.decision,
+              "agent_sdk.decision_by": event.data.by,
+              "agent_sdk.mcp_connection": event.data.connection,
+            }),
+            startTime,
+          );
+        return;
+      }
+      case "action.result": {
+        const turn = ensureTurn(event, session, startTime);
+        const span = turn?.tools.get(event.data.callId);
+        const status = event.data.isError ? "failure" : "success";
+        if (span !== undefined) {
+          span.setAttribute("cursor.tool.status", status);
+          if (logOpts?.toolContent === true && event.data.output !== undefined) {
+            span.setAttribute("agent_sdk.tool_output", truncate(json(event.data.output)));
+          }
+          if (event.data.isError) {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: "tool error",
+            });
+          }
+          span.end(startTime);
+          turn?.tools.delete(event.data.callId);
+        }
+        metrics?.toolCalls.add(
+          1,
+          join(event.sessionId, {
+            "cursor.tool.name": event.data.toolName,
+            "cursor.tool.kind": "builtin",
+            "cursor.tool.status": status,
+            "agent_sdk.agent": agentName,
+          }),
+        );
+        emitLog(
+          "action.result",
+          event.data.isError ? SeverityNumber.ERROR : SeverityNumber.INFO,
+          attrs({
+            ...baseLog(event, session),
+            "cursor.tool.name": event.data.toolName,
+            "cursor.tool.status": status,
+            "agent_sdk.call_id": event.data.callId,
+          }),
+        );
+        // Direct callTool never emits turn.completed — close when idle.
+        if (
+          turn !== undefined &&
+          turn.synthetic &&
+          turn.tools.size === 0 &&
+          turn.subagents.size === 0 &&
+          event.turnId !== undefined
+        ) {
+          turn.span.setStatus({ code: SpanStatusCode.OK });
+          turn.span.end(startTime);
+          sessions.get(event.sessionId)?.turns.delete(event.turnId);
+        }
+        return;
+      }
+      case "subagent.called": {
+        const turn = ensureTurn(event, session, startTime);
+        if (turn === undefined) {
+          return;
+        }
+        const span = runtime.tracer.startSpan(
+          "agent_sdk.subagent",
+          {
+            kind: SpanKind.INTERNAL,
+            startTime,
+            attributes: join(event.sessionId, {
+              "cursor.conversation.id": event.sessionId,
+              "agent_sdk.agent": agentName,
+              "agent_sdk.turn_id": event.turnId,
+              "agent_sdk.call_id": event.data.callId,
+              "agent_sdk.subagent_name": event.data.name,
+              "agent_sdk.subagent_description":
+                logOpts?.toolContent === true && event.data.description !== undefined
+                  ? truncate(event.data.description)
+                  : undefined,
+            }),
+          },
+          trace.setSpan(context.active(), turn.span),
+        );
+        turn.subagents.set(event.data.callId, span);
+        metrics?.subagents.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.subagent_name": event.data.name ?? "unknown",
+          }),
+        );
+        return;
+      }
+      case "subagent.completed": {
+        const turn = ensureTurn(event, session, startTime);
+        const span = turn?.subagents.get(event.data.callId);
+        if (span !== undefined) {
+          span.end(startTime);
+          turn?.subagents.delete(event.data.callId);
+        }
+        return;
+      }
+      case "artifact.tagged": {
+        const state = sessions.get(event.sessionId);
+        if (state === undefined) {
+          return;
+        }
+        const tagged = attrs({
+          "agent_sdk.artifact_id": event.data.id,
+          "agent_sdk.artifact_kind": event.data.kind,
+          "agent_sdk.artifact_key": event.data.key,
+          "agent_sdk.artifact_source": event.data.source,
+        });
+        for (const turn of state.turns.values()) {
+          turn.span.addEvent("artifact.tagged", tagged, startTime);
+        }
+        return;
+      }
+      case "turn.completed": {
+        const turn = ensureTurn(event, session, startTime);
+        if (turn === undefined || event.turnId === undefined) {
+          return;
+        }
+        endOpenChildren(turn, startTime);
+        const usage = event.data.usage;
+        const cost = event.data.cost;
+        if (usage !== undefined) {
+          turn.span.setAttributes(
+            attrs({
+              "agent_sdk.usage.input_tokens": usage.inputTokens,
+              "agent_sdk.usage.output_tokens": usage.outputTokens,
+              "agent_sdk.usage.cache_read_tokens": usage.cacheReadTokens,
+              "agent_sdk.usage.cache_write_tokens": usage.cacheWriteTokens,
+              "agent_sdk.usage.reasoning_tokens": usage.reasoningTokens,
+            }),
+          );
+          recordTokens(event.sessionId, usage);
+        }
+        if (cost !== undefined) {
+          turn.span.setAttributes(
+            attrs({
+              "cursor.model.name": cost.model,
+              "agent_sdk.cost_usd": cost.totalUsd,
+              "agent_sdk.cost_source": cost.source,
+            }),
+          );
+          metrics?.cost.add(
+            cost.totalUsd,
+            join(event.sessionId, {
+              "cursor.model.name": cost.model,
+              "agent_sdk.agent": agentName,
+            }),
+          );
+        }
+        turn.span.setStatus({ code: SpanStatusCode.OK });
+        turn.span.end(startTime);
+        sessions.get(event.sessionId)?.turns.delete(event.turnId);
+        metrics?.turns.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.turn_status": "completed",
+          }),
+        );
+        emitLog(
+          "turn.completed",
+          SeverityNumber.INFO,
+          attrs({
+            ...baseLog(event, session),
+            "agent_sdk.usage.input_tokens": usage?.inputTokens,
+            "agent_sdk.usage.output_tokens": usage?.outputTokens,
+            "agent_sdk.cost_usd": cost?.totalUsd,
+            "cursor.model.name": cost?.model,
+          }),
+        );
+        return;
+      }
+      case "turn.failed": {
+        const turn = ensureTurn(event, session, startTime);
+        if (turn === undefined || event.turnId === undefined) {
+          return;
+        }
+        endOpenChildren(turn, startTime);
+        // Classify from the raw message. Gated text may be absent, and the
+        // span attribute is only the bounded reason — never the message.
+        // Expected customer-state failures stay OK so span-metric
+        // `status:error` numerators (security reviewer turn/stage/module
+        // duration) do not count them.
+        const expected = classifyExpectedDeliveryFailure(event.data.message);
+        const failureText = gatedContent(event.data.message);
+        if (expected !== undefined) {
+          turn.span.setAttribute("agent_sdk.expected_error", expected);
+          turn.span.setStatus({ code: SpanStatusCode.OK });
+        } else {
+          turn.span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: failureText ?? "turn failed",
+          });
+          if (failureText !== undefined) {
+            turn.span.recordException(new Error(failureText));
+          }
+        }
+        turn.span.end(startTime);
+        sessions.get(event.sessionId)?.turns.delete(event.turnId);
+        metrics?.turns.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.turn_status": expected ?? "failed",
+          }),
+        );
+        emitLog(
+          "turn.failed",
+          expected === undefined ? SeverityNumber.ERROR : SeverityNumber.WARN,
+          attrs({
+            ...baseLog(event, session),
+            "agent_sdk.error_message": failureText,
+            "agent_sdk.expected_error": expected,
+          }),
+        );
+        return;
+      }
+      case "session.completed": {
+        endSession({
+          sessionId: event.sessionId,
+          code: SpanStatusCode.OK,
+          message: undefined,
+          endTime: startTime,
+        });
+        return;
+      }
+      case "session.failed": {
+        const expected = classifyExpectedDeliveryFailure(event.data.message);
+        const failureText = gatedContent(event.data.message);
+        if (expected !== undefined) {
+          const state = sessions.get(event.sessionId);
+          for (const turn of state?.turns.values() ?? []) {
+            turn.span.setAttribute("agent_sdk.expected_error", expected);
+          }
+        }
+        endSession({
+          sessionId: event.sessionId,
+          code: expected === undefined ? SpanStatusCode.ERROR : SpanStatusCode.OK,
+          message: expected === undefined ? (failureText ?? "session failed") : undefined,
+          endTime: startTime,
+        });
+        emitLog(
+          "session.failed",
+          expected === undefined ? SeverityNumber.ERROR : SeverityNumber.WARN,
+          attrs({
+            ...baseLog(event, session),
+            "agent_sdk.error_message": failureText,
+            "agent_sdk.expected_error": expected,
+          }),
+        );
+        return;
+      }
+      default:
+        return;
+    }
+  }
+
+  function sessionState(sessionId: string): SessionState {
+    const existing = sessions.get(sessionId);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const state: SessionState = { turns: new Map() };
+    sessions.set(sessionId, state);
+    return state;
+  }
+
+  /**
+   * Direct `callTool` and post-restore turns may emit tool events without
+   * a prior `turn.started` in this process — open a synthetic turn span.
+   */
+  function ensureTurn(
+    event: SessionEvent,
+    session: SessionInfo,
+    startTime: number | undefined,
+  ): TurnState | undefined {
+    if (event.turnId === undefined) {
+      return undefined;
+    }
+    const state = sessionState(event.sessionId);
+    const existing = state.turns.get(event.turnId);
+    if (existing !== undefined) {
+      return existing;
+    }
+    return openTurn({
+      state,
+      sessionId: event.sessionId,
+      turnId: event.turnId,
+      session,
+      startTime,
+      synthetic: true,
+    });
+  }
+
+  function openTurn(args: {
+    state: SessionState;
+    sessionId: string;
+    turnId: string;
+    session: SessionInfo;
+    startTime: number | undefined;
+    synthetic: boolean;
+  }): TurnState {
+    const span = runtime.tracer.startSpan(
+      "agent_sdk.turn",
+      {
+        kind: SpanKind.INTERNAL,
+        startTime: args.startTime,
+        attributes: join(args.sessionId, {
+          "cursor.conversation.id": args.sessionId,
+          "agent_sdk.agent": agentName,
+          "agent_sdk.turn_id": args.turnId,
+          "agent_sdk.channel": args.session.channelId,
+          "agent_sdk.session_mode": args.session.mode,
+          "agent_sdk.session_purpose": args.session.purpose ?? "live",
+          "agent_sdk.turn_synthetic": args.synthetic ? true : undefined,
+        }),
+      },
+      ROOT_CONTEXT,
+    );
+    const turn: TurnState = {
+      span,
+      tools: new Map(),
+      subagents: new Map(),
+      synthetic: args.synthetic,
+    };
+    args.state.turns.set(args.turnId, turn);
+    return turn;
+  }
+
+  function parentCtxFor(turn: TurnState, parentCallId: string | undefined): Context {
+    if (parentCallId !== undefined) {
+      const sub = turn.subagents.get(parentCallId);
+      if (sub !== undefined) {
+        return trace.setSpan(context.active(), sub);
+      }
+    }
+    return trace.setSpan(context.active(), turn.span);
+  }
+
+  function openToolSpan(args: {
+    turn: TurnState;
+    sessionId: string;
+    turnId: string | undefined;
+    call: {
+      callId: string;
+      toolName: string;
+      args?: unknown;
+      parentCallId?: string;
+    };
+    parentCallId?: string;
+    startTime: number | undefined;
+  }): Span {
+    const existing = args.turn.tools.get(args.call.callId);
+    if (existing !== undefined) {
+      // Early `runInCall` opens with callId/toolName only. Fill in
+      // parent linkage and opt-in args when `actions.requested` arrives.
+      // The OTel parent is fixed at start; `parent_call_id` still records
+      // the event-stream hierarchy for nested/subagent calls.
+      existing.setAttributes(
+        join(args.sessionId, {
+          "agent_sdk.parent_call_id": args.parentCallId ?? args.call.parentCallId,
+          "agent_sdk.tool_args":
+            logOpts?.toolContent === true && args.call.args !== undefined
+              ? truncate(json(args.call.args))
+              : undefined,
+        }),
+      );
+      return existing;
+    }
+    const span = runtime.tracer.startSpan(
+      "agent_sdk.tool",
+      {
+        kind: SpanKind.INTERNAL,
+        startTime: args.startTime,
+        attributes: join(args.sessionId, {
+          "cursor.conversation.id": args.sessionId,
+          "cursor.tool.name": args.call.toolName,
+          "cursor.tool.kind": "builtin",
+          "agent_sdk.agent": agentName,
+          "agent_sdk.turn_id": args.turnId,
+          "agent_sdk.call_id": args.call.callId,
+          "agent_sdk.parent_call_id": args.call.parentCallId,
+          "agent_sdk.tool_args":
+            logOpts?.toolContent === true && args.call.args !== undefined
+              ? truncate(json(args.call.args))
+              : undefined,
+        }),
+      },
+      parentCtxFor(args.turn, args.parentCallId ?? args.call.parentCallId),
+    );
+    args.turn.tools.set(args.call.callId, span);
+    return span;
+  }
+
+  function ensureTurnState(args: OtelTurnContext): TurnState {
+    const startTime = Date.now();
+    const state = sessionState(args.sessionId);
+    return (
+      state.turns.get(args.turnId) ??
+      openTurn({
+        state,
+        sessionId: args.sessionId,
+        turnId: args.turnId,
+        session: args.session,
+        startTime,
+        synthetic: true,
+      })
+    );
+  }
+
+  function ensureTurnSpan(args: OtelTurnContext): Span {
+    return ensureTurnState(args).span;
+  }
+
+  function ensureCallSpan(args: OtelCallContext): Span {
+    const turn = ensureTurnState(args);
+    return openToolSpan({
+      turn,
+      sessionId: args.sessionId,
+      turnId: args.turnId,
+      call: { callId: args.callId, toolName: args.toolName },
+      startTime: Date.now(),
+    });
+  }
+
+  function endOpenChildren(turn: TurnState, endTime: number | undefined): void {
+    for (const span of turn.tools.values()) {
+      span.end(endTime);
+    }
+    turn.tools.clear();
+    for (const span of turn.subagents.values()) {
+      span.end(endTime);
+    }
+    turn.subagents.clear();
+  }
+
+  function endSession(args: {
+    sessionId: string;
+    code: SpanStatusCode;
+    message: string | undefined;
+    endTime: number | undefined;
+  }): void {
+    const state = sessions.get(args.sessionId);
+    if (state === undefined) {
+      return;
+    }
+    for (const turn of state.turns.values()) {
+      endOpenChildren(turn, args.endTime);
+      if (args.message !== undefined) {
+        turn.span.setStatus({ code: args.code, message: args.message });
+      } else {
+        turn.span.setStatus({ code: args.code });
+      }
+      turn.span.end(args.endTime);
+    }
+    state.turns.clear();
+    sessions.delete(args.sessionId);
+    extraBySession.delete(args.sessionId);
+  }
+
+  function extra(sessionId: string): Record<string, AttrValue> {
+    return extraBySession.get(sessionId) ?? {};
+  }
+
+  function join(
+    sessionId: string,
+    rest: Record<string, AttrValue | undefined>,
+  ): Record<string, AttrValue> {
+    return attrs({
+      ...extra(sessionId),
+      "cursor.conversation.id": sessionId,
+      "agent_sdk.session_id": sessionId,
+      ...rest,
+    });
+  }
+
+  function paintOpenSpans(sessionId: string, incoming: Record<string, AttrValue>): void {
+    const state = sessions.get(sessionId);
+    if (state === undefined) {
+      return;
+    }
+    const painted = attrs(incoming);
+    if (Object.keys(painted).length === 0) {
+      return;
+    }
+    for (const turn of state.turns.values()) {
+      turn.span.setAttributes(painted);
+      for (const span of turn.tools.values()) {
+        span.setAttributes(painted);
+      }
+      for (const span of turn.subagents.values()) {
+        span.setAttributes(painted);
+      }
+    }
+  }
+
+  function recordTokens(
+    sessionId: string,
+    usage: {
+      inputTokens: number;
+      outputTokens: number;
+      cacheReadTokens: number;
+      cacheWriteTokens: number;
+      reasoningTokens?: number;
+    },
+  ): void {
+    if (metrics === undefined) {
+      return;
+    }
+    const agent = agentName;
+    // Wire token types match enterprise export (`cache_creation`, not write).
+    addTokens(sessionId, usage.inputTokens, "input", agent);
+    addTokens(sessionId, usage.outputTokens, "output", agent);
+    addTokens(sessionId, usage.cacheReadTokens, "cache_read", agent);
+    addTokens(sessionId, usage.cacheWriteTokens, "cache_creation", agent);
+    if (usage.reasoningTokens !== undefined) {
+      // Reasoning is Agent-SDK-only; enterprise wire has no reasoning enum.
+      metrics.tokens.add(
+        usage.reasoningTokens,
+        join(sessionId, {
+          "cursor.token.type": "reasoning",
+          "agent_sdk.agent": agent,
+        }),
+      );
+    }
+  }
+
+  function addTokens(
+    sessionId: string,
+    value: number,
+    type: "input" | "output" | "cache_read" | "cache_creation",
+    agent: string,
+  ): void {
+    if (metrics === undefined || value === 0) {
+      return;
+    }
+    metrics.tokens.add(
+      value,
+      join(sessionId, {
+        "cursor.token.type": type,
+        "agent_sdk.agent": agent,
+      }),
+    );
+  }
+
+  /** Content opt-in for failure text (same gate as tool payloads). */
+  function gatedContent(value: string): string | undefined {
+    if (logOpts?.toolContent !== true) {
+      return undefined;
+    }
+    return truncate(value);
+  }
+
+  function baseLog(
+    event: SessionEvent,
+    session: SessionInfo,
+  ): Record<string, AttrValue | undefined> {
+    return {
+      "cursor.conversation.id": event.sessionId,
+      "agent_sdk.event": event.type,
+      "agent_sdk.agent": agentName,
+      "agent_sdk.channel": session.channelId,
+      "agent_sdk.turn_id": event.turnId,
+    };
+  }
+
+  function emitLog(
+    eventName: string,
+    severity: SeverityNumber,
+    attributes: Record<string, AttrValue>,
+  ): void {
+    runtime.logger?.emit({
+      body: eventName,
+      severityNumber: severity,
+      attributes,
+    });
+  }
+}
+
+interface MetricSet {
+  sessions: Counter;
+  turns: Counter;
+  toolCalls: Counter;
+  subagents: Counter;
+  tokens: Counter;
+  cost: Counter;
+}
+
+function buildMetrics(meter: Meter): MetricSet {
+  return {
+    sessions: meter.createCounter("agent_sdk.session.count", {
+      description: "Sessions started",
+      unit: "{session}",
+    }),
+    turns: meter.createCounter("agent_sdk.turn.count", {
+      description: "Turns completed or failed",
+      unit: "{turn}",
+    }),
+    // Wire-aligned name so collectors joining org export see one series family.
+    toolCalls: meter.createCounter("cursor.tool.calls", {
+      description: "Tool calls finished",
+      unit: "{call}",
+    }),
+    subagents: meter.createCounter("agent_sdk.subagent.count", {
+      description: "Subagent invocations",
+      unit: "{call}",
+    }),
+    tokens: meter.createCounter("cursor.token.usage", {
+      description: "Token usage by type",
+      unit: "{token}",
+    }),
+    cost: meter.createCounter("cursor.cost.usage", {
+      description: "Estimated turn cost in USD",
+      unit: "USD",
+    }),
+  };
+}
+
+function truncate(value: string): string {
+  if (value.length <= CONTENT_MAX) {
+    return value;
+  }
+  return `${value.slice(0, CONTENT_MAX)}…`;
+}
+
+function json(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}