@introspection-sdk/introspection-node 0.4.0

package/dist/anthropic.js

@@ -0,0 +1,375 @@
+/**
+ * Lightweight Anthropic instrumentor for Introspection SDK.
+ *
+ * Captures the full Anthropic response including thinking blocks (extended
+ * thinking) with signatures, which third-party instrumentors drop.
+ *
+ * Supports both non-streaming (`messages.create`) and streaming
+ * (`messages.create({ stream: true })`) calls.
+ *
+ * @example
+ * ```ts
+ * import { AnthropicInstrumentor } from "@introspection-sdk/introspection-node";
+ *
+ * const instrumentor = new AnthropicInstrumentor();
+ * instrumentor.instrument({ tracerProvider: provider });
+ * // All client.messages.create calls are now traced
+ * ```
+ */
+import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+/** Sentinel value for redacted thinking blocks — content was encrypted by safety systems. */
+export const REDACTED_THINKING_CONTENT = "[redacted]";
+function blockToParts(block) {
+    const bt = block.type || "";
+    if (bt === "text") {
+        return [{ type: "text", content: block.text || "" }];
+    }
+    if (bt === "thinking") {
+        const part = {
+            type: "thinking",
+            content: block.thinking || undefined,
+            signature: block.signature || undefined,
+            provider_name: "anthropic",
+        };
+        return [part];
+    }
+    if (bt === "redacted_thinking") {
+        return [
+            {
+                type: "thinking",
+                content: REDACTED_THINKING_CONTENT,
+                signature: block.data || undefined,
+                provider_name: "anthropic",
+            },
+        ];
+    }
+    if (bt === "tool_use") {
+        return [
+            {
+                type: "tool_call",
+                id: block.id || "",
+                name: block.name || "",
+                arguments: block.input,
+            },
+        ];
+    }
+    if (bt === "tool_result") {
+        return [
+            {
+                type: "tool_call_response",
+                id: block.tool_use_id || "",
+                response: block.content != null ? String(block.content) : "",
+            },
+        ];
+    }
+    return [];
+}
+function convertAnthropicInput(messages) {
+    const result = [];
+    for (const msg of messages) {
+        const role = msg.role || "user";
+        const content = msg.content;
+        if (typeof content === "string") {
+            result.push({
+                role: role,
+                parts: [{ type: "text", content }],
+            });
+        }
+        else if (Array.isArray(content)) {
+            const parts = [];
+            for (const block of content) {
+                const rec = typeof block === "object" && block !== null
+                    ? block
+                    : { type: "text", text: String(block) };
+                parts.push(...blockToParts(rec));
+            }
+            if (parts.length > 0) {
+                result.push({ role: role, parts });
+            }
+        }
+    }
+    return result;
+}
+function convertAnthropicOutput(content) {
+    const parts = [];
+    let hasToolCalls = false;
+    for (const block of content) {
+        const newParts = blockToParts(block);
+        for (const p of newParts) {
+            if (p.type === "tool_call")
+                hasToolCalls = true;
+        }
+        parts.push(...newParts);
+    }
+    if (parts.length === 0)
+        return [];
+    return [
+        {
+            role: "assistant",
+            parts,
+            finish_reason: hasToolCalls ? "tool-calls" : "stop",
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Span helpers
+// ---------------------------------------------------------------------------
+function serializeMessages(msgs) {
+    return JSON.stringify(msgs.map((m) => {
+        const obj = { role: m.role, parts: m.parts };
+        if ("finish_reason" in m && m.finish_reason) {
+            obj.finish_reason = m.finish_reason;
+        }
+        return obj;
+    }));
+}
+function startSpan(tracer, model) {
+    const span = tracer.startSpan("chat", {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            "gen_ai.system": "anthropic",
+            "gen_ai.provider.name": "anthropic",
+            "gen_ai.operation.name": "chat",
+            "gen_ai.request.model": model,
+            "openinference.span.kind": "LLM",
+        },
+    });
+    return { span, token: null };
+}
+function setRequestAttrs(span, kwargs) {
+    const messages = kwargs.messages || [];
+    const inputMsgs = convertAnthropicInput(messages);
+    if (inputMsgs.length > 0) {
+        span.setAttribute("gen_ai.input.messages", serializeMessages(inputMsgs));
+    }
+    const system = kwargs.system;
+    if (system) {
+        const sysVal = typeof system === "string"
+            ? JSON.stringify([{ type: "text", content: system }])
+            : JSON.stringify(system);
+        span.setAttribute("gen_ai.system_instructions", sysVal);
+    }
+    const tools = kwargs.tools;
+    if (tools && tools.length > 0) {
+        const defs = tools.map((t) => ({
+            name: t.name || "",
+            description: t.description,
+            parameters: t.input_schema,
+        }));
+        span.setAttribute("gen_ai.tool.definitions", JSON.stringify(defs));
+    }
+}
+function setResponseAttrs(span, response) {
+    const content = response.content;
+    if (content) {
+        const outputMsgs = convertAnthropicOutput(content);
+        if (outputMsgs.length > 0) {
+            span.setAttribute("gen_ai.output.messages", serializeMessages(outputMsgs));
+        }
+    }
+    if (response.id)
+        span.setAttribute("gen_ai.response.id", String(response.id));
+    if (response.model)
+        span.setAttribute("gen_ai.response.model", String(response.model));
+    const usage = response.usage;
+    if (usage) {
+        if (usage.input_tokens != null)
+            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);
+    }
+    span.setStatus({ code: SpanStatusCode.OK });
+}
+class TracedStream {
+    inner;
+    span;
+    blocks = [];
+    currentBlock = null;
+    responseId = null;
+    responseModel = null;
+    inputTokens = 0;
+    outputTokens = 0;
+    finalized = false;
+    constructor(inner, span) {
+        this.inner = inner;
+        this.span = span;
+    }
+    async *[Symbol.asyncIterator]() {
+        try {
+            for await (const event of this.inner) {
+                this.processEvent(event);
+                yield event;
+            }
+        }
+        finally {
+            this.finalize();
+        }
+    }
+    processEvent(event) {
+        if (event.type === "message_start" && event.message) {
+            this.responseId = event.message.id || null;
+            this.responseModel = event.message.model || null;
+            const usage = event.message.usage;
+            if (usage)
+                this.inputTokens = usage.input_tokens || 0;
+        }
+        else if (event.type === "content_block_start" && event.content_block) {
+            const bt = event.content_block.type || "";
+            this.currentBlock = { type: bt };
+            if (bt === "thinking") {
+                this.currentBlock.thinking = "";
+                this.currentBlock.signature = "";
+            }
+            else if (bt === "text") {
+                this.currentBlock.text = "";
+            }
+        }
+        else if (event.type === "content_block_delta" && event.delta) {
+            if (!this.currentBlock)
+                return;
+            const dt = event.delta.type || "";
+            if (dt === "thinking_delta") {
+                this.currentBlock.thinking =
+                    (this.currentBlock.thinking || "") +
+                        (event.delta.thinking || "");
+            }
+            else if (dt === "text_delta") {
+                this.currentBlock.text =
+                    (this.currentBlock.text || "") +
+                        (event.delta.text || "");
+            }
+            else if (dt === "signature_delta") {
+                this.currentBlock.signature =
+                    (this.currentBlock.signature || "") +
+                        (event.delta.signature || "");
+            }
+        }
+        else if (event.type === "content_block_stop") {
+            if (this.currentBlock) {
+                this.blocks.push(this.currentBlock);
+                this.currentBlock = null;
+            }
+        }
+        else if (event.type === "message_delta") {
+            const usage = event.usage;
+            if (usage)
+                this.outputTokens = usage.output_tokens || 0;
+        }
+    }
+    finalize() {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        if (this.blocks.length > 0) {
+            const outputMsgs = convertAnthropicOutput(this.blocks);
+            if (outputMsgs.length > 0) {
+                this.span.setAttribute("gen_ai.output.messages", serializeMessages(outputMsgs));
+            }
+        }
+        if (this.responseId)
+            this.span.setAttribute("gen_ai.response.id", this.responseId);
+        if (this.responseModel)
+            this.span.setAttribute("gen_ai.response.model", this.responseModel);
+        if (this.inputTokens)
+            this.span.setAttribute("gen_ai.usage.input_tokens", this.inputTokens);
+        if (this.outputTokens)
+            this.span.setAttribute("gen_ai.usage.output_tokens", this.outputTokens);
+        this.span.setStatus({ code: SpanStatusCode.OK });
+        this.span.end();
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Traced wrapper around `client.messages.create(kwargs)`.
+ * Creates a gen_ai span with full Anthropic response including thinking blocks.
+ */
+export async function tracedMessagesCreate(tracer, client, kwargs) {
+    const { span } = startSpan(tracer, kwargs.model || "unknown");
+    try {
+        setRequestAttrs(span, kwargs);
+        const response = (await client.messages.create(kwargs));
+        setResponseAttrs(span, response);
+        return response;
+    }
+    catch (e) {
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: String(e),
+        });
+        throw e;
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Auto-instrumentor that patches `Anthropic.messages.create` to add tracing.
+ *
+ * Captures all content blocks including thinking (extended thinking) with
+ * signatures. Supports both non-streaming and streaming calls.
+ */
+/**
+ * Auto-instrumentor that wraps an Anthropic client instance to add tracing.
+ *
+ * Captures all content blocks including thinking (extended thinking) with
+ * signatures. Supports both non-streaming and streaming calls.
+ */
+export class AnthropicInstrumentor {
+    tracer = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    patchedClients = [];
+    instrument(opts) {
+        const { client } = opts;
+        if (!client?.messages?.create) {
+            throw new Error("Invalid client — pass an Anthropic client instance (new Anthropic())");
+        }
+        const provider = opts.tracerProvider ?? trace.getTracerProvider();
+        this.tracer = provider.getTracer("introspection-anthropic");
+        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) {
+            const kwargs = args[0];
+            const isStream = kwargs?.stream === true;
+            const { span } = startSpan(tracer, kwargs?.model || "unknown");
+            setRequestAttrs(span, kwargs || {});
+            if (isStream) {
+                const streamPromise = origCreate(...args);
+                return streamPromise.then((stream) => new TracedStream(stream, span), (err) => {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: String(err),
+                    });
+                    span.end();
+                    throw err;
+                });
+            }
+            const resultPromise = origCreate(...args);
+            return resultPromise.then((response) => {
+                setResponseAttrs(span, response);
+                span.end();
+                return response;
+            }, (err) => {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: String(err),
+                });
+                span.end();
+                throw err;
+            });
+        };
+    }
+    uninstrument() {
+        for (const { client, originalCreate } of this.patchedClients) {
+            client.messages.create = originalCreate;
+        }
+        this.patchedClients = [];
+        this.tracer = null;
+    }
+}

