@sema-agent/core 1.294.0 → 1.296.0

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

@@ -14,7 +14,10 @@ export declare function seedReadFileStateFromContext(state: ReadFileState, key:
 export interface CwdRef {
     current: string;
 }
-export declare function makeReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities): AgentTool;
+export declare function makeReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
+    taskId?: string;
+    principal?: string;
+}) => boolean): AgentTool;
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook } from "../../core/types.js";
 export declare function makeEditFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook): AgentTool;
 export declare function makeWriteFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], beforeWrite?: BeforeWriteHook): AgentTool;
@@ -34,6 +37,10 @@ export declare function bashReversibilityProbe(allow?: readonly string[]): (args
 export interface ExecClampOption {
     deadlineMs: () => number | undefined;
     onClamp?: (requestedSec: number, clampedSec: number) => void;
+    registerKillHandle?: (toolCallId: string, handle: {
+        pid: number;
+        kill: () => void;
+    }) => () => void;
 }
 export declare function bashExitOneInterpretation(command: string): string | undefined;
 export declare function makeBashTool(env: ExecutionEnv, rootCanonical: string, coAuthor?: string | false, cwdRef?: CwdRef, taskOpts?: {

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/fs/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/fs/index.js

@@ -324,7 +324,7 @@ async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, p
         },
     };
 }
-export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities) {
+export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption) {
     return defineTool({
         name: "Read",
         description: "Reads a file from the local filesystem.\n" +
@@ -352,7 +352,7 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
             const path = fileArgPath(args);
             if (path === undefined)
                 return `Error (Read): file_path is required.`;
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
+            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx));
             if (!r.ok)
                 return violationText("Read", r.violation);
             const imageMime = imageMimeForRead(r.key);
@@ -937,21 +937,20 @@ export function makeNotebookEditTool(env, state, rootCanonical, cwdRef, addition
 export function makeGrepTool(env, rootCanonical, additionalRoots) {
     return defineTool({
         name: "Grep",
-        description: "Search file contents under the root. ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a " +
-            "Bash command. Uses ripgrep when available (respects .gitignore, skips binary/hidden files), otherwise a " +
-            "JS fallback that skips node_modules/build/.dart_tool/… and parses .gitignore. Pattern is a LITERAL " +
-            "substring by default — set `regex: true` for regex syntax. Returns relative `path:line:text` (content " +
-            "mode), `path` (files_with_matches), or `path:count` (count). By default patterns match within single " +
-            "lines only; for cross-line patterns use `multiline: true`. Use Agent tool for open-ended searches " +
-            "requiring multiple rounds.",
+        description: "Content search built on ripgrep. Prefer this over `grep`/`rg` via Bash — results integrate with the permission UI and file links.\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/hidden files), otherwise a JS fallback that skips node_modules/build/… and parses .gitignore.\n" +
+            "- Use Agent tool for open-ended searches requiring multiple rounds",
         parameters: Type.Object({
-            pattern: Type.String({ description: "Literal substring, or a regex when `regex` is true." }),
-            regex: Type.Optional(Type.Boolean({ description: "Treat pattern as a regex (default false = literal)." })),
+            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)." })),
             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")], {
-                description: "content (default): path:line:text. files_with_matches: path. count: path:count.",
+                description: '"content" (matching lines), "files_with_matches" (paths only), or "count" (match counts). Defaults to "files_with_matches".',
             })),
             context: Type.Optional(Type.Number({ description: "Lines of context around each match (content mode). CC alias: -C." })),
             "-C": Type.Optional(Type.Number({ description: "Number of lines to show before and after each match (content mode only)." })),
@@ -964,7 +963,9 @@ export function makeGrepTool(env, rootCanonical, additionalRoots) {
             })),
             "-n": Type.Optional(Type.Boolean({ description: "Show line numbers (accepted for CC compatibility; content mode always includes line numbers)." })),
             multiline: Type.Optional(Type.Boolean({ description: "Match across line boundaries." })),
-            head_limit: Type.Optional(Type.Number({ description: "Cap results (default 250)." })),
+            head_limit: Type.Optional(Type.Number({
+                description: 'Limit output to first N lines/entries, equivalent to "| head -N". Works across all output modes: content (limits output lines), files_with_matches (limits file paths), count (limits count entries). Defaults to 250 when unspecified. Pass 0 for unlimited (use sparingly — large result sets waste context).',
+            })),
             offset: Type.Optional(Type.Number({ description: "Skip the first N output lines (pagination partner of head_limit)." })),
             max_results: Type.Optional(Type.Number({ description: "Deprecated alias for head_limit." })),
         }),
