@introspection-sdk/introspection-node 0.4.2 → 0.4.4

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<
@@ -378,16 +438,106 @@ export async function tracedMessagesCreate(
  * Captures all content blocks including thinking (extended thinking) with
  * signatures. Supports both non-streaming and streaming calls.
  */
+/**
+ * Build the traced replacement for `messages.create`.
+ *
+ * Shared by {@link AnthropicInstrumentor.instrument} (patches a single client
+ * instance) and {@link AnthropicInstrumentor.instrumentClass} (patches
+ * `Anthropic.Messages.prototype.create` so every client is auto-traced). The
+ * returned function preserves the call-site `this`, so it works whether it is
+ * assigned to an instance property or onto the class prototype.
+ */
+function buildTracedCreate(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  origCreate: (...args: any[]) => any,
+  tracer: Tracer,
+  defaultConversationId: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): (...args: any[]) => any {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function tracedCreate(this: unknown, ...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) {
+      const streamPromise = origCreate.apply(this, args) as Promise<
+        AsyncIterable<StreamEvent>
+      >;
+      return streamPromise.then(
+        (stream: AsyncIterable<StreamEvent>) => new TracedStream(stream, span),
+        (err: Error) => {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+          span.end();
+          throw err;
+        },
+      );
+    }
+
+    const resultPromise = origCreate.apply(this, args) as Promise<
+      Record<string, unknown>
+    >;
+    return resultPromise.then(
+      (response: Record<string, unknown>) => {
+        setResponseAttrs(span, response);
+        span.end();
+        return response;
+      },
+      (err: Error) => {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+        span.end();
+        throw err;
+      },
+    );
+  };
+}
+
+/**
+ * Marker placed on a patched `Messages.prototype.create` so repeated
+ * `instrumentClass()` calls (e.g. a second `introspection.init()`) are no-ops.
+ */
+const PATCHED = Symbol.for("introspection.anthropic.patched");
+
 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 protoRestores: Array<() => void> = [];
+  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 +546,8 @@ export class AnthropicInstrumentor {
       );
     }
 
+    this.conversationId = opts.conversationId ?? crypto.randomUUID();
+
     const provider = opts.tracerProvider ?? trace.getTracerProvider();
     this.tracer = (provider as BasicTracerProvider).getTracer(
       "introspection-anthropic",
@@ -403,56 +555,54 @@ export class AnthropicInstrumentor {
 
     const origCreate = client.messages.create.bind(client.messages);
     this.patchedClients.push({ client, originalCreate: origCreate });
-    const tracer = this.tracer!;
 
-    // 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;
+    client.messages.create = buildTracedCreate(
+      origCreate,
+      this.tracer,
+      this.conversationId,
+    );
+  }
 
-      const { span } = startSpan(
-        tracer,
-        (kwargs?.model as string) || "unknown",
+  /**
+   * Patch `Anthropic.Messages.prototype.create` so **every** client constructed
+   * from the given module is traced — the one-liner path used by
+   * `introspection.init()`. Idempotent: a second call is a no-op.
+   *
+   * @param opts.anthropic The `@anthropic-ai/sdk` module's default export
+   *   (the `Anthropic` class). Its `.Messages.prototype.create` is patched.
+   */
+  instrumentClass(opts: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    anthropic: any;
+    tracerProvider?: BasicTracerProvider;
+    conversationId?: string;
+  }): void {
+    const Messages = opts.anthropic?.Messages;
+    const proto = Messages?.prototype;
+    if (typeof proto?.create !== "function") {
+      throw new Error(
+        "Invalid Anthropic module — expected `Anthropic.Messages.prototype.create`",
       );
-      setRequestAttrs(span, kwargs || {});
-
-      if (isStream) {
-        const streamPromise = origCreate(...args) as Promise<
-          AsyncIterable<StreamEvent>
-        >;
-        return streamPromise.then(
-          (stream: AsyncIterable<StreamEvent>) =>
-            new TracedStream(stream, span),
-          (err: Error) => {
-            span.setStatus({
-              code: SpanStatusCode.ERROR,
-              message: String(err),
-            });
-            span.end();
-            throw err;
-          },
-        );
-      }
+    }
+    if (proto.create[PATCHED]) return;
 
-      const resultPromise = origCreate(...args) as Promise<
-        Record<string, unknown>
-      >;
-      return resultPromise.then(
-        (response: Record<string, unknown>) => {
-          setResponseAttrs(span, response);
-          span.end();
-          return response;
-        },
-        (err: Error) => {
-          span.setStatus({
-            code: SpanStatusCode.ERROR,
-            message: String(err),
-          });
-          span.end();
-          throw err;
-        },
-      );
-    };
+    this.conversationId = opts.conversationId ?? crypto.randomUUID();
+    const provider = opts.tracerProvider ?? trace.getTracerProvider();
+    this.tracer = (provider as BasicTracerProvider).getTracer(
+      "introspection-anthropic",
+    );
+
+    const origCreate = proto.create;
+    const patched = buildTracedCreate(
+      origCreate,
+      this.tracer,
+      this.conversationId,
+    ) as ((...args: unknown[]) => unknown) & { [PATCHED]?: boolean };
+    patched[PATCHED] = true;
+    proto.create = patched;
+    this.protoRestores.push(() => {
+      proto.create = origCreate;
+    });
   }
 
   uninstrument(): void {
@@ -460,6 +610,8 @@ export class AnthropicInstrumentor {
       client.messages.create = originalCreate;
     }
     this.patchedClients = [];
+    for (const restore of this.protoRestores) restore();
+    this.protoRestores = [];
     this.tracer = null;
   }
 }