@struct-ai/sdk 0.3.17 → 0.4.3

package/dist/esm/context.js

@@ -94,4 +94,60 @@ export function runWithStore(store, fn) {
 export function runInFreshContext(fn) {
     return als.run({}, fn);
 }
+/**
+ * Write-once `gen_ai.provider.name` on an invoke_agent span.
+ *
+ * The GenAI spec puts `gen_ai.provider.name` on invoke_agent spans, but the
+ * layer that CREATES those spans (`struct.agent()`, the LangChain handler) is
+ * provider-agnostic and can't know the value yet — only the child inference
+ * call can. The first chat call within the agent scope stamps it (best
+ * knowledge; first one wins); an agent that never reaches a model omits the
+ * attribute rather than carrying a framework name. Parity: python
+ * `_genai_content.stamp_provider_once`.
+ */
+const PROVIDER_STAMPED = Symbol("struct.providerStamped");
+/**
+ * Write-once `gen_ai.provider.name` on an invoke_agent span.
+ *
+ * CONTRACT: `agentSpan` is always an SDK-OWNED span — created by our own
+ * tracer in `struct.agent()` or the LangChain handler and delivered via the
+ * ALS store / run map, which nothing else writes. Never a host object. So
+ * the industry-standard owned-object pattern applies (state lives ON the
+ * object — Sentry/dd-trace private span fields, OTel JS symbol markers): a
+ * private Symbol sentinel set after a successful write. No registries or
+ * lifecycle bookkeeping — those are for FOREIGN objects.
+ *
+ * Semantics: "a real child provider" — racing children with different
+ * providers may pick either; the sentinel is set only after a successful
+ * write so a transient failure can be retried. Parity: python
+ * `stamp_provider_once`.
+ */
+export function stampProviderOnce(agentSpan, provider) {
+    try {
+        if (!agentSpan || !provider)
+            return;
+        const marked = agentSpan;
+        if (marked[PROVIDER_STAMPED])
+            return;
+        agentSpan.setAttribute("gen_ai.provider.name", provider);
+        try {
+            marked[PROVIDER_STAMPED] = true;
+        }
+        catch {
+            /* frozen span — worst case a later child re-stamps a real provider */
+        }
+    }
+    catch {
+        /* never fail the application for telemetry */
+    }
+}
+/** Stamp the ambient agent span with the child call's provider (write-once). */
+export function propagateProviderToParent(provider) {
+    try {
+        stampProviderOnce(getAgentSpan(), provider);
+    }
+    catch {
+        /* never fail the application for telemetry */
+    }
+}
 //# sourceMappingURL=context.js.map

package/dist/esm/core.js

@@ -84,12 +84,22 @@ export function safe(fn, site, logger) {
         fn();
     }
     catch (err) {
-        if (firstFailureLogged.has(site)) {
-            logger.debug(`Struct SDK suppressed exception at ${site}`, err);
+        // The diagnostic log MUST NOT itself throw into the host: the default
+        // logger reaches `console.warn`, which a host may have replaced with a
+        // throwing implementation, and callers pass custom loggers. A throw here
+        // would escape `safe()` and defeat its whole purpose (e.g. block the host
+        // call when span creation fails). Guard the logging too.
+        try {
+            if (firstFailureLogged.has(site)) {
+                logger.debug(`Struct SDK suppressed exception at ${site}`, err);
+            }
+            else {
+                firstFailureLogged.add(site);
+                logger.warn(`Struct SDK suppressed exception at ${site}`, err);
+            }
         }
-        else {
-            firstFailureLogged.add(site);
-            logger.warn(`Struct SDK suppressed exception at ${site}`, err);
+        catch {
+            /* diagnostic logging failed — never propagate into the host path */
         }
     }
 }
@@ -380,7 +390,10 @@ export class StructSDK {
         const startedSpan = span;
         safe(() => {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "invoke_agent");
-            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "struct");
+            // gen_ai.provider.name is NOT set here: this layer is
+            // provider-agnostic, and a framework name ("struct") isn't a
+            // provider. The first child inference call stamps the real one via
+            // propagateProviderToParent (write-once, best knowledge).
             startedSpan.setAttribute(GEN_AI.AGENT_NAME, agentName);
             // gen_ai.agent.id is the stable identifier of the agent
             // DEFINITION. Only set it when the caller provides one — we do
@@ -475,7 +488,8 @@ export class StructSDK {
         const startedSpan = span;
         safe(() => {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "execute_tool");
-            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "struct");
+            // No gen_ai.provider.name: the spec's execute_tool span does not
+            // define that attribute.
             startedSpan.setAttribute(GEN_AI.TOOL_NAME, toolName);
             if (toolCallId) {
                 startedSpan.setAttribute(GEN_AI.TOOL_CALL_ID, toolCallId);
@@ -491,7 +505,28 @@ export class StructSDK {
             if (this.captureContent && result !== undefined && result !== null) {
                 safe(() => startedSpan.setAttribute(GEN_AI.TOOL_CALL_RESULT, safeJsonStringify(result).slice(0, 8192)), "tool.set_result_attr", this._internalLogger);
             }
-            safe(() => startedSpan.setStatus({ code: SpanStatusCode.OK }), "tool.set_ok_status", this._internalLogger);
+            if (toolResultSignalsError(result)) {
+                safe(() => {
+                    startedSpan.setAttribute(ERROR_TYPE, "tool_error");
+                    // The status message is content placed on a SPAN — it follows
+                    // the span-content routing gate (emitSpanContent), not merely
+                    // "any capture on": under EventOnly (the default) content
+                    // routes to log events, so span text gets the fixed literal.
+                    // Deliberate boundary: gen_ai.tool.call.result above stays on
+                    // captureContent — tool spans have no log-event equivalent for
+                    // results, so the attribute is the sanctioned tool-content
+                    // channel in every non-None mode. Mirrors python _note_result.
+                    startedSpan.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: this.emitSpanContent
+                            ? toolErrorStatusMessage(result)
+                            : "tool returned is_error=true",
+                    });
+                }, "tool.set_tool_error_status", this._internalLogger);
+            }
+            else {
+                safe(() => startedSpan.setStatus({ code: SpanStatusCode.OK }), "tool.set_ok_status", this._internalLogger);
+            }
             return result;
         }
         catch (err) {
@@ -512,4 +547,65 @@ function recordError(span, err) {
         span.recordException(err);
     }
 }
+/**
+ * Read one property from untrusted host data, isolating the read in its
+ * own try — a hostile getter/Proxy trap on ONE key must never throw into
+ * tool()'s try block (rejecting the host's successful call) nor mask a
+ * readable value on a SIBLING key (callers probe each supported alias
+ * independently). Mirrors python `_safe_probe` — keep in lockstep.
+ */
+function safeProbe(obj, key) {
+    if (typeof obj !== "object" || obj === null)
+        return undefined;
+    try {
+        return obj[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a tool's RETURN VALUE signals in-band failure (MCP
+ * CallToolResult.isError / Anthropic tool_result.is_error). Strictly
+ * boolean `true` on the top-level object — truthy strings/numbers and
+ * nested flags do not trigger (host data is untrusted; be conservative).
+ * Each alias is probed independently so a hostile getter on one cannot
+ * mask the other. Mirrors python `_tool_result_signals_error`.
+ */
+function toolResultSignalsError(result) {
+    return (safeProbe(result, "isError") === true ||
+        safeProbe(result, "is_error") === true);
+}
+/** Short status message from an error result's content, else a fixed one.
+ *
+ * TOTAL FUNCTION: never throws and does bounded work. It runs inside the
+ * safe() closure that also sets span status — a hostile Proxy whose
+ * `length`/index traps throw must not abort that closure (which would
+ * leave the span UNSET instead of ERROR). Two layers: per-key safeProbe
+ * isolation (one hostile item cannot mask a later readable one) INSIDE a
+ * whole-body catch (collection machinery itself is untrusted), index
+ * loop instead of for..of (iterator protocol is trappable), traversal
+ * capped at 20 items. Mirrors python `_tool_error_status_message`. */
+function toolErrorStatusMessage(result) {
+    try {
+        const content = safeProbe(result, "content");
+        if (typeof content === "string" && content)
+            return content.slice(0, 256);
+        if (Array.isArray(content)) {
+            const len = Math.min(content.length, 20);
+            for (let i = 0; i < len; i++) {
+                const item = safeProbe(content, String(i));
+                const text = safeProbe(item, "text");
+                // Truthiness (not just typeof) matches the python twin: empty-string
+                // text items are skipped, falling through to the fixed message.
+                if (typeof text === "string" && text)
+                    return text.slice(0, 256);
+            }
+        }
+    }
+    catch {
+        // Hostile collection — fall through to the fixed message.
+    }
+    return "tool returned is_error=true";
+}
 //# sourceMappingURL=core.js.map

package/dist/esm/events.d.ts

@@ -1,12 +1,23 @@
-import { type Logger } from "@opentelemetry/api-logs";
+import type { Logger } from "@opentelemetry/api-logs";
+import type { Span } from "@opentelemetry/api";
 /**
  * Emit per-message log events for an Anthropic messages.create() call.
- * Port of _emit_message_events from anthropic.py.
+ * Delegates the LogRecord wiring to the shared genai-content emitters; this
+ * function is only the Anthropic message → parts mapping + ordering.
  */
-export declare function emitAnthropicMessageEvents(logger: Logger, messages: unknown, system: unknown): void;
+export declare function emitAnthropicMessageEvents(logger: Logger, messages: unknown, system: unknown, span?: Span, provider?: string): void;
+/** Emit a gen_ai.choice LogRecord for an Anthropic response. */
+export declare function emitAnthropicChoiceEvent(logger: Logger, contentBlocks: unknown, stopReason: string | null | undefined, span?: Span, provider?: string): void;
 /**
- * Emit a gen_ai.choice LogRecord for an Anthropic response.
- * Port of _emit_choice_event from anthropic.py.
+ * Emit per-message log events for an OpenAI responses.create() call.
+ * `instructions` (the Responses system prompt) is emitted FIRST at index 0.
+ * Delegates LogRecord wiring to the shared emitters; only the Responses
+ * item → event mapping + ordering lives here.
  */
-export declare function emitAnthropicChoiceEvent(logger: Logger, contentBlocks: unknown, stopReason: string | null | undefined): void;
+export declare function emitOpenAIInputMessageEvents(logger: Logger, input: unknown, instructions: unknown, span?: Span, provider?: string): void;
+/**
+ * Emit the gen_ai.choice LogRecord from an OpenAI response.output.
+ * `finishReason` is mapped inside this emitter using mapChoiceFinishReason.
+ */
+export declare function emitOpenAIChoiceEvent(logger: Logger, output: unknown, finishReason: string | undefined, span?: Span, provider?: string): void;
 //# sourceMappingURL=events.d.ts.map

package/dist/esm/events.js

@@ -1,37 +1,13 @@
-import { context as otelContext } from "@opentelemetry/api";
-import { SeverityNumber, } from "@opentelemetry/api-logs";
-import { getSessionId } from "./context.js";
-import { ANTHROPIC_FINISH_REASON_MAP, EVENT_NAME, EVENT_NAMES, GEN_AI, ROLE_TO_EVENT_NAME, } from "./semconv.js";
-import { safeJsonStringify, truncateParts } from "./truncation.js";
-import { contentToParts, } from "./integrations/anthropic-content.js";
-/**
- * Emit a LogRecord with the active span context linked.
- *
- * Follows the OTel logs data model convention:
- * - `body` (log record body) = event tag string (human-readable signal)
- * - `attributes.body` (log record attribute) = JSON-serialised payload
- */
-function emitLogRecord({ logger, eventName, payload, extraAttrs = {}, }) {
-    const sessionId = getSessionId();
-    const attributes = {
-        [EVENT_NAME]: eventName,
-        body: payload,
-        ...extraAttrs,
-    };
-    if (sessionId)
-        attributes[GEN_AI.CONVERSATION_ID] = sessionId;
-    logger.emit({
-        body: eventName,
-        severityNumber: SeverityNumber.INFO,
-        attributes,
-        context: otelContext.active(),
-    });
-}
+import { emitChoiceEvent, emitMessageEvent, } from "./genai-content.js";
+import { ANTHROPIC_FINISH_REASON_MAP, EVENT_NAMES, ROLE_TO_EVENT_NAME, } from "./semconv.js";
+import { contentToParts } from "./integrations/anthropic-content.js";
+import { inputItemToEvent, mapChoiceFinishReason, normalizeInput, outputItemToChoiceParts, } from "./integrations/openai-content.js";
 /**
  * Emit per-message log events for an Anthropic messages.create() call.
- * Port of _emit_message_events from anthropic.py.
+ * Delegates the LogRecord wiring to the shared genai-content emitters; this
+ * function is only the Anthropic message → parts mapping + ordering.
  */
-export function emitAnthropicMessageEvents(logger, messages, system) {
+export function emitAnthropicMessageEvents(logger, messages, system, span, provider = "anthropic") {
     if (!Array.isArray(messages))
         return;
     let msgIndex = 0;
@@ -41,17 +17,14 @@ export function emitAnthropicMessageEvents(logger, messages, system) {
             : Array.isArray(system)
                 ? contentToParts(system)
                 : [{ type: "text", content: String(system) }];
-        emitLogRecord({
+        emitMessageEvent({
             logger,
+            role: "system",
+            parts,
             eventName: EVENT_NAMES.SYSTEM_MESSAGE,
-            payload: safeJsonStringify({
-                role: "system",
-                parts: truncateParts(parts),
-            }),
-            extraAttrs: {
-                [GEN_AI.PROVIDER_NAME]: "anthropic",
-                [GEN_AI.MESSAGE_INDEX]: msgIndex,
-            },
+            provider,
+            messageIndex: msgIndex,
+            span,
         });
         msgIndex++;
     }
@@ -62,38 +35,86 @@ export function emitAnthropicMessageEvents(logger, messages, system) {
         const role = typeof m.role === "string" ? m.role : "user";
         const parts = contentToParts(m.content);
         const eventName = ROLE_TO_EVENT_NAME[role] ?? `gen_ai.${role}.message`;
-        emitLogRecord({
+        emitMessageEvent({
             logger,
+            role,
+            parts,
             eventName,
-            payload: safeJsonStringify({ role, parts: truncateParts(parts) }),
-            extraAttrs: {
-                [GEN_AI.PROVIDER_NAME]: "anthropic",
-                [GEN_AI.MESSAGE_INDEX]: msgIndex,
-            },
+            provider,
+            messageIndex: msgIndex,
+            span,
         });
         msgIndex++;
     }
 }
-/**
- * Emit a gen_ai.choice LogRecord for an Anthropic response.
- * Port of _emit_choice_event from anthropic.py.
- */
-export function emitAnthropicChoiceEvent(logger, contentBlocks, stopReason) {
+/** Emit a gen_ai.choice LogRecord for an Anthropic response. */
+export function emitAnthropicChoiceEvent(logger, contentBlocks, stopReason, span, provider = "anthropic") {
     const parts = contentToParts(contentBlocks);
     const mappedReason = (stopReason && (ANTHROPIC_FINISH_REASON_MAP[stopReason] ?? stopReason)) ||
         "stop";
-    const payload = safeJsonStringify({
-        index: 0,
-        finish_reason: mappedReason,
-        message: { role: "assistant", parts: truncateParts(parts) },
+    emitChoiceEvent({
+        logger,
+        parts,
+        finishReason: mappedReason,
+        provider,
+        span,
     });
-    emitLogRecord({
+}
+/**
+ * Emit per-message log events for an OpenAI responses.create() call.
+ * `instructions` (the Responses system prompt) is emitted FIRST at index 0.
+ * Delegates LogRecord wiring to the shared emitters; only the Responses
+ * item → event mapping + ordering lives here.
+ */
+export function emitOpenAIInputMessageEvents(logger, input, instructions, span, provider = "openai") {
+    let msgIndex = 0;
+    if (instructions) {
+        const parts = typeof instructions === "string"
+            ? [{ type: "text", content: instructions }]
+            : [{ type: "text", content: String(instructions) }];
+        emitMessageEvent({
+            logger,
+            role: "system",
+            parts,
+            eventName: EVENT_NAMES.SYSTEM_MESSAGE,
+            provider,
+            messageIndex: msgIndex,
+            span,
+        });
+        msgIndex++;
+    }
+    for (const item of normalizeInput(input)) {
+        const mapped = inputItemToEvent(item);
+        if (!mapped)
+            continue;
+        const [eventName, role, parts] = mapped;
+        emitMessageEvent({
+            logger,
+            role,
+            parts,
+            eventName,
+            provider,
+            messageIndex: msgIndex,
+            span,
+        });
+        msgIndex++;
+    }
+}
+/**
+ * Emit the gen_ai.choice LogRecord from an OpenAI response.output.
+ * `finishReason` is mapped inside this emitter using mapChoiceFinishReason.
+ */
+export function emitOpenAIChoiceEvent(logger, output, finishReason, span, provider = "openai") {
+    const parts = [];
+    for (const item of Array.isArray(output) ? output : []) {
+        parts.push(...outputItemToChoiceParts(item));
+    }
+    emitChoiceEvent({
         logger,
-        eventName: EVENT_NAMES.CHOICE,
-        payload,
-        extraAttrs: {
-            [GEN_AI.PROVIDER_NAME]: "anthropic",
-        },
+        parts,
+        finishReason: mapChoiceFinishReason(finishReason),
+        provider,
+        span,
     });
 }
 //# sourceMappingURL=events.js.map

package/dist/esm/genai-content.d.ts

@@ -0,0 +1,52 @@
+import { type Span } from "@opentelemetry/api";
+import { type Logger } from "@opentelemetry/api-logs";
+/** Part in the GenAI spec format (provider-agnostic, already mapped). */
+export type Part = Record<string, unknown>;
+/** Emit ONE per-message LogRecord from already-built spec parts. */
+export declare function emitMessageEvent(opts: {
+    logger: Logger;
+    role: string;
+    parts: Part[];
+    eventName: string;
+    provider: string;
+    messageIndex: number;
+    span?: Span;
+}): void;
+/**
+ * Emit the `gen_ai.choice` LogRecord. `finishReason` is already spec-mapped by
+ * the caller (mapping is provider-specific). Omits `gen_ai.message.index`.
+ */
+export declare function emitChoiceEvent(opts: {
+    logger: Logger;
+    parts: Part[];
+    finishReason: string;
+    provider: string;
+    span?: Span;
+}): void;
+/**
+ * Stamp the last user message on the parent invoke_agent span (write-once).
+ * Provider-agnostic: the caller extracts the last user message's spec parts
+ * (Anthropic message blocks vs Responses items differ); this only stamps them.
+ */
+export declare function propagateUserPromptToParent(lastUserParts: Part[] | undefined): void;
+export type ProviderClassNameRule = readonly [ReadonlySet<string>, string];
+export type ProviderHostRule = readonly [(host: string) => boolean, string];
+/**
+ * Best-knowledge `gen_ai.provider.name` from a bound resource. TS twin of
+ * python `_genai_content.detect_provider_from_resource`.
+ *
+ * The platform client flavors (@anthropic-ai/bedrock-sdk, /vertex-sdk,
+ * AzureOpenAI) reuse the same resource prototypes as the first-party clients,
+ * so the platform is read at call time from the resource's owning client:
+ * EXACT constructor names up the prototype chain first (exact, not substring
+ * — a class named `NotAzureOpenAI` must not match; subclasses match via their
+ * inherited base's name), then per-platform `baseURL` host predicates matching
+ * only official endpoint shapes.
+ *
+ * Takes the RESOURCE: the `_client` property access is a host-boundary read (a
+ * proxied resource can throw from its getter), so it happens inside this
+ * function's guard. Falls back whenever routing is not positively detectable;
+ * never throws.
+ */
+export declare function detectProviderFromResource(resource: unknown, classNameRules: readonly ProviderClassNameRule[], hostRules: readonly ProviderHostRule[], fallback: string): string;
+//# sourceMappingURL=genai-content.d.ts.map

package/dist/esm/genai-content.js

@@ -0,0 +1,137 @@
+import { context as otelContext, trace } from "@opentelemetry/api";
+import { SeverityNumber, } from "@opentelemetry/api-logs";
+import { getAgentSpan, getSessionId } from "./context.js";
+import { EVENT_NAME, EVENT_NAMES, GEN_AI } from "./semconv.js";
+import { safeJsonStringify, truncateAndSerialize, truncateParts, } from "./truncation.js";
+/**
+ * Low-level LogRecord emitter — the single home for the OTel logs data-model
+ * wiring both providers share:
+ * - `body` (log record body) = event-tag string
+ * - `attributes.body` = JSON-serialised structured payload
+ * - `gen_ai.provider.name` always stamped; `gen_ai.conversation.id` when a
+ *   session is active.
+ *
+ * Span-context is taken from the EXPLICIT `span` when given. This matters on
+ * async resolution paths (provider `.then` continuations): OTel context does
+ * NOT auto-propagate there (the SDK installs no global context manager), so
+ * `otelContext.active()` would drop the chat span and mis-link the record.
+ * Passing the span explicitly pins the linkage. (ALS-derived values like the
+ * session id DO propagate via async_hooks, so `getSessionId()` stays correct.)
+ */
+function emitLogRecord(logger, eventName, payload, extraAttrs, span) {
+    const sessionId = getSessionId();
+    const attributes = {
+        [EVENT_NAME]: eventName,
+        body: payload,
+        ...extraAttrs,
+    };
+    if (sessionId)
+        attributes[GEN_AI.CONVERSATION_ID] = sessionId;
+    const ctx = span
+        ? trace.setSpan(otelContext.active(), span)
+        : otelContext.active();
+    logger.emit({
+        body: eventName,
+        severityNumber: SeverityNumber.INFO,
+        attributes,
+        context: ctx,
+    });
+}
+/** Emit ONE per-message LogRecord from already-built spec parts. */
+export function emitMessageEvent(opts) {
+    const { logger, role, parts, eventName, provider, messageIndex, span } = opts;
+    emitLogRecord(logger, eventName, safeJsonStringify({ role, parts: truncateParts(parts) }), {
+        [GEN_AI.PROVIDER_NAME]: provider,
+        [GEN_AI.MESSAGE_INDEX]: messageIndex,
+    }, span);
+}
+/**
+ * Emit the `gen_ai.choice` LogRecord. `finishReason` is already spec-mapped by
+ * the caller (mapping is provider-specific). Omits `gen_ai.message.index`.
+ */
+export function emitChoiceEvent(opts) {
+    const { logger, parts, finishReason, provider, span } = opts;
+    const payload = safeJsonStringify({
+        index: 0,
+        finish_reason: finishReason || "stop",
+        message: { role: "assistant", parts: truncateParts(parts) },
+    });
+    emitLogRecord(logger, EVENT_NAMES.CHOICE, payload, { [GEN_AI.PROVIDER_NAME]: provider }, span);
+}
+/**
+ * Stamp the last user message on the parent invoke_agent span (write-once).
+ * Provider-agnostic: the caller extracts the last user message's spec parts
+ * (Anthropic message blocks vs Responses items differ); this only stamps them.
+ */
+export function propagateUserPromptToParent(lastUserParts) {
+    try {
+        // Skip when the last user message has no parts (null/empty content). This
+        // matches Python's `_genai_content.propagate_user_prompt_to_parent`
+        // (`if not last_user_parts: return`) — an intentional parity-aligned delta
+        // from the old Anthropic-only helper, which stamped an empty stub here.
+        if (!lastUserParts || lastUserParts.length === 0)
+            return;
+        const agentSpan = getAgentSpan();
+        if (!agentSpan)
+            return;
+        // The SDK span type doesn't expose `attributes` — brand-check the
+        // ReadableSpan-like shape (same as the prior anthropic.ts inline helper).
+        const agentAttrs = agentSpan.attributes;
+        if (agentAttrs && agentAttrs[GEN_AI.INPUT_MESSAGES])
+            return; // write-once
+        agentSpan.setAttribute(GEN_AI.INPUT_MESSAGES, truncateAndSerialize([{ role: "user", parts: lastUserParts }]));
+    }
+    catch {
+        /* never fail the application for telemetry */
+    }
+}
+/**
+ * Best-knowledge `gen_ai.provider.name` from a bound resource. TS twin of
+ * python `_genai_content.detect_provider_from_resource`.
+ *
+ * The platform client flavors (@anthropic-ai/bedrock-sdk, /vertex-sdk,
+ * AzureOpenAI) reuse the same resource prototypes as the first-party clients,
+ * so the platform is read at call time from the resource's owning client:
+ * EXACT constructor names up the prototype chain first (exact, not substring
+ * — a class named `NotAzureOpenAI` must not match; subclasses match via their
+ * inherited base's name), then per-platform `baseURL` host predicates matching
+ * only official endpoint shapes.
+ *
+ * Takes the RESOURCE: the `_client` property access is a host-boundary read (a
+ * proxied resource can throw from its getter), so it happens inside this
+ * function's guard. Falls back whenever routing is not positively detectable;
+ * never throws.
+ */
+export function detectProviderFromResource(resource, classNameRules, hostRules, fallback) {
+    try {
+        const client = resource
+            ?._client;
+        if (!client || typeof client !== "object")
+            return fallback;
+        let proto = Object.getPrototypeOf(client);
+        while (proto) {
+            const name = proto.constructor
+                ?.name;
+            if (typeof name === "string") {
+                for (const [names, provider] of classNameRules) {
+                    if (names.has(name))
+                        return provider;
+                }
+            }
+            proto = Object.getPrototypeOf(proto);
+        }
+        const raw = client.baseURL;
+        const host = raw ? new URL(String(raw)).hostname : "";
+        if (host) {
+            for (const [matchesHost, provider] of hostRules) {
+                if (matchesHost(host))
+                    return provider;
+            }
+        }
+    }
+    catch {
+        /* detection must never fault the host call */
+    }
+    return fallback;
+}
+//# sourceMappingURL=genai-content.js.map

package/dist/esm/instrument.d.ts

@@ -0,0 +1,47 @@
+import { SpanKind, type Context, type Span, type Tracer } from "@opentelemetry/api";
+import { type InternalLogger } from "./core.js";
+/**
+ * Telemetry callbacks + span config a provider supplies to {@link instrumentCall}.
+ * The callbacks are the ONLY provider-specific code; they run inside `safe()`
+ * and may never reach the host call path.
+ */
+export interface CallInstrumentation {
+    tracer: Tracer;
+    spanName: string;
+    spanKind: SpanKind;
+    /** Resolves the parent context for the span (e.g. the enclosing agent span). */
+    parentContext: () => Context;
+    /** Prefix for `safe()` telemetry-failure sites, e.g. `"openai.create"`. */
+    sitePrefix: string;
+    internalLogger: InternalLogger;
+    /** Set request-side attributes + emit request log events (given the span). */
+    onStart: (span: Span) => void;
+    /** Set response-side attributes + emit the choice event (given the span). */
+    onSuccess: (span: Span, result: unknown) => void;
+    /** Record an error on the span. */
+    onError: (span: Span, err: unknown) => void;
+}
+/**
+ * The single audited host boundary for provider `create()` instrumentation.
+ *
+ * STRUCTURAL GUARANTEE: `invoke()` (the host provider call) runs EXACTLY ONCE,
+ * and its return value / thrown error reaches the caller UNCHANGED, regardless
+ * of any telemetry failure. Nothing host-controllable — a customer's global
+ * OTel `ContextManager`, a hostile response/thenable, a broken tracer — is ever
+ * on the synchronous path that produces `invoke()`'s result:
+ *
+ *   - span creation is `safe()`-guarded; on failure we run `invoke()`
+ *     uninstrumented and return it;
+ *   - all telemetry (request attrs/events, response attrs/events, error
+ *     recording, span end) runs in `safe()` satellites that degrade to
+ *     "no telemetry" on any throw;
+ *   - `invoke()` itself is NOT wrapped in `otelContext.with(...)` or any other
+ *     host-controllable operation — log-record→span linkage is carried by the
+ *     explicit span passed to the emitters, not by ambient context.
+ *
+ * New providers supply only the telemetry callbacks, so they add no new way to
+ * break the host. Mirrors struct-sdk-python's generator sandwich in
+ * `_create_common` / `_wrap_create`.
+ */
+export declare function instrumentCall(invoke: () => unknown, inst: CallInstrumentation): unknown;
+//# sourceMappingURL=instrument.d.ts.map