@sema-agent/core 1.450.0 → 1.452.0

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

@@ -0,0 +1,43 @@
+export declare function isNotebookPath(p: string): boolean;
+export declare const NOTEBOOK_CELL_OUTPUT_POINTER_CHARS = 10000;
+export declare const NOTEBOOK_OUTPUT_TEXT_CLIP = 10000;
+export declare const NOTEBOOK_IMAGE_BASE64_BUDGET = 262144;
+export interface NotebookOutputImage {
+    image_data: string;
+    media_type: "image/png" | "image/jpeg";
+}
+export interface NotebookOutput {
+    output_type: string;
+    text?: string;
+    image?: NotebookOutputImage;
+}
+export interface NotebookCell {
+    cell_id: string;
+    cellType: string;
+    source: string;
+    language?: string;
+    execution_count?: number;
+    outputs?: NotebookOutput[];
+}
+export type ParsedNotebook = {
+    ok: true;
+    cells: NotebookCell[];
+} | {
+    ok: false;
+    reason: "json" | "shape";
+};
+export declare function parseNotebookCells(text: string, notebookPath: string): ParsedNotebook;
+export interface NotebookRender {
+    blocks: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>;
+    textChars: number;
+    imageChars: number;
+}
+export declare function renderNotebookCells(cells: readonly NotebookCell[], imageBase64Budget: number): NotebookRender;
+export declare function stripNotebookImageData(cell: NotebookCell): NotebookCell;

package/dist/tools/fs/notebook.js

