@aexol/spectral 0.9.127 → 0.9.128

package/dist/sdk/coding-agent/core/tools/edit-diff.js

@@ -7,13 +7,21 @@ import { constants } from "fs";
 import { access, readFile } from "fs/promises";
 import { resolveToCwd } from "./path-utils.js";
 export function detectLineEnding(content) {
-    const crlfIdx = content.indexOf("\r\n");
-    const lfIdx = content.indexOf("\n");
-    if (lfIdx === -1)
-        return "\n";
-    if (crlfIdx === -1)
+    let crlfCount = 0;
+    let lfCount = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] !== "\n")
+            continue;
+        if (i > 0 && content[i - 1] === "\r") {
+            crlfCount++;
+        }
+        else {
+            lfCount++;
+        }
+    }
+    if (crlfCount === 0 && lfCount === 0)
         return "\n";
-    return crlfIdx < lfIdx ? "\r\n" : "\n";
+    return crlfCount > lfCount ? "\r\n" : "\n";
 }
 export function normalizeToLF(text) {
     return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -22,31 +30,26 @@ export function restoreLineEndings(text, ending) {
     return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
 }
 /**
- * Normalize text for fuzzy matching. Applies progressive transformations:
+ * Normalize text for fuzzy matching. Applies only semantically-safe
+ * whitespace/visibility transformations:
  * - Strip trailing whitespace from each line
- * - Normalize smart quotes to ASCII equivalents
- * - Normalize Unicode dashes/hyphens to ASCII hyphen
- * - Normalize special Unicode spaces to regular space
+ * - Normalize special Unicode spaces to a regular space
+ *
+ * Intentionally does NOT perform NFKC compatibility decomposition, smart-quote
+ * → straight-quote, or dash/hyphen substitutions: those transformations make
+ * semantically different code match silently. Matching across those characters
+ * requires the oldText to use the exact same characters as the file.
  */
 export function normalizeForFuzzyMatch(text) {
-    return (text
-        .normalize("NFKC")
-        // Strip trailing whitespace per line
+    return text
+        // Strip trailing whitespace per line (tab/space visibility tolerance)
         .split("\n")
         .map((line) => line.trimEnd())
         .join("\n")
-        // Smart single quotes → '
-        .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
-        // Smart double quotes → "
-        .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
-        // Various dashes/hyphens → -
-        // U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash,
-        // U+2013 en-dash, U+2014 em-dash, U+2015 horizontal bar, U+2212 minus
-        .replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
-        // Special spaces → regular space
+        // Special spaces → regular space (whitespace-equivalence only)
         // U+00A0 NBSP, U+2002-U+200A various spaces, U+202F narrow NBSP,
         // U+205F medium math space, U+3000 ideographic space
-        .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " "));
+        .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
 }
 function findExactMatches(content, oldText) {
     const matches = [];
@@ -194,6 +197,12 @@ function findLineTrimmedMatches(content, oldText) {
     }
     return dedupeMatches(matches);
 }
