@introspection-sdk/introspection-node 0.4.2 → 0.4.4

package/dist/otel/init.js

@@ -0,0 +1,259 @@
+/**
+ * One-liner bootstrap for the Introspection OTel surface.
+ *
+ * `init()` detects the installed LLM frameworks and wires them into one shared
+ * pipeline, mirroring the Python SDK's `introspection.init()`:
+ *
+ * ```ts
+ * import * as introspection from "@introspection-sdk/introspection-node/otel";
+ * import Anthropic from "@anthropic-ai/sdk";
+ *
+ * await introspection.init({ serviceName: "my-app" });
+ *
+ * const client = new Anthropic(); // auto-traced — no per-client wiring
+ * await introspection.conversation(() =>
+ *   client.messages.create({ ... }),
+ * );
+ * ```
+ *
+ * It also exposes the `track` / `feedback` / `identify` analytics surface and a
+ * `conversation()` scope, proxied to a global {@link IntrospectionLogs}.
+ */
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { logger } from "../utils.js";
+import { discoverIntegrations, setupIntegrations, teardownIntegrations, } from "./integrations/index.js";
+import { IntrospectionLogs } from "./logs.js";
+import { registerOTelGlobals } from "./setup.js";
+import { IntrospectionSpanProcessor } from "./span-processor.js";
+const state = {
+    provider: null,
+    ownsProvider: false,
+    logs: null,
+    handles: {},
+    shutdownRegistered: false,
+};
+/** Generate a fresh conversation id (matches the Python SDK's format). */
+export function newConversationId() {
+    return `intro_conv_${crypto.randomUUID().replace(/-/g, "")}`;
+}
+function resolveProvider(options, token, serviceName, advanced) {
+    // baggage scopes (conversation/agent/identity) need these globals regardless
+    // of who owns the provider.
+    registerOTelGlobals(options.onConflict);
+    if (options.tracerProvider)
+        return options.tracerProvider;
+    const provider = new NodeTracerProvider({
+        resource: serviceName
+            ? resourceFromAttributes({ [ATTR_SERVICE_NAME]: serviceName })
+            : undefined,
+        // Order is irrelevant (IntrospectionSpanProcessor exports an isolated
+        // converted copy and never mutates the shared span); listed first to match
+        // setupTracing()'s ordering.
+        spanProcessors: [
+            new IntrospectionSpanProcessor({ token, serviceName, advanced }),
+            ...(options.spanProcessors ?? []),
+        ],
+    });
+    provider.register();
+    return provider;
+}
+/**
+ * Detect installed LLM frameworks and wire them into one shared provider.
+ *
+ * Idempotent: repeated calls return the already-configured provider without
+ * re-installing integrations.
+ */
+export async function init(options = {}) {
+    if (state.provider) {
+        logger.debug("introspection.init() already called; returning provider");
+        return state.provider;
+    }
+    const token = options.token ?? process.env.INTROSPECTION_TOKEN;
+    const serviceName = options.serviceName ?? process.env.INTROSPECTION_SERVICE_NAME ?? undefined;
+    const baseUrl = options.baseUrl ?? process.env.INTROSPECTION_BASE_OTEL_URL ?? undefined;
+    const advanced = options.advanced;
+    // A custom span exporter (tests) stands in for a token; otherwise a token is
+    // required for anything to be exported.
+    if (!token && !advanced?.spanExporter && !options.tracerProvider) {
+        throw new Error("introspection.init() requires a token. Set INTROSPECTION_TOKEN or pass { token }.");
+    }
+    const ownsProvider = !options.tracerProvider;
+    const provider = resolveProvider(options, token, serviceName, advanced);
+    // The track / feedback / identify surface is a separate OTLP log stream.
+    const logs = new IntrospectionLogs({
+        token,
+        serviceName,
+        baseOtelUrl: baseUrl,
+        additionalHeaders: advanced?.additionalHeaders,
+        flushInterval: advanced?.flushInterval,
+        maxBatchSize: advanced?.maxBatchSize,
+    });
+    const ctx = {
+        tracerProvider: provider,
+        token,
+        serviceName,
+        baseUrl,
+        advanced,
+        handles: state.handles,
+    };
+    // Run discovery + setup BEFORE committing global state, so a failure here
+    // doesn't leave a half-configured provider behind the idempotency guard
+    // (a later init() would otherwise return the broken provider and never retry).
+    try {
+        const toInstall = [];
+        if (options.autoDiscover !== false) {
+            toInstall.push(...(await discoverIntegrations()));
+        }
+        if (options.integrations)
+            toInstall.push(...options.integrations);
+        setupIntegrations(toInstall, ctx);
+    }
+    catch (e) {
+        state.handles = {};
+        throw e;
+    }
+    state.provider = provider;
+    state.ownsProvider = ownsProvider;
+    state.logs = logs;
+    if (!state.shutdownRegistered) {
+        process.once("beforeExit", () => {
+            void shutdown();
+        });
+        state.shutdownRegistered = true;
+    }
+    return provider;
+}
+/** Return the global logs client. Throws if {@link init} has not been called. */
+export function getClient() {
+    if (!state.logs) {
+        throw new Error("introspection.init() must be called before using track / feedback / identify.");
+    }
+    return state.logs;
+}
+/** Return the shared provider. Throws if {@link init} has not been called. */
+export function getTracerProvider() {
+    if (!state.provider) {
+        throw new Error("introspection.init() must be called first.");
+    }
+    return state.provider;
+}
+/** Track an analytics event. Requires {@link init} first. */
+export function track(eventName, properties, options) {
+    getClient().track(eventName, properties, options);
+}
+/** Record feedback on an AI response. Requires {@link init} first. */
+export function feedback(name, options = {}) {
+    getClient().feedback(name, options);
+}
+/** Associate the current context with a user. Requires {@link init} first. */
+export function identify(userId, traits, anonymousId, eventId) {
+    getClient().identify(userId, traits, anonymousId, eventId);
+}
+export function conversation(a, b) {
+    const conversationId = typeof a === "string" ? a : newConversationId();
+    const callback = (typeof a === "string" ? b : a);
+    return getClient().withConversation(conversationId, undefined, () => callback(conversationId));
+}
+/**
+ * Run `callback` with `gen_ai.agent.name` (+ optional `gen_ai.agent.id`) on the
+ * baggage, so spans/events produced within are attributed to that agent.
+ * Requires {@link init} first. Mirrors `IntrospectionLogs.withAgent`.
+ */
+export function withAgent(agentName, agentId, callback) {
+    return getClient().withAgent(agentName, agentId, callback);
+}
+/**
+ * Run `callback` inside a conversation scope, optionally chaining a previous
+ * response id. Unlike {@link conversation}, the id is required (no auto-gen).
+ * Requires {@link init} first.
+ */
+export function withConversation(conversationId, previousResponseId, callback) {
+    return getClient().withConversation(conversationId, previousResponseId, callback);
+}
+/** Run `callback` with `identity.user_id` on the baggage. Requires {@link init} first. */
+export function withUserId(userId, callback) {
+    return getClient().withUserId(userId, callback);
+}
+/** Run `callback` with `identity.anonymous_id` on the baggage. Requires {@link init} first. */
+export function withAnonymousId(anonymousId, callback) {
+    return getClient().withAnonymousId(anonymousId, callback);
+}
+/**
+ * The LangChain handler bound by `init()`. Attach it per-invoke:
+ * `chain.invoke(input, { callbacks: [introspection.getLangchainHandler()] })`.
+ */
+export function getLangchainHandler() {
+    const handler = state.handles.langchainHandler;
+    if (!handler) {
+        throw new Error("LangChain integration not configured. Call introspection.init() with @langchain/core installed.");
+    }
+    return handler;
+}
+/** The Mastra exporter bound by `init()`. Put it in `observability.configs`. */
+export function getMastraExporter() {
+    const exporter = state.handles.mastraExporter;
+    if (!exporter) {
+        throw new Error("Mastra integration not configured. Call introspection.init() with @mastra/core installed.");
+    }
+    return exporter;
+}
+/** Instrument a Pi `Agent` against the shared provider. Requires {@link init}. */
+export function instrumentPi(agent, meta) {
+    const instrumentor = state.handles.piInstrumentor;
+    if (!instrumentor) {
+        throw new Error("Pi integration not configured. Call introspection.init() with @mariozechner/pi-agent-core installed.");
+    }
+    instrumentor.instrument(agent, meta);
+}
+/**
+ * Wrap the Claude Agent SDK module so its `query()` calls are traced.
+ * Equivalent to `withIntrospection(sdk)` but pre-bound to the `init()` config.
+ */
+export function instrumentClaudeAgent(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sdk) {
+    const fn = state.handles.instrumentClaudeAgent;
+    if (!fn) {
+        throw new Error("Claude Agent integration not configured. Call introspection.init() with @anthropic-ai/claude-agent-sdk installed.");
+    }
+    return fn(sdk);
+}
+/** Flush and shut down the logs client and (if owned) the provider. */
+export async function shutdown() {
+    const { logs, provider, ownsProvider } = state;
+    if (logs) {
+        try {
+            await logs.shutdown();
+        }
+        catch (e) {
+            logger.debug(`Error shutting down logs client: ${String(e)}`);
+        }
+    }
+    if (ownsProvider && provider && "shutdown" in provider) {
+        try {
+            await provider.shutdown();
+        }
+        catch (e) {
+            logger.debug(`Error shutting down provider: ${String(e)}`);
+        }
+    }
+    // Run integration teardowns (uninstrument prototype patches) + clear the
+    // run-once guard so a later init() re-installs and rebuilds the handles
+    // against the new provider instead of being skipped.
+    teardownIntegrations();
+    state.provider = null;
+    state.ownsProvider = false;
+    state.logs = null;
+    state.handles = {};
+}
+/** Reset module state. Test-only utility. */
+export function _resetForTests() {
+    teardownIntegrations();
+    state.provider = null;
+    state.ownsProvider = false;
+    state.logs = null;
+    state.handles = {};
+}
+//# sourceMappingURL=init.js.map

