@aexol/spectral 0.9.126 → 0.9.128

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.

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

@@ -6,18 +6,15 @@ declare const writeSchema: Type.TObject<{
     content: Type.TString;
 }>;
 export type WriteToolInput = Static<typeof writeSchema>;
-/**
- * Pluggable operations for the write tool.
- * Override these to delegate file writing to remote systems (for example SSH).
- */
 export interface WriteOperations {
-    /** Write content to a file */
-    writeFile: (absolutePath: string, content: string) => Promise<void>;
-    /** Create directory recursively */
+    /**
+     * Optional atomic write override (temp file + rename). When omitted,
+     * the default {@link atomicWriteFile} helper is used.
+     */
+    atomicWrite?: (absolutePath: string, content: string) => Promise<void>;
     mkdir: (dir: string) => Promise<void>;
 }
 export interface WriteToolOptions {
-    /** Custom operations for file writing. Default: local filesystem */
     operations?: WriteOperations;
 }
 export declare function createWriteToolDefinition(cwd: string, options?: WriteToolOptions): ToolDefinition<typeof writeSchema, undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/write.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;AAM7D,QAAA,MAAM,WAAW;;;EAGf,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,8BAA8B;IAC9B,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,mCAAmC;IACnC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAOD,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,UAAU,CAAC,EAAE,eAAe,CAAC;CAC7B;AA2DD,wBAAgB,yBAAyB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,GACxB,cAAc,CAAC,OAAO,WAAW,EAAE,SAAS,CAAC,CA2D/C;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEtG"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/write.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;AAe7D,QAAA,MAAM,WAAW;;;EAKf,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACxD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAID,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AA6DD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,GACzB,cAAc,CAAC,OAAO,WAAW,EAAE,SAAS,CAAC,CA+E/C;AACD,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,GACzB,SAAS,CAAC,OAAO,WAAW,CAAC,CAE/B"}

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

@@ -1,17 +1,19 @@
-import { mkdir as fsMkdir, writeFile as fsWriteFile } from "fs/promises";
+import { mkdir as fsMkdir } from "fs/promises";
 import { dirname } from "path";
 import { Type } from "typebox";
 import { getLanguageFromPath, highlightCode } from "../theme.js";
+import { atomicWriteFile, defaultAtomicWriteOperations, } from "./atomic-write.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { resolveToCwd } from "./path-utils.js";
-import { normalizeDisplayText, replaceTabs, shortenPath, str } from "./render-utils.js";
+import { normalizeDisplayText, replaceTabs, shortenPath, str, } from "./render-utils.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
 const writeSchema = Type.Object({
-    path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+    path: Type.String({
+        description: "Path to the file to write (relative or absolute)",
+    }),
     content: Type.String({ description: "Content to write to the file" }),
 });
 const defaultWriteOperations = {
-    writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
     mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => { }),
 };
 function trimTrailingEmptyLines(lines) {
@@ -62,6 +64,7 @@ function formatWriteResult(result, _theme) {
 }
 export function createWriteToolDefinition(cwd, options) {
     const ops = options?.operations ?? defaultWriteOperations;
+    const atomicOps = defaultAtomicWriteOperations;
     return {
         name: "write",
         label: "write",
@@ -73,30 +76,45 @@ export function createWriteToolDefinition(cwd, options) {
             const absolutePath = resolveToCwd(path, cwd);
             const dir = dirname(absolutePath);
             return withFileMutationQueue(absolutePath, () => new Promise((resolve, reject) => {
+                // Abort BEFORE the write begins -> reject immediately.
                 if (signal?.aborted) {
                     reject(new Error("Operation aborted"));
                     return;
                 }
                 let aborted = false;
+                let writeStarted = false;
                 const onAbort = () => {
                     aborted = true;
-                    reject(new Error("Operation aborted"));
+                    // W2: only reject when aborted BEFORE the write begins. An abort
+                    // that fires during/after the write must not swallow the
+                    // successful resolve once the write completes.
+                    if (!writeStarted) {
+                        reject(new Error("Operation aborted"));
+                    }
                 };
                 signal?.addEventListener("abort", onAbort, { once: true });
                 (async () => {
                     try {
-                        // Create parent directories if needed.
                         await ops.mkdir(dir);
+                        // Reject if aborted before the write begins.
                         if (aborted)
                             return;
-                        // Write the file contents.
-                        await ops.writeFile(absolutePath, content);
-                        if (aborted)
-                            return;
+                        writeStarted = true;
+                        // W1 + W5: atomic write (temp + rename). On failure the
+                        // temp is cleaned up and the target is left untouched.
+                        const writeFn = ops.atomicWrite ??
+                            ((p, c) => atomicWriteFile(p, c, "utf-8", atomicOps));
+                        await writeFn(absolutePath, content);
+                        // W2: once the write has completed successfully, resolve
+                        // with the success content even if the abort signal
+                        // fired mid-write. Do NOT swallow the resolve.
                         signal?.removeEventListener("abort", onAbort);
                         resolve({
                             content: [
-                                { type: "text", text: `Successfully wrote ${content.length} bytes to ${path}` },
+                                {
+                                    type: "text",
+                                    text: `Successfully wrote ${Buffer.byteLength(content, "utf-8")} bytes to ${path}`,
+                                },
                             ],
                             details: undefined,
                         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.126",
+  "version": "0.9.128",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,