@introspection-sdk/introspection-node 0.4.1 → 0.4.3

package/src/index.ts

@@ -1,36 +1,18 @@
-import { IntrospectionSpanProcessor } from "./span-processor.js";
-import type { IntrospectionSpanProcessorOptions } from "./span-processor.js";
-
 /**
- * Factory that creates an {@link IntrospectionSpanProcessor}.
- *
- * Provided as the default export for convenient use with logfire's
- * `additionalSpanProcessors` option.
+ * Root entry point — REST-only surface.
  *
- * @param options - Optional processor configuration (token, serviceName, etc.).
- * @returns A ready-to-use {@link IntrospectionSpanProcessor}.
+ * Exports `IntrospectionClient` (REST), Runner / RuntimeHandle /
+ * ExperimentHandle, REST wire types, and HTTP helpers. None of these
+ * touch the OpenTelemetry SDK.
  *
- * @example
- * ```ts
- * import introspectionSpanProcessor from "@introspection-sdk/introspection-node";
- *
- * logfire.configure({ additionalSpanProcessors: [introspectionSpanProcessor()] });
- * ```
+ * For the OTel surface (logs, span processors, instrumentors) import
+ * from `@introspection-sdk/introspection-node/otel`.
  */
-export default function introspectionSpanProcessor(
-  options?: IntrospectionSpanProcessorOptions,
-): IntrospectionSpanProcessor {
-  return new IntrospectionSpanProcessor(options);
-}
-
-// Span processor exports (for OpenTelemetry integration)
-export { IntrospectionSpanProcessor } from "./span-processor.js";
-export type { IntrospectionSpanProcessorOptions } from "./span-processor.js";
 
-// Client exports
+// REST client.
 export { IntrospectionClient } from "./client.js";
 
-// Type exports
+// Configuration / event types shared with the OTel surface.
 export type {
   AdvancedOptions,
   IntrospectionClientOptions,
@@ -38,40 +20,98 @@ export type {
   UserTraits,
 } from "./types.js";
 
-// Tracing processor exports (for OpenAI Agents SDK integration)
-export { IntrospectionTracingProcessor } from "./tracing-processor.js";
-export type {
-  IntrospectionTracingProcessorOptions,
-  TracingProcessorAdvancedOptions,
-} from "./tracing-processor.js";
+// Runner-bound REST namespaces (runner.tasks, runner.files) + HTTP/SSE.
+export { TasksApi, TaskRunsApi, RunHandle } from "./runner-resources/tasks.js";
+export type { StartParams } from "./runner-resources/tasks.js";
+export { FilesApi, FileVersionsApi } from "./runner-resources/files.js";
+export type { FileUploadBody } from "./runner-resources/files.js";
+export { HttpClient } from "./http.js";
+export type { ResolvedApiConfig } from "./http.js";
+export { parseSse } from "./streaming.js";
 
-// Claude Agent SDK hooks exports
-export { IntrospectionClaudeHooks } from "./claude-hooks.js";
-export type {
-  IntrospectionClaudeHooksOptions,
-  ClaudeHooksAdvancedOptions,
-  ClaudeHooksConfig,
-  ClaudeHookCallbackMatcher,
-  ClaudeHookEvent,
-  ClaudeHookInput,
-  ClaudeHookOutput,
-  ClaudeHookCallback,
-  ClaudeUsage,
-  ClaudeModelUsage,
-  ClaudeResultMessage,
-  ClaudeAssistantMessage,
-  ClaudeSDKMessage,
-} from "./claude-hooks.js";
+// Runner + CP resources.
+export { Runner } from "./runner.js";
+export type { RunnerSource } from "./runner.js";
+export {
+  RuntimesApi,
+  RuntimeHandle,
+  attachRuntimes,
+  isUuid,
+} from "./resources/runtimes.js";
+export type { RuntimeHandleFactory } from "./resources/runtimes.js";
+export {
+  ExperimentsApi,
+  ExperimentHandle,
+  attachExperiments,
+} from "./resources/experiments.js";
+export type { ExperimentHandleFactory } from "./resources/experiments.js";
+export { RecipesApi, attachRecipes } from "./resources/recipes.js";
 
-// Claude Agent SDK wrapper exports
-export { withIntrospection } from "./claude-wrapper.js";
+// REST API wire types
 export type {
-  WithIntrospectionOptions,
-  InstrumentedClaudeAgentSDK,
-  ClaudeAgentSDKModule,
-} from "./claude-wrapper.js";
+  Paginated,
+  ListParams,
+  Task,
+  TaskCreateParams,
+  TaskUpdateParams,
+  TaskListParams,
+  TaskMode,
+  TaskStatus,
+  TaskPrompt,
+  TaskRun,
+  TaskRunCreateParams,
+  TaskRunResponse,
+  TaskCreateResponse,
+  TaskCancelResponse,
+  AgentInfo,
+  File,
+  FileType,
+  FileListParams,
+  FileUpdateParams,
+  FileCreateTextParams,
+  SseEvent,
+  Runtime,
+  RuntimeCreate,
+  RuntimeUpdate,
+  RuntimeListParams,
+  Experiment,
+  ExperimentCreate,
+  ExperimentUpdate,
+  ExperimentListParams,
+  ExperimentStatus,
+  ExperimentEndParams,
+  Arm,
+  Recipe,
+  RecipeCreate,
+  RecipeUpdate,
+  RecipeListParams,
+  RunnerSpec,
+  RunnerDeployment,
+  RunnerContext,
+  RunnerRecipeSummary,
+  RunnerIdentity,
+  RunRequest,
+  RunCaller,
+  RunCallerLibrary,
+  RunCallerPage,
+  RunIdentityInput,
+} from "@introspection-sdk/types";
+export {
+  IntrospectionAPIError,
+  AuthenticationError,
+  InsufficientScopeError,
+  RunnerExpiredError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  RateLimitError,
+  SandboxUnavailableError,
+  StreamError,
+  NetworkError,
+  apiErrorFromResponse,
+} from "@introspection-sdk/types";
 
