@struct-ai/sdk 0.3.0 → 0.4.2

package/dist/esm/integrations/openai.js

@@ -0,0 +1,296 @@
+import { SpanKind, SpanStatusCode, context as otelContext, trace, } from "@opentelemetry/api";
+import { ensurePendingToolCallsSlot, getAgentSpan, getSessionId, isGenAiSuppressed, propagateProviderToParent, pushPendingToolCalls, } from "../context.js";
+import { emitOpenAIChoiceEvent, emitOpenAIInputMessageEvents, } from "../events.js";
+import { detectProviderFromResource, propagateUserPromptToParent, } from "../genai-content.js";
+import { instrumentCall } from "../instrument.js";
+import { ERROR_TYPE, GEN_AI, STRUCT } from "../semconv.js";
+import { deriveFinishReason, isTerminalResponse, iterFunctionCalls, lastUserParts, safeJsonForTool, toInputMessages, toOutputMessages, toSystemInstructions, } from "./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 = getAgentSpan();
+    return agentSpan
+        ? trace.setSpan(otelContext.active(), agentSpan)
+        : otelContext.active();
+}
+export 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");
+    }
+}
+export 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 detectProviderFromResource(resource, CLASS_NAME_RULES, HOST_RULES, "openai");
+}
+/** @internal */
+export const _detectProviderForTest = detectProvider;
+export 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);
+        propagateProviderToParent(provider);
+        if (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 instrumentCall(() => original.call(this, params, opts), {
+            tracer,
+            spanName: `chat ${model}`,
+            spanKind: 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(GEN_AI.OPERATION_NAME, "chat");
+    span.setAttribute(GEN_AI.PROVIDER_NAME, provider);
+    const model = params?.model ?? "unknown";
+    span.setAttribute(GEN_AI.REQUEST_MODEL, model);
+    const sessionId = getSessionId();
+    if (sessionId)
+        span.setAttribute(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(GEN_AI.REQUEST_MAX_TOKENS, params.max_output_tokens);
+    }
+    if (params?.temperature != null) {
+        span.setAttribute(GEN_AI.REQUEST_TEMPERATURE, params.temperature);
+    }
+    if (params?.top_p != null) {
+        span.setAttribute(GEN_AI.REQUEST_TOP_P, params.top_p);
+    }
+    const input = params?.input;
+    const instructions = params?.instructions;
+    if (typeof input === "string") {
+        span.setAttribute(STRUCT.INPUT_MESSAGE_COUNT, 1);
+    }
+    else if (Array.isArray(input)) {
+        span.setAttribute(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) {
+        propagateUserPromptToParent(lastUserParts(input));
+    }
+    if (sdk.emitEvents && logger) {
+        emitOpenAIInputMessageEvents(logger, input, instructions, span, provider);
+    }
+    if (sdk.emitSpanContent) {
+        if (input !== undefined && input !== null) {
+            span.setAttribute(GEN_AI.INPUT_MESSAGES, toInputMessages(input));
+        }
+        if (instructions) {
+            span.setAttribute(GEN_AI.SYSTEM_INSTRUCTIONS, toSystemInstructions(instructions));
+        }
+        if (params?.tools && Array.isArray(params.tools)) {
+            span.setAttribute(GEN_AI.TOOL_DEFINITIONS, 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(GEN_AI.USAGE_INPUT_TOKENS, inputTokens);
+        span.setAttribute(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(GEN_AI.USAGE_REASONING_OUTPUT_TOKENS, reasoningTokens);
+        }
+        if (cacheRead) {
+            span.setAttribute(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(GEN_AI.USAGE_CACHE_CREATION_INPUT_TOKENS, cacheWrite);
+        }
+    }
+    if (response?.model)
+        span.setAttribute(GEN_AI.RESPONSE_MODEL, response.model);
+    if (response?.id)
+        span.setAttribute(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 = isTerminalResponse(response);
+    const finishReason = deriveFinishReason(response);
+    if (finishReason && terminal) {
+        span.setAttribute(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.
+        emitOpenAIChoiceEvent(logger, output, finishReason, span, provider);
+    }
+    if (sdk.emitSpanContent && terminal) {
+        span.setAttribute(GEN_AI.OUTPUT_MESSAGES, toOutputMessages(output, finishReason));
+    }
+}
+function recordPendingToolCalls(output) {
+    const pairs = iterFunctionCalls(output);
+    if (pairs.length === 0)
+        return;
+    ensurePendingToolCallsSlot();
+    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(ERROR_TYPE, errorType);
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    if (err instanceof Error) {
+        span.recordException(err);
+    }
+}
+/** @internal */
+export function _wrapCreateForTest(original) {
+    return wrapCreate(original);
+}
+/** @internal */
+export const _setChatRequestAttrsForTest = setChatRequestAttrs;
+export function _setActivePatchCtxForTest(ctx) {
+    activePatchCtx.value = ctx;
+}
+/** @internal — version-compat tests assert the patch surface across openai releases. */
+export function _collectResponsesClassesForTest(mod) {
+    return collectResponsesClasses(mod);
+}
+//# sourceMappingURL=openai.js.map

package/dist/esm/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";
@@ -33,12 +34,23 @@ export declare const GEN_AI: {
     readonly RETRIEVAL_QUERY_TEXT: "gen_ai.retrieval.query.text";
     readonly RETRIEVAL_DOCUMENTS: "gen_ai.retrieval.documents";
     readonly MESSAGE_INDEX: "gen_ai.message.index";
+    readonly OUTPUT_TYPE: "gen_ai.output.type";
 };
 export declare const STRUCT: {
     readonly METADATA_PREFIX: "struct.metadata.";
     readonly AGENT_PARENT_SESSION_ID: "struct.agent.parent_session_id";
+    readonly AGENT_THREAD_ID: "struct.agent.thread_id";
     readonly INPUT_MESSAGE_COUNT: "struct.input.message_count";
 };
+export declare const LANGCHAIN: {
+    /**
+     * LangChain's own run-scoped message id (e.g. `run-...` / `lc_run--...`),
+     * recorded only when it diverges from `gen_ai.response.id` (the provider's
+     * `msg_...`/`chatcmpl-...` id, which wins as the canonical fingerprint).
+     * Parity: python `langchain.run.id` (langchain.py:1567-1575).
+     */
+    readonly RUN_ID: "langchain.run.id";
+};
 export declare const EVENT_NAME = "event.name";
 export declare const ERROR_TYPE = "error.type";
 export declare const EVENT_NAMES: {

package/dist/esm/semconv.js

@@ -21,6 +21,7 @@ export const 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",
@@ -33,12 +34,23 @@ export const GEN_AI = {
     RETRIEVAL_QUERY_TEXT: "gen_ai.retrieval.query.text",
     RETRIEVAL_DOCUMENTS: "gen_ai.retrieval.documents",
     MESSAGE_INDEX: "gen_ai.message.index",
+    OUTPUT_TYPE: "gen_ai.output.type",
 };
 export const STRUCT = {
     METADATA_PREFIX: "struct.metadata.",
     AGENT_PARENT_SESSION_ID: "struct.agent.parent_session_id",
+    AGENT_THREAD_ID: "struct.agent.thread_id",
     INPUT_MESSAGE_COUNT: "struct.input.message_count",
 };
+export const LANGCHAIN = {
+    /**
+     * LangChain's own run-scoped message id (e.g. `run-...` / `lc_run--...`),
+     * recorded only when it diverges from `gen_ai.response.id` (the provider's
+     * `msg_...`/`chatcmpl-...` id, which wins as the canonical fingerprint).
+     * Parity: python `langchain.run.id` (langchain.py:1567-1575).
+     */
+    RUN_ID: "langchain.run.id",
+};
 export const EVENT_NAME = "event.name";
 export const ERROR_TYPE = "error.type";
 export const EVENT_NAMES = {

package/dist/esm/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/esm/truncation.js

@@ -43,9 +43,10 @@ export function truncateParts(parts) {
     return result;
 }
 export function truncateAndSerialize(obj, maxSize = 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 };
@@ -57,31 +58,202 @@ export function truncateAndSerialize(obj, maxSize = 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);
+}
 export 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`.
+ */
+export 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 > MAX_FIELD_SIZE) {
+        mutable().description = src.description.slice(0, MAX_FIELD_SIZE) + 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 > 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).
+ */
+export function serializeToolDefinitions(obj) {
+    try {
+        if (!Array.isArray(obj))
+            return truncateAndSerialize(obj);
+        const bounded = obj.map(truncateToolDefinition);
+        const serialized = safeJsonStringify(bounded);
+        if (serialized.length <= 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, 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/esm/version.d.ts

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

package/dist/esm/version.js

@@ -0,0 +1,3 @@
+// Keep in sync with package.json; test/version.test.ts enforces it.
+export const SDK_VERSION = "0.4.2";
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struct-ai/sdk",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry",
   "type": "module",
   "main": "./dist/commonjs/index.js",
@@ -31,7 +31,9 @@
     "typecheck": "tsc --noEmit",
     "lint": "echo 'TODO: eslint not configured for @struct-ai/sdk yet — see investigation'",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:live": "vitest run -c vitest.live.config.ts",
+    "test:parity": "node scripts/parity/run.mjs"
   },
   "keywords": [
     "struct",
@@ -67,7 +69,8 @@
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.30.0",
     "@langchain/core": ">=0.3.0",
-    "@langchain/langgraph": ">=0.2.0"
+    "@langchain/langgraph": ">=0.2.0",
+    "openai": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/sdk": {
@@ -78,6 +81,9 @@
     },
     "@langchain/langgraph": {
       "optional": true
+    },
+    "openai": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -88,6 +94,8 @@
     "@langchain/openai": "^0.5.18",
     "@types/node": "^20.0.0",
     "nock": "^13.5.0",
+    "openai": "^5.23.2",
+    "openai-v6": "npm:openai@^6.0.0",
     "tshy": "^3.0.0",
     "tsx": "^4.21.0",
     "typescript": "^5.5.0",