@sema-agent/core 2.1.0 → 2.2.0

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;

package/dist/tools/fs/safety.js

@@ -41,7 +41,10 @@ const BLOCKED_DEVICE_PATHS = new Set([
 function isProcStdioFd(key) {
     return key.startsWith("/proc/") && (key.endsWith("/fd/0") || key.endsWith("/fd/1") || key.endsWith("/fd/2"));
 }
-const PROC_SENSITIVE_RE = /^\/proc\/[^/]+\/(environ|cmdline|auxv|maps|mem|stat)$/;
+const PROC_SENSITIVE_SUFFIXES = ["/environ", "/cmdline", "/auxv", "/maps", "/mem", "/stat"];
+function isProcSensitiveFile(key) {
+    return key.startsWith("/proc/") && PROC_SENSITIVE_SUFFIXES.some((suf) => key.endsWith(suf));
+}
 const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^\\/]*)?$/i;
 function isWinFormPath(p) {
     return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\") || (!p.startsWith("/") && p.includes("\\"));
@@ -54,7 +57,7 @@ function isWinReservedDeviceKey(key) {
     return WIN_RESERVED_RE.test(base);
 }
 export function isBlockedDevicePath(key) {
-    return BLOCKED_DEVICE_PATHS.has(key) || isProcStdioFd(key) || PROC_SENSITIVE_RE.test(key) || isWinReservedDeviceKey(key);
+    return BLOCKED_DEVICE_PATHS.has(key) || isProcStdioFd(key) || isProcSensitiveFile(key) || isWinReservedDeviceKey(key);
 }
 export function normalizeAbsPathLexically(p) {
     if (!p.startsWith("/"))
@@ -73,12 +76,16 @@ export function normalizeAbsPathLexically(p) {
 }
 const BINARY_EXTENSIONS = new Set([
     ".exe", ".dll", ".so", ".dylib", ".o", ".a", ".obj", ".lib", ".bin", ".class", ".pyc", ".pyo", ".wasm",
-    ".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".jar", ".war", ".ear", ".lz4", ".zst",
+    ".app", ".msi", ".deb", ".rpm", ".node", ".rlib",
+    ".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".jar", ".war", ".ear", ".lz4", ".zst", ".z",
     ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif", ".ico", ".heic", ".avif",
-    ".mp3", ".wav", ".flac", ".ogg", ".m4a", ".aac", ".mp4", ".mov", ".avi", ".mkv", ".webm", ".wmv", ".flv",
+    ".mp3", ".wav", ".flac", ".ogg", ".m4a", ".aac", ".wma", ".aiff", ".opus",
+    ".mp4", ".mov", ".avi", ".mkv", ".webm", ".wmv", ".flv", ".m4v", ".mpeg", ".mpg",
     ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".odt", ".ods", ".odp",
     ".woff", ".woff2", ".ttf", ".otf", ".eot",
-    ".db", ".sqlite", ".sqlite3", ".mdb", ".dat", ".pdb", ".ipa", ".apk", ".dmg", ".iso", ".img",
+    ".psd", ".ai", ".eps", ".sketch", ".fig", ".xd", ".blend", ".3ds", ".max", ".swf", ".fla",
+    ".db", ".sqlite", ".sqlite3", ".mdb", ".idx", ".dat", ".data", ".lockb",
+    ".pdb", ".ipa", ".apk", ".dmg", ".iso", ".img",
 ]);
 export function hasBinaryExtension(path) {
     const dot = path.lastIndexOf(".");
@@ -256,7 +263,7 @@ export function checkNoChange(oldString, newString) {
 }
 export function checkStale(entry, currentHash) {
     if (entry.hash !== currentHash) {
-        return { code: "stale", message: "File has been modified since it was read; read it again before editing." };
+        return { code: "stale", message: "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it." };
     }
     return undefined;
 }
@@ -292,6 +299,95 @@ export function resolveQuoteMatch(content, oldString) {
         return undefined;
     return content.substring(idx, idx + oldString.length);
 }
+const UNICODE_ESCAPE_RE = /\\u[0-9a-fA-F]{4}/;
+const NON_ASCII_RE = /[\u0080-\uffff]/;
+function decodeUnicodeEscapes(s) {
+    return s.replace(/(\\\\)|\\u([0-9a-fA-F]{4})/g, (m, dbl, hex) => (dbl !== undefined ? m : String.fromCharCode(parseInt(hex, 16))));
+}
+function escapedSpellingPattern(s) {
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        if (code >= 128) {
+            out += "\\\\u";
+            for (const d of code.toString(16).padStart(4, "0"))
+                out += d >= "a" ? `[${d}${d.toUpperCase()}]` : d;
+        }
+        else
+            out += s[i].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return out;
+}
+export function resolveEscapeMatch(content, oldString) {
+    if (oldString === "")
+        return undefined;
+    if (UNICODE_ESCAPE_RE.test(oldString)) {
+        const decoded = decodeUnicodeEscapes(oldString);
+        if (decoded !== oldString && content.includes(decoded))
+            return decoded;
+    }
+    if (NON_ASCII_RE.test(oldString)) {
+        let hit = null;
+        try {
+            hit = content.match(new RegExp(escapedSpellingPattern(oldString)));
+        }
+        catch {
+            hit = null;
+        }
+        if (hit)
+            return hit[0];
+    }
+    return undefined;
+}
+export function adaptNewStringEscapes(oldString, matchedOld, newString) {
+    if (oldString === matchedOld)
+        return newString;
+    if (NON_ASCII_RE.test(oldString)) {
+        let full;
+        try {
+            full = new RegExp(`^${escapedSpellingPattern(oldString)}$`);
+        }
+        catch {
+            full = undefined;
+        }
+        if (full?.test(matchedOld)) {
+            const hexOf = new Map();
+            let upper = 0;
+            let lower = 0;
+            for (let i = 0, at = 0; i < oldString.length; i++) {
+                const code = oldString.charCodeAt(i);
+                if (code >= 128) {
+                    const hex = matchedOld.slice(at + 2, at + 6);
+                    hexOf.set(code, hex);
+                    for (const d of hex) {
+                        if (d >= "a" && d <= "f")
+                            lower++;
+                        else if (d >= "A" && d <= "F")
+                            upper++;
+                    }
+                    at += 6;
+                }
+                else
+                    at += 1;
+            }
+            return newString.replace(/[\u0080-\uffff]/g, (ch) => {
+                const code = ch.charCodeAt(0);
+                const known = hexOf.get(code);
+                if (known !== undefined)
+                    return `\\u${known}`;
+                const hex = code.toString(16).padStart(4, "0");
+                return `\\u${upper > lower ? hex.toUpperCase() : hex}`;
+            });
+        }
+    }
+    if (UNICODE_ESCAPE_RE.test(oldString) && decodeUnicodeEscapes(oldString) === matchedOld)
+        return decodeUnicodeEscapes(newString);
+    return newString;
+}
+export function escapeMatchWasAttempted(oldString) {
+    return UNICODE_ESCAPE_RE.test(oldString) || NON_ASCII_RE.test(oldString);
+}
+export 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.)";
 function isQuoteOpenerPosition(chars, i) {
     if (i === 0)
         return true;

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

@@ -21,6 +21,7 @@ export declare function splitAbsoluteGlobPattern(pattern: string): {
     relativePattern: string;
 } | undefined;
 export declare function shellQuote(s: string): string;
+export declare function invalidGlobTokens(glob: string): string[];
 export declare function gitignoreMatcher(content: string): (rel: string, isDir: boolean) => boolean;
 export declare function buildIgnore(env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<(rel: string, isDir: boolean) => boolean>;
 export interface WalkResult {

package/dist/tools/fs/search.js

@@ -76,7 +76,7 @@ export function splitAbsoluteGlobPattern(pattern) {
 export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-function globTokenToRegExp(token, anchored, glob = false) {
+function globTokenToRegExp(token, anchored, glob = false, report) {
     const charToRe = (ch) => ch === "*" ? "[^/]*" : ch === "?" ? "[^/]" : ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     let re = "";
     for (let i = 0; i < token.length; i++) {
@@ -100,8 +100,11 @@ function globTokenToRegExp(token, anchored, glob = false) {
                 re += `(?:${alts.join("|")})`;
                 i = close;
             }
-            else
+            else {
                 re += "\\{";
+                if (report)
+                    report.degraded = true;
+            }
         }
         else if (glob && c === "[") {
             let j = i + 1;
@@ -129,14 +132,27 @@ function globTokenToRegExp(token, anchored, glob = false) {
                 re += cls;
                 i = close;
             }
-            else
+            else {
                 re += "\\[";
+                if (report)
+                    report.degraded = true;
+            }
         }
         else
             re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     }
     return new RegExp(`${anchored ? "^" : "(^|/)"}${re}$`);
 }
+export function invalidGlobTokens(glob) {
+    const bad = [];
+    for (const token of splitGlobParam(glob)) {
+        const report = { degraded: false };
+        globTokenToRegExp(normalizeGlobToken(token), globIsAnchored(token), true, report);
+        if (report.degraded)
+            bad.push(token);
+    }
+    return bad;
+}
 function normalizeGlobToken(token) {
     let t = token;
     while (t.startsWith("./"))
@@ -1095,6 +1111,10 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
             const error = `Error (Glob): path ${JSON.stringify(opts.path)} does not exist — check the path, or omit \`path\` to search the whole root.`;
             return { text: error, error, filenames: [], numFiles: 0, truncated: false, durationMs: Date.now() - t0, totalMatches: 0, countIsComplete: false };
         }
+        if (probe.ok && probe.value.kind === "file") {
+            const error = `Error (Glob): path ${JSON.stringify(opts.path)} is not a directory — \`path\` scopes the search to a directory; pass its parent directory (and name the file in \`pattern\`), or omit \`path\` to search the whole root.`;
+            return { text: error, error, filenames: [], numFiles: 0, truncated: false, durationMs: Date.now() - t0, totalMatches: 0, countIsComplete: false };
+        }
     }
     const pat = normalizeGlobToken(pattern);
     const anchored = globIsAnchored(pattern);

package/dist/tools/monitor.js

@@ -10,7 +10,7 @@ const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its
     `exceeds its timeout is killed and reported (default ${MONITOR_DEFAULT_TIMEOUT_MS}ms, max ${MONITOR_MAX_TIMEOUT_MS}ms).\n` +
     "- stderr does NOT trigger notifications, but it is captured — read it any time with TaskOutput(task_id), " +
     "which also serves the full re-readable stdout spool.\n" +
-    "- A monitor that produces too many events is stopped automatically (the stop notification says why).\n" +
+    "- A monitor that produces too many events is rate-limited: excess batches are suppressed (a notification tells you how many), and a watch that stays over the limit is stopped automatically.\n" +
     "- Set persistent: true for a session-resident watch with no watch timeout of its own; it still ends when " +
     "the execution environment's background time budget expires, when you stop it with TaskStop(task_id), or " +
     "when the session is released.\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -56,7 +56,8 @@
     "smoke": "tsx src/examples/smoke.ts",
     "eval": "tsx eval/run.ts",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build && npm run test"
+    "prepublishOnly": "npm run build && npm run test",
+    "gate:blackbox": "node scripts/run-blackbox-gate.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",