package/dist/otel/init.js.map

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

package/dist/otel/integrations/anthropic.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Anthropic Node SDK integration.
+ *
+ * Patches `Anthropic.Messages.prototype.create` so every `new Anthropic()`
+ * client is traced against the shared provider — no per-client wiring.
+ */
+import type { Integration } from "./base.js";
+declare const integration: Integration;
+export default integration;
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/otel/integrations/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WASlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/anthropic.js

@@ -0,0 +1,22 @@
+/**
+ * Anthropic Node SDK integration.
+ *
+ * Patches `Anthropic.Messages.prototype.create` so every `new Anthropic()`
+ * client is traced against the shared provider — no per-client wiring.
+ */
+// Top-level import gates availability: if `@anthropic-ai/sdk` is not installed
+// the dynamic import of this module rejects and discovery skips the shim.
+import Anthropic from "@anthropic-ai/sdk";
+import { AnthropicInstrumentor } from "../anthropic.js";
+const integration = {
+    identifier: "anthropic",
+    setupOnce({ tracerProvider }) {
+        const instrumentor = new AnthropicInstrumentor();
+        instrumentor.instrumentClass({ anthropic: Anthropic, tracerProvider });
+        // Restore the original prototype on shutdown so a later init() re-patches
+        // against the rebuilt provider (the patch captures the provider's tracer).
+        return () => instrumentor.uninstrument();
+    },
+};
+export default integration;
+//# sourceMappingURL=anthropic.js.map

