saeeol 1.2.0 → 1.2.2

package/src/tool/file/edit.ts

@@ -0,0 +1,262 @@
+// the approaches in this edit tool are sourced from
+// https://github.com/cline/cline/blob/main/evals/diff-edits/diff-apply/diff-06-23-25.ts
+// https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/utils/editCorrector.ts
+// https://github.com/cline/cline/blob/main/evals/diff-edits/diff-apply/diff-06-26-25.ts
+
+import * as path from "path"
+import { Effect, Schema, Semaphore } from "effect"
+import * as Tool from "../core/tool"
+import { LSP } from "@/lsp/lsp"
+import { createTwoFilesPatch } from "diff"
+import DESCRIPTION from "./edit.txt"
+import { File } from "../../file"
+import { FileWatcher } from "../../file/watcher"
+import { Bus } from "../../bus"
+import { Format } from "../../format"
+import { InstanceState } from "@/effect/instance-state"
+import { Snapshot } from "@/snapshot"
+import { assertExternalDirectoryEffect } from "../core/external-directory"
+import { AppFileSystem } from "@saeeol/core/filesystem"
+import * as Bom from "@/util/bom"
+import { filterDiagnostics } from "../integration/diagnostics"
+import { ConfigValidation } from "../../overlay/config-validation"
+import * as EncodedIO from "../../overlay/tool/encoded-io"
+import { buildFileDiff, normalizeLineEndings, detectLineEnding, convertToLineEnding, trimDiff } from "./edit-utils"
+import {
+  SimpleReplacer,
+  LineTrimmedReplacer,
+  BlockAnchorReplacer,
+  WhitespaceNormalizedReplacer,
+  IndentationFlexibleReplacer,
+  EscapeNormalizedReplacer,
+  MultiOccurrenceReplacer,
+  TrimmedBoundaryReplacer,
+  ContextAwareReplacer,
+} from "./edit-replacers"
+
+export { buildFileDiff, trimDiff } from "./edit-utils"
+export type { Replacer } from "./edit-replacers"
+export {
+  SimpleReplacer,
+  LineTrimmedReplacer,
+  BlockAnchorReplacer,
+  WhitespaceNormalizedReplacer,
+  IndentationFlexibleReplacer,
+  EscapeNormalizedReplacer,
+  MultiOccurrenceReplacer,
+  TrimmedBoundaryReplacer,
+  ContextAwareReplacer,
+} from "./edit-replacers"
+
+const locks = new Map<string, Semaphore.Semaphore>()
+
+function lock(filePath: string) {
+  const resolvedFilePath = AppFileSystem.resolve(filePath)
+  const hit = locks.get(resolvedFilePath)
+  if (hit) return hit
+
+  const next = Semaphore.makeUnsafe(1)
+  locks.set(resolvedFilePath, next)
+  return next
+}
+
+export const Parameters = Schema.Struct({
+  filePath: Schema.String.annotate({ description: "The absolute path to the file to modify" }),
+  oldString: Schema.String.annotate({ description: "The text to replace" }),
+  newString: Schema.String.annotate({
+    description: "The text to replace it with (must be different from oldString)",
+  }),
+  replaceAll: Schema.optional(Schema.Boolean).annotate({
+    description: "Replace all occurrences of oldString (default false)",
+  }),
+})
+
+export function replace(content: string, oldString: string, newString: string, replaceAll = false): string {
+  if (oldString === newString) {
+    throw new Error("No changes to apply: oldString and newString are identical.")
+  }
+  let notFound = true
+  for (const replacer of [
+    SimpleReplacer,
+    LineTrimmedReplacer,
+    BlockAnchorReplacer,
+    WhitespaceNormalizedReplacer,
+    IndentationFlexibleReplacer,
+    EscapeNormalizedReplacer,
+    TrimmedBoundaryReplacer,
+    ContextAwareReplacer,
+    MultiOccurrenceReplacer,
+  ]) {
+    for (const search of replacer(content, oldString)) {
+      const index = content.indexOf(search)
+      if (index === -1) continue
+      notFound = false
+      if (replaceAll) {
+        return content.replaceAll(search, newString)
+      }
+      const lastIndex = content.lastIndexOf(search)
+      if (index !== lastIndex) continue
+      return content.substring(0, index) + newString + content.substring(index + search.length)
+    }
+  }
+  if (notFound) {
+    throw new Error(
+      "Could not find oldString in the file. It must match exactly, including whitespace, indentation, and line endings.",
+    )
+  }
+  throw new Error("Found multiple matches for oldString. Provide more surrounding context to make the match unique.")
+}
+
+export const EditTool = Tool.define(
+  "edit",
+  Effect.gen(function* () {
+    const lsp = yield* LSP.Service
+    const afs = yield* AppFileSystem.Service
+    const format = yield* Format.Service
+    const bus = yield* Bus.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          if (!params.filePath) {
+            throw new Error("filePath is required")
+          }
+
+          if (params.oldString === params.newString) {
+            throw new Error("No changes to apply: oldString and newString are identical.")
+          }
+
+          const instance = yield* InstanceState.context
+          const filePath = path.isAbsolute(params.filePath)
+            ? params.filePath
+            : path.join(instance.directory, params.filePath)
+          yield* assertExternalDirectoryEffect(ctx, filePath)
+
+          let diff = ""
+          let contentOld = ""
+          let contentNew = ""
+          let cachedFilediff: Snapshot.FileDiff | undefined
+          yield* lock(filePath).withPermits(1)(
+            Effect.gen(function* () {
+              if (params.oldString === "") {
+                const existed = yield* afs.existsSafe(filePath)
+                // derive the BOM flag from the detected encoding label instead of the decoded text.
+                const pre = existed ? yield* EncodedIO.read(filePath) : { text: "", encoding: "utf-8" }
+                const source = { bom: pre.encoding === "utf-8-bom", text: pre.text, encoding: pre.encoding }
+                const next = Bom.split(params.newString)
+                const desiredBom = source.bom || next.bom
+                contentOld = source.text
+                contentNew = next.text
+                diff = trimDiff(createTwoFilesPatch(filePath, filePath, contentOld, contentNew))
+                cachedFilediff = buildFileDiff(filePath, contentOld, contentNew)
+                yield* ctx.ask({
+                  permission: "edit",
+                  patterns: [path.relative(instance.worktree, filePath)],
+                  always: ["*"],
+                  metadata: {
+                    filepath: filePath,
+                    diff,
+                    filediff: cachedFilediff,
+                  },
+                })
+                yield* EncodedIO.write(filePath, Bom.join(contentNew, desiredBom), source.encoding)
+                if (yield* format.file(filePath)) {
+                  contentNew = yield* Bom.syncFile(afs, filePath, desiredBom)
+                }
+                yield* bus.publish(File.Event.Edited, { file: filePath })
+                yield* bus.publish(FileWatcher.Event.Updated, {
+                  file: filePath,
+                  event: existed ? "change" : "add",
+                })
+                return
+              }
+
+              const info = yield* afs.stat(filePath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+              if (!info) throw new Error(`File ${filePath} not found`)
+              if (info.type === "Directory") throw new Error(`Path is a directory, not a file: ${filePath}`)
+              // derive the BOM flag from the detected encoding label instead of the decoded text.
+              const pre = yield* EncodedIO.read(filePath)
+              const source = { bom: pre.encoding === "utf-8-bom", text: pre.text, encoding: pre.encoding }
+              contentOld = source.text
+
+              const ending = detectLineEnding(contentOld)
+              const old = convertToLineEnding(normalizeLineEndings(params.oldString), ending)
+              const replacement = convertToLineEnding(normalizeLineEndings(params.newString), ending)
+
+              const next = Bom.split(replace(contentOld, old, replacement, params.replaceAll))
+              const desiredBom = source.bom || next.bom
+              contentNew = next.text
+
+              diff = trimDiff(
+                createTwoFilesPatch(
+                  filePath,
+                  filePath,
+                  normalizeLineEndings(contentOld),
+                  normalizeLineEndings(contentNew),
+                ),
+              )
+              cachedFilediff = buildFileDiff(filePath, contentOld, contentNew)
+              yield* ctx.ask({
+                permission: "edit",
+                patterns: [path.relative(instance.worktree, filePath)],
+                always: ["*"],
+                metadata: {
+                  filepath: filePath,
+                  diff,
+                  filediff: cachedFilediff,
+                },
+              })
+
+              yield* EncodedIO.write(filePath, Bom.join(contentNew, desiredBom), source.encoding)
+              if (yield* format.file(filePath)) {
+                contentNew = yield* Bom.syncFile(afs, filePath, desiredBom)
+              }
+              yield* bus.publish(File.Event.Edited, { file: filePath })
+              yield* bus.publish(FileWatcher.Event.Updated, {
+                file: filePath,
+                event: "change",
+              })
+              diff = trimDiff(
+                createTwoFilesPatch(
+                  filePath,
+                  filePath,
+                  normalizeLineEndings(contentOld),
+                  normalizeLineEndings(contentNew),
+                ),
+              )
+            }).pipe(Effect.orDie),
+          )
+
+          const filediff: Snapshot.FileDiff = cachedFilediff ?? buildFileDiff(filePath, contentOld, contentNew)
+
+          yield* ctx.metadata({
+            metadata: {
+              diff,
+              filediff,
+              diagnostics: {},
+            },
+          })
+
+          let output = "Edit applied successfully."
+          yield* lsp.touchFile(filePath, "document")
+          const diagnostics = yield* lsp.diagnostics()
+          const normalizedFilePath = AppFileSystem.normalizePath(filePath)
+          const block = LSP.Diagnostic.report(filePath, diagnostics[normalizedFilePath] ?? [])
+          if (block) output += `\n\nLSP errors detected in this file, please fix:\n${block}`
+          output += yield* Effect.promise(() => ConfigValidation.check(filePath))
+
+          return {
+            metadata: {
+              diagnostics: filterDiagnostics(diagnostics, [normalizedFilePath]),
+              diff,
+              filediff,
+            },
+            title: `${path.relative(instance.worktree, filePath)}`,
+            output,
+          }
+        }),
+    }
+  }),
+)

