@introspection-sdk/introspection-node 0.4.0

package/dist/claude-wrapper.js

@@ -0,0 +1,154 @@
+/**
+ * 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, } from "./claude-hooks.js";
+import { logger } from "./utils.js";
+// --- Implementation ---
+/**
+ * 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 function withIntrospection(sdk, options) {
+    const hooks = new IntrospectionClaudeHooks(options);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function wrappedQuery(params) {
+        // Auto-capture prompt
+        if (typeof params?.prompt === "string") {
+            hooks.setInputPrompt(params.prompt);
+        }
+        // Auto-capture systemPrompt from options
+        const opts = (params?.options || {});
+        if (typeof opts.systemPrompt === "string") {
+            hooks.setSystemInstructions(opts.systemPrompt);
+        }
+        // Merge instrumentation hooks with any user-provided hooks
+        const introspectionHooks = hooks.getHooks();
+        const userHooks = opts.hooks;
+        const mergedHooks = mergeHooks(introspectionHooks, userHooks);
+        // Call original query with merged hooks
+        const modifiedOptions = { ...opts, hooks: mergedHooks };
+        const originalQuery = sdk.query({
+            ...params,
+            options: modifiedOptions,
+        });
+        // Wrap the async generator to intercept messages
+        return wrapQueryResult(originalQuery, hooks);
+    }
+    return {
+        ...sdk,
+        query: wrappedQuery,
+        hooks,
+        forceFlush: () => hooks.forceFlush(),
+        shutdown: () => hooks.shutdown(),
+    };
+}
+/**
+ * Merges introspection hooks with user-provided hooks.
+ * Introspection hooks fire first, then user hooks.
+ * User hooks on events we don't handle pass through untouched.
+ */
+function mergeHooks(introspectionHooks, userHooks) {
+    if (!userHooks) {
+        return introspectionHooks;
+    }
+    const merged = {};
+    const allEvents = new Set([
+        ...Object.keys(introspectionHooks),
+        ...Object.keys(userHooks),
+    ]);
+    for (const event of allEvents) {
+        const ours = introspectionHooks[event] || [];
+        const theirs = userHooks[event] || [];
+        merged[event] = [...ours, ...theirs];
+    }
+    return merged;
+}
+/**
+ * Wraps a Query async generator to intercept messages for usage recording.
+ * Uses a Proxy to transparently forward all non-iterator properties
+ * (interrupt, close, setModel, etc.) to the original Query object.
+ */
+function wrapQueryResult(originalQuery, hooks) {
+    const query = originalQuery;
+    async function* instrumentedIterator() {
+        try {
+            for await (const message of query) {
+                hooks.recordUsage(message);
+                yield message;
+            }
+        }
+        finally {
+            try {
+                await hooks.forceFlush();
+            }
+            catch (flushError) {
+                logger.warn("Failed to flush spans after query completed", flushError);
+            }
+        }
+    }
+    const wrapped = instrumentedIterator();
+    // Use Proxy to transparently delegate non-iterator properties to original query.
+    // Iterator protocol methods come from our wrapper (bound to the actual generator
+    // to avoid "incompatible receiver" errors); everything else (interrupt, close,
+    // setModel, setPermissionMode, etc.) delegates to the original Query.
+    return new Proxy(wrapped, {
+        get(target, prop) {
+            if (prop === Symbol.asyncIterator ||
+                prop === "next" ||
+                prop === "return" ||
+                prop === "throw") {
+                const value = Reflect.get(target, prop);
+                if (typeof value === "function") {
+                    return value.bind(target);
+                }
+                return value;
+            }
+            const original = query[prop];
+            if (typeof original === "function") {
+                return original.bind(query);
+            }
+            return original;
+        },
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Introspection Client for Node.js
+ * Provides an API for tracking events and feedback using OTLP Logs.
+ *
+ * Identity and gen_ai context are automatically extracted from OpenTelemetry
+ * baggage.
+ */
+import { type IntrospectionClientOptions, type FeedbackOptions, type UserTraits } from "./types.js";
+/**
+ * Introspection client for tracking events and feedback using OTLP Logs.
+ *
+ * @example
+ * ```typescript
+ * const client = new IntrospectionClient({
+ *   token: process.env.INTROSPECTION_TOKEN,
+ * });
+ *
+ * client.identify("user_123", { email: "user@example.com" });
+ * client.feedback("thumbs_up", { comments: "Great response!" });
+ *
+ * await client.shutdown();
+ * ```
+ */
+export declare class IntrospectionClient {
+    private loggerProvider;
+    private otelLogger;
+    private userId;
+    private anonymousId;
+    private traits;
+    constructor(options?: IntrospectionClientOptions);
+    /** Get gen_ai context from baggage */
+    private getGenAiFromContext;
+    /** Get identity from baggage or client instance */
+    private getIdentityFromContext;
+    /**
+     * Get current timestamp as OpenTelemetry HrTime.
+     * Uses process.hrtime.bigint() for nanosecond precision in Node.js.
+     */
+    private getTimestamp;
+    /**
+     * Build log record attributes.
+     */
+    private buildAttributes;
+    /**
+     * Track a custom event.
+     *
+     * @param eventName - A descriptive name for the event (e.g. `"page_view"`).
+     * @param properties - Arbitrary key/value pairs attached to the event.
+     * @param options - Optional overrides such as a custom `eventId`.
+     */
+    track(eventName: string, properties?: Record<string, unknown>, options?: {
+        eventId?: string;
+    }): void;
+    /**
+     * Track feedback on a message or response.
+     *
+     * @param name - Feedback type (e.g. `"thumbs_up"`, `"thumbs_down"`).
+     * @param options - Additional feedback context such as comments or conversation ID.
+     */
+    feedback(name: string, options?: FeedbackOptions): void;
+    /**
+     * Identify a user and associate traits with them.
+     *
+     * @param userId - Unique identifier for the user.
+     * @param traits - Key/value user properties (e.g. `{ email: "…" }`).
+     * @param anonymousId - Optional anonymous identifier to link pre-auth sessions.
+     * @param eventId - Optional custom event ID override.
+     */
+    identify(userId: string, traits?: UserTraits, anonymousId?: string, eventId?: string): void;
+    /**
+     * Create an OTel context with the given baggage values set.
+     *
+     * @param values - Key/value pairs to store in OTel baggage.
+     * @returns A new context containing the baggage entries.
+     */
+    createBaggageContext(values: Record<string, string>): import("@opentelemetry/api").Context;
+    /**
+     * Set multiple baggage values and run a callback within that context.
+     *
+     * @param values - Key/value pairs to store in OTel baggage.
+     * @param callback - Function to execute with the baggage context active.
+     * @returns The value returned by `callback`.
+     */
+    withBaggage<T>(values: Record<string, string>, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Set `gen_ai.agent.name` (and optionally `gen_ai.agent.id`) baggage and run
+     * a callback within that context.
+     *
+     * @param agentName - The agent name to propagate.
+     * @param agentId - Optional agent identifier.
+     * @param callback - Function to execute with the agent baggage active.
+     * @returns The value returned by `callback`.
+     */
+    withAgent<T>(agentName: string, agentId: string | undefined, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Set conversation-related baggage (`gen_ai.conversation.id`,
+     * `gen_ai.request.previous_response_id`) and run a callback within that
+     * context.
+     *
+     * @param conversationId - The conversation identifier.
+     * @param previousResponseId - The ID of the previous response in the conversation.
+     * @param callback - Function to execute with the conversation baggage active.
+     * @returns The value returned by `callback`.
+     */
+    withConversation<T>(conversationId: string | undefined, previousResponseId: string | undefined, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Set the user ID on this client instance.
+     *
+     * @param userId - Unique identifier for the user.
+     */
+    setUserId(userId: string): void;
+    /**
+     * Set the anonymous ID on this client instance.
+     *
+     * @param anonymousId - Anonymous identifier used before authentication.
+     */
+    setAnonymousId(anonymousId: string): void;
+    /**
+     * Set `identity.user_id` baggage and run a callback within that context.
+     *
+     * @param userId - The user identifier to propagate.
+     * @param callback - Function to execute with the user-ID baggage active.
+     * @returns The value returned by `callback`.
+     */
+    withUserId<T>(userId: string, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Set `identity.anonymous_id` baggage and run a callback within that context.
+     *
+     * @param anonymousId - The anonymous identifier to propagate.
+     * @param callback - Function to execute with the anonymous-ID baggage active.
+     * @returns The value returned by `callback`.
+     */
+    withAnonymousId<T>(anonymousId: string, callback: () => T | Promise<T>): Promise<T>;
+    /**
+     * Get the current anonymous ID stored on this client instance.
+     *
+     * @returns The anonymous ID, or `undefined` if not set.
+     */
+    getAnonymousId(): string | undefined;
+    /**
+     * Reset all client-side state (user ID, anonymous ID, and traits).
+     */
+    reset(): void;
+    /**
+     * Flush all queued log records to the backend.
+     *
+     * @returns A promise that resolves once the flush completes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shut down the client, flushing all pending log records.
+     *
+     * @returns A promise that resolves once shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,OAAO,EAEL,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACpB,KAAK,UAAU,EAGhB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,MAAM,CAA+B;gBAEjC,OAAO,GAAE,0BAA+B;IAqEpD,sCAAsC;IACtC,OAAO,CAAC,mBAAmB;IAY3B,mDAAmD;IACnD,OAAO,CAAC,sBAAsB;IAS9B;;;OAGG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;IACH,OAAO,CAAC,eAAe;IAuFvB;;;;;;OAMG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B,IAAI;IAiBP;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI;IA2B3D;;;;;;;OAOG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,UAAU,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,GACf,IAAI;IAsBP;;;;;OAKG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAWnD;;;;;;OAMG;IACG,WAAW,CAAC,CAAC,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC;IAKb;;;;;;;;OAQG;IACG,SAAS,CAAC,CAAC,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC;IAQb;;;;;;;;;OASG;IACG,gBAAgB,CAAC,CAAC,EACtB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,QAAQ,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC;IAWb;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIzC;;;;;;OAMG;IACG,UAAU,CAAC,CAAC,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC;IAOb;;;;;;OAMG;IACG,eAAe,CAAC,CAAC,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC;IAOb;;;;OAIG;IACH,cAAc,IAAI,MAAM,GAAG,SAAS;IAIpC;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAIhC"}