Python: Add agent-triggered in-run compaction

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Agents can recognize semantic context boundaries—such as finishing planning or completing work that required a loaded skill—but existing compaction strategies run only according to developer-configured conditions. This change lets an agent request in-run compaction while preserving the existing responsibility split: the agent chooses when to compact, and the configured strategy controls what is removed and how.

The implementation composes with the existing function-calling and compaction pipelines and does not introduce persisted-history mutation.

Description & Review Guide

• What are the major changes?
  • Added AgentTriggeredCompactionStrategy, which wraps one existing strategy and exposes one explicitly registered trigger tool.
  • Added UnloadSkillsCompactionStrategy and its unload_skill trigger for one skill, multiple skills, or all loaded skills.
  • Temporarily excludes the trigger group while the inner strategy runs so workload retention counters do not include control-plane context, then restores it by default or excludes it when configured.
  • Preserves mixed parallel tool batches atomically regardless of trigger position.
  • Added public exports, focused streaming/non-streaming and strategy tests, and generic plus skill-unloading samples.
• What is the impact of these changes?
  • Applications can expose developer-controlled compaction to an agent without changing the existing CompactionStrategy protocol, Agent tool discovery, sessions, or history providers.
  • Existing strategies remain unchanged and can be wrapped directly.
• What do you want reviewers to focus on?
  • The trigger-group lifecycle and whether temporarily excluding it gives the expected semantics for existing retention strategies.
  • Atomic behavior when the trigger appears in a mixed parallel tool batch.
  • The specialized trigger-tool factory used by skill unloading while retaining a single exposed tool.

Related Issue

Fixes #9381

Part of #9379

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: GitHub Copilot assisted with the design, Python implementation, tests, samples, and this pull request description.

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 links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• 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 the title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Skill unloading can remove unrelated hosted-tool batches, while malformed trigger arguments can crash or unload all skills.

3 open findings

• Reject mixed provider-atomic groups containing non-skill tool calls · New
• Validate skill_name union to prevent unintended unloads and crashes · New
• Correct documentation for consumed marker state location · New

What changed in this PR

Adds agent-requested in-run context compaction while retaining developer-controlled compaction policies.

Changes:

• Adds generic triggered compaction and skill-unloading strategies.
• Exports and tests streaming, retention, and atomic-group behavior.
• Adds Foundry samples and documentation.

File	Description
python/​packages/​core/​agent_framework/​_compaction.py	Implements both strategies and trigger tools.
python/​packages/​core/​agent_framework/​__init__.py	Adds runtime exports.
python/​packages/​core/​agent_framework/​__init__.pyi	Adds typed exports.
python/​packages/​core/​tests/​core/​test_compaction.py	Tests strategy semantics.
python/​packages/​core/​tests/​core/​test_agents.py	Tests streaming and non-streaming integration.
python/​packages/​core/​AGENTS.md	Documents compaction behavior.
python/​samples/​02-agents/​compaction/​README.md	Lists the new samples.
python/​samples/​02-agents/​compaction/​agent_triggered_compaction.py	Demonstrates skill unloading.
python/​samples/​02-agents/​compaction/​agent_triggered_compaction_basic.py	Demonstrates generic triggering.

🧠 Review effort: Balanced

---

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

[github-code-quality]

Code coverage overview

Languages: Python

Python / code-coverage/python

main 220aec4	agent-controlled-com... 3095146	+/-
92%	92%	0%

View coverage of the 4 most impacted files.

File	main 220aec4	agent-controlled-com... 3095146	+/-
packages/core/a.../_compaction.py	94%	93%	-1%
packages/core/a...eature_stage.py	95%	95%	0%
packages/core/a...ework/_types.py	96%	96%	0%
packages/core/a...ork/_clients.py	93%	94%	+1%

ℹ️ Calculations represent line coverage. Results may change as calculations are updated.

---

_{Updated October 15, 2026 15:48 UTC}

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 7004916523b4
Model: gpt-5.6-sol

Overview

The PR composes agent-triggered compaction with the existing grouping and projection pipeline, with strong guards for one-shot consumption, failure restoration, mixed trigger batches, and streaming parity. The skill-unloading strategy also preserves ordinary mixed function-call groups and normalizes selected skill names. Two lifecycle gaps remain: rejected approval results are accepted as successful triggers, and completed non-adjacent trigger groups can be skipped because recency is based on the declaration's first occurrence.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (2 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_compaction.py