package/dist/claude-hooks.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Claude Agent SDK Instrumentation Hooks
+ *
+ * Provides OpenTelemetry instrumentation for the Claude Agent SDK via its hooks system.
+ * Creates spans for sessions, tool uses, and subagent executions with gen_ai.* attributes.
+ *
+ * @see https://platform.claude.com/docs/en/agent-sdk/typescript
+ */
+import { type SpanExporter, type IdGenerator } from "@opentelemetry/sdk-trace-base";
+/** Common fields present on every hook input payload. */
+export interface BaseHookInput {
+    /** Active session identifier. */
+    session_id: string;
+    /** Path to the session transcript file. */
+    transcript_path: string;
+    /** Working directory of the agent process. */
+    cwd: string;
+    /** Permission mode the session is running in. */
+    permission_mode?: string;
+}
+/** Input payload for the `SessionStart` hook. */
+export interface SessionStartHookInput extends BaseHookInput {
+    hook_event_name: "SessionStart";
+    /** How the session was initiated. */
+    source: "startup" | "resume" | "clear" | "compact";
+    /** Agent type (e.g. `"main"`, `"subagent"`). */
+    agent_type?: string;
+    /** Model used for this session. */
+    model?: string;
+}
+/** Input payload for the `SessionEnd` hook. */
+export interface SessionEndHookInput extends BaseHookInput {
+    hook_event_name: "SessionEnd";
+    /** Reason the session ended. */
+    reason: string;
+}
+/** Input payload for the `PreToolUse` hook. */
+export interface PreToolUseHookInput extends BaseHookInput {
+    hook_event_name: "PreToolUse";
+    /** Name of the tool about to be invoked. */
+    tool_name: string;
+    /** Input data passed to the tool. */
+    tool_input: unknown;
+    /** Unique identifier for this tool invocation. */
+    tool_use_id: string;
+}
+/** Input payload for the `PostToolUse` hook. */
+export interface PostToolUseHookInput extends BaseHookInput {
+    hook_event_name: "PostToolUse";
+    /** Name of the tool that was invoked. */
+    tool_name: string;
+    /** Input data that was passed to the tool. */
+    tool_input: unknown;
+    /** Response returned by the tool. */
+    tool_response: unknown;
+    /** Unique identifier for this tool invocation. */
+    tool_use_id: string;
+}
+/** Input payload for the `SubagentStart` hook. */
+export interface SubagentStartHookInput extends BaseHookInput {
+    hook_event_name: "SubagentStart";
+    /** Identifier of the sub-agent. */
+    agent_id: string;
+    /** Type / name of the sub-agent. */
+    agent_type: string;
+}
+/** Input payload for the `SubagentStop` hook. */
+export interface SubagentStopHookInput extends BaseHookInput {
+    hook_event_name: "SubagentStop";
+    /** Identifier of the sub-agent. */
+    agent_id: string;
+    /** Type / name of the sub-agent. */
+    agent_type: string;
+    /** Path to the sub-agent's transcript. */
+    agent_transcript_path: string;
+}
+/** Discriminated union of all possible hook input payloads. */
+export type ClaudeHookInput = SessionStartHookInput | SessionEndHookInput | PreToolUseHookInput | PostToolUseHookInput | SubagentStartHookInput | SubagentStopHookInput;
+/**
+ * JSON-serialisable output returned by a hook callback
+ * (`SyncHookJSONOutput` in the SDK).
+ */
+export type ClaudeHookOutput = {
+    /** Whether the SDK should continue processing. */
+    continue?: boolean;
+    /** Suppress the default output for this hook event. */
+    suppressOutput?: boolean;
+    /** Reason to stop the session. */
+    stopReason?: string;
+    /** Approval decision for `PreToolUse` hooks. */
+    decision?: "approve" | "block";
+    /** System message to inject into the conversation. */
+    systemMessage?: string;
+    /** Human-readable reason for the decision. */
+    reason?: string;
+};
+/**
+ * Async callback signature for a Claude Agent SDK hook.
+ *
+ * @param input - The hook input payload.
+ * @param toolUseID - The tool-use ID (set for `PreToolUse` / `PostToolUse`).
+ * @param options - Abort signal for cancellation.
+ * @returns A {@link ClaudeHookOutput} controlling the SDK's behaviour.
+ */
+export type ClaudeHookCallback = (input: ClaudeHookInput, toolUseID: string | undefined, options: {
+    signal: AbortSignal;
+}) => Promise<ClaudeHookOutput>;
+/** Pairs an optional glob matcher with one or more hook callbacks. */
+export interface ClaudeHookCallbackMatcher {
+    /** Glob pattern to match tool names (only relevant for tool hooks). */
+    matcher?: string;
+    /** Callbacks to invoke when the matcher (or all events) match. */
+    hooks: ClaudeHookCallback[];
+    /** Timeout in milliseconds for hook execution. */
+    timeout?: number;
+}
+/** String literal union of all Claude Agent SDK hook event names. */
+export type ClaudeHookEvent = "PreToolUse" | "PostToolUse" | "SessionStart" | "SessionEnd" | "SubagentStart" | "SubagentStop";
+/**
+ * Full hooks configuration object accepted by the Claude Agent SDK
+ * `query()` options. Maps each event name to an array of
+ * {@link ClaudeHookCallbackMatcher} entries.
+ */
+export type ClaudeHooksConfig = Partial<Record<ClaudeHookEvent, ClaudeHookCallbackMatcher[]>>;
+/** Token-level usage counters reported by the Claude API. */
+export interface ClaudeUsage {
+    /** Number of input tokens consumed. */
+    input_tokens: number;
+    /** Number of output tokens generated. */
+    output_tokens: number;
+    /** Tokens used to create new cache entries. */
+    cache_creation_input_tokens?: number;
+    /** Tokens read from cache. */
+    cache_read_input_tokens?: number;
+}
+/** Per-model usage breakdown reported in a result message. */
+export interface ClaudeModelUsage {
+    /** Input tokens for this model. */
+    inputTokens: number;
+    /** Output tokens for this model. */
+    outputTokens: number;
+    /** Tokens read from cache for this model. */
+    cacheReadInputTokens: number;
+    /** Tokens used to create cache for this model. */
+    cacheCreationInputTokens: number;
+    /** Estimated cost in USD for this model. */
+    costUSD: number;
+}
+/** A `"result"` message yielded at the end of a `query()` stream. */
+export interface ClaudeResultMessage {
+    type: "result";
+    /** Aggregate token usage for the session. */
+    usage?: ClaudeUsage;
+    /** Total estimated cost in USD. */
+    total_cost_usd?: number;
+    /** Per-model usage breakdown. */
+    modelUsage?: Record<string, ClaudeModelUsage>;
+    /** Final text result (if any). */
+    result?: string;
+    /** Whether the session ended with an error. */
+    is_error?: boolean;
+    /** Session identifier. */
+    session_id: string;
+}
+/** An `"assistant"` message yielded during a `query()` stream. */
+export interface ClaudeAssistantMessage {
+    type: "assistant";
+    /** The underlying API message with optional usage and content. */
+    message?: {
+        id?: string;
+        model?: string;
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+        };
+        content?: Array<{
+            type: string;
+            text?: string;
+        }>;
+    };
+    /** Session identifier. */
+    session_id: string;
+}
+/**
+ * Discriminated union of all messages that can be yielded by a Claude Agent
+ * SDK `query()` stream.
+ */
+export type ClaudeSDKMessage = ClaudeResultMessage | ClaudeAssistantMessage | {
+    type: string;
+    session_id?: string;
+};
+/** Advanced options for testing and customization of {@link IntrospectionClaudeHooks}. */
+export interface ClaudeHooksAdvancedOptions {
+    /** Custom span exporter (for testing) */
+    spanExporter?: SpanExporter;
+    /** Custom ID generator (for testing) */
+    idGenerator?: IdGenerator;
+    /** Use SimpleSpanProcessor instead of BatchSpanProcessor (for testing) */
+    useSimpleSpanProcessor?: boolean;
+}
+/** Configuration for {@link IntrospectionClaudeHooks}. */
+export interface IntrospectionClaudeHooksOptions {
+    /** Authentication token (env: INTROSPECTION_TOKEN) */
+    token?: string;
+    /** Base URL for the API (env: INTROSPECTION_BASE_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;
+    /** Additional headers to include in requests */
+    additionalHeaders?: Record<string, string>;
+    /** Advanced options for testing and customization */
+    advanced?: ClaudeHooksAdvancedOptions;
+}
+/**
+ * Provides instrumented hooks for Claude Agent SDK.
+ *
+ * Creates OpenTelemetry spans with gen_ai.* semantic convention attributes:
+ * - Session spans: gen_ai.system, gen_ai.request.model
+ * - Tool spans: gen_ai.tool.name, gen_ai.tool.input, gen_ai.tool.output
+ * - Subagent spans: gen_ai.agent.name
+ *
+ * Usage tracking is captured from streamed messages via recordUsage().
+ *
+ * @example
+ * ```typescript
+ * import { query } from "@anthropic-ai/claude-agent-sdk";
+ * import { IntrospectionClaudeHooks } from "@introspection-sdk/introspection-node";
+ *
+ * const hooks = new IntrospectionClaudeHooks();
+ *
+ * const stream = query({
+ *   prompt: "Hello",
+ *   options: {
+ *     hooks: hooks.getHooks(),
+ *   },
+ * });
+ *
+ * for await (const message of stream) {
+ *   hooks.recordUsage(message);
+ *   // handle message...
+ * }
+ *
+ * await hooks.shutdown();
+ * ```
+ */
+export declare class IntrospectionClaudeHooks {
+    private _tracerProvider;
+    private _tracer;
+    private _agentName;
+    private _sessionSpans;
+    private _toolSpans;
+    private _subagentSpans;
+    private _sessionUsage;
+    constructor(options?: IntrospectionClaudeHooksOptions);
+    /**
+     * Build the hooks configuration object to pass to Claude Agent SDK
+     * `query()` options.
+     *
+     * @returns A {@link ClaudeHooksConfig} wired to this instance's tracing.
+     */
+    getHooks(): ClaudeHooksConfig;
+    /**
+     * Set the input prompt for a session so it appears as
+     * `gen_ai.input.messages` on the session span.
+     *
+     * If `sessionId` is not provided the prompt is buffered and associated
+     * with the next session that starts via an `init` message.
+     *
+     * @param prompt - The user prompt string passed to `query()`.
+     * @param sessionId - Optional session ID if already known.
+     */
+    setInputPrompt(prompt: string, sessionId?: string): void;
+    private _pendingInputPrompt?;
+    /**
+     * Set system instructions for a session so they appear as
+     * `gen_ai.system_instructions` on the session span.
+     *
+     * If `sessionId` is not provided the value is buffered and associated
+     * with the next session that starts via an `init` message.
+     *
+     * @param instructions - The system prompt / instructions string.
+     * @param sessionId - Optional session ID if already known.
+     */
+    setSystemInstructions(instructions: string, sessionId?: string): void;
+    private _pendingSystemInstructions?;
+    /**
+     * Record usage from a streamed SDK message.
+     *
+     * Call this for **every** message yielded by `query()` to capture token
+     * usage. Session spans are automatically created on `init` messages and
+     * ended on `result` messages.
+     *
+     * @param message - A {@link ClaudeSDKMessage} yielded by the `query()` stream.
+     */
+    recordUsage(message: ClaudeSDKMessage): void;
+    /**
+     * Start a session span from an init system message.
+     * This provides an alternative to the SessionStart hook which has timing issues.
+     */
+    private _startSessionFromMessage;
+    /**
+     * End a session span from a result message.
+     * This provides an alternative to the SessionEnd hook which has timing issues.
+     */
+    private _endSessionFromMessage;
+    private _onSessionStart;
+    private _onSessionEnd;
+    private _onPreToolUse;
+    private _onPostToolUse;
+    private _onSubagentStart;
+    private _onSubagentStop;
+    /**
+     * Force-flush any buffered spans to the Introspection backend.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Shut down the hooks, ending any in-flight spans and flushing all
+     * pending data.
+     *
+     * @returns A promise that resolves once shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=claude-hooks.d.ts.map