@introspection-sdk/introspection-node 0.4.6 → 0.4.8

package/dist/otel/integrations/index.js

@@ -6,13 +6,12 @@
  * once per identifier per process, and an integration may `deactivate` others.
  */
 import { logger } from "../../utils.js";
-import { DidNotEnable, } from "./base.js";
-export { DidNotEnable };
+import { DidNotEnable, isModuleNotFound, } from "./base.js";
+export { DidNotEnable, isModuleNotFound };
 /**
- * Built-in integrations, loaded lazily. Each thunk dynamically imports an
- * integration module; that module imports its framework at the top level, so
- * if the framework is not installed the import rejects and the integration is
- * skipped. Order matters only for `deactivates` resolution (handled below).
+ * Built-in integrations, loaded lazily. Each integration probes its optional
+ * framework package at runtime, so importing the OTel barrel never requires
+ * every optional framework SDK to be installed.
  */
 const BUILTIN_INTEGRATIONS = [
     () => import("./anthropic.js"),
@@ -28,25 +27,22 @@ const installed = new Set();
 // Teardown callbacks returned by integration setupOnce (e.g. uninstrument a
 // prototype patch), run by teardownIntegrations() on shutdown.
 const teardowns = [];
-/**
- * Distinguish "framework package not installed" (expected — skip quietly) from
- * a real error inside an installed integration (a bug we shouldn't hide).
- */
-export function isModuleNotFound(e) {
-    const code = e?.code;
-    if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
-        return true;
+async function availableIntegrations(integrations) {
+    const available = [];
+    for (const integration of integrations) {
+        if (integration.isAvailable && !(await integration.isAvailable())) {
+            continue;
+        }
+        available.push(integration);
     }
-    const msg = e instanceof Error ? e.message : String(e);
-    return /Cannot find (module|package)|Failed to resolve/i.test(msg);
+    return available;
 }
 /**
  * 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.
+ * Missing optional peer packages are expected and skipped quietly. Any OTHER
+ * failure is surfaced at warn level rather than silently swallowed — it's a
+ * bug, not an absent peer.
  */
 export async function discoverIntegrations() {
     const found = [];
@@ -65,17 +61,17 @@ export async function discoverIntegrations() {
             }
         }
     }
-    return found;
+    return availableIntegrations(found);
 }
 /**
  * Run each integration's `setupOnce` once, honouring `deactivates`.
  *
  * @returns the set of identifiers installed so far this process.
  */
