Python: Prevent replayed history from being re-persisted by CosmosHistoryProvider

[WhaleTech (ryo-whaletech)]

Motivation & Context

CosmosHistoryProvider.save_messages() currently upserts every supplied message under a fresh document ID. When a caller supplies a full accumulated transcript, the provider writes the already-persisted prefix again, causing silent duplicate and potentially superlinear persistent-history growth.

The core history contract already handles both append-only input and full-transcript replay through filter_new_messages(). Applying the same behavior to Cosmos closes a remaining provider-specific instance of the history replay problem addressed in #7242.

Description & Review Guide

• What are the major changes? CosmosHistoryProvider.save_messages() now reads the existing history for the same session and source, applies filter_new_messages(), returns when the incoming sequence is an exact replay, and builds Cosmos batch operations only for genuinely new messages. Deterministic regression tests exercise the actual query_items seam and verify both that prefix replay writes only C for existing [A, B] plus incoming [A, B, C], and that an exact replay writes nothing.
• What is the impact of these changes? Full-transcript callers no longer duplicate stored Cosmos messages. Append-only inputs remain supported, while document structure, ordering, and the 100-operation batch limit are unchanged. Each non-empty save now performs a session/source-scoped read before writing; there is no public API or storage-format change. As with the established Redis pattern, this does not make independent concurrent writers transactionally idempotent.
• What do you want reviewers to focus on? Please verify that using the existing session partition key for the read preserves Cosmos scoping, and that the regression tests sufficiently exercise the provider's actual read/write seam.

Related Issue

Fixes #8268

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟢 Approval recommended

The implementation follows the established history-provider pattern and is covered by focused regression tests.

Pull request overview

Prevents duplicate Cosmos history growth when callers replay accumulated transcripts.

Changes:

• Filters incoming messages against session/source-scoped history.
• Skips writes for exact replays.
• Adds regression coverage for replay scenarios.

File summaries

File	Description
python/packages/azure-cosmos/agent_framework_azure_cosmos/_history_provider.py	Persists only genuinely new messages.
python/packages/azure-cosmos/tests/test_cosmos_history_provider.py	Tests prefix and exact replay behavior.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[WhaleTech (ryo-whaletech)]

@microsoft-github-policy-service agree