Retrieval-first Context Packets

src/context/retrieval-packet.ts provides ContextPacket — a token-bounded, structured summary of large tool results. It sits between the tool executor and the message history: when a search result would balloon the context, the packet replaces the raw JSON before it reaches the model.

When compression is applied

maybeCompressSearchResult() intercepts every completed search.rg and search.files result. Compression triggers when:

estimateTextTokens(JSON.stringify(toolResult.output)) > 1 500

Results under 1 500 tokens (~6 000 chars) are passed through as-is.

Packet token caps per mode

Mode	Max packet tokens
plan	1 000
agent	2 000
full	2 000
exec	3 000

search.rg packet

Files are sorted by match count descending — the most relevant file appears first. For each file, only the top snippet (first match, max 200 chars) is kept. Binary files are detected via a 512-byte scan for non-printable control characters and marked [binary file — skipped]. Language is detected from extension (TypeScript, Python, Rust, Go, etc.) and annotated inline.

Output format:

[Context packet: search.rg]
Query: MyClass
Files considered: 42 | 87 match(es) across 42 file(s); ranked by match count
src/core/my-class.ts:14:0: (typescript) export class MyClass implements ...
src/tests/my-class.test.ts:3:0: (typescript) import { MyClass } from ...
... [truncated — 1847 tokens used of budget]

search.files packet

No ranking — files are listed in scan order up to the token cap. Language tag added per extension.

Exact references preserved

Every file:line:column reference in the packet is kept verbatim. The model can use these directly in subsequent fs.read or search.rg calls without re-searching. This is the “retrieval-first” contract: search to find the location, then read only what you need.