Interface: SubtractToFitOptions
Defined in: src/batteries/context/thrift/subtractive_pass.ts:211
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.
Remarks
Earlier positional-argument forms of this function (as it existed in the flagship reference agent this battery was extracted from) took outputReserve, keepThoughtIds, renderTools, protectThoughtIds, renderCtx, and protectedToolNames as seven trailing positional parameters. They are collected here into one options object to keep the call site legible and to give each a documented default — the mapping from the old positional order to these keys is: position 4 → outputReserve, 5 → keepThoughtIds, 6 → renderTools, 7 → protectThoughtIds, 8 → renderCtx, 9 → protectedToolNames.
Extends
Properties
| Property | Type | Description | Inherited from | Defined in |
|---|---|---|---|---|
encoding? | string | The encoding to measure under. Default: DEFAULT_ENCODING. | EstimatorOptions.encoding | src/batteries/context/thrift/subtractive_pass.ts:194 |
estimateTokens | EstimateTokensFn | REQUIRED. Measures a rendered string's token cost under encoding, optionally resolved against a live dispatch context. There is no default — this battery ships with no bundled tokenizer, so a caller who omits this gets a clear thrown error naming the option, not a silent guess. | EstimatorOptions.estimateTokens | src/batteries/context/thrift/subtractive_pass.ts:192 |
isEphemeralMessage? | IsEphemeralMessageFn | Decides whether a message is an ephemeral control message (step 6) — re-derived fresh every dispatch iteration, never persisted, so only the LATEST surviving copy carries live information. Default: (m) => m.id.startsWith('__eph-'), the flagship reference agent's own convention. A caller with a different (or no) ephemeral-message convention should override this; the default simply never matches when a caller's ids don't use that prefix, degrading step 6 to a no-op. | - | src/batteries/context/thrift/subtractive_pass.ts:298 |
isSummaryMessage? | IsSummaryMessageFn | Decides whether a message is a summarizing strategy's load-bearing running summary (step 7) — content that stands in for every older turn that strategy folded away, and so must never be shed like an ordinary old turn even though it renders as the chronologically oldest message. Default: (m) => m.id === '__compact-summary', the flagship reference agent's own convention for its paired summarizing ("compact") strategy. Callers who never run a summarizing strategy alongside this battery can ignore this option entirely — the default predicate simply never matches. | - | src/batteries/context/thrift/subtractive_pass.ts:307 |
keepThoughtIds? | ReadonlySet<string> | Thought ids to PRESERVE through the prior-turn strip (step 1) — e.g. a planner's synthetic THIS-TURN plan thought, which is fresh guidance generated for the current request (not prior-turn chain-of-thought, and not subject to the §3 policy above). Everything else is dropped when stripping is enabled. Omit to drop every thought when stripping is enabled. | - | src/batteries/context/thrift/subtractive_pass.ts:243 |
outputReserve? | number | The EXACT number of tokens to hold back for the model's own output — pass the generation maxTokens the model is configured with. When omitted, falls back to DEFAULT_RESERVE_FRACTION of the window (a guess, for callers that don't know the cap). Clamped so the reserve never exceeds the window. Forwarded to resolveBudget. | - | src/batteries/context/thrift/subtractive_pass.ts:218 |
protectedToolNames? | ReadonlySet<string> | Tool names the caller's CURRENT PLAN has committed to that have NOT yet been called this turn. These are UNSHEDDABLE by the last-resort tool shed (step 9) until every other tool has already shed — removing a plan-committed tool from the visible set leaves the model instructed to call a tool it can no longer see. The protection is bounded: once the tool HAS been called (its result is already in context) it should be dropped from this set by the caller, so it is never a permanent floor. Omit to make every visible tool sheddable on equal footing. | - | src/batteries/context/thrift/subtractive_pass.ts:279 |
protectThoughtIds? | ReadonlySet<string> | Thought ids that must NEVER be shed for budget (step 8) even when the dispatch is over — the this-turn scaffolding the model needs to answer at all (e.g. a plan thought + a citation reinforcement thought). Everything else in the surviving keep-set (per-iteration nudge thoughts, older synthetic guidance) is sheddable oldest-first when the dispatch still doesn't fit. This is a SUBSET of keepThoughtIds: keepThoughtIds decides what survives the prior-turn strip (step 1); protectThoughtIds decides what additionally survives the budget shed (step 8). Omit to make every surviving thought sheddable. | - | src/batteries/context/thrift/subtractive_pass.ts:261 |
renderCtx? | unknown | The live dispatch context, so a DYNAMIC (evaluatable) value's token count reflects the string it will resolve to for THIS dispatch — forwarded as the ctx argument to estimateTokens. Without it, a dynamic value is measured at its no-ctx fallback size, and the budget can disagree with what the caller's own battery ships (an under-count, since evaluated content is typically LARGER than its static form — e.g. an interpolated system prompt). Optional; static content measures identically with or without it. | - | src/batteries/context/thrift/subtractive_pass.ts:270 |
renderTools? | RenderToolsFn | The caller's tool-declaration renderer. When supplied, the tools bucket is measured against the REAL rendered tool-definitions block (e.g. full JSON-Schema per tool) instead of a name: description proxy — the proxy can undercount a schema-heavy tool block by an order of magnitude relative to what actually gets dispatched. Omit to fall back to the proxy (keeps this battery usable standalone, without a real tool-rendering pipeline, e.g. in tests). | - | src/batteries/context/thrift/subtractive_pass.ts:251 |
reserveFraction? | number | The fallback reserve fraction used when outputReserve is omitted. Default: DEFAULT_RESERVE_FRACTION. Forwarded to resolveBudget. | - | src/batteries/context/thrift/subtractive_pass.ts:223 |
shedRank? | ShedRankFn | Ranks a tool by last-resort shed priority for step 9 (lower sheds first). Default: a single generic tier — every tool ranks equally, so the shed proceeds in the order relevantToolNames listed them (a stable sort preserves input order when every rank ties). This battery has no domain knowledge of which of a caller's tools are cheap-to-lose "gather" tools versus load-bearing "delivery" tools, so it does not guess a tiering. A caller WHO DOES have that knowledge (as the flagship reference agent does — it ranks ~90 known tool names into seven tiers, sheds its provide_answer tool before its core artifact readers, etc.) should inject a ShedRankFn that encodes it; see ShedRankFn for the contract. | - | src/batteries/context/thrift/subtractive_pass.ts:290 |
stripPriorTurnThoughts? | boolean | Whether to apply the prior-turn thought strip (step 1) at all. Default true. Remarks The default is driven by Gemma's model card §3, "No Thinking Content in History": thoughts from previous model turns must not be re-added before the next user turn. This is also pure thrift — prior-turn reasoning is the highest-volume, lowest-reuse content there is, Gemma or not — so the default stays true even for callers on a different model family; a caller whose model genuinely benefits from replaying its own prior chain-of-thought (uncommon) can set this false to skip the strip entirely and let every thought flow into the later per-thought budget shed (step 8) instead. | - | src/batteries/context/thrift/subtractive_pass.ts:236 |
thisTurnResultKeep? | number | How many of the NEWEST this-turn tool-result bodies the newest-N backstop (step 3b) protects from shedding once ordinary prior-turn shedding is exhausted and the dispatch still doesn't fit. Default: DEFAULT_THIS_TURN_RESULT_KEEP. | - | src/batteries/context/thrift/subtractive_pass.ts:313 |