@introspection-sdk/introspection-node 0.20.0 → 0.21.0

package/dist/otel/openai.d.ts

@@ -1,20 +0,0 @@
-/** Privacy-preserving OpenAI embeddings instrumentation. */
-import { 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;
-}
-/**
- * Call `client.embeddings.create` and emit a metadata-only GenAI span.
- *
- * Inputs and embedding vectors are deliberately never attached to the span.
- */
-export declare function tracedEmbeddingsCreate(tracer: Tracer, client: OpenAIEmbeddingsClient, params: EmbeddingCreateParams, options?: TracedEmbeddingsOptions): Promise<CreateEmbeddingResponse>;
-//# sourceMappingURL=openai.d.ts.map

package/dist/otel/openai.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/otel/openai.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,6BAA6B,CAAC;AAErC,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE;QACV,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;KACzE,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmBD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,sBAAsB,EAC9B,MAAM,EAAE,qBAAqB,EAC7B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,uBAAuB,CAAC,CAsClC"}

package/dist/otel/openai.js

@@ -1,55 +0,0 @@
-/** Privacy-preserving OpenAI embeddings instrumentation. */
-import { context, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
-function setResponseAttributes(span, response) {
-    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, client, params, options = {}) {
-    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();
-    }
-}
-//# sourceMappingURL=openai.js.map

package/dist/otel/openai.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/otel/openai.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAE5D,OAAO,EACL,OAAO,EACP,QAAQ,EACR,cAAc,EACd,KAAK,GAGN,MAAM,oBAAoB,CAAC;AAkB5B,SAAS,qBAAqB,CAC5B,IAAU,EACV,QAAiC;IAEjC,IAAI,CAAC,YAAY,CAAC,uBAAuB,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC3D,IAAI,CAAC,YAAY,CAAC,2BAA2B,EAAE,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAE7E,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;IACnD,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC,YAAY,CACf,mCAAmC,EACnC,cAAc,CAAC,MAAM,CACtB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAc,EACd,MAA8B,EAC9B,MAA6B,EAC7B,UAAmC,EAAE;IAErC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,QAAQ,CAAC;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,MAAM,CAAC,KAAK,EAAE,EAAE;QAC1D,IAAI,EAAE,QAAQ,CAAC,MAAM;QACrB,UAAU,EAAE;YACV,eAAe,EAAE,YAAY;YAC7B,sBAAsB,EAAE,YAAY;YACpC,uBAAuB,EAAE,YAAY;YACrC,sBAAsB,EAAE,MAAM,CAAC,KAAK;YACpC,yBAAyB,EAAE,WAAW;YACtC,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS;gBACjC,CAAC,CAAC,EAAE,mCAAmC,EAAE,MAAM,CAAC,UAAU,EAAE;gBAC5D,CAAC,CAAC,SAAS,CAAC;YACd,GAAG,CAAC,MAAM,CAAC,eAAe;gBACxB,CAAC,CAAC,EAAE,iCAAiC,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE;gBACjE,CAAC,CAAC,SAAS,CAAC;SACf;KACF,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CACvB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,EACrC,KAAK,IAAI,EAAE;YACT,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACxD,qBAAqB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACtC,OAAO,QAAQ,CAAC;QAClB,CAAC,CACF,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,SAAS,CAAC;YACb,IAAI,EAAE,cAAc,CAAC,KAAK;YAC1B,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAChE,CAAC,CAAC;QACH,IAAI,KAAK,YAAY,KAAK;YAAE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QACxD,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,GAAG,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/otel/tracing-processor.d.ts