@@ -989,7 +990,9 @@ export function makeGrepTool(env, rootCanonical, additionalRoots) {
                 only_matching: a.only_matching ?? a["-o"],
             }, ctx.signal);
             const text = grepRun.text;
-            const mode = a.output_mode ?? "content";
+            if (text.startsWith("Error (grep)") || text.startsWith("Error (Grep)"))
+                return text;
+            const mode = a.output_mode ?? "files_with_matches";
             const rows = text.startsWith("No matches.")
                 ? []
                 : text
@@ -1045,7 +1048,9 @@ export function makeGlobTool(env, rootCanonical, additionalRoots) {
         name: "Glob",
         description: "- Fast file pattern matching tool that works with any codebase size\n" +
             '- Supports glob patterns like "**/*.js" or "src/**/*.ts"\n' +
-            "- Returns matching RELATIVE file paths, sorted alphabetically; skips ignored trees (node_modules/build/.gitignore)\n" +
+            "- Returns matching file paths sorted by modification time\n" +
+            "- 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\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",
         parameters: Type.Object({
@@ -1219,7 +1224,7 @@ async function diagnoseDeadCwd(env, toolName, effectiveCwd, root, cwdRef) {
         `It was likely deleted by a previous command (e.g. rm -rf on the current directory). There is no directory to reset to; ` +
         `this task cannot recover its working tree.`);
 }
-async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef, detach, execClamp) {
+async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef, detach, execClamp, toolCallId) {
     let timeout = Math.min(BASH_MAX_TIMEOUT_SEC, Math.max(1, Math.floor(timeoutSec ?? BASH_DEFAULT_TIMEOUT_SEC)));
     const requestedSec = timeout;
     let clampedByDeadline = false;
@@ -1242,13 +1247,36 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
         ? `${command}\n__cc_rc=$?; printf '%s%s%s' '${CWD_SENTINEL}' "$(pwd)" '${CWD_SENTINEL}' 1>&2; exit $__cc_rc`
         : command;
     const execEnv = cwdRef ? { env: { PWD: effectiveCwd } } : undefined;
-    const res = await env.exec(toRun, {
-        cwd: effectiveCwd,
-        timeout,
-        abortSignal: signal,
-        ...execEnv,
-        ...(detach ? { detachSignal: detach.signal } : {}),
-    });
+    let deregisterKill;
+    const registerKillHandle = execClamp?.registerKillHandle;
+    let res;
+    try {
+        res = await env.exec(toRun, {
+            cwd: effectiveCwd,
+            timeout,
+            abortSignal: signal,
+            ...execEnv,
+            ...(detach
+                ? {
+                    detachSignal: detach.signal,
+                    onDetachAdopted: () => {
+                        deregisterKill?.();
+                        deregisterKill = undefined;
+                    },
+                }
+                : {}),
+            ...(registerKillHandle !== undefined && toolCallId !== undefined
+                ? {
+                    onSpawn: (handle) => {
+                        deregisterKill = registerKillHandle(toolCallId, handle);
+                    },
+                }
+                : {}),
+        });
+    }
+    finally {
+        deregisterKill?.();
+    }
     if (!res.ok) {
         if (res.error.code === "spawn_error" || res.error.code === "shell_unavailable") {
             const diagnosis = await diagnoseDeadCwd(env, toolName, effectiveCwd, cwd, cwdRef);
@@ -1423,6 +1451,14 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                     const owner = sessionScoped ? taskOpts.sessionId : (ctx.taskId ?? taskOpts.taskOwner);
                     const scope = ctx.principal ?? taskOpts.taskScope;
                     const onNotify = taskOpts.onTaskNotification;
+                    let outputFile;
+                    if (onNotify !== undefined) {
+                        const tf = await env.createTempFile({ prefix: "bash-task-", suffix: ".output" });
+                        if (tf.ok) {
+                            const tfCanon = await env.canonicalPath(tf.value);
+                            outputFile = tfCanon.ok ? tfCanon.value : tf.value;
+                        }
+                    }
                     let taskId;
                     try {
                         taskId = taskOpts.taskRegistry.registerBackgroundBash({
@@ -1433,6 +1469,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                             ...(owner !== undefined ? { owner } : {}),
                             ...(scope !== undefined ? { scope } : {}),
                             ...(sessionScoped ? { sessionScoped: true } : {}),
+                            ...(outputFile !== undefined ? { outputFile } : {}),
                             ...(onNotify !== undefined ? { onTerminal: (n) => onNotify(n, { priority: "next" }) } : {}),
                         });
                     }
@@ -1456,9 +1493,12 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                             details: { type: "bash", registerFailed: true, killFailed: true },
                         };
                     }
+                    const interimNote = outputFile !== undefined
+                        ? ` Output file: ${outputFile} (full output is appended there — Read it any time).`
+                        : ` Use TaskOutput("${taskId}") to check interim output.`;
                     return onNotify !== undefined
-                        ? `Command running in background; task_id=${taskId}. You will be notified when it completes — do not poll; ` +
-                            `end your turn if nothing else is pending. Use TaskOutput("${taskId}") to check interim output; TaskStop("${taskId}") to stop.` +
+                        ? `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.` +
                             budgetNote
                         : `Started in background; task_id=${taskId}. ` +
                             `Use TaskOutput("${taskId}") to read output (poll until status is no longer "running"); ` +
@@ -1478,6 +1518,14 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                         const owner = sessionScoped ? taskOpts.sessionId : (ctx.taskId ?? taskOpts.taskOwner);
                         const scope = ctx.principal ?? taskOpts.taskScope;
                         const onNotify = taskOpts.onTaskNotification;
+                        let outputFile;
+                        if (onNotify !== undefined) {
+                            const tf = await env.createTempFile({ prefix: "bash-task-", suffix: ".output" });
+                            if (tf.ok) {
+                                const tfCanon = await env.canonicalPath(tf.value);
+                                outputFile = tfCanon.ok ? tfCanon.value : tf.value;
+                            }
+                        }
                         let taskId;
                         try {
                             taskId = taskOpts.taskRegistry.registerBackgroundBash({
@@ -1488,6 +1536,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                                 ...(owner !== undefined ? { owner } : {}),
                                 ...(scope !== undefined ? { scope } : {}),
                                 ...(sessionScoped ? { sessionScoped: true } : {}),
+                                ...(outputFile !== undefined ? { outputFile } : {}),
                                 ...(onNotify !== undefined ? { onTerminal: (n) => onNotify(n, { priority: "next" }) } : {}),
                             });
                         }
@@ -1529,20 +1578,23 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                             : "";
                         return {
                             content: `Command moved to background; task_id=${taskId}. ` +
-                                `Use TaskOutput("${taskId}") to read its output; TaskStop("${taskId}") to stop it. ` +
+                                (outputFile !== undefined
+                                    ? `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".`) +
                                 adoptBudgetNote +
                                 (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
-                            details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}) },
+                            details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}) },
                         };
                     },
                 }
                 : undefined;
             let res;
             try {
-                res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, cwdRef, detachChain, taskOpts.execClamp);
+                res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, cwdRef, detachChain, taskOpts.execClamp, ctx.toolCallId);
             }
             finally {
                 taskOpts.detachHub?.gc(ctx.toolCallId);
@@ -1576,7 +1628,7 @@ export function makeBashReadonlyTool(env, rootCanonical, allow, execClamp) {
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
                 return `Error (Bash): ${reason}`;
-            return runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, undefined, undefined, execClamp);
+            return runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, undefined, undefined, execClamp, ctx.toolCallId);
         },
     });
 }
@@ -1658,7 +1710,17 @@ export function makeKillShellTool(env, registry = defaultTaskRegistry) {
 export function createHandsToolkit(env, readFileState, rootCanonical, opts = {}) {
     const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = DEFAULT_COMMIT_COAUTHOR, mountBackgroundTaskTools = true, additionalRoots, } = opts;
     const cwdRef = opts.cwdRef ?? { current: rootCanonical };
-    const tools = [makeReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, additionalRoots, opts.readImageDownsampler, opts.pdfModelCapabilities)];
+    const bgReadRegistry = opts.taskRegistry;
+    const bgOutputReadExemption = bgReadRegistry === undefined
+        ? undefined
+        : (canonicalKey, c) => bgReadRegistry.isBackgroundOutputFile(canonicalKey, {
+            owner: c.taskId ?? opts.taskOwner,
+            scope: c.principal ?? opts.taskScope,
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+        }, env);
+    const tools = [
+        makeReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, additionalRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption),
+    ];
     if (!readOnly) {
         tools.push(makeEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), makeWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), makeNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite));
     }