@introspection-sdk/introspection-node 0.4.0

package/dist/claude-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-hooks.d.ts","sourceRoot":"","sources":["../src/claude-hooks.ts"],"names":[],"mappings":"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"}

package/dist/claude-hooks.js

@@ -0,0 +1,571 @@
+/**
+ * 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 { context as otelContext, trace as otelTrace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
+import { BasicTracerProvider, BatchSpanProcessor, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { resourceFromAttributes, defaultResource, } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { logger } from "./utils.js";
+import { VERSION } from "./version.js";
+import { convertClaudeSessionToOtelAttributes, } from "./converters/claude.js";
+/**
+ * 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 class IntrospectionClaudeHooks {
+    _tracerProvider;
+    _tracer;
+    _agentName;
+    _sessionSpans = new Map();
+    _toolSpans = new Map();
+    _subagentSpans = new Map();
+    _sessionUsage = new Map();
+    constructor(options = {}) {
+        const advanced = options.advanced;
+        const serviceName = options.serviceName || "claude-agent";
+        this._agentName = options.agentName || serviceName;
+        const resource = defaultResource().merge(resourceFromAttributes({ [ATTR_SERVICE_NAME]: serviceName }));
+        if (!advanced?.spanExporter) {
+            const token = options.token || process.env.INTROSPECTION_TOKEN;
+            if (!token) {
+                throw new Error("INTROSPECTION_TOKEN is required");
+            }
+            const baseUrl = options.baseUrl ||
+                process.env.INTROSPECTION_BASE_URL ||
+                "https://otel.introspection.dev";
+            const headers = {
+                "User-Agent": `introspection-sdk/${VERSION}`,
+                Authorization: `Bearer ${token}`,
+                ...options.additionalHeaders,
+            };
+            const endpoint = baseUrl.endsWith("/v1/traces")
+                ? baseUrl
+                : `${baseUrl.replace(/\/$/, "")}/v1/traces`;
+            logger.info(`IntrospectionClaudeHooks initialized: service=${serviceName}, endpoint=${endpoint}`);
+            const spanExporter = new OTLPTraceExporter({
+                url: endpoint,
+                headers,
+            });
+            // Default to sequential export for dev/staging tokens.
+            const useSimple = advanced?.useSimpleSpanProcessor ||
+                token.startsWith("intro_dev") ||
+                token.startsWith("intro_staging");
+            const spanProcessor = useSimple
+                ? new SimpleSpanProcessor(spanExporter)
+                : new BatchSpanProcessor(spanExporter, { scheduledDelayMillis: 1000 });
+            this._tracerProvider = new BasicTracerProvider({
+                resource,
+                idGenerator: advanced?.idGenerator,
+                spanProcessors: [spanProcessor],
+            });
+        }
+        else {
+            logger.info(`IntrospectionClaudeHooks initialized in test mode with custom exporter`);
+            const spanProcessor = advanced.useSimpleSpanProcessor
+                ? new SimpleSpanProcessor(advanced.spanExporter)
+                : new BatchSpanProcessor(advanced.spanExporter, {
+                    scheduledDelayMillis: 100,
+                });
+            this._tracerProvider = new BasicTracerProvider({
+                resource,
+                idGenerator: advanced.idGenerator,
+                spanProcessors: [spanProcessor],
+            });
+        }
+        this._tracer = this._tracerProvider.getTracer("claude-agent-sdk", VERSION);
+    }
+    /**
+     * Build the hooks configuration object to pass to Claude Agent SDK
+     * `query()` options.
+     *
+     * @returns A {@link ClaudeHooksConfig} wired to this instance's tracing.
+     */
+    getHooks() {
+        return {
+            SessionStart: [
+                {
+                    hooks: [this._onSessionStart.bind(this)],
+                },
+            ],
+            SessionEnd: [
+                {
+                    hooks: [this._onSessionEnd.bind(this)],
+                },
+            ],
+            PreToolUse: [
+                {
+                    hooks: [this._onPreToolUse.bind(this)],
+                },
+            ],
+            PostToolUse: [
+                {
+                    hooks: [this._onPostToolUse.bind(this)],
+                },
+            ],
+            SubagentStart: [
+                {
+                    hooks: [this._onSubagentStart.bind(this)],
+                },
+            ],
+            SubagentStop: [
+                {
+                    hooks: [this._onSubagentStop.bind(this)],
+                },
+            ],
+        };
+    }
+    /**
+     * 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, sessionId) {
+        if (sessionId) {
+            const existing = this._sessionUsage.get(sessionId) || {
+                input: 0,
+                output: 0,
+            };
+            existing.inputPrompt = prompt;
+            this._sessionUsage.set(sessionId, existing);
+        }
+        else {
+            // Store for when session starts
+            this._pendingInputPrompt = prompt;
+        }
+    }
+    _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, sessionId) {
+        if (sessionId) {
+            const existing = this._sessionUsage.get(sessionId) || {
+                input: 0,
+                output: 0,
+            };
+            existing.systemInstructions = instructions;
+            this._sessionUsage.set(sessionId, existing);
+        }
+        else {
+            this._pendingSystemInstructions = instructions;
+        }
+    }
+    _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) {
+        const sessionId = message.session_id || "default";
+        const msg = message;
+        // Handle system init message - start session span
+        if (message.type === "system" && msg.subtype === "init") {
+            this._startSessionFromMessage(sessionId, msg);
+            return;
+        }
+        if (message.type === "assistant") {
+            const assistantMsg = message;
+            const existing = this._sessionUsage.get(sessionId) || {
+                input: 0,
+                output: 0,
+            };
+            // Track usage
+            const usage = assistantMsg.message?.usage;
+            if (usage) {
+                existing.input += usage.input_tokens || 0;
+                existing.output += usage.output_tokens || 0;
+                if (assistantMsg.message?.model) {
+                    existing.model = assistantMsg.message.model;
+                }
+                logger.debug(`Recorded usage for session ${sessionId}: +${usage.input_tokens || 0} input, +${usage.output_tokens || 0} output`);
+            }
+            // Capture response ID from assistant message
+            if (assistantMsg.message?.id) {
+                existing.responseId = assistantMsg.message.id;
+            }
+            // Extract response content from assistant message
+            const content = assistantMsg.message?.content;
+            if (content && Array.isArray(content)) {
+                // Store content blocks for proper conversion
+                existing.responseBlocks = [
+                    ...(existing.responseBlocks || []),
+                    ...content,
+                ];
+                // Also extract text for backwards compatibility
+                const textContent = content
+                    .filter((block) => block.type === "text" && block.text)
+                    .map((block) => block.text)
+                    .join("");
+                if (textContent) {
+                    existing.responseContent =
+                        (existing.responseContent || "") + textContent;
+                }
+            }
+            this._sessionUsage.set(sessionId, existing);
+        }
+        else if (message.type === "result") {
+            const resultMsg = message;
+            const existing = this._sessionUsage.get(sessionId) || {
+                input: 0,
+                output: 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.total_cost_usd !== undefined) {
+                existing.cost = resultMsg.total_cost_usd;
+            }
+            // Capture stop reason from result subtype
+            const subtype = msg.subtype;
+            if (subtype) {
+                existing.stopReason = subtype;
+            }
+            this._sessionUsage.set(sessionId, existing);
+            logger.debug(`Recorded final usage for session ${sessionId}: ${existing.input} input, ${existing.output} output, $${existing.cost || 0}`);
+            // End session span on result message
+            this._endSessionFromMessage(sessionId, msg);
+        }
+    }
+    /**
+     * Start a session span from an init system message.
+     * This provides an alternative to the SessionStart hook which has timing issues.
+     */
+    _startSessionFromMessage(sessionId, msg) {
+        // Don't create duplicate spans if hook already created one
+        if (this._sessionSpans.has(sessionId)) {
+            logger.debug(`Session span already exists for ${sessionId}, skipping`);
+            return;
+        }
+        logger.debug(`Starting session span from init message: ${sessionId}`);
+        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",
+            },
+        });
+        // Add model if present in init message
+        const model = msg.model;
+        if (model) {
+            span.setAttribute("gen_ai.request.model", model);
+        }
+        // Add tools if present
+        const tools = msg.tools;
+        if (tools && tools.length > 0) {
+            span.setAttribute("claude.tools", tools.join(","));
+            span.setAttribute("gen_ai.tool.definitions", JSON.stringify(tools.map((name) => ({ name }))));
+        }
+        this._sessionSpans.set(sessionId, span);
+        // Initialize session usage, including any pending input prompt and system instructions
+        const sessionData = { input: 0, output: 0, model };
+        if (tools && tools.length > 0) {
+            sessionData.toolNames = tools;
+        }
+        if (this._pendingInputPrompt) {
+            sessionData.inputPrompt = this._pendingInputPrompt;
+            this._pendingInputPrompt = undefined;
+        }
+        if (this._pendingSystemInstructions) {
+            sessionData.systemInstructions = this._pendingSystemInstructions;
+            this._pendingSystemInstructions = undefined;
+        }
+        this._sessionUsage.set(sessionId, sessionData);
+        logger.info(`Created session span for ${sessionId}`);
+    }
+    /**
+     * End a session span from a result message.
+     * This provides an alternative to the SessionEnd hook which has timing issues.
+     */
+    _endSessionFromMessage(sessionId, msg) {
+        const span = this._sessionSpans.get(sessionId);
+        if (!span) {
+            logger.debug(`No session span found for ${sessionId}, nothing to end`);
+            return;
+        }
+        const usage = this._sessionUsage.get(sessionId);
+        // Use converter to set GenAI semantic convention attributes
+        const otelAttrs = convertClaudeSessionToOtelAttributes({
+            sessionId,
+            inputPrompt: usage?.inputPrompt,
+            responseContent: usage?.responseContent,
+            responseBlocks: usage?.responseBlocks,
+            model: usage?.model,
+            inputTokens: usage?.input,
+            outputTokens: usage?.output,
+            costUsd: usage?.cost,
+            stopReason: usage?.stopReason,
+            responseId: usage?.responseId,
+            toolNames: usage?.toolNames,
+            systemInstructions: usage?.systemInstructions,
+        });
+        // Apply all converted attributes to the span
+        for (const [key, value] of Object.entries(otelAttrs)) {
+            span.setAttribute(key, value);
+        }
+        // Set subtype/reason from result message
+        const subtype = msg.subtype;
+        if (subtype) {
+            span.setAttribute("claude.result_subtype", subtype);
+            if (subtype === "success") {
+                span.setStatus({ code: SpanStatusCode.OK });
+            }
+            else {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: subtype,
+                });
+            }
+        }
+        else {
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        span.end();
+        this._sessionSpans.delete(sessionId);
+        this._sessionUsage.delete(sessionId);
+        logger.info(`Ended session span for ${sessionId}: ${usage?.input || 0} input, ${usage?.output || 0} output tokens`);
+    }
+    async _onSessionStart(input, _toolUseID, _options) {
+        void _toolUseID;
+        void _options;
+        const sessionInput = input;
+        logger.debug(`SessionStart hook: ${sessionInput.session_id}`);
+        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,
+            },
+        });
+        if (sessionInput.model) {
+            span.setAttribute("gen_ai.request.model", sessionInput.model);
+        }
+        if (sessionInput.agent_type) {
+            span.setAttribute("claude.agent_type", sessionInput.agent_type);
+        }
+        this._sessionSpans.set(sessionInput.session_id, span);
+        // Initialize session usage, consuming any pending prompts/instructions
+        const sessionUsage = {
+            input: 0,
+            output: 0,
+        };
+        if (this._pendingInputPrompt) {
+            sessionUsage.inputPrompt = this._pendingInputPrompt;
+            this._pendingInputPrompt = undefined;
+        }
+        if (this._pendingSystemInstructions) {
+            sessionUsage.systemInstructions = this._pendingSystemInstructions;
+            this._pendingSystemInstructions = undefined;
+        }
+        this._sessionUsage.set(sessionInput.session_id, sessionUsage);
+        return { continue: true };
+    }
+    async _onSessionEnd(input, _toolUseID, _options) {
+        void _toolUseID;
+        void _options;
+        const sessionInput = input;
+        logger.debug(`SessionEnd hook: ${sessionInput.session_id}`);
+        const span = this._sessionSpans.get(sessionInput.session_id);
+        if (span) {
+            const usage = this._sessionUsage.get(sessionInput.session_id);
+            if (usage) {
+                // Use converter for consistent gen_ai attribute mapping
+                const otelAttrs = convertClaudeSessionToOtelAttributes({
+                    sessionId: sessionInput.session_id,
+                    inputPrompt: usage.inputPrompt,
+                    responseContent: usage.responseContent,
+                    responseBlocks: usage.responseBlocks,
+                    model: usage.model,
+                    inputTokens: usage.input,
+                    outputTokens: usage.output,
+                    costUsd: usage.cost,
+                    stopReason: usage.stopReason,
+                    responseId: usage.responseId,
+                    toolNames: usage.toolNames,
+                    systemInstructions: usage.systemInstructions,
+                });
+                for (const [key, value] of Object.entries(otelAttrs)) {
+                    span.setAttribute(key, value);
+                }
+            }
+            span.setAttribute("claude.exit_reason", sessionInput.reason);
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.end();
+            this._sessionSpans.delete(sessionInput.session_id);
+            this._sessionUsage.delete(sessionInput.session_id);
+            logger.debug(`Ended session span for ${sessionInput.session_id}`);
+        }
+        return { continue: true };
+    }
+    async _onPreToolUse(input, _toolUseID, _options) {
+        void _toolUseID;
+        void _options;
+        const toolInput = input;
+        logger.debug(`PreToolUse: ${toolInput.tool_name} (${toolInput.tool_use_id})`);
+        const parentSpan = this._sessionSpans.get(toolInput.session_id);
+        const ctx = parentSpan
+            ? otelTrace.setSpan(otelContext.active(), parentSpan)
+            : undefined;
+        const span = this._tracer.startSpan(`tool.${toolInput.tool_name}`, {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                "gen_ai.tool.name": toolInput.tool_name,
+                "claude.session_id": toolInput.session_id,
+                "claude.tool_use_id": toolInput.tool_use_id,
+            },
+        }, ctx);
+        if (toolInput.tool_input) {
+            try {
+                span.setAttribute("gen_ai.tool.input", JSON.stringify(toolInput.tool_input));
+            }
+            catch {
+                span.setAttribute("gen_ai.tool.input", String(toolInput.tool_input));
+            }
+        }
+        this._toolSpans.set(toolInput.tool_use_id, span);
+        return { continue: true };
+    }
+    async _onPostToolUse(input, _toolUseID, _options) {
+        void _toolUseID;
+        void _options;
+        const toolInput = input;
+        logger.debug(`PostToolUse: ${toolInput.tool_name} (${toolInput.tool_use_id})`);
+        const span = this._toolSpans.get(toolInput.tool_use_id);
+        if (span) {
+            if (toolInput.tool_response !== undefined) {
+                try {
+                    span.setAttribute("gen_ai.tool.output", JSON.stringify(toolInput.tool_response));
+                }
+                catch {
+                    span.setAttribute("gen_ai.tool.output", String(toolInput.tool_response));
+                }
+            }
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.end();
+            this._toolSpans.delete(toolInput.tool_use_id);
+        }
+        return { continue: true };
+    }
+    async _onSubagentStart(input, _toolUseID, _options) {
+        void _toolUseID;
+        void _options;
+        const subagentInput = input;
+        logger.debug(`SubagentStart: ${subagentInput.agent_type} (${subagentInput.agent_id})`);
+        const parentSpan = this._sessionSpans.get(subagentInput.session_id);
+        const ctx = parentSpan
+            ? otelTrace.setSpan(otelContext.active(), parentSpan)
+            : undefined;
+        const span = this._tracer.startSpan(`subagent.${subagentInput.agent_type}`, {
+            kind: SpanKind.INTERNAL,
+            attributes: {
+                "gen_ai.agent.name": subagentInput.agent_type,
+                "claude.session_id": subagentInput.session_id,
+                "claude.agent_id": subagentInput.agent_id,
+            },
+        }, ctx);
+        this._subagentSpans.set(subagentInput.agent_id, span);
+        return { continue: true };
+    }
+    async _onSubagentStop(input, _toolUseID, _options) {
+        void _toolUseID;
+        void _options;
+        const subagentInput = input;
+        logger.debug(`SubagentStop: ${subagentInput.agent_type} (${subagentInput.agent_id})`);
+        const span = this._subagentSpans.get(subagentInput.agent_id);
+        if (span) {
+            span.setStatus({ code: SpanStatusCode.OK });
+            span.end();
+            this._subagentSpans.delete(subagentInput.agent_id);
+        }
+        return { continue: true };
+    }
+    /**
+     * Force-flush any buffered spans to the Introspection backend.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    async forceFlush() {
+        await this._tracerProvider.forceFlush();
+    }
+    /**
+     * Shut down the hooks, ending any in-flight spans and flushing all
+     * pending data.
+     *
+     * @returns A promise that resolves once shutdown is complete.
+     */
+    async shutdown() {
+        // End any remaining spans
+        for (const [, span] of this._sessionSpans) {
+            span.end();
+        }
+        for (const [, span] of this._toolSpans) {
+            span.end();
+        }
+        for (const [, span] of this._subagentSpans) {
+            span.end();
+        }
+        this._sessionSpans.clear();
+        this._toolSpans.clear();
+        this._subagentSpans.clear();
+        this._sessionUsage.clear();
+        await this._tracerProvider.shutdown();
+    }
+}