@@ -1,139 +0,0 @@
-/**
- * OpenAI Agents TracingProcessor for Introspection SDK.
- *
- * Forwards OpenAI agent traces to the backend via OTLP with OTel Gen AI semantic
- * convention attributes.
- */
-import { type SpanExporter, type IdGenerator } from "@opentelemetry/sdk-trace-base";
-import type { TracingProcessor, Trace, Span, SpanData } from "@openai/agents";
-/**
- * Advanced options for testing and customization of
- * {@link IntrospectionTracingProcessor}.
- */
-export interface TracingProcessorAdvancedOptions {
-    /** Custom span exporter (for testing - use InMemorySpanExporter) */
-    spanExporter?: SpanExporter;
-    /** Custom ID generator (for testing - use IncrementalIdGenerator) */
-    idGenerator?: IdGenerator;
-    /** Use SimpleSpanProcessor instead of BatchSpanProcessor (for testing) */
-    useSimpleSpanProcessor?: boolean;
-    /**
-     * Maximum number of spans to export in a single batch.
-     * Set to 1 to export each span individually on end, ensuring sequential
-     * processing by the backend (useful for multi-turn conversations where
-     * each turn must be ingested before the next arrives).
-     * Defaults to the OTel SDK default (512).
-     */
-    maxExportBatchSize?: number;
-    /**
-     * Delay interval in milliseconds between batch exports.
-     * Lower values reduce latency but increase network requests.
-     * Defaults to 1000.
-     */
-    scheduledDelayMillis?: number;
-}
-/** Configuration for {@link IntrospectionTracingProcessor}. */
-export interface IntrospectionTracingProcessorOptions {
-    /** Authentication token (env: INTROSPECTION_TOKEN) */
-    token?: string;
-    /** Base URL for the API (env: INTROSPECTION_BASE_OTEL_URL, default: "https://otel.introspection.dev") */
-    baseUrl?: string;
-    /** Service name for telemetry (env: INTROSPECTION_SERVICE_NAME) */
-    serviceName?: string;
-    /** Additional headers to include in requests */
-    additionalHeaders?: Record<string, string>;
-    /** Advanced options for testing and customization */
-    advanced?: TracingProcessorAdvancedOptions;
-}
-/**
- * {@link TracingProcessor} that forwards OpenAI agent traces to the
- * Introspection backend via OTLP.
- *
- * Extracts OTel Gen AI semantic convention attributes from span data:
- * - Agent spans: `gen_ai.agent.name`, `gen_ai.tool.definitions`, `gen_ai.agent.handoffs`
- * - Function spans: `gen_ai.tool.name`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`
- * - Response spans: `gen_ai.input/output.messages`, `gen_ai.usage.*`, `gen_ai.request.model`
- * - Generation spans: `gen_ai.request.model`, `gen_ai.usage.*`
- * - Handoff spans: `gen_ai.handoff.from_agent`, `gen_ai.handoff.to_agent`
- *
- * @example
- * ```ts
- * import { IntrospectionTracingProcessor } from "@introspection-sdk/introspection-node";
- *
- * const processor = new IntrospectionTracingProcessor({ token: "sk-intro-…" });
- * // pass processor to the OpenAI Agents SDK withTrace() or registerProcessor()
- * ```
- */
-export declare class IntrospectionTracingProcessor implements TracingProcessor {
-    private _tracerProvider;
-    private _tracer;
-    private _spans;
-    private _conversationIds;
-    constructor(options?: IntrospectionTracingProcessorOptions);
-    /**
-     * Called when the processor is started. Optional lifecycle hook.
-     */
-    start(): void;
-    /**
-     * Called when a trace starts. Creates a root OTel span.
-     *
-     * @param trace - The OpenAI Agents SDK trace object.
-     */
-    onTraceStart(trace: Trace): Promise<void>;
-    /**
-     * Called when a trace ends. Closes the root OTel span.
-     *
-     * @param trace - The OpenAI Agents SDK trace object.
-     */
-    onTraceEnd(trace: Trace): Promise<void>;
-    /**
-     * Called when a span starts. Creates a child OTel span with parent context.
-     *
-     * @param span - The OpenAI Agents SDK span.
-     */
-    onSpanStart(span: Span<SpanData>): Promise<void>;
-    /**
-     * Called when a span ends. Extracts `gen_ai.*` attributes from the span
-     * data and sets them on the corresponding OTel span before ending it.
-     *
-     * @param span - The OpenAI Agents SDK span.
-     */
-    onSpanEnd(span: Span<SpanData>): Promise<void>;
-    /**
-     * Extract attributes from agent spans.
-     */
-    private _processAgentSpan;
-    /**
-     * Extract attributes from function/tool spans.
-     */
-    private _processFunctionSpan;
-    /**
-     * Extract attributes from response spans.
-     * Matches Python implementation - extracts from both spanData and _response object.
-     */
-    private _processResponseSpan;
-    /**
-     * Extract attributes from generation spans.
-     * Handles both structured GenerationUsageData (spanData.usage) and raw
-     * Chat Completions API responses stored in spanData.output[0] by
-     * OpenAIChatCompletionsModel.
-     */
-    private _processGenerationSpan;
-    /**
-     * Extract attributes from handoff spans.
-     */
-    private _processHandoffSpan;
-    /**
-     * Shut down the tracer provider, flushing all pending spans.
-     *
-     * @returns A promise that resolves once shutdown is complete.
-     */
-    shutdown(): Promise<void>;
-    /**
-     * Force-flush any buffered spans to the Introspection backend.
-     *
-     * @returns A promise that resolves once the flush completes.
-     */
-    forceFlush(): Promise<void>;
-}
-//# sourceMappingURL=tracing-processor.d.ts.map

