Repository navigation
[FEATURE]: Plugin API: read the session context size estimate #57216
Description
Problem
The host calculates the session context size estimate. The estimate is private to the core. A plugin cannot read it.
Source (v2.0.31)
-
packages/core/src/session/compaction.ts:874gives the estimate:export const estimateContext = (context: SessionContext.Loaded) => { -
packages/client/src/effect/api/api.ts:361shows that the plugin context operation gives messages only:export type SessionContextOutput = ReadonlyArray<SessionMessage.Info>The output has no token estimate.
Purpose
A plugin shows the context usage in a status line. A plugin selects compaction before the context overflows. The plugin must have the same estimate that the host uses.
Proposed minimal API
Add the estimate to the plugin session domain, for example ctx.session.contextSize({ sessionID }). Give the measured and estimated token counts.
What the plugin does today without it
The plugin cannot read the estimate. The plugin must approximate the size from the message text, and the approximation disagrees with the host.
Activity
opencode-agent commentedon Oct 19, 2026
Thanks for the request and for pointing to the exact code.
To restate it: you'd like the plugin API to expose the context size estimate the host already calculates. That's the measured tokens from the latest provider response plus the estimated tokens added since, for example via
ctx.session.contextSize({ sessionID }). Your plugin could then show context usage and decide on compaction using the same number OpenCode uses.This can't really be done as a plugin today. A plugin can rebuild the measured part from the latest assistant message's
tokens. The estimated part depends on how the host shapes the request internally (system prompt, tool definitions, unsupported media, the image budget), and plugins can't see that. Any plugin-side approximation will drift from the host's value, as you describe. A small read-only addition would close the gap: returnestimatePrompt's{ measured, estimated }, ideally with the model's context limit and the auto-compaction threshold. Maintainers will consider it.Related issues:
martinderm commentedon Nov 9, 2026
The maintainer guidance on #59531 ("write a plugin for it") points here: this issue is the enabling piece, not a nice-to-have.
A plugin can rebuild the measured part from the latest assistant message's
tokens, but not the estimated part the host adds (system prompt, tool definitions, media and image budget). Any plugin-side approximation therefore drifts from the number the host uses for compaction.Concrete case: a long-running OpenChamber session on OpenCode v2.2.6, model
opencode-go/deepseek-v4.1-flash#max(1M context). The agent-facing surface exposes no context-budget figure; the session data available to the agent carries cumulative token counters only, not the last request, the effective limit or the compaction threshold. A plugin is the suggested workaround, but a plugin cannot read the host estimate either, so it cannot supply a faithful figure.Minimal shape that would make the plugin path real:
ctx.session.contextSize({ sessionID })returning{ measured, estimated }, ideally with the model's context limit and the auto-compaction threshold.That is the value
estimateContextalready computes. A status line, a pre-compaction decision or a read-only tool could then use the same number as the host instead of guessing.Related: #59531 (closed not planned; plugin suggested), #19471 (closed for inactivity), #53030 (notify subagents when context runs low), #56744 (plugin hook to request compaction).