@struct-ai/sdk 0.3.17 → 0.4.2

package/dist/commonjs/integrations/openai.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._setChatRequestAttrsForTest = exports._detectProviderForTest = void 0;
+exports.patch = patch;
+exports.unpatch = unpatch;
+exports.wrapCreate = wrapCreate;
+exports._wrapCreateForTest = _wrapCreateForTest;
+exports._setActivePatchCtxForTest = _setActivePatchCtxForTest;
+exports._collectResponsesClassesForTest = _collectResponsesClassesForTest;
+const api_1 = require("@opentelemetry/api");
+const context_js_1 = require("../context.js");
+const events_js_1 = require("../events.js");
+const genai_content_js_1 = require("../genai-content.js");
+const instrument_js_1 = require("../instrument.js");
+const semconv_js_1 = require("../semconv.js");
+const openai_content_js_1 = require("./openai-content.js");
+const STRUCT_WRAPPED = Symbol.for("struct.wrapped");
+const STRUCT_ORIGINAL = Symbol.for("struct.original");
+/**
+ * Mutable reference updated on each patch() call — wrappers dereference it at
+ * call time, so the most recently initialized SDK wins (matches the singleton
+ * production model + keeps multi-instance tests working). Mirrors anthropic.ts.
+ */
+const activePatchCtx = { value: undefined };
+function childParentContext() {
+    const agentSpan = (0, context_js_1.getAgentSpan)();
+    return agentSpan
+        ? api_1.trace.setSpan(api_1.context.active(), agentSpan)
+        : api_1.context.active();
+}
+async function patch(sdk) {
+    const openaiMod = (await import("openai"));
+    activePatchCtx.value = {
+        tracer: sdk.getTracer("struct-sdk-openai"),
+        sdk,
+        logger: sdk.emitEvents ? sdk.getLogger("struct-sdk-openai") : undefined,
+    };
+    const classes = collectResponsesClasses(openaiMod);
+    for (const cls of classes) {
+        wrapMethod(cls.prototype, "create");
+    }
+}
+async function unpatch() {
+    activePatchCtx.value = undefined;
+    try {
+        const openaiMod = (await import("openai"));
+        const classes = collectResponsesClasses(openaiMod);
+        for (const cls of classes) {
+            restoreMethod(cls.prototype, "create");
+        }
+    }
+    catch {
+        /* not installed */
+    }
+}
+/**
+ * Collect the `Responses` class from the openai module. The default export
+ * (`OpenAI`) exposes `OpenAI.Responses` as a static (client.js assigns it in
+ * both v5 and v6). Older versions without the Responses API expose no such
+ * static → returns []; patch() becomes a graceful no-op.
+ */
+function collectResponsesClasses(mod) {
+    const classes = [];
+    const OpenAI = mod.default ?? mod.OpenAI;
+    if (typeof OpenAI === "function") {
+        const ctor = OpenAI;
+        if (typeof ctor.Responses === "function") {
+            classes.push(ctor.Responses);
+        }
+    }
+    return classes;
+}
+function wrapMethod(proto, methodName) {
+    const original = proto[methodName];
+    if (typeof original !== "function")
+        return;
+    const existing = original;
+    if (existing[STRUCT_WRAPPED])
+        return;
+    const wrapper = wrapCreate(original);
+    wrapper[STRUCT_WRAPPED] = true;
+    wrapper[STRUCT_ORIGINAL] = original;
+    proto[methodName] = wrapper;
+}
+function restoreMethod(proto, methodName) {
+    const current = proto[methodName];
+    if (current && current[STRUCT_WRAPPED] && current[STRUCT_ORIGINAL]) {
+        proto[methodName] = current[STRUCT_ORIGINAL];
+    }
+}
+// Exact client class names (prototype chain covers subclasses) and official
+// Azure endpoint host shapes. Parity: python openai.py.
+const CLASS_NAME_RULES = [
+    [new Set(["AzureOpenAI", "BaseAzureOpenAI"]), "azure.ai.openai"],
+];
+function isAzureHost(host) {
+    // Precise SERVICE suffixes only, incl. sovereign clouds (Azure Government
+    // .us, Azure China .cn) — generic .azure.{com,us,cn} proxies must not
+    // match. Parity: python openai.py's nine suffixes.
+    return (host.endsWith(".openai.azure.com") ||
+        host.endsWith(".openai.azure.us") ||
+        host.endsWith(".openai.azure.cn") ||
+        host.endsWith(".cognitiveservices.azure.com") ||
+        host.endsWith(".cognitiveservices.azure.us") ||
+        host.endsWith(".cognitiveservices.azure.cn") ||
+        host.endsWith(".services.ai.azure.com") ||
+        host.endsWith(".services.ai.azure.us") ||
+        host.endsWith(".services.ai.azure.cn"));
+}
+const HOST_RULES = [
+    [isAzureHost, "azure.ai.openai"],
+];
+function detectProvider(resource) {
+    return (0, genai_content_js_1.detectProviderFromResource)(resource, CLASS_NAME_RULES, HOST_RULES, "openai");
+}
+/** @internal */
+exports._detectProviderForTest = detectProvider;
+function wrapCreate(original) {
+    return function wrappedCreate(params, opts) {
+        const patchCtx = activePatchCtx.value;
+        if (!patchCtx) {
+            return original.call(this, params, opts);
+        }
+        // CLASS RULE: detection => propagation, immediately and on EVERY path —
+        // before suppression/streaming returns AND before any chat-span telemetry
+        // that could fail (a broken tracer or throwing chat-span attribute write
+        // must not leave a healthy agent span unattributed). Both calls are
+        // internally guarded; write-once makes repeats harmless.
+        const provider = detectProvider(this);
+        (0, context_js_1.propagateProviderToParent)(provider);
+        if ((0, context_js_1.isGenAiSuppressed)()) {
+            // A framework layer owns this chat span — run the call, emit no span.
+            return original.call(this, params, opts);
+        }
+        // Preflight reads touch CALLER-owned `params` — a Proxy / lazy request
+        // object can have throwing getters, and a throw here (before
+        // instrumentCall's guards) would prevent the OpenAI call entirely.
+        // Degrade: exactly one plain, uninstrumented original.call.
+        let streaming = false;
+        let model = "unknown";
+        try {
+            streaming = !!(params && params.stream === true);
+            model = params?.model ?? "unknown";
+        }
+        catch {
+            return original.call(this, params, opts);
+        }
+        // Streaming is out of scope: pass through untouched, emit no span. The SDK
+        // must never consume/buffer a caller's stream. `responses.stream()` routes
+        // here internally with stream:true too, so this covers it.
+        if (streaming) {
+            // Stream passthrough: no chat span; agent already attributed above.
+            return original.call(this, params, opts);
+        }
+        const { tracer, sdk, logger } = patchCtx;
+        // All host-boundary safety lives in the shared instrumentCall harness: the
+        // host call runs exactly once, nothing host-controllable wraps it, and every
+        // telemetry side-effect degrades via safe(). This provider only supplies the
+        // telemetry callbacks.
+        return (0, instrument_js_1.instrumentCall)(() => original.call(this, params, opts), {
+            tracer,
+            spanName: `chat ${model}`,
+            spanKind: api_1.SpanKind.CLIENT,
+            parentContext: childParentContext,
+            sitePrefix: "openai.create",
+            internalLogger: sdk.getInternalLogger(),
+            onStart: (span) => setChatRequestAttrs(span, params, sdk, logger, provider),
+            onSuccess: (span, result) => setChatResponseAttrs(span, sdk, result, logger, provider),
+            onError: (span, err) => recordErrorOnSpan(span, err),
+        });
+    };
+}
+function setChatRequestAttrs(span, params, sdk, logger, provider = "openai") {
+    span.setAttribute(semconv_js_1.GEN_AI.OPERATION_NAME, "chat");
+    span.setAttribute(semconv_js_1.GEN_AI.PROVIDER_NAME, provider);
+    const model = params?.model ?? "unknown";
+    span.setAttribute(semconv_js_1.GEN_AI.REQUEST_MODEL, model);
+    const sessionId = (0, context_js_1.getSessionId)();
+    if (sessionId)
+        span.setAttribute(semconv_js_1.GEN_AI.CONVERSATION_ID, sessionId);
+    // Responses names its output cap `max_output_tokens`; semconv is
+    // `gen_ai.request.max_tokens` (same key the Anthropic emitter uses). Truthy
+    // check mirrors python (`if kwargs.get("max_output_tokens")`); temp/top_p use
+    // `!= null` so 0 is recorded (mirrors python `is not None`).
+    if (params?.max_output_tokens) {
+        span.setAttribute(semconv_js_1.GEN_AI.REQUEST_MAX_TOKENS, params.max_output_tokens);
+    }
+    if (params?.temperature != null) {
+        span.setAttribute(semconv_js_1.GEN_AI.REQUEST_TEMPERATURE, params.temperature);
+    }
+    if (params?.top_p != null) {
+        span.setAttribute(semconv_js_1.GEN_AI.REQUEST_TOP_P, params.top_p);
+    }
+    const input = params?.input;
+    const instructions = params?.instructions;
+    if (typeof input === "string") {
+        span.setAttribute(semconv_js_1.STRUCT.INPUT_MESSAGE_COUNT, 1);
+    }
+    else if (Array.isArray(input)) {
+        span.setAttribute(semconv_js_1.STRUCT.INPUT_MESSAGE_COUNT, input.length);
+    }
+    // Parent-prompt preview is CONTENT — never emit it in ContentCaptureMode.None.
+    // Deliberately kept in EventOnly (the default): the agent-span prompt preview
+    // is Struct's shipped behavior in both SDKs and what the waterfall UI reads.
+    if (sdk.captureContent) {
+        (0, genai_content_js_1.propagateUserPromptToParent)((0, openai_content_js_1.lastUserParts)(input));
+    }
+    if (sdk.emitEvents && logger) {
+        (0, events_js_1.emitOpenAIInputMessageEvents)(logger, input, instructions, span, provider);
+    }
+    if (sdk.emitSpanContent) {
+        if (input !== undefined && input !== null) {
+            span.setAttribute(semconv_js_1.GEN_AI.INPUT_MESSAGES, (0, openai_content_js_1.toInputMessages)(input));
+        }
+        if (instructions) {
+            span.setAttribute(semconv_js_1.GEN_AI.SYSTEM_INSTRUCTIONS, (0, openai_content_js_1.toSystemInstructions)(instructions));
+        }
+        if (params?.tools && Array.isArray(params.tools)) {
+            span.setAttribute(semconv_js_1.GEN_AI.TOOL_DEFINITIONS, (0, openai_content_js_1.safeJsonForTool)(params.tools));
+        }
+    }
+}
+function setChatResponseAttrs(span, sdk, response, logger, provider = "openai") {
+    const usage = response?.usage;
+    if (usage) {
+        const inputTokens = usage.input_tokens ?? 0;
+        const outputTokens = usage.output_tokens ?? 0;
+        const details = usage.input_tokens_details;
+        const cacheRead = details?.cached_tokens ?? 0;
+        // OpenAI input_tokens ALREADY includes cached tokens — report as-is (NO
+        // Anthropic-style add-back; that would double-count).
+        span.setAttribute(semconv_js_1.GEN_AI.USAGE_INPUT_TOKENS, inputTokens);
+        span.setAttribute(semconv_js_1.GEN_AI.USAGE_OUTPUT_TOKENS, outputTokens);
+        const reasoningTokens = usage.output_tokens_details?.reasoning_tokens ?? 0;
+        if (reasoningTokens) {
+            // Subset of output_tokens (chain-of-thought) — observability only, never
+            // added to cost. Emitted only when > 0.
+            span.setAttribute(semconv_js_1.GEN_AI.USAGE_REASONING_OUTPUT_TOKENS, reasoningTokens);
+        }
+        if (cacheRead) {
+            span.setAttribute(semconv_js_1.GEN_AI.USAGE_CACHE_READ_INPUT_TOKENS, cacheRead);
+        }
+        const cacheWrite = details?.cache_write_tokens ?? 0;
+        if (cacheWrite) {
+            // gpt-5.6 charges cache writes (1.25x input). Nested-key name matches the
+            // Anthropic emitter / Struct ingest views. Emitted only when > 0.
+            span.setAttribute(semconv_js_1.GEN_AI.USAGE_CACHE_CREATION_INPUT_TOKENS, cacheWrite);
+        }
+    }
+    if (response?.model)
+        span.setAttribute(semconv_js_1.GEN_AI.RESPONSE_MODEL, response.model);
+    if (response?.id)
+        span.setAttribute(semconv_js_1.GEN_AI.RESPONSE_ID, response.id);
+    // A background (`queued`/`in_progress`) response is NOT terminal — the
+    // generation hasn't finished, so there is no assistant message yet. Emitting
+    // a terminal finish reason / choice event then would report a still-running
+    // request as completed. Skip terminal telemetry until a terminal response is
+    // observed; usage/model/id above are still recorded.
+    const terminal = (0, openai_content_js_1.isTerminalResponse)(response);
+    const finishReason = (0, openai_content_js_1.deriveFinishReason)(response);
+    if (finishReason && terminal) {
+        span.setAttribute(semconv_js_1.GEN_AI.RESPONSE_FINISH_REASONS, [finishReason]);
+    }
+    const output = response?.output;
+    // Structural (not content) — always runs, like the Anthropic emitter.
+    recordPendingToolCalls(output);
+    if (sdk.emitEvents && logger && terminal) {
+        // The choice emitter maps the finish reason to the spec name internally
+        // via mapChoiceFinishReason — pass the RAW derived reason.
+        (0, events_js_1.emitOpenAIChoiceEvent)(logger, output, finishReason, span, provider);
+    }
+    if (sdk.emitSpanContent && terminal) {
+        span.setAttribute(semconv_js_1.GEN_AI.OUTPUT_MESSAGES, (0, openai_content_js_1.toOutputMessages)(output, finishReason));
+    }
+}
+function recordPendingToolCalls(output) {
+    const pairs = (0, openai_content_js_1.iterFunctionCalls)(output);
+    if (pairs.length === 0)
+        return;
+    (0, context_js_1.ensurePendingToolCallsSlot)();
+    (0, context_js_1.pushPendingToolCalls)(pairs);
+}
+function recordErrorOnSpan(span, err) {
+    const errorType = err instanceof Error ? err.constructor.name : typeof err;
+    const message = err instanceof Error ? err.message : String(err);
+    span.setAttribute(semconv_js_1.ERROR_TYPE, errorType);
+    span.setStatus({ code: api_1.SpanStatusCode.ERROR, message });
+    if (err instanceof Error) {
+        span.recordException(err);
+    }
+}
+/** @internal */
+function _wrapCreateForTest(original) {
+    return wrapCreate(original);
+}
+/** @internal */
+exports._setChatRequestAttrsForTest = setChatRequestAttrs;
+function _setActivePatchCtxForTest(ctx) {
+    activePatchCtx.value = ctx;
+}
+/** @internal — version-compat tests assert the patch surface across openai releases. */
+function _collectResponsesClassesForTest(mod) {
+    return collectResponsesClasses(mod);
+}
+//# sourceMappingURL=openai.js.map

