@trim21/personal-pi-extensions 0.1.558 → 0.1.560

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.558",
+  "version": "0.1.560",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/claude-code/files.ts

@@ -118,6 +118,10 @@ function splitFileLines(content: string): string[] {
  * 的 `N\t` 前缀——tab 分隔符在 Go 等 tab 缩进语言里会与内容缩进连排，模型
  * 易误判多一层缩进。limit 未指定时读取全部。无 PARTIAL 提示、无单行截断
  * （由 execute 层的字节/token 上限兜底）。
+ *
+ * offset 为负数时从文件末尾倒数（`offset=-5` 等价 `tail -n 5`），超出文件
+ * 长度时钳到文件开头（与 tail 一致，不告警）。输出行号始终为绝对行号；
+ * offset=0 的「行号从 0 起」是对齐 Claude Code lineOffset 的历史语义。
  */
 export function formatReadOutput(
   content: string,
@@ -138,11 +142,11 @@ export function formatReadOutput(
       totalLines,
     };
   }
-  // offset=0 时从第一行开始、行号从 0 起（对齐 Claude Code 的 lineOffset 语义）
-  const startIndex = offset === 0 ? 0 : offset - 1;
+  const startIndex = offset === 0 ? 0 : offset > 0 ? offset - 1 : Math.max(totalLines + offset, 0);
+  const firstLine = offset === 0 ? 0 : startIndex + 1;
   const selected =
     limit === undefined ? lines.slice(startIndex) : lines.slice(startIndex, startIndex + limit);
-  const text = selected.map((line, index) => `${offset + index}: ${line}`).join("\n");
+  const text = selected.map((line, index) => `${firstLine + index}: ${line}`).join("\n");
   return { text, totalLines };
 }
 
@@ -234,6 +238,7 @@ export function registerFileTools(
       "Reads a file from the local filesystem. You can access any file directly using this tool.",
       "Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.",
       "The file_path parameter must be an absolute path. By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit.",
+      "Read parts of files with offset and limit instead of running head/tail via Bash: a positive offset is the starting line number, a negative offset counts from the end of the file (offset=-5 reads the last 5 lines, like tail -n 5).",
       "Results use cat -n style line numbers starting at 1. Images are returned visually.",
       "This tool reads files, not directories.",
     ].join("\n"),