package/dist/claude-wrapper.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Claude Agent SDK Wrapper
+ *
+ * Provides a zero-friction `withIntrospection()` wrapper for the Claude Agent SDK.
+ * Automatically instruments all query() calls with OpenTelemetry tracing via
+ * IntrospectionClaudeHooks — no manual hook wiring or recordUsage() calls needed.
+ *
+ * @example
+ * ```typescript
+ * import * as sdk from "@anthropic-ai/claude-agent-sdk";
+ * import { withIntrospection } from "@introspection-sdk/introspection-node";
+ *
+ * const tracedSdk = withIntrospection(sdk, { serviceName: "my-agent" });
+ *
+ * for await (const message of tracedSdk.query({ prompt: "Hello" })) {
+ *   // messages yielded normally — tracing happens automatically
+ * }
+ *
+ * await tracedSdk.shutdown();
+ * ```
+ */
+import { IntrospectionClaudeHooks, type IntrospectionClaudeHooksOptions } from "./claude-hooks.js";
+/**
+ * Configuration for {@link withIntrospection}.
+ *
+ * Alias of {@link IntrospectionClaudeHooksOptions}.
+ */
+export type WithIntrospectionOptions = IntrospectionClaudeHooksOptions;
+/**
+ * Minimal interface for the Claude Agent SDK module.
+ * Accepts `import * as sdk from "@anthropic-ai/claude-agent-sdk"`.
+ *
+ * Uses `any` for the query signature to accept any SDK version's types
+ * without requiring the SDK as a compile-time dependency.
+ */
+export interface ClaudeAgentSDKModule {
+    query: (...args: any[]) => any;
+    [key: string]: unknown;
+}
+/**
+ * The instrumented SDK returned by {@link withIntrospection}.
+ *
+ * Exposes the same surface as the original SDK module plus tracing helpers.
+ */
+export interface InstrumentedClaudeAgentSDK {
+    /** Instrumented `query()` — auto-captures prompt, hooks, and usage. */
+    query: (...args: any[]) => any;
+    /**
+     * Flush pending spans without shutting down.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Shut down tracing and flush all pending spans.
+     *
+     * @returns A promise that resolves once shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+    /** The underlying {@link IntrospectionClaudeHooks} instance for advanced usage. */
+    readonly hooks: IntrospectionClaudeHooks;
+    /** All other SDK exports pass through unchanged. */
+    [key: string]: unknown;
+}
+/**
+ * Wrap the Claude Agent SDK module to automatically instrument every
+ * `query()` call with OpenTelemetry tracing.
+ *
+ * The returned SDK:
+ * - Auto-captures `prompt` and `systemPrompt` from query params
+ * - Injects instrumentation hooks (merged with any user-provided hooks)
+ * - Calls {@link IntrospectionClaudeHooks.recordUsage | recordUsage()} on
+ *   every streamed message automatically
+ * - Flushes spans when each query stream completes
+ *
+ * @param sdk - The Claude Agent SDK module
+ *   (`import * as sdk from "@anthropic-ai/claude-agent-sdk"`).
+ * @param options - Introspection configuration (token, serviceName, baseUrl, etc.).
+ * @returns An {@link InstrumentedClaudeAgentSDK} with the same API plus
+ *   `forceFlush()`, `shutdown()`, and `hooks`.
+ *
+ * @example
+ * ```ts
+ * import * as sdk from "@anthropic-ai/claude-agent-sdk";
+ * import { withIntrospection } from "@introspection-sdk/introspection-node";
+ *
+ * const traced = withIntrospection(sdk, { serviceName: "my-agent" });
+ * for await (const msg of traced.query({ prompt: "Hello" })) { /* … *\/ }
+ * await traced.shutdown();
+ * ```
+ */
+export declare function withIntrospection(sdk: ClaudeAgentSDKModule, options?: WithIntrospectionOptions): InstrumentedClaudeAgentSDK;
+//# sourceMappingURL=claude-wrapper.d.ts.map

package/dist/claude-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-wrapper.d.ts","sourceRoot":"","sources":["../src/claude-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,+BAA+B,EAGrC,MAAM,mBAAmB,CAAC;AAK3B;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,+BAA+B,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IAEnC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,uEAAuE;IAEvE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;IAC/B;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IACzC,oDAAoD;IACpD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,oBAAoB,EACzB,OAAO,CAAC,EAAE,wBAAwB,GACjC,0BAA0B,CAyC5B"}