@struct-ai/sdk 0.3.0 → 0.3.17

package/dist/esm/integrations/anthropic.js

@@ -1,5 +1,5 @@
 import { SpanKind, SpanStatusCode, context as otelContext, trace, } from "@opentelemetry/api";
-import { ensurePendingToolCallsSlot, getAgentSpan, getSessionId, pushPendingToolCalls, runWithStore, snapshotStore, } from "../context.js";
+import { ensurePendingToolCallsSlot, getAgentSpan, getSessionId, isGenAiSuppressed, pushPendingToolCalls, runWithContext, runWithStore, snapshotStore, } from "../context.js";
 function childParentContext() {
     const agentSpan = getAgentSpan();
     return agentSpan
@@ -97,12 +97,16 @@ function restoreMethod(proto, methodName) {
         proto[methodName] = current[STRUCT_ORIGINAL];
     }
 }
-function wrapCreate(original) {
+export function wrapCreate(original) {
     return function wrappedCreate(params, opts) {
         const patchCtx = activePatchCtx.value;
         if (!patchCtx) {
             return original.call(this, params, opts);
         }
+        if (isGenAiSuppressed()) {
+            // A framework layer owns this chat span — run the call, emit no span.
+            return original.call(this, params, opts);
+        }
         // If params.stream is true, Messages.create delegates to the streaming path.
         // We still need to instrument the returned stream like we do in messages.stream.
         if (params && params.stream === true) {
@@ -132,27 +136,87 @@ function wrapCreate(original) {
         // user/system message logs back to the chat span.
         return otelContext.with(liveCtx, () => {
             safe(() => setChatRequestAttrs(liveSpan, params, sdk, logger), "anthropic.create.set_request_attrs", internalLogger);
-            const promise = Promise.resolve(original.call(this, params, opts));
-            return promise.then((result) => {
-                safe(() => setChatResponseAttrs(liveSpan, sdk, result, logger), "anthropic.create.set_response_attrs", internalLogger);
-                safe(() => liveSpan.setStatus({ code: SpanStatusCode.OK }), "anthropic.create.set_ok_status", internalLogger);
-                safe(() => liveSpan.end(), "anthropic.create.span_end", internalLogger);
-                return result;
-            }, (err) => {
+            let rawResult;
+            try {
+                rawResult = original.call(this, params, opts);
+            }
+            catch (err) {
+                // Sync throw from the original call (e.g. a validation error thrown
+                // before any request goes out) would otherwise leak the span — no
+                // promise is ever created to drive the .then/.catch below.
                 safe(() => recordErrorOnSpan(liveSpan, err), "anthropic.create.record_error", internalLogger);
                 safe(() => liveSpan.end(), "anthropic.create.span_end_on_error", internalLogger);
-                // User's API exception always propagates unchanged.
                 throw err;
-            });
+            }
+            // Observe the SDK's own return value (Anthropic's APIPromise) for
+            // telemetry, then hand it BACK UNCHANGED — replacing it with a native
+            // `Promise.resolve(...).then(...)` strips APIPromise methods
+            // (.withResponse/.asResponse), breaking customer code only when
+            // instrumentation is enabled. Our observer chain must not create an
+            // unhandled rejection. (The prior code returned a native Promise here;
+            // this is adjacent hardening of pre-existing behavior — the identity
+            // hazard predates the streaming work.)
+            //
+            // Both the `.then` PROPERTY READ (`rt.then`) and the `.then(...)` CALL
+            // that registers our observer run SYNCHRONOUSLY on the success path of
+            // a customer's `create()` call, and were previously unguarded — a
+            // hostile thenable (a `.then` accessor that throws on read, or a
+            // `.then` function that throws synchronously when invoked) would turn
+            // a SUCCESSFUL Anthropic request into a synchronous exception thrown
+            // out of `wrappedCreate`. Wrap the read + registration so a broken
+            // thenable degrades instead of crashing the host: close the span with
+            // no telemetry and hand back rawResult UNCHANGED — never
+            // `Promise.resolve(...)`, which would also strip APIPromise
+            // identity/methods.
+            try {
+                const rt = rawResult;
+                if (rt && typeof rt.then === "function") {
+                    rawResult.then((result) => {
+                        safe(() => setChatResponseAttrs(liveSpan, sdk, result, logger), "anthropic.create.set_response_attrs", internalLogger);
+                        safe(() => liveSpan.setStatus({ code: SpanStatusCode.OK }), "anthropic.create.set_ok_status", internalLogger);
+                        safe(() => liveSpan.end(), "anthropic.create.span_end", internalLogger);
+                    }, (err) => {
+                        safe(() => recordErrorOnSpan(liveSpan, err), "anthropic.create.record_error", internalLogger);
+                        safe(() => liveSpan.end(), "anthropic.create.span_end_on_error", internalLogger);
+                        // Observer branch only — do NOT rethrow; the original APIPromise
+                        // still rejects to the customer independently.
+                    });
+                    return rawResult;
+                }
+            }
+            catch {
+                // Reading `.then` or invoking it threw (hostile thenable). The
+                // underlying call already succeeded (rawResult exists) — this is an
+                // instrumentation-only failure, not an API error. Degrade like the
+                // other host-crash guards in this file (e.g. wrapStream's dispatch
+                // region below): close the span with no telemetry, hand back
+                // rawResult untouched.
+                safe(() => liveSpan.setStatus({ code: SpanStatusCode.OK }), "anthropic.create.set_ok_status", internalLogger);
+                safe(() => liveSpan.end(), "anthropic.create.span_end", internalLogger);
+                return rawResult;
+            }
+            // Non-thenable return (a synchronous / mocked result, or any SDK shape
+            // that isn't a promise): run the response telemetry inline on it, close
+            // the span, and hand it back untouched — matching the prior
+            // `Promise.resolve(...).then(...)` behavior, which unified thenable and
+            // non-thenable returns.
+            safe(() => setChatResponseAttrs(liveSpan, sdk, rawResult, logger), "anthropic.create.set_response_attrs", internalLogger);
+            safe(() => liveSpan.setStatus({ code: SpanStatusCode.OK }), "anthropic.create.set_ok_status", internalLogger);
+            safe(() => liveSpan.end(), "anthropic.create.span_end", internalLogger);
+            return rawResult;
         });
     };
 }
-function wrapStream(original) {
+export function wrapStream(original) {
     return function wrappedStream(params, opts) {
         const patchCtx = activePatchCtx.value;
         if (!patchCtx) {
             return original.call(this, params, opts);
         }
+        if (isGenAiSuppressed()) {
+            // A framework layer owns this chat span — run the call, emit no span.
+            return original.call(this, params, opts);
+        }
         const { tracer, sdk, logger } = patchCtx;
         const internalLogger = sdk.getInternalLogger();
         const model = params?.model ?? "unknown";
@@ -172,13 +236,6 @@ function wrapStream(original) {
         const liveSpan = span;
         const liveCtx = ctx;
         const storeSnapshot = snapshotStore();
-        // Enter the span's context BEFORE request-side log emission so logs
-        // link back to the chat span via TraceId. Same rationale as wrapCreate.
-        // @anthropic-ai/sdk's `stream()` returns a MessageStream synchronously.
-        const stream = otelContext.with(liveCtx, () => {
-            safe(() => setChatRequestAttrs(liveSpan, params, sdk, logger), "anthropic.stream.set_request_attrs", internalLogger);
-            return original.call(this, params, opts);
-        });
         let finalized = false;
         const finalize = (result, err) => {
             if (finalized)
@@ -198,43 +255,407 @@ function wrapStream(original) {
                 safe(() => liveSpan.end(), "anthropic.stream.span_end", internalLogger);
             });
         };
-        const ee = stream;
-        if (ee && typeof ee.on === "function") {
-            ee.on("finalMessage", (msg) => {
-                finalize(msg, undefined);
-            });
-            ee.on("error", (err) => {
-                finalize(undefined, err);
+        // Enter the span's context BEFORE request-side log emission so logs
+        // link back to the chat span via TraceId. Same rationale as wrapCreate.
+        // @anthropic-ai/sdk's `stream()` returns a MessageStream synchronously,
+        // but `messages.create({stream:true})` (delegated here from wrapCreate)
+        // returns an APIPromise-like thenable resolving to a raw event Stream —
+        // both shapes are handled below.
+        //
+        // Suppress nested instrumentation: the real `Messages.prototype.stream()`
+        // (`original` here) internally calls `MessageStream.createMessage`, whose
+        // executor synchronously invokes `messages.create({ ...params, stream:
+        // true }, ...)` — on the SAME patched `Messages` prototype — before its
+        // first `await` yields control. That resolves to our `wrapCreate`
+        // wrapper, which would otherwise see `params.stream === true` and
+        // re-delegate to a brand-new `wrapStream(original)`, instrumenting the
+        // same underlying raw stream a second time (2 chat spans, same
+        // gen_ai.response.id). `runWithContext({ suppressGenAi: true }, ...)`
+        // scopes an ALS store patch around exactly this synchronous call (plus
+        // any promise chain it kicks off internally, since AsyncLocalStorage
+        // propagates into `.then` continuations created within the `run()`
+        // callback) — `wrapCreate` checks `isGenAiSuppressed()` before its
+        // `stream === true` branch and, when suppressed, falls through to
+        // calling the TRUE raw `create` directly (no span, no re-wrap). This
+        // must NOT leak into user code: the store patch is popped the instant
+        // `original.call(...)` returns (it returns the MessageStream
+        // synchronously), so by the time control returns to the caller of
+        // `.stream()`, suppression is already off again — user code that later
+        // iterates the stream, or that itself calls `messages.create`/`.stream`,
+        // runs with a clean (unsuppressed) ALS store.
+        let stream;
+        try {
+            stream = otelContext.with(liveCtx, () => {
+                safe(() => setChatRequestAttrs(liveSpan, params, sdk, logger), "anthropic.stream.set_request_attrs", internalLogger);
+                return runWithContext({ suppressGenAi: true }, () => original.call(this, params, opts));
             });
-            // If the stream is created and never iterated / finalized, at least
-            // don't hang on test exit — "end" fires after iteration completes.
-            ee.on("end", () => {
-                // Only fires if no finalMessage / error fired first (rare path).
+        }
+        catch (err) {
+            // Sync throw from the original call would otherwise leak the span —
+            // no stream/promise is ever produced to drive finalize() below.
+            finalize(undefined, err);
+            throw err;
+        }
+        // The entire branch-dispatch region below — reading `ee.on`/`.then`/
+        // `Symbol.asyncIterator`, registering `.on(...)` listeners, invoking
+        // `.then(...)`, and calling `instrumentSyncIterable` — runs SYNCHRONOUSLY
+        // on the success path of the customer's `.stream()`/`.create()` call, and
+        // was previously unguarded (round-4 only hardened the ASYNC observer
+        // callbacks registered inside it, e.g. the onFulfilled/onRejected
+        // handlers below). A hostile/broken stream-like object — a throwing
+        // `.on`/`.then`/`Symbol.asyncIterator` getter, or a `.on()` registration
+        // call that itself throws — would throw synchronously OUT of the
+        // customer's call. Wrap the whole dispatch in try/catch so a successful
+        // request never becomes a hard failure purely because OUR observer
+        // wiring couldn't attach: degrade to no telemetry and hand back the
+        // ORIGINAL stream object unchanged.
+        try {
+            const ee = stream;
+            // Emitter path wins first — a real MessageStream (`.on`) is never
+            // thenable, but check `.on` before `.then` defensively in case some
+            // future stream shape exposes both.
+            if (ee && typeof ee.on === "function") {
+                ee.on("finalMessage", (msg) => {
+                    finalize(msg, undefined);
+                });
+                ee.on("error", (err) => {
+                    finalize(undefined, err);
+                });
+                // Abort fires before "end" on an aborted stream — without this
+                // listener the "end" handler below finalizes with OK status even
+                // though the request was aborted. `finalized` makes the subsequent
+                // "end" a no-op.
+                ee.on("abort", (err) => {
+                    finalize(undefined, err ?? new Error("aborted"));
+                });
+                // If the stream is created and never iterated / finalized, at least
+                // don't hang on test exit — "end" fires after iteration completes.
+                ee.on("end", () => {
+                    // Only fires if no finalMessage / error / abort fired first (rare
+                    // path for a healthy, fully-drained stream).
+                    finalize(undefined, undefined);
+                });
+            }
+            else if (ee && typeof ee.then === "function") {
+                // `create({stream:true})` shape: an APIPromise-like thenable that
+                // resolves to a raw event Stream (no `.on`, no synchronous
+                // asyncIterator until resolved). Observe the resolution to instrument
+                // the resolved Stream BY MUTATION, but return the ORIGINAL thenable —
+                // Anthropic's APIPromise exposes methods like `.withResponse()` /
+                // `.asResponse()` that a native `Promise.resolve(...).then(...)` would
+                // strip, breaking customer code only when instrumentation is enabled.
+                // Our observer registers synchronously here, before the caller can
+                // await, so instrumentRawStream mutates the same resolved object the
+                // caller receives, before they iterate it.
+                const thenable = stream;
+                const observerChain = thenable.then((raw) => {
+                    // instrumentRawStream can itself throw at points outside its OWN
+                    // internal try/catch (e.g. a hostile `Symbol.asyncIterator`
+                    // getter, read before that internal guard) — this must not
+                    // escape THIS onFulfilled callback: an uncaught throw here
+                    // becomes an unhandled rejection on the promise `.then()`
+                    // returns, even though the customer's original APIPromise
+                    // resolved successfully — a successful request must never crash
+                    // the host. Degrade: end the span with no telemetry and swallow.
+                    try {
+                        instrumentRawStream(raw);
+                    }
+                    catch {
+                        finalize(undefined, undefined);
+                    }
+                }, (err) => {
+                    // Observe the rejection to finalize the span, but do NOT rethrow:
+                    // this observer branch must never surface as an unhandled
+                    // rejection. The original thenable still rejects to the caller
+                    // independently.
+                    finalize(undefined, err);
+                });
+                // Belt-and-suspenders: both branches above are already guarded to
+                // never throw/reject, so this derived promise should never reject —
+                // but chain a no-op `.catch` anyway so this internal observer chain
+                // can NEVER become an unhandled-rejection source, even under future
+                // edits to the branches above.
+                observerChain.catch?.(() => { });
+                return stream;
+            }
+            else if (ee && typeof ee[Symbol.asyncIterator] === "function") {
+                // Wrap the async iterator so each .next() runs inside the captured
+                // ALS store.
+                instrumentSyncIterable(ee);
+            }
+            return stream;
+        }
+        catch {
+            finalize(undefined, undefined);
+            return stream;
+        }
+        function instrumentRawStream(raw) {
+            const it = raw;
+            if (!it || typeof it[Symbol.asyncIterator] !== "function") {
+                finalize(undefined, undefined); // not iterable — end the span rather than leak it
+                return raw;
+            }
+            // A raw stream that is awaited but never iterated would otherwise leak
+            // its span — finalize() only fires through the iterator hooks below.
+            // Anthropic's Stream carries an AbortController; close the span if the
+            // request is aborted before/without iteration. Residual (documented,
+            // accepted): a stream awaited, never iterated, AND never aborted stays
+            // open until process exit — no lifecycle signal exists to close it.
+            //
+            // This whole section reads a `controller` getter and calls
+            // `addEventListener` on whatever object the SDK (or a hostile/broken
+            // caller-supplied stand-in) hands us — both are fallible and, unlike
+            // the `Symbol.asyncIterator` assignment below, were previously
+            // unguarded. Wrap it so a throwing getter degrades to "no abort-driven
+            // finalize wiring" rather than aborting instrumentRawStream entirely
+            // (which would also skip the Symbol.asyncIterator instrumentation
+            // below and lose the whole stream's telemetry, not just the abort
+            // hook). The caller (the observer's onFulfilled, or the synchronous
+            // `.on()`/asyncIterator paths in wrapStream) also guards its own call
+            // to instrumentRawStream, so this is defense-in-depth, not the only
+            // guard.
+            try {
+                const ctrl = raw.controller;
+                const sig = ctrl?.signal;
+                if (sig) {
+                    if (sig.aborted) {
+                        finalize(undefined, sig.reason ?? new Error("aborted"));
+                    }
+                    else {
+                        sig.addEventListener("abort", () => finalize(undefined, sig.reason ?? new Error("aborted")), { once: true });
+                    }
+                }
+            }
+            catch {
+                // Swallow — no abort-driven finalize wiring for this stream, but
+                // fall through to installing the Symbol.asyncIterator override
+                // below so normal iteration still drives accumulate()/finalize().
+            }
+            const acc = {};
+            const originalIter = it[Symbol.asyncIterator].bind(it);
+            try {
+                it[Symbol.asyncIterator] = () => {
+                    const inner = originalIter();
+                    return {
+                        next: () => runWithStore(storeSnapshot, () => inner.next().then((res) => {
+                            // accumulate()/accToResponseMessage() inspect provider-owned
+                            // values (a proxy getter can throw; accToResponseMessage
+                            // JSON.parses input_json_delta, which may be malformed). A
+                            // successfully yielded item must NEVER become a rejected
+                            // next(): on any instrumentation failure, degrade telemetry
+                            // (finalize with no result) and return the original res.
+                            try {
+                                if (!res.done)
+                                    accumulate(acc, res.value);
+                                else
+                                    finalize(accToResponseMessage(acc), undefined);
+                            }
+                            catch {
+                                finalize(undefined, undefined);
+                            }
+                            return res;
+                        }, (err) => {
+                            finalize(undefined, err);
+                            throw err;
+                        })),
+                        return: (v) => runWithStore(storeSnapshot, () => {
+                            // Settle the inner iterator's cleanup BEFORE finalizing, so a
+                            // cleanup rejection is recorded as ERROR rather than the span
+                            // being closed OK while the caller receives a rejection.
+                            const ret = inner.return
+                                ? inner.return(v)
+                                : Promise.resolve({ value: v, done: true });
+                            return Promise.resolve(ret).then((res) => {
+                                finalize(accToResponseMessage(acc), undefined); // early break — close OK
+                                return res;
+                            }, (err) => {
+                                finalize(undefined, err); // cleanup rejected — record ERROR
+                                throw err; // propagate the original rejection unchanged
+                            });
+                        }),
+                        throw: (e) => runWithStore(storeSnapshot, () => {
+                            // The thrown value IS the error condition, so finalize ERROR
+                            // with it regardless of the inner iterator's cleanup outcome.
+                            finalize(undefined, e);
+                            return inner.throw ? inner.throw(e) : Promise.reject(e);
+                        }),
+                    };
+                };
+            }
+            catch {
+                // The resolved stream object is frozen/sealed or the property is
+                // non-writable — assigning Symbol.asyncIterator threw. A successful
+                // request must never become a rejected promise because OUR
+                // instrumentation couldn't attach; degrade gracefully (end the span
+                // with no telemetry) and hand back the untouched object. No Proxy
+                // fallback — that would change the stream's identity, which is its
+                // own hazard.
                 finalize(undefined, undefined);
-            });
+            }
+            return raw;
         }
-        // Wrap the async iterator so each .next() runs inside the captured ALS store.
-        if (ee && typeof ee[Symbol.asyncIterator] === "function") {
-            const originalIter = ee[Symbol.asyncIterator].bind(ee);
-            ee[Symbol.asyncIterator] = () => {
-                const inner = originalIter();
-                const wrapped = {
-                    next() {
-                        return runWithStore(storeSnapshot, () => inner.next());
-                    },
-                    return(value) {
-                        return runWithStore(storeSnapshot, () => inner.return ? inner.return(value) : Promise.resolve({ value, done: true }));
-                    },
-                    throw(err) {
-                        return runWithStore(storeSnapshot, () => inner.throw
-                            ? inner.throw(err)
-                            : Promise.reject(err));
-                    },
+        function instrumentSyncIterable(target) {
+            const originalIter = target[Symbol.asyncIterator].bind(target);
+            try {
+                target[Symbol.asyncIterator] = () => {
+                    const inner = originalIter();
+                    const wrapped = {
+                        next() {
+                            return runWithStore(storeSnapshot, () => inner.next());
+                        },
+                        return(value) {
+                            return runWithStore(storeSnapshot, () => inner.return
+                                ? inner.return(value)
+                                : Promise.resolve({ value, done: true }));
+                        },
+                        throw(err) {
+                            return runWithStore(storeSnapshot, () => inner.throw ? inner.throw(err) : Promise.reject(err));
+                        },
+                    };
+                    return wrapped;
                 };
-                return wrapped;
+            }
+            catch {
+                // Same hazard class as instrumentRawStream above: the target is
+                // frozen/sealed or the property is non-writable. This call happens
+                // synchronously inside wrapStream itself (not inside a promise
+                // callback), so an uncaught throw here would surface as a
+                // SYNCHRONOUS exception out of the user's `.stream()`/`.create()`
+                // call — turning a successful request into a hard failure. Degrade
+                // gracefully instead: end the span with no telemetry and leave the
+                // iterable completely untouched (the failed assignment never took
+                // effect).
+                finalize(undefined, undefined);
+            }
+        }
+        function accumulate(acc, ev) {
+            const e = ev;
+            if (e?.type === "message_start" && e.message) {
+                acc.id = e.message.id;
+                acc.model = e.message.model;
+                acc.inputTokens = e.message.usage?.input_tokens;
+                // Cached `create({stream:true})` requests carry cache token counts
+                // on message_start's usage (never on message_delta's) — without
+                // these, the synthesized ResponseMessage under-reports input usage
+                // (setChatResponseAttrs adds them into the total) and omits both
+                // cache attributes entirely, unlike the non-streaming and
+                // MessageStream (`.on("finalMessage")`) paths, which pass the SDK's
+                // own parsed usage straight through.
+                acc.cacheReadTokens = e.message.usage?.cache_read_input_tokens;
+                acc.cacheCreationTokens = e.message.usage?.cache_creation_input_tokens;
+            }
+            else if (e?.type === "content_block_start" && typeof e.index === "number") {
+                // Assemble content blocks so the synthesized response carries
+                // `content` — without it, setChatResponseAttrs's `if (response.content)`
+                // block never runs on this raw-stream path, dropping
+                // gen_ai.output.messages, the gen_ai.choice event, and (critically)
+                // recordPendingToolCalls, so a streamed tool_use never links to its
+                // execute_tool span. Mirrors MessageStream's finalMessage assembly,
+                // minimally: text blocks and tool_use blocks only.
+                const blocks = (acc.blocks ??= {});
+                const cb = e.content_block;
+                if (cb?.type === "tool_use") {
+                    blocks[e.index] = {
+                        type: "tool_use",
+                        id: cb.id,
+                        name: cb.name,
+                        jsonBuf: "",
+                    };
+                }
+                else if (cb?.type === "text") {
+                    blocks[e.index] = { type: "text", text: cb.text ?? "" };
+                }
+                else if (cb?.type) {
+                    blocks[e.index] = { type: cb.type };
+                }
+            }
+            else if (e?.type === "content_block_delta" && typeof e.index === "number") {
+                const blocks = (acc.blocks ??= {});
+                const b = blocks[e.index];
+                if (!b)
+                    return;
+                if (e.delta?.type === "text_delta" && typeof e.delta.text === "string") {
+                    b.text = (b.text ?? "") + e.delta.text;
+                }
+                else if (e.delta?.type === "input_json_delta" &&
+                    typeof e.delta.partial_json === "string") {
+                    b.jsonBuf = (b.jsonBuf ?? "") + e.delta.partial_json;
+                }
+            }
+            else if (e?.type === "content_block_stop" && typeof e.index === "number") {
+                const blocks = (acc.blocks ??= {});
+                const b = blocks[e.index];
+                if (b?.type === "tool_use") {
+                    // Parse the accumulated partial_json into the tool_use input; fall
+                    // back to the raw string if the model streamed malformed JSON (the
+                    // block still links via id/name, which is what tool-call linkage
+                    // needs).
+                    try {
+                        b.input = b.jsonBuf ? JSON.parse(b.jsonBuf) : {};
+                    }
+                    catch {
+                        b.input = b.jsonBuf;
+                    }
+                }
+            }
+            else if (e?.type === "message_delta") {
+                if (e.delta?.stop_reason)
+                    acc.stopReason = e.delta.stop_reason;
+                if (e.usage?.output_tokens !== undefined) {
+                    acc.outputTokens = e.usage.output_tokens;
+                }
+            }
+        }
+        // NOTE (parity, intentional divergence — self-audit round 5, item G):
+        // this synthesizes a FULL ResponseMessage (content, usage, stop_reason,
+        // id, model) from the raw SSE event stream, matching what the
+        // non-streaming `create()` path and `MessageStream`'s `finalMessage`
+        // event already carry. struct-sdk-python's `create(stream=True)` raw
+        // path does NOT do this reconstruction yet and emits none of these
+        // response-side attributes for that one call shape. This is TS being
+        // MORE complete than Python here, not a TS bug — do not remove it to
+        // "match" Python. Bringing Python's raw-stream path up to parity is a
+        // separate, independent follow-up.
+        function accToResponseMessage(acc) {
+            const blocks = acc.blocks;
+            if (acc.id === undefined && acc.inputTokens === undefined && !blocks) {
+                return undefined;
+            }
+            // Rebuild content in ascending block index, shaped like the SDK's own
+            // parsed message content so setChatResponseAttrs / iterToolUses read it
+            // identically to the non-streaming path.
+            let content;
+            if (blocks) {
+                content = Object.keys(blocks)
+                    .map((k) => Number(k))
+                    .sort((a, b) => a - b)
+                    .map((i) => {
+                    const b = blocks[i];
+                    if (b.type === "tool_use") {
+                        return { type: "tool_use", id: b.id, name: b.name, input: b.input ?? {} };
+                    }
+                    if (b.type === "text") {
+                        return { type: "text", text: b.text ?? "" };
+                    }
+                    return { type: b.type };
+                });
+            }
+            return {
+                id: acc.id,
+                model: acc.model,
+                stop_reason: acc.stopReason,
+                content: content,
+                usage: {
+                    input_tokens: acc.inputTokens,
+                    output_tokens: acc.outputTokens,
+                    // Raw fields only — setChatResponseAttrs remains the single place
+                    // that adds these into the reported total, matching the
+                    // non-streaming/MessageStream contract exactly.
+                    cache_read_input_tokens: acc.cacheReadTokens,
+                    cache_creation_input_tokens: acc.cacheCreationTokens,
+                },
             };
         }
-        return stream;
     };
 }
 function setChatRequestAttrs(span, params, sdk, logger) {