openai 7.4.0 → 7.6.0

package/src/lib/AssistantStream.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   TextContentBlock,
   ImageFileContentBlock,
   Message,
@@ -9,8 +9,8 @@ import {
   MessageDelta,
   MessageContent,
 } from '../resources/beta/threads/messages';
-import { RequestOptions } from '../internal/request-options';
-import {
+import type { RequestOptions } from '../internal/request-options';
+import type {
   Run,
   RunCreateParamsBase,
   RunCreateParamsStreaming,
@@ -18,70 +18,150 @@ import {
   RunSubmitToolOutputsParamsBase,
   RunSubmitToolOutputsParamsStreaming,
 } from '../resources/beta/threads/runs/runs';
-import { type ReadableStream } from '../internal/shim-types';
+import type { ReadableStream } from '../internal/shim-types';
 import { Stream } from '../streaming';
 import { APIUserAbortError, OpenAIError } from '../error';
-import {
+import type {
   AssistantStreamEvent,
   MessageStreamEvent,
   RunStepStreamEvent,
   RunStreamEvent,
 } from '../resources/beta/assistants';
-import { RunStep, RunStepDelta, ToolCall, ToolCallDelta } from '../resources/beta/threads/runs/steps';
-import { ThreadCreateAndRunParamsBase, Threads } from '../resources/beta/threads/threads';
-import { BaseEvents, EventStream } from './EventStream';
-import { isObj } from '../internal/utils';
-
+import type { RunStep, RunStepDelta, ToolCall, ToolCallDelta } from '../resources/beta/threads/runs/steps';
+import type { ThreadCreateAndRunParamsBase, Threads } from '../resources/beta/threads/threads';
+import type { BaseEvents, EventParameters } from './EventStream';
+import { EventStream } from './EventStream';
+import { hasOwn } from '../internal/utils';
+import {
+  accumulateAssistantStreamDelta,
+  assertSafeAssistantStreamDelta,
+  createAssistantStreamArrayDeltaCommit,
+  defineAssistantStreamArrayEntry,
+  isAssistantStreamValueExternallyMutable,
+  markAssistantStreamValueExternallyMutable,
+} from '../internal/assistant-stream-delta';
+
+/** Lifecycle, message, run-step, tool-call, and content events emitted by an assistant stream. */
 export interface AssistantStreamEvents extends BaseEvents {
+  /** Called with the finalized assistant run after all stream events have been processed. */
   run: (run: Run) => void;
 
-  //New event structure
+  /** Called when a new assistant-thread message is created. */
   messageCreated: (message: Message) => void;
+  /** Called with a message delta and the message snapshot after applying that delta. */
   messageDelta: (message: MessageDelta, snapshot: Message) => void;
+  /** Called when an assistant-thread message reaches a completed or incomplete terminal state. */
   messageDone: (message: Message) => void;
 
+  /** Called when a new step is added to the assistant run. */
   runStepCreated: (runStep: RunStep) => void;
+  /** Called with a run-step delta and the step snapshot after applying that delta. */
   runStepDelta: (delta: RunStepDelta, snapshot: Runs.RunStep) => void;
+  /** Called with the terminal run-step event and its accumulated snapshot. */
   runStepDone: (runStep: Runs.RunStep, snapshot: Runs.RunStep) => void;
 
+  /** Called when a new tool call begins within an assistant run step. */
   toolCallCreated: (toolCall: ToolCall) => void;
+  /** Called with a tool-call delta and the tool-call snapshot after applying that delta. */
   toolCallDelta: (delta: ToolCallDelta, snapshot: ToolCall) => void;
+  /** Called when the current tool call finishes or a subsequent tool call begins. */
   toolCallDone: (toolCall: ToolCall) => void;
 
+  /** Called when a new text content block is added to an assistant message. */
   textCreated: (content: Text) => void;
+  /** Called with a text fragment and the complete text accumulated for its content block. */
   textDelta: (delta: TextDelta, snapshot: Text) => void;
+  /** Called when a text content block finishes, together with its containing message. */
   textDone: (content: Text, snapshot: Message) => void;
 
-  //No created or delta as this is not streamed
+  /** Called with a completed image-file content block; image files do not have delta events. */
   imageFileDone: (content: ImageFile, snapshot: Message) => void;
 
+  /** Called for every raw assistant-stream event received from the API. */
   event: (event: AssistantStreamEvent) => void;
 }
 
+/** Parameters for creating an assistant thread and immediately streaming its run. */
 export type ThreadCreateAndRunParamsBaseStream = Omit<ThreadCreateAndRunParamsBase, 'stream'> & {
+  /** Streaming is always enabled by the helper and may be specified explicitly. */
   stream?: true;
 };
 
+/** Parameters for creating and streaming an assistant run on an existing thread. */
 export type RunCreateParamsBaseStream = Omit<RunCreateParamsBase, 'stream'> & {
+  /** Streaming is always enabled by the helper and may be specified explicitly. */
   stream?: true;
 };
 
+/** Parameters for submitting tool outputs and streaming the resumed assistant run. */
 export type RunSubmitToolOutputsParamsStream = Omit<RunSubmitToolOutputsParamsBase, 'stream'> & {
+  /** Streaming is always enabled by the helper and may be specified explicitly. */
   stream?: true;
 };
 
+function stabilizeAssistantStreamEvent(event: AssistantStreamEvent): {
+  event: AssistantStreamEvent;
+  exposedEvent: AssistantStreamEvent;
+} {
+  const eventDescriptor = Object.getOwnPropertyDescriptor(event, 'event');
+  const dataDescriptor = Object.getOwnPropertyDescriptor(event, 'data');
+  const eventType = Reflect.get(event, 'event', event) as AssistantStreamEvent['event'];
+  const data = Reflect.get(event, 'data', event) as AssistantStreamEvent['data'];
+  let stableData = data;
+  if (
+    eventType === 'thread.message.created' ||
+    eventType === 'thread.message.in_progress' ||
+    eventType === 'thread.message.delta' ||
+    eventType === 'thread.message.completed' ||
+    eventType === 'thread.message.incomplete' ||
+    eventType === 'thread.run.step.created' ||
+    eventType === 'thread.run.step.in_progress' ||
+    eventType === 'thread.run.step.delta' ||
+    eventType === 'thread.run.step.completed' ||
+    eventType === 'thread.run.step.failed' ||
+    eventType === 'thread.run.step.cancelled' ||
+    eventType === 'thread.run.step.expired'
+  ) {
+    const messageID = Object.getOwnPropertyDescriptor(data, 'id');
+    if (messageID && 'value' in messageID && Reflect.get(data, 'id', data) !== messageID.value) {
+      const canonicalID = messageID.value as unknown;
+      stableData = new Proxy(data, {
+        get(target, property) {
+          return property === 'id' ? canonicalID : Reflect.get(target, property, target);
+        },
+      }) as AssistantStreamEvent['data'];
+    }
+  }
+  const stableEvent = Object.freeze({ event: eventType, data: stableData }) as AssistantStreamEvent;
+  const ordinaryEvent =
+    eventDescriptor !== undefined &&
+    'value' in eventDescriptor &&
+    eventDescriptor.value === eventType &&
+    dataDescriptor !== undefined &&
+    'value' in dataDescriptor &&
+    dataDescriptor.value === data &&
+    stableData === data;
+
+  return {
+    event: stableEvent,
+    exposedEvent: ordinaryEvent ? event : ({ event: eventType, data: stableData } as AssistantStreamEvent),
+  };
+}
+
+/** Streams assistant-run events while accumulating messages, run steps, and tool-call snapshots. */
 export class AssistantStream
   extends EventStream<AssistantStreamEvents>
   implements AsyncIterable<AssistantStreamEvent>
 {
-  //Track all events in a single list for reference
-  #events: AssistantStreamEvent[] = [];
-
   //Used to accumulate deltas
   //We are accumulating many types so the value here is not strict
-  #runStepSnapshots: { [id: string]: Runs.RunStep } = {};
-  #messageSnapshots: { [id: string]: Message } = {};
+  #runStepSnapshots: Record<string, Runs.RunStep> = Object.create(null);
+  #runStepIDOwners = new Map<string, string>();
+  #activeRunStepID: string | undefined;
+  #messageSnapshots: Record<string, Message> = Object.create(null);
+  #messageIDOwners = new Map<string, string>();
   #messageSnapshot: Message | undefined;
+  #activeMessageID: string | undefined;
   #finalRun: Run | undefined;
   #currentContentIndex: number | undefined;
   #currentContent: MessageContent | undefined;
@@ -93,69 +173,20 @@ export class AssistantStream
   #currentRunSnapshot: Run | undefined;
   #currentRunStepSnapshot: Runs.RunStep | undefined;
 
+  /** Iterates over cloned raw assistant events; stopping early aborts the underlying request. */
   [Symbol.asyncIterator](): AsyncIterator<AssistantStreamEvent> {
-    const pushQueue: AssistantStreamEvent[] = [];
-    const readQueue: {
-      resolve: (chunk: AssistantStreamEvent | undefined) => void;
-      reject: (err: unknown) => void;
-    }[] = [];
-    let done = false;
-
-    //Catch all for passing along all events
-    this.on('event', (event) => {
-      const eventCopy = structuredClone(event);
-      const reader = readQueue.shift();
-      if (reader) {
-        reader.resolve(eventCopy);
-      } else {
-        pushQueue.push(eventCopy);
-      }
-    });
-
-    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<AssistantStreamEvent>> => {
-        if (!pushQueue.length) {
-          if (done) {
-            return { value: undefined, done: true };
-          }
-          return new Promise<AssistantStreamEvent | 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 };
+    return this._createIterator<AssistantStreamEvent>(
+      (push) => {
+        //Catch all for passing along all events
+        const onEvent = (event: AssistantStreamEvent) => push(structuredClone(event));
+        this.on('event', onEvent);
+        return () => this.off('event', onEvent);
       },
-    };
+      { onReturn: () => this.abort() },
+    );
   }
 
+  /** Restores an assistant stream from events serialized by `toReadableStream()`. */
   static fromReadableStream(stream: ReadableStream): AssistantStream {
     const runner = new AssistantStream();
     runner._run(() => runner._fromReadableStream(stream));
@@ -178,11 +209,13 @@ export class AssistantStream
     return this._addRun(this.#endRequest());
   }
 
+  /** Serializes assistant events into a readable stream for transfer to another runtime. */
   toReadableStream(): ReadableStream {
     const stream = new Stream(this[Symbol.asyncIterator].bind(this), this.controller);
     return stream.toReadableStream();
   }
 
+  /** Submits tool outputs and starts streaming the continuation of an existing assistant run. */
   static createToolAssistantStream(
     runId: string,
     runs: Runs,
@@ -193,7 +226,7 @@ export class AssistantStream
     runner._run(() =>
       runner._runToolAssistantStream(runId, runs, params, {
         ...options,
-        headers: { ...options?.headers, 'X-Stainless-Helper-Method': 'stream' },
+        __metadata: { ...options?.__metadata, helperMethod: 'stream' },
       }),
     );
     return runner;
@@ -225,6 +258,7 @@ export class AssistantStream
     return this._addRun(this.#endRequest());
   }
 
+  /** Creates an assistant thread and starts streaming its newly created run. */
   static createThreadAssistantStream(
     params: ThreadCreateAndRunParamsBaseStream,
     thread: Threads,
@@ -234,12 +268,13 @@ export class AssistantStream
     runner._run(() =>
       runner._threadAssistantStream(params, thread, {
         ...options,
-        headers: { ...options?.headers, 'X-Stainless-Helper-Method': 'stream' },
+        __metadata: { ...options?.__metadata, helperMethod: 'stream' },
       }),
     );
     return runner;
   }
 
+  /** Creates a run on an existing assistant thread and starts streaming its events. */
   static createAssistantStream(
     threadId: string,
     runs: Runs,
@@ -250,43 +285,56 @@ export class AssistantStream
     runner._run(() =>
       runner._runAssistantStream(threadId, runs, params, {
         ...options,
-        headers: { ...options?.headers, 'X-Stainless-Helper-Method': 'stream' },
+        __metadata: { ...options?.__metadata, helperMethod: 'stream' },
       }),
     );
     return runner;
   }
 
+  /** Returns the most recent raw event, or `undefined` before any event arrives. */
   currentEvent(): AssistantStreamEvent | undefined {
+    markAssistantStreamValueExternallyMutable(this.#currentEvent);
     return this.#currentEvent;
   }
 
+  /** Returns the latest run snapshot, or `undefined` before a run event arrives. */
   currentRun(): Run | undefined {
+    markAssistantStreamValueExternallyMutable(this.#currentRunSnapshot);
     return this.#currentRunSnapshot;
   }
 
+  /** Returns the message currently being accumulated, or `undefined` before message creation. */
   currentMessageSnapshot(): Message | undefined {
+    markAssistantStreamValueExternallyMutable(this.#messageSnapshot);
     return this.#messageSnapshot;
   }
 
+  /** Returns the run step currently being accumulated, or `undefined` before a step begins. */
   currentRunStepSnapshot(): Runs.RunStep | undefined {
+    markAssistantStreamValueExternallyMutable(this.#currentRunStepSnapshot);
     return this.#currentRunStepSnapshot;
   }
 
+  /** Waits for successful completion and returns the final snapshot of every observed run step. */
   async finalRunSteps(): Promise<Runs.RunStep[]> {
     await this.done();
 
     return Object.values(this.#runStepSnapshots);
   }
 
+  /** Waits for successful completion and returns the final snapshot of every observed message. */
   async finalMessages(): Promise<Message[]> {
     await this.done();
 
     return Object.values(this.#messageSnapshots);
   }
 
+  /** Waits for completion and returns the final run, or rejects if no terminal run was received. */
   async finalRun(): Promise<Run> {
     await this.done();
-    if (!this.#finalRun) throw Error('Final run was not received.');
+    if (!this.#finalRun) {
+      throw new Error('Final run was not received.');
+    }
 
     return this.#finalRun;
   }
@@ -337,16 +385,57 @@ export class AssistantStream
   }
 
   #addEvent(event: AssistantStreamEvent) {
-    if (this.ended) return;
+    if (this.ended) {
+      return;
+    }
 
-    this.#currentEvent = event;
+    const { event: stableEvent, exposedEvent } = stabilizeAssistantStreamEvent(event);
 
-    this.#handleEvent(event);
+    let messageID: string | undefined;
+    let messageData: MessageStreamEvent['data'] | undefined;
+    let runStepID: string | undefined;
+    let runStepData: RunStepStreamEvent['data'] | undefined;
+    switch (stableEvent.event) {
+      case 'thread.message.created':
+      case 'thread.message.in_progress':
+      case 'thread.message.delta':
+      case 'thread.message.completed':
+      case 'thread.message.incomplete': {
+        messageID = this.#validateMessageEvent(stableEvent);
+        messageData = stableEvent.data;
+        break;
+      }
+      case 'thread.run.step.created':
+      case 'thread.run.step.in_progress':
+      case 'thread.run.step.delta':
+      case 'thread.run.step.completed':
+      case 'thread.run.step.failed':
+      case 'thread.run.step.cancelled':
+      case 'thread.run.step.expired': {
+        runStepID = this.#validateRunStepEvent(stableEvent);
+        runStepData = stableEvent.data;
+        break;
+      }
+    }
 
-    switch (event.event) {
-      case 'thread.created':
+    this.#currentEvent = exposedEvent;
+
+    this.#handleEvent(exposedEvent);
+    if (messageID !== undefined && messageData !== undefined) {
+      this.#reserveMessageAlias(messageData, messageID);
+    }
+    if (runStepID !== undefined && runStepData !== undefined) {
+      this.#reserveRunStepAlias(runStepData, runStepID);
+    }
+    if (runStepID === undefined && this.#activeRunStepID !== undefined && this.#currentRunStepSnapshot) {
+      this.#reserveRunStepAlias(this.#currentRunStepSnapshot, this.#activeRunStepID);
+    }
+
+    switch (stableEvent.event) {
+      case 'thread.created': {
         //No action on this event.
         break;
+      }
 
       case 'thread.run.created':
       case 'thread.run.queued':
@@ -357,9 +446,10 @@ export class AssistantStream
       case 'thread.run.failed':
       case 'thread.run.cancelling':
       case 'thread.run.cancelled':
-      case 'thread.run.expired':
-        this.#handleRun(event);
+      case 'thread.run.expired': {
+        this.#handleRun(stableEvent);
         break;
+      }
 
       case 'thread.run.step.created':
       case 'thread.run.step.in_progress':
@@ -367,25 +457,48 @@ export class AssistantStream
       case 'thread.run.step.completed':
       case 'thread.run.step.failed':
       case 'thread.run.step.cancelled':
-      case 'thread.run.step.expired':
-        this.#handleRunStep(event);
+      case 'thread.run.step.expired': {
+        if (runStepID === undefined) {
+          throw new OpenAIError('Received assistant run-step event without a canonical run-step ID');
+        }
+        const activeRunStep = this.#runStepSnapshots[runStepID];
+        if (activeRunStep) {
+          this.#reserveRunStepAlias(activeRunStep, runStepID);
+        }
+        this.#handleRunStep(stableEvent, runStepID);
+        this.#reserveRunStepAlias(stableEvent.data, runStepID);
+        const retainedRunStep = this.#runStepSnapshots[runStepID];
+        if (retainedRunStep) {
+          this.#reserveRunStepAlias(retainedRunStep, runStepID);
+        }
         break;
+      }
 
       case 'thread.message.created':
       case 'thread.message.in_progress':
       case 'thread.message.delta':
       case 'thread.message.completed':
-      case 'thread.message.incomplete':
-        this.#handleMessage(event);
+      case 'thread.message.incomplete': {
+        this.#handleMessage(stableEvent);
+        if (messageID !== undefined) {
+          this.#reserveMessageAlias(stableEvent.data, messageID);
+          const retainedMessage = this.#messageSnapshots[messageID];
+          if (retainedMessage) {
+            this.#reserveMessageAlias(retainedMessage, messageID);
+          }
+        }
         break;
+      }
 
-      case 'error':
+      case 'error': {
         //This is included for completeness, but errors are processed in the SSE event processing so this should not occur
         throw new Error(
           'Encountered an error event in event processing - errors should be processed earlier',
         );
-      default:
-        assertNever(event);
+      }
+      default: {
+        assertNever(stableEvent);
+      }
     }
   }
 
@@ -394,57 +507,201 @@ export class AssistantStream
       throw new OpenAIError(`stream has ended, this shouldn't happen`);
     }
 
-    if (!this.#finalRun) throw Error('Final run has not been received');
+    if (!this.#finalRun) {
+      throw new Error('Final run has not been received');
+    }
 
     return this.#finalRun;
   }
 
+  #validateRunStepEvent(event: RunStepStreamEvent): string {
+    const descriptor = Object.getOwnPropertyDescriptor(event.data, 'id');
+    const runStepID = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+
+    if (typeof runStepID !== 'string' || runStepID.length === 0) {
+      throw new OpenAIError('Received assistant run-step event with an invalid run-step ID');
+    }
+
+    if (event.event === 'thread.run.step.created') {
+      if (this.#activeRunStepID !== undefined) {
+        throw new OpenAIError(
+          `Received run-step creation for "${runStepID}" before the active run step "${this.#activeRunStepID}" reached a terminal state`,
+        );
+      }
+
+      if (hasOwn(this.#runStepSnapshots, runStepID) || this.#runStepIDOwners.has(runStepID)) {
+        throw new OpenAIError(
+          `Received run-step creation for run step "${runStepID}", which has already been created`,
+        );
+      }
+
+      this.#activeRunStepID = runStepID;
+      this.#runStepIDOwners.set(runStepID, runStepID);
+      return runStepID;
+    }
+
+    if (this.#activeRunStepID !== undefined) {
+      if (runStepID !== this.#activeRunStepID) {
+        throw new OpenAIError(
+          `Received ${event.event} for run step "${runStepID}", which does not match the active run step "${this.#activeRunStepID}"`,
+        );
+      }
+      return runStepID;
+    }
+
+    if (event.event === 'thread.run.step.delta') {
+      if (!hasOwn(this.#runStepSnapshots, runStepID)) {
+        throw new OpenAIError('Received a RunStepDelta before creation of a snapshot');
+      }
+      throw new OpenAIError(`Received run-step delta for "${runStepID}" with no active run step`);
+    }
+
+    if (hasOwn(this.#runStepSnapshots, runStepID) || this.#runStepIDOwners.has(runStepID)) {
+      throw new OpenAIError(
+        `Received run-step event for run step "${runStepID}", which has already been created`,
+      );
+    }
+
+    this.#runStepIDOwners.set(runStepID, runStepID);
+    if (event.event === 'thread.run.step.in_progress') {
+      this.#activeRunStepID = runStepID;
+    }
+    return runStepID;
+  }
+
+  #reserveRunStepAlias(data: RunStepStreamEvent['data'], canonicalID: string): void {
+    const descriptor = Object.getOwnPropertyDescriptor(data, 'id');
+    const runStepID = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+    if (typeof runStepID !== 'string' || runStepID.length === 0) {
+      throw new OpenAIError('Received assistant run-step event with an invalid run-step ID');
+    }
+    const owner = this.#runStepIDOwners.get(runStepID);
+    if (owner !== undefined && owner !== canonicalID) {
+      throw new OpenAIError(
+        `Received run-step creation for run step "${runStepID}", which has already been created`,
+      );
+    }
+    this.#runStepIDOwners.set(runStepID, canonicalID);
+  }
+
+  #validateMessageEvent(event: MessageStreamEvent): string {
+    const descriptor = Object.getOwnPropertyDescriptor(event.data, 'id');
+    const messageID = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+
+    if (typeof messageID !== 'string' || messageID.length === 0) {
+      throw new OpenAIError('Received assistant message event with an invalid message ID');
+    }
+
+    if (event.event === 'thread.message.created') {
+      if (this.#messageSnapshot) {
+        throw new OpenAIError(
+          `Received message creation for "${messageID}" before the active message "${this.#activeMessageID}" reached a terminal state`,
+        );
+      }
+
+      if (hasOwn(this.#messageSnapshots, messageID) || this.#messageIDOwners.has(messageID)) {
+        throw new OpenAIError(
+          `Received message creation for message "${messageID}", which has already been created`,
+        );
+      }
+
+      this.#activeMessageID = messageID;
+      this.#messageIDOwners.set(messageID, messageID);
+      return messageID;
+    }
+
+    if (!this.#messageSnapshot) {
+      if (event.event === 'thread.message.delta') {
+        throw new OpenAIError(
+          'Received a delta with no existing snapshot (there should be one from message creation)',
+        );
+      }
+
+      throw new OpenAIError('Received thread message event with no existing snapshot');
+    }
+
+    if (messageID !== this.#activeMessageID) {
+      throw new OpenAIError(
+        `Received ${event.event} for message "${messageID}", which does not match the active message "${this.#activeMessageID}"`,
+      );
+    }
+    return messageID;
+  }
+
+  #reserveMessageAlias(data: MessageStreamEvent['data'], canonicalID: string): void {
+    const descriptor = Object.getOwnPropertyDescriptor(data, 'id');
+    const messageID = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+    if (typeof messageID !== 'string' || messageID.length === 0) {
+      throw new OpenAIError('Received assistant message event with an invalid message ID');
+    }
+    const owner = this.#messageIDOwners.get(messageID);
+    if (owner !== undefined && owner !== canonicalID) {
+      throw new OpenAIError(
+        `Received message creation for message "${messageID}", which has already been created`,
+      );
+    }
+    this.#messageIDOwners.set(messageID, canonicalID);
+  }
+
   #handleMessage(this: AssistantStream, event: MessageStreamEvent) {
     const [accumulatedMessage, newContent] = this.#accumulateMessage(event, this.#messageSnapshot);
     this.#messageSnapshot = accumulatedMessage;
-    this.#messageSnapshots[accumulatedMessage.id] = accumulatedMessage;
+    if (!this.#activeMessageID) {
+      throw new OpenAIError('Received thread message event with no active message ID');
+    }
+    this.#messageSnapshots[this.#activeMessageID] = accumulatedMessage;
 
     for (const content of newContent) {
       const snapshotContent = accumulatedMessage.content[content.index];
-      if (snapshotContent?.type == 'text') {
-        this._emit('textCreated', snapshotContent.text);
+      if (snapshotContent?.type === 'text') {
+        this.#emitExposed('textCreated', snapshotContent.text);
       }
     }
 
     switch (event.event) {
-      case 'thread.message.created':
-        this._emit('messageCreated', event.data);
+      case 'thread.message.created': {
+        this.#currentContentIndex = undefined;
+        this.#currentContent = undefined;
+        this.#emitExposed('messageCreated', event.data);
         break;
+      }
 
-      case 'thread.message.in_progress':
+      case 'thread.message.in_progress': {
         break;
+      }
 
-      case 'thread.message.delta':
-        this._emit('messageDelta', event.data.delta, accumulatedMessage);
+      case 'thread.message.delta': {
+        this.#emitExposed('messageDelta', event.data.delta, accumulatedMessage);
 
         if (event.data.delta.content) {
           for (const content of event.data.delta.content) {
             //If it is text delta, emit a text delta event
-            if (content.type == 'text' && content.text) {
-              let textDelta = content.text;
-              let snapshot = accumulatedMessage.content[content.index];
-              if (snapshot && snapshot.type == 'text') {
-                this._emit('textDelta', textDelta, snapshot.text);
+            if (content.type === 'text' && content.text) {
+              const textDelta = content.text;
+              const snapshot = accumulatedMessage.content[content.index];
+              if (snapshot && snapshot.type === 'text') {
+                this.#emitExposed('textDelta', textDelta, snapshot.text);
               } else {
-                throw Error('The snapshot associated with this text delta is not text or missing');
+                throw new Error('The snapshot associated with this text delta is not text or missing');
               }
             }
 
-            if (content.index != this.#currentContentIndex) {
+            if (content.index !== this.#currentContentIndex) {
               //See if we have in progress content
               if (this.#currentContent) {
                 switch (this.#currentContent.type) {
-                  case 'text':
-                    this._emit('textDone', this.#currentContent.text, this.#messageSnapshot);
+                  case 'text': {
+                    this.#emitExposed('textDone', this.#currentContent.text, this.#messageSnapshot);
                     break;
-                  case 'image_file':
-                    this._emit('imageFileDone', this.#currentContent.image_file, this.#messageSnapshot);
+                  }
+                  case 'image_file': {
+                    this.#emitExposed(
+                      'imageFileDone',
+                      this.#currentContent.image_file,
+                      this.#messageSnapshot,
+                    );
                     break;
+                  }
                 }
               }
 
@@ -456,124 +713,155 @@ export class AssistantStream
         }
 
         break;
+      }
 
       case 'thread.message.completed':
-      case 'thread.message.incomplete':
+      case 'thread.message.incomplete': {
         //We emit the latest content we were working on on completion (including incomplete)
         if (this.#currentContentIndex !== undefined) {
           const currentContent = event.data.content[this.#currentContentIndex];
           if (currentContent) {
             switch (currentContent.type) {
-              case 'image_file':
-                this._emit('imageFileDone', currentContent.image_file, this.#messageSnapshot);
+              case 'image_file': {
+                this.#emitExposed('imageFileDone', currentContent.image_file, this.#messageSnapshot);
                 break;
-              case 'text':
-                this._emit('textDone', currentContent.text, this.#messageSnapshot);
+              }
+              case 'text': {
+                this.#emitExposed('textDone', currentContent.text, this.#messageSnapshot);
                 break;
+              }
             }
           }
         }
 
         if (this.#messageSnapshot) {
-          this._emit('messageDone', event.data);
+          this.#emitExposed('messageDone', event.data);
         }
 
+        this.#currentContentIndex = undefined;
+        this.#currentContent = undefined;
         this.#messageSnapshot = undefined;
+        this.#activeMessageID = undefined;
+      }
     }
   }
 
-  #handleRunStep(this: AssistantStream, event: RunStepStreamEvent) {
-    const accumulatedRunStep = this.#accumulateRunStep(event);
+  #handleRunStep(this: AssistantStream, event: RunStepStreamEvent, runStepID: string) {
+    const accumulatedRunStep = this.#accumulateRunStep(event, runStepID);
     this.#currentRunStepSnapshot = accumulatedRunStep;
 
     switch (event.event) {
-      case 'thread.run.step.created':
-        this._emit('runStepCreated', event.data);
+      case 'thread.run.step.created': {
+        this.#currentToolCallIndex = undefined;
+        this.#currentToolCall = undefined;
+        this.#emitExposed('runStepCreated', event.data);
         break;
-      case 'thread.run.step.delta':
+      }
+      case 'thread.run.step.delta': {
         const delta = event.data.delta;
         if (
           delta.step_details &&
-          delta.step_details.type == 'tool_calls' &&
+          delta.step_details.type === 'tool_calls' &&
           delta.step_details.tool_calls &&
-          accumulatedRunStep.step_details.type == 'tool_calls'
+          accumulatedRunStep.step_details.type === 'tool_calls'
         ) {
           for (const toolCall of delta.step_details.tool_calls) {
-            if (toolCall.index == this.#currentToolCallIndex) {
-              this._emit(
+            if (toolCall.index === this.#currentToolCallIndex) {
+              this.#emitExposed(
                 'toolCallDelta',
                 toolCall,
                 accumulatedRunStep.step_details.tool_calls[toolCall.index] as ToolCall,
               );
             } else {
               if (this.#currentToolCall) {
-                this._emit('toolCallDone', this.#currentToolCall);
+                this.#emitExposed('toolCallDone', this.#currentToolCall);
               }
 
               this.#currentToolCallIndex = toolCall.index;
               this.#currentToolCall = accumulatedRunStep.step_details.tool_calls[toolCall.index];
-              if (this.#currentToolCall) this._emit('toolCallCreated', this.#currentToolCall);
+              if (this.#currentToolCall) {
+                this.#emitExposed('toolCallCreated', this.#currentToolCall);
+              }
             }
           }
         }
 
-        this._emit('runStepDelta', event.data.delta, accumulatedRunStep);
+        this.#emitExposed('runStepDelta', event.data.delta, accumulatedRunStep);
         break;
+      }
       case 'thread.run.step.completed':
       case 'thread.run.step.failed':
       case 'thread.run.step.cancelled':
-      case 'thread.run.step.expired':
+      case 'thread.run.step.expired': {
         this.#currentRunStepSnapshot = undefined;
+        this.#activeRunStepID = undefined;
         const details = event.data.step_details;
-        if (details.type == 'tool_calls') {
-          if (this.#currentToolCall) {
-            this._emit('toolCallDone', this.#currentToolCall as ToolCall);
-            this.#currentToolCall = undefined;
-          }
+        if (details.type === 'tool_calls' && this.#currentToolCall) {
+          this.#emitExposed('toolCallDone', this.#currentToolCall as ToolCall);
         }
-        this._emit('runStepDone', event.data, accumulatedRunStep);
+        this.#emitExposed('runStepDone', event.data, accumulatedRunStep);
+        this.#currentToolCallIndex = undefined;
+        this.#currentToolCall = undefined;
         break;
-      case 'thread.run.step.in_progress':
+      }
+      case 'thread.run.step.in_progress': {
         break;
+      }
+    }
+  }
+
+  #emitExposed<Event extends keyof AssistantStreamEvents>(
+    event: Event,
+    ...args: EventParameters<AssistantStreamEvents, Event>
+  ): void {
+    if (this._hasListeners(event)) {
+      for (const value of args) {
+        markAssistantStreamValueExternallyMutable(value);
+      }
     }
+    this._emit(event, ...args);
   }
 
   #handleEvent(this: AssistantStream, event: AssistantStreamEvent) {
-    this.#events.push(event);
-    this._emit('event', event);
+    this.#emitExposed('event', event);
   }
 
-  #accumulateRunStep(event: RunStepStreamEvent): Runs.RunStep {
+  #accumulateRunStep(event: RunStepStreamEvent, runStepID: string): Runs.RunStep {
     switch (event.event) {
-      case 'thread.run.step.created':
-        this.#runStepSnapshots[event.data.id] = event.data;
+      case 'thread.run.step.created': {
+        this.#runStepSnapshots[runStepID] = event.data;
         return event.data;
+      }
 
-      case 'thread.run.step.delta':
-        let snapshot = this.#runStepSnapshots[event.data.id] as Runs.RunStep;
+      case 'thread.run.step.delta': {
+        const snapshot = this.#runStepSnapshots[runStepID] as Runs.RunStep;
         if (!snapshot) {
-          throw Error('Received a RunStepDelta before creation of a snapshot');
+          throw new Error('Received a RunStepDelta before creation of a snapshot');
         }
 
-        let data = event.data;
+        const data = event.data;
 
         if (data.delta) {
-          const accumulated = AssistantStream.accumulateDelta(snapshot, data.delta) as Runs.RunStep;
-          this.#runStepSnapshots[event.data.id] = accumulated;
+          const accumulated = accumulateAssistantStreamDelta(snapshot, data.delta, true) as Runs.RunStep;
+          this.#runStepSnapshots[runStepID] = accumulated;
         }
 
-        return this.#runStepSnapshots[event.data.id] as Runs.RunStep;
+        return this.#runStepSnapshots[runStepID] as Runs.RunStep;
+      }
 
       case 'thread.run.step.completed':
       case 'thread.run.step.failed':
       case 'thread.run.step.cancelled':
       case 'thread.run.step.expired':
-      case 'thread.run.step.in_progress':
-        this.#runStepSnapshots[event.data.id] = event.data;
+      case 'thread.run.step.in_progress': {
+        this.#runStepSnapshots[runStepID] = event.data;
         break;
+      }
     }
 
-    if (this.#runStepSnapshots[event.data.id]) return this.#runStepSnapshots[event.data.id] as Runs.RunStep;
+    if (this.#runStepSnapshots[runStepID]) {
+      return this.#runStepSnapshots[runStepID] as Runs.RunStep;
+    }
     throw new Error('No snapshot available');
   }
 
@@ -581,155 +869,124 @@ export class AssistantStream
     event: AssistantStreamEvent,
     snapshot: Message | undefined,
   ): [Message, MessageContentDelta[]] {
-    let newContent: MessageContentDelta[] = [];
+    const newContent: MessageContentDelta[] = [];
 
     switch (event.event) {
-      case 'thread.message.created':
+      case 'thread.message.created': {
         //On creation the snapshot is just the initial message
         return [event.data, newContent];
+      }
 
-      case 'thread.message.delta':
+      case 'thread.message.delta': {
         if (!snapshot) {
-          throw Error(
+          throw new Error(
             'Received a delta with no existing snapshot (there should be one from message creation)',
           );
         }
 
-        let data = event.data;
+        const data = event.data;
 
         //If this delta does not have content, nothing to process
         if (data.delta.content) {
+          assertSafeAssistantStreamDelta(data.delta);
+          const cacheArrays = !isAssistantStreamValueExternallyMutable(snapshot);
+          const commitProjection = createAssistantStreamArrayDeltaCommit(
+            snapshot.content,
+            data.delta.content,
+            'content',
+            cacheArrays,
+          );
+
           for (const contentElement of data.delta.content) {
-            if (contentElement.index in snapshot.content) {
-              let currentContent = snapshot.content[contentElement.index];
+            if (hasOwn(snapshot.content, contentElement.index)) {
+              const currentContent = snapshot.content[contentElement.index];
               snapshot.content[contentElement.index] = this.#accumulateContent(
                 contentElement,
                 currentContent,
+                cacheArrays,
               );
             } else {
-              snapshot.content[contentElement.index] = contentElement as MessageContent;
+              defineAssistantStreamArrayEntry(snapshot.content, contentElement.index, contentElement);
               // This is a new element
               newContent.push(contentElement);
             }
           }
+
+          commitProjection();
         }
 
         return [snapshot, newContent];
+      }
 
       case 'thread.message.in_progress':
       case 'thread.message.completed':
-      case 'thread.message.incomplete':
+      case 'thread.message.incomplete': {
         //No changes on other thread events
         if (snapshot) {
           return [snapshot, newContent];
-        } else {
-          throw Error('Received thread message event with no existing snapshot');
         }
+        throw new Error('Received thread message event with no existing snapshot');
+      }
     }
-    throw Error('Tried to accumulate a non-message event');
+    throw new Error('Tried to accumulate a non-message event');
   }
 
+  // oxlint-disable-next-line class-methods-use-this -- Keeping this helper on the instance preserves nearby accumulator method structure.
   #accumulateContent(
     contentElement: MessageContentDelta,
     currentContent: MessageContent | undefined,
+    cacheArrays: boolean,
   ): TextContentBlock | ImageFileContentBlock {
-    return AssistantStream.accumulateDelta(currentContent as unknown as Record<any, any>, contentElement) as
-      | TextContentBlock
-      | ImageFileContentBlock;
+    return accumulateAssistantStreamDelta(
+      currentContent as unknown as Record<any, any>,
+      contentElement,
+      cacheArrays,
+    ) as TextContentBlock | ImageFileContentBlock;
   }
 
+  /**
+   * Applies an assistant delta to its mutable snapshot, concatenating text and
+   * merging nested objects and indexed array entries.
+   */
   static accumulateDelta(acc: Record<string, any>, delta: Record<string, any>): Record<string, any> {
-    for (const [key, deltaValue] of Object.entries(delta)) {
-      if (!acc.hasOwnProperty(key)) {
-        acc[key] = deltaValue;
-        continue;
-      }
-
-      let accValue = acc[key];
-      if (accValue === null || accValue === undefined) {
-        acc[key] = deltaValue;
-        continue;
-      }
-
-      // We don't accumulate these special properties
-      if (key === 'index' || key === 'type') {
-        acc[key] = deltaValue;
-        continue;
-      }
-
-      // Type-specific accumulation logic
-      if (typeof accValue === 'string' && typeof deltaValue === 'string') {
-        accValue += deltaValue;
-      } else if (typeof accValue === 'number' && typeof deltaValue === 'number') {
-        accValue += deltaValue;
-      } else if (isObj(accValue) && isObj(deltaValue)) {
-        accValue = this.accumulateDelta(accValue as Record<string, any>, deltaValue as Record<string, any>);
-      } else if (Array.isArray(accValue) && Array.isArray(deltaValue)) {
-        if (accValue.every((x) => typeof x === 'string' || typeof x === 'number')) {
-          accValue.push(...deltaValue); // Use spread syntax for efficient addition
-          continue;
-        }
-
-        for (const deltaEntry of deltaValue) {
-          if (!isObj(deltaEntry)) {
-            throw new Error(`Expected array delta entry to be an object but got: ${deltaEntry}`);
-          }
-
-          const index = deltaEntry['index'];
-          if (index == null) {
-            console.error(deltaEntry);
-            throw new Error('Expected array delta entry to have an `index` property');
-          }
-
-          if (typeof index !== 'number') {
-            throw new Error(`Expected array delta entry \`index\` property to be a number but got ${index}`);
-          }
-
-          const accEntry = accValue[index];
-          if (accEntry == null) {
-            accValue[index] = deltaEntry;
-          } else {
-            accValue[index] = this.accumulateDelta(accEntry, deltaEntry);
-          }
-        }
-        continue;
-      } else {
-        throw Error(`Unhandled record type: ${key}, deltaValue: ${deltaValue}, accValue: ${accValue}`);
-      }
-      acc[key] = accValue;
-    }
-
-    return acc;
+    return accumulateAssistantStreamDelta(acc, delta);
   }
 
   #handleRun(this: AssistantStream, event: RunStreamEvent) {
     this.#currentRunSnapshot = event.data;
 
     switch (event.event) {
-      case 'thread.run.created':
+      case 'thread.run.created': {
         break;
-      case 'thread.run.queued':
+      }
+      case 'thread.run.queued': {
         break;
-      case 'thread.run.in_progress':
+      }
+      case 'thread.run.in_progress': {
         break;
+      }
       case 'thread.run.requires_action':
       case 'thread.run.cancelled':
       case 'thread.run.failed':
       case 'thread.run.completed':
       case 'thread.run.expired':
-      case 'thread.run.incomplete':
+      case 'thread.run.incomplete': {
         this.#finalRun = event.data;
         if (this.#currentToolCall) {
-          this._emit('toolCallDone', this.#currentToolCall);
-          this.#currentToolCall = undefined;
+          this.#emitExposed('toolCallDone', this.#currentToolCall);
         }
+        this.#currentToolCallIndex = undefined;
+        this.#currentToolCall = undefined;
         break;
-      case 'thread.run.cancelling':
+      }
+      case 'thread.run.cancelling': {
         break;
+      }
     }
   }
 
   protected _addRun(run: Run): Run {
+    this.#emitExposed('run', run);
     return run;
   }
 
@@ -760,4 +1017,6 @@ export class AssistantStream
   }
 }
 
-function assertNever(_x: never) {}
+function assertNever(_x: never) {
+  return _x;
+}