Skip to content

Commit 7032ae6

Browse files
committed
feat(read-files): add bounded native batches on reader foundation (Zoo-Code-Org#1948)
1 parent 8365676 commit 7032ae6

31 files changed

Lines changed: 1659 additions & 119 deletions
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
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.

‎packages/types/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ export * from "./mode.js"
2020
export * from "./model.js"
2121
export * from "./provider-identifiers.js"
2222
export * from "./provider-settings.js"
23+
export * from "./read-files/read-files.js"
2324
export * from "./task.js"
2425
export * from "./todo.js"
2526
export * from "./skills.js"
Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
import { MAX_READ_FILES, readFilesParamsSchema, isLegacyReadFileParams, READ_FILES_TOOL_NAME } from "../read-files.js"
2+
import * as publicTypes from "../../index.js"
3+
import * as compatibilityTypes from "../../tool-params.js"
4+
import type { ReadFileParams, ReadFileToolParams } from "../../tool-params.js"
5+
import type { ReadFilesParams, LegacyReadFileParams, FileEntry, LineRange } from "../read-files.js"
6+
7+
describe("multiple-file reading contracts", () => {
8+
it("exposes the same runtime contract through feature, public and compatibility modules", () => {
9+
for (const exports of [publicTypes, compatibilityTypes]) {
10+
expect(exports.MAX_READ_FILES).toBe(MAX_READ_FILES)
11+
expect(exports.readFilesParamsSchema).toBe(readFilesParamsSchema)
12+
expect(exports.isLegacyReadFileParams).toBe(isLegacyReadFileParams)
13+
}
14+
})
15+
16+
it("preserves public and compatibility type exports", () => {
17+
expectTypeOf<publicTypes.ReadFilesParams>().toEqualTypeOf<ReadFilesParams>()
18+
expectTypeOf<compatibilityTypes.ReadFilesParams>().toEqualTypeOf<ReadFilesParams>()
19+
expectTypeOf<publicTypes.LegacyReadFileParams>().toEqualTypeOf<LegacyReadFileParams>()
20+
expectTypeOf<compatibilityTypes.LegacyReadFileParams>().toEqualTypeOf<LegacyReadFileParams>()
21+
expectTypeOf<publicTypes.FileEntry>().toEqualTypeOf<FileEntry>()
22+
expectTypeOf<compatibilityTypes.FileEntry>().toEqualTypeOf<FileEntry>()
23+
expectTypeOf<publicTypes.LineRange>().toEqualTypeOf<LineRange>()
24+
expectTypeOf<compatibilityTypes.LineRange>().toEqualTypeOf<LineRange>()
25+
expectTypeOf<ReadFilesParams["entries"][number]>().toMatchTypeOf<ReadFileParams>()
26+
})
27+
28+
describe("bounded native batches", () => {
29+
it("shares the canonical tool name with the public tool registry", () => {
30+
expect(publicTypes.READ_FILES_TOOL_NAME).toBe(READ_FILES_TOOL_NAME)
31+
expect(publicTypes.toolNames).toContain(READ_FILES_TOOL_NAME)
32+
expect(publicTypes.toolNamesSchema.parse(READ_FILES_TOOL_NAME)).toBe(READ_FILES_TOOL_NAME)
33+
})
34+
35+
it("retains independent slice and indentation parameters", () => {
36+
const batch: ReadFilesParams = {
37+
entries: [
38+
{ path: "source.ts", offset: 10, limit: 5 },
39+
{ path: "test.ts", mode: "indentation", indentation: { anchor_line: 42, include_header: false } },
40+
],
41+
}
42+
expect(readFilesParamsSchema.parse(batch)).toEqual(batch)
43+
})
44+
45+
it("normalizes strict-provider nulls without losing false or zero", () => {
46+
expect(
47+
readFilesParamsSchema.parse({
48+
entries: [
49+
{
50+
path: "source.ts",
51+
mode: null,
52+
offset: null,
53+
limit: null,
54+
indentation: {
55+
anchor_line: null,
56+
max_levels: 0,
57+
include_siblings: false,
58+
include_header: false,
59+
max_lines: null,
60+
},
61+
},
62+
],
63+
}),
64+
).toEqual({
65+
entries: [
66+
{
67+
path: "source.ts",
68+
mode: undefined,
69+
offset: undefined,
70+
limit: undefined,
71+
indentation: {
72+
anchor_line: undefined,
73+
max_levels: 0,
74+
include_siblings: false,
75+
include_header: false,
76+
max_lines: undefined,
77+
},
78+
},
79+
],
80+
})
81+
})
82+
83+
it("accepts the maximum batch size", () => {
84+
expect(
85+
readFilesParamsSchema.safeParse({
86+
entries: Array.from({ length: MAX_READ_FILES }, () => ({ path: "source.ts" })),
87+
}).success,
88+
).toBe(true)
89+
})
90+
91+
it.each([
92+
{ entries: [] },
93+
{ entries: Array.from({ length: MAX_READ_FILES + 1 }, () => ({ path: "source.ts" })) },
94+
{ entries: [{ path: "" }] },
95+
{ entries: [{ path: "source.ts", offset: 0 }] },
96+
{ entries: [{ path: "source.ts", limit: 1.5 }] },
97+
{ entries: [{ path: "source.ts", indentation: { max_levels: -1 } }] },
98+
{ entries: [{ path: "source.ts", lineRanges: [{ start: 1, end: 2 }] }] },
99+
{ files: [{ path: "source.ts" }] },
100+
])("still rejects malformed or legacy native batches: %j", (params) => {
101+
expect(readFilesParamsSchema.safeParse(params).success).toBe(false)
102+
})
103+
})
104+
105+
describe("legacy conversation compatibility", () => {
106+
it("recognizes tagged legacy reads and preserves type narrowing", () => {
107+
const params: ReadFileToolParams = {
108+
files: [{ path: "source.ts", lineRanges: [{ start: 1, end: 3 }] }],
109+
_legacyFormat: true,
110+
}
111+
expect(isLegacyReadFileParams(params)).toBe(true)
112+
if (isLegacyReadFileParams(params)) expect(params.files[0]?.lineRanges).toEqual([{ start: 1, end: 3 }])
113+
})
114+
115+
it("recognizes persisted untagged legacy reads", () => {
116+
// Histories predating the discriminant are valid runtime inputs even
117+
// though new callers must use the tagged LegacyReadFileParams type.
118+
const persisted = { files: [{ path: "source.ts" }] } as ReadFileToolParams
119+
expect(isLegacyReadFileParams(persisted)).toBe(true)
120+
})
121+
122+
it("does not classify ordinary single-file reads as legacy", () => {
123+
expect(isLegacyReadFileParams({ path: "source.ts", offset: 3 })).toBe(false)
124+
})
125+
})
126+
})
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
/** Legacy read_file parameters and compatibility guard for conversation resumption. */
2+
import type { ReadFileToolParams } from "../tool-params.js"
3+
4+
/**
5+
* Line range specification for legacy read_file format.
6+
* Represents a contiguous range of lines [start, end] (1-based, inclusive).
7+
*/
8+
export interface LineRange {
9+
start: number
10+
end: number
11+
}
12+
13+
/**
14+
* File entry for legacy read_file format.
15+
* Supports reading multiple disjoint line ranges from a single file.
16+
*/
17+
export interface FileEntry {
18+
/** Path to the file, relative to workspace */
19+
path: string
20+
/** Optional list of line ranges to read (if omitted, reads entire file) */
21+
lineRanges?: LineRange[]
22+
}
23+
24+
/**
25+
* Legacy parameters for the read_file tool (pre-refactor format).
26+
* Supports reading multiple files in a single call with optional line ranges.
27+
*
28+
* @deprecated Use ReadFilesParams for batches or ReadFileParams for a single
29+
* file. This format is maintained for compatibility with existing chat histories.
30+
*/
31+
export interface LegacyReadFileParams {
32+
/** Array of file entries to read */
33+
files: FileEntry[]
34+
/** Discriminant flag for type narrowing */
35+
_legacyFormat: true
36+
}
37+
38+
/** Type guard for the historical multi-file read_file contract. */
39+
export function isLegacyReadFileParams(params: ReadFileToolParams): params is LegacyReadFileParams {
40+
// `NativeToolCallParser` always tags freshly parsed legacy calls with `_legacyFormat: true`.
41+
// The bare-`files` fallback only matters for chat history persisted before that flag was
42+
// introduced (commit cc86049f1) and re-hydrated on a later run. Note that params matched via
43+
// that fallback narrow to `LegacyReadFileParams` but leave `_legacyFormat` `undefined`, so
44+
// callers should branch on the presence of `files`, not on `_legacyFormat === true`.
45+
const hasLegacyFlag = "_legacyFormat" in params && params._legacyFormat === true
46+
const hasFilesArray = "files" in params && Array.isArray(params.files)
47+
return hasLegacyFlag || hasFilesArray
48+
}
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
/**
2+
* Parameters, validation, and limits for bounded native multiple-file reads (read_files).
3+
*/
4+
import { z } from "zod"
5+
6+
/** A deliberately small, sequential batch of modern file reads. */
7+
export const MAX_READ_FILES = 10
8+
9+
const optionalInteger = (minimum: number) =>
10+
z
11+
.number()
12+
.int()
13+
.min(minimum)
14+
.max(Number.MAX_SAFE_INTEGER)
15+
.nullish()
16+
.transform((value) => value ?? undefined)
17+
18+
export const readFilesParamsSchema = z
19+
.object({
20+
entries: z
21+
.array(
22+
z
23+
.object({
24+
path: z.string().min(1).max(1024),
25+
mode: z
26+
.enum(["slice", "indentation"])
27+
.nullish()
28+
.transform((value) => value ?? undefined),
29+
offset: optionalInteger(1),
30+
limit: optionalInteger(1),
31+
indentation: z
32+
.object({
33+
anchor_line: optionalInteger(1),
34+
max_levels: optionalInteger(0),
35+
include_siblings: z
36+
.boolean()
37+
.nullish()
38+
.transform((value) => value ?? undefined),
39+
include_header: z
40+
.boolean()
41+
.nullish()
42+
.transform((value) => value ?? undefined),
43+
max_lines: optionalInteger(1),
44+
})
45+
.strict()
46+
.nullish()
47+
.transform((value) => value ?? undefined),
48+
})
49+
.strict(),
50+
)
51+
.min(1)
52+
.max(MAX_READ_FILES),
53+
})
54+
.strict()
55+
56+
export type ReadFilesParams = z.infer<typeof readFilesParamsSchema>
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/** Canonical native tool name, shared by registration, parsing, and execution. */
2+
export const READ_FILES_TOOL_NAME = "read_files"
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/** Multiple-file reading: bounded native batches and legacy compatibility. */
2+
export * from "./read-files-tool-name.js"
3+
export * from "./read-files-params.js"
4+
export * from "./legacy-read-file-params.js"

0 commit comments

Comments
 (0)