@introspection-sdk/introspection-node 0.4.6 → 0.4.8

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.
   },