Python: Add gates and buffering to ResponseStream

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

ResponseStream.buffered_and_gated() introduced a specialized stream subtype and combined blocking, transformation, buffering, and replay policy in one operation. That made egress controls difficult to compose and forced middleware such as agent-hooks to own stream materialization instead of declaring the processing stages it needs.

This change moves those capabilities into ResponseStream itself so updates and final results can use the same explicit gate/transform pipeline, with buffering selected independently when fail-closed release or final-result replacement is required.

Description & Review Guide

• What are the major changes?
  • Add constructor and fluent APIs for ordered update/result gates, update/result transforms, buffered update release, final-result-to-update conversion, and complete-consumption context managers.
  • Keep existing transform/result hook names as compatibility aliases, remove _GatedResponseStream, and deprecate ResponseStream.buffered_and_gated() as a translation onto the new structures.
  • Extend middleware contexts so middleware registers stream configuration before call_next(); the pipeline applies it to the eventual stream. Agent-hooks now contributes its enforcement pieces through this mechanism without replacing or wrapping the returned stream.
  • Expand ResponseStream and agent-hooks coverage, and update the ResponseStream and streaming middleware samples to demonstrate the new developer experience.
• What is the impact of these changes?
  • Existing ResponseStream construction and hook APIs continue to work. Buffered streams can block before any egress, expose only released updates, and re-derive updates from an authoritative final result.
  • buffered_and_gated() remains available with a deprecation warning, while its private subtype is removed.
• What do you want reviewers to focus on?
  • Gate/transform ordering for live and buffered streams, finalization and cleanup behavior, middleware nesting order, and compatibility behavior for buffered_and_gated() and agent-hooks.

Related Issue

N/A — intentionally opened without a linked issue.

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]

Copilot review overview

🟡 Changes recommended

Buffered cancellation and unconditional re-derivation can lose updates or metadata, and the updated override sample currently fails due to transform ordering.

Review effort: Balanced
Findings: 3

Open (3)

• Unchanged streams lose updates and metadata during reconstruction · New
• Cancellation discards buffered updates and causes incomplete cleanup · New
• Validation transform ordering drops validation messages · New

What changed in this PR

Adds composable gates, transforms, buffering, and middleware configuration to Python ResponseStream.

Changes:

• Adds ordered update/result pipelines and buffered release.
• Migrates agent-hooks and middleware to declarative stream configuration.
• Expands tests and samples for the new APIs.

File	Description
python/​samples/​02-agents/​response_stream.py	Demonstrates gates, transforms, and buffering.
python/​samples/​02-agents/​middleware/​usage_tracking_middleware.py	Uses renamed transform collections.
python/​samples/​02-agents/​middleware/​README.md	Updates sample descriptions.
python/​samples/​02-agents/​middleware/​override_result_with_middleware.py	Migrates result overriding to buffered transforms.
python/​packages/​core/​tests/​core/​test_types.py	Tests gates and buffered streams.
python/​packages/​core/​tests/​core/​test_agent_hooks.py	Updates agent-hooks compatibility tests.
python/​packages/​core/​agent_framework/​_types.py	Implements the new ResponseStream pipeline.
python/​packages/​core/​agent_framework/​_middleware.py	Adds middleware stream configuration fields.
python/​packages/​core/​agent_framework/​_agents.py	Updates stream-gating documentation.
python/​packages/​core/​agent_framework/​_agent_hooks.py	Migrates enforcement to buffered stream configuration.

---

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

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 7aa97237eaac
Model: gpt-5.6-sol-fast

Overview

The new ResponseStream pipeline has strong ordering, atomic buffering, configuration-sealing, and cleanup guardrails, with extensive tests for normal gate and transform behavior. However, agent-hooks policy is now composed as ordinary mutable stream configuration, allowing later transforms or a replaced re-derivation callback to emit content after approval. The change also introduces observable compatibility regressions in pass-through stream fidelity and legacy hook assignment, plus duplicate shutdown records on failed streaming output evaluation.

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

Affected areas: python/packages/core/agent_framework/_agent_hooks.py, python/packages/core/agent_framework/_middleware.py, python/packages/core/agent_framework/_types.py