@@ -0,0 +1,141 @@
+import { imageMagicMatches } from "./safety.js";
+export function isNotebookPath(p) {
+    return p.toLowerCase().endsWith(".ipynb");
+}
+export const NOTEBOOK_CELL_OUTPUT_POINTER_CHARS = 10_000;
+export const NOTEBOOK_OUTPUT_TEXT_CLIP = 10_000;
+export const NOTEBOOK_IMAGE_BASE64_BUDGET = 262_144;
+function joinedText(v) {
+    if (v === undefined || v === null)
+        return "";
+    return Array.isArray(v) ? v.join("") : String(v);
+}
+function clipOutputText(s) {
+    if (s.length <= NOTEBOOK_OUTPUT_TEXT_CLIP)
+        return s;
+    const droppedLines = s.slice(NOTEBOOK_OUTPUT_TEXT_CLIP).split("\n").length;
+    return `${s.slice(0, NOTEBOOK_OUTPUT_TEXT_CLIP)}\n\n… [${droppedLines} lines truncated] …`;
+}
+function imageFromData(data) {
+    if (data === undefined)
+        return undefined;
+    for (const mime of ["image/png", "image/jpeg"]) {
+        const v = data[mime];
+        if (typeof v !== "string")
+            continue;
+        const stripped = v.replace(/\s/g, "");
+        if (!imageMagicMatches(Buffer.from(stripped, "base64"), mime))
+            return undefined;
+        return { image_data: stripped, media_type: mime };
+    }
+    return undefined;
+}
+function mapOutput(raw) {
+    if (raw === null || typeof raw !== "object")
+        return undefined;
+    const o = raw;
+    switch (o.output_type) {
+        case "stream":
+            return { output_type: "stream", text: clipOutputText(joinedText(o.text)) };
+        case "execute_result":
+        case "display_data": {
+            const data = o.data !== null && typeof o.data === "object" ? o.data : undefined;
+            const image = imageFromData(data);
+            return { output_type: o.output_type, text: clipOutputText(joinedText(data?.["text/plain"])), ...(image ? { image } : {}) };
+        }
+        case "error": {
+            const tb = Array.isArray(o.traceback) ? o.traceback.join("\n") : "";
+            return { output_type: "error", text: clipOutputText(`${joinedText(o.ename)}: ${joinedText(o.evalue)}\n${tb}`) };
+        }
+        default:
+            return undefined;
+    }
+}
+export function parseNotebookCells(text, notebookPath) {
+    let nb;
+    try {
+        nb = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "json" };
+    }
+    const top = nb;
+    const rawCells = top?.cells;
+    if (!Array.isArray(rawCells) || rawCells.some((c) => c === null || typeof c !== "object")) {
+        return { ok: false, reason: "shape" };
+    }
+    const language = typeof top?.metadata?.language_info?.name === "string" ? top.metadata.language_info.name : "python";
+    const cells = rawCells.map((raw, i) => {
+        const c = raw;
+        const cellType = typeof c.cell_type === "string" ? c.cell_type : "code";
+        const cell = {
+            cell_id: typeof c.id === "string" ? c.id : `cell-${i}`,
+            cellType,
+            source: joinedText(c.source),
+        };
+        if (cellType === "code") {
+            cell.language = language;
+            if (typeof c.execution_count === "number" && c.execution_count)
+                cell.execution_count = c.execution_count;
+            if (Array.isArray(c.outputs) && c.outputs.length > 0) {
+                const mapped = c.outputs.map(mapOutput).filter((o) => o !== undefined);
+                let sum = 0;
+                let over = false;
+                for (const o of mapped) {
+                    sum += (o.text?.length ?? 0) + (o.image?.image_data.length ?? 0);
+                    if (sum > NOTEBOOK_CELL_OUTPUT_POINTER_CHARS) {
+                        over = true;
+                        break;
+                    }
+                }
+                cell.outputs = over
+                    ? [{ output_type: "stream", text: `Outputs are too large to include. Use Bash with: cat "${notebookPath}" | jq '.cells[${i}].outputs'` }]
+                    : mapped;
+            }
+        }
+        return cell;
+    });
+    return { ok: true, cells };
+}
+export function renderNotebookCells(cells, imageBase64Budget) {
+    const blocks = [];
+    let imageChars = 0;
+    const pushText = (t) => {
+        const last = blocks[blocks.length - 1];
+        if (last !== undefined && last.type === "text")
+            last.text += `\n${t}`;
+        else
+            blocks.push({ type: "text", text: t });
+    };
+    for (const cell of cells) {
+        const tags = [];
+        if (cell.cellType !== "code")
+            tags.push(`<cell_type>${cell.cellType}</cell_type>`);
+        if (cell.language !== undefined && cell.language !== "python" && cell.cellType === "code")
+            tags.push(`<language>${cell.language}</language>`);
+        pushText(`<cell id="${cell.cell_id}">${tags.join("")}${cell.source}</cell id="${cell.cell_id}">`);
+        for (const o of cell.outputs ?? []) {
+            if (o.text !== undefined && o.text !== "")
+                pushText(`\n${o.text}`);
+            if (o.image !== undefined) {
+                if (imageChars + o.image.image_data.length > imageBase64Budget) {
+                    pushText("[image output omitted: notebook image budget exceeded]");
+                }
+                else {
+                    imageChars += o.image.image_data.length;
+                    blocks.push({ type: "image", data: o.image.image_data, mimeType: o.image.media_type });
+                }
+            }
+        }
+    }
+    const textChars = blocks.reduce((n, b) => n + (b.type === "text" ? b.text.length : 0), 0);
+    return { blocks, textChars, imageChars };
+}
+export function stripNotebookImageData(cell) {
+    if (cell.outputs === undefined)
+        return cell;
+    return {
+        ...cell,
+        outputs: cell.outputs.map((o) => o.image === undefined ? o : { ...o, image: { ...o.image, image_data: `[${o.image.image_data.length} base64 chars omitted]` } }),
+    };
+}

package/dist/tools/fs/repo-map.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { defineTool } from "../../core/tools.js";
+import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText } from "./safety.js";
 import { buildIgnore, walk, walkIsPartial } from "./search.js";
 const DEFAULT_MAX_CHARS = 16_000;
