-
Notifications
You must be signed in to change notification settings - Fork 162
perf(tools): content-hash read cache for unchanged re-reads #3385
Description
The agent re-reads files it has already read in the same session, and each re-read costs a full round trip and the file's full contents again. Nothing tracks that it has seen the file before, so there is no way for it to know the file is unchanged short of reading it.
On the honest size of this: by call count it is a large share of reads, but reads are individually small, so in tokens — which is what a 32K window actually cares about — the saving is modest. Making truncated output addressable (#3378) is worth considerably more. This is filed because it is cheap and tidy, not because it is urgent, and it should be scheduled accordingly.
Acceptance criteria
- Reads are content-hashed; an unchanged re-read returns a reference plus the hash, not the bytes again.
- Invalidation is correct across edits the agent itself made — this is the case a naive mtime check gets wrong, because the agent writes and re-reads within the same second.
- The agent can force a full re-read explicitly when it needs the bytes.
- Cache is per-task and does not leak across tasks or across agents.
- Measure the actual token saving on a named eval scenario — pick one from the existing agent-eval categories and state it in the PR — and report the figure. If it is negligible, say so and close this as not-worth-doing; that is a legitimate outcome.
🔍 Technical details
read_file exists in three mixins (file_io_tools, file_tools, filesystem_tools), all reading from disk and returning full contents on every call, with no shared cache layer. They register under the same tool name into the same registry and the last write wins silently, so a given profile only ever exposes one — for the flagship's "full" that is file_io_tools.read_file. The file_io_tools and file_tools versions are near-verbatim copies: the duplication is worse than it looks and the reachability narrower.
The paging subtlety is not an offset parameter — none of these take one. The analogue is filesystem_tools' lines/mode arguments, where a partial read must not be counted as a re-read of the whole file.
Prior art. #2810 (closed) already implements FileStateTracker in cpp/include/gaia/file_tools.h — a read-time content-hash ledger with divergence detection, with read returning a content hash. That is this design, shipped, on the other tree.