fix: avoid replaying assistant conversation item IDs

seratch · seratch · commit bdbaaec7512f · 2026-05-05T21:03:13.000+09:00
diff --git a/.changeset/clean-conversation-replay.md b/.changeset/clean-conversation-replay.md
@@ -0,0 +1,6 @@
+---
+'@openai/agents-core': patch
+'@openai/agents-openai': patch
+---
+
+fix: avoid replaying assistant conversation item IDs from OpenAI Conversations history
diff --git a/packages/agents-core/src/memory/session.ts b/packages/agents-core/src/memory/session.ts
@@ -38,6 +38,14 @@ export interface Session {
    */
   getItems(limit?: number): Promise<AgentInputItem[]>;
 
+  /**
+   * Optionally rewrite a stored history item before it is sent back to the model.
+   *
+   * Session implementations can use this to strip provider-managed replay metadata while
+   * preserving their public `getItems()` shape for UI and deletion workflows.
+   */
+  prepareHistoryItemForModelInput?(item: AgentInputItem): AgentInputItem;
+
   /**
    * Append new items to the conversation history.
    *
diff --git a/packages/agents-core/src/runner/sessionPersistence.ts b/packages/agents-core/src/runner/sessionPersistence.ts
@@ -342,8 +342,11 @@ export async function prepareInputItemsWithSession(
   const newInputItems = toAgentInputList(input);
 
   if (!sessionInputCallback) {
+    const historyForModelInput = history.map((item) =>
+      prepareHistoryItemForModelInput(session, item),
+    );
     const preparedInput = includeHistoryInPreparedInput
-      ? dropOrphanToolCalls([...history, ...newInputItems], {
+      ? dropOrphanToolCalls([...historyForModelInput, ...newInputItems], {
           pruningIndexes: new Set(history.map((_, index) => index)),
         })
       : newInputItems;
@@ -363,37 +366,41 @@ export async function prepareInputItemsWithSession(
     );
   }
 
-  const historyCounts = buildItemFrequencyMap(historySnapshot);
+  const historyCounts = buildItemFrequencyMap(historySnapshot, {
+    session,
+    prepareForModelInput: true,
+  });
   const newInputCounts = buildItemFrequencyMap(newInputSnapshot);
   const historyRefs = buildAgentInputPool(historySnapshot);
   const newInputRefs = buildAgentInputPool(newInputSnapshot);
   const historyIndexes = new Set<number>();
 
   const appended: AgentInputItem[] = [];
   for (const [index, item] of combined.entries()) {
-    const key = getAgentInputItemKey(item);
+    const historyKey = getHistoryItemModelInputKey(session, item);
+    const newInputKey = getAgentInputItemKey(item);
     if (removeAgentInputFromPool(newInputRefs, item)) {
-      decrementCount(newInputCounts, key);
+      decrementCount(newInputCounts, newInputKey);
       appended.push(item);
       continue;
     }
 
     if (removeAgentInputFromPool(historyRefs, item)) {
-      decrementCount(historyCounts, key);
+      decrementCount(historyCounts, historyKey);
       historyIndexes.add(index);
       continue;
     }
 
-    const historyRemaining = historyCounts.get(key) ?? 0;
+    const historyRemaining = historyCounts.get(historyKey) ?? 0;
     if (historyRemaining > 0) {
-      historyCounts.set(key, historyRemaining - 1);
+      historyCounts.set(historyKey, historyRemaining - 1);
       historyIndexes.add(index);
       continue;
     }
 
-    const newRemaining = newInputCounts.get(key) ?? 0;
+    const newRemaining = newInputCounts.get(newInputKey) ?? 0;
     if (newRemaining > 0) {
-      newInputCounts.set(key, newRemaining - 1);
+      newInputCounts.set(newInputKey, newRemaining - 1);
       appended.push(item);
       continue;
     }
@@ -421,7 +428,14 @@ export async function prepareInputItemsWithSession(
   }
 
   const prunedPreparedItems = includeHistoryInPreparedInput
-    ? dropOrphanToolCalls(preparedItems, { pruningIndexes: historyIndexes })
+    ? dropOrphanToolCalls(
+        prepareHistoryItemsForModelInput(
+          session,
+          preparedItems,
+          historyIndexes,
+        ),
+        { pruningIndexes: historyIndexes },
+      )
     : preparedItems;
 
   return {
@@ -430,6 +444,35 @@ export async function prepareInputItemsWithSession(
   };
 }
 
+function prepareHistoryItemsForModelInput(
+  session: Session,
+  items: AgentInputItem[],
+  historyIndexes: Set<number>,
+): AgentInputItem[] {
+  if (!session.prepareHistoryItemForModelInput || historyIndexes.size === 0) {
+    return items;
+  }
+  return items.map((item, index) =>
+    historyIndexes.has(index)
+      ? prepareHistoryItemForModelInput(session, item)
+      : item,
+  );
+}
+
+function prepareHistoryItemForModelInput(
+  session: Session,
+  item: AgentInputItem,
+): AgentInputItem {
+  return session.prepareHistoryItemForModelInput?.(item) ?? item;
+}
+
+function getHistoryItemModelInputKey(
+  session: Session,
+  item: AgentInputItem,
+): string {
+  return getAgentInputItemKey(prepareHistoryItemForModelInput(session, item));
+}
+
 function normalizeItemsForSessionPersistence(
   items: AgentInputItem[],
 ): AgentInputItem[] {
@@ -635,10 +678,16 @@ async function runCompactionOnSession(
   );
 }
 
-function buildItemFrequencyMap(items: AgentInputItem[]): Map<string, number> {
+function buildItemFrequencyMap(
+  items: AgentInputItem[],
+  options?: { session?: Session; prepareForModelInput?: boolean },
+): Map<string, number> {
   const counts = new Map<string, number>();
   for (const item of items) {
-    const key = getAgentInputItemKey(item);
+    const key =
+      options?.prepareForModelInput && options.session
+        ? getHistoryItemModelInputKey(options.session, item)
+        : getAgentInputItemKey(item);
     counts.set(key, (counts.get(key) ?? 0) + 1);
   }
   return counts;
diff --git a/packages/agents-core/test/runner/sessionPersistence.test.ts b/packages/agents-core/test/runner/sessionPersistence.test.ts
@@ -697,6 +697,28 @@ describe('prepareInputItemsWithSession', () => {
     async clearSession(): Promise<void> {}
   }
 
+  class AssistantReplaySanitizingSession extends StubSession {
+    prepareHistoryItemForModelInput(item: AgentInputItem): AgentInputItem {
+      if (
+        !item ||
+        typeof item !== 'object' ||
+        Array.isArray(item) ||
+        item.type !== 'message' ||
+        item.role !== 'assistant'
+      ) {
+        return item;
+      }
+
+      const {
+        id: _id,
+        providerData: _providerData,
+        provider_data: _provider_data,
+        ...rest
+      } = item as Record<string, unknown>;
+      return rest as AgentInputItem;
+    }
+  }
+
   it('concatenates session history with array inputs when no callback is provided', async () => {
     const historyItem: AgentInputItem = {
       type: 'message',
@@ -738,6 +760,171 @@ describe('prepareInputItemsWithSession', () => {
     expect(sessionItems[1]).toBe(newItems[1]);
   });
 
+  it('sanitizes assistant history items before model input when the session requests it', async () => {
+    const userHistoryItem: AgentInputItem = {
+      id: 'conv-user',
+      type: 'message',
+      role: 'user',
+      content: 'user history',
+      providerData: { server: 'metadata' },
+    };
+    const assistantHistoryItem: AgentInputItem = {
+      id: 'conv-assistant',
+      type: 'message',
+      role: 'assistant',
+      status: 'completed',
+      content: [
+        {
+          type: 'output_text',
+          text: 'assistant history',
+        },
+      ],
+      providerData: { server: 'metadata' },
+    };
+    const functionCallItem: AgentInputItem = {
+      id: 'conv-call',
+      type: 'function_call',
+      name: 'lookup',
+      callId: 'call-history',
+      arguments: '{}',
+      status: 'completed',
+    };
+    const functionCallOutputItem: AgentInputItem = {
+      id: 'conv-output',
+      type: 'function_call_result',
+      name: 'lookup',
+      callId: 'call-history',
+      output: 'ok',
+      status: 'completed',
+    };
+    const session = new AssistantReplaySanitizingSession([
+      userHistoryItem,
+      assistantHistoryItem,
+      functionCallItem,
+      functionCallOutputItem,
+    ]);
+
+    const result = await prepareInputItemsWithSession('new', session);
+
+    expect(result.preparedInput).toEqual([
+      userHistoryItem,
+      {
+        type: 'message',
+        role: 'assistant',
+        status: 'completed',
+        content: [
+          {
+            type: 'output_text',
+            text: 'assistant history',
+          },
+        ],
+      },
+      functionCallItem,
+      functionCallOutputItem,
+      ...toAgentInputList('new'),
+    ]);
+    expect(result.sessionItems).toEqual(toAgentInputList('new'));
+  });
+
+  it('matches sanitized assistant history returned by callbacks without re-persisting it', async () => {
+    const assistantHistoryItem: AgentInputItem = {
+      id: 'conv-assistant',
+      type: 'message',
+      role: 'assistant',
+      status: 'completed',
+      content: [
+        {
+          type: 'output_text',
+          text: 'assistant history',
+        },
+      ],
+      providerData: { server: 'metadata' },
+    };
+    const newItem: AgentInputItem = {
+      type: 'message',
+      role: 'user',
+      content: 'new',
+    };
+    const session = new AssistantReplaySanitizingSession([
+      assistantHistoryItem,
+    ]);
+
+    const result = await prepareInputItemsWithSession(
+      [newItem],
+      session,
+      (history, newItems) => {
+        const {
+          id: _id,
+          providerData: _providerData,
+          ...historyCopy
+        } = history[0] as Record<string, unknown>;
+        return [historyCopy as AgentInputItem, { ...newItems[0] }];
+      },
+    );
+
+    expect(result.preparedInput).toEqual([
+      {
+        type: 'message',
+        role: 'assistant',
+        status: 'completed',
+        content: [
+          {
+            type: 'output_text',
+            text: 'assistant history',
+          },
+        ],
+      },
+      newItem,
+    ]);
+    expect(result.sessionItems).toEqual([newItem]);
+  });
+
+  it('keeps sanitized user history distinct when callbacks remove its id', async () => {
+    const userHistoryItem: AgentInputItem = {
+      id: 'conv-user',
+      type: 'message',
+      role: 'user',
+      content: 'user history',
+      providerData: { server: 'metadata' },
+    };
+    const newItem: AgentInputItem = {
+      type: 'message',
+      role: 'user',
+      content: 'new',
+    };
+    const session = new AssistantReplaySanitizingSession([userHistoryItem]);
+
+    const result = await prepareInputItemsWithSession(
+      [newItem],
+      session,
+      (history, newItems) => {
+        const {
+          id: _id,
+          providerData: _providerData,
+          ...historyCopy
+        } = history[0] as Record<string, unknown>;
+        return [historyCopy as AgentInputItem, { ...newItems[0] }];
+      },
+    );
+
+    expect(result.preparedInput).toEqual([
+      {
+        type: 'message',
+        role: 'user',
+        content: 'user history',
+      },
+      newItem,
+    ]);
+    expect(result.sessionItems).toEqual([
+      {
+        type: 'message',
+        role: 'user',
+        content: 'user history',
+      },
+      newItem,
+    ]);
+  });
+
   it('only persists new inputs when callbacks prepend history duplicates', async () => {
     const historyItem: AgentInputItem = {
       type: 'message',
diff --git a/packages/agents-openai/src/memory/openaiConversationsSession.ts b/packages/agents-openai/src/memory/openaiConversationsSession.ts
@@ -174,6 +174,10 @@ export class OpenAIConversationsSession
     return orderedItems;
   }
 
+  prepareHistoryItemForModelInput(item: AgentInputItem): AgentInputItem {
+    return stripAssistantReplayMetadata(item);
+  }
+
   async addItems(items: AgentInputItem[]): Promise<void> {
     if (!items.length) {
       return;
@@ -241,6 +245,25 @@ function stripIdsAndProviderData(items: AgentInputItem[]): AgentInputItem[] {
   });
 }
 
+function stripAssistantReplayMetadata(item: AgentInputItem): AgentInputItem {
+  if (Array.isArray(item) || item === null || typeof item !== 'object') {
+    return item;
+  }
+
+  const record = item as Record<string, unknown>;
+  if (record.type !== 'message' || record.role !== 'assistant') {
+    return item;
+  }
+
+  const {
+    id: _id,
+    providerData: _providerData,
+    provider_data: _provider_data,
+    ...rest
+  } = record;
+  return rest as AgentInputItem;
+}
+
 const INPUT_CONTENT_TYPES = new Set([
   'input_text',
   'input_image',
diff --git a/packages/agents-openai/test/openaiConversationsSession.test.ts b/packages/agents-openai/test/openaiConversationsSession.test.ts
