@introspection-sdk/introspection-node 0.20.0 → 0.21.0

package/src/otel/openai.ts

@@ -1,93 +0,0 @@
-/** Privacy-preserving OpenAI embeddings instrumentation. */
-
-import {
-  context,
-  SpanKind,
-  SpanStatusCode,
-  trace,
-  type Span,
-  type Tracer,
-} from "@opentelemetry/api";
-import type {
-  CreateEmbeddingResponse,
-  EmbeddingCreateParams,
-} from "openai/resources/embeddings";
-
-/** The narrow OpenAI client surface required by the embedding wrapper. */
-export interface OpenAIEmbeddingsClient {
-  embeddings: {
-    create(params: EmbeddingCreateParams): Promise<CreateEmbeddingResponse>;
-  };
-}
-
-export interface TracedEmbeddingsOptions {
-  /** GenAI provider name. Defaults to `openai`. */
-  providerName?: string;
-}
-
-function setResponseAttributes(
-  span: Span,
-  response: CreateEmbeddingResponse,
-): void {
-  span.setAttribute("gen_ai.response.model", response.model);
-  span.setAttribute("gen_ai.usage.input_tokens", response.usage.prompt_tokens);
-
-  const firstEmbedding = response.data[0]?.embedding;
-  if (Array.isArray(firstEmbedding)) {
-    span.setAttribute(
-      "gen_ai.embeddings.dimension.count",
-      firstEmbedding.length,
-    );
-  }
-  span.setStatus({ code: SpanStatusCode.OK });
-}
-
-/**
- * Call `client.embeddings.create` and emit a metadata-only GenAI span.
- *
- * Inputs and embedding vectors are deliberately never attached to the span.
- */
-export async function tracedEmbeddingsCreate(
-  tracer: Tracer,
-  client: OpenAIEmbeddingsClient,
-  params: EmbeddingCreateParams,
-  options: TracedEmbeddingsOptions = {},
-): Promise<CreateEmbeddingResponse> {
-  const providerName = options.providerName ?? "openai";
-  const span = tracer.startSpan(`embeddings ${params.model}`, {
-    kind: SpanKind.CLIENT,
-    attributes: {
-      "gen_ai.system": providerName,
-      "gen_ai.provider.name": providerName,
-      "gen_ai.operation.name": "embeddings",
-      "gen_ai.request.model": params.model,
-      "openinference.span.kind": "EMBEDDING",
-      ...(params.dimensions !== undefined
-        ? { "gen_ai.embeddings.dimension.count": params.dimensions }
-        : undefined),
-      ...(params.encoding_format
-        ? { "gen_ai.request.encoding_formats": [params.encoding_format] }
-        : undefined),
-    },
-  });
-
-  try {
-    return await context.with(
-      trace.setSpan(context.active(), span),
-      async () => {
-        const response = await client.embeddings.create(params);
-        setResponseAttributes(span, response);
-        return response;
-      },
-    );
-  } catch (error) {
-    span.setStatus({
-      code: SpanStatusCode.ERROR,
-      message: error instanceof Error ? error.message : String(error),
-    });
-    if (error instanceof Error) span.recordException(error);
-    throw error;
-  } finally {
-    span.end();
-  }
-}

package/src/otel/pi.ts

