Skip to content

feat: emit contextWindowFallback stream event before context reduction#2060

Open
Zelys-DFKH wants to merge 1 commit intostrands-agents:mainfrom
Zelys-DFKH:feat/context-window-fallback-event
Open

feat: emit contextWindowFallback stream event before context reduction#2060
Zelys-DFKH wants to merge 1 commit intostrands-agents:mainfrom
Zelys-DFKH:feat/context-window-fallback-event

Conversation

@Zelys-DFKH
Copy link
Copy Markdown

@Zelys-DFKH Zelys-DFKH commented Apr 4, 2026

Description

When the agent handles a context window overflow, it calls `reduce_context()` synchronously. This is a blocking operation that can take a noticeable amount of time in long sessions, but callers have no way to know it has started. From outside, the stream just goes quiet until the reduction finishes and the model is called again.

This change adds a `contextWindowFallback` event emitted immediately before `reduce_context()` is called, giving streaming consumers a real-time signal that context compression is starting.

Changes:

  • Add `ContextWindowFallbackEvent` TypedDict to `streaming.py` (alongside the other streaming event types)
  • Add `ContextWindowFallbackStreamEvent` TypedEvent subclass in `_events.py` so the event follows the same protocol as all other agent events
  • Yield the new event from the `except ContextWindowOverflowException` handler in `agent.py`, before the `reduce_context()` call

The `contextWindowFallback` key is also added to `StreamEvent` so consumers can pattern-match it in the same way as `messageStart`, `messageStop`, and the other stream event types.

Related Issues

Fixes #1511

Documentation PR

N/A

Type of Change

New feature

Testing

  • Added `test_stream_async_emits_context_window_fallback_event`, which mocks `reduce_context` to isolate event emission and verifies exactly one fallback event appears in the stream with the overflow message in the payload
  • All 120 existing agent tests pass

Checklist

  • I have read the CONTRIBUTING document
  • I have added any necessary tests that prove my fix is effective or my feature works
  • I have updated the documentation accordingly
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

When the agent catches a ContextWindowOverflowException it now yields a
contextWindowFallback streaming event before calling reduce_context, giving
callers a real-time signal that context compression is starting.

Adds ContextWindowFallbackEvent TypedDict to streaming.py, a matching
ContextWindowFallbackStreamEvent TypedEvent subclass in _events.py, and
wires it into the overflow handler in agent.py.

Closes strands-agents#1511
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Real-time Streaming Events During Context Reduction

1 participant