+/**
+ * Files at or above this size skip the O(n) normalized index map. Line-trimmed
+ * matching (which already covers tab/space/CRLF tolerance) is still attempted;
+ * only the costly normalized pass is skipped for large files.
+ */
+const NORMALIZED_MATCH_MAX_BYTES = 256 * 1024; // 256KB
 function findTextMatches(content, oldText) {
     const exactMatches = findExactMatches(content, oldText);
     if (exactMatches.length > 0)
@@ -201,6 +210,8 @@ function findTextMatches(content, oldText) {
     const lineTrimmedMatches = findLineTrimmedMatches(content, oldText);
     if (lineTrimmedMatches.length > 0)
         return lineTrimmedMatches;
+    if (content.length >= NORMALIZED_MATCH_MAX_BYTES)
+        return [];
     return findNormalizedTextMatches(content, oldText);
 }
 export function fuzzyFindText(content, oldText) {
@@ -240,8 +251,14 @@ function adaptIndentationFlexibleReplacement(oldText, newText, matchedText) {
     const matchedBaseIndent = leadingWhitespace(matchedBaseLine);
     if (oldBaseIndent === matchedBaseIndent)
         return newText;
+    // When oldText/matchedText/newText have differing line counts, only adapt the
+    // common-length prefix; leave the remaining newText lines untouched so a
+    // divergent tail is not corrupted by fabricated base-indent prefixes.
+    const commonLength = Math.min(oldLines.length, matchedLines.length, newLines.length);
     return newLines
         .map((line, index) => {
+        if (index >= commonLength)
+            return line;
         if (line.trim().length === 0)
             return line;
         const oldLine = oldLines[index];
@@ -312,6 +329,7 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
     }
     const baseContent = normalizedContent;
     const matchedEdits = [];
+    let usedFuzzyMatch = false;
     for (let i = 0; i < normalizedEdits.length; i++) {
         const edit = normalizedEdits[i];
         const matches = findTextMatches(baseContent, edit.oldText);
@@ -322,6 +340,8 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
             throw getDuplicateError(path, i, normalizedEdits.length, matches.length);
         }
         const match = matches[0];
+        if (match.strategy !== "exact")
+            usedFuzzyMatch = true;
         matchedEdits.push({
             editIndex: i,
             matchIndex: match.index,
@@ -348,7 +368,7 @@ export function applyEditsToNormalizedContent(normalizedContent, edits, path) {
     if (baseContent === newContent) {
         throw getNoChangeError(path, normalizedEdits.length);
     }
-    return { baseContent, newContent };
+    return { baseContent, newContent, usedFuzzyMatch };
 }
 /** Generate a standard unified patch. */
 export function generateUnifiedPatch(path, oldContent, newContent, contextLines = 4) {

package/dist/sdk/coding-agent/core/tools/edit.d.ts

@@ -1,4 +1,5 @@
 import type { AgentTool } from "../../../agent-core/index.js";
+import type { Stats } from "fs";
 import { type Static, Type } from "typebox";
 import type { ToolDefinition } from "../extensions/types.js";
 declare const editSchema: Type.TObject<{
@@ -28,6 +29,11 @@ export interface EditOperations {
     writeFile: (absolutePath: string, content: string) => Promise<void>;
     /** Check if file is readable and writable (throw if not) */
     access: (absolutePath: string) => Promise<void>;
+    /**
+     * Stat a file to obtain a freshness token (mtime). Used to detect stale reads
+     * between read and write. Optional — defaults to local fs.stat.
+     */
+    stat?: (absolutePath: string) => Promise<Stats>;
 }
 export interface EditToolOptions {
     /** Custom operations for file editing. Default: local filesystem */

package/dist/sdk/coding-agent/core/tools/edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/edit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA6B7D,QAAA,MAAM,UAAU;;;;;;EASf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAMtD,MAAM,WAAW,eAAe;IAC/B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,8BAA8B;IAC9B,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,4DAA4D;IAC5D,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAQD,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAoFD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAsIhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/edit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA8B7D,QAAA,MAAM,UAAU;;;;;;EASf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAMtD,MAAM,WAAW,eAAe;IAC/B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,8BAA8B;IAC9B,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,4DAA4D;IAC5D,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;CAChD;AASD,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAqGD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAyJhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}

package/dist/sdk/coding-agent/core/tools/edit.js

@@ -1,8 +1,9 @@
 import { constants } from "fs";
-import { access as fsAccess, readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
+import { access as fsAccess, readFile as fsReadFile, stat as fsStat, writeFile as fsWriteFile } from "fs/promises";
 import { Type } from "typebox";
 import { renderDiff } from "./render-diff.js";
 import { applyEditsToNormalizedContent, detectLineEnding, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, stripBom, } from "./edit-diff.js";
+import { atomicWriteFile } from "./atomic-write.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { resolveToCwd } from "./path-utils.js";
 import { shortenPath, str } from "./render-utils.js";
@@ -23,6 +24,7 @@ const defaultEditOperations = {
     readFile: (path) => fsReadFile(path),
     writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
     access: (path) => fsAccess(path, constants.R_OK | constants.W_OK),
+    stat: (path) => fsStat(path),
 };
 function prepareEditArguments(input) {
     if (!input || typeof input !== "object") {
@@ -36,7 +38,10 @@ function prepareEditArguments(input) {
             if (Array.isArray(parsed))
                 args.edits = parsed;
         }
-        catch { }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid "edits" argument for edit tool: expected an array but received a string that could not be parsed as JSON. Parse error: ${reason}`);
+        }
     }
     const legacy = args;
     if (typeof legacy.oldText !== "string" || typeof legacy.newText !== "string") {
@@ -51,6 +56,14 @@ function validateEditInput(input) {
     if (!Array.isArray(input.edits) || input.edits.length === 0) {
         throw new Error("Edit tool input is invalid. edits must contain at least one replacement.");
     }
+    for (const edit of input.edits) {
+        if (!edit ||
+            typeof edit !== "object" ||
+            typeof edit.oldText !== "string" ||
+            typeof edit.newText !== "string") {
+            throw new Error("Edit tool input is invalid. Each edit must have string oldText and newText properties.");
+        }
+    }
     return { path: input.path, edits: input.edits };
 }
 function formatEditCall(args, _theme) {
@@ -136,6 +149,8 @@ export function createEditToolDefinition(cwd, options) {
                         // Read the file.
                         const buffer = await ops.readFile(absolutePath);
                         const rawContent = buffer.toString("utf-8");
+                        // Capture a freshness token so we can detect stale reads before writing.
+                        const freshnessTokenBefore = ops.stat ? (await ops.stat(absolutePath)).mtimeMs : undefined;
                         // Check if aborted after reading.
                         if (aborted) {
                             return;
@@ -144,13 +159,24 @@ export function createEditToolDefinition(cwd, options) {
                         const { bom, text: content } = stripBom(rawContent);
                         const originalEnding = detectLineEnding(content);
                         const normalizedContent = normalizeToLF(content);
-                        const { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);
+                        const { baseContent, newContent, usedFuzzyMatch } = applyEditsToNormalizedContent(normalizedContent, edits, path);
                         // Check if aborted before writing.
                         if (aborted) {
                             return;
                         }
+                        // Detect stale file: re-check freshness token before writing.
+                        if (freshnessTokenBefore !== undefined && ops.stat) {
+                            const freshnessTokenAfter = (await ops.stat(absolutePath)).mtimeMs;
+                            if (freshnessTokenAfter !== freshnessTokenBefore) {
+                                if (signal) {
+                                    signal.removeEventListener("abort", onAbort);
+                                }
+                                reject(new Error(`File ${path} was modified since read. Re-read the file and retry your edit.`));
+                                return;
+                            }
+                        }
                         const finalContent = bom + restoreLineEndings(newContent, originalEnding);
-                        await ops.writeFile(absolutePath, finalContent);
+                        await atomicWriteFile(absolutePath, finalContent);
                         // Check if aborted after writing.
                         if (aborted) {
                             return;
@@ -165,7 +191,7 @@ export function createEditToolDefinition(cwd, options) {
                             content: [
                                 {
                                     type: "text",
-                                    text: `Successfully replaced ${edits.length} block(s) in ${path}.`,
+                                    text: `Successfully replaced ${edits.length} block(s) in ${path}.${usedFuzzyMatch ? " (used tolerant matching — verify the change)" : ""}`,
                                 },
                             ],
                             details: { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },

package/dist/sdk/coding-agent/core/tools/file-mutation-queue.d.ts

@@ -1,6 +1,12 @@
 /**
- * Serialize file mutation operations targeting the same file.
- * Operations for different files still run in parallel.
+ * Run `fn` while holding the per-file mutation lock for `filePath`.
+ *
+ * `filePath` may be a single path or an array of paths. For an array, each
+ * file gets its own per-file queue key (NOT a joined blob — a joined key would
+ * fail to serialize against single-path locks on the same file). Keys are
+ * sorted and acquired in a fixed order to avoid deadlock between two array
+ * locks that share a subset of files. The callback runs only once all locks
+ * are held and every lock is released in the `finally` block.
  */
-export declare function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+export declare function withFileMutationQueue<T>(filePath: string | string[], fn: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=file-mutation-queue.d.ts.map

package/dist/sdk/coding-agent/core/tools/file-mutation-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-mutation-queue.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/file-mutation-queue.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAoBjG"}
+{"version":3,"file":"file-mutation-queue.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/file-mutation-queue.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC5C,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CA0BZ"}

package/dist/sdk/coding-agent/core/tools/file-mutation-queue.js

@@ -1,6 +1,13 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 const fileMutationQueues = new Map();
+/**
+ * Derive a stable per-file queue key. Tries realpath first (canonicalizes
+ * symlinks and existing files); falls back to the resolved path for files that
+ * do not exist yet (e.g. Add File targets). The fallback is essential —
+ * realpathSync throws ENOENT for non-existent files, which would otherwise
+ * produce a different key before vs after creation.
+ */
 function getMutationQueueKey(filePath) {
     const resolvedPath = resolve(filePath);
     try {
@@ -11,11 +18,43 @@ function getMutationQueueKey(filePath) {
     }
 }
 /**
- * Serialize file mutation operations targeting the same file.
- * Operations for different files still run in parallel.
+ * Run `fn` while holding the per-file mutation lock for `filePath`.
+ *
+ * `filePath` may be a single path or an array of paths. For an array, each
+ * file gets its own per-file queue key (NOT a joined blob — a joined key would
+ * fail to serialize against single-path locks on the same file). Keys are
+ * sorted and acquired in a fixed order to avoid deadlock between two array
+ * locks that share a subset of files. The callback runs only once all locks
+ * are held and every lock is released in the `finally` block.
  */
 export async function withFileMutationQueue(filePath, fn) {
-    const key = getMutationQueueKey(filePath);
+    const paths = Array.isArray(filePath) ? filePath : [filePath];
+    // Empty/empty-array: no locks to acquire, just run the callback.
+    if (paths.length === 0) {
+        return fn();
+    }
+    // Dedupe and sort per-file keys. Sorting gives a stable acquisition order so
+    // two overlapping array locks cannot deadlock each other.
+    const keys = Array.from(new Set(paths.map((p) => getMutationQueueKey(p)))).sort();
+    // For a single unique key, use the original single-path fast path.
+    if (keys.length === 1) {
+        return withSingleFileMutationQueue(keys[0], fn);
+    }
+    // For multiple keys, chain each lock. Each step waits on the previous
+    // queue before acquiring the next, so the callback runs only once every
+    // per-file lock is held.
+    let chain = fn;
+    for (const key of keys) {
+        const next = chain;
+        chain = () => withSingleFileMutationQueue(key, next);
+    }
+    return chain();
+}
+/**
+ * Acquire a single per-file queue, run `fn`, then release. This is the core
+ * lock primitive shared by the single-path and array paths above.
+ */
+async function withSingleFileMutationQueue(key, fn) {
     const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve();
     let releaseNext;
     const nextQueue = new Promise((resolveQueue) => {

package/dist/sdk/coding-agent/core/tools/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAI9D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAM5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,OAAO,EAAoD,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAEtH,QAAA,MAAM,UAAU;;;;EAId,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AASD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,+CAA+C;IAC/C,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACnF;AAQD,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAkID,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CA+IhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAI9D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAM5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,OAAO,EAAoD,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAEtH,QAAA,MAAM,UAAU;;;;EAId,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AASD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,qCAAqC;IACrC,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,+CAA+C;IAC/C,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,sEAAsE;IACtE,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACnF;AAQD,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAkID,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CA8KhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}

package/dist/sdk/coding-agent/core/tools/read.js

@@ -131,6 +131,13 @@ export function createReadToolDefinition(cwd, options) {
         parameters: readSchema,
         async execute(_toolCallId, { path, offset, limit }, signal, _onUpdate, ctx) {
             const absolutePath = resolveReadPath(path, cwd);
+            // Validate offset/limit before doing any I/O. Distinguish undefined (unset) from 0.
+            if (offset !== undefined && offset <= 0) {
+                throw new Error("offset must be ≥ 1");
+            }
+            if (limit !== undefined && limit <= 0) {
+                throw new Error("limit must be ≥ 1");
+            }
             return new Promise((resolve, reject) => {
                 if (signal?.aborted) {
                     reject(new Error("Operation aborted"));
@@ -199,60 +206,85 @@ export function createReadToolDefinition(cwd, options) {
                         else {
                             // Read text content.
                             const buffer = await ops.readFile(absolutePath);
-                            const textContent = buffer.toString("utf-8");
-                            const allLines = textContent.split("\n");
-                            const totalFileLines = allLines.length;
-                            // Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.
-                            const startLine = offset ? Math.max(0, offset - 1) : 0;
-                            const startLineDisplay = startLine + 1;
-                            // Check if offset is out of bounds.
-                            if (startLine >= allLines.length) {
-                                throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+                            // Binary file detection: scan the first chunk for NUL bytes.
+                            // Legitimate UTF-8 (including emoji and CJK) never contains NUL bytes, so
+                            // a NUL byte is a strong signal that this is a non-text binary (executable,
+                            // archive, etc.). Return a note instead of decoding garbage UTF-8.
+                            const binaryScanLen = Math.min(buffer.length, 8192);
+                            let isBinary = false;
+                            for (let i = 0; i < binaryScanLen; i++) {
+                                if (buffer[i] === 0x00) {
+                                    isBinary = true;
+                                    break;
+                                }
                             }
-                            let selectedContent;
-                            let userLimitedLines;
-                            // If limit is specified by the user, honor it first. Otherwise truncateHead decides.
-                            if (limit !== undefined) {
-                                const endLine = Math.min(startLine + limit, allLines.length);
-                                selectedContent = allLines.slice(startLine, endLine).join("\n");
-                                userLimitedLines = endLine - startLine;
+                            if (isBinary) {
+                                content = [
+                                    { type: "text", text: `[Binary file, ${formatSize(buffer.length)}, not displayed]` },
+                                ];
                             }
                             else {
-                                selectedContent = allLines.slice(startLine).join("\n");
-                            }
-                            // Apply truncation, respecting both line and byte limits.
-                            const truncation = truncateHead(selectedContent);
-                            let outputText;
-                            if (truncation.firstLineExceedsLimit) {
-                                // First line alone exceeds the byte limit. Point the model at a bash fallback.
-                                const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
-                                outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
-                                details = { truncation };
-                            }
-                            else if (truncation.truncated) {
-                                // Truncation occurred. Build an actionable continuation notice.
-                                const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
-                                const nextOffset = endLineDisplay + 1;
-                                outputText = truncation.content;
-                                if (truncation.truncatedBy === "lines") {
-                                    outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
+                                const textContent = buffer.toString("utf-8");
+                                let allLines = textContent.split("\n");
+                                // A trailing newline produces an extra empty element on split; drop it so the
+                                // reported line count and all offset/limit math match the real content.
+                                const totalFileLines = textContent.endsWith("\n") ? allLines.length - 1 : allLines.length;
+                                if (textContent.endsWith("\n")) {
+                                    allLines = allLines.slice(0, -1);
+                                }
+                                // Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.
+                                // Use explicit undefined check so offset=0 is rejected above rather than treated as "no offset".
+                                const startLine = offset !== undefined ? Math.max(0, offset - 1) : 0;
+                                const startLineDisplay = startLine + 1;
+                                // Check if offset is out of bounds.
+                                if (startLine >= allLines.length) {
+                                    throw new Error(`Offset ${offset} is beyond end of file (${totalFileLines} lines total)`);
+                                }
+                                let selectedContent;
+                                let userLimitedLines;
+                                // If limit is specified by the user, honor it first. Otherwise truncateHead decides.
+                                if (limit !== undefined) {
+                                    const endLine = Math.min(startLine + limit, allLines.length);
+                                    selectedContent = allLines.slice(startLine, endLine).join("\n");
+                                    userLimitedLines = endLine - startLine;
                                 }
                                 else {
-                                    outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+                                    selectedContent = allLines.slice(startLine).join("\n");
                                 }
-                                details = { truncation };
-                            }
-                            else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
-                                // User-specified limit stopped early, but the file still has more content.
-                                const remaining = allLines.length - (startLine + userLimitedLines);
-                                const nextOffset = startLine + userLimitedLines + 1;
-                                outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
-                            }
-                            else {
-                                // No truncation and no remaining user-limited content.
-                                outputText = truncation.content;
+                                // Apply truncation, respecting both line and byte limits.
+                                const truncation = truncateHead(selectedContent);
+                                let outputText;
+                                if (truncation.firstLineExceedsLimit) {
+                                    // First line alone exceeds the byte limit. Point the model at a bash fallback.
+                                    const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
+                                    outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
+                                    details = { truncation };
+                                }
+                                else if (truncation.truncated) {
+                                    // Truncation occurred. Build an actionable continuation notice.
+                                    const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+                                    const nextOffset = endLineDisplay + 1;
+                                    outputText = truncation.content;
+                                    if (truncation.truncatedBy === "lines") {
+                                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
+                                    }
+                                    else {
+                                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+                                    }
+                                    details = { truncation };
+                                }
+                                else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
+                                    // User-specified limit stopped early, but the file still has more content.
+                                    const remaining = allLines.length - (startLine + userLimitedLines);
+                                    const nextOffset = startLine + userLimitedLines + 1;
+                                    outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+                                }
+                                else {
+                                    // No truncation and no remaining user-limited content.
+                                    outputText = truncation.content;
+                                }
+                                content = [{ type: "text", text: outputText }];
                             }
-                            content = [{ type: "text", text: outputText }];
                         }
                         if (aborted)
                             return;

package/dist/sdk/coding-agent/core/tools/truncate.d.ts

@@ -48,8 +48,10 @@ export declare function formatSize(bytes: number): string;
  * Truncate content from the head (keep first N lines/bytes).
  * Suitable for file reads where you want to see the beginning.
  *
- * Never returns partial lines. If first line exceeds byte limit,
- * returns empty content with firstLineExceedsLimit=true.
+ * If a single line exceeds the byte limit, that line is byte-capped
+ * (keeping a valid UTF-8 boundary) rather than aborting the whole read;
+ * subsequent lines are still scanned. firstLineExceedsLimit is set true only
+ * when the oversized line is the first requested line.
  */
 export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
 /**

package/dist/sdk/coding-agent/core/tools/truncate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAC3C,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAChC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IACtC,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,eAAe,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAkF/F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAyE/F;AAuBD;;;GAGG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAA6B,GACrC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAKzC"}
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAC3C,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAChC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IACtC,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,eAAe,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAkF/F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAyE/F;AA2CD;;;GAGG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAA6B,GACrC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAKzC"}

package/dist/sdk/coding-agent/core/tools/truncate.js

@@ -38,8 +38,10 @@ export function formatSize(bytes) {
  * Truncate content from the head (keep first N lines/bytes).
  * Suitable for file reads where you want to see the beginning.
  *
- * Never returns partial lines. If first line exceeds byte limit,
- * returns empty content with firstLineExceedsLimit=true.
+ * If a single line exceeds the byte limit, that line is byte-capped
+ * (keeping a valid UTF-8 boundary) rather than aborting the whole read;
+ * subsequent lines are still scanned. firstLineExceedsLimit is set true only
+ * when the oversized line is the first requested line.
  */
 export function truncateHead(content, options = {}) {
     const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
@@ -63,30 +65,31 @@ export function truncateHead(content, options = {}) {
             maxBytes,
         };
     }
-    // Check if first line alone exceeds byte limit
-    const firstLineBytes = Buffer.byteLength(lines[0], "utf-8");
-    if (firstLineBytes > maxBytes) {
-        return {
-            content: "",
-            truncated: true,
-            truncatedBy: "bytes",
-            totalLines,
-            totalBytes,
-            outputLines: 0,
-            outputBytes: 0,
-            lastLinePartial: false,
-            firstLineExceedsLimit: true,
-            maxLines,
-            maxBytes,
-        };
-    }
-    // Collect complete lines that fit
+    // Scan lines, byte-capping any single oversized line instead of aborting.
+    // firstLineExceedsLimit is surfaced only when the very first requested line
+    // is the oversized one, so callers that render a per-line hint (e.g. read)
+    // keep doing so without losing the rest of the content.
     const outputLinesArr = [];
     let outputBytesCount = 0;
     let truncatedBy = "lines";
+    let firstLineExceedsLimit = false;
+    let lastLinePartial = false;
     for (let i = 0; i < lines.length && i < maxLines; i++) {
         const line = lines[i];
-        const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+        const newlineCost = i > 0 ? 1 : 0; // +1 for joining newline
+        let lineBytes = Buffer.byteLength(line, "utf-8");
+        // A single line larger than the whole byte budget: cap it in place.
+        if (lineBytes > maxBytes) {
+            if (i === 0)
+                firstLineExceedsLimit = true;
+            const capped = truncateStringToBytesFromStart(line, maxBytes);
+            outputLinesArr.push(capped);
+            outputBytesCount = maxBytes;
+            lastLinePartial = true;
+            truncatedBy = "bytes";
+            break;
+        }
+        lineBytes += newlineCost;
         if (outputBytesCount + lineBytes > maxBytes) {
             truncatedBy = "bytes";
             break;
@@ -108,8 +111,8 @@ export function truncateHead(content, options = {}) {
         totalBytes,
         outputLines: outputLinesArr.length,
         outputBytes: finalOutputBytes,
-        lastLinePartial: false,
-        firstLineExceedsLimit: false,
+        lastLinePartial,
+        firstLineExceedsLimit,
         maxLines,
         maxBytes,
     };
@@ -202,6 +205,23 @@ function truncateStringToBytesFromEnd(str, maxBytes) {
     }
     return buf.slice(start).toString("utf-8");
 }
+/**
+ * Truncate a string to fit within a byte limit (from the start).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+function truncateStringToBytesFromStart(str, maxBytes) {
+    const buf = Buffer.from(str, "utf-8");
+    if (buf.length <= maxBytes) {
+        return str;
+    }
+    let end = maxBytes;
+    // Walk back to a valid UTF-8 character boundary so we don't slice
+    // through the middle of a multi-byte sequence.
+    while (end > 0 && (buf[end] & 0xc0) === 0x80) {
+        end--;
+    }
+    return buf.slice(0, end).toString("utf-8");
+}
 /**
  * Truncate a single line to max characters, adding [truncated] suffix.
  * Used for grep match lines.