package/dist/otel/integrations/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../../src/otel/integrations/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,0EAA0E;AAC1E,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,WAAW;IACvB,SAAS,CAAC,EAAE,cAAc,EAAE;QAC1B,MAAM,YAAY,GAAG,IAAI,qBAAqB,EAAE,CAAC;QACjD,YAAY,CAAC,eAAe,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,CAAC;QACvE,0EAA0E;QAC1E,2EAA2E;QAC3E,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,CAAC;IAC3C,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/base.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Integration base contract, modeled on Sentry's integration registry and the
+ * Python SDK's `Integration` ABC.
+ *
+ * An {@link Integration} knows how to wire one framework (Anthropic, Gemini,
+ * OpenAI Agents, …) into the shared Introspection trace pipeline. `init()`
+ * discovers the integrations whose framework is importable and runs each
+ * `setupOnce()` exactly once.
+ */
+import type { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import type { AdvancedOptions } from "../../types.js";
+import type { InstrumentedClaudeAgentSDK } from "../claude-wrapper.js";
+import type { IntrospectionCallbackHandler } from "../langchain-handler.js";
+import type { IntrospectionPiInstrumentor } from "../pi.js";
+/**
+ * Bound framework handles published by instance/config-based integrations.
+ *
+ * Some JS framework hooks cannot be wired globally — the caller still has to
+ * pass a handler to `chain.invoke({ callbacks })`, put an exporter in the
+ * Mastra config, instrument an Agent instance, or wrap the Claude Agent SDK
+ * module. For those, the integration publishes a handle here, pre-bound to the
+ * `init()` token / provider, and `init()` re-exposes it (e.g.
+ * `introspection.getLangchainHandler()`).
+ */
+export interface IntegrationHandles {
+    langchainHandler?: IntrospectionCallbackHandler;
+    mastraExporter?: any;
+    piInstrumentor?: IntrospectionPiInstrumentor;
+    instrumentClaudeAgent?: (sdk: any) => InstrumentedClaudeAgentSDK;
+}
+/**
+ * Thrown by an integration module/`setupOnce` when the framework cannot be
+ * activated (package missing, version too old, …).
+ *
+ * Swallowed during auto-discovery so a missing framework just skips its shim;
+ * re-raised only when an integration is requested explicitly.
+ */
+export declare class DidNotEnable extends Error {
+    constructor(message: string);
+}
+/**
+ * Everything an integration needs to wire itself into the shared pipeline.
+ *
+ * Most JS framework hooks (the OpenAI Agents processor, the LangChain handler,
+ * the Mastra exporter) own their own OTLP export pipeline and only need the
+ * `token` / `serviceName` / `baseUrl`. Instrumentors that emit onto the shared
+ * `TracerProvider` (Anthropic, Gemini, Vercel AI SDK, Pi) use `tracerProvider`.
+ */
+export interface IntegrationSetupContext {
+    /** The shared provider built (or adopted) by `init()`. */
+    tracerProvider: BasicTracerProvider;
+    /** Auth token resolved by `init()` (arg → env). */
+    token?: string;
+    /** Service name resolved by `init()`. */
+    serviceName?: string;
+    /** OTLP base URL resolved by `init()`. */
+    baseUrl?: string;
+    /** Advanced options (custom exporter for tests, headers, …). */
+    advanced?: AdvancedOptions;
+    /** Mutable bag for integrations to publish pre-bound framework handles. */
+    handles: IntegrationHandles;
+}
+/**
+ * A framework integration. Each built-in integration is a singleton object;
+ * users may also pass custom integrations to `init({ integrations: [...] })`.
+ */
+export interface Integration {
+    /** Stable identifier used for the run-once guard and `deactivates`. */
+    readonly identifier: string;
+    /**
+     * Identifiers of other integrations to disable when this one is active, so a
+     * wrapping framework (e.g. LangChain) does not double-trace the SDK it wraps.
+     */
+    readonly deactivates?: readonly string[];
+    /**
+     * Wire the framework into the shared pipeline. Runs once; may throw
+     * {@link DidNotEnable}. May return a teardown callback (e.g. to uninstrument a
+     * prototype patch) that `introspection.shutdown()` runs so a later `init()`
+     * re-installs cleanly against the rebuilt provider.
+     */
+    setupOnce(ctx: IntegrationSetupContext): void | (() => void);
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/otel/integrations/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,CAAC,EAAE,4BAA4B,CAAC;IAEhD,cAAc,CAAC,EAAE,GAAG,CAAC;IACrB,cAAc,CAAC,EAAE,2BAA2B,CAAC;IAC7C,qBAAqB,CAAC,EAAE,CAEtB,GAAG,EAAE,GAAG,KACL,0BAA0B,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,cAAc,EAAE,mBAAmB,CAAC;IACpC,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,2EAA2E;IAC3E,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,uBAAuB,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;CAC9D"}

package/dist/otel/integrations/base.js

@@ -0,0 +1,23 @@
+/**
+ * Integration base contract, modeled on Sentry's integration registry and the
+ * Python SDK's `Integration` ABC.
+ *
+ * An {@link Integration} knows how to wire one framework (Anthropic, Gemini,
+ * OpenAI Agents, …) into the shared Introspection trace pipeline. `init()`
+ * discovers the integrations whose framework is importable and runs each
+ * `setupOnce()` exactly once.
+ */
+/**
+ * Thrown by an integration module/`setupOnce` when the framework cannot be
+ * activated (package missing, version too old, …).
+ *
+ * Swallowed during auto-discovery so a missing framework just skips its shim;
+ * re-raised only when an integration is requested explicitly.
+ */
+export class DidNotEnable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DidNotEnable";
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/otel/integrations/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/otel/integrations/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8BH;;;;;;GAMG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/otel/integrations/claude-agent.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Claude Agent SDK integration.
+ *
+ * The Claude Agent SDK is instrumented by wrapping its module
+ * (`withIntrospection(sdk)`), which there is no global hook for. So this
+ * integration publishes a pre-bound `instrumentClaudeAgent(sdk)` handle that
+ * `init()` re-exposes as `introspection.instrumentClaudeAgent(sdk)`.
+ */
+import "@anthropic-ai/claude-agent-sdk";
+import type { Integration } from "./base.js";
+declare const integration: Integration;
+export default integration;
+//# sourceMappingURL=claude-agent.d.ts.map

package/dist/otel/integrations/claude-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-agent.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/claude-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,gCAAgC,CAAC;AAGxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WAclB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/claude-agent.js

@@ -0,0 +1,27 @@
+/**
+ * Claude Agent SDK integration.
+ *
+ * The Claude Agent SDK is instrumented by wrapping its module
+ * (`withIntrospection(sdk)`), which there is no global hook for. So this
+ * integration publishes a pre-bound `instrumentClaudeAgent(sdk)` handle that
+ * `init()` re-exposes as `introspection.instrumentClaudeAgent(sdk)`.
+ */
+// Presence gate.
+import "@anthropic-ai/claude-agent-sdk";
+import { withIntrospection } from "../claude-wrapper.js";
+const integration = {
+    identifier: "claude_agent",
+    setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
+        handles.instrumentClaudeAgent = (sdk) => withIntrospection(sdk, {
+            token,
+            serviceName,
+            baseUrl,
+            additionalHeaders: advanced?.additionalHeaders,
+            advanced: advanced?.spanExporter
+                ? { spanExporter: advanced.spanExporter }
+                : undefined,
+        });
+    },
+};
+export default integration;
+//# sourceMappingURL=claude-agent.js.map

package/dist/otel/integrations/claude-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-agent.js","sourceRoot":"","sources":["../../../src/otel/integrations/claude-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iBAAiB;AACjB,OAAO,gCAAgC,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,cAAc;IAC1B,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE;QAC1D,OAAO,CAAC,qBAAqB,GAAG,CAAC,GAAG,EAAE,EAAE,CACtC,iBAAiB,CAAC,GAAG,EAAE;YACrB,KAAK;YACL,WAAW;YACX,OAAO;YACP,iBAAiB,EAAE,QAAQ,EAAE,iBAAiB;YAC9C,QAAQ,EAAE,QAAQ,EAAE,YAAY;gBAC9B,CAAC,CAAC,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE;gBACzC,CAAC,CAAC,SAAS;SACd,CAAC,CAAC;IACP,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/gemini.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Gemini (`@google/genai`) integration.
+ *
+ * Patches `Models.prototype.generateContentInternal` / `…StreamInternal` so
+ * every `GoogleGenAI` client is traced. Preserves the thought-signature
+ * capture the standalone `GeminiInstrumentor` is built for.
+ */
+import type { Integration } from "./base.js";
+declare const integration: Integration;
+export default integration;
+//# sourceMappingURL=gemini.d.ts.map

package/dist/otel/integrations/gemini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/gemini.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WASlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/gemini.js

@@ -0,0 +1,21 @@
+/**
+ * Gemini (`@google/genai`) integration.
+ *
+ * Patches `Models.prototype.generateContentInternal` / `…StreamInternal` so
+ * every `GoogleGenAI` client is traced. Preserves the thought-signature
+ * capture the standalone `GeminiInstrumentor` is built for.
+ */
+import * as genai from "@google/genai";
+import { GeminiInstrumentor } from "../gemini.js";
+const integration = {
+    identifier: "gemini",
+    setupOnce({ tracerProvider }) {
+        const instrumentor = new GeminiInstrumentor();
+        instrumentor.instrumentClass({ genai, tracerProvider });
+        // Restore the original prototype on shutdown so a later init() re-patches
+        // against the rebuilt provider (the patch captures the provider's tracer).
+        return () => instrumentor.uninstrument();
+    },
+};
+export default integration;
+//# sourceMappingURL=gemini.js.map

package/dist/otel/integrations/gemini.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../../src/otel/integrations/gemini.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,eAAe,CAAC;AAEvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,QAAQ;IACpB,SAAS,CAAC,EAAE,cAAc,EAAE;QAC1B,MAAM,YAAY,GAAG,IAAI,kBAAkB,EAAE,CAAC;QAC9C,YAAY,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;QACxD,0EAA0E;QAC1E,2EAA2E;QAC3E,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,CAAC;IAC3C,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Integration discovery + setup loader for `introspection.init()`.
+ *
+ * Mirrors the Python SDK's registry: built-in integrations are resolved
+ * lazily (a missing framework just skips its shim), `setupOnce` runs at most
+ * once per identifier per process, and an integration may `deactivate` others.
+ */
+import { DidNotEnable, type Integration, type IntegrationHandles, type IntegrationSetupContext } from "./base.js";
+export { DidNotEnable };
+export type { Integration, IntegrationHandles, IntegrationSetupContext };
+/**
+ * Distinguish "framework package not installed" (expected — skip quietly) from
+ * a real error inside an installed integration (a bug we shouldn't hide).
+ */
+export declare function isModuleNotFound(e: unknown): boolean;
+/**
+ * Return the built-in integrations whose framework is importable.
+ *
+ * Each module's top-level framework import determines availability: a missing
+ * package makes the dynamic import reject, which we log at debug and skip. Any
+ * OTHER failure (a real error inside an installed integration) is surfaced at
+ * warn level rather than silently swallowed — it's a bug, not an absent peer.
+ */
+export declare function discoverIntegrations(): Promise<Integration[]>;
+/**
+ * Run each integration's `setupOnce` once, honouring `deactivates`.
+ *
+ * @returns the set of identifiers installed so far this process.
+ */
+export declare function setupIntegrations(integrations: Integration[], ctx: IntegrationSetupContext): Set<string>;
+/**
+ * Run every integration teardown and clear the run-once guard, so the next
+ * `setupIntegrations()` (e.g. after `introspection.shutdown()` + a fresh
+ * `init()`) re-installs against the rebuilt provider instead of being skipped.
+ */
+export declare function teardownIntegrations(): void;
+/** Clear the run-once guard (running teardowns). Test-only utility. */
+export declare function resetInstalledForTests(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/otel/integrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC7B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,CAAC;AA0BzE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAOpD;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAmBnE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,WAAW,EAAE,EAC3B,GAAG,EAAE,uBAAuB,GAC3B,GAAG,CAAC,MAAM,CAAC,CAoCb;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAS3C;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}