AIClaw 3.7.13: Separating Context Estimates from Provider Usage

Long-running agent sessions continuously accumulate text, tool call results, and decision records. Context meters help developers understand this growth, but an isolated percentage is easy to misread—is it an estimate of the current history, the last input count reported by the provider, or a cumulative billing total? AIClaw addresses this in version 3.7.13 by explicitly separating these three values.

Three readings with different meanings

v3.7.12 first introduced the context inspection panel, and v3.7.13 moves its entry point to the bottom toolbar, right next to the model selector. The panel presents the following three values separately:

• Current text and tool estimate: An approximation of the session's current messages and available tool definitions.
• Configured context window and estimated remaining space: The capacity provided by the model configuration, with remaining space calculated from the estimate.
• Provider's latest reported input tokens: The most recent input usage reading at runtime, shown separately from the estimate.

The estimator counts message text, a small allowance per message, tool call names and arguments, and serialized tool schemas. Image bytes are excluded, and the state separately indicates whether images are present. It uses the existing character heuristic—roughly one token per 4 ASCII characters and one token per non-ASCII character—which is not the true tokenizer of the selected model. Estimates may therefore diverge from provider usage and do not include vision tokens.

For example: if the configured window is 100,000 tokens and the estimate is 40,000 tokens, remaining space is approximately 60,000 tokens. The provider's reported 38,000 does not replace that estimate, and none of these numbers is cumulative billing.

What is a token? A token is the basic unit of text processing in a large language model—neither a character nor a word, but a subword fragment in between. Different models use different tokenizers, and the same text may produce different token counts across models. For example, in English "unbelievable" might be split into three tokens "un"+"believ"+"able", while a common word like "the" typically occupies just one. Chinese characters usually take one to two tokens each. Thus, the article's "roughly one token per 4 ASCII characters" is only a coarse character heuristic estimate, with systematic deviation from any specific model's true tokenization. This is also why the panel presents estimates separately from the provider's reported actual token count—the latter is a precise reading processed by that model's tokenizer, while the former is merely an approximation for quickly gauging context pressure.

Unknown capacity stays unknown

When the configured window is a positive number, the panel calculates a percentage. Without that configuration, it displays an unknown state and omits the remaining space calculation and progress bar. When the status request fails, the interface shows data unavailable rather than fabricating usage.

Provider usage also has its own missing data state. After a successful compaction, the previous input reading is reset to avoid showing an old request as the input size after a new compacted history. The panel is an inspection aid, not a guarantee that the next request will fit.

Compaction records keep bounded history

When a successful non-empty summary replaces the history, the runtime attempts to save timestamps and text estimates from before and after compaction. If the request fails or the summary is empty, the record does not advance. If metadata saving fails, the runtime provides a notice; a successful summary does not mean its record was necessarily saved.

Persistent history keeps cumulative counts and the most recent 50 records, accessible after session recovery. Records begin when the feature was introduced in v3.7.12; earlier compactions are not speculatively reconstructed. The before/after comparison describes the estimated context size—it does not measure summary quality, does not prove all facts were preserved, and does not report tokens billed for generating the summary.

Context compaction is a common mechanism for long-session agents: when accumulated conversation history approaches the model's context window limit, the runtime calls the model to generate a summary of earlier messages, replacing the original text with this summary to free space. Compaction is lossy—original tool call details, intermediate reasoning steps, and phrasing are lost, retaining only the key points captured by the summary. Therefore, the "text estimate comparison" before and after compaction only reflects the reduction in context size, not that information was preserved losslessly. This is also why AIClaw emphasizes that records "do not measure summary quality": a session where the post-compaction estimate drops significantly may precisely be a signal that the summary lost critical details, and the panel itself cannot judge this—developers need to review the summary content themselves.

Metadata across the interface, not conversation content

The session/context handler requires a restored session to exist and returns a context status structure. The response includes the model, usage fields, and compaction metadata—not message bodies, prompt text, or tool payloads. The renderer reloads status when session information changes and after related completion events, and its request generation and session checks prevent delayed responses from other chats from replacing the current display.

v3.7.13 replaces the standalone row above the text area with a 24px ring. Hovering shows the estimated percentage or unknown state, and clicking expands details above the toolbar. Refresh, close, and keyboard access functions are preserved, and the compaction control also carries accessibility labels.

session/context handler and request generation: In desktop applications like Electron, the renderer process (interface) and the main process (runtime) communicate via IPC channels. The session/context handler is an interface exposed by the main process that returns only metadata (model name, usage fields, compaction records), not message bodies or prompts—this is both a privacy boundary and a performance consideration, as metadata is far smaller than the full conversation. "Request generation" is a race-condition protection pattern: each status request carries an incrementing sequence number, and when a response returns, the renderer checks whether its sequence number is still the latest; if not (indicating the user has switched to another session and initiated a new request), the response is discarded to prevent stale data from overwriting the new interface. This is especially important during rapid switching between multiple sessions.

What the tests verified

The context tests cover the separation of estimates from provider usage, image byte exclusion, unknown values, the distinction between successful and failed compaction, and the behavior of retaining 50 records after 55 records. Desktop smoke tests use the real Vue/preload interface with fixture responses, checking items including the compaction control, tooltips, unknown window behavior, record display, and refresh after model switching.

The v3.7.13 release notes report 267 renderer/helper tests and 133 work interface checks passing; these are suite totals, not just context tests. The release workflow completed successfully. The release notes also state that live model scenarios were not re-run for this layout change; fixture checks do not establish tokenizer accuracy or summary quality.

Practical implications

The core value of this improvement is that developers can inspect context pressure and recent compaction records while clearly seeing the source and limitations of each number. Showing estimates, configured capacity, and provider-reported usage separately avoids conflating three readings of different natures. For teams relying on long-session agents, this transparency helps more accurately judge when to compact, when to adjust model configuration, and when to pay attention to actual billing data.