Skip to content

Improve source read efficiency and model compatibility - #867

Open
anandh8x wants to merge 4 commits into
mainfrom
feat/structural-code-query
Open

Improve source read efficiency and model compatibility#867
anandh8x wants to merge 4 commits into
mainfrom
feat/structural-code-query

Conversation

@anandh8x

@anandh8x anandh8x commented Aug 4, 2026

Copy link
Copy Markdown
Collaborator

What changed

  • add bounded compact source reads with safe Go fragment parsing and conservative fallback behavior
  • standardize the model-facing read_file contract on path, offset, and limit
  • retain legacy line and byte arguments internally, with mixed legacy calls preferring the line range instead of failing
  • expose one case-sensitivity argument for grep
  • make compact source reading available up front and clarify when exact reads and plans are appropriate
  • add regression coverage for canonical ranges, mixed legacy arguments, schema exposure, and Go fragments

Why

The previous read_file schema exposed overlapping line and byte pagination systems. Some models combined both systems in one request, producing deterministic argument failures and repeated retries until the loop guard stopped the run. The canonical contract removes that ambiguity while preserving compatibility for existing callers.

GPT-5.5 benchmark

Identical read-only inspection prompt against the Zero source tree:

Build Time Tokens Result
Before 40.3s 10,859 stopped after six invalid read_file calls
After 19.4s 13,219 completed with one search, two successful reads, and no plan calls

The pre-change token total is lower only because the task halted without producing the requested answer; the primary measured improvement is successful completion without the invalid-call loop.

Validation

  • make fmt-check
  • go vet ./...
  • go test ./... with an isolated empty user config root
  • go run ./cmd/zero-release build
  • go run ./cmd/zero-release smoke
  • make lint-static
  • make vulncheck
  • git diff HEAD --check

Summary by CodeRabbit

  • New Features
    • Added offset/limit line-range selection for both source and minified-source reading.
    • Improved Go minification for standalone and context-aware fragments, including safer handling of partial code.
  • Bug Fixes
    • Updated truncation/out-of-range messaging and continuation hints to use canonical range terminology.
    • Refined tool behavior and schemas (e.g., case-insensitive option documentation).
  • Documentation
    • Clarified planning requirements for update_plan and standardized source-exploration guidance.
  • Tests
    • Expanded coverage for ranged reads, minification edge cases, and planning/range validation.

@coderabbitai

coderabbitai Bot commented Aug 4, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 778149f6-b1cc-49ae-b4c8-2672a35441f0

📥 Commits

Reviewing files that changed from the base of the PR and between 3aa190b and e3337d0.

📒 Files selected for processing (2)
  • internal/tools/read_minified_file.go
  • internal/tools/read_minified_file_test.go
🚧 Files skipped from review as they are similar to previous changes (2)
  • internal/tools/read_minified_file_test.go
  • internal/tools/read_minified_file.go

Walkthrough

The change adds bounded Go-fragment minification, canonical offset/limit source-range parameters to read_file and read_minified_file, ranged minified reads with recalculated metrics, and revised agent guidance that limits update_plan and prefers read_minified_file for initial source exploration.

Changes

Source reading workflow

