refactor(runtime): unify ArchiveRead canonical document and response-budget ownership
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
Part of #4267. Follow-up to #4355 and #4380.
## Motivation
The ArchiveRead retrieval work in #4380 fixes the immediate correctness failures (non-advancing line pagination, Unicode search coordinates, and inspect response overflow), but the review also exposed a structural issue: coordinate semantics and response-budget fitting are currently implemented by several independent branches.
The follow-up should make the invariants explicit without expanding #4380 or breaking its line-facing contract.
## Proposed scope
- Introduce one canonical archive-document projection for plain text, terminal pipes, PTY streams, and structured JSON.
- Make internal read/search coordinates derive from that document authority.
- Keep the public `unit: "line"` / line-offset facade from #4355 while allowing the implementation to use character ranges internally.
- Introduce one field-aware `fitArchiveResponse()` owner for the final `TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS` envelope across inspect, read, query, and search.
- Optimize line reads so large windows do not repeatedly materialize and stringify the same content.
- Define the coordinate/ref contract for queryable `items[]` subdocuments.
- Add operation × payload-shape regression/property tests for the response-size invariant and continuation progress.
## Non-goals
- Do not change the shell capture/preservation contract or recover output already dropped before archiving.
- Do not reopen archive threshold policy.
- Do not remove or silently change the line-oriented API in the first iteration.
## Acceptance
- Every successful and failure ArchiveRead response stays within the configured response budget after final serialization.
- Search offsets, snippets, and continuations are in the documented canonical coordinate space.
- Line reads either return progress or an actionable bounded failure for an oversized line.
- Long accepted search patterns remain representable without silent truncation.
- Existing #4355 behavior and current `ArchiveRead` refs remain backward compatible.
Contributor guide
Research direction
Start by reading ArchiveRead and the referenced #4355 and #4380 behavior, then trace how plain text, terminal or PTY streams, and structured JSON are represented. Define the canonical coordinate and response-budget ownership boundaries before changing implementation. Done means the listed operations preserve the line-facing contract, make continuation progress, and remain within the configured budget after serialization.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, testing
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100