@sema-agent/core 2.3.0 → 2.5.0

package/dist/tools/fs/index.js

@@ -35,7 +35,10 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
     tools.push(createGrepTool(env, rootCanonical, additionalRoots), createGlobTool(env, rootCanonical, additionalRoots), createRepoMapTool(env, rootCanonical, additionalRoots));
     if (includeShell) {
         tools.push(readOnly
-            ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), opts.execClamp)
+            ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), opts.execClamp, {
+                ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
+                ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
+            })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
                 taskRegistry: opts.taskRegistry,
                 taskOwner: opts.taskOwner,
@@ -46,6 +49,9 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 execClamp: opts.execClamp,
                 ...(opts.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: opts.autoBackgroundOnTimeout } : {}),
                 ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
+                ...(additionalRoots !== undefined ? { additionalRoots } : {}),
+                ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
+                ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
             }));
         if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
             const sessionAxis = opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {};

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { resolveKey, violationText } from "./safety.js";
+import { resolveKey, violationText, violationDetails } from "./safety.js";
 import { buildIgnore, walk, walkIsPartial } from "./search.js";
 const DEFAULT_MAX_CHARS = 16_000;
 const DEFAULT_MAX_FILES = 400;
@@ -101,7 +101,7 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots) {
             if (a.path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, a.path, signal, rootCanonical, additionalRoots);
                 if (!r.ok)
-                    return errorResult(violationText("RepoMap", r.violation));
+                    return errorResult(violationText("RepoMap", r.violation), violationDetails(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

@@ -18,6 +18,8 @@ export declare function sha256(content: string): string;
 export interface FsViolation {
     code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid";
     partialView?: true;
+    target?: string;
+    roots?: readonly string[];
     message: string;
 }
 export declare function isBlockedDevicePath(key: string): boolean;
@@ -43,6 +45,14 @@ export declare function canonicalizeTarget(env: ExecutionEnv, path: string, sign
     unresolvedSymlink?: true;
 }>;
 export declare function violationText(toolName: string, v: FsViolation): string;
+export declare function violationDetails(v: FsViolation): {
+    type: "path_not_in_root";
+    code: "path_not_in_root";
+    target: string;
+    roots: readonly string[];
+} | undefined;
+export declare function withinAnyRoot(rootsCanonical: readonly string[], p: string): boolean;
+export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s) and the deployment permits it, use the Bash tool \u2014 it is not confined by this fence, though every call remains subject to the deployment's approval policy. Or ask for the directory to be added to additionalDirectories.)";
 export declare function requireRead(state: ReadFileState, key: string): FsViolation | undefined;
 export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused \u2014 read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";

package/dist/tools/fs/safety.js

@@ -175,7 +175,12 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
         const roots = [rootCanonical, ...(additionalRootsCanonical ?? [])];
         return {
             ok: false,
-            violation: { code: "path_not_in_root", message: `path "${path}" resolves outside the allowed root${roots.length > 1 ? "s" : ""} (${roots.join(", ")}); access denied` },
+            violation: {
+                code: "path_not_in_root",
+                message: `path "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}resolves outside the allowed root${roots.length > 1 ? "s" : ""} (${roots.join(", ")}); access denied. ${PATH_NOT_IN_ROOT_ESCAPE_HINT}`,
+                target: key,
+                roots,
+            },
         };
     }
     return { ok: true, key };
@@ -241,6 +246,15 @@ async function canonicalizeNewPath(env, abs, signal) {
 export function violationText(toolName, v) {
     return `Error (${toolName}): ${v.message}`;
 }
+export function violationDetails(v) {
+    return v.code === "path_not_in_root" && v.target !== undefined
+        ? { type: "path_not_in_root", code: "path_not_in_root", target: v.target, roots: v.roots ?? [] }
+        : undefined;
+}
+export function withinAnyRoot(rootsCanonical, p) {
+    return rootsCanonical.some((r) => within(r, p));
+}
+export const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s) and the deployment permits it, use the Bash tool — it is not confined by this fence, though every call remains subject to the deployment's approval policy. Or ask for the directory to be added to additionalDirectories.)";
 export function requireRead(state, key) {
     const entry = state.get(key);
     if (entry === undefined || entry.isPartialView) {

package/dist/tools/monitor.js

@@ -91,17 +91,31 @@ export function createMonitorTool(env, opts) {
                 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 wasClamped = timeout_ms !== undefined && timeout_ms !== timeoutMs;
+            const clampNote = !isPersistent && wasClamped ? ` (clamped to ${timeoutMs}ms from your requested ${timeout_ms}ms)` : "";
+            const timeoutIgnoredNote = isPersistent && timeout_ms !== undefined ? ` (the timeout_ms you passed is ignored because persistent is true)` : "";
             const lifetime = isPersistent
                 ? 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
+                    ? `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, 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${timeoutIgnoredNote}, 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${clampNote} if still running.`;
+            const content = onNotify !== undefined
                 ? `Monitoring in background; task_id=${taskId}. Each stdout line becomes a notification event (lines within ` +
                     `~200ms are batched); you'll get a final notification with the exit code when it ends — do not poll. ` +
                     `${lifetime} TaskOutput("${taskId}") reads the full spool (stdout+stderr); TaskStop("${taskId}") stops the watch.`
                 : `Monitoring in background; task_id=${taskId}. No notification channel is wired in this mount — read output with ` +
                     `TaskOutput("${taskId}") (re-readable spool, stdout+stderr) and stop with TaskStop("${taskId}"). ${lifetime}`;
+            return {
+                content,
+                details: {
+                    type: "monitor-start",
+                    taskId,
+                    persistent: isPersistent,
+                    ...(isPersistent
+                        ? { timeoutIgnored: timeout_ms !== undefined }
+                        : { timeoutMs, ...(timeout_ms !== undefined ? { requestedTimeoutMs: timeout_ms } : {}), wasClamped }),
+                },
+            };
         },
     });
 }