Layer / File(s) Summary
Go fragment minification
internal/minify/minify.go, internal/minify/minify_test.go
minify.File now tries bounded Go-fragment parsing after full-file parsing fails. Fragment finds the longest parseable declaration or statement prefix, prints valid AST nodes, and keeps incomplete tails through conservative normalization. ContextualFragment uses token scanning to avoid standalone parsing when a range starts inside a string or comment. Fragments over 512 lines are rejected. Tests cover fragment compaction, declaration prefixes, the 512-line cap, and conservative fallback.
Canonical read_file line ranges
internal/tools/read_file.go, internal/tools/file_tools_test.go, internal/tools/file_safety_test.go
read_file now exposes canonical offset and limit line-range parameters. Parsing prefers canonical arguments, falls back to legacy line arguments, and keeps byte mode only when no line range is supplied. Messages and truncation hints use offset/limit. Tests cover canonical reads, out-of-range offsets, legacy precedence, schema shape, and edit authorization from a bounded read.
Ranged minified reads with fragment minification
internal/tools/read_minified_file.go, internal/tools/read_minified_file_test.go
read_minified_file now accepts optional offset and limit parameters. It selects source lines first, switches to contextual fragment minification for ranged reads, and recomputes metrics from the selected content. Output text and byte-budget guidance use ranged-read terminology. Tests cover source selection, lexical preservation in ranged reads, and past-end offsets.
Tool guidance and registry wiring
internal/tools/registry.go, internal/tools/registry_test.go, internal/tools/grep.go, internal/tools/update_plan.go, internal/tools/file_tracker.go, internal/agent/system_prompt.md, internal/agent/system_prompt_models.go, internal/cli/deferred_wiring_test.go, internal/tools/file_tools_test.go
read_minified_file is registered before read_file and treated as an eager builtin. The grep schema drops the documented -i parameter. update_plan guidance now applies only to implementation or investigation tasks with at least three meaningful dependent steps. Agent prompts match that threshold and prefer read_minified_file for initial exploration. File-tracker messaging uses offset/limit. Tool-schema tests and deferred-builtin tests were updated to match the new metadata.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

  • Gitlawb/zero#838: This PR also changes internal/agent/system_prompt.md in the same planning and editing-discipline area.