-export function setupIntegrations(integrations, ctx) {
+export async function setupIntegrations(integrations, ctx) {
     // First-wins de-dupe by identifier.
     const byId = new Map();
-    for (const integration of integrations) {
+    for (const integration of await availableIntegrations(integrations)) {
         if (!byId.has(integration.identifier)) {
             byId.set(integration.identifier, integration);
         }
@@ -93,7 +89,7 @@ export function setupIntegrations(integrations, ctx) {
         if (installed.has(identifier))
             continue;
         try {
-            const teardown = integration.setupOnce(ctx);
+            const teardown = await integration.setupOnce(ctx);
             if (typeof teardown === "function")
                 teardowns.push(teardown);
             installed.add(identifier);

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

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

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

@@ -9,8 +9,7 @@
  * model, the handler already traces the call, so the prototype-level Anthropic
  * patch would double-trace it.
  */
-import "@langchain/core/callbacks/base";
-import type { Integration } from "./base.js";
+import { type Integration } from "./base.js";
 declare const integration: Integration;
 export default integration;
 //# sourceMappingURL=langchain.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/langchain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,gCAAgC,CAAC;AAGxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WAwBlB,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/langchain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AAWnB,QAAA,MAAM,WAAW,EAAE,WA6BlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/langchain.js

@@ -9,11 +9,11 @@
  * model, the handler already traces the call, so the prototype-level Anthropic
  * patch would double-trace it.
  */
-// Presence gate.
-import "@langchain/core/callbacks/base";
-import { IntrospectionCallbackHandler } from "../langchain-handler.js";
+import { importOptionalPeer, isOptionalPeerInstalled, OPTIONAL_PEERS, } from "./base.js";
+const importLocal = (specifier) => import(specifier);
 const integration = {
     identifier: "langchain",
+    isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.langchainCallbacks),
     // Intentional, and matches the Python SDK: when @langchain/core is present,
     // auto-discovery skips the always-on raw-Anthropic prototype patch so a
     // LangChain → ChatAnthropic call isn't traced twice (once by LangChain's
@@ -25,7 +25,9 @@ const integration = {
     // `new AnthropicInstrumentor().instrumentClass(...)`, or call
     // `init({ autoDiscover: false, integrations: [anthropicIntegration] })`.
     deactivates: ["anthropic"],
-    setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
+    async setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
+        await importOptionalPeer(OPTIONAL_PEERS.langchainCallbacks);
+        const { IntrospectionCallbackHandler } = await importLocal("../langchain-handler.js");
         handles.langchainHandler = new IntrospectionCallbackHandler({
             token,
             serviceName,

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

@@ -1 +1 @@
-{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../../../src/otel/integrations/langchain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iBAAiB;AACjB,OAAO,gCAAgC,CAAC;AAExC,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAGvE,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,WAAW;IACvB,4EAA4E;IAC5E,wEAAwE;IACxE,yEAAyE;IACzE,8DAA8D;IAC9D,EAAE;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,kEAAkE;IAClE,8DAA8D;IAC9D,yEAAyE;IACzE,WAAW,EAAE,CAAC,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE;QAC1D,OAAO,CAAC,gBAAgB,GAAG,IAAI,4BAA4B,CAAC;YAC1D,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;IACL,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../../../src/otel/integrations/langchain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,GAEf,MAAM,WAAW,CAAC;AAGnB,MAAM,WAAW,GAAG,CAAC,SAAiB,EAAE,EAAE,CACxC,MAAM,CAAC,SAAS,CAKd,CAAC;AAEL,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,WAAW;IACvB,WAAW,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,cAAc,CAAC,kBAAkB,CAAC;IAC7E,4EAA4E;IAC5E,wEAAwE;IACxE,yEAAyE;IACzE,8DAA8D;IAC9D,EAAE;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,kEAAkE;IAClE,8DAA8D;IAC9D,yEAAyE;IACzE,WAAW,EAAE,CAAC,WAAW,CAAC;IAC1B,KAAK,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE;QAChE,MAAM,kBAAkB,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC;QAC5D,MAAM,EAAE,4BAA4B,EAAE,GAAG,MAAM,WAAW,CACxD,yBAAyB,CAC1B,CAAC;QACF,OAAO,CAAC,gBAAgB,GAAG,IAAI,4BAA4B,CAAC;YAC1D,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;IACL,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

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

@@ -8,7 +8,7 @@
  * Importing `../mastra-exporter.js` (which requires `@mastra/observability`)
  * is the presence gate: a missing Mastra makes discovery skip this shim.
  */
-import type { Integration } from "./base.js";
+import { type Integration } from "./base.js";
 declare const integration: Integration;
 export default integration;
 //# sourceMappingURL=mastra.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"mastra.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/mastra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WAalB,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"mastra.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/mastra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AAUnB,QAAA,MAAM,WAAW,EAAE,WAmBlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/mastra.js

@@ -8,10 +8,14 @@
  * Importing `../mastra-exporter.js` (which requires `@mastra/observability`)
  * is the presence gate: a missing Mastra makes discovery skip this shim.
  */
-import { IntrospectionMastraExporter } from "../mastra-exporter.js";
+import { importOptionalPeer, isOptionalPeerInstalled, OPTIONAL_PEERS, } from "./base.js";
+const importLocal = (specifier) => import(specifier);
 const integration = {
     identifier: "mastra",
-    setupOnce({ token, baseUrl, advanced, handles }) {
+    isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.mastraObservability),
+    async setupOnce({ token, baseUrl, advanced, handles }) {
+        await importOptionalPeer(OPTIONAL_PEERS.mastraObservability);
+        const { IntrospectionMastraExporter } = await importLocal("../mastra-exporter.js");
         handles.mastraExporter = new IntrospectionMastraExporter({
             token,
             baseUrl,

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

@@ -1 +1 @@
-{"version":3,"file":"mastra.js","sourceRoot":"","sources":["../../../src/otel/integrations/mastra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAGpE,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,QAAQ;IACpB,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE;QAC7C,OAAO,CAAC,cAAc,GAAG,IAAI,2BAA2B,CAAC;YACvD,KAAK;YACL,OAAO;YACP,iBAAiB,EAAE,QAAQ,EAAE,iBAAiB;YAC9C,KAAK,EAAE,QAAQ,EAAE,KAAK;YACtB,QAAQ,EAAE,QAAQ,EAAE,YAAY;gBAC9B,CAAC,CAAC,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE;gBACzC,CAAC,CAAC,SAAS;SACd,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"mastra.js","sourceRoot":"","sources":["../../../src/otel/integrations/mastra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,GAEf,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,GAAG,CAAC,SAAiB,EAAE,EAAE,CACxC,MAAM,CAAC,SAAS,CAKd,CAAC;AAEL,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,QAAQ;IACpB,WAAW,EAAE,GAAG,EAAE,CAChB,uBAAuB,CAAC,cAAc,CAAC,mBAAmB,CAAC;IAC7D,KAAK,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE;QACnD,MAAM,kBAAkB,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QAC7D,MAAM,EAAE,2BAA2B,EAAE,GAAG,MAAM,WAAW,CACvD,uBAAuB,CACxB,CAAC;QACF,OAAO,CAAC,cAAc,GAAG,IAAI,2BAA2B,CAAC;YACvD,KAAK;YACL,OAAO;YACP,iBAAiB,EAAE,QAAQ,EAAE,iBAAiB;YAC9C,KAAK,EAAE,QAAQ,EAAE,KAAK;YACtB,QAAQ,EAAE,QAAQ,EAAE,YAAY;gBAC9B,CAAC,CAAC,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE;gBACzC,CAAC,CAAC,SAAS;SACd,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/openai-agents.d.ts

@@ -5,7 +5,7 @@
  * global trace pipeline. `addTraceProcessor` appends, preserving any processors
  * other integrations (e.g. a vendor exporter) already registered.
  */
-import type { Integration } from "./base.js";
+import { type Integration } from "./base.js";
 declare const integration: Integration;
 export default integration;
 //# sourceMappingURL=openai-agents.d.ts.map

package/dist/otel/integrations/openai-agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-agents.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/openai-agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WAelB,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"openai-agents.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/openai-agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AAMnB,QAAA,MAAM,WAAW,EAAE,WAwBlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/openai-agents.js

@@ -5,11 +5,16 @@
  * global trace pipeline. `addTraceProcessor` appends, preserving any processors
  * other integrations (e.g. a vendor exporter) already registered.
  */
-import { addTraceProcessor } from "@openai/agents";
 import { IntrospectionTracingProcessor } from "../tracing-processor.js";
+import { importOptionalPeer, isOptionalPeerInstalled, OPTIONAL_PEERS, } from "./base.js";
 const integration = {
     identifier: "openai_agents",
-    setupOnce({ token, serviceName, baseUrl, advanced }) {
+    isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.openaiAgents),
+    async setupOnce({ token, serviceName, baseUrl, advanced }) {
+        const { addTraceProcessor } = await importOptionalPeer(OPTIONAL_PEERS.openaiAgents);
+        if (!addTraceProcessor) {
+            throw new Error("Invalid @openai/agents module: addTraceProcessor missing");
+        }
         addTraceProcessor(new IntrospectionTracingProcessor({
             token,
             serviceName,

package/dist/otel/integrations/openai-agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai-agents.js","sourceRoot":"","sources":["../../../src/otel/integrations/openai-agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAGxE,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,eAAe;IAC3B,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE;QACjD,iBAAiB,CACf,IAAI,6BAA6B,CAAC;YAChC,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,CACH,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"openai-agents.js","sourceRoot":"","sources":["../../../src/otel/integrations/openai-agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,GAEf,MAAM,WAAW,CAAC;AAMnB,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,eAAe;IAC3B,WAAW,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,cAAc,CAAC,YAAY,CAAC;IACvE,KAAK,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE;QACvD,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,kBAAkB,CACpD,cAAc,CAAC,YAAY,CAC5B,CAAC;QACF,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,0DAA0D,CAC3D,CAAC;QACJ,CAAC;QACD,iBAAiB,CACf,IAAI,6BAA6B,CAAC;YAChC,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,CACH,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

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

@@ -5,8 +5,7 @@
  * builds the instrumentor — bound to the shared provider's global tracer — and
  * publishes it via `introspection.instrumentPi(agent, meta)`.
  */
-import "@earendil-works/pi-agent-core";
-import type { Integration } from "./base.js";
+import { type Integration } from "./base.js";
 declare const integration: Integration;
 export default integration;
 //# sourceMappingURL=pi.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pi.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/pi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WAOlB,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"pi.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/pi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AAEnB,QAAA,MAAM,WAAW,EAAE,WASlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/pi.js

@@ -5,12 +5,13 @@
  * builds the instrumentor — bound to the shared provider's global tracer — and
  * publishes it via `introspection.instrumentPi(agent, meta)`.
  */
-// Presence gate.
-import "@earendil-works/pi-agent-core";
 import { IntrospectionPiInstrumentor } from "../pi.js";
+import { importOptionalPeer, isOptionalPeerInstalled, OPTIONAL_PEERS, } from "./base.js";
 const integration = {
     identifier: "pi",
-    setupOnce({ handles }) {
+    isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.piAgentCore),
+    async setupOnce({ handles }) {
+        await importOptionalPeer(OPTIONAL_PEERS.piAgentCore);
         // The instrumentor emits onto the global tracer, which `init()` has just
         // registered with the shared IntrospectionSpanProcessor.
         handles.piInstrumentor = new IntrospectionPiInstrumentor();

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

@@ -1 +1 @@
-{"version":3,"file":"pi.js","sourceRoot":"","sources":["../../../src/otel/integrations/pi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iBAAiB;AACjB,OAAO,+BAA+B,CAAC;AAEvC,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAGvD,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,IAAI;IAChB,SAAS,CAAC,EAAE,OAAO,EAAE;QACnB,yEAAyE;QACzE,yDAAyD;QACzD,OAAO,CAAC,cAAc,GAAG,IAAI,2BAA2B,EAAE,CAAC;IAC7D,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"pi.js","sourceRoot":"","sources":["../../../src/otel/integrations/pi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,GAEf,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,IAAI;IAChB,WAAW,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,cAAc,CAAC,WAAW,CAAC;IACtE,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE;QACzB,MAAM,kBAAkB,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACrD,yEAAyE;QACzE,yDAAyD;QACzD,OAAO,CAAC,cAAc,GAAG,IAAI,2BAA2B,EAAE,CAAC;IAC7D,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

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

@@ -8,8 +8,7 @@
  * This integration exists so auto-discovery reports the AI SDK as detected and
  * (via its top-level import) is skipped when `ai` is not installed.
  */
-import "ai";
-import type { Integration } from "./base.js";
+import { type Integration } from "./base.js";
 declare const integration: Integration;
 export default integration;
 //# sourceMappingURL=vercel.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,IAAI,CAAC;AAEZ,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,QAAA,MAAM,WAAW,EAAE,WAKlB,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../../../src/otel/integrations/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AAEnB,QAAA,MAAM,WAAW,EAAE,WAMlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/otel/integrations/vercel.js

@@ -8,10 +8,10 @@
  * This integration exists so auto-discovery reports the AI SDK as detected and
  * (via its top-level import) is skipped when `ai` is not installed.
  */
-// Presence gate: a missing `ai` package makes this module's import reject.
-import "ai";
+import { isOptionalPeerInstalled, OPTIONAL_PEERS, } from "./base.js";
 const integration = {
     identifier: "vercel",
+    isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.vercelAi),
     setupOnce() {
         // No-op: the shared IntrospectionSpanProcessor converts AI SDK spans.
     },

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

@@ -1 +1 @@
-{"version":3,"file":"vercel.js","sourceRoot":"","sources":["../../../src/otel/integrations/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,OAAO,IAAI,CAAC;AAIZ,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,QAAQ;IACpB,SAAS;QACP,sEAAsE;IACxE,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"vercel.js","sourceRoot":"","sources":["../../../src/otel/integrations/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,uBAAuB,EACvB,cAAc,GAEf,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,GAAgB;IAC/B,UAAU,EAAE,QAAQ;IACpB,WAAW,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,cAAc,CAAC,QAAQ,CAAC;IACnE,SAAS;QACP,sEAAsE;IACxE,CAAC;CACF,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-sdk/introspection-node",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "license": "Apache-2.0",
   "description": "Introspection observability SDK for Node.js",
   "engines": {
@@ -43,18 +43,18 @@
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/sdk-trace-node": "^2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
-    "@types/node": "^22.19.19",
+    "@types/node": "^22.19.20",
     "eslint": "^9.39.4",
     "@langchain/core": "^1.1.48",
-    "@mastra/core": "^1.37.1",
-    "@mastra/observability": "^1.14.0",
+    "@mastra/core": "^1.41.0",
+    "@mastra/observability": "^1.14.1",
     "@earendil-works/pi-agent-core": "^0.75.4",
     "@earendil-works/pi-ai": "^0.75.4",
-    "@anthropic-ai/sdk": "^0.100.1",
-    "@anthropic-ai/claude-agent-sdk": "^0.3.159",
-    "@google/genai": "^2.6.0",
-    "ai": "^6.0.194",
-    "openai": "^6.40.0",
+    "@anthropic-ai/sdk": "^0.102.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.168",
+    "@google/genai": "^2.8.0",
+    "ai": "^6.0.197",
+    "openai": "^6.42.0",
     "typescript": "5.9.3",
     "@repo/typescript-config": "0.0.0",
     "@repo/eslint-config": "0.0.0"
@@ -138,9 +138,9 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "https-proxy-agent": "^7.0.6",
-    "@introspection-sdk/introspection-pi": "0.4.6",
-    "@introspection-sdk/types": "0.4.6",
-    "@introspection-sdk/introspection-proxy": "0.1.0"
+    "@introspection-sdk/types": "0.4.8",
+    "@introspection-sdk/introspection-proxy": "0.4.8",
+    "@introspection-sdk/introspection-pi": "0.4.8"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",

package/src/otel/init.ts

@@ -184,7 +184,7 @@ export async function init(options: InitOptions = {}): Promise<TracerProvider> {
       toInstall.push(...(await discoverIntegrations()));
     }
     if (options.integrations) toInstall.push(...options.integrations);
-    setupIntegrations(toInstall, ctx);
+    await setupIntegrations(toInstall, ctx);
   } catch (e) {
     state.handles = {};
     throw e;

package/src/otel/integrations/anthropic.ts

@@ -5,16 +5,26 @@
  * 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";
-import type { Integration } from "./base.js";
+import {
+  importOptionalPeer,
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
+
+async function loadAnthropicSdk(): Promise<unknown> {
+  const mod = await importOptionalPeer<{ default?: unknown }>(
+    OPTIONAL_PEERS.anthropic,
+  );
+  return mod.default ?? mod;
+}
 
 const integration: Integration = {
   identifier: "anthropic",
-  setupOnce({ tracerProvider }) {
+  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.anthropic),
+  async setupOnce({ tracerProvider }) {
+    const Anthropic = await loadAnthropicSdk();
     const instrumentor = new AnthropicInstrumentor();
     instrumentor.instrumentClass({ anthropic: Anthropic, tracerProvider });
     // Restore the original prototype on shutdown so a later init() re-patches

package/src/otel/integrations/base.ts

@@ -15,6 +15,17 @@ import type { InstrumentedClaudeAgentSDK } from "../claude-wrapper.js";
 import type { IntrospectionCallbackHandler } from "../langchain-handler.js";
 import type { IntrospectionPiInstrumentor } from "../pi.js";
 
+export const OPTIONAL_PEERS = {
+  anthropic: "@anthropic-ai/sdk",
+  claudeAgent: "@anthropic-ai/claude-agent-sdk",
+  gemini: "@google/genai",
+  langchainCallbacks: "@langchain/core/callbacks/base",
+  mastraObservability: "@mastra/observability",
+  openaiAgents: "@openai/agents",
+  piAgentCore: "@earendil-works/pi-agent-core",
+  vercelAi: "ai",
+} as const;
+
 /**
  * Bound framework handles published by instance/config-based integrations.
  *
@@ -50,6 +61,50 @@ export class DidNotEnable extends Error {
   }
 }
 
+/**
+ * Distinguish "framework package not installed" (expected — skip quietly) from
+ * a real error inside an installed integration (a bug we shouldn't hide).
+ */
+export function isModuleNotFound(e: unknown): boolean {
+  const code = (e as { code?: string } | null)?.code;
+  if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+    return true;
+  }
+  const msg = e instanceof Error ? e.message : String(e);
+  return /Cannot find (module|package)|Failed to resolve/i.test(msg);
+}
+
+/**
+ * Import an optional peer without leaving a static import edge for bundlers.
+ * Keep the `import()` argument variable-based: built-in framework integrations
+ * use this so importing `@introspection-sdk/introspection-node/otel` does not
+ * require every optional framework SDK to be installed.
+ */
+export async function importOptionalPeer<T = unknown>(
+  specifier: string,
+): Promise<T> {
+  try {
+    return (await import(specifier)) as T;
+  } catch (e) {
+    if (isModuleNotFound(e)) {
+      throw new DidNotEnable(`Optional peer ${specifier} is not installed`);
+    }
+    throw e;
+  }
+}
+
+export async function isOptionalPeerInstalled(
+  specifier: (typeof OPTIONAL_PEERS)[keyof typeof OPTIONAL_PEERS],
+): Promise<boolean> {
+  try {
+    await importOptionalPeer(specifier);
+    return true;
+  } catch (e) {
+    if (e instanceof DidNotEnable) return false;
+    throw e;
+  }
+}
+
 /**
  * Everything an integration needs to wire itself into the shared pipeline.
  *
@@ -85,11 +140,19 @@ export interface Integration {
    * wrapping framework (e.g. LangChain) does not double-trace the SDK it wraps.
    */
   readonly deactivates?: readonly string[];
+  /**
+   * Optional availability probe for built-in integrations backed by optional
+   * peer packages. Missing peers should return false so their `deactivates`
+   * rules do not affect installed integrations.
+   */
+  isAvailable?(): boolean | Promise<boolean>;
   /**
    * 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);
+  setupOnce(
+    ctx: IntegrationSetupContext,
+  ): void | (() => void) | Promise<void | (() => void)>;
 }

package/src/otel/integrations/claude-agent.ts

@@ -7,15 +7,19 @@
  * `init()` re-exposes as `introspection.instrumentClaudeAgent(sdk)`.
  */
 
-// Presence gate.
-import "@anthropic-ai/claude-agent-sdk";
-
 import { withIntrospection } from "../claude-wrapper.js";
-import type { Integration } from "./base.js";
+import {
+  importOptionalPeer,
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
 
 const integration: Integration = {
   identifier: "claude_agent",
-  setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
+  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.claudeAgent),
+  async setupOnce({ token, serviceName, baseUrl, advanced, handles }) {
+    await importOptionalPeer(OPTIONAL_PEERS.claudeAgent);
     handles.instrumentClaudeAgent = (sdk) =>
       withIntrospection(sdk, {
         token,

package/src/otel/integrations/gemini.ts

@@ -6,14 +6,19 @@
  * capture the standalone `GeminiInstrumentor` is built for.
  */
 
-import * as genai from "@google/genai";
-
 import { GeminiInstrumentor } from "../gemini.js";
-import type { Integration } from "./base.js";
+import {
+  importOptionalPeer,
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
 
 const integration: Integration = {
   identifier: "gemini",
-  setupOnce({ tracerProvider }) {
+  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.gemini),
+  async setupOnce({ tracerProvider }) {
+    const genai = await importOptionalPeer(OPTIONAL_PEERS.gemini);
     const instrumentor = new GeminiInstrumentor();
     instrumentor.instrumentClass({ genai, tracerProvider });
     // Restore the original prototype on shutdown so a later init() re-patches