1# Project Brief: Byte-windowed `read_file` content windows (line-rounded)
  2
  3## Summary
  4
  5This project improves the Agent’s ability to read file contents efficiently by adding a byte-window mode to the `read_file` tool. The Agent will be able to request larger, deterministic content windows using byte offsets, and the tool will round returned output to whole line boundaries. The primary goal is to reduce repetitive paging calls (and associated latency/rate limits) while keeping the returned text easy to reason about and safe to splice into subsequent tool calls.
  6
  7This project is scoped to *paging mechanics* and does not attempt to build a global syntactic map of the codebase.
  8
  9## Background / Problem
 10
 11Today, when the Agent needs more context from a medium/large file, it often falls into a pattern like:
 12
 13- `read_file(path, lines 1-220)`
 14- `read_file(path, lines 220-520)`
 15- `read_file(path, lines 520-720)`
 16- …mixed with `grep` to find landmarks…
 17
 18This is expensive in:
 19- tool-call count (more opportunities to hit rate limits),
 20- latency (many round trips),
 21- model confusion (the model must pick line ranges and frequently underfetch/overfetch).
 22
 23A byte-window API provides:
 24- deterministic forward/back paging by `start_byte`,
 25- the ability to request a larger chunk up front (`max_bytes`),
 26- fewer total tool calls, especially on large files.
 27
 28## Goals
 29
 301. **Enable large, deterministic reads**: Allow the Agent to request file content windows using byte offsets and sizes.
 312. **Round to clean boundaries**: Returned content must be rounded to whole line boundaries (no partial lines).
 323. **Reduce paging calls**: Encourage larger window sizes to reduce repeated reads.
 334. **Maintain backwards compatibility**: Existing line-based reads (`start_line`, `end_line`) must continue to work unchanged.
 345. **Be safe and bounded**: Enforce a server-side cap to prevent extremely large tool outputs.
 35
 36## Non-goals
 37
 38- Providing symbol/outline querying or syntactic navigation of large files.
 39- Building a global codebase index or “syntactic map”.
 40- Altering privacy/exclusion behavior for file access.
 41- Changing how outlines are generated for large files, except where required to support byte windows cleanly.
 42
 43## Proposed Tool Input Changes
 44
 45Extend the `read_file` tool input schema with optional byte-window parameters:
 46
 47- `start_byte: Option<u64>`
 48  - 0-based byte offset into the file.
 49  - When omitted, defaults to `0` in byte-window mode.
 50
 51- `max_bytes: Option<u32>`
 52  - Requested maximum bytes for the window.
 53  - When omitted, a default will be applied (see Defaults & Caps).
 54
 55### Precedence Rules
 56
 571. If `start_line` or `end_line` is provided, treat the call as line-range mode (existing behavior).
 582. Otherwise, if `start_byte` or `max_bytes` is provided, treat the call as byte-window mode.
 593. Otherwise, preserve current behavior (small file full content, large file outline fallback).
 60
 61## Byte-window Mode Semantics
 62
 63### Window selection
 64
 65Given:
 66- `start = start_byte.unwrap_or(0)`
 67- `requested_len = max_bytes.unwrap_or(DEFAULT_MAX_BYTES)`
 68- `end = start + requested_len`
 69
 70The implementation will clamp to file length and adjust to safe UTF-8 boundaries before converting to internal points/ranges.
 71
 72### Line rounding
 73
 74The returned content must be rounded to line boundaries:
 75
 76- Start is snapped to the beginning of the line containing `start`.
 77- End is snapped so the output includes only whole lines (typically to the beginning of the next line after `end`, or to end-of-file).
 78
 79The key property: **no partial lines** are returned.
 80
 81### Deterministic paging
 82
 83The Agent should be able to page by setting `start_byte` to the prior returned window end (or a tracked byte offset) and requesting another window.
 84
 85To support this, the tool may optionally include the effective returned byte range in the output (as a short header) so the Agent can page precisely.
 86
 87## Defaults & Caps
 88
 89### Defaults
 90
 91- `DEFAULT_MAX_BYTES`: A conservative default that is large enough to reduce paging (e.g., 64KiB), but small enough to keep tool outputs manageable.
 92
 93### Hard cap
 94
 95- `HARD_MAX_BYTES`: A strict server-side maximum (e.g., 256KiB) applied even if a larger `max_bytes` is requested.
 96
 97If the Agent requests more than `HARD_MAX_BYTES`, the tool will clamp the request to `HARD_MAX_BYTES`.
 98
 99## Edge Cases / Special Handling
100
101- **Single extremely long line**: If a single line is longer than `HARD_MAX_BYTES`, rounding to full lines can cause a window to exceed the cap. The implementation must define behavior for this case. Recommended approach:
102  - Prefer whole-line output; however, if a single line exceeds the hard cap, allow returning that line truncated with an explicit note, or fall back to returning a bounded slice with clear markers. The chosen behavior must remain deterministic and avoid invalid UTF-8.
103
104- **Files larger than the “auto-outline” threshold**: Byte-window mode should allow reading chunks even for large files (where the default no-args call would return an outline). This enables efficient paging without requiring the Agent to switch to line ranges.
105
106- **UTF-8 safety**: Byte offsets must not split multi-byte characters.
107
108## UX Guidance for the Agent
109
110The tool documentation should recommend:
111
112- Use `max_bytes` generously (up to the hard cap) when you expect to need more context, to reduce paging and rate-limit pressure.
113- Prefer byte-window paging for “continue reading” workflows; use line ranges when following up on outline-provided line numbers.
114
115## Telemetry / Observability (optional)
116
117If available, log:
118- number of `read_file` calls per task,
119- average output size,
120- frequency of paging patterns (repeated reads of same file),
121- rate-limit related failures.
122
123This will validate that the change reduces tool-call volume in practice.
124
125## Acceptance Criteria
126
127- `read_file` accepts `start_byte` and `max_bytes` and returns content rounded to whole lines.
128- Output is safe UTF-8 and does not panic on boundary conditions.
129- A single call can return a substantially larger chunk than typical line-based paging patterns, reducing follow-up reads.
130- Existing `start_line` / `end_line` behavior remains unchanged.
131- Large file default behavior (outline) remains unchanged when byte-window parameters are not provided.
132
133## Out of Scope Follow-up
134
135A separate project will address “global syntactic navigation” (e.g., outline querying, codebase-wide symbol maps, and syntactic retrieval interfaces). This brief intentionally does not cover that work.