Python: Keep call and result occurrences atomic in compaction

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Compaction can separate a function call from a non-adjacent result, especially when completed rounds reuse the
same call_id. That can leave provider-invalid transcripts after sliding-window or incremental compaction.

Description & Review Guide

• What are the major changes?
  • Pair non-adjacent call/result spans by ordered, unambiguous occurrence.
  • Re-annotate enough prior history when a newly appended result completes an older call.
  • Preserve ambiguity safeguards when several unmatched declarations share one id.
  • Keep completed reused-id rounds atomic under sliding-window compaction.
• What is the impact of these changes?
  • Compaction no longer retains a result while dropping its matching declaration.
  • Legitimate reused ids remain separate logical rounds.
  • Ambiguous transcripts are not guessed into incorrect pairs.
• What do you want reviewers to focus on?
  • Ordered occurrence matching and incremental reannotation boundaries.
  • The distinction between completed reused-id rounds and genuinely ambiguous duplicates.

Related Issue

Fixes #7212

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.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_compaction.py	809	61	92%	137–138, 146, 173, 264–265, 283–284, 301, 336, 350, 357, 372–373, 427, 434, 450, 500, 536, 538, 558, 600, 656, 662, 664, 683, 727–732, 744, 828, 830, 845, 890, 952, 1078, 1084–1088, 1091–1093, 1101, 1176, 1178, 1194, 1201, 1206, 1221, 1229, 1328, 1351, 1363, 1459, 1486, 1570
TOTAL	45988	4479	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9488	34 💤	0 ❌	0 🔥	2m 35s ⏱️

[Copilot]

Pull request overview

This PR improves Python message compaction correctness by ensuring function-call declarations and their tool results remain grouped atomically even when the result is non-adjacent (e.g., approval/resume traffic in between) and when call_id values are legitimately reused across completed rounds. It updates both the compaction implementation and its specification/tests to prevent provider-invalid transcripts caused by orphaned call/result halves.

Changes:

• Link non-adjacent function_call / function_result occurrences by ordered, unambiguous call_id matching, including merging groups when a single tool message returns multiple results.
• Expand incremental re-annotation boundaries when newly appended tool results complete earlier declarations, and ensure linked groups are kept/excluded atomically.
• Add comprehensive unit tests and update docs/spec text to cover non-adjacent pairing, reused ids, and ambiguity safeguards.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
python/packages/core/agent_framework/_compaction.py	Implements unambiguous non-adjacent pairing/linking for tool call/result spans and adjusts incremental group re-annotation to preserve atomicity.
python/packages/core/tests/core/test_compaction.py	Adds tests covering non-adjacent pairing, multiple results, reused call_id occurrences, ambiguity handling, incremental extension behavior, and sliding-window behavior.
python/packages/core/AGENTS.md	Documents the new “ordered unambiguous occurrence” rule for reused call_id pairing during compaction.
docs/specs/004-python-function-calling-loop.md	Updates the spec’s compaction integrity coverage references and tracking list to reflect the new behavior and tests.

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 68% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Failure Modes, Design Approach

---

Automated review by eavanvalkenburg's agents