@@ -101,7 +101,7 @@ export function makeRepoMapTool(env, rootCanonical, additionalRoots) {
             if (a.path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, a.path, signal, rootCanonical, additionalRoots);
                 if (!r.ok)
-                    return violationText("RepoMap", r.violation);
+                    return errorResult(violationText("RepoMap", r.violation));
                 start = r.key;
             }
             const maxChars = Math.max(1, Math.floor(a.max_chars ?? DEFAULT_MAX_CHARS));

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, braces = false) {
+function globTokenToRegExp(token, anchored, glob = false) {
     const charToRe = (ch) => ch === "*" ? "[^/]*" : ch === "?" ? "[^/]" : ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     let re = "";
     for (let i = 0; i < token.length; i++) {
@@ -93,7 +93,7 @@ function globTokenToRegExp(token, anchored, braces = false) {
         }
         else if (c === "?")
             re += "[^/]";
-        else if (braces && c === "{") {
+        else if (glob && c === "{") {
             const close = token.indexOf("}", i);
             if (close > i + 1) {
                 const alts = token.slice(i + 1, close).split(",").map((alt) => [...alt].map(charToRe).join(""));
@@ -103,11 +103,52 @@ function globTokenToRegExp(token, anchored, braces = false) {
             else
                 re += "\\{";
         }
+        else if (glob && c === "[") {
+            let j = i + 1;
+            let neg = false;
+            if (token[j] === "!" || token[j] === "^") {
+                neg = true;
+                j++;
+            }
+            const bodyStart = j;
+            if (token[j] === "]")
+                j++;
+            const close = token.indexOf("]", j);
+            let cls;
+            if (close !== -1) {
+                const body = token.slice(bodyStart, close).replace(/[\\[\]]/g, "\\$&").replace(/\//g, "");
+                cls = `[${neg ? "^/" : ""}${body}]`;
+                try {
+                    new RegExp(cls);
+                }
+                catch {
+                    cls = undefined;
+                }
+            }
+            if (cls !== undefined) {
+                re += cls;
+                i = close;
+            }
+            else
+                re += "\\[";
+        }
         else
             re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     }
     return new RegExp(`${anchored ? "^" : "(^|/)"}${re}$`);
 }
+function normalizeGlobToken(token) {
+    let t = token;
+    while (t.startsWith("./"))
+        t = t.slice(2);
+    return t.replace(/^\/+/, "");
+}
+function globIsAnchored(token) {
+    let t = token;
+    while (t.startsWith("./"))
+        t = t.slice(2);
+    return t.includes("/");
+}
 export function gitignoreMatcher(content) {
     const rules = content
         .split(/\r?\n/)
@@ -736,9 +777,9 @@ export async function jsGrep(env, root, p, signal, guards) {
         return p.path || r === abs ? r : `./${r}`;
     };
     if (p.glob) {
-        const globRes = splitGlobParam(p.glob).map((g) => globTokenToRegExp(g, false, true));
+        const globRes = splitGlobParam(p.glob).map((g) => globTokenToRegExp(normalizeGlobToken(g), globIsAnchored(g), true));
         if (globRes.length > 0)
-            files = files.filter((f) => globRes.some((re) => re.test(rel(f))));
+            files = files.filter((f) => globRes.some((re) => re.test(rel(f).replace(/\\/g, "/"))));
     }
     let typeNote = "";
     if (p.type) {
@@ -863,8 +904,8 @@ export async function jsGrep(env, root, p, signal, guards) {
             totalContent += fileCount;
         if (fileCount > 0) {
             totalFiles++;
-            if (mode === "files_with_matches" && fileMatches.length < collectCap)
-                fileMatches.push(relOut(f));
+            if (mode === "files_with_matches")
+                fileMatches.push(f);
             else if (mode === "count" && counts.length < collectCap)
                 counts.push(`${relOut(f)}:${fileCount}`);
         }
@@ -888,7 +929,14 @@ export async function jsGrep(env, root, p, signal, guards) {
     const paged = (arr) => (off > 0 ? arr.slice(off, off + cap) : arr);
     const offNote = off > 0 ? `\n[offset ${off}]` : "";
     if (mode === "files_with_matches") {
-        const body = paged(fileMatches);
+        const haveMtimes = fileMatches.length > 0 && fileMatches.every((f) => walked.mtimes.has(f));
+        const sortedFileMatches = haveMtimes
+            ? fileMatches
+                .map((f) => ({ r: relOut(f), m: walked.mtimes.get(f) }))
+                .sort((a, b) => b.m - a.m || (a.r < b.r ? -1 : a.r > b.r ? 1 : 0))
+                .map((x) => x.r)
+            : fileMatches.map(relOut).sort();
+        const body = sortedFileMatches.slice(off, off + cap);
         return body.length === 0
             ? NO_MATCHES + offNote + typeNote + caveat
             : body.join("\n") + (totalFiles > off + cap ? `\n…[capped at ${cap} of ${totalFiles}]` : "") + offNote + typeNote + caveat;
@@ -921,6 +969,25 @@ export function detectRipgrep(env) {
     }
     return cached;
 }
+async function sortRgFilesByMtime(env, root, stdout, signal) {
+    const paths = stdout.split("\n").filter((l) => l.length > 0);
+    if (paths.length === 0)
+        return stdout;
+    const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
+    const toAbs = (p) => {
+        const stripped = p.startsWith("./") ? p.slice(2) : p;
+        return stripped.startsWith("/") || /^[A-Za-z]:[\\/]/.test(stripped) ? stripped : `${rootPrefix}${stripped}`;
+    };
+    const infos = await Promise.all(paths.map((p) => env.fileInfo(toAbs(p), signal)));
+    const withMtime = paths.map((p, i) => {
+        const r = infos[i];
+        return { p, m: r.ok && typeof r.value.mtimeMs === "number" ? r.value.mtimeMs : undefined };
+    });
+    const sorted = withMtime.every((x) => x.m !== undefined)
+        ? [...withMtime].sort((a, b) => b.m - a.m || (a.p < b.p ? -1 : a.p > b.p ? 1 : 0))
+        : [...withMtime].sort((a, b) => (a.p < b.p ? -1 : a.p > b.p ? 1 : 0));
+    return sorted.map((x) => x.p).join("\n");
+}
 function formatRgStdout(stdout, p, caveat = "") {
     const cap = p.head_limit === 0 ? Infinity : Math.max(1, Math.floor(p.head_limit ?? GREP_DEFAULT_CAP));
     const off = Math.max(0, Math.floor(p.offset ?? 0));
@@ -1003,7 +1070,8 @@ export async function rgGrepDetailed(env, root, p, signal) {
         }
         return jsGrepFallback(env, root, p, signal, `exited with code ${exitCode} and produced no output`);
     }
-    return { text: formatRgStdout(stdout, p) };
+    const orderedStdout = mode === "files_with_matches" ? await sortRgFilesByMtime(env, root, stdout, signal) : stdout;
+    return { text: formatRgStdout(orderedStdout, p) };
 }
 export async function runGrepDetailed(env, root, p, signal) {
     if (await detectRipgrep(env))
@@ -1018,16 +1086,74 @@ export async function runGlob(env, root, pattern, opts = {}, signal) {
 }
 export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     const t0 = Date.now();
-    const ignore = await buildIgnore(env, root, signal);
+    const baseIgnore = await buildIgnore(env, root, signal);
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
     const start = opts.path ? (opts.path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(opts.path) ? opts.path : `${rootPrefix}${opts.path}`) : root;
+    const pat = normalizeGlobToken(pattern);
+    const anchored = globIsAnchored(pattern);
+    const re = globTokenToRegExp(pat, anchored, true);
+    const startPrefix = start.replace(/[\\/]+$/, "") + (start.includes("\\") ? "\\" : "/");
+    const startRelPrefix = startPrefix.startsWith(rootPrefix) ? startPrefix.slice(rootPrefix.length) : startPrefix;
+    const toStartRel = (p) => {
+        const s = p.startsWith(startPrefix)
+            ? p.slice(startPrefix.length)
+            : startRelPrefix.length > 0 && p.startsWith(startRelPrefix)
+                ? p.slice(startRelPrefix.length)
+                : p;
+        return s.replace(/\\/g, "/");
+    };
+    const patternSegs = pat.split("/");
+    const groupSpansSlash = /\{[^}]*\/[^}]*\}|\[[^\]]*\/[^\]]*\]/.test(pat);
+    const prunable = anchored && !groupSpansSlash;
+    const firstStarStar = patternSegs.findIndex((s) => s.includes("**"));
+    const starStarIdx = firstStarStar === -1 ? Infinity : firstStarStar;
+    const segRes = prunable ? patternSegs.map((s) => globTokenToRegExp(s, true, true)) : [];
+    const isLiteralSeg = (s) => s.length > 0 && !/[*?[{]/.test(s);
+    const literalAt = prunable ? patternSegs.map((s) => (isLiteralSeg(s) ? s : undefined)) : [];
+    const literalAfterStarStar = new Set(prunable ? patternSegs.filter((s, i) => i > starStarIdx && isLiteralSeg(s)) : []);
+    const mayContainMatch = (dirRel) => {
+        if (!prunable)
+            return true;
+        const d = dirRel.split("/");
+        if (d.length >= patternSegs.length && starStarIdx === Infinity)
+            return false;
+        const lim = Math.min(d.length, starStarIdx);
+        for (let i = 0; i < lim; i++)
+            if (!segRes[i].test(d[i]))
+                return false;
+        return true;
+    };
+    const explicitlyNamed = (sr) => {
+        if (!prunable)
+            return false;
+        const segs = sr.split("/");
+        const k = segs.length - 1;
+        return k < starStarIdx ? literalAt[k] === segs[k] : literalAfterStarStar.has(segs[k]);
+    };
+    let ignoredDirs = 0;
+    const rescued = [];
+    const ignore = (relPath, isDir) => {
+        const sr = toStartRel(relPath);
+        if (isDir && !mayContainMatch(sr))
+            return true;
+        if (explicitlyNamed(sr)) {
+            if (isDir && baseIgnore(relPath, true))
+                rescued.push(sr + "/");
+            return false;
+        }
+        if (rescued.length > 0 && rescued.some((r) => sr.startsWith(r)))
+            return false;
+        const ig = baseIgnore(relPath, isDir);
+        if (ig && isDir)
+            ignoredDirs++;
+        return ig;
+    };
     const walked = await walk(env, root, start, ignore, signal);
     const caveat = walkCaveat(walked, false);
     const files = [...walked.files, ...walked.nameOnly];
-    const re = globTokenToRegExp(pattern, false, true);
     const rel = (abs) => (abs.startsWith(rootPrefix) ? abs.slice(rootPrefix.length) : abs);
     const cap = Math.max(1, Math.floor(opts.max ?? 500));
-    const matchedAbs = files.filter((f) => re.test(rel(f)) || re.test(basename(f)));
+    const matchedAbs = files.filter((f) => re.test(toStartRel(f)) || (!anchored && re.test(basename(f))));
     const haveMtimes = matchedAbs.length > 0 && matchedAbs.every((f) => walked.mtimes.has(f));
     const matchedAll = haveMtimes
         ? matchedAbs
@@ -1044,6 +1170,9 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
         : countIsComplete
             ? `\n(Showing ${matched.length} of ${totalMatches} matching files; ${totalMatches - matched.length} more are not listed. Narrow the pattern or path to see the rest.)`
             : `\n(Showing the first ${matched.length} files; there are more than ${totalMatches} matches. Narrow the pattern or path to see the rest.)`;
-    const text = matched.length === 0 ? "No files matched." + caveat : matched.join("\n") + capNote + caveat;
+    const ignoreNote = matched.length === 0 && ignoredDirs > 0
+        ? `\n[note: ${ignoredDirs} ignored director${ignoredDirs === 1 ? "y was" : "ies were"} not searched (dependency/build/VCS trees and .gitignore) — name a directory in the pattern (e.g. "dist/**") or pass \`path\` to include it]`
+        : "";
+    const text = matched.length === 0 ? "No files matched." + ignoreNote + caveat : matched.join("\n") + capNote + caveat;
     return { text, filenames: matched, numFiles: matched.length, truncated, durationMs: Date.now() - t0, totalMatches, countIsComplete };
 }

package/dist/tools/gitea-issue.js

@@ -23,7 +23,7 @@ export function createGiteaIssueTool(opts) {
             const a = args;
             const title = String(a.title ?? "").trim();
             if (!title) {
-                return { content: "Issue not created: a non-empty title is required.", details: { error: "empty title" } };
+                return { content: "Issue not created: a non-empty title is required.", details: { error: "empty title" }, isError: true };
             }
             const modelLabels = opts.allowModelLabels && Array.isArray(a.labels) ? a.labels : [];
             const labels = [...new Set([...(opts.defaultLabels ?? []), ...modelLabels])];
@@ -43,13 +43,14 @@ export function createGiteaIssueTool(opts) {
             }
             catch (e) {
                 const msg = e instanceof Error ? e.message : String(e);
-                return { content: `Issue not created: request failed (${msg}).`, details: { error: msg } };
+                return { content: `Issue not created: request failed (${msg}).`, details: { error: msg }, isError: true };
             }
             if (!res.ok) {
                 const detail = await res.text().catch(() => "");
                 return {
                     content: `Issue not created: Gitea returned HTTP ${res.status}. ${detail.slice(0, 300)}`,
                     details: { status: res.status },
+                    isError: true,
                 };
             }
             const PARSE_FAILED = Symbol("json-parse-failed");
@@ -60,6 +61,7 @@ export function createGiteaIssueTool(opts) {
                     content: `Issue request returned HTTP ${res.status} but the response body was not a valid issue ` +
                         `(no number) — the issue may NOT have been created; verify before retrying.`,
                     details: { status: res.status, parsed: parsed === PARSE_FAILED ? "unparseable" : "no-number" },
+                    isError: true,
                 };
             }
             const issue = parsed;

package/dist/tools/monitor.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { defineTool } from "../core/tools.js";
+import { defineTool, errorResult } from "../core/tools.js";
 import { hasBackgroundShell } from "../core/background-shell.js";
 import { MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, } from "../core/task-registry.js";
 const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its stdout as a stream of events.\n" +
@@ -11,8 +11,9 @@ const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its
     "- 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" +
-    "- Set persistent: true for a session-resident watch with no timeout; stop it with TaskStop(task_id) or it " +
-    "ends when the session is released.\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" +
     "- After starting a monitor you do not need to poll — end your turn if nothing else is pending; events will " +
     "reach you as notifications.\n" +
     "- Use this for logs, dev servers, build watchers, or any wait-for-a-condition loop (e.g. `tail -f app.log`, " +
@@ -44,14 +45,14 @@ export function createMonitorTool(env, opts) {
                 description: `How long the watch may run before it is killed, in milliseconds (default ${MONITOR_DEFAULT_TIMEOUT_MS}, max ${MONITOR_MAX_TIMEOUT_MS}). Ignored when persistent is true.`,
             })),
             persistent: Type.Optional(Type.Boolean({
-                description: "Set to true for a session-resident monitor with no timeout (default false). It keeps watching until you stop it with TaskStop or the session ends.",
+                description: "Set to true for a session-resident monitor with no watch timeout of its own (default false). It keeps watching until the execution environment's background time budget expires, until you stop it with TaskStop, or until the session ends.",
             })),
         }),
         effect: "write",
         execute: async (args, ctx) => {
             const { command, description, timeout_ms, persistent } = args;
             if (!hasBackgroundShell(env)) {
-                return "Error (Monitor): this environment does not support background processes.";
+                return errorResult("Error (Monitor): this environment does not support background processes.");
             }
             const isPersistent = persistent === true;
             const timeoutMs = Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.floor(timeout_ms ?? MONITOR_DEFAULT_TIMEOUT_MS)));
@@ -60,7 +61,7 @@ export function createMonitorTool(env, opts) {
                 ...(isPersistent ? {} : { timeout: Math.ceil(timeoutMs / 1000) + 5 }),
             });
             if (!spawn.ok)
