@introspection-sdk/introspection-node 0.4.7 → 0.4.9

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.7",
+  "version": "0.4.9",
   "license": "Apache-2.0",
   "description": "Introspection observability SDK for Node.js",
   "engines": {
@@ -43,21 +43,21 @@
     "@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",
-    "@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",
+    "@mastra/core": "^1.41.0",
+    "@mastra/observability": "^1.14.1",
+    "@earendil-works/pi-agent-core": "^0.79.0",
+    "@earendil-works/pi-ai": "^0.79.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"
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "peerDependencies": {
     "@openai/agents": ">=0.0.1",
@@ -138,9 +138,9 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "https-proxy-agent": "^7.0.6",
-    "@introspection-sdk/introspection-pi": "0.4.7",
-    "@introspection-sdk/introspection-proxy": "0.4.7",
-    "@introspection-sdk/types": "0.4.7"
+    "@introspection-sdk/types": "0.4.9",
+    "@introspection-sdk/introspection-pi": "0.4.9",
+    "@introspection-sdk/introspection-proxy": "0.4.9"
   },
   "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

package/src/otel/integrations/index.ts

@@ -9,19 +9,19 @@
 import { logger } from "../../utils.js";
 import {
   DidNotEnable,
+  isModuleNotFound,
   type Integration,
   type IntegrationHandles,
   type IntegrationSetupContext,
 } from "./base.js";
 
-export { DidNotEnable };
+export { DidNotEnable, isModuleNotFound };
 export type { Integration, IntegrationHandles, IntegrationSetupContext };
 
 /**
- * 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: ReadonlyArray<
   () => Promise<{ default: Integration }>
@@ -41,26 +41,27 @@ const installed = new Set<string>();
 // prototype patch), run by teardownIntegrations() on shutdown.
 const teardowns: Array<() => void> = [];
 
-/**
- * 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;
+async function availableIntegrations(
+  integrations: Integration[],
+): Promise<Integration[]> {
+  const available: Integration[] = [];
+
+  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(): Promise<Integration[]> {
   const found: Integration[] = [];
@@ -80,7 +81,7 @@ export async function discoverIntegrations(): Promise<Integration[]> {
       }
     }
   }
-  return found;
+  return availableIntegrations(found);
 }
 
 /**
@@ -88,13 +89,13 @@ export async function discoverIntegrations(): Promise<Integration[]> {
  *
  * @returns the set of identifiers installed so far this process.
  */
-export function setupIntegrations(
+export async function setupIntegrations(
   integrations: Integration[],
   ctx: IntegrationSetupContext,
-): Set<string> {
+): Promise<Set<string>> {
   // First-wins de-dupe by identifier.
   const byId = new Map<string, Integration>();
-  for (const integration of integrations) {
+  for (const integration of await availableIntegrations(integrations)) {
     if (!byId.has(integration.identifier)) {
       byId.set(integration.identifier, integration);
     }
@@ -114,7 +115,7 @@ export function setupIntegrations(
     }
     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);
     } catch (e) {

package/src/otel/integrations/langchain.ts

@@ -10,14 +10,25 @@
  * patch would double-trace it.
  */
 
-// Presence gate.
-import "@langchain/core/callbacks/base";
+import {
+  importOptionalPeer,
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
+import type { IntrospectionCallbackHandler } from "../langchain-handler.js";
 
-import { IntrospectionCallbackHandler } from "../langchain-handler.js";
-import type { Integration } from "./base.js";
+const importLocal = (specifier: string) =>
+  import(specifier) as Promise<{
+    IntrospectionCallbackHandler: new (
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      options: any,
+    ) => IntrospectionCallbackHandler;
+  }>;
 
 const integration: 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
@@ -29,7 +40,11 @@ const integration: 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/src/otel/integrations/mastra.ts

@@ -9,12 +9,30 @@
  * is the presence gate: a missing Mastra makes discovery skip this shim.
  */
 
-import { IntrospectionMastraExporter } from "../mastra-exporter.js";
-import type { Integration } from "./base.js";
+import {
+  importOptionalPeer,
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
+
+const importLocal = (specifier: string) =>
+  import(specifier) as Promise<{
+    IntrospectionMastraExporter: new (
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      options: any,
+    ) => unknown;
+  }>;
 
 const integration: 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/src/otel/integrations/openai-agents.ts

@@ -6,14 +6,30 @@
  * other integrations (e.g. a vendor exporter) already registered.
  */
 
-import { addTraceProcessor } from "@openai/agents";
-
 import { IntrospectionTracingProcessor } from "../tracing-processor.js";
-import type { Integration } from "./base.js";
+import {
+  importOptionalPeer,
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
+
+interface OpenAIAgentsModule {
+  addTraceProcessor?: (processor: IntrospectionTracingProcessor) => void;
+}
 
 const integration: Integration = {
   identifier: "openai_agents",
-  setupOnce({ token, serviceName, baseUrl, advanced }) {
+  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.openaiAgents),
+  async setupOnce({ token, serviceName, baseUrl, advanced }) {
+    const { addTraceProcessor } = await importOptionalPeer<OpenAIAgentsModule>(
+      OPTIONAL_PEERS.openaiAgents,
+    );
+    if (!addTraceProcessor) {
+      throw new Error(
+        "Invalid @openai/agents module: addTraceProcessor missing",
+      );
+    }
     addTraceProcessor(
       new IntrospectionTracingProcessor({
         token,

package/src/otel/integrations/pi.ts

@@ -6,15 +6,19 @@
  * publishes it via `introspection.instrumentPi(agent, meta)`.
  */
 
-// Presence gate.
-import "@earendil-works/pi-agent-core";
-
 import { IntrospectionPiInstrumentor } from "../pi.js";
-import type { Integration } from "./base.js";
+import {
+  importOptionalPeer,
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
 
 const integration: 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/src/otel/integrations/vercel.ts

@@ -9,13 +9,15 @@
  * (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 type { Integration } from "./base.js";
+import {
+  isOptionalPeerInstalled,
+  OPTIONAL_PEERS,
+  type Integration,
+} from "./base.js";
 
 const integration: Integration = {
   identifier: "vercel",
+  isAvailable: () => isOptionalPeerInstalled(OPTIONAL_PEERS.vercelAi),
   setupOnce() {
     // No-op: the shared IntrospectionSpanProcessor converts AI SDK spans.
   },