feat(sdk): report remaining lines for paginated reads

[Mason Daugherty (mdrxy)]

Closes #2142

Credit to Shawn (@kevinWangSheng) for making an earlier attempt at this!

read_file now reports when a paginated read returns only part of a text file, including the source-line range returned, total line count, remaining line count, and next offset to pass for the following page.

External backends implementing the current BackendProtocol continue to work unchanged.

---

Previously, callers could request a limited window and receive line-numbered content, but they had to infer whether more lines existed and what offset would resume the read. That was especially fragile for sandboxed reads that can be byte-capped before the requested line window is fully rendered.

Implementation

• Extended ReadResult with optional pagination metadata for the returned source-line range, total line count, and next offset. The existing error and file-data fields remain unchanged, so external backends do not need to adopt the new metadata immediately.
• Updated the built-in state, store, filesystem, and sandbox backends to populate that metadata for text reads. Sandbox-backed reads keep line counting bounded for large files and avoid advancing past content hidden by output-size limits.
• Updated FilesystemMiddleware to turn the metadata into the model-facing notice. If its own token limit shortens the result further, it recalculates the visible range and resume offset so subsequent reads do not skip lines.
• Added backend and middleware coverage for partial reads, EOF, offsets, output truncation, and compatibility, plus an end-to-end eval for the resulting agent behavior.

Example output

A partial read now includes the returned line range, total line count, and next offset:

     1	one
     2	two

[Read 2 lines (lines 1-2 of 5 total). 3 lines remaining from offset 2.]

Offset reads report the original source-line range instead of starting the notice from line 1:

     3	three
     4	four

[Read 2 lines (lines 3-4 of 5 total). 1 line remaining from offset 4.]

Reads that reach EOF keep the existing output shape and omit the footer:

     1	one
     2	two
     3	three

Evaluation

The test_read_file_remaining_lines_notice_enables_tail_jump eval asks the agent to find the last non-empty line of a 301-line file using read_file directly. The target value is outside the first 100-line page, so the agent must determine where to read next.

Both main and this PR returned the correct value. With the remaining-line notice, both tested models used the first page's metadata to jump near the tail in one additional read:

Model	Version	Agent steps	Tool calls	Duration
GPT-5.5	main	4	6	13.1s
GPT-5.5	This PR	3	2	8.4s
Claude Sonnet 4.6	main	4	3	8.1s
Claude Sonnet 4.6	This PR	3	2	5.5s

Across three additional runs per model and version, this PR used exactly two tool calls in all six runs, while main required three to six calls. The eval preserves correctness as a hard requirement and records three agent steps, two tool calls, and two direct read_file calls as the expected efficient trajectory.

[corridor-security]

The sandbox read loop scans to EOF unconditionally to compute total_lines, allowing a caller to force unbounded file I/O on arbitrarily large files even when requesting a tiny page (e.g. limit=1), enabling CPU/I/O exhaustion on the sandbox worker.

[open-swe]

Open SWE Review found 2 potential issues.

Open in Web • View Open SWE trace

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

[github-actions]

ℹ️ PR scope/file mismatch acknowledged via the allow-scope-mismatch label.

Title scope(s): sdk

Touched package dir(s) not covered by those scopes:

• package label evals from libs/evals/

Remove the label to re-enable the block.