-// GenAI types exports
+// GenAI types (shared, no OTel SDK imports).
 export type {
   GenAiAttributes,
   InputMessage,
@@ -85,7 +125,7 @@ export type {
 } from "@introspection-sdk/types";
 export { toAttributes } from "@introspection-sdk/types";
 
-// OpenAI converter exports
+// OpenAI converter exports (pure functions, no OTel SDK imports).
 export {
   convertResponsesInputsToSemconv,
   convertResponsesOutputsToSemconv,
@@ -100,22 +140,17 @@ export type {
   Response as OpenAIResponse,
 } from "./converters/openai.js";
 
-// AI SDK integration exports (for Vercel AI SDK)
-export { IntrospectionAISDKIntegration } from "./ai-sdk-integration.js";
-export type {
-  IntrospectionAISDKIntegrationOptions,
-  AISDKIntegrationAdvancedOptions,
-} from "./ai-sdk-integration.js";
-
-// OpenInference converter exports
-export {
-  addOpenInferenceAttributes,
-  OpenInferenceSpanExporter,
-} from "./converters/openinference.js";
-
-// Anthropic instrumentor exports
+// Gemini converters (pure functions, no OTel SDK imports).
 export {
-  AnthropicInstrumentor,
-  tracedMessagesCreate,
-  REDACTED_THINKING_CONTENT,
-} from "./anthropic.js";
+  convertGeminiContentsToInputMessages,
+  convertGeminiCandidatesToOutputMessages,
+  convertGeminiSystemInstructionToSemconv,
+  convertGeminiToolsToToolDefinitions,
+} from "./converters/gemini.js";
+export type {
+  GeminiCandidate,
+  GeminiContent,
+  GeminiFunctionDeclaration,
+  GeminiPart,
+  GeminiTool,
+} from "./converters/gemini.js";

package/src/{anthropic.ts → otel/anthropic.ts}

@@ -24,7 +24,13 @@ import type {
   ReasoningPart,
 } from "@introspection-sdk/types";
 
-import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import {
+  trace,
+  context as otelContext,
+  propagation,
+  SpanKind,
+  SpanStatusCode,
+} from "@opentelemetry/api";
 import type { Tracer, Span } from "@opentelemetry/api";
 import type { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
 
@@ -154,7 +160,11 @@ function serializeMessages(msgs: InputMessage[] | OutputMessage[]): string {
   );
 }
 
-function startSpan(tracer: Tracer, model: string): { span: Span; token: null } {
+function startSpan(
+  tracer: Tracer,
+  model: string,
+  conversationId?: string,
+): { span: Span; token: null } {
   const span = tracer.startSpan("chat", {
     kind: SpanKind.CLIENT,
     attributes: {
@@ -163,6 +173,9 @@ function startSpan(tracer: Tracer, model: string): { span: Span; token: null } {
       "gen_ai.operation.name": "chat",
       "gen_ai.request.model": model,
       "openinference.span.kind": "LLM",
+      ...(conversationId
+        ? { "gen_ai.conversation.id": conversationId }
+        : undefined),
     },
   });
   return { span, token: null };
@@ -177,10 +190,26 @@ function setRequestAttrs(span: Span, kwargs: Record<string, unknown>): void {
 
   const system = kwargs.system;
   if (system) {
-    const sysVal =
-      typeof system === "string"
-        ? JSON.stringify([{ type: "text", content: system }])
-        : JSON.stringify(system);
+    let sysVal: string;
+    if (typeof system === "string") {
+      sysVal = JSON.stringify([{ type: "text", content: system }]);
+    } else if (Array.isArray(system)) {
+      // Anthropic block format: [{type:"text", text:"...", cache_control:{...}}]
+      // Normalize to gen_ai format: [{type:"text", content:"..."}]
+      sysVal = JSON.stringify(
+        (system as Array<Record<string, unknown>>).map((block) => ({
+          type: "text",
+          content:
+            typeof block.text === "string"
+              ? block.text
+              : typeof block.content === "string"
+                ? block.content
+                : "",
+        })),
+      );
+    } else {
+      sysVal = JSON.stringify(system);
+    }
     span.setAttribute("gen_ai.system_instructions", sysVal);
   }
 
@@ -219,6 +248,16 @@ function setResponseAttrs(span: Span, response: Record<string, unknown>): void {
       span.setAttribute("gen_ai.usage.input_tokens", usage.input_tokens);
     if (usage.output_tokens != null)
       span.setAttribute("gen_ai.usage.output_tokens", usage.output_tokens);
+    if (usage.cache_read_input_tokens != null)
+      span.setAttribute(
+        "gen_ai.usage.cache_read.input_tokens",
+        usage.cache_read_input_tokens,
+      );
+    if (usage.cache_creation_input_tokens != null)
+      span.setAttribute(
+        "gen_ai.usage.cache_creation.input_tokens",
+        usage.cache_creation_input_tokens,
+      );
   }
 
   span.setStatus({ code: SpanStatusCode.OK });
@@ -245,6 +284,8 @@ class TracedStream {
   private responseModel: string | null = null;
   private inputTokens = 0;
   private outputTokens = 0;
+  private cacheReadInputTokens = 0;
+  private cacheCreationInputTokens = 0;
   private finalized = false;
 
   constructor(inner: AsyncIterable<StreamEvent>, span: Span) {
@@ -268,7 +309,11 @@ class TracedStream {
       this.responseId = (event.message.id as string) || null;
       this.responseModel = (event.message.model as string) || null;
       const usage = event.message.usage as Record<string, number> | undefined;
-      if (usage) this.inputTokens = usage.input_tokens || 0;
+      if (usage) {
+        this.inputTokens = usage.input_tokens || 0;
+        this.cacheReadInputTokens = usage.cache_read_input_tokens || 0;
+        this.cacheCreationInputTokens = usage.cache_creation_input_tokens || 0;
+      }
     } else if (event.type === "content_block_start" && event.content_block) {
       const bt = (event.content_block.type as string) || "";
       this.currentBlock = { type: bt };
@@ -328,6 +373,16 @@ class TracedStream {
       this.span.setAttribute("gen_ai.usage.input_tokens", this.inputTokens);
     if (this.outputTokens)
       this.span.setAttribute("gen_ai.usage.output_tokens", this.outputTokens);
+    if (this.cacheReadInputTokens)
+      this.span.setAttribute(
+        "gen_ai.usage.cache_read.input_tokens",
+        this.cacheReadInputTokens,
+      );
+    if (this.cacheCreationInputTokens)
+      this.span.setAttribute(
+        "gen_ai.usage.cache_creation.input_tokens",
+        this.cacheCreationInputTokens,
+      );
     this.span.setStatus({ code: SpanStatusCode.OK });
     this.span.end();
   }
@@ -345,8 +400,13 @@ export async function tracedMessagesCreate(
   tracer: Tracer,
   client: { messages: { create: (...args: unknown[]) => Promise<unknown> } },
   kwargs: Record<string, unknown>,
+  conversationId?: string,
 ): Promise<unknown> {
-  const { span } = startSpan(tracer, (kwargs.model as string) || "unknown");
+  const { span } = startSpan(
+    tracer,
+    (kwargs.model as string) || "unknown",
+    conversationId,
+  );
   try {
     setRequestAttrs(span, kwargs);
     const response = (await client.messages.create(kwargs)) as Record<
@@ -382,12 +442,20 @@ export class AnthropicInstrumentor {
   private tracer: Tracer | null = null;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private patchedClients: Array<{ client: any; originalCreate: any }> = [];
+  private conversationId: string | undefined;
 
   instrument(opts: {
     tracerProvider?: BasicTracerProvider;
     /** The Anthropic client instance to instrument. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     client: any;
+    /**
+     * Conversation ID shared across all spans produced by this instrumentor.
+     * Enables the Introspection processor to reliably link multi-turn API calls
+     * into a single conversation without relying on history-hash matching.
+     * Defaults to a random UUID generated at instrument() time.
+     */
+    conversationId?: string;
   }): void {
     const { client } = opts;
     if (!client?.messages?.create) {
@@ -396,6 +464,8 @@ export class AnthropicInstrumentor {
       );
     }
 
+    this.conversationId = opts.conversationId ?? crypto.randomUUID();
+
     const provider = opts.tracerProvider ?? trace.getTracerProvider();
     this.tracer = (provider as BasicTracerProvider).getTracer(
       "introspection-anthropic",
@@ -404,16 +474,33 @@ export class AnthropicInstrumentor {
     const origCreate = client.messages.create.bind(client.messages);
     this.patchedClients.push({ client, originalCreate: origCreate });
     const tracer = this.tracer!;
+    const defaultConversationId = this.conversationId;
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     client.messages.create = function (...args: any[]) {
       const kwargs = args[0] as Record<string, unknown>;
       const isStream = kwargs?.stream === true;
 
+      // Baggage on the active context overrides the conversation ID bound
+      // at instrument() time, so callers can wrap a request in
+      // IntrospectionClient.withConversation() to scope a single call to a
+      // distinct conversation without re-instrumenting the client.
+      const baggage = propagation.getBaggage(otelContext.active());
+      const baggageConvId = baggage?.getEntry("gen_ai.conversation.id")?.value;
+      const baggageAgentName = baggage?.getEntry("gen_ai.agent.name")?.value;
+      const baggageAgentId = baggage?.getEntry("gen_ai.agent.id")?.value;
+
       const { span } = startSpan(
         tracer,
         (kwargs?.model as string) || "unknown",
+        baggageConvId ?? defaultConversationId,
       );
+      if (baggageAgentName) {
+        span.setAttribute("gen_ai.agent.name", baggageAgentName);
+      }
+      if (baggageAgentId) {
+        span.setAttribute("gen_ai.agent.id", baggageAgentId);
+      }
       setRequestAttrs(span, kwargs || {});
 
       if (isStream) {