fix(core): tail reads from the end of a file and suggest close file names (#62147)

Co-authored-by: Aiden Cline <aidenpcline@gmail.com>
This commit is contained in:
Kit Langton
2026-11-08 15:31:32 -08:00
committed by GitHub
Unverified
parent eedb7fb3d0
commit 7d5b722508
5 changed files with 561 additions and 111 deletions
+104 -35
View File
@@ -1,7 +1,7 @@
export * as ReadTool from "./read.js"
import type { Context } from "@opencode/plugin/effect/plugin"
import { basename, dirname, join } from "path"
import { basename, dirname, extname, isAbsolute, join, relative } from "path"
import { ToolFailure } from "@opencode/ai/effect"
import { Effect, Schema } from "effect"
import { FSUtil } from "@opencode/util/fs-util"
@@ -27,6 +27,7 @@ const LocationInput = Schema.Struct({
}),
})
export const Input = LocationInput
type Missing = { input: string; requested: FileAccess.Target; context: FileAccess.Invocation }
const Output = Schema.Union([ReadToolFileSystem.FileContent, ReadToolFileSystem.TextPage, ReadToolFileSystem.ListPage])
export const Plugin = {
@@ -39,6 +40,7 @@ export const Plugin = {
const sessionInstructions = yield* SessionInstructions.Service
const fs = yield* FSUtil.Service
const location = yield* Location.Service
const environment = yield* Environment.Service
yield* ctx.tool
.transform((editor) =>
@@ -107,15 +109,15 @@ export const Plugin = {
const alternate = yield* alternatePath(requested.absolute).pipe(
Effect.orElseSucceed(() => undefined),
)
if (!alternate) return yield* missing(input.path, requested.absolute)
if (!alternate) return yield* missing({ input: input.path, requested, context })
const target = yield* access.authorizeRead(alternate, context, { siblingOf: requested })
const content = yield* read(target).pipe(
Effect.catchIf(
(error) => error instanceof Environment.NotFound,
() => missing(input.path, requested.absolute),
() => missing({ input: input.path, requested, context }),
),
)
if (content.type === "list-page") return yield* missing(input.path, requested.absolute)
if (content.type === "list-page") return yield* missing({ input: input.path, requested, context })
return {
content,
target,
@@ -162,8 +164,8 @@ export const Plugin = {
const message =
error instanceof ReadToolFileSystem.BinaryFileError ||
error instanceof ReadToolFileSystem.MediaIngestLimitError ||
error instanceof ReadToolFileSystem.OffsetOutOfRangeError ||
error instanceof ReadToolFileSystem.PathKindError
error instanceof ReadToolFileSystem.PathKindError ||
error instanceof ReadToolFileSystem.DirectoryOffsetError
? error.message
: `Unable to read ${input.path}`
return new ToolFailure({ message, error })
@@ -175,11 +177,6 @@ export const Plugin = {
.pipe(Effect.orDie)
const alternatePath = Effect.fn("ReadTool.alternatePath")(function* (absolute: string) {
const canonical = (name: string) =>
name
.normalize("NFC")
.replace(/[\u00a0\u202f]/g, " ")
.replace(/[\u2018\u2019]/g, "'")
const base = canonical(basename(absolute))
const matches = (yield* reader.list(AbsolutePath.make(dirname(absolute)))).filter(
(entry) => entry.type === "file" && canonical(entry.name) === base,
@@ -196,54 +193,122 @@ export const Plugin = {
Effect.orElseSucceed(() => ({ type: "unknown" as const })),
)
const similar = (names: readonly string[], name: string) => {
const base = name.toLowerCase()
return names
.filter((entry) => {
const candidate = entry.toLowerCase()
return candidate.includes(base) || base.includes(candidate)
})
.slice(0, 3)
}
// A path written from the wrong root, such as /Users/me/src/a.ts for a location at /Users/me/repo,
// usually means <location>/src/a.ts, so check that one path and nothing else.
const reroot = Effect.fn("ReadTool.reroot")(function* (miss: Missing) {
const root = location.directory
if (FSUtil.contains(root, miss.requested.absolute) || !FSUtil.contains(dirname(root), miss.requested.absolute))
return []
const target = yield* access.resolve({ path: join(root, relative(dirname(root), miss.requested.absolute)) })
if (!(yield* Environment.exists(environment.files, target.absolute))) return []
const readable = yield* permission.allows({
action: "read",
resources: [target.resource],
save: ["*"],
...Permission.invocation(miss.context),
})
if (!readable) return []
return [isAbsolute(miss.input) || miss.input.startsWith("~/") ? target.absolute : target.resource]
})
const didYouMean = (suggestions: string[]) =>
suggestions.length === 0 ? [] : [`Did you mean one of these?\n${suggestions.slice(0, 3).join("\n")}`]
// A missing folder usually means a removed worktree, a moved directory, or a relative path
// resolved from the wrong place, so name the first missing folder and its nearest existing parent.
const missingFolder = Effect.fn("ReadTool.missingFolder")(function* (input: string, folder: string) {
const missingFolder = Effect.fn("ReadTool.missingFolder")(function* (
input: string,
folder: string,
moved: string[],
) {
let child = folder
let parent = dirname(folder)
while (parent !== child) {
const found = yield* listing(parent)
if (found.type === "unknown") break
if (found.type === "found") {
const suggestions = similar(found.names, basename(child)).map((entry) => join(parent, entry))
const suggestions = [...moved, ...similar(found.names, basename(child)).map((entry) => join(parent, entry))]
const message = [
`File not found: ${input}`,
`The folder ${child} does not exist. The nearest folder that does is ${parent}.`,
...(suggestions.length === 0 ? [] : [`Did you mean one of these?\n${suggestions.join("\n")}`]),
...didYouMean(suggestions),
].join("\n\n")
return yield* new ToolFailure({ message })
}
child = parent
parent = dirname(parent)
}
return yield* new ToolFailure({ message: `File not found: ${input}` })
return yield* new ToolFailure({ message: [`File not found: ${input}`, ...didYouMean(moved)].join("\n\n") })
})
const missing = Effect.fn("ReadTool.missing")(function* (input: string, absolute: string) {
const folder = dirname(absolute)
const missing = Effect.fn("ReadTool.missing")(function* (miss: Missing) {
const moved = yield* reroot(miss).pipe(Effect.orElseSucceed(() => []))
const folder = dirname(miss.requested.absolute)
const found = yield* listing(folder)
if (found.type === "missing") return yield* missingFolder(input, folder)
const suggestions =
found.type === "found" ? similar(found.names, basename(input)).map((entry) => join(dirname(input), entry)) : []
const message =
suggestions.length === 0
? `File not found: ${input}`
: `File not found: ${input}\n\nDid you mean one of these?\n${suggestions.join("\n")}`
return yield* new ToolFailure({ message })
if (found.type === "missing") return yield* missingFolder(miss.input, folder, moved)
const suggestions = [
...moved,
...(found.type === "found"
? similar(found.names, basename(miss.input)).map((entry) => join(dirname(miss.input), entry))
: []),
]
return yield* new ToolFailure({
message: [`File not found: ${miss.input}`, ...didYouMean(suggestions)].join("\n\n"),
})
})
}),
}
// Ranks a folder's entries against a missing name: same name ignoring case, then same stem with
// another extension, then one containing the other, then a typo in the stem.
const similar = (names: readonly string[], requested: string) => {
const name = requested.toLowerCase()
const wanted = stem(name)
const typos = wanted.length < 3 ? 0 : wanted.length < 5 ? 1 : 2
const tier = (candidate: string) => {
if (candidate === name) return 1
// Names that only differ in look-alike characters are what alternatePath recovers or deliberately skips.
if (canonical(candidate) === canonical(name)) return
const found = stem(candidate)
if (found === wanted) return 2
if (
Math.min(found.length, wanted.length) >= 3 &&
(candidate.includes(name) || name.includes(candidate) || found.includes(wanted) || wanted.includes(found))
)
return 3
// Folders can be huge, so skip the distance when the lengths alone rule out a typo.
if (typos > 0 && Math.abs(found.length - wanted.length) <= typos && editDistance(found, wanted) <= typos) return 4
}
return names
.filter((entry) => entry !== requested)
.flatMap((entry) => {
const rank = tier(entry.toLowerCase())
return rank === undefined ? [] : [{ entry, rank, distance: editDistance(entry.toLowerCase(), name) }]
})
.sort((a, b) => a.rank - b.rank || a.distance - b.distance || a.entry.localeCompare(b.entry))
.slice(0, 3)
.map((match) => match.entry)
}
const canonical = (name: string) =>
name
.normalize("NFC")
.replace(/[\u00a0\u202f]/g, " ")
.replace(/[\u2018\u2019]/g, "'")
const stem = (name: string) => name.slice(0, name.length - extname(name).length) || name
const editDistance = (a: string, b: string) => {
let previous = Array.from({ length: b.length + 1 }, (_, index) => index)
for (let i = 1; i <= a.length; i++) {
const current = [i]
for (let j = 1; j <= b.length; j++)
current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
previous = current
}
return previous[b.length]
}
function parseSkillUri(value: string) {
const trimmed = value.slice("skill://".length).replace(/\/+$/, "")
const slash = trimmed.indexOf("/")
@@ -284,8 +349,12 @@ export const toModelContent = (path: string, offset: number | undefined, output:
// Pages already join selected lines; a trailing newline represents a selected blank line.
const text = output.type === "file" ? output.content.replace(/\n$/, "") : output.content
const lines = output.content === "" ? [] : text.split("\n")
// A page that starts before the requested offset is the file's tail, returned for an offset past the end.
const total = start + lines.length - 1
const pastEnd = output.type === "text-page" && offset !== undefined && start < offset
const content = [
lines.length === 0 ? `Read file ${path}, 0 lines` : `Read file ${path}, lines ${start}-${start + lines.length - 1}`,
(lines.length === 0 ? `Read file ${path}, 0 lines` : `Read file ${path}, lines ${start}-${total}`) +
(pastEnd ? ` (offset ${offset} is past the end; the file has ${total} ${total === 1 ? "line" : "lines"})` : ""),
]
lines.forEach((line, index) => content.push(`${start + index}: ${line}`))
if (output.type === "text-page" && output.truncated && output.next !== undefined)
+95 -49
View File
@@ -15,6 +15,7 @@ export const MAX_READ_LINES = 2_000
export const MAX_READ_BYTES = 50 * 1024
export const MAX_MEDIA_INGEST_BYTES = 20 * 1024 * 1024
const FIRST_CHUNK = 256 * 1024
const TAIL_LINES = 100
const MAX_LINE_LENGTH = 2_000
const TREE_BASE = 6
const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`
@@ -40,15 +41,6 @@ export class MediaIngestLimitError extends Schema.TaggedError<MediaIngestLimitEr
}
}
export class OffsetOutOfRangeError extends Schema.TaggedError<OffsetOutOfRangeError>()(
"ReadTool.OffsetOutOfRangeError",
{ offset: Schema.Number, lines: Schema.Number },
) {
override get message() {
return `Offset ${this.offset} is out of range for this file (${this.lines} ${this.lines === 1 ? "line" : "lines"})`
}
}
export class PathKindError extends Schema.TaggedError<PathKindError>()("ReadTool.PathKindError", {
resource: Schema.String,
expected: Schema.Literals(["a file", "a file or directory"]),
@@ -58,16 +50,24 @@ export class PathKindError extends Schema.TaggedError<PathKindError>()("ReadTool
}
}
export class DirectoryOffsetError extends Schema.TaggedError<DirectoryOffsetError>()("ReadTool.DirectoryOffsetError", {
resource: Schema.String,
}) {
override get message() {
return `A negative offset only works for files, and ${this.resource} is a directory`
}
}
export type ReadError =
| Environment.NotFound
| Environment.Failed
| BinaryFileError
| MediaIngestLimitError
| OffsetOutOfRangeError
| PathKindError
| DirectoryOffsetError
export const PageInput = Schema.Struct({
offset: Schema.optionalKey(NonNegativeInt),
offset: Schema.optionalKey(Schema.Int),
limit: Schema.optionalKey(NonNegativeInt),
})
export type PageInput = typeof PageInput.Type
@@ -121,16 +121,19 @@ export const read = Effect.fn("ReadTool.read")(function* (
) {
const virtual = resource.startsWith("skill://")
const first = yield* files.read(input, { offset: 0, length: FIRST_CHUNK }).pipe(
Effect.catchTag("Environment.WrongKind", (error) => {
if (error.actual !== "directory")
return Effect.fail(new PathKindError({ resource, expected: "a file or directory" }))
return files.list(input).pipe(
Effect.map((entries) => list(entries, page, virtual ? "/" : path.sep)),
Effect.catchTag("Environment.WrongKind", () =>
Effect.fail(new PathKindError({ resource, expected: "a file or directory" })),
),
)
}),
Effect.catchTag("Environment.WrongKind", (error) =>
Effect.gen(function* () {
if (error.actual !== "directory")
return yield* new PathKindError({ resource, expected: "a file or directory" })
if (page.offset !== undefined && page.offset < 0) return yield* new DirectoryOffsetError({ resource })
return yield* files.list(input).pipe(
Effect.map((entries) => list(entries, page, virtual ? "/" : path.sep)),
Effect.catchTag("Environment.WrongKind", () =>
Effect.fail(new PathKindError({ resource, expected: "a file or directory" })),
),
)
}),
),
)
if (first instanceof ListPage) return first
@@ -162,17 +165,7 @@ export const read = Effect.fn("ReadTool.read")(function* (
}
}
if (first.bytes.length >= first.info.size) {
const result = textPage(first.bytes, true, page)
if (result === undefined) return yield* Effect.die("Read page did not settle for a complete first chunk")
return yield* makeTextPage(
input,
resource,
result,
first.bytes.subarray(0, result.consumed).includes(0),
lineCount(textLeaf(first.bytes).summary.lines, first.bytes.at(-1)),
)
}
if (first.bytes.length >= first.info.size) return yield* completePage(input, resource, first.bytes, page)
const offset = page.offset || 1
const limit = Math.min(page.limit || MAX_READ_LINES, MAX_READ_LINES)
@@ -182,24 +175,38 @@ export const read = Effect.fn("ReadTool.read")(function* (
let ended = false
while (true) {
const eof = ended || bytes >= first.info.size
if (lines >= offset - 1 || eof) {
const total = lineCount(lines, leaves.at(-1)?.bytes.at(-1))
if (eof && offset > total) {
const skipped = Math.max(0, total - Math.min(page.limit || TAIL_LINES, TAIL_LINES))
// Decode from the newline ending the last skipped line, so a byte order mark
// starting the tail stays content. That empty first line is never in the tail.
const tree = textTree(leaves)
const start = textOffset(tree, offset - 1)
let position = 0
const selected = Buffer.concat(
leaves.flatMap((leaf) => {
const leafStart = position
position += leaf.summary.bytes
if (position <= start) return []
return [leaf.bytes.subarray(Math.max(0, start - leafStart))]
}),
const tail = textPage(
textSlice(leaves, Math.max(0, textOffset(tree, skipped) - 1), tree.summary.bytes),
true,
page,
)
const result = textPage(selected, eof, { limit })
if (tail === undefined) return yield* Effect.die("Read page did not settle for a complete file")
return yield* makeTextPage(
input,
resource,
{ ...tail, offset: Math.max(0, skipped - 1) + tail.offset },
leaves.some((leaf) => leaf.bytes.includes(0)),
)
}
if (eof || (offset > 0 && lines >= offset - 1)) {
// A negative offset only resolves at EOF, counting back from the last line.
const from = offset < 0 ? Math.max(1, total + offset + 1) : offset
const tree = textTree(leaves)
const start = textOffset(tree, from - 1)
// Decode only the requested lines plus one byte, enough to tell whether more follow.
const end = Math.min(tree.summary.bytes, textOffset(tree, from - 1 + limit) + 1)
const result = textPage(textSlice(leaves, start, end), eof && end === tree.summary.bytes, { limit })
if (result !== undefined) {
const translated = {
...result,
offset,
...(result.next === undefined ? { next: undefined } : { next: offset + result.next - 1 }),
offset: from,
...(result.next === undefined ? { next: undefined } : { next: from + result.next - 1 }),
}
const consumed = start + result.consumed
let checked = 0
@@ -208,7 +215,7 @@ export const read = Effect.fn("ReadTool.read")(function* (
checked += leaf.summary.bytes
return length > 0 && leaf.bytes.subarray(0, length).includes(0)
})
return yield* makeTextPage(input, resource, translated, binary, lineCount(lines, leaves.at(-1)?.bytes.at(-1)))
return yield* makeTextPage(input, resource, translated, binary)
}
}
@@ -236,16 +243,29 @@ const readFile = (
Effect.catchTag("Environment.WrongKind", () => Effect.fail(new PathKindError({ resource, expected: "a file" }))),
)
const completePage = Effect.fnUntraced(function* (
input: AbsolutePath,
resource: string,
bytes: Uint8Array,
page: PageInput,
) {
const total = lineCount(textLeaf(bytes).summary.lines, bytes.at(-1))
const result = textPage(
bytes,
true,
page.offset !== undefined && page.offset < 0 ? { ...page, offset: Math.max(1, total + page.offset + 1) } : page,
)
if (result === undefined) return yield* Effect.die("Read page did not settle for a complete file")
return yield* makeTextPage(input, resource, result, bytes.subarray(0, result.consumed).includes(0))
})
const makeTextPage = Effect.fnUntraced(function* (
input: AbsolutePath,
resource: string,
result: NonNullable<ReturnType<typeof textPage>>,
binary: boolean,
lines: number,
) {
if (binary) return yield* new BinaryFileError({ resource })
if (result.entries.length === 0 && result.offset !== 1)
return yield* new OffsetOutOfRangeError({ offset: result.offset, lines })
return new TextPage({
type: "text-page",
content: result.entries.join("\n"),
@@ -299,6 +319,16 @@ const textPage = (bytes: Uint8Array, eof: boolean, page: PageInput) => {
const entries: string[] = []
let size = 0
// An offset past the end returns the file's last lines that fit, ending at the last line.
if (eof && offset > Math.max(1, available.length)) {
for (const value of available.slice(-Math.min(page.limit || TAIL_LINES, TAIL_LINES)).toReversed()) {
const text = clampLine(value)
size += Buffer.byteLength(text, "utf-8") + (entries.length > 0 ? 1 : 0)
if (size > MAX_READ_BYTES) break
entries.unshift(text)
}
return { entries, offset: available.length - entries.length + 1, next: undefined, consumed: bytes.length }
}
let next: number | undefined
for (const [index, value] of available.slice(offset - 1).entries()) {
const line = offset + index
@@ -380,6 +410,22 @@ const textOffset = (tree: TextNode, newline: number) => {
return end === undefined ? tree.summary.bytes : offset + end
}
const textSlice = (
leaves: ReadonlyArray<Extract<TextNode, { readonly type: "leaf" }>>,
start: number,
end: number,
) => {
let position = 0
return Buffer.concat(
leaves.flatMap((leaf) => {
const leafStart = position
position += leaf.summary.bytes
if (position <= start || leafStart >= end) return []
return [leaf.bytes.subarray(Math.max(0, start - leafStart), end - leafStart)]
}),
)
}
const nthNewline = (bytes: Uint8Array, count: number) => {
let found = 0
for (const [index, byte] of bytes.entries()) {
@@ -13,6 +13,7 @@ import { Global } from "@opencode/util/global"
import { Image } from "@opencode/core/image"
import { Location } from "@opencode/core/location"
import { FileAccess } from "@opencode/core/file-access"
import { Environment } from "@opencode/core/environment/index"
import { Model } from "@opencode/core/model"
import { Permission } from "@opencode/core/permission"
import { Project } from "@opencode/core/project"
@@ -50,6 +51,7 @@ const readToolNode = makeLocationNode({
SessionInstructions.node,
Skill.node,
FSUtil.node,
Environment.node,
Location.node,
],
})
+185 -7
View File
@@ -212,18 +212,196 @@ describe("ReadToolFileSystem", () => {
}),
)
it.effect("reports out-of-range pagination as a typed error", () =>
it.effect("returns the last lines when the offset is past the end", () =>
Effect.gen(function* () {
const { environment, files, directory } = yield* fixture
const file = path.join(directory, "short.txt")
yield* files.writeFileString(file, "one\n")
const read = (name: string, content: string, page: ReadToolFileSystem.PageInput) =>
files.writeFileString(path.join(directory, name), content).pipe(
Effect.andThen(ReadToolFileSystem.read(environment, absolute(path.join(directory, name)), name, page)),
Effect.map((result) => String(ReadTool.toModelContent(name, page.offset, result)).split("\n")),
)
const long = Array.from({ length: 1_800 }, (_, index) => `${index + 1}`.padEnd(1_000, "x"))
const error = yield* ReadToolFileSystem.read(environment, absolute(file), "short.txt", { offset: 2 }).pipe(
Effect.flip,
expect(yield* read("short.txt", "one\ntwo\nthree\nfour\nfive\n", { offset: 9, limit: 2 })).toEqual([
"Read file short.txt, lines 4-5 (offset 9 is past the end; the file has 5 lines)",
"4: four",
"5: five",
])
expect(yield* read("empty.txt", "", { offset: 5 })).toEqual([
"Read file empty.txt, 0 lines (offset 5 is past the end; the file has 0 lines)",
])
// The 50 KB cap keeps the last 51 of 100 tail lines, still ending at the last line.
const tail = yield* read("long.txt", long.join("\n"), { offset: 2_000, limit: 2_000 })
expect([tail[0], tail.at(-1)]).toEqual([
"Read file long.txt, lines 1750-1800 (offset 2000 is past the end; the file has 1800 lines)",
`1800: ${long.at(-1)}`,
])
}),
)
it.effect("returns the last lines of a file larger than the first chunk when the offset is past the end", () =>
Effect.gen(function* () {
const { environment, files, directory } = yield* fixture
const read = (name: string, content: string | Uint8Array, page: ReadToolFileSystem.PageInput) =>
(typeof content === "string"
? files.writeFileString(path.join(directory, name), content)
: files.writeFile(path.join(directory, name), content)
).pipe(
Effect.andThen(ReadToolFileSystem.read(environment, absolute(path.join(directory, name)), name, page)),
Effect.map((result) => String(ReadTool.toModelContent(name, page.offset, result)).split("\n")),
)
const lines = Array.from({ length: 3_000 }, (_, index) => `${index + 1}`.padEnd(100, "x"))
const expected = (from: number) =>
lines.slice(from - 1).map((line, index) => `${from + index}: ${line}`)
expect(yield* read("lf.txt", lines.join("\n") + "\n", { offset: 5_000 })).toEqual([
"Read file lf.txt, lines 2901-3000 (offset 5000 is past the end; the file has 3000 lines)",
...expected(2_901),
])
expect(yield* read("unterminated.txt", lines.join("\n"), { offset: 3_001 })).toEqual([
"Read file unterminated.txt, lines 2901-3000 (offset 3001 is past the end; the file has 3000 lines)",
...expected(2_901),
])
expect(yield* read("crlf.txt", lines.join("\r\n") + "\r\n", { offset: 3_001, limit: 5 })).toEqual([
"Read file crlf.txt, lines 2996-3000 (offset 3001 is past the end; the file has 3000 lines)",
...expected(2_996),
])
expect(yield* read("crlf-unterminated.txt", lines.join("\r\n"), { offset: 4_000, limit: 1 })).toEqual([
"Read file crlf-unterminated.txt, lines 3000-3000 (offset 4000 is past the end; the file has 3000 lines)",
...expected(3_000),
])
// A mid-file byte order mark is line content, not a decoder signature.
const marked = lines.map((line, index) => (index === 2_900 ? `\uFEFF${line}` : line))
expect((yield* read("bom.txt", marked.join("\n"), { offset: 3_001 }))[1]).toBe(`2901: \uFEFF${lines[2_900]}`)
const huge = yield* read("huge-last.txt", `${lines.slice(0, 10).join("\n")}\n${"z".repeat(300 * 1024)}`, {
offset: 12,
})
expect(huge).toEqual([
"Read file huge-last.txt, lines 1-11 (offset 12 is past the end; the file has 11 lines)",
...expected(1).slice(0, 10),
`11: ${"z".repeat(2_000)}... (line truncated to 2000 chars)`,
])
// Each clamped line is 2041 bytes, so 25 of them fit in the 50 KB cap.
const wide = Array.from({ length: 200 }, (_, index) => `${index + 1}`.padEnd(3_000, "w"))
const capped = yield* read("wide.txt", wide.join("\n") + "\n", { offset: 201 })
expect(capped[0]).toBe("Read file wide.txt, lines 176-200 (offset 201 is past the end; the file has 200 lines)")
expect(capped.slice(1)).toEqual(
wide.slice(175).map((line, index) => `${176 + index}: ${line.slice(0, 2_000)}... (line truncated to 2000 chars)`),
)
expect(error).toBeInstanceOf(ReadToolFileSystem.OffsetOutOfRangeError)
expect(error.message).toBe("Offset 2 is out of range for this file (1 line)")
// Matches whole-file reads: a null byte anywhere in the file rejects a past-end read.
const early = new TextEncoder().encode(lines.join("\n"))
early[10] = 0
const binary = yield* read("early-nul.txt", early, { offset: 3_001 }).pipe(Effect.flip)
expect(binary).toBeInstanceOf(ReadToolFileSystem.BinaryFileError)
}),
)
it.effect("starts a negative offset that many lines before the end", () =>
Effect.gen(function* () {
const { environment, files, directory } = yield* fixture
const read = (name: string, content: string, page: ReadToolFileSystem.PageInput) =>
files.writeFileString(path.join(directory, name), content).pipe(
Effect.andThen(ReadToolFileSystem.read(environment, absolute(path.join(directory, name)), name, page)),
Effect.map((result) => String(ReadTool.toModelContent(name, page.offset, result)).split("\n")),
)
const small = "one\ntwo\nthree\nfour\nfive\n"
expect(yield* read("small.txt", small, { offset: -3 })).toEqual([
"Read file small.txt, lines 3-5",
"3: three",
"4: four",
"5: five",
])
expect(yield* read("all.txt", small, { offset: -50 })).toEqual([
"Read file all.txt, lines 1-5",
"1: one",
"2: two",
"3: three",
"4: four",
"5: five",
])
expect(yield* read("limited.txt", small, { offset: -4, limit: 2 })).toEqual([
"Read file limited.txt, lines 2-3",
"2: two",
"3: three",
"[Output truncated. Continue reading with offset: 4]",
])
expect(yield* read("crlf.txt", "one\r\ntwo\r\nthree\r\n", { offset: -2 })).toEqual([
"Read file crlf.txt, lines 2-3",
"2: two",
"3: three",
])
expect(yield* read("unterminated.txt", "one\ntwo\nthree", { offset: -1 })).toEqual([
"Read file unterminated.txt, lines 3-3",
"3: three",
])
expect(yield* read("empty.txt", "", { offset: -5 })).toEqual(["Read file empty.txt, 0 lines"])
}),
)
it.effect("starts a negative offset from the end of a file larger than the first chunk", () =>
Effect.gen(function* () {
const { environment, files, directory } = yield* fixture
const read = (name: string, content: string, page: ReadToolFileSystem.PageInput) =>
files.writeFileString(path.join(directory, name), content).pipe(
Effect.andThen(ReadToolFileSystem.read(environment, absolute(path.join(directory, name)), name, page)),
Effect.map((result) => String(ReadTool.toModelContent(name, page.offset, result)).split("\n")),
)
const lines = Array.from({ length: 3_000 }, (_, index) => `${index + 1}`.padEnd(100, "x"))
const expected = (from: number, to = 3_000) =>
lines.slice(from - 1, to).map((line, index) => `${from + index}: ${line}`)
expect(yield* read("lf.txt", lines.join("\n") + "\n", { offset: -50 })).toEqual([
"Read file lf.txt, lines 2951-3000",
...expected(2_951),
])
expect(yield* read("window.txt", lines.join("\n") + "\n", { offset: -50, limit: 10 })).toEqual([
"Read file window.txt, lines 2951-2960",
...expected(2_951, 2_960),
"[Output truncated. Continue reading with offset: 2961]",
])
expect(yield* read("crlf.txt", lines.join("\r\n"), { offset: -3 })).toEqual([
"Read file crlf.txt, lines 2998-3000",
...expected(2_998),
])
// 3000 lines of 101 bytes exceed the 50 KB cap, so reading from line 1 stops after 506 like any read.
const whole = yield* read("whole.txt", lines.join("\n") + "\n", { offset: -5_000 })
expect([whole[0], whole.at(-2), whole.at(-1)]).toEqual([
"Read file whole.txt, lines 1-506",
`506: ${lines[505]}`,
"[Output truncated. Continue reading with offset: 507]",
])
// Each clamped line is 2041 bytes, so 25 of them fit in the 50 KB cap.
const wide = Array.from({ length: 200 }, (_, index) => `${index + 1}`.padEnd(3_000, "w"))
const clipped = yield* read("wide.txt", wide.join("\n") + "\n", { offset: -100 })
expect([clipped[0], clipped.at(-1)]).toEqual([
"Read file wide.txt, lines 101-125",
"[Output truncated. Continue reading with offset: 126]",
])
const short = lines.slice(0, 10)
const huge = yield* read("huge.txt", `${short.join("\n")}\n${"z".repeat(300 * 1024)}`, { offset: -20 })
expect(huge).toEqual([
"Read file huge.txt, lines 1-11",
...expected(1, 10),
`11: ${"z".repeat(2_000)}... (line truncated to 2000 chars)`,
])
}),
)
it.effect("rejects a negative offset for a directory", () =>
Effect.gen(function* () {
const { environment, files, directory } = yield* fixture
yield* files.writeFileString(path.join(directory, "a.txt"), "a\n")
const error = yield* ReadToolFileSystem.read(environment, absolute(directory), "src", { offset: -1 }).pipe(
Effect.flip,
)
expect(error).toBeInstanceOf(ReadToolFileSystem.DirectoryOffsetError)
expect(error.message).toBe("A negative offset only works for files, and src is a directory")
}),
)
+175 -20
View File
@@ -1,4 +1,5 @@
import { beforeEach, describe, expect } from "bun:test"
import fs from "fs/promises"
import path from "path"
import { Effect, Exit, Layer, Result } from "effect"
import { Config } from "@opencode/core/config"
@@ -14,7 +15,9 @@ import { Skill } from "@opencode/core/skill"
import { AbsolutePath, RelativePath } from "@opencode/core/schema"
import { Global } from "@opencode/util/global"
import { FileAccess } from "@opencode/core/file-access"
import { hostEnvironmentLayer } from "./fixture/environment"
import { location } from "./fixture/location"
import { withTempDir } from "./fixture/tmpdir"
import { Tool } from "@opencode/core/tool"
import { ReadTool } from "@opencode/core/tool/plugin/read"
import { ReadToolFileSystem } from "@opencode/core/tool/read-filesystem"
@@ -37,6 +40,7 @@ const readToolNode = makeLocationNode({
SessionInstructions.node,
Skill.node,
FSUtil.node,
Environment.node,
Location.node,
],
})
@@ -98,6 +102,7 @@ const permission = permissionLayer({
),
),
),
allows: (input) => Effect.succeed(allow && !input.resources.some((resource) => resource === deniedResource)),
})
const config = Config.testLayer()
const imageLayer = AppNodeBuilder.build(Image.node)
@@ -112,6 +117,7 @@ const readLayer = (imageLayer: Layer.Layer<Image.Service>) =>
Layer.mergeAll(
AppNodeBuilder.build(LayerNode.group([Tool.node, readToolNode, Skill.node]), [
ReadToolFileSystem.node.replace(reader),
Environment.node.replace(hostEnvironmentLayer),
Permission.node.replace(permission),
Config.node.replace(config),
Image.node.replace(imageLayer),
@@ -123,6 +129,38 @@ const readLayer = (imageLayer: Layer.Layer<Image.Service>) =>
imageLayer,
)
const it = testEffect(readLayer(imageLayer))
// Real-file tests provide their own layer per temp folder.
const live = testEffect(Layer.empty)
// Reads through the real filesystem with the location at `directory`; returns the failure message.
const readMissing = (directory: string, file: string) =>
Effect.gen(function* () {
const registry = yield* Tool.Service
const result = yield* executeTool(registry, {
sessionID,
...toolIdentity,
call: { type: "tool-call", id: "call-suggest", name: "read", input: { path: file } },
})
return result.error?.message
}).pipe(
Effect.provide(
Layer.mergeAll(
AppNodeBuilder.build(LayerNode.group([Tool.node, readToolNode, Skill.node]), [
Environment.node.replace(hostEnvironmentLayer),
Permission.node.replace(permission),
Config.node.replace(config),
Image.node.replace(imageLayer),
Location.node.replace(
Layer.succeed(Location.Service, Location.Service.of(location({ directory: AbsolutePath.make(directory) }))),
),
Global.node.replace(Global.layerWith({ data: Global.Path.data })),
]),
config,
imageLayer,
),
),
)
const write = (file: string) =>
Effect.promise(() => fs.mkdir(path.dirname(file), { recursive: true }).then(() => fs.writeFile(file, "x\n")))
const itWithoutResizer = testEffect(readLayer(unavailableImage))
const sessionID = Session.ID.make("ses_read_tool_test")
@@ -644,25 +682,14 @@ describe("ReadTool", () => {
it.effect("preserves actionable read failure messages", () =>
Effect.gen(function* () {
const registry = yield* Tool.Service
for (const [error, message] of [
[
new ReadToolFileSystem.OffsetOutOfRangeError({ offset: 10, lines: 3 }),
"Offset 10 is out of range for this file (3 lines)",
],
[
new ReadToolFileSystem.PathKindError({ resource: "socket", expected: "a file" }),
"Path is not a file: socket",
],
] as const) {
readFailure = error
expect(
yield* executeTool(registry, {
sessionID,
...toolIdentity,
call: { type: "tool-call", id: `call-${error._tag}`, name: "read", input: { path: "target" } },
}),
).toEqual({ status: "error", error: { type: "unknown", message } })
}
readFailure = new ReadToolFileSystem.PathKindError({ resource: "socket", expected: "a file" })
expect(
yield* executeTool(registry, {
sessionID,
...toolIdentity,
call: { type: "tool-call", id: "call-path-kind", name: "read", input: { path: "target" } },
}),
).toEqual({ status: "error", error: { type: "unknown", message: "Path is not a file: socket" } })
}),
)
@@ -724,7 +751,7 @@ describe("ReadTool", () => {
status: "error",
error: {
type: "tool.execution",
message: `File not found: ${missingPath}\n\nDid you mean one of these?\n__missing_read_target__.txt.bak\ncopy___missing_read_target__.txt\nold___missing_read_target__.txt`,
message: `File not found: ${missingPath}\n\nDid you mean one of these?\n__missing_read_target__.txt.bak\nold___missing_read_target__.txt\ncopy___missing_read_target__.txt`,
},
})
expect(assertions).toMatchObject([{ sessionID, action: "read", resources: [missingPath], save: ["*"] }])
@@ -794,6 +821,85 @@ describe("ReadTool", () => {
}),
)
live.live("suggests close names from the same folder", () =>
withTempDir((tmp) =>
Effect.gen(function* () {
for (const file of ["typo/config.ts", "typo/db.ts", "ext/config.yaml", "case/README.md"])
yield* write(path.join(tmp.path, file))
for (const file of ["short/db.ts", "short/io.ts", "short/api.ts", "short/build.ts"])
yield* write(path.join(tmp.path, file))
expect(yield* readMissing(tmp.path, "typo/conifg.ts")).toBe(
`File not found: typo/conifg.ts\n\nDid you mean one of these?\n${path.join("typo", "config.ts")}`,
)
expect(yield* readMissing(tmp.path, "ext/config.yml")).toBe(
`File not found: ext/config.yml\n\nDid you mean one of these?\n${path.join("ext", "config.yaml")}`,
)
expect(yield* readMissing(tmp.path, "short/ui.ts")).toBe("File not found: short/ui.ts")
// Case-insensitive filesystems, such as macOS by default, simply read the file.
expect([undefined, `File not found: case/readme.md\n\nDid you mean one of these?\n${path.join("case", "README.md")}`]).toContain(
yield* readMissing(tmp.path, "case/readme.md"),
)
}),
),
)
it.effect("ranks same-folder suggestions and shows at most three", () =>
Effect.gen(function* () {
readFailure = new Environment.NotFound({ path: path.join(process.cwd(), "config.ts") })
const registry = yield* Tool.Service
const read = () =>
executeTool(registry, {
sessionID,
...toolIdentity,
call: { type: "tool-call", id: "call-ranked", name: "read", input: { path: "config.ts" } },
}).pipe(Effect.map((result) => result.error?.message))
// Listed worst first: a typo, a containing name, the same stem, and the same name in another case.
directoryEntryDetails = ["confix.ts", "config.test.ts", "config.json", "Config.ts"].map((name) => ({
name,
type: "file" as const,
}))
expect(yield* read()).toBe(
"File not found: config.ts\n\nDid you mean one of these?\nConfig.ts\nconfig.json\nconfig.test.ts",
)
directoryEntryDetails = directoryEntryDetails.filter((entry) => entry.name !== "Config.ts")
expect(yield* read()).toBe(
"File not found: config.ts\n\nDid you mean one of these?\nconfig.json\nconfig.test.ts\nconfix.ts",
)
}),
)
live.live("suggests a path written from the parent of the location first", () =>
withTempDir((tmp) =>
Effect.gen(function* () {
const repo = path.join(tmp.path, "repo")
yield* write(path.join(repo, "src", "a.ts"))
const requested = path.join(tmp.path, "src", "a.ts")
expect(yield* readMissing(repo, requested)).toBe(
`File not found: ${requested}\n\nThe folder ${path.join(tmp.path, "src")} does not exist. The nearest folder that does is ${tmp.path}.\n\nDid you mean one of these?\n${path.join(repo, "src", "a.ts")}`,
)
yield* write(path.join(tmp.path, "src", "a.tsx"))
expect(yield* readMissing(repo, requested)).toBe(
`File not found: ${requested}\n\nDid you mean one of these?\n${path.join(repo, "src", "a.ts")}\n${path.join(tmp.path, "src", "a.tsx")}`,
)
}),
),
)
live.live("suggests close folder names from the nearest existing folder", () =>
withTempDir((tmp) =>
Effect.gen(function* () {
yield* write(path.join(tmp.path, "lib", "x.ts"))
expect(yield* readMissing(tmp.path, "libs/x.ts")).toBe(
`File not found: libs/x.ts\n\nThe folder ${path.join(tmp.path, "libs")} does not exist. The nearest folder that does is ${tmp.path}.\n\nDid you mean one of these?\n${path.join(tmp.path, "lib")}`,
)
}),
),
)
it.effect("recovers a unique file whose non-breaking spaces differ", () =>
Effect.gen(function* () {
const requested = "Screenshot 2026-08-27 3.15 PM.png"
@@ -1059,6 +1165,55 @@ describe("ReadTool", () => {
}),
)
it.effect("forwards a negative offset and shows the real line numbers and continuation", () =>
Effect.gen(function* () {
readResult = new ReadToolFileSystem.TextPage({
type: "text-page",
content: "nine\nten",
mime: "text/plain",
offset: 9,
truncated: true,
next: 11,
})
const registry = yield* Tool.Service
const result = yield* executeTool(registry, {
sessionID,
...toolIdentity,
call: { type: "tool-call", id: "call-tail", name: "read", input: { path: "log.txt", offset: -5, limit: 2 } },
})
expect(result.status).toBe("completed")
if (result.status !== "completed") return
expect(result.content).toEqual([
{
type: "text",
text: "Read file log.txt, lines 9-10\n9: nine\n10: ten\n[Output truncated. Continue reading with offset: 11]",
},
])
expect(readCalls).toEqual([
{ input: AbsolutePath.make(path.join(process.cwd(), "log.txt")), page: { offset: -5, limit: 2 } },
])
}),
)
it.effect("returns the negative directory offset error to the model", () =>
Effect.gen(function* () {
readFailure = new ReadToolFileSystem.DirectoryOffsetError({ resource: "src" })
const registry = yield* Tool.Service
expect(
yield* executeTool(registry, {
sessionID,
...toolIdentity,
call: { type: "tool-call", id: "call-dir-tail", name: "read", input: { path: "src", offset: -5 } },
}),
).toEqual({
status: "error",
error: { type: "unknown", message: "A negative offset only works for files, and src is a directory" },
})
}),
)
it.effect("reads virtual skill:// files and directories from Skill.Service without external_directory approval", () =>
Effect.gen(function* () {
const skills = yield* Skill.Service