@sema-agent/core 2.1.0 → 2.3.0

package/dist/stores/file/workflow-journal-store.js

@@ -1,12 +1,15 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { callKeyOrdinal } from "../../core/workflow-journal-store.js";
 import { AppendLog } from "./fs-atomic.js";
-import { canonicalStoreKey, sanitizePathComponent } from "./fs-atomic.js";
+import { canonicalStoreKey, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
 import { oversizeJournalResult } from "../../core/workflow-journal-store.js";
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
 export const RESUME_CLAIM_TTL_MS = 60 * 60 * 1000;
+export const RESUME_CLAIM_RELEASE_GRACE_MS = 5_000;
+export const RESUME_CLAIM_SWEEP_INTERVAL_MS = 60_000;
+export const RESUME_CLAIM_REAP_GRACE_MS = 5 * 60_000;
 const sharedJournalDirs = new Map();
 const MAX_OPEN_JOURNAL_LOGS = 64;
 export class FileWorkflowJournalStore {
@@ -16,6 +19,7 @@ export class FileWorkflowJournalStore {
     shared;
     sharedKey;
     closed = false;
+    lastClaimSweepAt = 0;
     get logs() {
         return this.shared.logs;
     }
@@ -122,20 +126,63 @@ export class FileWorkflowJournalStore {
         const scopeTag = createHash("sha256").update(scope).digest("hex").slice(0, 16);
         return join(this.claimsDir, `${sanitizePathComponent(sourceRunId)}.${scopeTag}.json`);
     }
-    readClaim(path) {
-        if (!existsSync(path))
+    readClaimRaw(path) {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch {
             return undefined;
+        }
         try {
-            const rec = JSON.parse(readFileSync(path, "utf8"));
+            const rec = JSON.parse(raw);
             if (typeof rec.holder !== "string" || typeof rec.expiresAt !== "number" || !Number.isFinite(rec.expiresAt)) {
                 return undefined;
             }
-            return rec;
+            return { raw, rec };
         }
         catch {
             return undefined;
         }
     }
+    unlinkIfUnchanged(path, expectedRaw) {
+        try {
+            if (expectedRaw !== undefined && readFileSync(path, "utf8") !== expectedRaw)
+                return;
+            unlinkSync(path);
+        }
+        catch {
+        }
+    }
+    sweepExpiredClaims() {
+        const now = Date.now();
+        if (now - this.lastClaimSweepAt < RESUME_CLAIM_SWEEP_INTERVAL_MS)
+            return;
+        this.lastClaimSweepAt = now;
+        let names;
+        try {
+            names = readdirSync(this.claimsDir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const path = join(this.claimsDir, name);
+            try {
+                const existing = this.readClaimRaw(path);
+                if (existing === undefined) {
+                    if (now - statSync(path).mtimeMs > RESUME_CLAIM_TTL_MS)
+                        unlinkSync(path);
+                    continue;
+                }
+                if (existing.rec.expiresAt + RESUME_CLAIM_REAP_GRACE_MS > now)
+                    continue;
+                this.unlinkIfUnchanged(path, existing.raw);
+            }
+            catch {
+            }
+        }
+    }
     async resumeClaim(input) {
         const { sourceRunId, newRunId, scope } = input;
         let path;
@@ -146,40 +193,32 @@ export class FileWorkflowJournalStore {
             return { granted: true };
         }
         mkdirSync(this.claimsDir, { recursive: true, mode: 0o700 });
+        this.sweepExpiredClaims();
+        const record = { sourceRunId, holder: newRunId, expiresAt: Date.now() + RESUME_CLAIM_TTL_MS };
+        const payload = JSON.stringify(record);
         for (let attempt = 0; attempt < 2; attempt++) {
-            const record = { sourceRunId, holder: newRunId, expiresAt: Date.now() + RESUME_CLAIM_TTL_MS };
             try {
-                const fd = openSync(path, "wx", 0o600);
-                try {
-                    writeSync(fd, JSON.stringify(record));
-                }
-                finally {
-                    closeSync(fd);
-                }
+                writeThenLink(path, payload);
                 return { granted: true };
             }
             catch (err) {
                 if (err.code !== "EEXIST")
                     throw err;
             }
-            const existing = this.readClaim(path);
-            if (existing !== undefined && existing.holder === newRunId) {
+            const existing = this.readClaimRaw(path);
+            if (existing !== undefined && existing.rec.holder === newRunId) {
                 return { granted: true };
             }
-            if (existing === undefined || existing.expiresAt <= Date.now()) {
-                try {
-                    unlinkSync(path);
-                }
-                catch {
-                }
+            if (existing === undefined || existing.rec.expiresAt <= Date.now()) {
+                this.unlinkIfUnchanged(path, existing?.raw);
                 continue;
             }
-            return { granted: false, holder: existing.holder };
+            return { granted: false, holder: existing.rec.holder };
         }
-        const winner = this.readClaim(path);
-        if (winner === undefined || winner.holder === newRunId)
+        const winner = this.readClaimRaw(path);
+        if (winner !== undefined && winner.rec.holder === newRunId)
             return { granted: true };
-        return { granted: false, holder: winner.holder };
+        return { granted: false, holder: winner?.rec.holder };
     }
     async releaseResumeClaim(input) {
         let path;
@@ -189,14 +228,12 @@ export class FileWorkflowJournalStore {
         catch {
             return;
         }
-        const existing = this.readClaim(path);
-        if (existing === undefined || existing.holder !== input.newRunId)
+        const existing = this.readClaimRaw(path);
+        if (existing === undefined || existing.rec.holder !== input.newRunId)
             return;
-        try {
-            unlinkSync(path);
-        }
-        catch {
-        }
+        if (existing.rec.expiresAt - Date.now() <= RESUME_CLAIM_RELEASE_GRACE_MS)
+            return;
+        this.unlinkIfUnchanged(path, existing.raw);
     }
     async deleteByRun(runId) {
         const log = this.logs.get(runId);

package/dist/tools/fs/bash-readonly-classifier.js

@@ -31,6 +31,24 @@ export function coarseReadonlyCheck(command, allow) {
     return undefined;
 }
 const SHELL_SEGMENT_HARD_REJECT = /[<>$()`\n\r\\]/;
+function foldQuoteRemovalToken(tok) {
+    if (!tok.includes('"') && !tok.includes("'"))
+        return tok;
+    let out = "";
+    let open;
+    for (const ch of tok) {
+        if (open === undefined && (ch === '"' || ch === "'")) {
+            open = ch;
+            continue;
+        }
+        if (open === ch) {
+            open = undefined;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
 export function classifyCompoundReadonly(command, allow) {
     const trimmed = command.trim();
     if (!trimmed)
@@ -111,7 +129,8 @@ export function classifyCompoundReadonly(command, allow) {
     };
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity };
     for (let si = 0; si < segments.length; si++) {
-        const toks = segments[si].trim().split(/\s+/).filter((t) => t.length > 0);
+        const toks = segments[si].trim().split(/\s+/).filter((t) => t.length > 0)
+            .map(foldQuoteRemovalToken);
         if (toks.length === 0)
             continue;
         const name = toks[0];

package/dist/tools/fs/fs-bash.d.ts

@@ -25,6 +25,7 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     execClamp?: ExecClampOption;
     autoBackgroundOnTimeout?: boolean;
+    oneShot?: boolean;
 }): AgentTool;
 export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption): AgentTool;
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;

package/dist/tools/fs/fs-bash.js

@@ -461,6 +461,11 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                     const interimNote = outputFile !== undefined
                         ? ` Output file: ${outputFile} (full output is appended there — Read it any time).`
                         : ` Use TaskOutput("${taskId}") to check interim output.`;
+                    if (taskOpts.oneShot === true && onNotify !== undefined) {
+                        return (`Command running in background; task_id=${taskId}.${interimNote} This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput("${taskId}", { block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget. TaskStop("${taskId}") to stop.` +
+                            budgetNote +
+                            lifetimeNote);
+                    }
                     return onNotify !== undefined
                         ? `Command running in background; task_id=${taskId}.${interimNote} You will be notified when it completes — do not poll; ` +
                             `end your turn if nothing else is pending. TaskStop("${taskId}") to stop.` +
@@ -554,9 +559,11 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                                     ? `Output file: ${outputFile} (full output is appended there — Read it any time). `
                                     : `Use TaskOutput("${taskId}") to read its output. `) +
                                 `TaskStop("${taskId}") to stop it. ` +
-                                (onNotify !== undefined
-                                    ? `You will be notified when it completes — do not poll.`
-                                    : `Poll TaskOutput until its status is no longer "running".`) +
+                                (taskOpts.oneShot === true && onNotify !== undefined
+                                    ? `This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput("${taskId}", { block: true }).`
+                                    : onNotify !== undefined
+                                        ? `You will be notified when it completes — do not poll.`
+                                        : `Poll TaskOutput until its status is no longer "running".`) +
                                 adoptBudgetNote +
                                 (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
                             details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}), ...(cause === "timeout" ? { autoBackgrounded: true } : {}) },

package/dist/tools/fs/fs-read.js

@@ -15,10 +15,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "\n" +
             "- `file_path` may be relative (resolved against the tracked working directory) or absolute (within the configured roots).\n" +
             "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call.\n" +
-            "- When you already know which part of the file you need, only read that part. This can be important for larger files.\n" +
+            "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n" +
             "- Results are returned using cat -n format, with line numbers starting at 1\n" +
             "- Reads images (PNG, JPG, …) and presents them visually. Reads PDFs via the `pages` parameter (e.g. \"1-5\", max 20 pages/request; a PDF whose detected page count exceeds 10 requires `pages`). Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
-            "- Reading a directory, a missing file, or an empty file returns an error or warning rather than content.\n" +
+            "- Reading a directory, a missing file, or an empty file returns an error or system reminder rather than content.\n" +
             "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
             "- You must read a file before editing it.\n" +
             "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
@@ -26,7 +26,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "\n" +
             "Usage:\n" +
             "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call\n" +
-            "- When you already know which part of the file you need, only read that part. This can be important for larger files.\n" +
+            "- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters\n" +
             "- Results are returned using cat -n format, with each line prefixed by its line number and a tab\n" +
             "- This tool allows the model to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually.\n" +
             "- This tool can only read files, not directories. To read a directory, use Glob/Grep or an ls command via the Bash tool.\n" +
@@ -34,7 +34,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "- Reads PDFs (.pdf): the document is provided to the model directly (text layer included). Use the `pages` parameter (e.g., \"1-5\") to read a page range; a PDF whose detected page count exceeds 10 requires `pages`. Maximum 20 pages per request.\n" +
             "- Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
             "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
-            "- If you read a file that exists but has empty contents you will receive a warning in place of file contents.\n" +
+            "- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.\n" +
             "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
         parameters: Type.Object({
             ...FILE_PATH_PARAMS,
@@ -129,7 +129,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                         `(${info.value.size} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
                         `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
                 }
-                if (!isNb && info.value.size > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+                if (!isNb && info.value.size > MAX_READ_BYTES && limit === undefined) {
                     return errorResult(`Error (Read): "${path}" is too large to read in full (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
                 }
             }
@@ -147,7 +147,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                     `(${readSize} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
                     `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
             }
-            if (!isNb && readSize > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+            if (!isNb && readSize > MAX_READ_BYTES && limit === undefined) {
                 return errorResult(`Error (Read): "${path}" is too large to read in full (${readSize} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
             }
             if (pdfMagicMatches(readBin.value)) {
@@ -158,7 +158,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                 return errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`);
             }
             const content = decoded.text;
-            if (isBinaryContent(content.slice(0, 4096))) {
+            if (isBinaryContent(content.slice(0, 8192))) {
                 return errorResult(`Error (Read): "${path}" appears to be a binary file (non-text content); this tool reads UTF-8 and BOM-marked UTF-16LE text only. ` +
                     `If it is UTF-16 without a BOM or a legacy encoding, convert it first (e.g. \`iconv -f UTF-16LE -t UTF-8\`) or inspect/transform it with bash.`);
             }
@@ -193,10 +193,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                             `  cat "${path}" | jq '.cells[] | select(.cell_type=="code") | .source' # All code sources`);
                     }
                     const prevNb = state.get(r.key);
-                    if (prevNb?.seededFromContext && prevNb.hash === hash) {
+                    if (prevNb?.seededFromContext && !prevNb.isPartialView && prevNb.hash === hash) {
                         return seededFileUnchangedReminder(r.key);
                     }
-                    if (prevNb && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
+                    if (prevNb && !prevNb.isPartialView && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
                         return `[${path}: unchanged since you last read it (lines 1-${total} of ${total}); content omitted to save context]`;
                     }
                     state.set(r.key, { hash, totalLines: countLines(content), truncated: false, view: { start: 1, end: total }, lastReadAt: Date.now() });
@@ -265,7 +265,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                 lastReadAt: Date.now(),
             });
             if (total === 0)
-                return `<system-reminder>Warning: the file exists but is shorter than the provided offset (${start}). The file has 1 lines.</system-reminder>`;
+                return `<system-reminder>Warning: the file exists but the contents are empty.</system-reminder>`;
             const header = pageMarker ?? (truncated ? `[${path}: lines ${start}-${end} of ${total}${end < total ? " — use offset to see more" : ""}]\n` : "");
             return {
                 content: `${nbFallbackPrefix}${header}${body}${READ_CYBER_REMINDER}`,

package/dist/tools/fs/fs-search-tools.js

@@ -1,21 +1,22 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText } from "./safety.js";
-import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern } from "./search.js";
+import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern, invalidGlobTokens } from "./search.js";
 export function createGrepTool(env, rootCanonical, additionalRoots) {
     return defineTool({
         name: "Grep",
         contract: { contractId: "core.grep@1", implementationRevision: "1" },
         description: "Content search built on ripgrep. Prefer this over `grep`/`rg` via Bash — results integrate with the permission UI and file links.\n" +
+            "\n" +
             '- Full regex syntax (e.g. "log.*Error", "function\\s+\\w+"). Ripgrep, not grep — escape literal braces (`interface\\{\\}`).\n' +
             '- Filter with `glob` (e.g. "**/*.tsx") or `type` (e.g. "js", "py", "rust").\n' +
             '- `output_mode`: "content" (matching lines), "files_with_matches" (paths only, default), or "count".\n' +
             "- `multiline: true` for patterns that span lines.\n" +
             "- Uses ripgrep when available (respects .gitignore, skips binary files and VCS directories), otherwise a JS fallback that skips node_modules/build/… and parses .gitignore. Hidden files/directories ARE searched.\n" +
-            "- Use Agent tool for open-ended searches requiring multiple rounds",
+            "- Use Agent tool (if available) for open-ended searches requiring multiple rounds",
         parameters: Type.Object({
             pattern: Type.String({ description: "The regular expression pattern to search for in file contents" }),
-            path: Type.Optional(Type.String({ description: "Restrict to a sub-directory (relative to root)." })),
+            path: Type.Optional(Type.String({ description: "File or directory to search in (rg PATH). Relative paths resolve against the root; defaults to the whole root." })),
             glob: Type.Optional(Type.String({ description: 'Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}")' })),
             type: Type.Optional(Type.String({ description: 'File type to search (rg --type): "js", "py", "rust", "go", "java", etc. More efficient than glob for standard file types.' })),
             output_mode: Type.Optional(Type.Union([Type.Literal("content"), Type.Literal("files_with_matches"), Type.Literal("count")], {
@@ -41,6 +42,23 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
         effect: "read",
         execute: async (args, ctx) => {
             const a = args;
+            for (const [name, value] of [
+                ["head_limit", a.head_limit],
+                ["offset", a.offset],
+            ]) {
+                if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+                    return errorResult(`Error (Grep): ${name} must be a whole number of 0 or more, got ${value}.${name === "head_limit" ? " Pass 0 for unlimited." : ""}`);
+                }
+            }
+            if (typeof a.glob === "string" && a.glob.length > 0) {
+                const badGlobs = invalidGlobTokens(a.glob);
+                if (badGlobs.length > 0) {
+                    return errorResult(`Error (Grep): rejected the glob ${badGlobs.map((g) => JSON.stringify(g)).join(", ")} without searching — ` +
+                        `an unterminated \`[\` class or \`{\` group cannot be compiled as a glob, and matching it literally would ` +
+                        `silently narrow the search to a file with that exact name (an empty result would NOT mean "no matches"). ` +
+                        `Close the bracket/brace, or drop \`glob\` and filter with \`path\`/\`type\` instead.`);
+                }
+            }
             let scoped = a.path;
             if (a.path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, a.path, ctx.signal, rootCanonical, additionalRoots);
@@ -77,9 +95,14 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
                 const m = /^(.*?):(\d+):/.exec(l);
                 return m ? m[1] : l;
             };
+            const capMarker = /^…\[capped at (\d+) of (\d+)\]$/m.exec(text);
+            const cappedAt = capMarker ? Number(capMarker[1]) : undefined;
+            const capTotal = capMarker ? Number(capMarker[2]) : undefined;
+            const appliedOffset = typeof a.offset === "number" && a.offset > 0 ? { appliedOffset: a.offset } : {};
+            const appliedLimit = cappedAt !== undefined ? { appliedLimit: cappedAt } : {};
             let detailFields;
             if (mode === "files_with_matches") {
-                detailFields = { filenames: rows, numFiles: rows.length };
+                detailFields = { filenames: rows, numFiles: rows.length, totalFiles: capTotal ?? rows.length, ...appliedLimit, ...appliedOffset };
             }
             else if (mode === "count") {
                 const filenames = [...new Set(rows.map((l) => (l.includes(":") ? l.slice(0, l.lastIndexOf(":")) : l)))];
@@ -92,7 +115,14 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
                     else
                         malformed = true;
                 }
-                detailFields = { filenames, numFiles: filenames.length, ...(malformed ? {} : { numMatches }) };
+                detailFields = {
+                    filenames,
+                    numFiles: filenames.length,
+                    content: rows.join("\n"),
+                    ...(malformed ? {} : { numMatches }),
+                    ...appliedLimit,
+                    ...appliedOffset,
+                };
             }
             else {
                 const filenames = [...new Set(rows.map(contentPathOf))];
@@ -103,6 +133,9 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
                     numFiles: filenames.length,
                     content: joined.length > GREP_CONTENT_PREVIEW_CHARS ? `${joined.slice(0, GREP_CONTENT_PREVIEW_CHARS)}\n…[truncated — full text in the tool output]` : joined,
                     numLines: rows.length,
+                    totalLines: capTotal ?? rows.length,
+                    ...appliedLimit,
+                    ...appliedOffset,
                 };
             }
             return {
@@ -126,10 +159,12 @@ export function createGlobTool(env, rootCanonical, additionalRoots) {
             "- On environments that do not report modification times, results fall back to alphabetical order\n" +
             "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped unless your pattern names them explicitly (e.g. `dist/**`)\n" +
             "- Use this tool when you need to find files by name patterns; use `path` to scope to a sub-directory\n" +
-            "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead",
+            "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead (if available)",
         parameters: Type.Object({
             pattern: Type.String({ description: "Glob pattern (`*`, `**`, `?`)." }),
-            path: Type.Optional(Type.String({ description: "Scope the search to this sub-directory (relative to root)." })),
+            path: Type.Optional(Type.String({
+                description: 'Scope the search to this sub-directory (relative to root). IMPORTANT: Omit this field to search the whole root. DO NOT enter "undefined" or "null" - simply omit it for the default behavior. Must be a valid directory path if provided.',
+            })),
             max_results: Type.Optional(Type.Number({ description: "Cap results (default 500)." })),
         }),
         effect: "read",

package/dist/tools/fs/fs-write.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
+import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, formatByteSize, decodeEditBytes, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
 async function gateToolWrite(hook, tool, path, key, content) {
@@ -54,12 +54,12 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return errorResult(`Error (Edit): file_path is required.`);
-            const ipynb = ipynbRedirect("Edit", path);
-            if (ipynb)
-                return errorResult(ipynb);
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
                 return errorResult(violationText("Edit", r.violation));
+            if (!batch && a.old_string === a.new_string) {
+                return errorResult(violationText("Edit", { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." }));
+            }
             const singleOld = batch ? undefined : a.old_string;
             const exists = await env.exists(r.key, ctx.signal);
             if (!exists.ok)
@@ -132,6 +132,9 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                     details: { type: "edit", filePath: path, originalFile: preDec.text, oldString: "", newString: newContent, replaceAll: false, edits: [{ oldString: "", newString: newContent, replaceAll: false }] },
                 };
             }
+            const ipynb = ipynbRedirect("Edit", path);
+            if (ipynb)
+                return errorResult(ipynb);
             const notRead = requireRead(state, r.key);
             if (notRead)
                 return errorResult(await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal));
@@ -170,9 +173,18 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                         oldS = resolved;
                     }
                 }
+                if (oldS !== "" && !working.includes(oldS)) {
+                    const resolvedEsc = resolveEscapeMatch(working, oldS);
+                    if (resolvedEsc !== undefined && resolvedEsc !== oldS) {
+                        newS = adaptNewStringEscapes(oldS, resolvedEsc, newS);
+                        oldS = resolvedEsc;
+                    }
+                }
                 const match = checkEditMatch(working, oldS, e.replace_all === true, entry.truncated);
-                if (match)
-                    return errorResult(batch ? `Error (Edit): ${where}${match.message} (no changes written — the batch is atomic).` : violationText("Edit", match));
+                if (match) {
+                    const escNote = match.code === "ambiguous_edit" && escapeMatchWasAttempted(e.old_string) && !working.includes(oldS) ? ESCAPE_MATCH_MISS_NOTE : "";
+                    return errorResult(batch ? `Error (Edit): ${where}${match.message}${escNote} (no changes written — the batch is atomic).` : `${violationText("Edit", match)}${escNote}`);
+                }
                 replacements += e.replace_all === true ? countOccurrences(working, oldS) : 1;
                 const effOld = e.replace_all === true ? oldS : deletionOldString(working, oldS, newS);
                 working = e.replace_all === true ? working.split(effOld).join(newS) : working.replace(effOld, () => newS);

package/dist/tools/fs/index.d.ts

@@ -29,6 +29,7 @@ export interface HandsToolkitOptions {
     }) => void;
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     execClamp?: ExecClampOption;
+    oneShot?: boolean;
     autoBackgroundOnTimeout?: boolean;
     readImageDownsampler?: ReadImageDownsamplerOption;
     pdfModelCapabilities?: PdfModelCapabilities;

package/dist/tools/fs/index.js

@@ -45,11 +45,12 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 detachHub: opts.detachHub,
                 execClamp: opts.execClamp,
                 ...(opts.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: opts.autoBackgroundOnTimeout } : {}),
+                ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
             }));
         if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
             const sessionAxis = opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {};
             tools.push(opts.taskRegistry
-                ? createTaskOutputTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis })
+                ? createTaskOutputTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis, ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}) })
                 : createEnvTaskOutputTool(env), opts.taskRegistry
                 ? createTaskStopTool({ registry: opts.taskRegistry, owner: opts.taskOwner, scope: opts.taskScope, ...sessionAxis })
                 : createEnvTaskStopTool(env));

package/dist/tools/fs/safety.d.ts

@@ -53,6 +53,10 @@ export declare function countOccurrences(haystack: string, needle: string): numb
 export declare function similarNameSuggestion(siblingNames: readonly string[], missingName: string): string | undefined;
 export declare function normalizeQuotes(s: string): string;
 export declare function resolveQuoteMatch(content: string, oldString: string): string | undefined;
+export declare function resolveEscapeMatch(content: string, oldString: string): string | undefined;
+export declare function adaptNewStringEscapes(oldString: string, matchedOld: string, newString: string): string;
+export declare function escapeMatchWasAttempted(oldString: string): boolean;
+export declare const ESCAPE_MATCH_MISS_NOTE = "\n(note: Edit also tried swapping \\uXXXX escapes and their characters; neither form matched, so the mismatch is likely elsewhere in old_string. Re-read the file and copy the exact surrounding text.)";
 export declare function adaptNewStringQuotes(matchedOld: string, newString: string): string;
 export declare function deletionOldString(content: string, oldString: string, newString: string): string;
 export declare function checkEditMatch(content: string, oldString: string, replaceAll: boolean, truncated: boolean): FsViolation | undefined;