package/dist/otel/tracing-processor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracing-processor.d.ts","sourceRoot":"","sources":["../../src/otel/tracing-processor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAsBvC,OAAO,KAAK,EACV,gBAAgB,EAChB,KAAK,EACL,IAAI,EACJ,QAAQ,EAMT,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,oEAAoE;IACpE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,oCAAoC;IACnD,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yGAAyG;IACzG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,EAAE,+BAA+B,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,6BAA8B,YAAW,gBAAgB;IACpE,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,OAAO,CAA+C;IAC9D,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,gBAAgB,CAAkC;gBAE9C,OAAO,GAAE,oCAAyC;IA2F9D;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/C;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAa7C;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BtD;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCpD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAoG5B;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IA2G9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/otel/tracing-processor.js

@@ -1,434 +0,0 @@
-/**
- * OpenAI Agents TracingProcessor for Introspection SDK.
- *
- * Forwards OpenAI agent traces to the backend via OTLP with OTel Gen AI semantic
- * convention attributes.
- */
-import { context as otelContext, trace as otelTrace, } from "@opentelemetry/api";
-import { BasicTracerProvider, BatchSpanProcessor, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { randomUUID } from "crypto";
-import { convertResponsesInputsToSemconv, convertResponsesOutputsToSemconv, convertResponsesToolsToSemconv, convertResponsesInstructionsToSemconv, } from "../converters/openai.js";
-import { providerCostAttributes } from "@introspection-sdk/types";
-import { logger, withOtlpHttpsProxy } from "../utils.js";
-import { VERSION } from "../version.js";
-/**
- * {@link TracingProcessor} that forwards OpenAI agent traces to the
- * Introspection backend via OTLP.
- *
- * Extracts OTel Gen AI semantic convention attributes from span data:
- * - Agent spans: `gen_ai.agent.name`, `gen_ai.tool.definitions`, `gen_ai.agent.handoffs`
- * - Function spans: `gen_ai.tool.name`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`
- * - Response spans: `gen_ai.input/output.messages`, `gen_ai.usage.*`, `gen_ai.request.model`
- * - Generation spans: `gen_ai.request.model`, `gen_ai.usage.*`
- * - Handoff spans: `gen_ai.handoff.from_agent`, `gen_ai.handoff.to_agent`
- *
- * @example
- * ```ts
- * import { IntrospectionTracingProcessor } from "@introspection-sdk/introspection-node";
- *
- * const processor = new IntrospectionTracingProcessor({ token: "sk-intro-…" });
- * // pass processor to the OpenAI Agents SDK withTrace() or registerProcessor()
- * ```
- */
-export class IntrospectionTracingProcessor {
-    _tracerProvider;
-    _tracer;
-    _spans = new Map();
-    _conversationIds = new Map();
-    constructor(options = {}) {
-        const advanced = options.advanced;
-        const serviceName = options.serviceName || process.env.INTROSPECTION_SERVICE_NAME;
-        const resource = serviceName
-            ? resourceFromAttributes({ [ATTR_SERVICE_NAME]: serviceName })
-            : undefined;
-        // If custom exporter is provided (testing mode), skip token validation
-        if (!advanced?.spanExporter) {
-            const token = options.token || process.env.INTROSPECTION_TOKEN;
-            if (!token) {
-                throw new Error("INTROSPECTION_TOKEN is required");
-            }
-            const baseUrl = options.baseUrl ||
-                process.env.INTROSPECTION_BASE_OTEL_URL ||
-                "https://otel.introspection.dev";
-            const headers = {
-                "User-Agent": `introspection-sdk/${VERSION}`,
-                Authorization: `Bearer ${token}`,
-                ...options.additionalHeaders,
-            };
-            // Construct endpoint URL
-            const endpoint = baseUrl.endsWith("/v1/traces")
-                ? baseUrl
-                : `${baseUrl.replace(/\/$/, "")}/v1/traces`;
-            logger.info(`IntrospectionTracingProcessor initialized: endpoint=${endpoint}`);
-            // Setup OTLP exporter
-            const spanExporter = new OTLPTraceExporter(withOtlpHttpsProxy({
-                url: endpoint,
-                headers,
-            }));
-            // Use SimpleSpanProcessor for maxExportBatchSize=1 (sequential export),
-            // otherwise BatchSpanProcessor with configurable batch size.
-            // Default to sequential export for dev/staging tokens.
-            const effectiveBatchSize = advanced?.maxExportBatchSize ??
-                (token.startsWith("intro_dev") || token.startsWith("intro_staging")
-                    ? 1
-                    : undefined);
-            const useSimple = advanced?.useSimpleSpanProcessor || effectiveBatchSize === 1;
-            const scheduledDelayMillis = advanced?.scheduledDelayMillis ?? 1000;
-            const spanProcessor = useSimple
-                ? new SimpleSpanProcessor(spanExporter)
-                : new BatchSpanProcessor(spanExporter, {
-                    scheduledDelayMillis,
-                    ...(effectiveBatchSize
-                        ? { maxExportBatchSize: effectiveBatchSize }
-                        : {}),
-                });
-            this._tracerProvider = new BasicTracerProvider({
-                resource,
-                idGenerator: advanced?.idGenerator,
-                spanProcessors: [spanProcessor],
-            });
-        }
-        else {
-            // Testing mode: use provided exporter
-            logger.info(`IntrospectionTracingProcessor initialized in test mode with custom exporter`);
-            // Choose span processor based on options
-            const spanProcessor = advanced.useSimpleSpanProcessor
-                ? new SimpleSpanProcessor(advanced.spanExporter)
-                : new BatchSpanProcessor(advanced.spanExporter, {
-                    scheduledDelayMillis: 100,
-                });
-            this._tracerProvider = new BasicTracerProvider({
-                resource,
-                idGenerator: advanced.idGenerator,
-                spanProcessors: [spanProcessor],
-            });
-        }
-        this._tracer = this._tracerProvider.getTracer("openai-agents", VERSION);
-    }
-    /**
-     * Called when the processor is started. Optional lifecycle hook.
-     */
-    start() {
-        // No-op - processor is ready after construction
-    }
-    /**
-     * Called when a trace starts. Creates a root OTel span.
-     *
-     * @param trace - The OpenAI Agents SDK trace object.
-     */
-    async onTraceStart(trace) {
-        logger.debug(`onTraceStart called: ${trace?.name} (${trace?.traceId})`);
-        if (trace) {
-            // Use groupId as conversationId when provided so callers can link
-            // multiple traces (e.g. multi-turn orchestrator runs) into one conversation.
-            const conversationId = trace.groupId ?? `intro_conv_${randomUUID().replace(/-/g, "")}`;
-            this._conversationIds.set(trace.traceId, conversationId);
-            const otelSpan = this._tracer.startSpan(trace.name);
-            this._spans.set(trace.traceId, otelSpan);
-            logger.debug(`Created root span for trace: ${trace.traceId}`);
-        }
-    }
-    /**
-     * Called when a trace ends. Closes the root OTel span.
-     *
-     * @param trace - The OpenAI Agents SDK trace object.
-     */
-    async onTraceEnd(trace) {
-        logger.debug(`onTraceEnd called: ${trace?.name} (${trace?.traceId})`);
-        if (trace) {
-            const otelSpan = this._spans.get(trace.traceId);
-            if (otelSpan) {
-                this._spans.delete(trace.traceId);
-                this._conversationIds.delete(trace.traceId);
-                otelSpan.end();
-                logger.debug(`Ended root span for trace: ${trace.traceId}`);
-            }
-        }
-    }
-    /**
-     * Called when a span starts. Creates a child OTel span with parent context.
-     *
-     * @param span - The OpenAI Agents SDK span.
-     */
-    async onSpanStart(span) {
-        logger.debug(`onSpanStart called: ${span?.spanId} (type: ${span?.spanData?.type})`);
-        if (span) {
-            const parentId = span.parentId || span.traceId;
-            const parent = this._spans.get(parentId);
-            const ctx = parent
-                ? otelTrace.setSpan(otelContext.active(), parent)
-                : undefined;
-            const spanData = span.spanData;
-            let name;
-            // Use name for agent and function spans, type for others
-            if (spanData.type === "agent") {
-                name = spanData.name;
-            }
-            else if (spanData.type === "function") {
-                name = spanData.name;
-            }
-            else {
-                name = spanData.type;
-            }
-            const otelSpan = this._tracer.startSpan(name, {}, ctx);
-            this._spans.set(span.spanId, otelSpan);
-        }
-    }
-    /**
-     * Called when a span ends. Extracts `gen_ai.*` attributes from the span
-     * data and sets them on the corresponding OTel span before ending it.
-     *
-     * @param span - The OpenAI Agents SDK span.
-     */
-    async onSpanEnd(span) {
-        if (!span)
-            return;
-        const otelSpan = this._spans.get(span.spanId);
-        if (!otelSpan) {
-            return;
-        }
-        this._spans.delete(span.spanId);
-        const spanData = span.spanData;
-        // Extract gen_ai.* attributes based on span type
-        switch (spanData.type) {
-            case "agent":
-                this._processAgentSpan(otelSpan, spanData);
-                break;
-            case "function":
-                this._processFunctionSpan(otelSpan, spanData);
-                break;
-            case "response":
-                this._processResponseSpan(otelSpan, spanData);
-                break;
-            case "generation":
-                this._processGenerationSpan(otelSpan, spanData);
-                break;
-            case "handoff":
-                this._processHandoffSpan(otelSpan, spanData);
-                break;
-        }
-        // Propagate conversation ID from trace
-        const conversationId = this._conversationIds.get(span.traceId);
-        if (conversationId) {
-            otelSpan.setAttribute("gen_ai.conversation.id", conversationId);
-        }
-        // Keep raw span data for debugging (matches Python attribute name)
-        otelSpan.setAttribute("openai_agents.span_data", JSON.stringify(spanData));
-        otelSpan.end();
-    }
-    /**
-     * Extract attributes from agent spans.
-     */
-    _processAgentSpan(otelSpan, spanData) {
-        otelSpan.setAttribute("gen_ai.agent.name", spanData.name);
-        otelSpan.setAttribute("gen_ai.provider.name", "openai");
-        otelSpan.setAttribute("openinference.span.kind", "AGENT");
-        if (spanData.tools) {
-            // Wrap tool names as objects for ClickHouse Array(JSON) compatibility
-            const toolDefs = spanData.tools.map((t) => ({
-                type: "function",
-                name: t,
-            }));
-            otelSpan.setAttribute("gen_ai.tool.definitions", JSON.stringify(toolDefs));
-        }
-        if (spanData.handoffs) {
-            otelSpan.setAttribute("gen_ai.agent.handoffs", JSON.stringify(spanData.handoffs));
-        }
-        if (spanData.output_type) {
-            otelSpan.setAttribute("gen_ai.agent.output_type", spanData.output_type);
-        }
-    }
-    /**
-     * Extract attributes from function/tool spans.
-     */
-    _processFunctionSpan(otelSpan, spanData) {
-        otelSpan.updateName(`execute_tool ${spanData.name}`);
-        otelSpan.setAttribute("gen_ai.operation.name", "execute_tool");
-        otelSpan.setAttribute("gen_ai.tool.name", spanData.name);
-        otelSpan.setAttribute("gen_ai.tool.type", "function");
-        otelSpan.setAttribute("openinference.span.kind", "TOOL");
-        if (spanData.input) {
-            otelSpan.setAttribute("gen_ai.tool.call.arguments", spanData.input);
-        }
-        if (spanData.output) {
-            otelSpan.setAttribute("gen_ai.tool.call.result", String(spanData.output));
-        }
-    }
-    /**
-     * Extract attributes from response spans.
-     * Matches Python implementation - extracts from both spanData and _response object.
-     */
-    _processResponseSpan(otelSpan, spanData) {
-        otelSpan.setAttribute("gen_ai.operation.name", "chat");
-        otelSpan.setAttribute("gen_ai.provider.name", "openai");
-        otelSpan.setAttribute("openinference.span.kind", "LLM");
-        // Response ID (from span_data directly)
-        if (spanData.response_id) {
-            otelSpan.setAttribute("gen_ai.response.id", spanData.response_id);
-        }
-        // Input messages (from spanData._input)
-        if (spanData._input) {
-            const inputs = Array.isArray(spanData._input)
-                ? spanData._input
-                : [spanData._input];
-            const [inputMessages] = convertResponsesInputsToSemconv(inputs, undefined);
-            if (inputMessages.length > 0) {
-                otelSpan.setAttribute("gen_ai.input.messages", JSON.stringify(inputMessages));
-            }
-        }
-        // Extract from _response if available (full Response object)
-        const response = spanData._response;
-        if (!response)
-            return;
-        // System instructions
-        const sysInstructions = convertResponsesInstructionsToSemconv(response.instructions);
-        if (sysInstructions) {
-            otelSpan.setAttribute("gen_ai.system_instructions", JSON.stringify(sysInstructions));
-        }
-        // Tool definitions (with full details from Response object)
-        if (response.tools && response.tools.length > 0) {
-            const toolDefs = convertResponsesToolsToSemconv(response.tools);
-            otelSpan.setAttribute("gen_ai.tool.definitions", JSON.stringify(toolDefs));
-        }
-        // Token usage
-        const usage = response.usage;
-        if (usage) {
-            if (usage.input_tokens) {
-                otelSpan.setAttribute("gen_ai.usage.input_tokens", usage.input_tokens);
-            }
-            if (usage.output_tokens) {
-                otelSpan.setAttribute("gen_ai.usage.output_tokens", usage.output_tokens);
-            }
-            // OpenAI returns cached token count in input_tokens_details.cached_tokens
-            const cachedTokens = usage.input_tokens_details?.cached_tokens;
-            if (cachedTokens) {
-                otelSpan.setAttribute("gen_ai.usage.cache_read.input_tokens", cachedTokens);
-            }
-            // Provider-reported cost (e.g. OpenRouter usage.cost) when present.
-            otelSpan.setAttributes(providerCostAttributes(usage));
-        }
-        // Model info
-        if (response.model) {
-            otelSpan.setAttribute("gen_ai.request.model", response.model);
-        }
-        // Response ID from response object (fallback if not in span_data)
-        if (!spanData.response_id && response.id) {
-            otelSpan.setAttribute("gen_ai.response.id", response.id);
-        }
-        // Output messages (from response.output)
-        if (response.output && response.output.length > 0) {
-            const outputMessages = convertResponsesOutputsToSemconv(response.output);
-            if (outputMessages.length > 0) {
-                otelSpan.setAttribute("gen_ai.output.messages", JSON.stringify(outputMessages));
-            }
-        }
-    }
-    /**
-     * Extract attributes from generation spans.
-     * Handles both structured GenerationUsageData (spanData.usage) and raw
-     * Chat Completions API responses stored in spanData.output[0] by
-     * OpenAIChatCompletionsModel.
-     */
-    _processGenerationSpan(otelSpan, spanData) {
-        otelSpan.setAttribute("gen_ai.operation.name", "chat");
-        otelSpan.setAttribute("gen_ai.provider.name", "openai");
-        otelSpan.setAttribute("openinference.span.kind", "LLM");
-        if (spanData.model) {
-            otelSpan.setAttribute("gen_ai.request.model", spanData.model);
-        }
-        // GenerationUsageData uses snake_case: input_tokens / output_tokens.
-        if (spanData.usage?.input_tokens) {
-            otelSpan.setAttribute("gen_ai.usage.input_tokens", spanData.usage.input_tokens);
-        }
-        if (spanData.usage?.output_tokens) {
-            otelSpan.setAttribute("gen_ai.usage.output_tokens", spanData.usage.output_tokens);
-        }
-        if (spanData.usage) {
-            // Provider-reported cost (e.g. OpenRouter usage.cost) when present.
-            otelSpan.setAttributes(providerCostAttributes(spanData.usage));
-        }
-        // OpenAIChatCompletionsModel stores the raw ChatCompletion response object
-        // in spanData.output[0] (it never sets spanData.usage). Extract usage,
-        // response ID, response model, and the actual assistant message from it.
-        if (!spanData.usage) {
-            const rawResponse = spanData.output?.[0];
-            // Response ID — required by the backend processor to register this span
-            // as a conversation item (build_request returns None without it).
-            const responseId = rawResponse?.id;
-            if (typeof responseId === "string" && responseId) {
-                otelSpan.setAttribute("gen_ai.response.id", responseId);
-            }
-            // Resolved model name (e.g. "gpt-4o-mini-2024-07-18" vs "gpt-4o-mini").
-            const responseModel = rawResponse?.model;
-            if (typeof responseModel === "string" && responseModel) {
-                otelSpan.setAttribute("gen_ai.response.model", responseModel);
-            }
-            const rawUsage = rawResponse?.usage;
-            if (rawUsage) {
-                const promptTokens = rawUsage.prompt_tokens;
-                const completionTokens = rawUsage.completion_tokens;
-                if (typeof promptTokens === "number") {
-                    otelSpan.setAttribute("gen_ai.usage.input_tokens", promptTokens);
-                }
-                if (typeof completionTokens === "number") {
-                    otelSpan.setAttribute("gen_ai.usage.output_tokens", completionTokens);
-                }
-                const promptDetails = rawUsage.prompt_tokens_details;
-                const cachedTokens = promptDetails?.cached_tokens;
-                if (typeof cachedTokens === "number" && cachedTokens > 0) {
-                    otelSpan.setAttribute("gen_ai.usage.cache_read.input_tokens", cachedTokens);
-                }
-                // OpenRouter-style gateways report the charged price and reasoning
-                // token split inside the Chat Completions usage block.
-                otelSpan.setAttributes(providerCostAttributes(rawUsage));
-            }
-            // Extract the actual assistant message from choices[0].message so that
-            // gen_ai.output.messages is a proper [{role, content}] array rather than
-            // the full ChatCompletion envelope (which the backend cannot parse).
-            const choices = rawResponse?.choices;
-            const assistantMessage = choices?.[0]?.message;
-            if (assistantMessage) {
-                otelSpan.setAttribute("gen_ai.output.messages", JSON.stringify([assistantMessage]));
-            }
-        }
-        if (spanData.input) {
-            otelSpan.setAttribute("gen_ai.input.messages", JSON.stringify(spanData.input));
-        }
-        // For non-Chat-Completions generation spans that do have usage set,
-        // still export output messages in the standard format if present.
-        if (spanData.usage && spanData.output) {
-            otelSpan.setAttribute("gen_ai.output.messages", JSON.stringify(spanData.output));
-        }
-    }
-    /**
-     * Extract attributes from handoff spans.
-     */
-    _processHandoffSpan(otelSpan, spanData) {
-        if (spanData.from_agent) {
-            otelSpan.setAttribute("gen_ai.handoff.from_agent", spanData.from_agent);
-        }
-        if (spanData.to_agent) {
-            otelSpan.setAttribute("gen_ai.handoff.to_agent", spanData.to_agent);
-        }
-    }
-    /**
-     * Shut down the tracer provider, flushing all pending spans.
-     *
-     * @returns A promise that resolves once shutdown is complete.
-     */
-    async shutdown() {
-        await this._tracerProvider.shutdown();
-    }
-    /**
-     * Force-flush any buffered spans to the Introspection backend.
-     *
-     * @returns A promise that resolves once the flush completes.
-     */
-    async forceFlush() {
-        await this._tracerProvider.forceFlush();
-    }
-}
-//# sourceMappingURL=tracing-processor.js.map