@sema-agent/core 5.17.0-pre.0 → 5.18.0

package/dist/tools/fs/fs-shared.d.ts

@@ -14,6 +14,9 @@ export declare function decodeEditBytes(bytes: Uint8Array, path: string): {
     ok: false;
     message: string;
 };
+export declare function tooLargeToEditMessage(path: string, bytes: number): string;
+export declare function truncatedUtf16BodyMessage(tool: string, path: string): string;
+export declare const BASH_READONLY_CONFINEMENT_NOTE = "bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.";
 export declare function persistedTextOf(encoded: string | Uint8Array): string;
 export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: Pick<FsViolation, "code" | "message" | "partialView">, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
 export declare const MAX_IMAGE_READ_BYTES: number;
@@ -27,6 +30,17 @@ export declare const BASH_DEFAULT_TIMEOUT_SEC = 120;
 export declare const BASH_MAX_TIMEOUT_SEC = 600;
 export declare const BASH_DEFAULT_TIMEOUT_MS: number;
 export declare const BASH_MAX_TIMEOUT_MS: number;
+export declare const MIN_BASH_TIMEOUT_MS = 1000;
+export declare const BASH_TIMEOUT_PLATEAU_END_MS = 1500;
+export declare function envErrorDetail(message: string | undefined): string;
+export declare function bashTimeoutParamDescription(caps: {
+    defaultMs: number;
+    maxMs: number;
+}, withDefault: boolean): string;
+export declare function bashTimeoutArgRefusal(timeoutMs: number | undefined, caps: {
+    defaultMs: number;
+    maxMs: number;
+}): string | undefined;
 export declare function resolveBashTimeoutCaps(opts?: {
     bashDefaultTimeoutMs?: number;
     bashMaxTimeoutMs?: number;
@@ -34,6 +48,7 @@ export declare function resolveBashTimeoutCaps(opts?: {
     defaultMs: number;
     maxMs: number;
 };
+export declare function __resetBashTimeoutAnnouncements(): void;
 export declare function bashTimeoutCapsSec(caps: {
     defaultMs: number;
     maxMs: number;

package/dist/tools/fs/fs-shared.js

@@ -24,9 +24,16 @@ export function decodeEditBytes(bytes, path) {
         return { ok: true, value: decodeTextBytes(bytes) };
     }
     catch {
-        return { ok: false, message: `Error (Edit): "${path}" is too large to edit (${formatByteSize(bytes.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.` };
+        return { ok: false, message: tooLargeToEditMessage(path, bytes.byteLength) };
     }
 }
+export function tooLargeToEditMessage(path, bytes) {
+    return `Error (Edit): "${path}" is too large to edit (${formatByteSize(bytes)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`;
+}
+export function truncatedUtf16BodyMessage(tool, path) {
+    return `Error (${tool}): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`;
+}
+export const BASH_READONLY_CONFINEMENT_NOTE = "bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.";
 export function persistedTextOf(encoded) {
     return decodeTextBytes(typeof encoded === "string" ? Buffer.from(encoded, "utf8") : encoded).text;
 }
@@ -52,19 +59,83 @@ export const BASH_DEFAULT_TIMEOUT_SEC = 120;
 export const BASH_MAX_TIMEOUT_SEC = 600;
 export const BASH_DEFAULT_TIMEOUT_MS = BASH_DEFAULT_TIMEOUT_SEC * 1000;
 export const BASH_MAX_TIMEOUT_MS = BASH_MAX_TIMEOUT_SEC * 1000;
+export const MIN_BASH_TIMEOUT_MS = 1000;
+export const BASH_TIMEOUT_PLATEAU_END_MS = 1500;
+function bashTimeoutDefect(ms) {
+    if (!Number.isFinite(ms))
+        return "must be a finite number of milliseconds";
+    if (ms <= 0)
+        return `must be a positive number of milliseconds (received ${ms})`;
+    if (ms < MIN_BASH_TIMEOUT_MS) {
+        return (`is in MILLISECONDS and ${ms} is under one second — if ${ms} seconds was meant, the value is ` +
+            `${ms * 1000}. Values below ${MIN_BASH_TIMEOUT_MS}ms all collapse to the same one-second budget`);
+    }
+    if (ms > MIN_BASH_TIMEOUT_MS && ms < BASH_TIMEOUT_PLATEAU_END_MS) {
+        return (`is ${ms}ms, which rounds down to the same one-second budget as ${MIN_BASH_TIMEOUT_MS}ms — the ` +
+            `shell's granularity is whole seconds, so write ${MIN_BASH_TIMEOUT_MS} for one second or at least ` +
+            `${BASH_TIMEOUT_PLATEAU_END_MS} for two`);
+    }
+    return undefined;
+}
 function validTimeoutMs(n) {
     if (n === undefined || !Number.isFinite(n))
         return undefined;
     const floored = Math.floor(n);
-    return floored >= 1 ? floored : undefined;
+    return bashTimeoutDefect(floored) === undefined ? floored : undefined;
+}
+export function envErrorDetail(message) {
+    const trimmed = (message ?? "").trim();
+    return trimmed === "" ? "the execution environment reported no reason" : trimmed;
+}
+const announcedTimeoutConfig = new Set();
+function announceDiscardedTimeout(knob, raw, usedMs) {
+    if (!Number.isFinite(raw) || raw <= 0)
+        return;
+    const defect = bashTimeoutDefect(Math.floor(raw));
+    if (defect === undefined)
+        return;
+    const line = `${knob}=${raw} was ignored — it ${defect}. Using ${usedMs}ms instead.`;
+    if (announcedTimeoutConfig.has(line))
+        return;
+    announcedTimeoutConfig.add(line);
+    console.warn(line);
+}
+export function bashTimeoutParamDescription(caps, withDefault) {
+    const bounds = `${withDefault ? `default ${caps.defaultMs}, ` : ""}min ${MIN_BASH_TIMEOUT_MS}, max ${caps.maxMs}`;
+    const escape = caps.maxMs >= BASH_TIMEOUT_PLATEAU_END_MS
+        ? ` — pass exactly ${MIN_BASH_TIMEOUT_MS} for one second, or ${BASH_TIMEOUT_PLATEAU_END_MS}+ for longer`
+        : ` — ${MIN_BASH_TIMEOUT_MS} is the only value this deployment accepts below its ${caps.maxMs}ms ceiling`;
+    return (`Timeout in milliseconds (${bounds}). The shell's granularity is whole seconds, so ${MIN_BASH_TIMEOUT_MS} is the ` +
+        `smallest accepted value and anything between ${MIN_BASH_TIMEOUT_MS} and ${BASH_TIMEOUT_PLATEAU_END_MS} is REJECTED ` +
+        `(it would round back down to ${MIN_BASH_TIMEOUT_MS})${escape}. Requests above the max are capped to it.`);
+}
+export function bashTimeoutArgRefusal(timeoutMs, caps) {
+    if (timeoutMs === undefined)
+        return undefined;
+    const defect = bashTimeoutDefect(timeoutMs);
+    if (defect === undefined)
+        return undefined;
+    return (`Error (Bash): \`timeout\` ${defect}. The command was NOT run. Omit \`timeout\` to use the default ` +
+        `budget of ${caps.defaultMs}ms (maximum ${caps.maxMs}ms).`);
 }
 export function resolveBashTimeoutCaps(opts) {
     const defaultMs = validTimeoutMs(opts?.bashDefaultTimeoutMs) ??
         validTimeoutMs(Number(process.env.BASH_DEFAULT_TIMEOUT_MS)) ??
         BASH_DEFAULT_TIMEOUT_MS;
     const maxMs = Math.max(validTimeoutMs(opts?.bashMaxTimeoutMs) ?? validTimeoutMs(Number(process.env.BASH_MAX_TIMEOUT_MS)) ?? BASH_MAX_TIMEOUT_MS, defaultMs);
+    if (opts?.bashDefaultTimeoutMs !== undefined)
+        announceDiscardedTimeout("bashDefaultTimeoutMs", opts.bashDefaultTimeoutMs, defaultMs);
+    else if (process.env.BASH_DEFAULT_TIMEOUT_MS !== undefined)
+        announceDiscardedTimeout("BASH_DEFAULT_TIMEOUT_MS", Number(process.env.BASH_DEFAULT_TIMEOUT_MS), defaultMs);
+    if (opts?.bashMaxTimeoutMs !== undefined)
+        announceDiscardedTimeout("bashMaxTimeoutMs", opts.bashMaxTimeoutMs, maxMs);
+    else if (process.env.BASH_MAX_TIMEOUT_MS !== undefined)
+        announceDiscardedTimeout("BASH_MAX_TIMEOUT_MS", Number(process.env.BASH_MAX_TIMEOUT_MS), maxMs);
     return { defaultMs, maxMs };
 }
+export function __resetBashTimeoutAnnouncements() {
+    announcedTimeoutConfig.clear();
+}
 export function bashTimeoutCapsSec(caps) {
     return { defaultSec: Math.max(1, Math.round(caps.defaultMs / 1000)), maxSec: Math.max(1, Math.round(caps.maxMs / 1000)) };
 }

package/dist/tools/fs/fs-write.js

@@ -3,7 +3,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
-import { MAX_EDIT_BYTES, formatByteSize, decodeEditBytes, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
+import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
 async function gateToolWrite(hook, tool, path, key, content) {
     if (hook === undefined)
         return undefined;
@@ -91,21 +91,21 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             }
             const editInfo = await env.fileInfo(r.key, ctx.signal);
             if (editInfo.ok && editInfo.value.size > MAX_EDIT_BYTES) {
-                return errorResult(`Error (Edit): "${path}" is too large to edit (${formatByteSize(editInfo.value.size)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`);
+                return errorResult(tooLargeToEditMessage(path, editInfo.value.size));
             }
             if (singleOld === "") {
                 const preBin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!preBin.ok)
                     return errorResult(`Error (Edit): cannot read "${path}": ${preBin.error.message}`);
                 if (preBin.value.byteLength > MAX_EDIT_BYTES) {
-                    return errorResult(`Error (Edit): "${path}" is too large to edit (${formatByteSize(preBin.value.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`);
+                    return errorResult(tooLargeToEditMessage(path, preBin.value.byteLength));
                 }
                 const preDecResult = decodeEditBytes(preBin.value, path);
                 if (!preDecResult.ok)
                     return errorResult(preDecResult.message);
                 const preDec = preDecResult.value;
                 if (preDec.malformed)
-                    return errorResult(`Error (Edit): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
+                    return errorResult(truncatedUtf16BodyMessage("Edit", path));
                 if (preDec.text.trim() !== "")
                     return errorResult(`Error (Edit): Cannot create new file - file already exists.`);
                 const priorRead = state.get(r.key);
@@ -141,14 +141,14 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             if (!readBin.ok)
                 return errorResult(`Error (Edit): cannot read "${path}": ${readBin.error.message}`);
             if (readBin.value.byteLength > MAX_EDIT_BYTES) {
-                return errorResult(`Error (Edit): "${path}" is too large to edit (${formatByteSize(readBin.value.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`);
+                return errorResult(tooLargeToEditMessage(path, readBin.value.byteLength));
             }
             const decodedResult = decodeEditBytes(readBin.value, path);
             if (!decodedResult.ok)
                 return errorResult(decodedResult.message);
             const decoded = decodedResult.value;
             if (decoded.malformed)
-                return errorResult(`Error (Edit): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
+                return errorResult(truncatedUtf16BodyMessage("Edit", path));
             const original = decoded.text;
             const entry = state.get(r.key);
             const readWasTruncated = entry?.truncated === true;
@@ -256,7 +256,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                     return errorResult(`Error (Write): cannot re-read "${path}" to verify it is unchanged: ${readBin.error.message}`);
                 const decodedPrev = decodeTextBytes(readBin.value);
                 if (decodedPrev.malformed)
-                    return errorResult(`Error (Write): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
+                    return errorResult(truncatedUtf16BodyMessage("Write", path));
                 const stale = checkStale(state.get(r.key), sha256(decodedPrev.text));
                 if (stale)
                     return errorResult(violationText("Write", stale));
@@ -340,7 +340,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return errorResult(`Error (NotebookEdit): cannot read "${notebook_path}": ${readBin.error.message}`);
             const decodedNb = decodeTextBytes(readBin.value);
             if (decodedNb.malformed)
-                return errorResult(`Error (NotebookEdit): "${notebook_path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
+                return errorResult(truncatedUtf16BodyMessage("NotebookEdit", notebook_path));
             const nbText = decodedNb.text;
             const stale = checkStale(state.get(r.key), sha256(nbText));
             if (stale)

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

@@ -34,6 +34,7 @@ export interface HandsToolkitOptions {
     autoBackgroundOnTimeout?: boolean;
     readImageDownsampler?: ReadImageDownsamplerOption;
     pdfModelCapabilities?: PdfModelCapabilities;
+    readCyberReminder?: boolean;
     beforeWrite?: BeforeWriteHook;
     monitorToolActive?: boolean;
 }

package/dist/tools/fs/index.js

@@ -30,7 +30,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
         }, env);
     const tools = [
-        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption),
+        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder),
     ];
     if (!readOnly) {
         tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite));

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

@@ -82,4 +82,5 @@ export declare function escapeMatchWasAttempted(oldString: string): boolean;
 export declare const ESCAPE_MATCH_MISS_NOTE = "\n(note: Edit also tried swapping \\uXXXX escapes and their characters; neither form matched, so the mismatch is likely elsewhere in old_string. Re-read the file and copy the exact surrounding text.)";
 export declare function adaptNewStringQuotes(matchedOld: string, newString: string): string;
 export declare function deletionOldString(content: string, oldString: string, newString: string): string;
+export declare const EDIT_ECHO_MAX_CHARS = 200;
 export declare function checkEditMatch(content: string, oldString: string, replaceAll: boolean, truncated: boolean): FsViolation | undefined;

package/dist/tools/fs/safety.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 export function fileArgPath(args) {
     const a = args;
     const fp = a?.file_path;
@@ -577,6 +578,12 @@ export function deletionOldString(content, oldString, newString) {
         return oldString + "\n";
     return oldString;
 }
+export const EDIT_ECHO_MAX_CHARS = 200;
+function boundEditEcho(oldString) {
+    if (oldString.length <= EDIT_ECHO_MAX_CHARS)
+        return oldString;
+    return `${sliceHeadSafe(oldString, EDIT_ECHO_MAX_CHARS)}… (truncated)`;
+}
 export function checkEditMatch(content, oldString, replaceAll, truncated) {
     if (oldString === "") {
         return { code: "invalid", message: "old_string must not be empty." };
@@ -585,13 +592,13 @@ export function checkEditMatch(content, oldString, replaceAll, truncated) {
     if (n === 0) {
         return {
             code: "ambiguous_edit",
-            message: `String to replace not found in file.${truncated ? " (note: the read was truncated — it may be in the unshown portion)" : ""}\nString: ${oldString}`,
+            message: `String to replace not found in file.${truncated ? " (note: the read was truncated — it may be in the unshown portion)" : ""}\nString: ${boundEditEcho(oldString)}`,
         };
     }
     if (n > 1 && !replaceAll) {
         return {
             code: "ambiguous_edit",
-            message: `Found ${n} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.${truncated ? " (the read was truncated; some matches may be in the unshown portion)" : ""}\nString: ${oldString}`,
+            message: `Found ${n} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.${truncated ? " (the read was truncated; some matches may be in the unshown portion)" : ""}\nString: ${boundEditEcho(oldString)}`,
         };
     }
     return undefined;

package/dist/tools/web.js

@@ -251,6 +251,7 @@ export function webFetchToolSpec(config = {}) {
                 : {}),
         }),
         effect: "read",
+        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { url, prompt } = args;
             const startedAt = Date.now();
@@ -811,6 +812,7 @@ export function createWebSearchTool(config) {
             blocked_domains: Type.Optional(Type.Array(Type.String(), { description: "Never include search results from these domains" })),
         }),
         effect: "read",
+        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { query, allowed_domains, blocked_domains } = args;
             const startedAt = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.17.0-pre.0",
+  "version": "5.18.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",