@@ -1,94 +0,0 @@
-/**
- * High-level pi Agent SDK integration for Introspection.
- *
- * Wraps {@link @introspection-sdk/introspection-pi} behind a zero-config
- * interface so users don't need to manage OpenTelemetry tracers directly.
- *
- * @example
- * ```ts
- * import { IntrospectionPiInstrumentor, setupTracing } from "@introspection-sdk/introspection-node";
- * import { Agent } from "@earendil-works/pi-agent-core";
- *
- * setupTracing({ serviceName: "my-app" });
- * const instrumentor = new IntrospectionPiInstrumentor();
- *
- * const agent = new Agent({ ... });
- * instrumentor.instrument(agent, {
- *   conversationId: "conv-123",
- *   agentId: "weather-agent",
- *   agentName: "Weather",
- * });
- *
- * await agent.prompt("What's the weather in Tokyo?");
- * instrumentor.stop();
- * ```
- */
-
-import { trace } from "@opentelemetry/api";
-import type { Agent, StreamFn } from "@earendil-works/pi-agent-core";
-import {
-  instrumentStream,
-  instrumentAgent,
-  type AgentMeta,
-  type AgentInstrumentation,
-} from "@introspection-sdk/introspection-pi";
-import { VERSION } from "../version.js";
-
-export type { AgentMeta } from "@introspection-sdk/introspection-pi";
-
-export interface IntrospectionPiInstrumentorOptions {
-  /** Tracer name used for all spans produced by this instrumentor. */
-  tracerName?: string;
-}
-
-/**
- * Zero-config pi Agent SDK integration for Introspection.
- *
- * Uses the global OTel tracer provider (registered by {@link setupTracing}).
- * Call {@link instrument} once per {@link Agent} instance, then {@link stop}
- * to unsubscribe all tool instrumentation and finalize open spans.
- */
-export class IntrospectionPiInstrumentor {
-  private _tracer: ReturnType<typeof trace.getTracer>;
-  private _instrumentations: AgentInstrumentation[] = [];
-
-  constructor(opts: IntrospectionPiInstrumentorOptions = {}) {
-    this._tracer = trace.getTracer(
-      opts.tracerName ?? "introspection-pi",
-      VERSION,
-    );
-  }
-
-  /**
-   * Instrument a pi {@link Agent}:
-   * - Wraps the agent stream function to emit a `chat ${provider}` span per
-   *   LLM call.
-   * - Subscribes to the agent loop to emit an `execute_tool ${name}` span per
-   *   tool execution.
-   *
-   * @param agent - The pi Agent instance to instrument.
-   * @param meta  - Identity metadata stamped on every span produced by this agent.
-   */
-  instrument(agent: Agent, meta: AgentMeta): void {
-    const key = "streamFunction" in agent ? "streamFunction" : "streamFn";
-    const instrumentable = agent as unknown as Record<
-      "streamFunction" | "streamFn",
-      StreamFn
-    >;
-    instrumentable[key] = instrumentStream(instrumentable[key], {
-      tracer: this._tracer,
-      meta,
-    });
-    this._instrumentations.push(
-      instrumentAgent(agent, { tracer: this._tracer, meta }),
-    );
-  }
-
-  /**
-   * Unsubscribe all active tool instrumentations and finalize any open spans.
-   */
-  stop(): void {
-    for (const inst of this._instrumentations) inst.stop();
-    this._instrumentations = [];
-  }
-}

package/src/otel/register.ts

@@ -1,50 +0,0 @@
-/**
- * Zero-code preload entry point for Introspection tracing.
- *
- * Usage (ESM):
- *
- * ```bash
- * node --import @introspection-sdk/introspection-node/otel/register app.js
- * ```
- *
- * Runs `introspection.init()` from the environment **before** the app's module
- * graph executes, so no `init()` call is needed in application source. Because
- * the Anthropic / Gemini one-liner works by prototype-patching the SDK classes
- * (see `AnthropicInstrumentor.instrumentClass`), every client constructed after
- * this preload is traced with zero code changes.
- *
- * Configuration is read from the usual environment variables
- * (`INTROSPECTION_TOKEN`, `INTROSPECTION_SERVICE_NAME`,
- * `INTROSPECTION_BASE_OTEL_URL`). If no token is configured the preload logs a
- * warning and does nothing, so it never crashes the host application.
- *
- * This is the counterpart to the private SDK's `register.ts`, adapted to the
- * `src/otel` surface: it drives the existing `init()` rather than registering an
- * import-in-the-middle loader hook (the prototype-patch path does not need one).
- */
-import { logger } from "../utils.js";
-import { init } from "./init.js";
-
-/**
- * Run `init()` if a token is configured. Exported (and awaited at module load)
- * so tests can invoke it deterministically; the module-level `await` below
- * guarantees the preload finishes — including framework auto-discovery and the
- * prototype patch — before Node evaluates the application entry point.
- */
-export async function registerFromEnv(): Promise<void> {
-  if (!process.env.INTROSPECTION_TOKEN) {
-    logger.warn(
-      "[introspection] register: INTROSPECTION_TOKEN not set; tracing not initialised.",
-    );
-    return;
-  }
-  try {
-    await init();
-    logger.debug("[introspection] register: tracing initialised from preload.");
-  } catch (err) {
-    // Never let a preload failure take down the host application.
-    logger.warn(`[introspection] register: init failed: ${String(err)}`);
-  }
-}
-
-await registerFromEnv();