-                return `Error (Monitor): ${spawn.error.message}`;
+                return errorResult(`Error (Monitor): ${spawn.error.message}`);
             const sessionScoped = isPersistent && opts.sessionId !== undefined;
             const owner = sessionScoped ? opts.sessionId : (ctx.taskId ?? opts.owner);
             const scope = ctx.principal ?? opts.scope;
@@ -85,10 +86,13 @@ export function createMonitorTool(env, opts) {
             }
             catch (e) {
                 await env.killBackground(spawn.value.shellId).catch(() => undefined);
-                return `Error (Monitor): the watch process was started but could not be registered (${e instanceof Error ? e.message : String(e)}); it has been terminated.`;
+                return errorResult(`Error (Monitor): the watch process was started but could not be registered (${e instanceof Error ? e.message : String(e)}); it has been terminated.`);
             }
+            const bgTimeout = env.backgroundCapabilities.defaultBgTimeoutSec;
             const lifetime = isPersistent
-                ? "It is persistent: no timeout — it runs until you stop it or the session ends."
+                ? typeof bgTimeout === "number"
+                    ? `It is persistent: no watch timeout of its own, but the execution environment kills background processes after ${bgTimeout}s; it runs until then, until you stop it, or until the session ends.`
+                    : "It is persistent: no watch timeout of its own, but the execution environment's background time budget still applies; it runs until then, until you stop it, or until the session ends."
                 : `It will be killed after ${timeoutMs}ms if still running.`;
             return onNotify !== undefined
                 ? `Monitoring in background; task_id=${taskId}. Each stdout line becomes a notification event (lines within ` +

