@nhtio/adk/batteries/context/thrift/subtractive_pass
The subtractive pass — the whole Token Thrift thesis, in code.
Remarks
A context window is NOT a chat history. It is just what you send for ONE dispatch. So: hold a large WORKING set (messages, memories, retrievables, thoughts, an image, tools), then SUBTRACT it down to the high-signal slice that fits the active model's window — focus, don't accumulate.
This module is the model-facing plane only. Where the human-facing chat history lives (a SQLite store, an in-memory array, anything else) is entirely the caller's concern — this battery never touches it. Everything here is window-agnostic: the same function runs at contextWindow: 4096 and contextWindow: 1_000_000 — the span is a parameter, not a rewrite.
This is a direct extraction of the flagship reference agent's production subtractive pass (evaluated head-to-head across five models — see the battery barrel's TSDoc for the results), retargeted at the local structural contracts in @nhtio/adk/batteries/context/thrift/contracts so it couples to nothing in @nhtio/adk core — every value it reads is duck-typed, and its one true dependency (token estimation) is an injected function, never a bundled tokenizer.
Interfaces
| Interface | Description |
|---|---|
| BucketTrace | A line in the "what got cut" trace — one bucket's before/after token weight. |
| EstimatorOptions | Options shared by every entry point in this module that needs to measure a value's token cost — the injected estimator plus the encoding it measures under. |
| SubtractToFitOptions | Options accepted by subtractToFit. estimateTokens (via EstimatorOptions) is the only option with no default; every other field is a calibrated default, documented on its own declaration below, that a caller can override. |
| ThriftTrace | The full record of one subtractive pass — before/after weights per bucket, and whether the dispatch ultimately fits the budget. |
| WorkingSet | The mutable working set a dispatch starts from — the "everything reasonable" set this pass subtracts down to what fits. Every field is a local structural type from @nhtio/adk/batteries/context/thrift/contracts — nothing here requires a core ADK value. |
Variables
| Variable | Description |
|---|---|
| DEFAULT_ENCODING | The token encoding this battery measures under, by default. |
| DEFAULT_RESERVE_FRACTION | Fallback output reserve, as a fraction of the window, used ONLY when the exact max-output budget is unknown. |
| DEFAULT_THIS_TURN_RESULT_KEEP | How many of the NEWEST this-turn tool-result bodies to protect from budget-shedding as a last-resort backstop, by default. |
Functions
| Function | Description |
|---|---|
| resolveBudget | Resolve the per-dispatch INPUT token budget from the ACTIVE model's window: the window minus the room held back for the model's own output. The same call works for a 4K model and a 1M model. |
| stripPriorTurnThoughts | Gemma model card §3 — "No Thinking Content in History": thoughts from previous model turns MUST NOT be re-added before the next user turn. Enforced here as a standalone, callable step (not a silent battery-wide flag), because it is also pure thrift: prior-turn reasoning is the highest-volume, lowest-reuse content a working set carries. |
| subtractToFit | The subtractive pass. Start wide; measure every bucket; then shed lowest-signal first until the dispatch fits the active window's budget — the image (the single biggest hog) goes first when it doesn't fit, then tools the turn doesn't need, the tail of the retrieval ranking, low-value memories, the oldest conversation turns. Each cut is by EVIDENCE (a measured bucket), never a guess. If even the floor (system prompt + newest turn) won't fit, the dispatch REFUSES (fits: false) — a bounded refusal beats a truncated, incoherent dispatch. |
References
EstimateTokensFn
Re-exports EstimateTokensFn
IsEphemeralMessageFn
Re-exports IsEphemeralMessageFn
IsSummaryMessageFn
Re-exports IsSummaryMessageFn
RenderToolsFn
Re-exports RenderToolsFn
ShedRankFn
Re-exports ShedRankFn
WorkingImage
Re-exports WorkingImage
WorkingMemory
Re-exports WorkingMemory
WorkingMessage
Re-exports WorkingMessage
WorkingRetrievable
Re-exports WorkingRetrievable
WorkingThought
Re-exports WorkingThought
WorkingTool
Re-exports WorkingTool
WorkingToolCall
Re-exports WorkingToolCall
WorkingToolRegistry
Re-exports WorkingToolRegistry