fix(realtime): keep conversation order when updateHistory corrects or inserts an item

`conversation.item.create` appends to the end of the conversation when
`previous_item_id` is omitted. `resetHistory()` omitted it for every item it
created, so correcting an item in the middle of the history -- which the voice
agent guide recommends for exactly that purpose -- moved it behind everything
that followed it. Inserting an item did the same.

The items are now walked in new-history order so each created item can name the
item it follows. Untouched items keep their place and can anchor the next
insert; a function call that could not be created does not, and neither does a
removed item.

An item with nothing before it is still created without `previous_item_id`.
The protocol accepts `previous_item_id: null` but does not document where that
places the item, so this leaves that case exactly as it was.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cmun2

.changeset/realtime-history-item-placement.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-realtime': patch
+---
+
+fix(realtime): keep conversation order when updateHistory corrects or inserts an item

packages/agents-realtime/src/openaiRealtimeBase.ts

@@ -993,27 +993,48 @@ export abstract class OpenAIRealtimeBase
       }
     }
 
-    const additionsAndUpdates = [...additions, ...updates];
+    // Walk the new history in order so each created item can name the item it
+    // follows. `conversation.item.create` appends to the end of the
+    // conversation when `previous_item_id` is omitted, which would move a
+    // corrected or inserted item behind everything after it.
+    const pendingIds = new Set(
+      [...additions, ...updates].map((item) => item.itemId),
+    );
+    let previousItemId: string | null = null;
+
+    for (const item of newHistory) {
+      if (!pendingIds.has(item.itemId)) {
+        // Untouched items keep their place and can anchor the next insert.
+        previousItemId = item.itemId;
+        continue;
+      }
 
-    for (const addition of additionsAndUpdates) {
-      if (addition.type === 'message') {
+      if (item.type === 'message') {
         const itemEntry: Record<string, any> = {
           type: 'message',
-          role: addition.role,
-          content: addition.content,
-          id: addition.itemId,
+          role: item.role,
+          content: item.content,
+          id: item.itemId,
         };
-        if (addition.role !== 'system' && addition.status) {
-          itemEntry.status = addition.status;
+        if (item.role !== 'system' && item.status) {
+          itemEntry.status = item.status;
         }
         this.sendEvent({
           type: 'conversation.item.create',
+          // Only when the item has a predecessor. `previous_item_id: null` is
+          // accepted by the protocol but its placement is not documented, so
+          // an item with nothing before it keeps the existing behaviour.
+          ...(previousItemId === null
+            ? {}
+            : { previous_item_id: previousItemId }),
           item: itemEntry,
         });
-      } else if (addition.type === 'function_call') {
+        previousItemId = item.itemId;
+      } else if (item.type === 'function_call') {
         logger.warn(
           'Function calls cannot be manually added or updated at the moment. Ignoring.',
         );
+        // Not created, so it cannot anchor the next insert.
       }
     }
   }

packages/agents-realtime/test/openaiRealtimeBase.test.ts

@@ -586,6 +586,105 @@ describe('OpenAIRealtimeBase helpers', () => {
     expect(base.events).toHaveLength(0);
   });
 
+  describe('resetHistory item placement', () => {
+    // `conversation.item.create` appends when `previous_item_id` is omitted, so
+    // a corrected or inserted item has to name the item it follows or it lands
+    // behind everything after it.
+    const message = (itemId: string, text: string) =>
+      ({
+        itemId,
+        type: 'message',
+        role: 'user',
+        status: 'completed',
+        content: [{ type: 'input_text', text }],
+      }) as any;
+
+    const functionCall = (itemId: string) =>
+      ({
+        itemId,
+        type: 'function_call',
+        name: 'f',
+        callId: itemId,
+        arguments: '{}',
+        status: 'completed',
+      }) as any;
+
+    function creates(oldHistory: any[], newHistory: any[]) {
+      const base = new TestBase();
+      base.resetHistory(oldHistory, newHistory);
+      return base.events
+        .filter((event: any) => event.type === 'conversation.item.create')
+        .map((event: any) =>
+          'previous_item_id' in event
+            ? `${event.item.id} after ${event.previous_item_id}`
+            : `${event.item.id} unanchored`,
+        );
+    }
+
+    it('anchors a corrected item to the one before it', () => {
+      expect(
+        creates(
+          [message('a', '1'), message('b', '2'), message('c', '3')],
+          [message('a', '1'), message('b', 'edited'), message('c', '3')],
+        ),
+      ).toEqual(['b after a']);
+    });
+
+    it('anchors an inserted item to the one before it', () => {
+      expect(
+        creates(
+          [message('a', '1'), message('c', '3')],
+          [message('a', '1'), message('b', '2'), message('c', '3')],
+        ),
+      ).toEqual(['b after a']);
+    });
+
+    it('chains consecutive corrections in history order', () => {
+      expect(
+        creates(
+          [message('a', '1'), message('b', '2'), message('c', '3')],
+          [message('a', '1'), message('b', 'B'), message('c', 'C')],
+        ),
+      ).toEqual(['b after a', 'c after b']);
+    });
+
+    it('leaves an item with nothing before it unanchored', () => {
+      expect(
+        creates(
+          [message('a', '1'), message('b', '2')],
+          [message('a', 'edited'), message('b', '2')],
+        ),
+      ).toEqual(['a unanchored']);
+    });
+
+    it('does not anchor to a function call it could not create', () => {
+      expect(
+        creates(
+          [message('a', '1')],
+          [message('a', '1'), functionCall('f'), message('c', '3')],
+        ),
+      ).toEqual(['c after a']);
+    });
+
+    it('anchors to a function call that is already in the conversation', () => {
+      expect(
+        creates(
+          [message('a', '1'), functionCall('f')],
+          [message('a', '1'), functionCall('f'), message('c', '3')],
+        ),
+      ).toEqual(['c after f']);
+    });
+
+    it('does not anchor to a removed item', () => {
+      expect(
+        creates(
+          [message('a', '1'), message('b', '2')],
+          [message('a', '1'), message('c', '3')],
+        ),
+      ).toEqual(['c after a']);
+    });
+  });
+
   it('sendMcpResponse emits approval response items', () => {
     const base = new TestBase();
     base.sendMcpResponse(