package/dist/tools/scheduler-tools.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { defineTool } from "../core/tools.js";
+import { defineTool, errorResult } from "../core/tools.js";
 import { hasScheduler, isValidCronExpr, } from "../core/scheduler.js";
 export const SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup";
 export const AUTONOMOUS_LOOP_SENTINEL = "<<autonomous-loop>>";
@@ -210,33 +210,33 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
         execute: async (args) => {
             const a = args;
             if (a.schedule !== undefined && a.cron !== undefined) {
-                return "Error (CronCreate): pass exactly one of `schedule` (object form) or `cron` (string form), not both.";
+                return errorResult("Error (CronCreate): pass exactly one of `schedule` (object form) or `cron` (string form), not both.");
             }
             if (a.schedule === undefined && a.cron === undefined) {
-                return "Error (CronCreate): a schedule is required — pass `schedule` (kinds cron/at/delay) or the shorthand `cron` string.";
+                return errorResult("Error (CronCreate): a schedule is required — pass `schedule` (kinds cron/at/delay) or the shorthand `cron` string.");
             }
             if (a.prompt === undefined) {
-                return "Error (CronCreate): `prompt` is required — the task runs unattended, so it needs self-contained instructions.";
+                return errorResult("Error (CronCreate): `prompt` is required — the task runs unattended, so it needs self-contained instructions.");
             }
             const when = a.schedule ?? { kind: "cron", expr: a.cron };
             if (when.kind === "cron") {
                 if (!isValidCronExpr(when.expr)) {
-                    return `Error (CronCreate): invalid cron expression "${when.expr}" — only 5/6 space-separated cron fields (digits and * / , -) are allowed.`;
+                    return errorResult(`Error (CronCreate): invalid cron expression "${when.expr}" — only 5/6 space-separated cron fields (digits and * / , -) are allowed.`);
                 }
                 const deepErr = cronScheduleError(when.expr);
                 if (deepErr)
-                    return `Error (CronCreate): cron expression "${when.expr}" — ${deepErr}`;
+                    return errorResult(`Error (CronCreate): cron expression "${when.expr}" — ${deepErr}`);
             }
             else if (a.recurring !== undefined) {
-                return `Error (CronCreate): \`recurring\` only applies to cron schedules — "${when.kind}" fires once by nature; omit \`recurring\`.`;
+                return errorResult(`Error (CronCreate): \`recurring\` only applies to cron schedules — "${when.kind}" fires once by nature; omit \`recurring\`.`);
             }
             const durable = a.durable ?? a.schedule !== undefined;
             if (!durable) {
                 if (sched.schedulerCapabilities.supportsSessionLifetime !== true) {
-                    return "Error (CronCreate): this scheduler backend does not support session-scoped jobs (they could not be cleaned up when the session ends). Pass `durable: true` to schedule a persistent job instead.";
+                    return errorResult("Error (CronCreate): this scheduler backend does not support session-scoped jobs (they could not be cleaned up when the session ends). Pass `durable: true` to schedule a persistent job instead.");
                 }
                 if (ctx.sessionId === undefined) {
-                    return "Error (CronCreate): session-scoped jobs need a session to bind to, and this run has none. Pass `durable: true` to schedule a persistent job instead.";
+                    return errorResult("Error (CronCreate): session-scoped jobs need a session to bind to, and this run has none. Pass `durable: true` to schedule a persistent job instead.");
                 }
             }
             const intent = {
@@ -248,7 +248,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             };
             const r = await sched.schedule(intent, schedCtx);
             if (!r.ok)
-                return `Error (CronCreate): ${r.error.message}`;
+                return errorResult(`Error (CronCreate): ${r.error.message}`);
             const humanSchedule = when.kind === "cron"
                 ? cronToHuman(when.expr)
                 : when.kind === "delay"
@@ -278,7 +278,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             if (!r.ok) {
                 if (r.error.code === "not_found")
                     return `CronDelete: no scheduled task "${id}" (already gone or not yours).`;
-                return `Error (CronDelete): ${r.error.message}`;
+                return errorResult(`Error (CronDelete): ${r.error.message}`);
             }
             return { content: `Cancelled scheduled task ${id}.`, details: { type: "cron-delete", id } };
         },