package/src/tool/file/edit.txt

@@ -0,0 +1,10 @@
+Performs exact string replacements in files. 
+
+Usage:
+- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. 
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + colon + space (e.g., `1: `). Everything after that space is the actual file content to match. Never include any part of the line number prefix in the oldString or newString.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if `oldString` is not found in the file with an error "oldString not found in content".
+- The edit will FAIL if `oldString` is found multiple times in the file with an error "Found multiple matches for oldString. Provide more surrounding lines in oldString to identify the correct match." Either provide a larger string with more surrounding context to make it unique or use `replaceAll` to change every instance of `oldString`. 
+- Use `replaceAll` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.

package/src/tool/file/read.ts

@@ -0,0 +1,389 @@
+import { lstat } from "fs/promises" 
+import { Effect, Option, Schema, Scope } from "effect"
+import { NonNegativeInt } from "@/util/schema"
+import * as path from "path"
+import type { Readable } from "stream" 
+import { createInterface } from "readline"
+import * as Tool from "../core/tool"
+import { AppFileSystem } from "@saeeol/core/filesystem"
+import { LSP } from "@/lsp/lsp"
+import DESCRIPTION from "./read.txt"
+import { InstanceState } from "@/effect/instance-state"
+import { assertExternalDirectoryEffect } from "../core/external-directory"
+import { Instruction } from "../../session/instruction"
+import { isPdfAttachment, sniffAttachmentMime } from "@/util/media"
+import * as Encoding from "../../overlay/encoding"
+import * as TextStream from "../../overlay/text-stream"
+
+const DEFAULT_READ_LIMIT = 2000
+const MAX_LINE_LENGTH = 2000
+const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`
+const MAX_BYTES = 50 * 1024
+const MAX_BYTES_LABEL = `${MAX_BYTES / 1024} KB`
+const SAMPLE_BYTES = 4096
+const DIRECTORY_CONCURRENCY = 8 
+const SUPPORTED_IMAGE_MIMES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"])
+
+// `offset` and `limit` were originally `z.coerce.number()` — the runtime
+// coercion was useful when the tool was called from a shell but serves no
+// purpose in the LLM tool-call path (the model emits typed JSON). The JSON
+// Schema output is identical (`type: "number"`), so the LLM view is
+// unchanged; purely CLI-facing uses must now send numbers rather than strings.
+export const Parameters = Schema.Struct({
+  filePath: Schema.String.annotate({ description: "The absolute path to the file or directory to read" }),
+  offset: Schema.optional(NonNegativeInt).annotate({
+    description: "The line number to start reading from (1-indexed)",
+  }),
+  limit: Schema.optional(NonNegativeInt).annotate({
+    description: "The maximum number of lines to read (defaults to 2000)",
+  }),
+})
+
+export const ReadTool = Tool.define(
+  "read",
+  Effect.gen(function* () {
+    const fs = yield* AppFileSystem.Service
+    const instruction = yield* Instruction.Service
+    const lsp = yield* LSP.Service
+    const scope = yield* Scope.Scope
+
+    const miss = Effect.fn("ReadTool.miss")(function* (filepath: string) {
+      const dir = path.dirname(filepath)
+      const base = path.basename(filepath)
+      const items = yield* fs.readDirectory(dir).pipe(
+        Effect.map((items) =>
+          items
+            .filter(
+              (item) =>
+                item.toLowerCase().includes(base.toLowerCase()) || base.toLowerCase().includes(item.toLowerCase()),
+            )
+            .map((item) => path.join(dir, item))
+            .slice(0, 3),
+        ),
+        Effect.catch(() => Effect.succeed([] as string[])),
+      )
+
+      if (items.length > 0) {
+        return yield* Effect.fail(
+          new Error(`File not found: ${filepath}\n\nDid you mean one of these?\n${items.join("\n")}`),
+        )
+      }
+
+      return yield* Effect.fail(new Error(`File not found: ${filepath}`))
+    })
+
+    const list = Effect.fn("ReadTool.list")(function* (filepath: string) {
+      const items = yield* fs.readDirectoryEntries(filepath)
+      return yield* Effect.forEach(
+        items,
+        Effect.fnUntraced(function* (item) {
+          if (item.type === "directory") return item.name + "/"
+          if (item.type !== "symlink") return item.name
+
+          const target = yield* fs.stat(path.join(filepath, item.name)).pipe(Effect.catch(() => Effect.void))
+          if (target?.type === "Directory") return item.name + "/"
+          return item.name
+        }),
+        { concurrency: "unbounded" },
+      ).pipe(Effect.map((items: string[]) => items.sort((a, b) => a.localeCompare(b))))
+    })
+
+    const warm = Effect.fn("ReadTool.warm")(function* (filepath: string) {
+      yield* lsp.touchFile(filepath).pipe(Effect.ignore, Effect.forkIn(scope))
+    })
+
+    const readSample = Effect.fn("ReadTool.readSample")(function* (
+      filepath: string,
+      fileSize: number,
+      sampleSize: number,
+    ) {
+      if (fileSize === 0) return new Uint8Array()
+
+      return yield* Effect.scoped(
+        Effect.gen(function* () {
+          const file = yield* fs.open(filepath, { flag: "r" })
+          return Option.getOrElse(yield* file.readAlloc(Math.min(sampleSize, fileSize)), () => new Uint8Array())
+        }),
+      )
+    })
+
+    const isBinaryFile = (filepath: string, bytes: Uint8Array) => {
+      const ext = path.extname(filepath).toLowerCase()
+      switch (ext) {
+        case ".zip":
+        case ".tar":
+        case ".gz":
+        case ".exe":
+        case ".dll":
+        case ".so":
+        case ".class":
+        case ".jar":
+        case ".war":
+        case ".7z":
+        case ".doc":
+        case ".docx":
+        case ".xls":
+        case ".xlsx":
+        case ".ppt":
+        case ".pptx":
+        case ".odt":
+        case ".ods":
+        case ".odp":
+        case ".bin":
+        case ".dat":
+        case ".obj":
+        case ".o":
+        case ".a":
+        case ".lib":
+        case ".wasm":
+        case ".pyc":
+        case ".pyo":
+          return true
+      }
+
+      if (bytes.length === 0) return false
+      const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+      if (Encoding.hasUtf16Bom(buf, bytes.length) || Encoding.hasUtf32Bom(buf, bytes.length)) return false
+
+      let nonPrintableCount = 0
+      for (let i = 0; i < bytes.length; i++) {
+        if (bytes[i] === 0) return true
+        if (bytes[i] < 9 || (bytes[i] > 13 && bytes[i] < 32)) {
+          nonPrintableCount++
+        }
+      }
+
+      return nonPrintableCount / bytes.length > 0.3
+    }
+    type DirectoryFile = {
+      filepath: string
+      content: string
+    }
+    const readDirectoryFiles = Effect.fn("ReadTool.readDirectoryFiles")(function* (
+      filepath: string,
+      items: string[],
+      directory: string,
+    ) {
+      const entries = yield* fs.readDirectoryEntries(filepath).pipe(Effect.catch(() => Effect.succeed([])))
+      const types = new Map(entries.map((entry) => [entry.name, entry.type]))
+      const files = yield* Effect.forEach(
+        items.filter((item) => !item.endsWith("/") && types.get(item) === "file"),
+        Effect.fnUntraced(function* (item) {
+          const child = path.join(filepath, item)
+          const info = yield* Effect.promise(() => lstat(child)).pipe(Effect.catch(() => Effect.void))
+          if (!info?.isFile()) return
+          const sample = yield* readSample(child, Number(info.size), SAMPLE_BYTES).pipe(
+            Effect.catch(() => Effect.succeed(new Uint8Array())),
+          )
+          if (isBinaryFile(child, sample)) return
+          const file = yield* Effect.promise(() => lines(child, { limit: DEFAULT_READ_LIMIT, offset: 1 })).pipe(
+            Effect.catch(() => Effect.void),
+          )
+          if (!file) return
+          const rel = path.relative(directory, child).replaceAll("\\", "/")
+          const note = file.cut || file.more ? "\n\n(File truncated)" : ""
+          return {
+            filepath: child,
+            content: `<file_content path="${rel}">\n${file.raw.join("\n")}${note}\n</file_content>`,
+          }
+        }),
+        { concurrency: DIRECTORY_CONCURRENCY },
+      )
+      return files.filter((item): item is DirectoryFile => item !== undefined)
+    })
+
+    const run = Effect.fn("ReadTool.execute")(function* (
+      params: Schema.Schema.Type<typeof Parameters>,
+      ctx: Tool.Context,
+    ) {
+      const instance = yield* InstanceState.context
+      let filepath = params.filePath
+      if (!path.isAbsolute(filepath)) {
+        filepath = path.resolve(instance.directory, filepath)
+      }
+      if (process.platform === "win32") {
+        filepath = AppFileSystem.normalizePath(filepath)
+      }
+      const title = path.relative(instance.worktree, filepath)
+
+      const stat = yield* fs.stat(filepath).pipe(
+        Effect.catchIf(
+          (err) => "reason" in err && err.reason._tag === "NotFound",
+          () => Effect.succeed(undefined),
+        ),
+      )
+
+      yield* assertExternalDirectoryEffect(ctx, filepath, {
+        bypass: Boolean(ctx.extra?.["bypassCwdCheck"]),
+        kind: stat?.type === "Directory" ? "directory" : "file",
+      })
+
+      yield* ctx.ask({
+        permission: "read",
+        patterns: [filepath],
+        always: ["*"],
+        metadata: {},
+      })
+
+      if (!stat) return yield* miss(filepath)
+
+      if (stat.type === "Directory") {
+        const items = yield* list(filepath)
+        const limit = params.limit ?? DEFAULT_READ_LIMIT
+        const offset = params.offset || 1
+        const start = offset - 1
+        const sliced = items.slice(start, start + limit)
+        const truncated = start + sliced.length < items.length
+        const expand = Boolean(ctx.extra?.["includeDirectoryFiles"])
+        const loaded = expand ? yield* readDirectoryFiles(filepath, sliced, instance.directory) : []
+        const content = loaded.map((item) => item.content).join("\n\n")
+
+        return {
+          title,
+          output: [
+            `<path>${filepath}</path>`,
+            `<type>directory</type>`,
+            `<entries>`,
+            sliced.join("\n"),
+            truncated
+              ? `\n(Showing ${sliced.length} of ${items.length} entries. Use 'offset' parameter to read beyond entry ${offset + sliced.length})`
+              : `\n(${items.length} entries)`,
+            `</entries>`,
+            ...(content ? [`\n${content}`] : []),
+          ].join("\n"),
+          metadata: {
+            preview: sliced.slice(0, 20).join("\n"),
+            truncated,
+            loaded: loaded.map((item) => item.filepath),
+          },
+        }
+      }
+
+      const loaded = yield* instruction.resolve(ctx.messages, filepath, ctx.messageID)
+      const sample = yield* readSample(filepath, Number(stat.size), SAMPLE_BYTES)
+
+      const mime = sniffAttachmentMime(sample, AppFileSystem.mimeType(filepath))
+      const isImage = SUPPORTED_IMAGE_MIMES.has(mime)
+
+      if (isImage || isPdfAttachment(mime)) {
+        const bytes = yield* fs.readFile(filepath)
+        const msg = isPdfAttachment(mime) ? "PDF read successfully" : "Image read successfully"
+        return {
+          title,
+          output: msg,
+          metadata: {
+            preview: msg,
+            truncated: false,
+            loaded: loaded.map((item) => item.filepath),
+          },
+          attachments: [
+            {
+              type: "file" as const,
+              mime,
+              url: `data:${mime};base64,${Buffer.from(bytes).toString("base64")}`,
+            },
+          ],
+        }
+      }
+
+      if (isBinaryFile(filepath, sample)) {
+        return yield* Effect.fail(new Error(`Cannot read binary file: ${filepath}`))
+      }
+
+      const file = yield* Effect.promise(() =>
+        lines(filepath, { limit: params.limit ?? DEFAULT_READ_LIMIT, offset: params.offset || 1 }),
+      )
+      if (file.count < file.offset && !(file.count === 0 && file.offset === 1)) {
+        return yield* Effect.fail(
+          new Error(`Offset ${file.offset} is out of range for this file (${file.count} lines)`),
+        )
+      }
+
+      let output = [`<path>${filepath}</path>`, `<type>file</type>`, "<content>\n"].join("\n")
+      output += file.raw.map((line, i) => `${i + file.offset}: ${line}`).join("\n")
+
+      const last = file.offset + file.raw.length - 1
+      const next = last + 1
+      const truncated = file.more || file.cut
+      if (file.cut) {
+        output += `\n\n(Output capped at ${MAX_BYTES_LABEL}. Showing lines ${file.offset}-${last}. Use offset=${next} to continue.)`
+      } else if (file.more) {
+        output += `\n\n(Showing lines ${file.offset}-${last} of ${file.count}. Use offset=${next} to continue.)`
+      } else {
+        output += `\n\n(End of file - total ${file.count} lines)`
+      }
+      output += "\n</content>"
+
+      yield* warm(filepath)
+
+      if (loaded.length > 0) {
+        output += `\n\n<system-reminder>\n${loaded.map((item) => item.content).join("\n\n")}\n</system-reminder>`
+      }
+
+      return {
+        title,
+        output,
+        metadata: {
+          preview: file.raw.slice(0, 20).join("\n"),
+          truncated,
+          loaded: loaded.map((item) => item.filepath),
+        },
+      }
+    })
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        run(params, ctx).pipe(Effect.orDie),
+    }
+  }),
+)
+// routed through TextStream.withFallback so non-UTF-8 files are decoded via
+// iconv. The body otherwise matches upstream.
+export async function lines(filepath: string, opts: { limit: number; offset: number }) {
+  return TextStream.withFallback(filepath, (stream) => readLines(stream, opts))
+}
+
+async function readLines(stream: Readable, opts: { limit: number; offset: number }) {
+  const rl = createInterface({
+    input: stream,
+    // Note: we use the crlfDelay option to recognize all instances of CR LF
+    // ('\r\n') in file as a single line break.
+    crlfDelay: Infinity,
+  })
+
+  const start = opts.offset - 1
+  const raw: string[] = []
+  let bytes = 0
+  let count = 0
+  let cut = false
+  let more = false
+  try {
+    for await (const text of rl) {
+      count += 1
+      if (count <= start) continue
+
+      if (raw.length >= opts.limit) {
+        more = true
+        continue
+      }
+
+      const line = text.length > MAX_LINE_LENGTH ? text.substring(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX : text
+      const size = Buffer.byteLength(line, "utf-8") + (raw.length > 0 ? 1 : 0)
+      if (bytes + size > MAX_BYTES) {
+        cut = true
+        more = true
+        break
+      }
+
+      raw.push(line)
+      bytes += size
+    }
+  } finally {
+    rl.close()
+    stream.destroy()
+  }
+
+  return { raw, count, cut, more, offset: opts.offset }
+}

package/src/tool/file/read.txt

@@ -0,0 +1,14 @@
+Read a file or directory from the local filesystem. If the path does not exist, an error is returned.
+
+Usage:
+- The filePath parameter should be an absolute path.
+- By default, this tool returns up to 2000 lines from the start of the file.
+- The offset parameter is the line number to start from (1-indexed).
+- To read later sections, call this tool again with a larger offset.
+- Use the grep tool to find specific content in large files or files with long lines.
+- If you are unsure of the correct file path, use the glob tool to look up filenames by glob pattern.
+- Contents are returned with each line prefixed by its line number as `<line>: <content>`. For example, if a file has contents "foo\n", you will receive "1: foo\n". For directories, entries are returned one per line (without line numbers) with a trailing `/` for subdirectories.
+- Any line longer than 2000 characters is truncated.
+- Call this tool in parallel when you know there are multiple files you want to read.
+- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.
+- This tool can read image files and PDFs and return them as file attachments.