@introspection-sdk/introspection-node 0.4.2 → 0.4.3

package/src/{claude-hooks.ts → otel/claude-hooks.ts}

@@ -9,10 +9,12 @@
 
 import {
   context as otelContext,
+  propagation,
   trace as otelTrace,
   Span as OtelSpan,
   SpanKind,
   SpanStatusCode,
+  type Attributes,
 } from "@opentelemetry/api";
 import {
   BasicTracerProvider,
@@ -28,12 +30,12 @@ import {
 } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 
-import { logger, withOtlpHttpsProxy } from "./utils.js";
-import { VERSION } from "./version.js";
+import { logger, withOtlpHttpsProxy } from "../utils.js";
+import { VERSION } from "../version.js";
 import {
   convertClaudeSessionToOtelAttributes,
   type ClaudeContentBlock,
-} from "./converters/claude.js";
+} from "../converters/claude.js";
 
 // ---------------------------------------------------------------------------
 // Claude Agent SDK Hook types
@@ -241,6 +243,8 @@ export interface ClaudeAssistantMessage {
     usage?: {
       input_tokens?: number;
       output_tokens?: number;
+      cache_read_input_tokens?: number;
+      cache_creation_input_tokens?: number;
     };
     content?: Array<{ type: string; text?: string }>;
   };