@@ -292,7 +292,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
         execute: async () => {
             const r = await sched.list(schedCtx);
             if (!r.ok)
-                return `Error (CronList): ${r.error.message}`;
+                return errorResult(`Error (CronList): ${r.error.message}`);
             if (r.value.length === 0) {
                 return { content: "No scheduled tasks.", details: { type: "cron-list", jobs: [] } };
             }
@@ -367,7 +367,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             if (a.stop === true) {
                 const pending = await listPendingWakeups();
                 if ("err" in pending)
-                    return `Error (${SCHEDULE_WAKEUP_TOOL_NAME}): ${pending.err}`;
+                    return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): ${pending.err}`);
                 const cancelledWakeups = await cancelWakeups(pending.ids);
                 return {
                     content: `Loop stopped. Cancelled ${cancelledWakeups} pending wakeup(s); recurring cron tasks are unaffected.`,
@@ -375,10 +375,10 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
                 };
             }
             if (a.delaySeconds === undefined || a.reason === undefined || a.prompt === undefined) {
-                return `Error (${SCHEDULE_WAKEUP_TOOL_NAME}): delaySeconds, reason and prompt are required unless \`stop\` is true.`;
+                return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): delaySeconds, reason and prompt are required unless \`stop\` is true.`);
             }
             if (sched.schedulerCapabilities.supportsSessionWakeup === false) {
-                return `Error (${SCHEDULE_WAKEUP_TOOL_NAME}): this environment has no resident scheduler that can honor a session wakeup — the wakeup would never fire. Wait in the foreground instead, or start the work in a self-detaching form.`;
+                return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): this environment has no resident scheduler that can honor a session wakeup — the wakeup would never fire. Wait in the foreground instead, or start the work in a self-detaching form.`);
             }
             const clampedDelaySeconds = Math.min(3600, Math.max(60, Math.round(a.delaySeconds)));
             const wasClamped = clampedDelaySeconds !== a.delaySeconds;
@@ -387,7 +387,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
                 await cancelWakeups(pending.ids);
             const r = await sched.schedule({ prompt: a.prompt, when: { kind: "delay", delaySec: clampedDelaySeconds }, label: WAKEUP_LABEL, mode: "session-wakeup" }, schedCtx);
             if (!r.ok)
-                return `Error (${SCHEDULE_WAKEUP_TOOL_NAME}): ${r.error.message}`;
+                return errorResult(`Error (${SCHEDULE_WAKEUP_TOOL_NAME}): ${r.error.message}`);
             const scheduledFor = Date.now() + clampedDelaySeconds * 1000;
             const hhmmss = new Date(scheduledFor).toTimeString().slice(0, 8);
             const clampNote = wasClamped ? ` (clamped to ${clampedDelaySeconds}s from your requested value)` : "";