@sema-agent/core 1.451.0 → 2.0.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/pdf.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionEnv } from "../../internal/harness.js";
+import type { ExecutionEnv } from "../../internal/harness-types.js";
 export declare const PDF_MAX_PAGES_PER_READ = 20;
 export declare const PDF_INLINE_PAGE_THRESHOLD = 10;
 export declare const PDF_TARGET_RAW_SIZE: number;

package/dist/tools/fs/repo-map.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool } from "../../internal/harness.js";
-import type { ExecutionEnv } from "../../internal/harness.js";
+import type { AgentTool } from "../../internal/harness-types.js";
+import type { ExecutionEnv } from "../../internal/harness-types.js";
 export declare function extractSymbols(text: string): string[];
-export declare function makeRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
+export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;

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;
@@ -79,7 +79,7 @@ function rankEntries(a, b) {
         return b.symbols.length - a.symbols.length;
     return a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0;
 }
-export function makeRepoMapTool(env, rootCanonical, additionalRoots) {
+export function createRepoMapTool(env, rootCanonical, additionalRoots) {
     return defineTool({
         name: "RepoMap",
         contract: { contractId: "core.repo_map@1", implementationRevision: "1" },
@@ -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/safety.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionEnv } from "../../internal/harness.js";
+import type { ExecutionEnv } from "../../internal/harness-types.js";
 export declare function fileArgPath(args: unknown): string | undefined;
 export declare function writeTargetPath(canonicalName: string, args: unknown): string | undefined;
 export interface ReadEntry {

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

@@ -1,4 +1,4 @@
-import type { ExecutionEnv } from "../../internal/harness.js";
+import type { ExecutionEnv } from "../../internal/harness-types.js";
 export declare const DEFAULT_IGNORE_DIRS: ReadonlySet<string>;
 export interface GrepParams {
     pattern: string;

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.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, ExecutionEnv } from "../internal/harness.js";
+import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
 import { type MonitorTimers, type TaskRegistry } from "../core/task-registry.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 export interface MonitorToolOptions {

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.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, ExecutionEnv } from "../internal/harness.js";
+import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
 export declare const SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup";
 export declare const AUTONOMOUS_LOOP_SENTINEL = "<<autonomous-loop>>";
 export declare const AUTONOMOUS_LOOP_DYNAMIC_SENTINEL = "<<autonomous-loop-dynamic>>";