|
| 1 | +# Bounded native file batches |
| 2 | + |
| 3 | +Issue [#1948](https://github.com/Zoo-Code-Org/Zoo-Code/issues/1948) adds the companion |
| 4 | +[`read_files`](../../src/core/prompts/tools/native-tools/read_files.ts:8) native tool. |
| 5 | +It avoids intervening model turns when the paths and reading ranges are already |
| 6 | +known. It does **not** implement parallel dispatch or promise faster disk I/O. |
| 7 | + |
| 8 | +## Contract and isolation |
| 9 | + |
| 10 | +- One call contains 1–10 entries, each with the existing single reader's slice or |
| 11 | + indentation options. Strict providers can send null for optional values; |
| 12 | + other providers can omit them. The |
| 13 | + [shared validation schema](../../packages/types/src/read-files/read-files-params.ts) rejects |
| 14 | + legacy ranges, malformed options, oversized arrays, and empty paths. |
| 15 | +- Both native definitions build their per-file parameters directly from the |
| 16 | + [independent shared schema](../../src/core/prompts/tools/native-tools/file-reading/readFileParameters.ts:31). |
| 17 | + Each keeps its own top-level description; batch construction does not instantiate |
| 18 | + the single-file tool. Runtime defaults live in the |
| 19 | + [file-reading constants module](../../src/core/tools/file-reading/readFileConstants.ts). |
| 20 | +- [`ReadFilesTool.execute()`](../../src/core/tools/file-reading/ReadFilesTool.ts:25) processes |
| 21 | + entries sequentially and returns exactly one result. No general parallel-tool |
| 22 | + setting or provider change is required. |
| 23 | +- Both tools reuse [`ReadFileTool.readEntry()`](../../src/core/tools/file-reading/ReadFileTool.ts:96). |
| 24 | + Ordinary single-file calls and historical legacy calls retain their original |
| 25 | + schemas and routing. The old multi-file executor is not used by the new tool. |
| 26 | +- Every entry passes the existing ignore check and gets its own ordinary |
| 27 | + single-file approval request, including its range/anchor and outside-workspace |
| 28 | + flag. Approving an earlier entry does not grant permission to another entry. |
| 29 | + Existing read allowlists and outside-workspace policy still apply independently. |
| 30 | + There is no new approval state or settings round trip. |
| 31 | +- Text and supported extracted documents use the same modern slice/indentation |
| 32 | + reader. Extracted text is not returned through the unbounded legacy document |
| 33 | + path. Images, including text-based SVG, and unsupported binary formats receive |
| 34 | + explicit unsupported results. Use the ordinary single reader for images; |
| 35 | + its existing image-memory limits are unchanged. Batch model results are text-only. |
| 36 | + |
| 37 | +## Results and interruption policy |
| 38 | + |
| 39 | +Each result has an entry index, escaped path label, and status: success, |
| 40 | +truncated, denied, blocked, error, unsupported, budget-exhausted, or cancelled. |
| 41 | +Duplicate paths are separate indexed reads with independent approval requests. |
| 42 | +Very long labels are explicitly abbreviated; the request index identifies the |
| 43 | +original entry unambiguously. |
| 44 | + |
| 45 | +Missing/unreadable files, unsupported formats, and ignore blocks do not discard |
| 46 | +successful siblings or prevent later eligible reads. **User rejection stops the |
| 47 | +batch:** the rejected entry is denied and all subsequent entries are cancelled. |
| 48 | +Completed results remain present. Cancellation during an approval starts no read; |
| 49 | +cancellation during an already approved read discards its in-flight result and |
| 50 | +starts no subsequent read. The executor only observes existing task cancellation |
| 51 | +flags; it does not mutate task lifecycle transitions. A failed/withdrawn approval |
| 52 | +also cancels the remaining reads, even before cancellation flags propagate. |
| 53 | + |
| 54 | +Line/range truncation includes continuation guidance. Additional budget clipping |
| 55 | +keeps only complete numbered lines and resumes at the first undelivered line. |
| 56 | +If no complete line fits, it does not advance the requested starting position. |
| 57 | +Structural blocks can become incomplete under the aggregate budget and are |
| 58 | +explicitly labelled as such. Long-line clipping is separately reported: changing |
| 59 | +line offsets cannot recover a line's omitted suffix. Feedback and error excerpts |
| 60 | +are bounded and explicitly marked when clipped. |
| 61 | + |
| 62 | +## Aggregate budget |
| 63 | + |
| 64 | +The [isolated budget helper](../../src/core/tools/file-reading/readFileBatchBudget.ts) |
| 65 | +uses the active input window, latest context usage, the shared output-token reserve, |
| 66 | +the existing 10% context safety margin, pending sibling tool results, and this |
| 67 | +call's arguments. UTF-8 byte length provides a deliberately conservative text |
| 68 | +token estimate rather than assuming four characters per token. |
| 69 | + |
| 70 | +The [batch output accumulator](../../src/core/tools/file-reading/readFileBatchOutput.ts) |
| 71 | +uses the [pure per-entry formatter](../../src/core/tools/file-reading/readFileBatchEntry.ts). |
| 72 | +The **complete model-facing batch result has a 64 KiB absolute ceiling**. Metadata |
| 73 | +for every entry is reserved before content allocation (1 KiB per entry plus the |
| 74 | +batch header). The remaining content allowance is shared among remaining entries, |
| 75 | +so a large first file cannot silently starve later files. Explicit line limits |
| 76 | +and indentation caps are defensively clamped to 2,000 lines, and the byte budget |
| 77 | +still clips the resulting text regardless of those limits. Paths, errors, user |
| 78 | +feedback, extracted documents, and continuation messages cannot bypass the ceiling. |
| 79 | + |
| 80 | +If context cannot accommodate the reserved result envelope, no files are opened |
| 81 | +or approved. A bounded, content-free status manifest is still returned for every |
| 82 | +entry, asking the model to free context before retrying. This minimal diagnostic |
| 83 | +is unavoidable when requiring a result for every entry even with zero available |
| 84 | +context; it does not turn zero available context into permission to read data. |
| 85 | +The absolute ceiling applies to this manifest as well. |
| 86 | + |
| 87 | +The reader continues to load/extract one source file at a time, as the existing |
| 88 | +modern reader does. This is an output/context bound, not a new streaming disk-read |
| 89 | +or document-extraction memory guarantee. |
| 90 | + |
| 91 | +## Validation and local comparison |
| 92 | + |
| 93 | +Coverage includes native schema/strict nulls, streaming/final parsing, modern |
| 94 | +executor integration, per-file approvals and allowlists, outside-workspace |
| 95 | +policy, cancellation, duplicate paths, missing files, aggregate output, |
| 96 | +oversized limits, UTF-8 boundaries, extracted documents, unsupported images, |
| 97 | +UI range/anchor navigation, and the Sol/Codex Lite single-call contract. |
| 98 | + |
| 99 | +The [known-path comparison test](../../src/core/tools/file-reading/__tests__/readFilesTool.spec.ts:319) |
| 100 | +reads identical source/test ranges with two single-file calls versus one batch. |
| 101 | +The source lines are asserted equivalent. On 2026-10-06, one local run recorded: |
| 102 | + |
| 103 | +| Metric | Single-file | Batch | |
| 104 | +| ----------------------------------------------------- | --------------: | --------------: | |
| 105 | +| Required tool-request turns on a single-call provider | 2 | 1 | |
| 106 | +| Local reader workflow time, mocked immediate approval | 3.139 ms | 2.263 ms | |
| 107 | +| Model-facing reader output | 388 UTF-8 bytes | 553 UTF-8 bytes | |
| 108 | +| Repeated reads | 0 | 0 | |
| 109 | +| Read errors | 0 | 0 | |
| 110 | +| Actual paid/network model requests in this test | 0 | 0 | |
| 111 | + |
| 112 | +The turn counts follow from the single-call contract, not a recorded paid model |
| 113 | +session. These tiny timing values are noisy, exclude model inference and human |
| 114 | +approval, and **are not an end-to-end speedup benchmark**. Total real model task |
| 115 | +time and model-induced retry/error rates remain unmeasured. Batching deliberately |
| 116 | +adds status/continuation overhead; its benefit is removing an intervening model |
| 117 | +turn, not necessarily reducing returned bytes. |
| 118 | + |
| 119 | +Reproduce the local comparison from the extension package: |
| 120 | + |
| 121 | +```sh |
| 122 | +pnpm --dir src exec vitest run core/tools/file-reading/__tests__/readFilesTool.spec.ts -t 'compares equivalent' --no-silent |
| 123 | +``` |
| 124 | + |
| 125 | +For a future real-provider comparison, use the same known paths/ranges, fresh |
| 126 | +equivalent context and auto-approval policy, and record provider/model, actual |
| 127 | +request count, whole-task wall time, total output bytes/tokens, repeated reads, |
| 128 | +errors/retries, and clipping for both cases. Do not compare sequential local I/O |
| 129 | +against unrelated parallel dispatch or claim a fixed speedup from the local test. |
0 commit comments