Suggested reviewers: gnanam1990, kevincodex1, vasanthdev2004

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 8.70% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main objective: improving source read efficiency through bounded compact reads and standardizing parameters, while also enhancing model compatibility through clarified tool contracts and guidance updates.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/structural-code-query

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/minify/minify.go`:
- Around line 59-61: Update the line-count logic in the minification flow around
strings.Split to remove one trailing empty element when the normalized content
ends with a newline before enforcing the 512-line limit. Preserve rejection
above 512 source lines, and add a regression test covering 512 statements
followed by a final newline that remains eligible for minification.

In `@internal/tools/read_file.go`:
- Around line 34-40: The renderReadFileRange out-of-range error still refers to
the removed start_line field, conflicting with the public schema. Update
renderReadFileRange to name the canonical offset parameter in that user-visible
message while preserving the existing range validation behavior.

In `@internal/tools/read_minified_file.go`:
- Around line 87-88: The ranged minification flow must preserve lexical state
instead of passing context-free fragments to minify.File. Update
selectSourceLines and the surrounding read logic in
internal/tools/read_minified_file.go at lines 87-88 and 131-144 to use only safe
ranges, retain scanner context, or apply whitespace-only normalization for
unsafe ranges; add or update coverage in
internal/tools/read_minified_file_test.go at lines 48-60 for ranges beginning
inside multiline strings, template literals, and block comments.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 794b02e9-666a-47f6-af12-98f2ac92e34f

📥 Commits

Reviewing files that changed from the base of the PR and between 91b413c and a394fd6.

📒 Files selected for processing (14)
  • internal/agent/system_prompt.md
  • internal/agent/system_prompt_models.go
  • internal/cli/deferred_wiring_test.go
  • internal/minify/minify.go
  • internal/minify/minify_test.go
  • internal/tools/file_tools_test.go
  • internal/tools/file_tracker.go
  • internal/tools/grep.go
  • internal/tools/read_file.go
  • internal/tools/read_minified_file.go
  • internal/tools/read_minified_file_test.go
  • internal/tools/registry.go
  • internal/tools/registry_test.go
  • internal/tools/update_plan.go
💤 Files with no reviewable changes (1)
  • internal/tools/grep.go

Comment thread internal/minify/minify.go
Comment thread internal/tools/read_file.go Outdated
Comment thread internal/tools/read_minified_file.go Outdated
coderabbitai[bot]
coderabbitai Bot previously approved these changes Aug 4, 2026
@anandh8x
anandh8x marked this pull request as ready for review August 4, 2026 16:10
@github-actions

github-actions Bot commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Zero automated PR review

Verdict: No blockers found

Blockers

  • None found.

Validation

  • [pass] Diff hygiene: git diff --check
  • [pass] Tests: go test ./...
  • [pass] Build: go run ./cmd/zero-release build
  • [pass] Smoke build: go run ./cmd/zero-release smoke

Scope

Head: e3337d06d58c
Changed files (15): internal/agent/system_prompt.md, internal/agent/system_prompt_models.go, internal/cli/deferred_wiring_test.go, internal/minify/minify.go, internal/minify/minify_test.go, internal/tools/file_safety_test.go, internal/tools/file_tools_test.go, internal/tools/file_tracker.go, internal/tools/grep.go, internal/tools/read_file.go, internal/tools/read_minified_file.go, internal/tools/read_minified_file_test.go, and 3 more

This deterministic review checks validation status and basic diff hygiene. A human reviewer still owns product judgment and design quality.

@Vasanthdev2004 Vasanthdev2004 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes: the new offset/limit pair cannot be used before an edit.

limit caps the range [offset, EOF] rather than defining the range, so any interior slice comes back flagged truncated. The registry then skips RecordSeenRange and the edit is refused, with a message telling the model to re-read using offset/limit, which is the call that just failed. The start_line/end_line pair this PR deletes from the schema is the only shape that still works:

offset=500 limit=10          truncated=true   reason="limit"   seen=""         edit refused
offset=500 (runs to EOF)     truncated=false                   seen=500-1000   edit ok
start_line=500 end_line=509  truncated=false                   seen=500-509    edit ok

1000 line file, driven through Registry.RunWithOptions.

Three others, all reproducible:

Ranged Go reads corrupt raw strings. A range that starts inside a raw string literal is parsed as code, so string content is deleted and identifiers are rewritten. SECRET-MARKER-ONE comes back as SECRET - MARKER - ONE, a line inside the string vanishes, and the header reports a 49% saving. Fragment's own doc says non-Go takes the conservative path because a range may begin inside a multiline string. Go needs the same guard.

Dropping byte_offset/byte_limit from the schema and from the unseen-file message leaves any file with a line over 128KB unreadable, and so uneditable. The byte path still works, and file_tracker_largefile_test.go still asserts it is what makes those files writable again.

Mixing one canonical and one legacy argument silently reads the wrong lines: {start_line: 5, limit: 2} returns lines 1 and 2.

Minor: read_minified_file with an offset past EOF returns an empty body with status ok, where read_file says the offset is past the end.

@Vasanthdev2004

Copy link
Copy Markdown
Collaborator

@anandh8x the blocking one is the offset/limit range, the rest are smaller. limit caps [offset, EOF] instead of defining the range, so an interior slice gets flagged truncated, never earns read credit, and the edit after it is refused. A slice that happens to reach EOF passes cleanly, which is why the tests here do not show it.

Two ways out and I would take the first: make limit set endLine so the read is not flagged truncated at all, or stop treating a limit cut as a byte-budget cut at the point the registry commits the observation. The second one reaches further than this PR needs to.

I have the probe that produced the table in the review, driven through Registry.RunWithOptions. Say the word and I will push it as a test on your branch.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/tools/file_safety_test.go`:
- Around line 318-323: Update the read_file line-range accounting so an offset
of 500 with limit 10 produces the inclusive range 500-509. In the relevant
read_file range-processing flow, calculate the bounded end as offset + limit - 1
and apply it before rendering, ensuring exact bounded reads receive seen_lines
metadata of 500-509.

In `@internal/tools/read_minified_file.go`:
- Around line 163-164: Update the range-end calculation in the
read-minified-file logic to compare limit against end-start before adding,
preventing integer overflow while preserving the existing limit behavior. Add a
regression test covering a maximum-int limit with a nonzero offset and verify
the resulting slice does not panic.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e278e93d-5cd5-485d-b4fd-949bdb05bbe6

📥 Commits

Reviewing files that changed from the base of the PR and between 00ad4d4 and 3aa190b.

