For long-lived SDK agents (Agent.create → many send/run cycles without close):
Remaining context headroom (tokens or %)
Event when context is truncated/summarized internally (what was dropped)
First-class compact() / rollover hook (summarize-in-place without killing the agent)
Why: We run long-lived agents; warm reuse works but context state is an opaque box — we built compensating rollover in our own layer because the SDK doesn’t expose this.
Thanks for the detailed write-up, Pete! I’ve linked your post to the feature request we’re using to track SDK context and run observability, and logged your three asks against it.
One thing that may help today: summarization is already observable through the on_delta stream. For a long-lived agent, you’ll receive a summary-started update when in-place summarization kicks off, a summary-completed update when it finishes, and a summary update with the generated summary text. Pairing those with token-delta and the turn-ended usage object gives you a rough running signal.
The parts that aren’t exposed yet, which I’ve captured in the request:
Remaining context headroom as tokens or a percentage. Today turn-ended.usage is an aggregate across the whole turn, not a per-request context size.
A “what was dropped” detail on the summarization events.
A first-class, user-callable compact() / rollover hook. Compaction runs automatically under the hood, but there’s no programmatic trigger today.
Hey @PeteD,
Following up on this — the SDK now reports token usage on your runs. Updating to the latest @cursor/sdk gets you cumulative usage on run.usage and RunResult.usage, plus a usage event on run.stream() for each turn (works for both cloud and local agents). Pairing that with the summary-started / summary-completed signals gives you a much fuller picture of a long-lived agent’s context.
The other pieces you asked about — remaining context headroom as a percentage, a “what was dropped” detail on summarization, and a first-class programmatic compact() hook — aren’t in yet, but they’re still on our list and I’ll post here as they land.