package/dist/tools/web.js

@@ -594,7 +594,7 @@ function classifySearchFailure(message) {
     if (code === 408 || /\btimed? ?out\b|\betimedout\b/.test(m)) {
         return { retryable: true, hint: "This looks like a timeout — a retry may succeed; a narrower query tends to return faster." };
     }
-    if (/\becconnrefused\b|\benotfound\b|\beai_again\b|\becconnreset\b|\bepipe\b|\bfetch failed\b|socket hang up|\bnetwork\b|\bdns\b/.test(m)) {
+    if (/\beconnrefused\b|\benotfound\b|\beai_again\b|\beconnreset\b|\bepipe\b|\bfetch failed\b|socket hang up|\bnetwork\b|\bdns\b/.test(m)) {
         return { retryable: true, hint: "This is a network/transport fault, not a rejection of the query — one retry is reasonable; if it repeats, treat the search backend as unavailable and continue without it." };
     }
     if (code !== undefined && code >= 500 && code <= 599) {
@@ -751,6 +751,7 @@ export function createWebSearchTool(config) {
             const domainFiltered = usable.filter((r) => webSearchResultAllowed(r.url, allowed_domains, blocked_domains));
             const droppedByDomain = usable.length - domainFiltered.length;
             const kept = domainFiltered.slice(0, max);
+            const droppedByMax = domainFiltered.length - kept.length;
             const schemeAssumed = kept.filter((r) => r.schemeAssumed).length;
             let clipped = false;
             const shown = kept.map((r) => {
@@ -771,6 +772,9 @@ export function createWebSearchTool(config) {
             const domainNote = droppedByDomain > 0
                 ? `\n\n[WebSearch: ${droppedByDomain} result(s) were dropped by the ${allowed_domains?.length ? "allowed_domains" : "blocked_domains"} filter passed with this call — the backend returned them, this tool removed them. Relax or drop the filter to see them.]`
                 : "";
+            const maxResultsNote = droppedByMax > 0
+                ? `\n\n[WebSearch: showing ${kept.length} of ${domainFiltered.length} results — the rest were cut off by this deployment's maxResults limit (${max}).]`
+                : "";
             const clipNote = clipped
                 ? "\n\n[WebSearch: one or more result fields exceeded the display limits and were truncated — treat the text above as an excerpt, not the backend's full result.]"
                 : "";
@@ -780,7 +784,7 @@ export function createWebSearchTool(config) {
             const tailReminder = shown.length > 0
                 ? "REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks."
                 : "REMINDER: this search returned ZERO usable sources — there is nothing above to cite. Do not fabricate sources, URLs or citations; tell the user the search returned no usable results (the notes above say why, when there is a why) and answer from what you already know, or try a different query.";
-            const modelText = `${fenced}${dropNote}${domainNote}${schemeNote}${clipNote}\n\n${tailReminder}`;
+            const modelText = `${fenced}${dropNote}${domainNote}${maxResultsNote}${schemeNote}${clipNote}\n\n${tailReminder}`;
             return {
                 content: modelText,
                 details: {

package/dist/tools/worktree.js

@@ -164,11 +164,14 @@ export function createWorktreeTools(env, opts) {
                 const originalCwd = previous ? previous.originalCwd : cwdRef.current;
                 session.current = { worktreeDir: target, originalCwd, baseSha: head.value.stdout.trim(), entered: true };
                 cwdRef.current = target;
-                return (`Switched into the existing worktree at ${target}${previous ? ` (the previous worktree at ${previous.worktreeDir} was left on disk, untouched)` : ""}. ` +
-                    "The session's working directory is now this worktree — subsequent commands and relative paths " +
-                    "operate there. Note this is a cwd switch, not a sandbox: file containment stays anchored at the " +
-                    "task root. ExitWorktree will restore the original directory but will NOT remove a worktree " +
-                    "entered via `path`.");
+                return {
+                    content: `Switched into the existing worktree at ${target}${previous ? ` (the previous worktree at ${previous.worktreeDir} was left on disk, untouched)` : ""}. ` +
+                        "The session's working directory is now this worktree — subsequent commands and relative paths " +
+                        "operate there. Note this is a cwd switch, not a sandbox: file containment stays anchored at the " +
+                        "task root. ExitWorktree will restore the original directory but will NOT remove a worktree " +
+                        "entered via `path`.",
+                    details: { type: "worktree", action: "enter", worktreeDir: target },
+                };
             }
             const base = await resolveBaseCommit(env, repoRoot, baseRef ?? "fresh");
             if ("error" in base)
@@ -195,11 +198,14 @@ export function createWorktreeTools(env, opts) {
                 baseSha: base.sha,
             };
             cwdRef.current = createdDir;
-            return (`Created worktree at ${createdDir} (base: ${base.label}${base.note ?? ""}). ` +
-                "The session's working directory is now the worktree — subsequent commands and relative paths " +
-                "operate there. Note this is a cwd switch, not a sandbox: file containment stays anchored at the " +
-                "task root, so the rest of the repository remains reachable. " +
-                "Use ExitWorktree to leave (an unchanged worktree is removed; a changed one is kept).");
+            return {
+                content: `Created worktree at ${createdDir} (base: ${base.label}${base.note ?? ""}). ` +
+                    "The session's working directory is now the worktree — subsequent commands and relative paths " +
+                    "operate there. Note this is a cwd switch, not a sandbox: file containment stays anchored at the " +
+                    "task root, so the rest of the repository remains reachable. " +
+                    "Use ExitWorktree to leave (an unchanged worktree is removed; a changed one is kept).",
+                details: { type: "worktree", action: "create", worktreeDir: createdDir, base: base.label },
+            };
         },
     });
     const exit = defineTool({
@@ -245,16 +251,22 @@ export function createWorktreeTools(env, opts) {
             cwdRef.current = restoredTo;
             if (active.entered) {
                 const discardNote = discardChanges === true ? " (`discardChanges` does not apply to a worktree this session did not create)" : "";
-                return (`Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
-                    `The worktree at ${active.worktreeDir} was entered via \`path\` (not created by this session) and ` +
-                    `was left on disk, untouched${discardNote}.`);
+                return {
+                    content: `Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
+                        `The worktree at ${active.worktreeDir} was entered via \`path\` (not created by this session) and ` +
+                        `was left on disk, untouched${discardNote}.`,
+                    details: { type: "worktree", action: "exit", worktreeDir: active.worktreeDir, kept: true },
+                };
             }
             const wtThere = await env.exists(active.worktreeDir);
             if (wtThere.ok && !wtThere.value) {
                 await pruneWorktrees(env, repoRoot).catch(() => undefined);
-                return (`Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
-                    `The worktree at ${active.worktreeDir} was already gone from disk (removed externally, not by this ` +
-                    "session — any uncommitted work in it is lost); stale git worktree metadata was pruned.");
+                return {
+                    content: `Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
+                        `The worktree at ${active.worktreeDir} was already gone from disk (removed externally, not by this ` +
+                        "session — any uncommitted work in it is lost); stale git worktree metadata was pruned.",
+                    details: { type: "worktree", action: "exit", worktreeDir: active.worktreeDir, kept: false },
+                };
             }
             let changed = true;
             let changeDetail = "could not verify the worktree state — keeping it to be safe";
@@ -278,10 +290,13 @@ export function createWorktreeTools(env, opts) {
                 const removeHint = wantsRemove && keep !== true
                     ? " To remove it anyway and permanently discard these changes, re-invoke with discard_changes: true."
                     : "";
-                return (`Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
-                    `The worktree was KEPT at ${active.worktreeDir} (${why}) — inspect or merge it there, and remove it ` +
-                    "later with `git worktree remove` if no longer needed." +
-                    removeHint);
+                return {
+                    content: `Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
+                        `The worktree was KEPT at ${active.worktreeDir} (${why}) — inspect or merge it there, and remove it ` +
+                        "later with `git worktree remove` if no longer needed." +
+                        removeHint,
+                    details: { type: "worktree", action: "exit", worktreeDir: active.worktreeDir, kept: true },
+                };
             }
             await env.exec(`git worktree remove --force ${shq(active.worktreeDir)}`, { cwd: repoRoot }).catch(() => undefined);
             await pruneWorktrees(env, repoRoot).catch(() => undefined);
@@ -291,12 +306,18 @@ export function createWorktreeTools(env, opts) {
                 : changeDetail;
             const stateClause = changed ? `had ${detailForDiscard} (discarded — discardChanges was set)` : "had no changes";
             if (stillThere.ok && stillThere.value) {
-                return (`Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
-                    `The worktree at ${active.worktreeDir} ${changed ? "was marked for discard" : "had no changes"} but could NOT be removed — it is still on disk; ` +
-                    "remove it manually with `git worktree remove --force` if no longer needed.");
+                return {
+                    content: `Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
+                        `The worktree at ${active.worktreeDir} ${changed ? "was marked for discard" : "had no changes"} but could NOT be removed — it is still on disk; ` +
+                        "remove it manually with `git worktree remove --force` if no longer needed.",
+                    details: { type: "worktree", action: "exit", worktreeDir: active.worktreeDir, kept: true },
+                };
             }
-            return (`Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
-                `The worktree at ${active.worktreeDir} ${stateClause} and was removed.`);
+            return {
+                content: `Exited the worktree session; working directory restored to ${restoredTo}${restoreNote}. ` +
+                    `The worktree at ${active.worktreeDir} ${stateClause} and was removed.`,
+                details: { type: "worktree", action: "exit", worktreeDir: active.worktreeDir, kept: false },
+            };
         },
     });
     return [enter, exit];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",