package/src/otel/setup.ts

@@ -1,215 +0,0 @@
-/**
- * One-call tracing bootstrap for Introspection.
- *
- * Wires up the three things every host process needs for baggage-based
- * agent / conversation propagation to work:
- *
- * 1. `AsyncLocalStorageContextManager` — without this, `context.with()` is a
- *    no-op (the default `NOOP_CONTEXT_MANAGER` silently drops the context),
- *    which makes `IntrospectionClient.withAgent()`, `.withConversation()`,
- *    etc. dead code.
- * 2. `W3CBaggagePropagator` — so baggage is carried across HTTP boundaries
- *    via the `baggage` header (alongside W3C trace-context).
- * 3. A registered `NodeTracerProvider` with an `IntrospectionSpanProcessor`
- *    on it — so spans are exported to Introspection and baggage values
- *    (conversation / agent IDs) are merged into span attributes at
- *    `onEnd()` time.
- *
- * Call this once at process start (before any instrumentors run). It is
- * idempotent across re-invocations — the cached provider is returned and
- * the global registrations are not touched a second time.
- *
- * **Loud-by-default registration.** OTel's `setGlobalContextManager` /
- * `setGlobalPropagator` silently refuse to replace an existing
- * registration. If anything (another lib, a stale call, a test fixture)
- * has already installed a context manager that does NOT propagate W3C
- * baggage, our `withAgent` / `withConversation` calls become silent
- * no-ops and users get spans with no identity attached — exactly the
- * footgun this SDK exists to prevent.
- *
- * `setupTracing` defends against that:
- *   - If no manager / propagator is registered: install ours.
- *   - If one is registered: WARN (default) or THROW (strict mode) so the
- *     host author sees it, rather than discovering missing baggage in
- *     production telemetry weeks later.
- *
- * Pass `{ onConflict: "throw" }` (or set `INTROSPECTION_STRICT_TRACING=1`
- * in the env) for the strict variant. Pass `{ onConflict: "replace" }`
- * to force replacement when you know the prior registration is wrong
- * (e.g. test setup, or migrating from another tracer).
- *
- * @example
- * ```ts
- * import { setupTracing, IntrospectionClient } from "@introspection-sdk/introspection-node";
- *
- * setupTracing();
- *
- * const introspect = new IntrospectionClient();
- *
- * await introspect.withAgent("researcher", "researcher-1", () =>
- *   introspect.withConversation(conversationId, undefined, () =>
- *     client.messages.create({ ... }),
- *   ),
- * );
- * ```
- */
-import { context, propagation } from "@opentelemetry/api";
-import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
-import {
-  CompositePropagator,
-  W3CBaggagePropagator,
-  W3CTraceContextPropagator,
-} from "@opentelemetry/core";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
-
-import { logger } from "../utils.js";
-import {
-  IntrospectionSpanProcessor,
-  type IntrospectionSpanProcessorOptions,
-} from "./span-processor.js";
-
-let registeredProvider: NodeTracerProvider | undefined;
-
-export type ConflictBehavior = "warn" | "throw" | "replace";
-
-export interface SetupTracingOptions extends IntrospectionSpanProcessorOptions {
-  /**
-   * What to do if a context manager or propagator is already registered.
-   *
-   *   - `"warn"`  (default) — log a warning and continue with the existing
-   *     registration. Spans still flow but baggage may not propagate as
-   *     expected. Set `INTROSPECTION_STRICT_TRACING=1` to upgrade to throw.
-   *   - `"throw"` — throw an error. Use in environments where a silent
-   *     baggage drop is unacceptable (production telemetry pipelines).
-   *   - `"replace"` — force-register over the existing manager / propagator.
-   *     Useful in tests or when migrating from another tracer; can break
-   *     other libraries that relied on the previous registration.
-   */
-  onConflict?: ConflictBehavior;
-
-  /**
-   * Extra span processors attached to the same `NodeTracerProvider`, so a
-   * single set of spans fans out to other backends (Langfuse, Arize, …).
-   * This is the low-level dual-export hook:
-   *
-   * ```ts
-   * setupTracing({
-   *   serviceName: "my-app",
-   *   additionalSpanProcessors: [new BatchSpanProcessor(langfuseExporter)],
-   * });
-   * ```
-   *
-   * Note: the {@link IntrospectionSpanProcessor} forwards its *own* converted
-   * copy of each span to Introspection — it does not mutate the shared span —
-   * so these processors receive the raw span and run independently of it.
-   * Order is therefore irrelevant. `introspection.init({ spanProcessors })`
-   * is the equivalent for the one-liner surface.
-   */
-  additionalSpanProcessors?: SpanProcessor[];
-}
-
-function defaultConflictBehavior(): ConflictBehavior {
-  return process.env.INTROSPECTION_STRICT_TRACING ? "throw" : "warn";
-}
-
-function registerContextManager(behavior: ConflictBehavior): void {
-  const ok = context.setGlobalContextManager(
-    new AsyncLocalStorageContextManager().enable(),
-  );
-  if (ok) return;
-  // OTel silently refuses replacement — we have to disable+retry to force.
-  const msg =
-    "setupTracing: another OTel context manager was already registered. " +
-    "withAgent / withConversation baggage scopes will not propagate unless " +
-    "that manager is an AsyncLocalStorageContextManager honoring W3C baggage.";
-  if (behavior === "throw") {
-    throw new Error(`[introspection] ${msg}`);
-  }
-  if (behavior === "replace") {
-    context.disable();
-    if (
-      !context.setGlobalContextManager(
-        new AsyncLocalStorageContextManager().enable(),
-      )
-    ) {
-      throw new Error(
-        "[introspection] setupTracing: failed to replace context manager " +
-          "even after disable(); the OTel global registry is in a bad state.",
-      );
-    }
-    return;
-  }
-  logger.warn(msg);
-}
-
-function registerPropagator(behavior: ConflictBehavior): void {
-  const propagator = new CompositePropagator({
-    propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()],
-  });
-  const ok = propagation.setGlobalPropagator(propagator);
-  if (ok) return;
-  const msg =
-    "setupTracing: another OTel propagator was already registered. " +
-    "Cross-process baggage propagation depends on the existing propagator " +
-    "carrying the W3C `baggage` header.";
-  if (behavior === "throw") {
-    throw new Error(`[introspection] ${msg}`);
-  }
-  if (behavior === "replace") {
-    propagation.disable();
-    if (!propagation.setGlobalPropagator(propagator)) {
-      throw new Error(
-        "[introspection] setupTracing: failed to replace propagator even " +
-          "after disable(); the OTel global registry is in a bad state.",
-      );
-    }
-    return;
-  }
-  logger.warn(msg);
-}
-
-/**
- * Install the OTel context manager + W3C (trace-context + baggage) propagator
- * that Introspection's baggage scopes depend on.
- *
- * Shared by {@link setupTracing} and `introspection.init()`. `behavior`
- * controls what happens when a manager / propagator is already registered
- * (see {@link ConflictBehavior}).
- */
-export function registerOTelGlobals(behavior?: ConflictBehavior): void {
-  const resolved = behavior ?? defaultConflictBehavior();
-  registerContextManager(resolved);
-  registerPropagator(resolved);
-}
-
-/**
- * Initialise Introspection tracing for a Node.js process.
- */
-export function setupTracing(
-  options?: SetupTracingOptions,
-): NodeTracerProvider {
-  if (registeredProvider) {
-    return registeredProvider;
-  }
-
-  const behavior: ConflictBehavior =
-    options?.onConflict ?? defaultConflictBehavior();
-
-  registerOTelGlobals(behavior);
-
-  const provider = new NodeTracerProvider({
-    // Order is irrelevant: IntrospectionSpanProcessor exports its own converted
-    // copy and does not mutate the shared span, so co-located dual-export
-    // processors receive the raw span regardless of position. Listed first here
-    // (and in init()) purely for a consistent, readable ordering story.
-    spanProcessors: [
-      new IntrospectionSpanProcessor(options),
-      ...(options?.additionalSpanProcessors ?? []),
-    ],
-  });
-  provider.register();
-
-  registeredProvider = provider;
-  return provider;
-}