Skip to content

feat(tea): compaction fires on input tokens, held image bytes or image count, whichever comes first - #998

Queued
cansirin wants to merge 3 commits into
mainfrom
can/tea-compaction-triggers
Queued

cansirin wants to merge 3 commits into
mainfrom
can/tea-compaction-triggers

Conversation

@cansirin

Copy link
Copy Markdown
Contributor

defineAgent can now compact when any one of five thresholds holds: the existing turn count and input-plus-output context size, plus three new ones. A model with a per-request image budget needs the new ones: a host that compacts only on tokens sends a request the provider refuses once screenshots pile up.

What changed

  • Three new optional triggers on compaction:
    • afterInputTokens: the last brain turn's reported usage.inputTokens, cached tokens included, strictly above N;
    • afterImageBytes: held image payload bytes strictly above B (decoded bytes for base64, byteLength for bytes, 0 for a URL);
    • afterImageCount: held image parts at or above C.
      afterTurns and afterContextTokens keep their meaning exactly (>=, input plus output).
  • One table, one interpreter: the five triggers are rows of COMPACTION_TRIGGER_RULES (satisfies Record<CompactionTriggerTag, …>), read with .some(...), so any number firing at once folds once. The per-trigger if chain is deleted. The at-least-one-trigger type is derived from the keys, not hand-written.
  • Images are counted from the same projection the prompt uses (ToolRouter.partsOf) and recounted from the surviving records after a fold, so a folded image stops counting. No second inventory, no counters in state, no I/O: planCompaction stays pure (invariant 2, ADR 0004).
  • Docs: how-to "bound a run" gains an image-only recipe, and the explanation separates last-turn readings, cumulative spend and held images. The reference and AGENTS.md are regenerated.

Proof

  • compaction-triggers.test.ts, 17 cases through public defineAgent(...).run(...):
    • each trigger fires alone with the others false, and nothing fires when all are false;
    • two triggers true fold once;
    • the boundaries hold: input and bytes are strict, count is inclusive;
    • padded base64, Uint8Array views, URLs, mixed parts and repeated images are counted correctly;
    • stale input usage never re-fires before a fresh reading;
    • a fake image-budget model gets the fold before its next request.
  • Type tests accept each new option alone and combined, and still reject {} and { keepTurns: 2 }.
  • Existing compaction tests are unchanged and green.
  • Gates, all exit 0: tea lint, typecheck, typecheck:test, test (268 files, 5,434 tests), docs:reference and docs:agents plus their checks, and api:ratchet against base 84a500e.

Risk

  • No live provider was called. A URL image's bytes are unknown, so it counts 1 image and 0 bytes.
  • The minimum-two-turn rule, retained tails and a failed summary can still leave a request over a provider limit, as before.

Changeset: minor, Additive (declaration only).

🤖 Generated with Claude Code

cansirin and others added 3 commits November 20, 2026 22:06
Keep legacy context-token semantics and route all thresholds through one pure
facts reader and exhaustive trigger table. Cover boundaries, freshness, media
projection and repeated image-budget crossings through defineAgent.run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Document strict input and byte thresholds, image-only configuration and retained
media limits. Regenerate the public agent reference from its source.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Limit the no-usage skip instruction to token settings, so image-only users
continue to their independent compaction recipe in the same step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cansirin
cansirin added this pull request to the merge queue Nov 21, 2026
Any commits made after this event will not be merged.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant