fix: document --budget item-boundary semantics and announce oversized items - #63
Merged
Conversation
… items --budget cuts at item boundaries and always emits at least one item, so a single oversized item can exceed the budget — intentional, but undocumented, and with --offset leaving nothing after that item the overflow was completely silent. Announce it on stderr (including in envelope mode), measure JSON budgets against the pretty-printed form that is actually written, and state the semantics in --help, README, and the agent context. Closes #60 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #60, taking all three asks:
--help, README, andsrc/agent-context.txtnow state that--budgetcuts at item boundaries, never splits an item, and always emits at least one, so a single oversized item can exceed the budget.ax: note: emitted item is ~N tokens — over --budget (…). This fires in--json-envelopemode too: continuation info lives inmeta, but this is a warning, so never-silent wins. The issue's--offset 1 --budget 1repro — previously byte-for-byte silent at ~1600x over — now announces.JSON.stringify(v, null, 2), the pretty-printed form actually written, instead of the compact form that systematically undercounted.The always-emit-one behavior itself is unchanged — an empty result for a small budget would be useless, and #40's resume tests pin it.
metais untouched: the envelope contract gains no fields.Tests
One new CLI test pinning: the previously-silent
--offsetoverflow announces, no note when items fit, and the warning reaches stderr in envelope mode withmeta.statestillcomplete.bun test test/: 159 pass.tsc --noEmitandoxfmt --checkclean.🤖 Generated with Claude Code