📒 Files selected for processing (7)
  • internal/minify/minify.go
  • internal/tools/file_safety_test.go
  • internal/tools/file_tools_test.go
  • internal/tools/file_tracker.go
  • internal/tools/read_file.go
  • internal/tools/read_minified_file.go
  • internal/tools/read_minified_file_test.go
🚧 Files skipped from review as they are similar to previous changes (3)
  • internal/tools/file_tracker.go
  • internal/tools/file_tools_test.go
  • internal/tools/read_file.go

Comment on lines +318 to +323
if read.Status != StatusOK || read.Truncated {
t.Fatalf("bounded canonical read must be exact: status=%s truncated=%v meta=%#v", read.Status, read.Truncated, read.Meta)
}
if read.Meta["seen_lines"] != "500-509" {
t.Fatalf("bounded canonical read did not receive exact-read credit: %#v", read.Meta)
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

ast-grep outline internal/tools/read_file.go --items all
rg -n -C 10 'offset|limit|endLine|Truncated|RecordSeenRange' \
  internal/tools/read_file.go internal/tools/file_tracker.go

Repository: Gitlawb/zero

Length of output: 26265


🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '--- internal/tools/read_file.go relevant sections ---\n'
sed -n '1,290p' internal/tools/read_file.go
printf '\n--- internal/tools/file_tracker.go RecordSeenRange ---\n'
sed -n '100,210p' internal/tools/file_tracker.go

printf '\n--- tests around bounded canonical read ---\n'
sed -n '260,335p' internal/tools/file_safety_test.go

printf '\n--- file_tracker references to Result.Truncated and seen ranges ---\n'
rg -n -C 4 'Result|Truncated|RecordSeenRange|SeenRange|seen_lines|pendingFileObservation' internal/tools -g '*.go'

Repository: Gitlawb/zero

Length of output: 241


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- internal/tools/read_file.go relevant sections ---'
sed -n '1,290p' internal/tools/read_file.go
echo '--- internal/tools/file_tracker.go RecordSeenRange ---'
sed -n '100,210p' internal/tools/file_tracker.go

echo '--- tests around bounded canonical read ---'
sed -n '260,335p' internal/tools/file_safety_test.go

echo '--- file_tracker references to Result.Truncated and seen ranges ---'
rg -n -C 4 'Result|Truncated|RecordSeenRange|SeenRange|seen_lines|pendingFileObservation' internal/tools -g '*.go'

Repository: Gitlawb/zero

Length of output: 50369


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- internal/tools/read_file.go relevant sections ---'
sed -n '1,290p' internal/tools/read_file.go

echo '--- internal/tools/file_tracker.go RecordSeenRange ---'
sed -n '100,210p' internal/tools/file_tracker.go

echo '--- internal/tools/file_safety_test.go test body ---'
sed -n '260,335p' internal/tools/file_safety_test.go

echo '--- registry CommitFileObservation and budget helper definitions ---'
sed -n '230,265p' internal/tools/registry.go
rg -n -C 3 'type outputBudgetBuilder|func .*Output|func .*Budget|Retruncated|Truncated|Reduce' internal/tools -g '*.go' | sed -n '1,260p'

Repository: Gitlawb/zero

Length of output: 37277


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- output boundary implementation ---'
sed -n '1,112p' internal/tools/output_boundary.go
rg -n -C 4 'type budgetedOutput|func budgetSemanticOutput|func newHeadTailOutputBucket|func newOutputBudget|Truncated|Truncate|text' internal/tools/output_boundary.go internal/tools -g '*.go' | sed -n '1,260p'

echo '--- TestCanonicalLimitedReadAuthorizesEdit ---'
grep -n -C 25 'func TestCanonicalLimitedReadAuthorizesEdit' internal/tools/file_safety_test.go

Repository: Gitlawb/zero

Length of output: 25685


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- locate registry RunWithOptions/apply budget sequence ---'
sed -n '120,195p' internal/tools/registry.go
sed -n '195,270p' internal/tools/registry.go

echo '--- output_budget budgetary helpers ---'
rg -n -C 5 'func budgetSemanticOutput|func newHeadTail|func newOutputBudget|type outputBudgetBuilder|func .*Truncated|func .*Result|func fitsOutputBudget' internal/tools -g '*.go'

echo '--- exact output_boundary lines for budget helpers ---'
sed -n '244,420p' internal/tools/output_boundary.go

Repository: Gitlawb/zero

Length of output: 50369


Fix read_file line-range accounting.

offset: 500, limit: 10 should be the lines 500 through 509, and seen_lines should be 500-509. The bounded end is offset + limit - 1`; apply that end line before rendering so the range counts as exact.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@internal/tools/file_safety_test.go` around lines 318 - 323, Update the
read_file line-range accounting so an offset of 500 with limit 10 produces the
inclusive range 500-509. In the relevant read_file range-processing flow,
calculate the bounded end as offset + limit - 1 and apply it before rendering,
ensuring exact bounded reads receive seen_lines metadata of 500-509.

Comment thread internal/tools/read_minified_file.go Outdated
@anandh8x

anandh8x commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator Author

@coderabbitai The latest review found no actionable comments, but the previous changes-requested verdict is still active. Please review the latest commit and clear it if no blockers remain.

@coderabbitai

coderabbitai Bot commented Aug 5, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '=== PR metadata and latest commits ==='
gh pr view 867 --repo Gitlawb/zero --json headRefOid,baseRefOid,commits,reviewDecision \
  --jq '{headRefOid,baseRefOid,reviewDecision,commits:[.commits[]|{oid,messageHeadline,authoredDate}]}'

echo
echo '=== Changed files in the latest commit ==='
git show --stat --oneline --decorate HEAD
git show --format=fuller --find-renames --find-copies -- \
  internal/tools/read_file.go \
  internal/tools/file_safety_test.go \
  internal/tools/file_tools_test.go \
  internal/tools/registry.go \
  internal/tools/read_minified_file.go \
  internal/tools/read_minified_file_test.go

echo
echo '=== Relevant source outlines ==='
ast-grep outline internal/tools/read_file.go --items all --view expanded
ast-grep outline internal/tools/file_safety_test.go --items all --view expanded
ast-grep outline internal/tools/registry.go --items all --view expanded

echo
echo '=== Range, truncation, and observation call sites ==='
rg -n -C 5 -P '\b(offset|limit|endLine|truncated|Observe|observation|RecordRead|read credit)\b' \
  internal/tools/read_file.go \
  internal/tools/file_safety_test.go \
  internal/tools/file_tools_test.go \
  internal/tools/registry.go \
  internal/tools/read_minified_file.go \
  internal/tools/read_minified_file_test.go

Length of output: 54503


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '=== End-to-end regression test ==='
sed -n '299,333p' internal/tools/file_safety_test.go

echo
echo '=== Registry execution and observation commit ==='
sed -n '129,259p' internal/tools/registry.go

echo
echo '=== Canonical range calculation and observation creation ==='
sed -n '66,177p' internal/tools/read_file.go
sed -n '179,278p' internal/tools/read_file.go

echo
echo '=== Corrective commit for the original blocker ==='
git show --format=fuller --find-renames --find-copies 3aa190bd7f56266325a196b4985c56c413c4d4a5 -- \
  internal/tools/read_file.go \
  internal/tools/file_safety_test.go \
  internal/tools/file_tools_test.go \
  internal/tools/registry.go

Length of output: 24078


@anandh8x I reviewed the latest commit and the prior blocking range issue.

limit now defines the exact end of the canonical line range. An interior range no longer sets Truncated. The regression test uses Registry.RunWithOptions, confirms read credit for lines 500-509, and confirms that an edit in that range succeeds.

The latest commit also prevents overflow for a maximum limit in read_minified_file.

I found no remaining blockers. I did not run tests because the review sandbox does not execute repository code.

[approve]

You are interacting with an AI system.

@anandh8x
anandh8x requested a review from Vasanthdev2004 August 6, 2026 06:30
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.

2 participants