@@ -243,9 +248,12 @@ export function registerFileTools(
       {
         file_path: Type.String({ description: "The absolute path to the file to read" }),
         offset: Type.Optional(
-          Type.Number({ description: "The line number to start reading from" }),
+          Type.Integer({
+            description:
+              "The line number to start reading from. A negative value counts from the end of the file (offset=-5 starts 5 lines before EOF).",
+          }),
         ),
-        limit: Type.Optional(Type.Number({ description: "The number of lines to read" })),
+        limit: Type.Optional(Type.Integer({ description: "The number of lines to read" })),
         pages: Type.Optional(
           Type.String({ description: 'Page range for PDF files (for example "1-5" or "3")' }),
         ),
@@ -255,11 +263,8 @@ export function registerFileTools(
     async execute(_id, params, signal, _onUpdate, ctx) {
       signal?.throwIfAborted();
       const filePath = requireAbsolutePath(params.file_path);
-      if (
-        params.offset !== undefined &&
-        (!Number.isSafeInteger(params.offset) || params.offset < 0)
-      ) {
-        throw new Error("offset must be a non-negative integer");
+      if (params.offset !== undefined && !Number.isSafeInteger(params.offset)) {
+        throw new Error("offset must be an integer");
       }
       if (params.limit !== undefined && (!Number.isSafeInteger(params.limit) || params.limit < 1)) {
         throw new Error("limit must be a positive integer");

package/src/claude-code/read.md

@@ -7,6 +7,7 @@ Usage:
 - The file_path parameter must be an absolute path, not a relative path
 - By default, it reads the entire file; files over 256 KB or 25K tokens require offset and limit to read specific portions
 - When you already know which part of the file you need, only read that part. This can be important for larger files.
+- Do not use head/tail (or sed -n) via the Bash tool to read parts of files — use offset and limit here instead. They are line-based: `offset=5, limit=10` reads 10 lines starting at line 5 (like `sed -n '5,14p'`), and a negative offset counts from the end of the file — `offset=-5` reads the last 5 lines (like `tail -n 5`). Line numbers in the output are always absolute.
 - Results are returned as `<lineNumber>: <content>` lines, 1-indexed
 - This tool allows you to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually.
 - This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.

package/src/opencode/files.ts

@@ -192,11 +192,17 @@ export interface LinePage {
  * - per-line truncation to MAX_LINE_LENGTH
  * - line cap via maxLines (more): keep scanning so count is the file total
  * - byte cap via maxBytes (cut): stop immediately
+ *
+ * offset 为负数时从文件末尾倒数（`offset=-2` 等价 `tail -n 2`）：流式单遍
+ * 扫描全程只保留末尾窗口，返回前把 offset 换算为正的绝对起始行号
+ * （`totalLines + offset + 1`，超出文件长度时钳到 1），行号/续读提示与
+ * 正向语义一致。
  */
 export async function readLines(
   filePath: string,
   opts: { offset: number; limit: number; maxBytes?: number },
 ): Promise<LinePage> {
+  if (opts.offset < 0) return readTailLines(filePath, opts);
   const start = opts.offset - 1;
   const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
   const raw: string[] = [];
@@ -236,6 +242,59 @@ export async function readLines(
   return { raw, count, cut, more, offset: opts.offset };
 }
 
+/**
+ * tail 语义的负 offset 实现：单遍流式扫描，环形缓冲只保留末尾 K 行
+ * （K = -offset），扫完后对窗口应用 limit 与字节上限，避免为取末尾几行
+ * 而把整个文件驻留内存。
+ */
+async function readTailLines(
+  filePath: string,
+  opts: { offset: number; limit: number; maxBytes?: number },
+): Promise<LinePage> {
+  const windowSize = -opts.offset;
+  const window: string[] = [];
+  let head = 0;
+  let count = 0;
+
+  const stream = createReadStream(filePath, { encoding: "utf8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const text of rl) {
+      count += 1;
+      const line =
+        text.length > MAX_LINE_LENGTH ? text.slice(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX : text;
+      window.push(line);
+      if (window.length > windowSize) head += 1;
+    }
+  } finally {
+    rl.close();
+    stream.destroy();
+  }
+
+  const offset = Math.max(count + opts.offset + 1, 1);
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const raw: string[] = [];
+  let bytes = 0;
+  let cut = false;
+  let more = false;
+  for (const line of window.slice(head)) {
+    if (raw.length >= opts.limit) {
+      more = true;
+      break;
+    }
+    const size = Buffer.byteLength(line, "utf8") + (raw.length > 0 ? 1 : 0);
+    if (bytes + size > maxBytes) {
+      cut = true;
+      more = true;
+      break;
+    }
+    raw.push(line);
+    bytes += size;
+  }
+
+  return { raw, count, cut, more, offset };
+}
+
 function truncationFromPage(page: LinePage): TruncationResult {
   const content = page.raw.join("\n");
   return {
@@ -299,15 +358,17 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
   pi.registerTool({
     name: "read",
     label: "read",
-    description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
+    description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. A negative offset counts from the end of the file (offset=-2 reads the last 2 lines). When you need the full file, continue with offset until complete.`,
     promptSnippet: "Read file contents",
-    promptGuidelines: ["Use read to examine files instead of cat or sed."],
+    promptGuidelines: [
+      "Use read to examine files instead of cat, sed, or tail. A negative offset reads from the end of the file (offset=-2 reads the last 2 lines).",
+    ],
     parameters: Type.Object({
       filePath: Type.String({ description: "The absolute path to the file or directory to read" }),
       offset: Type.Optional(
         Type.Integer({
-          minimum: 0,
-          description: "The line number to start reading from (1-indexed)",
+          description:
+            "The line number to start reading from (1-indexed; 0 is treated as 1). A negative value counts from the end of the file (offset=-2 reads the last 2 lines).",
         }),
       ),
       limit: Type.Optional(
@@ -340,9 +401,9 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
       if (fileStat.isDirectory()) {
         const entries = await formatDirectoryEntries(absolutePath);
         const limitVal = limit ?? DEFAULT_MAX_LINES;
-        // opencode: params.offset || 1（0 视为 1）
+        // opencode: params.offset || 1（0 视为 1）；负数从末尾倒数
         const offsetVal = offset || 1;
-        const start = offsetVal - 1;
+        const start = offsetVal < 0 ? Math.max(entries.length + offsetVal, 0) : offsetVal - 1;
         const sliced = entries.slice(start, start + limitVal);
         const totalEntries = entries.length;
         const truncated = start + sliced.length < totalEntries;