package/dist/commonjs/semconv.d.ts

@@ -21,6 +21,7 @@ export declare const GEN_AI: {
     readonly USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
     readonly USAGE_CACHE_READ_INPUT_TOKENS: "gen_ai.usage.cache_read.input_tokens";
     readonly USAGE_CACHE_CREATION_INPUT_TOKENS: "gen_ai.usage.cache_creation.input_tokens";
+    readonly USAGE_REASONING_OUTPUT_TOKENS: "gen_ai.usage.reasoning.output_tokens";
     readonly INPUT_MESSAGES: "gen_ai.input.messages";
     readonly OUTPUT_MESSAGES: "gen_ai.output.messages";
     readonly SYSTEM_INSTRUCTIONS: "gen_ai.system_instructions";

package/dist/commonjs/semconv.js

@@ -24,6 +24,7 @@ exports.GEN_AI = {
     USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
     USAGE_CACHE_READ_INPUT_TOKENS: "gen_ai.usage.cache_read.input_tokens",
     USAGE_CACHE_CREATION_INPUT_TOKENS: "gen_ai.usage.cache_creation.input_tokens",
+    USAGE_REASONING_OUTPUT_TOKENS: "gen_ai.usage.reasoning.output_tokens",
     INPUT_MESSAGES: "gen_ai.input.messages",
     OUTPUT_MESSAGES: "gen_ai.output.messages",
     SYSTEM_INSTRUCTIONS: "gen_ai.system_instructions",

package/dist/commonjs/truncation.d.ts

@@ -6,5 +6,34 @@ type Part = Record<string, unknown>;
 export declare function truncateParts(parts: Part[]): Part[];
 export declare function truncateAndSerialize(obj: unknown, maxSize?: number): string;
 export declare function safeJsonStringify(obj: unknown): string;
+/**
+ * Bound the large string/schema fields of a SINGLE tool definition so one
+ * oversized tool can't push the whole `gen_ai.tool.definitions` payload past
+ * the content cap and trigger `truncateAndSerialize`'s `[]` fallback (which
+ * would erase ALL tool telemetry). Tool definitions have no `parts`/`content`
+ * fields, so the array-level truncation doesn't reach them — this does.
+ *
+ * Returns the tool UNCHANGED (same reference) when nothing is oversized, so
+ * normal-sized tools serialize byte-identically (no behavior change). Covers
+ * both providers' schema key (`parameters` for OpenAI, `input_schema` for
+ * Anthropic) plus `description`.
+ */
+export declare function truncateToolDefinition(tool: unknown): unknown;
+/**
+ * Serialize a provider's tool-definitions to bounded, ALWAYS-valid JSON for the
+ * `gen_ai.tool.definitions` attribute. Two levels of bounding:
+ *
+ *  1. per-tool: each tool's oversized description/schema is capped
+ *     (`truncateToolDefinition`);
+ *  2. per-array: many tools can each fit under `MAX_FIELD_SIZE` yet together
+ *     exceed `MAX_CONTENT_SIZE`. Rather than let `truncateAndSerialize` byte-cut
+ *     the array (which can slice inside a nested schema and append `]` →
+ *     malformed JSON), keep as many WHOLE tool entries as fit and append a
+ *     truncation-marker entry. Output is guaranteed parseable.
+ *
+ * Non-arrays fall back to `truncateAndSerialize`. Never throws (the whole thing
+ * degrades to a best-effort string).
+ */
+export declare function serializeToolDefinitions(obj: unknown): string;
 export {};
 //# sourceMappingURL=truncation.d.ts.map

package/dist/commonjs/truncation.js

@@ -5,6 +5,8 @@ exports.truncateField = truncateField;
 exports.truncateParts = truncateParts;
 exports.truncateAndSerialize = truncateAndSerialize;
 exports.safeJsonStringify = safeJsonStringify;
+exports.truncateToolDefinition = truncateToolDefinition;
+exports.serializeToolDefinitions = serializeToolDefinitions;
 exports.MAX_CONTENT_SIZE = 128 * 1024;
 exports.MAX_FIELD_SIZE = 16384;
 exports.TRUNCATION_MARKER = "… [truncated]";
@@ -50,9 +52,10 @@ function truncateParts(parts) {
     return result;
 }
 function truncateAndSerialize(obj, maxSize = exports.MAX_CONTENT_SIZE) {
+    let items;
     let result;
     if (Array.isArray(obj)) {
-        const truncated = obj.map((item) => {
+        items = obj.map((item) => {
             if (!item || typeof item !== "object")
                 return item;
             const copy = { ...item };
@@ -64,31 +67,202 @@ function truncateAndSerialize(obj, maxSize = exports.MAX_CONTENT_SIZE) {
             }
             return copy;
         });
-        result = safeJsonStringify(truncated);
+        result = safeJsonStringify(items);
     }
     else {
         result = safeJsonStringify(obj);
     }
     if (result.length > maxSize) {
-        const cut = result.slice(0, maxSize - 50);
-        const lastBrace = cut.lastIndexOf("}");
-        if (lastBrace > 0) {
-            result = cut.slice(0, lastBrace + 1) + "]";
-        }
-        else {
-            result = "[]";
+        // NEVER byte-cut serialized JSON — a cut can land inside a nested object
+        // (e.g. a message's parts array) and appending "]" then yields malformed
+        // output. Instead: (1) shrink any single entry that alone exceeds the
+        // budget by dropping whole PARTS (so one huge multipart message keeps a
+        // prefix of its parts rather than vanishing); (2) keep whole top-level
+        // entries; (3) append a MESSAGE-SHAPED marker entry. Consumers of
+        // gen_ai.{input,output}.messages parse these arrays as {role, parts}
+        // messages — a bare marker object without `parts` crashes them, so the
+        // marker must itself be a valid message.
+        if (items) {
+            // Shape-aware marker: gen_ai.{input,output}.messages arrays hold
+            // {role, parts} MESSAGES, but gen_ai.system_instructions holds bare
+            // {type, content} PARTS — a message-shaped marker among parts corrupts
+            // that attribute's shape for consumers. Mirror whichever shape the
+            // array actually carries.
+            const isMessageArray = items.some((i) => !!i && typeof i === "object" && "role" in i);
+            const marker = isMessageArray
+                ? (dropped) => ({
+                    role: "system",
+                    parts: [
+                        {
+                            type: "text",
+                            content: `[struct.truncated: ${dropped} message(s) dropped]`,
+                        },
+                    ],
+                    "struct.truncated": true,
+                })
+                : (dropped) => ({
+                    type: "text",
+                    content: `[struct.truncated: ${dropped} item(s) dropped]`,
+                    "struct.truncated": true,
+                });
+            const entryBudget = maxSize - MARKER_HEADROOM - 2;
+            const shrunk = items.map((i) => shrinkOversizedPartsEntry(i, entryBudget));
+            return capWholeEntries(shrunk, maxSize, marker);
         }
+        // Oversized non-array payload (rare): drop rather than emit malformed JSON.
+        return "[]";
     }
     return result;
 }
+const MARKER_HEADROOM = 256;
+/**
+ * If a single {role, parts} entry serializes past `maxSize`, keep a prefix of
+ * WHOLE parts that fits and append a text marker part — the entry survives with
+ * partial content instead of being dropped wholesale. Entries without a parts
+ * array are returned unchanged (capWholeEntries will drop them if oversized).
+ */
+function shrinkOversizedPartsEntry(item, maxSize) {
+    if (!item || typeof item !== "object")
+        return item;
+    const serialized = safeJsonStringify(item);
+    if (serialized.length <= maxSize)
+        return item;
+    const rec = item;
+    if (!Array.isArray(rec.parts))
+        return item;
+    const envelope = serialized.length - safeJsonStringify(rec.parts).length;
+    const kept = [];
+    let size = envelope + 2;
+    for (const p of rec.parts) {
+        const ps = safeJsonStringify(p);
+        if (size + ps.length + 1 + MARKER_HEADROOM > maxSize)
+            break;
+        kept.push(p);
+        size += ps.length + 1;
+    }
+    kept.push({
+        type: "text",
+        content: `[struct.truncated: ${rec.parts.length - kept.length} part(s) dropped]`,
+    });
+    return { ...rec, parts: kept, "struct.truncated": true };
+}
+/**
+ * Serialize `items` keeping as many WHOLE top-level entries as fit in
+ * `maxSize`, appending `marker(droppedCount)` as a final entry when any were
+ * dropped. Output is always parseable — the guarantee byte-cutting can't give.
+ */
+function capWholeEntries(items, maxSize, marker) {
+    // Reserve the ACTUAL worst-case marker size (dropped = items.length has the
+    // most digits), not a fixed guess — a fixed reserve can't honor small
+    // maxSize values.
+    const reserve = safeJsonStringify(marker(items.length)).length + 1;
+    const kept = [];
+    let size = 2; // "[]"
+    for (const item of items) {
+        const entry = safeJsonStringify(item);
+        if (size + entry.length + 1 + reserve > maxSize)
+            break;
+        kept.push(item);
+        size += entry.length + 1;
+    }
+    const dropped = items.length - kept.length;
+    if (dropped > 0) {
+        const markerEntry = marker(dropped);
+        if (kept.length === 0 &&
+            safeJsonStringify([markerEntry]).length > maxSize) {
+            return "[]"; // even the marker alone exceeds the caller's budget
+        }
+        kept.push(markerEntry);
+    }
+    return safeJsonStringify(kept);
+}
 function safeJsonStringify(obj) {
     try {
-        return JSON.stringify(obj, defaultReplacer);
+        // JSON.stringify returns the VALUE undefined (not a string) for
+        // undefined/functions/symbols — normalize to valid JSON so callers can
+        // safely read `.length` / embed the result.
+        return JSON.stringify(obj, defaultReplacer) ?? "null";
     }
     catch {
         return JSON.stringify(String(obj));
     }
 }
+/**
+ * Bound the large string/schema fields of a SINGLE tool definition so one
+ * oversized tool can't push the whole `gen_ai.tool.definitions` payload past
+ * the content cap and trigger `truncateAndSerialize`'s `[]` fallback (which
+ * would erase ALL tool telemetry). Tool definitions have no `parts`/`content`
+ * fields, so the array-level truncation doesn't reach them — this does.
+ *
+ * Returns the tool UNCHANGED (same reference) when nothing is oversized, so
+ * normal-sized tools serialize byte-identically (no behavior change). Covers
+ * both providers' schema key (`parameters` for OpenAI, `input_schema` for
+ * Anthropic) plus `description`.
+ */
+function truncateToolDefinition(tool) {
+    if (!tool || typeof tool !== "object")
+        return tool;
+    const src = tool;
+    let copy;
+    const mutable = () => (copy ??= { ...src });
+    if (typeof src.description === "string" && src.description.length > exports.MAX_FIELD_SIZE) {
+        mutable().description = src.description.slice(0, exports.MAX_FIELD_SIZE) + exports.TRUNCATION_MARKER;
+    }
+    for (const key of ["parameters", "input_schema"]) {
+        const value = src[key];
+        if (value && typeof value === "object") {
+            const serialized = safeJsonStringify(value);
+            if (serialized.length > exports.MAX_FIELD_SIZE) {
+                // Keep the schema field a valid OBJECT. Slicing the serialized JSON to a
+                // string would parse at the outer payload level but leave the schema
+                // non-traversable and violating both providers' tool contract. A
+                // sentinel object signals truncation + the original size instead.
+                mutable()[key] = {
+                    "struct.truncated": true,
+                    original_bytes: serialized.length,
+                };
+            }
+        }
+    }
+    return copy ?? tool;
+}
+/**
+ * Serialize a provider's tool-definitions to bounded, ALWAYS-valid JSON for the
+ * `gen_ai.tool.definitions` attribute. Two levels of bounding:
+ *
+ *  1. per-tool: each tool's oversized description/schema is capped
+ *     (`truncateToolDefinition`);
+ *  2. per-array: many tools can each fit under `MAX_FIELD_SIZE` yet together
+ *     exceed `MAX_CONTENT_SIZE`. Rather than let `truncateAndSerialize` byte-cut
+ *     the array (which can slice inside a nested schema and append `]` →
+ *     malformed JSON), keep as many WHOLE tool entries as fit and append a
+ *     truncation-marker entry. Output is guaranteed parseable.
+ *
+ * Non-arrays fall back to `truncateAndSerialize`. Never throws (the whole thing
+ * degrades to a best-effort string).
+ */
+function serializeToolDefinitions(obj) {
+    try {
+        if (!Array.isArray(obj))
+            return truncateAndSerialize(obj);
+        const bounded = obj.map(truncateToolDefinition);
+        const serialized = safeJsonStringify(bounded);
+        if (serialized.length <= exports.MAX_CONTENT_SIZE)
+            return serialized;
+        // Overflow: keep whole tool entries + a marker (shared core with
+        // truncateAndSerialize — never a mid-object byte slice).
+        return capWholeEntries(bounded, exports.MAX_CONTENT_SIZE, (dropped) => ({
+            "struct.truncated": true,
+            dropped_tools: dropped,
+        }));
+    }
+    catch {
+        // Terminal, NON-host-controlled fallback. Re-serializing `obj` here could
+        // return the original oversized payload (size guarantee violated) or throw
+        // again via hostile toString/map overrides — degrade to an empty array.
+        return "[]";
+    }
+}
 function defaultReplacer(_key, value) {
     if (typeof value === "bigint")
         return value.toString();

package/dist/commonjs/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "0.3.17";
+export declare const SDK_VERSION = "0.4.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/commonjs/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
 // Keep in sync with package.json; test/version.test.ts enforces it.
-exports.SDK_VERSION = "0.3.17";
+exports.SDK_VERSION = "0.4.2";
 //# sourceMappingURL=version.js.map

package/dist/esm/context.d.ts

@@ -53,4 +53,23 @@ export declare function snapshotStore(): StructContext | undefined;
 export declare function runWithStore<T>(store: StructContext | undefined, fn: () => T): T;
 /** Test-only: run `fn` inside a completely fresh context (no parent store). */
 export declare function runInFreshContext<T>(fn: () => T): T;
+/**
+ * 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 declare function stampProviderOnce(agentSpan: Span | undefined, provider: string | undefined): void;
+/** Stamp the ambient agent span with the child call's provider (write-once). */
+export declare function propagateProviderToParent(provider: string | undefined): void;
 //# sourceMappingURL=context.d.ts.map