@@ -271,12 +275,16 @@ export interface ClaudeHooksAdvancedOptions {
 export interface IntrospectionClaudeHooksOptions {
   /** Authentication token (env: INTROSPECTION_TOKEN) */
   token?: string;
-  /** Base URL for the API (env: INTROSPECTION_BASE_URL) */
+  /** Base URL for the API (env: INTROSPECTION_BASE_OTEL_URL) */
   baseUrl?: string;
   /** Service name for the OTel resource (defaults to "claude-agent") */
   serviceName?: string;
   /** Agent name set on session spans as gen_ai.agent.name (defaults to serviceName) */
   agentName?: string;
+  /** Agent ID set on session spans as gen_ai.agent.id */
+  agentId?: string;
+  /** Conversation ID set on session spans as gen_ai.conversation.id */
+  conversationId?: string;
   /** Additional headers to include in requests */
   additionalHeaders?: Record<string, string>;
   /** Advanced options for testing and customization */
@@ -319,6 +327,8 @@ export class IntrospectionClaudeHooks {
   private _tracerProvider: BasicTracerProvider;
   private _tracer: ReturnType<BasicTracerProvider["getTracer"]>;
   private _agentName: string;
+  private _agentId?: string;
+  private _conversationId?: string;
   private _sessionSpans: Map<string, OtelSpan> = new Map();
   private _toolSpans: Map<string, OtelSpan> = new Map();
   private _subagentSpans: Map<string, OtelSpan> = new Map();
@@ -327,6 +337,8 @@ export class IntrospectionClaudeHooks {
     {
       input: number;
       output: number;
+      cacheRead: number;
+      cacheCreation: number;
       cost?: number;
       model?: string;
       inputPrompt?: string;
@@ -343,6 +355,8 @@ export class IntrospectionClaudeHooks {
     const advanced = options.advanced;
     const serviceName = options.serviceName || "claude-agent";
     this._agentName = options.agentName || serviceName;
+    this._agentId = options.agentId;
+    this._conversationId = options.conversationId;
     const resource = defaultResource().merge(
       resourceFromAttributes({ [ATTR_SERVICE_NAME]: serviceName }),
     );
@@ -355,7 +369,7 @@ export class IntrospectionClaudeHooks {
 
       const baseUrl =
         options.baseUrl ||
-        process.env.INTROSPECTION_BASE_URL ||
+        process.env.INTROSPECTION_BASE_OTEL_URL ||
         "https://otel.introspection.dev";
 
       const headers: Record<string, string> = {
@@ -455,6 +469,32 @@ export class IntrospectionClaudeHooks {
     };
   }
 
+  /**
+   * Resolve effective agent / conversation identity for a session, in order
+   * of precedence: OTel baggage on the active context > constructor option >
+   * the Claude session ID. Lets callers override identity per-invocation via
+   * `IntrospectionClient.withAgent()` / `.withConversation()` without
+   * having to construct a new hooks instance per call.
+   *
+   * Requires an active context manager — see {@link setupTracing}.
+   */
+  private _resolveIdentity(sessionId: string): {
+    agentName: string;
+    agentId?: string;
+    conversationId: string;
+  } {
+    const baggage = propagation.getBaggage(otelContext.active());
+    const baggageAgentName = baggage?.getEntry("gen_ai.agent.name")?.value;
+    const baggageAgentId = baggage?.getEntry("gen_ai.agent.id")?.value;
+    const baggageConvId = baggage?.getEntry("gen_ai.conversation.id")?.value;
+
+    return {
+      agentName: baggageAgentName || this._agentName,
+      agentId: baggageAgentId || this._agentId,
+      conversationId: baggageConvId || this._conversationId || sessionId,
+    };
+  }
+
   /**
    * Set the input prompt for a session so it appears as
    * `gen_ai.input.messages` on the session span.
@@ -470,6 +510,8 @@ export class IntrospectionClaudeHooks {
       const existing = this._sessionUsage.get(sessionId) || {
         input: 0,
         output: 0,
+        cacheRead: 0,
+        cacheCreation: 0,
       };
       existing.inputPrompt = prompt;
       this._sessionUsage.set(sessionId, existing);
@@ -496,12 +538,17 @@ export class IntrospectionClaudeHooks {
       const existing = this._sessionUsage.get(sessionId) || {
         input: 0,
         output: 0,
+        cacheRead: 0,
+        cacheCreation: 0,
       };
       existing.systemInstructions = instructions;
       this._sessionUsage.set(sessionId, existing);
     } else {
       this._pendingSystemInstructions = instructions;
     }
+    logger.info(
+      `System instructions set (${instructions.length} chars)${sessionId ? ` for session ${sessionId}` : " (pending)"}`,
+    );
   }
 
   private _pendingSystemInstructions?: string;
@@ -530,6 +577,8 @@ export class IntrospectionClaudeHooks {
       const existing = this._sessionUsage.get(sessionId) || {
         input: 0,
         output: 0,
+        cacheRead: 0,
+        cacheCreation: 0,
       };
 
       // Track usage
@@ -537,6 +586,8 @@ export class IntrospectionClaudeHooks {
       if (usage) {
         existing.input += usage.input_tokens || 0;
         existing.output += usage.output_tokens || 0;
+        existing.cacheRead += usage.cache_read_input_tokens || 0;
+        existing.cacheCreation += usage.cache_creation_input_tokens || 0;
         if (assistantMsg.message?.model) {
           existing.model = assistantMsg.message.model;
         }
@@ -575,12 +626,31 @@ export class IntrospectionClaudeHooks {
       const existing = this._sessionUsage.get(sessionId) || {
         input: 0,
         output: 0,
+        cacheRead: 0,
+        cacheCreation: 0,
       };
 
       if (resultMsg.usage) {
         // Result message has final totals
         existing.input = resultMsg.usage.input_tokens || existing.input;
         existing.output = resultMsg.usage.output_tokens || existing.output;
+        if (resultMsg.usage.cache_read_input_tokens != null) {
+          existing.cacheRead = resultMsg.usage.cache_read_input_tokens;
+        }
+        if (resultMsg.usage.cache_creation_input_tokens != null) {
+          existing.cacheCreation = resultMsg.usage.cache_creation_input_tokens;
+        }
+      }
+      // Fallback: aggregate cache tokens from per-model breakdown when top-level usage omits them
+      if (
+        resultMsg.modelUsage &&
+        existing.cacheRead === 0 &&
+        existing.cacheCreation === 0
+      ) {
+        for (const modelData of Object.values(resultMsg.modelUsage)) {
+          existing.cacheRead += modelData.cacheReadInputTokens || 0;
+          existing.cacheCreation += modelData.cacheCreationInputTokens || 0;
+        }
       }
       if (resultMsg.total_cost_usd !== undefined) {
         existing.cost = resultMsg.total_cost_usd;
@@ -617,16 +687,23 @@ export class IntrospectionClaudeHooks {
     }
 
     logger.debug(`Starting session span from init message: ${sessionId}`);
+    const ids = this._resolveIdentity(sessionId);
+    const attrs: Attributes = {
+      "gen_ai.system": "anthropic",
+      "gen_ai.operation.name": "chat",
+      "gen_ai.agent.name": ids.agentName,
+      "gen_ai.conversation.id": ids.conversationId,
+      "claude.session_id": sessionId,
+      "claude.source": "message",
+    };
+
+    if (ids.agentId) {
+      attrs["gen_ai.agent.id"] = ids.agentId;
+    }
 
     const span = this._tracer.startSpan("claude.session", {
       kind: SpanKind.CLIENT,
-      attributes: {
-        "gen_ai.system": "anthropic",
-        "gen_ai.operation.name": "chat",
-        "gen_ai.agent.name": this._agentName,
-        "claude.session_id": sessionId,
-        "claude.source": "message",
-      },
+      attributes: attrs,
     });
 
     // Add model if present in init message
@@ -651,12 +728,14 @@ export class IntrospectionClaudeHooks {
     const sessionData: {
       input: number;
       output: number;
+      cacheRead: number;
+      cacheCreation: number;
       model?: string;
       inputPrompt?: string;
       responseContent?: string;
       toolNames?: string[];
       systemInstructions?: string;
-    } = { input: 0, output: 0, model };
+    } = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0, model };
 
     if (tools && tools.length > 0) {
       sessionData.toolNames = tools;
@@ -701,6 +780,8 @@ export class IntrospectionClaudeHooks {
       model: usage?.model,
       inputTokens: usage?.input,
       outputTokens: usage?.output,
+      cacheReadInputTokens: usage?.cacheRead || undefined,
+      cacheCreationInputTokens: usage?.cacheCreation || undefined,
       costUsd: usage?.cost,
       stopReason: usage?.stopReason,
       responseId: usage?.responseId,
@@ -747,15 +828,27 @@ export class IntrospectionClaudeHooks {
     const sessionInput = input as SessionStartHookInput;
     logger.debug(`SessionStart hook: ${sessionInput.session_id}`);
 
+    // Resolve identity via _resolveIdentity so baggage on the active context
+    // takes precedence over constructor defaults, matching the message-init
+    // path in _startSessionFromMessage. Without this, the SessionStart hook
+    // would always stamp the constructor-time agentName / sessionId even
+    // when the caller wrapped the query in withAgent() / withConversation().
+    const ids = this._resolveIdentity(sessionInput.session_id);
+    const attrs: Attributes = {
+      "gen_ai.system": "anthropic",
+      "gen_ai.operation.name": "chat",
+      "gen_ai.agent.name": ids.agentName,
+      "gen_ai.conversation.id": ids.conversationId,
+      "claude.session_id": sessionInput.session_id,
+      "claude.source": sessionInput.source,
+    };
+    if (ids.agentId) {
+      attrs["gen_ai.agent.id"] = ids.agentId;
+    }
+
     const span = this._tracer.startSpan("claude.session", {
       kind: SpanKind.CLIENT,
-      attributes: {
-        "gen_ai.system": "anthropic",
-        "gen_ai.operation.name": "chat",
-        "gen_ai.agent.name": this._agentName,
-        "claude.session_id": sessionInput.session_id,
-        "claude.source": sessionInput.source,
-      },
+      attributes: attrs,
     });
 
     if (sessionInput.model) {
@@ -771,11 +864,15 @@ export class IntrospectionClaudeHooks {
     const sessionUsage: {
       input: number;
       output: number;
+      cacheRead: number;
+      cacheCreation: number;
       inputPrompt?: string;
       systemInstructions?: string;
     } = {
       input: 0,
       output: 0,
+      cacheRead: 0,
+      cacheCreation: 0,
     };
     if (this._pendingInputPrompt) {
       sessionUsage.inputPrompt = this._pendingInputPrompt;
@@ -813,6 +910,8 @@ export class IntrospectionClaudeHooks {
           model: usage.model,
           inputTokens: usage.input,
           outputTokens: usage.output,
+          cacheReadInputTokens: usage.cacheRead || undefined,
+          cacheCreationInputTokens: usage.cacheCreation || undefined,
           costUsd: usage.cost,
           stopReason: usage.stopReason,
           responseId: usage.responseId,

package/src/{claude-wrapper.ts → otel/claude-wrapper.ts}

@@ -26,7 +26,7 @@ import {
   type ClaudeHooksConfig,
   type ClaudeSDKMessage,
 } from "./claude-hooks.js";
-import { logger } from "./utils.js";
+import { logger } from "../utils.js";
 
 // --- Public types ---