Feature request: structured context overflow event payload contract

[drukpa1455]

Summary

Expose a structured overflow/compaction event payload as a stable contract for app instrumentation and tests.

Motivation

Apps implementing long-running agents currently infer overflow behavior from exceptions or ad-hoc strings. A typed payload would make retries, audit, and tests deterministic.

Proposal (additive)

• Add a small payload shape for overflow/compaction outcomes, e.g.:
  • reason (usage_limit_exceeded, context_limit_error, ...)
  • action (retry_compacted, retry_trim, fail)
  • trim_retries, max_trim_retries
  • optional error (truncated)
• Keep this opt-in and backward compatible.
• No provider-specific policy in V1.

Why separate from #4137

#4137 is the compaction abstraction. This issue is a narrower observability/testing contract that can be useful even with custom app-level compaction.

Offer

Happy to implement this behind a minimal additive API, pending maintainer scope approval.

[drukpa1455]

quick scope note: this is intended as payload contract only (observability/testability), not a broader compaction framework. happy to fold this into #4137 if maintainers prefer consolidation.

[drukpa1455]

opened a pr for this: #4429

scope is intentionally narrow to payload contract:

• adds ContextOverflowEvent
• adds UsageLimitExceeded.overflow_payload
• populates payload from UsageLimits checks
• includes tests + docs update