@verevoir/review 0.3.0 → 0.3.2

package/node_modules/@anthropic-ai/sdk/src/lib/BetaMessageStream.ts

@@ -0,0 +1,874 @@
+import { STAINLESS_HELPER_METHOD_HEADER } from '../internal/stainless-helper-header';
+import type { BaseAnthropic, Logger } from '../client';
+import { AnthropicError, APIUserAbortError } from '../error';
+import { isAbortError } from '../internal/errors';
+import { checkNever } from '../internal/utils/values';
+import { type RequestOptions } from '../internal/request-options';
+import {
+  type BetaContentBlock,
+  type BetaMCPToolUseBlock,
+  type BetaMessage,
+  type BetaMessageParam,
+  Messages as BetaMessages,
+  type BetaRawMessageStreamEvent as BetaMessageStreamEvent,
+  type BetaServerToolUseBlock,
+  type BetaTextBlock,
+  type BetaTextCitation,
+  type BetaToolUseBlock,
+  type MessageCreateParams,
+  type MessageCreateParamsBase,
+  MessageCreateParamsStreaming,
+} from '../resources/beta/messages/messages';
+import { Stream } from '../streaming';
+import { maybeParseBetaMessage, type ParsedBetaMessage } from './beta-parser';
+import { startMessagesStreamSpan } from './internal/beta-messages-request';
+import { recordStreamedMessageContent } from './internal/tracing';
+import type { MessagesCreateSpan } from './internal/tracing/types';
+import { JSON_BUF_PROPERTY, withLazyInput } from '../internal/message-stream-utils';
+
+export interface MessageStreamEvents {
+  connect: () => void;
+  /** @internal Every stream event. `streamEvent` needs a snapshot, so it starts at `message_start`. */
+  _rawEvent: (event: BetaMessageStreamEvent) => void;
+  streamEvent: (event: BetaMessageStreamEvent, snapshot: BetaMessage) => void;
+  text: (textDelta: string, textSnapshot: string) => void;
+  citation: (citation: BetaTextCitation, citationsSnapshot: BetaTextCitation[]) => void;
+  inputJson: (partialJson: string, jsonSnapshot: unknown) => void;
+  thinking: (thinkingDelta: string, thinkingSnapshot: string) => void;
+  signature: (signature: string) => void;
+  compaction: (compactedContent: string) => void;
+  message: (message: BetaMessage) => void;
+  contentBlock: (content: BetaContentBlock) => void;
+  finalMessage: (message: BetaMessage) => void;
+  error: (error: AnthropicError) => void;
+  abort: (error: APIUserAbortError) => void;
+  end: () => void;
+}
+
+type MessageStreamEventListeners<Event extends keyof MessageStreamEvents> = {
+  listener: MessageStreamEvents[Event];
+  once?: boolean;
+}[];
+
+export type TracksToolInput = BetaToolUseBlock | BetaServerToolUseBlock | BetaMCPToolUseBlock;
+
+function tracksToolInput(content: BetaContentBlock): content is TracksToolInput {
+  return content.type === 'tool_use' || content.type === 'server_tool_use' || content.type === 'mcp_tool_use';
+}
+
+export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMessageStreamEvent> {
+  messages: BetaMessageParam[] = [];
+  receivedMessages: ParsedBetaMessage<ParsedT>[] = [];
+  #currentMessageSnapshot: BetaMessage | undefined;
+  #params: MessageCreateParams | null = null;
+
+  controller: AbortController = new AbortController();
+
+  #connectedPromise: Promise<Response | null>;
+  #resolveConnectedPromise: (response: Response | null) => void = () => {};
+  #rejectConnectedPromise: (error: AnthropicError) => void = () => {};
+
+  #endPromise: Promise<void>;
+  #resolveEndPromise: () => void = () => {};
+  #rejectEndPromise: (error: AnthropicError) => void = () => {};
+
+  #listeners: { [Event in keyof MessageStreamEvents]?: MessageStreamEventListeners<Event> } = {};
+
+  #ended = false;
+  #errored = false;
+  #aborted = false;
+  #catchingPromiseCreated = false;
+  #response: Response | null | undefined;
+  #request_id: string | null | undefined;
+  #workspace_id: string | null | undefined;
+  #logger: Logger;
+  // The client that makes the request, and the call span of the request, to record the message on.
+  // Both are set only for a stream that an SDK method created.
+  #client: BaseAnthropic | undefined;
+  #span: MessagesCreateSpan | undefined;
+
+  constructor(
+    params: MessageCreateParamsBase | null,
+    opts?: {
+      logger?: Logger | undefined;
+      /** The client that makes the request, for the stream to start its span and record the message on it. */
+      client?: BaseAnthropic | undefined;
+    },
+  ) {
+    this.#connectedPromise = new Promise<Response | null>((resolve, reject) => {
+      this.#resolveConnectedPromise = resolve;
+      this.#rejectConnectedPromise = reject;
+    });
+
+    this.#endPromise = new Promise<void>((resolve, reject) => {
+      this.#resolveEndPromise = resolve;
+      this.#rejectEndPromise = reject;
+    });
+
+    // Don't let these promises cause unhandled rejection errors.
+    // we will manually cause an unhandled rejection error later
+    // if the user hasn't registered any error listener or called
+    // any promise-returning method.
+    this.#connectedPromise.catch(() => {});
+    this.#endPromise.catch(() => {});
+
+    this.#params = params;
+    this.#logger = opts?.logger ?? console;
+    this.#client = opts?.client;
+  }
+
+  get response(): Response | null | undefined {
+    return this.#response;
+  }
+
+  get request_id(): string | null | undefined {
+    return this.#request_id;
+  }
+
+  get workspace_id(): string | null | undefined {
+    return this.#workspace_id;
+  }
+
+  /**
+   * Returns the `MessageStream` data, the raw `Response` instance and the ID of the request,
+   * returned vie the `request-id` header which is useful for debugging requests and resporting
+   * issues to Anthropic.
+   *
+   * This is the same as the `APIPromise.withResponse()` method.
+   *
+   * This method will raise an error if you created the stream using `MessageStream.fromReadableStream`
+   * as no `Response` is available.
+   */
+  async withResponse(): Promise<{
+    data: BetaMessageStream<ParsedT>;
+    response: Response;
+    request_id: string | null | undefined;
+    workspace_id: string | null | undefined;
+  }> {
+    this.#catchingPromiseCreated = true;
+
+    const response = await this.#connectedPromise;
+    if (!response) {
+      throw new Error('Could not resolve a `Response` object');
+    }
+
+    return {
+      data: this,
+      response,
+      request_id: response.headers.get('request-id'),
+      workspace_id: response.headers.get('anthropic-workspace-id'),
+    };
+  }
+
+  /**
+   * Intended for use on the frontend, consuming a stream produced with
+   * `.toReadableStream()` on the backend.
+   *
+   * Note that messages sent to the model do not appear in `.on('message')`
+   * in this context.
+   */
+  static fromReadableStream(stream: ReadableStream): BetaMessageStream {
+    const runner = new BetaMessageStream(null);
+    runner._run(() => runner._fromReadableStream(stream));
+    return runner;
+  }
+
+  static createMessage<ParsedT>(
+    messages: BetaMessages,
+    params: MessageCreateParamsBase,
+    options?: RequestOptions,
+    {
+      logger,
+      client,
+    }: {
+      logger?: Logger | undefined;
+      /** The client that makes the request, for the stream to start its span and record the message on it. */
+      client?: BaseAnthropic | undefined;
+    } = {},
+  ): BetaMessageStream<ParsedT> {
+    const runner = new BetaMessageStream<ParsedT>(params as MessageCreateParamsStreaming, {
+      logger,
+      client,
+    });
+    for (const message of params.messages) {
+      runner._addMessageParam(message);
+    }
+    runner.#params = { ...params, stream: true };
+    runner._run(() =>
+      runner._createMessage(
+        messages,
+        { ...params, stream: true },
+        { ...options, headers: { ...options?.headers, [STAINLESS_HELPER_METHOD_HEADER]: 'stream' } },
+      ),
+    );
+    return runner;
+  }
+
+  protected _run(executor: () => Promise<any>) {
+    executor().then(() => {
+      this._emitFinal();
+      this._emit('end');
+    }, this.#handleError);
+  }
+
+  protected _addMessageParam(message: BetaMessageParam) {
+    this.messages.push(message);
+  }
+
+  protected _addMessage(message: ParsedBetaMessage<ParsedT>, emit = true) {
+    this.receivedMessages.push(message);
+    if (emit) {
+      this._emit('message', message);
+    }
+  }
+
+  protected async _createMessage(
+    messages: BetaMessages,
+    params: MessageCreateParams,
+    options?: RequestOptions,
+  ): Promise<void> {
+    const signal = options?.signal;
+    let abortHandler: (() => void) | undefined;
+    if (signal) {
+      if (signal.aborted) this.controller.abort();
+      abortHandler = this.controller.abort.bind(this.controller);
+      signal.addEventListener('abort', abortHandler);
+    }
+    try {
+      this.#beginRequest();
+      // Started here, where a throw fails the stream, and kept to record the final message on.
+      // `create()` below gets it in its options, so it uses this span instead of starting its own.
+      this.#span =
+        options?.__span ?? (this.#client && startMessagesStreamSpan(this.#client, params, options));
+      const { response, data: stream } = await messages
+        .create(
+          { ...params, stream: true },
+          { ...options, __span: this.#span, signal: this.controller.signal },
+        )
+        .withResponse();
+      try {
+        this._connected(response);
+      } catch (error) {
+        // Nothing reads the stream after a `connect` listener throws: closing it ends its span.
+        if (this.#span) {
+          this.#span.failure = error;
+        }
+        stream.controller.abort();
+        throw error;
+      }
+      for await (const event of stream) {
+        try {
+          this.#addStreamEvent(event);
+        } catch (error) {
+          if (this.#span) {
+            this.#span.failure = error;
+          }
+          throw error;
+        }
+      }
+      if (stream.controller.signal?.aborted) {
+        throw new APIUserAbortError();
+      }
+      this.#endRequest();
+    } finally {
+      if (signal && abortHandler) {
+        signal.removeEventListener('abort', abortHandler);
+      }
+    }
+  }
+
+  protected _connected(response: Response | null) {
+    if (this.ended) return;
+    this.#response = response;
+    this.#request_id = response?.headers.get('request-id');
+    this.#workspace_id = response?.headers.get('anthropic-workspace-id');
+    this.#resolveConnectedPromise(response);
+    this._emit('connect');
+  }
+
+  get ended(): boolean {
+    return this.#ended;
+  }
+
+  get errored(): boolean {
+    return this.#errored;
+  }
+
+  get aborted(): boolean {
+    return this.#aborted;
+  }
+
+  abort() {
+    this.controller.abort();
+  }
+
+  /**
+   * Adds the listener function to the end of the listeners array for the event.
+   * No checks are made to see if the listener has already been added. Multiple calls passing
+   * the same combination of event and listener will result in the listener being added, and
+   * called, multiple times.
+   * @returns this MessageStream, so that calls can be chained
+   */
+  on<Event extends keyof MessageStreamEvents>(event: Event, listener: MessageStreamEvents[Event]): this {
+    const listeners: MessageStreamEventListeners<Event> =
+      this.#listeners[event] || (this.#listeners[event] = []);
+    listeners.push({ listener });
+    return this;
+  }
+
+  /**
+   * Removes the specified listener from the listener array for the event.
+   * off() will remove, at most, one instance of a listener from the listener array. If any single
+   * listener has been added multiple times to the listener array for the specified event, then
+   * off() must be called multiple times to remove each instance.
+   * @returns this MessageStream, so that calls can be chained
+   */
+  off<Event extends keyof MessageStreamEvents>(event: Event, listener: MessageStreamEvents[Event]): this {
+    const listeners = this.#listeners[event];
+    if (!listeners) return this;
+    const index = listeners.findIndex((l) => l.listener === listener);
+    if (index >= 0) listeners.splice(index, 1);
+    return this;
+  }
+
+  /**
+   * Adds a one-time listener function for the event. The next time the event is triggered,
+   * this listener is removed and then invoked.
+   * @returns this MessageStream, so that calls can be chained
+   */
+  once<Event extends keyof MessageStreamEvents>(event: Event, listener: MessageStreamEvents[Event]): this {
+    const listeners: MessageStreamEventListeners<Event> =
+      this.#listeners[event] || (this.#listeners[event] = []);
+    listeners.push({ listener, once: true });
+    return this;
+  }
+
+  /**
+   * This is similar to `.once()`, but returns a Promise that resolves the next time
+   * the event is triggered, instead of calling a listener callback.
+   * @returns a Promise that resolves the next time given event is triggered,
+   * or rejects if an error is emitted.  (If you request the 'error' event,
+   * returns a promise that resolves with the error).
+   *
+   * Example:
+   *
+   *   const message = await stream.emitted('message') // rejects if the stream errors
+   */
+  emitted<Event extends keyof MessageStreamEvents>(
+    event: Event,
+  ): Promise<
+    Parameters<MessageStreamEvents[Event]> extends [infer Param] ? Param
+    : Parameters<MessageStreamEvents[Event]> extends [] ? void
+    : Parameters<MessageStreamEvents[Event]>
+  > {
+    return new Promise((resolve, reject) => {
+      this.#catchingPromiseCreated = true;
+      if (event !== 'error') this.once('error', reject);
+      this.once(event, resolve as any);
+    });
+  }
+
+  async done(): Promise<void> {
+    this.#catchingPromiseCreated = true;
+    await this.#endPromise;
+  }
+
+  get currentMessage(): BetaMessage | undefined {
+    return this.#currentMessageSnapshot;
+  }
+
+  #getFinalMessage(): ParsedBetaMessage<ParsedT> {
+    if (this.receivedMessages.length === 0) {
+      throw new AnthropicError('stream ended without producing a Message with role=assistant');
+    }
+    return this.receivedMessages.at(-1)!;
+  }
+
+  /**
+   * @returns a promise that resolves with the the final assistant Message response,
+   * or rejects if an error occurred or the stream ended prematurely without producing a Message.
+   * If structured outputs were used, this will be a ParsedMessage with a `parsed` field.
+   */
+  async finalMessage(): Promise<ParsedBetaMessage<ParsedT>> {
+    await this.done();
+    return this.#getFinalMessage();
+  }
+
+  #getFinalText(): string {
+    if (this.receivedMessages.length === 0) {
+      throw new AnthropicError('stream ended without producing a Message with role=assistant');
+    }
+    const textBlocks = this.receivedMessages
+      .at(-1)!
+      .content.filter((block): block is BetaTextBlock => block.type === 'text')
+      .map((block) => block.text);
+    if (textBlocks.length === 0) {
+      throw new AnthropicError('stream ended without producing a content block with type=text');
+    }
+    return textBlocks.join(' ');
+  }
+
+  /**
+   * @returns a promise that resolves with the the final assistant Message's text response, concatenated
+   * together if there are more than one text blocks.
+   * Rejects if an error occurred or the stream ended prematurely without producing a Message.
+   */
+  async finalText(): Promise<string> {
+    await this.done();
+    return this.#getFinalText();
+  }
+
+  #handleError = (error: unknown) => {
+    this.#errored = true;
+    // The stream ignores the events after an error, so its message stops being what the API sent.
+    if (this.#span) {
+      this.#span.streamed = undefined;
+    }
+    if (isAbortError(error)) {
+      error = new APIUserAbortError();
+    }
+    if (error instanceof APIUserAbortError) {
+      this.#aborted = true;
+      return this._emit('abort', error);
+    }
+    if (error instanceof AnthropicError) {
+      return this._emit('error', error);
+    }
+    if (error instanceof Error) {
+      const anthropicError: AnthropicError = new AnthropicError(error.message);
+      // @ts-ignore
+      anthropicError.cause = error;
+      return this._emit('error', anthropicError);
+    }
+    return this._emit('error', new AnthropicError(String(error)));
+  };
+
+  protected _emit<Event extends keyof MessageStreamEvents>(
+    event: Event,
+    ...args: Parameters<MessageStreamEvents[Event]>
+  ) {
+    // make sure we don't emit any MessageStreamEvents after end
+    if (this.#ended) return;
+
+    if (event === 'end') {
+      this.#ended = true;
+      this.#resolveEndPromise();
+    }
+
+    const listeners: MessageStreamEventListeners<Event> | undefined = this.#listeners[event];
+    if (listeners) {
+      this.#listeners[event] = listeners.filter((l) => !l.once) as any;
+      listeners.forEach(({ listener }: any) => listener(...args));
+    }
+
+    if (event === 'abort') {
+      const error = args[0] as APIUserAbortError;
+      if (!this.#catchingPromiseCreated && !listeners?.length) {
+        Promise.reject(error);
+      }
+      this.#rejectConnectedPromise(error);
+      this.#rejectEndPromise(error);
+      this._emit('end');
+      return;
+    }
+
+    if (event === 'error') {
+      // NOTE: _emit('error', error) should only be called from #handleError().
+
+      const error = args[0] as AnthropicError;
+      if (!this.#catchingPromiseCreated && !listeners?.length) {
+        // Trigger an unhandled rejection if the user hasn't registered any error handlers.
+        // If you are seeing stack traces here, make sure to handle errors via either:
+        // - runner.on('error', () => ...)
+        // - await runner.done()
+        // - await runner.final...()
+        // - etc.
+        Promise.reject(error);
+      }
+      this.#rejectConnectedPromise(error);
+      this.#rejectEndPromise(error);
+      this._emit('end');
+    }
+  }
+
+  protected _emitFinal() {
+    const finalMessage = this.receivedMessages.at(-1);
+    if (finalMessage) {
+      this._emit('finalMessage', this.#getFinalMessage());
+    }
+  }
+
+  #beginRequest() {
+    if (this.ended) return;
+    this.#currentMessageSnapshot = undefined;
+  }
+  /** @internal A method so that the tool runner's stream can act before and after an event's listeners. */
+  protected _deliverEvent(event: BetaMessageStreamEvent, snapshot: BetaMessage | undefined) {
+    this._emit('_rawEvent', event);
+    if (snapshot) this._emit('streamEvent', event, snapshot);
+  }
+  #addStreamEvent(event: BetaMessageStreamEvent) {
+    if (this.ended) return;
+    const messageSnapshot = this.#accumulateMessage(event);
+    this._deliverEvent(event, messageSnapshot);
+    if (!messageSnapshot) return;
+
+    switch (event.type) {
+      case 'content_block_delta': {
+        const content = messageSnapshot.content.at(-1)!;
+        switch (event.delta.type) {
+          case 'text_delta': {
+            if (content.type === 'text') {
+              this._emit('text', event.delta.text, content.text || '');
+            }
+            break;
+          }
+          case 'citations_delta': {
+            if (content.type === 'text') {
+              this._emit('citation', event.delta.citation, content.citations ?? []);
+            }
+            break;
+          }
+          case 'input_json_delta': {
+            if (tracksToolInput(content) && this.#listeners.inputJson?.length) {
+              let jsonSnapshot: unknown;
+              try {
+                jsonSnapshot = content.input;
+              } catch (err) {
+                this.#handleError(this.#toolInputParseError(content, err));
+                break;
+              }
+              this._emit('inputJson', event.delta.partial_json, jsonSnapshot);
+            }
+            break;
+          }
+          case 'thinking_delta': {
+            if (content.type === 'thinking') {
+              this._emit('thinking', event.delta.thinking, content.thinking);
+            }
+            break;
+          }
+          case 'signature_delta': {
+            if (content.type === 'thinking') {
+              this._emit('signature', content.signature);
+            }
+            break;
+          }
+          case 'compaction_delta': {
+            if (content.type === 'compaction' && content.content) {
+              this._emit('compaction', content.content);
+            }
+            break;
+          }
+          default:
+            checkNever(event.delta);
+        }
+        break;
+      }
+      case 'message_stop': {
+        if (this.#client && this.#span && this.#params) {
+          recordStreamedMessageContent(this.#client, this.#span, this.#params, messageSnapshot);
+        }
+        // Assertion needed until the generated request and response types of `tool_listing` agree.
+        this._addMessageParam(messageSnapshot as BetaMessageParam);
+        this._addMessage(
+          maybeParseBetaMessage(messageSnapshot, this.#params, { logger: this.#logger }),
+          true,
+        );
+        break;
+      }
+      case 'content_block_stop': {
+        this._emit('contentBlock', messageSnapshot.content.at(-1)!);
+        break;
+      }
+      case 'message_start': {
+        this.#currentMessageSnapshot = messageSnapshot;
+        if (this.#span && this.#params) {
+          this.#span.streamed = { body: this.#params, message: messageSnapshot };
+        }
+        break;
+      }
+      case 'content_block_start':
+      case 'message_delta':
+        break;
+    }
+  }
+  #endRequest(): ParsedBetaMessage<ParsedT> {
+    if (this.ended) {
+      throw new AnthropicError(`stream has ended, this shouldn't happen`);
+    }
+    const snapshot = this.#currentMessageSnapshot;
+    if (!snapshot) {
+      throw new AnthropicError(`request ended without sending any chunks`);
+    }
+    this.#currentMessageSnapshot = undefined;
+    return maybeParseBetaMessage(snapshot, this.#params, { logger: this.#logger });
+  }
+
+  protected async _fromReadableStream(
+    readableStream: ReadableStream,
+    options?: RequestOptions,
+  ): Promise<void> {
+    const signal = options?.signal;
+    let abortHandler: (() => void) | undefined;
+    if (signal) {
+      if (signal.aborted) this.controller.abort();
+      abortHandler = this.controller.abort.bind(this.controller);
+      signal.addEventListener('abort', abortHandler);
+    }
+    try {
+      this.#beginRequest();
+      this._connected(null);
+      const stream = Stream.fromReadableStream<BetaMessageStreamEvent>(readableStream, this.controller);
+      for await (const event of stream) {
+        this.#addStreamEvent(event);
+      }
+      if (stream.controller.signal?.aborted) {
+        throw new APIUserAbortError();
+      }
+      this.#endRequest();
+    } finally {
+      if (signal && abortHandler) {
+        signal.removeEventListener('abort', abortHandler);
+      }
+    }
+  }
+
+  /**
+   * Mutates this.#currentMessage with the current event. Handling the accumulation of multiple messages
+   * will be needed to be handled by the caller, this method will throw if you try to accumulate for multiple
+   * messages.
+   */
+  #accumulateMessage(event: BetaMessageStreamEvent): BetaMessage | undefined {
+    let snapshot = this.#currentMessageSnapshot;
+
+    if (event.type === 'message_start') {
+      if (snapshot) {
+        throw new AnthropicError(`Unexpected event order, got ${event.type} before receiving "message_stop"`);
+      }
+      return event.message;
+    }
+
+    if (!snapshot) return;
+
+    switch (event.type) {
+      case 'message_stop':
+        return snapshot;
+      case 'message_delta':
+        snapshot.stop_reason = event.delta.stop_reason;
+        snapshot.stop_sequence = event.delta.stop_sequence;
+        snapshot.stop_details = event.delta.stop_details;
+        snapshot.usage.output_tokens = event.usage.output_tokens;
+
+        if (event.delta.container != null) {
+          snapshot.container = event.delta.container;
+        }
+
+        if (event.context_management != null) {
+          snapshot.context_management = event.context_management;
+        }
+
+        if (event.input_transformations != null) {
+          snapshot.input_transformations = event.input_transformations;
+        }
+
+        // The remaining usage counters are cumulative whole-message totals that are
+        // omitted when they don't apply, so overwrite when present and never add.
+        if (event.usage.input_tokens != null) {
+          snapshot.usage.input_tokens = event.usage.input_tokens;
+        }
+
+        if (event.usage.cache_creation_input_tokens != null) {
+          snapshot.usage.cache_creation_input_tokens = event.usage.cache_creation_input_tokens;
+        }
+
+        if (event.usage.cache_read_input_tokens != null) {
+          snapshot.usage.cache_read_input_tokens = event.usage.cache_read_input_tokens;
+        }
+
+        if (event.usage.server_tool_use != null) {
+          snapshot.usage.server_tool_use = event.usage.server_tool_use;
+        }
+
+        if (event.usage.iterations != null) {
+          snapshot.usage.iterations = event.usage.iterations;
+        }
+
+        if (event.usage.fallback_credit != null) {
+          snapshot.usage.fallback_credit = event.usage.fallback_credit;
+        }
+
+        if (event.usage.output_tokens_details != null) {
+          snapshot.usage.output_tokens_details = event.usage.output_tokens_details;
+        }
+
+        return snapshot;
+      case 'content_block_start':
+        snapshot.content.push(event.content_block);
+        if (event.content_block.type === 'fallback') {
+          // the final hop's fallback block names the model that served the response —
+          // keeps the snapshot consistent with the relabeled non-streaming message
+          snapshot.model = event.content_block.to.model;
+        }
+        return snapshot;
+      case 'content_block_delta': {
+        const snapshotContent = snapshot.content.at(event.index);
+
+        switch (event.delta.type) {
+          case 'text_delta': {
+            if (snapshotContent?.type === 'text') {
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                text: (snapshotContent.text || '') + event.delta.text,
+              };
+            }
+            break;
+          }
+          case 'citations_delta': {
+            if (snapshotContent?.type === 'text') {
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                citations: [...(snapshotContent.citations ?? []), event.delta.citation],
+              };
+            }
+            break;
+          }
+          case 'input_json_delta': {
+            if (snapshotContent && tracksToolInput(snapshotContent)) {
+              const jsonBuf = ((snapshotContent as any)[JSON_BUF_PROPERTY] || '') + event.delta.partial_json;
+              snapshot.content[event.index] = withLazyInput(snapshotContent, jsonBuf);
+            }
+            break;
+          }
+          case 'thinking_delta': {
+            if (snapshotContent?.type === 'thinking') {
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                thinking: snapshotContent.thinking + event.delta.thinking,
+              };
+            }
+            break;
+          }
+          case 'signature_delta': {
+            if (snapshotContent?.type === 'thinking') {
+              snapshot.content[event.index] = {
+                ...snapshotContent,
+                signature: event.delta.signature,
+              };
+            }
+            break;
+          }
+          case 'compaction_delta': {
+            if (snapshotContent?.type === 'compaction') {
+              // The delta carries the block's final value (null content = failed compaction), so assign.
+              const block = { ...snapshotContent, content: event.delta.content };
+              // beta-gated key: only copy it when the server sent it
+              if ('encrypted_content' in event.delta) {
+                block.encrypted_content = event.delta.encrypted_content;
+              }
+              snapshot.content[event.index] = block;
+            }
+            break;
+          }
+          default:
+            checkNever(event.delta);
+        }
+        return snapshot;
+      }
+      case 'content_block_stop': {
+        const snapshotContent = snapshot.content.at(event.index);
+        if (snapshotContent && tracksToolInput(snapshotContent) && JSON_BUF_PROPERTY in snapshotContent) {
+          let input: unknown;
+          try {
+            input = snapshotContent.input;
+          } catch (err) {
+            input = {};
+            this.#handleError(this.#toolInputParseError(snapshotContent, err));
+          }
+          Object.defineProperty(snapshotContent, 'input', {
+            value: input,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        }
+        return snapshot;
+      }
+      default:
+        return snapshot;
+    }
+  }
+
+  #toolInputParseError(block: TracksToolInput, err: unknown): AnthropicError {
+    const jsonBuf = (block as any)[JSON_BUF_PROPERTY];
+    return new AnthropicError(
+      `Unable to parse tool parameter JSON from model. Please retry your request or adjust your prompt. Error: ${err}. JSON: ${jsonBuf}`,
+    );
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<BetaMessageStreamEvent> {
+    const pushQueue: BetaMessageStreamEvent[] = [];
+    const readQueue: {
+      resolve: (chunk: BetaMessageStreamEvent | undefined) => void;
+      reject: (error: unknown) => void;
+    }[] = [];
+    let done = false;
+
+    this.on('_rawEvent', (event) => {
+      const reader = readQueue.shift();
+      if (reader) {
+        reader.resolve(event);
+      } else {
+        pushQueue.push(event);
+      }
+    });
+
+    this.on('end', () => {
+      done = true;
+      for (const reader of readQueue) {
+        reader.resolve(undefined);
+      }
+      readQueue.length = 0;
+    });
+
+    this.on('abort', (err) => {
+      done = true;
+      for (const reader of readQueue) {
+        reader.reject(err);
+      }
+      readQueue.length = 0;
+    });
+
+    this.on('error', (err) => {
+      done = true;
+      for (const reader of readQueue) {
+        reader.reject(err);
+      }
+      readQueue.length = 0;
+    });
+
+    return {
+      next: async (): Promise<IteratorResult<BetaMessageStreamEvent>> => {
+        if (!pushQueue.length) {
+          if (done) {
+            return { value: undefined, done: true };
+          }
+          return new Promise<BetaMessageStreamEvent | undefined>((resolve, reject) =>
+            readQueue.push({ resolve, reject }),
+          ).then((chunk) => (chunk ? { value: chunk, done: false } : { value: undefined, done: true }));
+        }
+        const chunk = pushQueue.shift()!;
+        return { value: chunk, done: false };
+      },
+      return: async () => {
+        this.abort();
+        return { value: undefined, done: true };
+      },
+    };
+  }
+
+  toReadableStream(): ReadableStream {
+    const stream = new Stream(this[Symbol.asyncIterator].bind(this), this.controller);
+    return stream.toReadableStream();
+  }
+}