@sema-agent/core 5.18.1 → 5.20.0

package/dist/index.js

@@ -116,7 +116,7 @@ export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmitti
 export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, } from "./core/permission-rule-store.js";
 export { prepareCardApproval, confirmRuleApproval, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
-export { formatHookFeedback, runToolGate, createHookEnvCapabilities, } from "./core/hooks.js";
+export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, } from "./core/memory.js";
 export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, migrateScope, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, syncMemoryScope, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, } from "./core/shared-memory/types.js";

package/dist/orchestration/run-spec.js

@@ -26,7 +26,7 @@ function frozenDenyPolicy(rootDir, frozenResolved) {
             if (typeof raw !== "string" || raw.length === 0)
                 return { action: "allow" };
             const absForm = isAbsolutePathForm(raw);
-            const abs = pathKey(absForm ? raw : resolve(rootDir, raw));
+            const abs = pathKey(absForm ? raw : resolve(req.cwd || rootDir, raw));
             if (frozen.has(abs)) {
                 return { action: "deny", message: `${raw} is part of the frozen specification surface (read-only).` };
             }
@@ -102,6 +102,9 @@ export async function runSpec(runner, contract, opts) {
     const userHooks = opts.taskSpec.hooks && deployBaseline?.hooks
         ? {
             preToolUse: (opts.taskSpec.hooks.preToolUse ?? deployBaseline.hooks.preToolUse)?.bind(opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
+            ...((opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks).preToolUseObservational === true
+                ? { preToolUseObservational: true }
+                : {}),
             postToolUse: (opts.taskSpec.hooks.postToolUse ?? deployBaseline.hooks.postToolUse)?.bind(opts.taskSpec.hooks.postToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
             userPromptSubmit: (opts.taskSpec.hooks.userPromptSubmit ?? deployBaseline.hooks.userPromptSubmit)?.bind(opts.taskSpec.hooks.userPromptSubmit ? opts.taskSpec.hooks : deployBaseline.hooks),
             stop: (opts.taskSpec.hooks.stop ?? deployBaseline.hooks.stop)?.bind(opts.taskSpec.hooks.stop ? opts.taskSpec.hooks : deployBaseline.hooks),
@@ -118,6 +121,7 @@ export async function runSpec(runner, contract, opts) {
     let gateAbandoned = false;
     const hooks = {
         ...(userHooks?.preToolUse && { preToolUse: userHooks.preToolUse.bind(userHooks) }),
+        ...(userHooks?.preToolUse && userHooks.preToolUseObservational === true ? { preToolUseObservational: true } : {}),
         ...(userHooks?.postToolUse && { postToolUse: userHooks.postToolUse.bind(userHooks) }),
         ...(userHooks?.userPromptSubmit && { userPromptSubmit: userHooks.userPromptSubmit.bind(userHooks) }),
         ...(userHooks?.postToolUseFailure && { postToolUseFailure: userHooks.postToolUseFailure.bind(userHooks) }),

package/dist/orchestration/workflow.js

@@ -245,6 +245,7 @@ function normalizeConcurrency(c) {
     }
     return Math.floor(c);
 }
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function normalizeWorkflowHardCap(name, v) {
     if (v === undefined)
         return undefined;
@@ -253,12 +254,22 @@ function normalizeWorkflowHardCap(name, v) {
     }
     return v;
 }
+function normalizeWorkflowTimerCap(name, v) {
+    const normalized = normalizeWorkflowHardCap(name, v);
+    if (normalized !== undefined && normalized > MAX_TIMER_DELAY_MS) {
+        throw new Error(`runWorkflow: ${name} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) (got ${v}) — a host timer truncates a larger delay and fires immediately, cancelling the run at once. Omit it for no deadline.`);
+    }
+    return normalized;
+}
 function normalizeWorkflowStallMs(v) {
     if (v === undefined)
         return WORKFLOW_AGENT_STALL_MS;
     if (!Number.isFinite(v)) {
         throw new Error(`runWorkflow: stallMs must be a finite number of milliseconds (got ${v}); 0 or a negative value is the documented explicit "off", not NaN/Infinity`);
     }
+    if (v > MAX_TIMER_DELAY_MS) {
+        throw new Error(`runWorkflow: stallMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) (got ${v}) — a host timer truncates a larger delay and fires immediately, so a watchdog stretched that far would trip on every agent instead of tolerating a long one. Pass 0 to turn it off.`);
+    }
     return v;
 }
 function createSemaphore(max) {
@@ -346,10 +357,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     const maxAgents = normalizeWorkflowHardCap("maxAgents", opts.maxAgents);
     const maxLogChars = normalizeWorkflowHardCap("maxLogChars", opts.maxLogChars);
     const maxResultChars = normalizeWorkflowHardCap("maxResultChars", opts.maxResultChars);
-    const totalTimeoutMs = normalizeWorkflowHardCap("totalTimeoutMs", opts.totalTimeoutMs);
+    const totalTimeoutMs = normalizeWorkflowTimerCap("totalTimeoutMs", opts.totalTimeoutMs);
     const stallMs = normalizeWorkflowStallMs(opts.stallMs);
     const agentMaxRetries = normalizeWorkflowHardCap("agentMaxRetries", opts.agentMaxRetries) ?? WORKFLOW_AGENT_MAX_RETRIES;
-    const throttleBackoffMs = normalizeWorkflowHardCap("throttleBackoffMs", opts.throttleBackoffMs) ?? WORKFLOW_AGENT_THROTTLE_BACKOFF_MS;
+    const throttleBackoffMs = normalizeWorkflowTimerCap("throttleBackoffMs", opts.throttleBackoffMs) ?? WORKFLOW_AGENT_THROTTLE_BACKOFF_MS;
     const timers = opts.timers ?? REAL_WORKFLOW_TIMERS;
     const cancelController = new AbortController();
     const timeoutController = totalTimeoutMs !== undefined ? new AbortController() : undefined;

package/dist/stores/file/background-agent-store.js

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, queryBackgroundAgents, } from "../../core/background-agent-store.js";
+import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, assertBackgroundAgentReapOptions, queryBackgroundAgents, } from "../../core/background-agent-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 const agentLedgers = new SharedLedgerTable({
     keyOf: (r) => FileBackgroundAgentStore.key(r.handle, r.scope),
@@ -113,6 +113,7 @@ export class FileBackgroundAgentStore {
         });
     }
     async reap(scope, now, opts) {
+        assertBackgroundAgentReapOptions(opts);
         if (!opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined))
             return 0;
         const changed = new Set();

package/dist/stores/file/mailbox-store.js

@@ -1,4 +1,5 @@
 import { join, resolve, sep } from "node:path";
+import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { newestSentAt, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
@@ -176,6 +177,7 @@ export class FileMailboxStore {
         });
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("MailboxStore.reap", opts);
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;

package/dist/stores/file/workflow-run-store.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { WorkflowRunStoreError, isTerminalWorkflowStatus, nextWorkflowRunOnUpdate, queryWorkflowRuns, } from "../../core/workflow-run-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 const runLedgers = new SharedLedgerTable({
@@ -64,6 +65,7 @@ export class FileWorkflowRunStore {
         return queryWorkflowRuns(this.runs.values(), scope, opts);
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("WorkflowRunStore.reap", opts);
         if (opts?.maxAgeMs === undefined && opts?.keep === undefined)
             return 0;
         const terminal = [...this.runs.values()].filter((r) => r.scope === scope && isTerminalWorkflowStatus(r.status));

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -1,11 +1,14 @@
 export declare const NOT_AUTO_ALLOWED = "\u2014 not auto-allowed";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
-export declare function parseLeadingCommandName(command: string): {
+export interface LeadingCommandNameOptions {
+    quotedOperatorsAreText?: boolean;
+}
+export declare function parseLeadingCommandName(command: string, options?: LeadingCommandNameOptions): {
     name: string;
 } | {
     reject: string;
 };
-export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>): string | undefined;
+export declare function coarseReadonlyCheck(command: string, allow: ReadonlySet<string>, options?: LeadingCommandNameOptions): string | undefined;
 export interface BashReadonlyRootBoundary {
     roots: readonly string[];
     cwd?: string;

package/dist/tools/fs/bash-readonly-classifier.js

@@ -5,11 +5,41 @@ export const BASH_READONLY_DEFAULT_ALLOW = [
     "grep", "cut", "tr", "basename", "dirname", "stat", "du", "df", "which",
 ];
 const SHELL_OPERATORS = /[;&|<>$()`\n\r\\]/;
-export function parseLeadingCommandName(command) {
+function quoteMask(s) {
+    const quoted = new Array(s.length).fill(false);
+    let open;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (open === undefined && (ch === '"' || ch === "'")) {
+            open = ch;
+            quoted[i] = true;
+            continue;
+        }
+        if (open !== undefined) {
+            quoted[i] = true;
+            if (open === ch)
+                open = undefined;
+        }
+    }
+    return { quoted, balanced: open === undefined };
+}
+function hasBareShellOperator(s, quotedOperatorsAreText) {
+    if (!quotedOperatorsAreText)
+        return SHELL_OPERATORS.test(s);
+    const mask = quoteMask(s);
+    if (!mask.balanced)
+        return SHELL_OPERATORS.test(s);
+    for (let i = 0; i < s.length; i++) {
+        if (!mask.quoted[i] && SHELL_OPERATORS.test(s[i]))
+            return true;
+    }
+    return false;
+}
+export function parseLeadingCommandName(command, options) {
     const trimmed = command.trim();
     if (!trimmed)
         return { reject: "empty command" };
-    if (SHELL_OPERATORS.test(trimmed)) {
+    if (hasBareShellOperator(trimmed, options?.quotedOperatorsAreText === true)) {
         return {
             reject: "shell operators (pipes, redirects, ;, &&, command substitution, subshells, variable expansion) are not allowed — run a single simple command",
         };
@@ -23,8 +53,8 @@ export function parseLeadingCommandName(command) {
         return { reject: "the command name must be a bare token (no quotes, braces, globs, or ~)" };
     return { name: first };
 }
-export function coarseReadonlyCheck(command, allow) {
-    const parsed = parseLeadingCommandName(command);
+export function coarseReadonlyCheck(command, allow, options) {
+    const parsed = parseLeadingCommandName(command, options);
     if ("reject" in parsed)
         return parsed.reject;
     if (!allow.has(parsed.name))
@@ -32,6 +62,35 @@ export function coarseReadonlyCheck(command, allow) {
     return undefined;
 }
 const SHELL_SEGMENT_HARD_REJECT = /[<>$()`\n\r\\]/;
+const EXEMPT_REDIRECTION = /^(?:2>\/dev\/null|[12]?>&[12])$/;
+function stripExemptRedirections(command) {
+    if (!command.includes(">"))
+        return command;
+    const mask = quoteMask(command);
+    if (!mask.balanced)
+        return command;
+    let out = "";
+    let word = "";
+    let wordQuoted = false;
+    const flush = () => {
+        out += wordQuoted || !EXEMPT_REDIRECTION.test(word) ? word : "";
+        word = "";
+        wordQuoted = false;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (!mask.quoted[i] && (ch === " " || ch === "\t")) {
+            flush();
+            out += ch;
+            continue;
+        }
+        if (mask.quoted[i])
+            wordQuoted = true;
+        word += ch;
+    }
+    flush();
+    return out;
+}
 function foldQuoteRemovalToken(tok) {
     if (!tok.includes('"') && !tok.includes("'"))
         return tok;
@@ -77,12 +136,30 @@ function resolveOperandLexically(base, operand, homeDir) {
     return normalizeAbsPathLexically(`${base.replace(/[/\\]+$/, "")}/${raw}`);
 }
 function tokenizeSegment(segment) {
-    const raw = segment
-        .trim()
-        .split(/\s+/)
-        .filter((t) => t.length > 0);
+    const raw = splitWordsQuoteAware(segment);
     return { folded: raw.map(foldQuoteRemovalToken), raw };
 }
+function splitWordsQuoteAware(segment) {
+    const s = segment.trim();
+    const mask = quoteMask(s);
+    if (!mask.balanced)
+        return s.split(/\s+/).filter((t) => t.length > 0);
+    const out = [];
+    let cur = "";
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (!mask.quoted[i] && /\s/.test(ch)) {
+            if (cur.length > 0)
+                out.push(cur);
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.length > 0)
+        out.push(cur);
+    return out;
+}
 function hasUnquotedExpansionMetachar(rawToken) {
     let open;
     for (const ch of rawToken) {
@@ -147,6 +224,26 @@ function isCutDelimiterPayloadLongOption(tok) {
     const name = longOptionNameOf(tok);
     return name !== undefined && (isLongOptionAbbrevOf(name, "delimiter") || isLongOptionAbbrevOf(name, "output-delimiter"));
 }
+function isGrepClusterFileStdin(tok) {
+    if (tok.startsWith("--") || !/^-[A-Za-z0-9]/.test(tok))
+        return false;
+    for (let i = 1; i < tok.length; i++) {
+        const ch = tok[i];
+        if (ch === "e")
+            return false;
+        if (ch === "f")
+            return tok.slice(i + 1) === "-";
+        if (!/[A-Za-z0-9]/.test(ch))
+            return false;
+    }
+    return false;
+}
+function isCutSeparatedDelimiterOption(tok) {
+    if (tok.includes("="))
+        return false;
+    const name = longOptionNameOf(tok);
+    return name !== undefined && (isLongOptionAbbrevOf(name, "delimiter") || isLongOptionAbbrevOf(name, "output-delimiter"));
+}
 function isGrepFileStdinLongOption(tok) {
     const eq = tok.indexOf("=");
     if (eq < 0 || tok.slice(eq + 1) !== "-")
@@ -285,16 +382,22 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     const trimmed = command.trim();
     if (!trimmed)
         return { reason: "empty command" };
-    if (SHELL_SEGMENT_HARD_REJECT.test(trimmed)) {
+    const redirectionStripped = stripExemptRedirections(trimmed);
+    if (SHELL_SEGMENT_HARD_REJECT.test(redirectionStripped)) {
         return { reason: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
     }
-    const source = trimmed.endsWith(";") ? trimmed.slice(0, -1) : trimmed;
+    const source = redirectionStripped.endsWith(";") ? redirectionStripped.slice(0, -1) : redirectionStripped;
     const segments = [];
     const pipeFed = [false];
+    const mask = quoteMask(source);
+    const quoted = (i) => mask.balanced && mask.quoted[i] === true;
     let cur = "";
     for (let i = 0; i < source.length; i++) {
         const c = source[i];
-        if (c === "&") {
+        if (quoted(i)) {
+            cur += c;
+        }
+        else if (c === "&") {
             if (source[i + 1] === "&") {
                 segments.push(cur);
                 cur = "";
@@ -327,7 +430,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
     }
     segments.push(cur);
     for (const segment of segments) {
-        const reason = coarseReadonlyCheck(segment, allow);
+        const reason = coarseReadonlyCheck(segment, allow, { quotedOperatorsAreText: true });
         if (reason !== undefined)
             return { reason };
     }
@@ -368,21 +471,21 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
             continue;
         foldedSegments.push(segmentTokens);
         const name = toks[0];
-        const nonOption = toks.slice(1).filter((t) => !t.startsWith("-"));
         if (!(pipeFed[si] ?? false)) {
             const floor = STDIN_FILE_FLOOR[name];
             const restArgs = toks.slice(1);
             const grepPatternSuppliedByFlag = name === "grep" && restArgs.some(isGrepPatternFlagToken);
             let sawNonFlagOperand = false;
             let hasStdinDash = false;
+            let operandCount = 0;
             if (name !== "tr") {
                 for (let k = 0; k < restArgs.length; k++) {
                     const t = restArgs[k];
-                    if (name === "cut" && (t === "-d" || t === "--delimiter")) {
+                    if (name === "cut" && (t === "-d" || isCutSeparatedDelimiterOption(t))) {
                         k++;
                         continue;
                     }
-                    if (name === "grep" && (t === "-f-" || isGrepFileStdinLongOption(t))) {
+                    if (name === "grep" && (isGrepClusterFileStdin(t) || isGrepFileStdinLongOption(t))) {
                         hasStdinDash = true;
                         break;
                     }
@@ -390,6 +493,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
                         continue;
                     const isGrepPatternPosition = name === "grep" && !grepPatternSuppliedByFlag && !sawNonFlagOperand;
                     sawNonFlagOperand = true;
+                    operandCount++;
                     if (isGrepPatternPosition)
                         continue;
                     if (t === "-") {
@@ -401,7 +505,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
             if (floor !== undefined && hasStdinDash) {
                 return { reason: `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout ${NOT_AUTO_ALLOWED}` };
             }
-            if (floor !== undefined && nonOption.length < floor) {
+            if (floor !== undefined && operandCount < floor) {
                 return { reason: `"${name}" with no file argument reads stdin and would block until the tool timeout ${NOT_AUTO_ALLOWED}` };
             }
         }
@@ -409,7 +513,15 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary) {
             return { reason: "`tail` in follow mode never terminates " + NOT_AUTO_ALLOWED };
         }
         const GENERATOR_DEVICES = new Set(["/dev/zero", "/dev/random", "/dev/urandom", "/dev/full"]);
-        const deviceArgs = toks.slice(1).filter((t) => !t.startsWith("-")).map(normalizeAbsPathLexically).filter(isBlockedDevicePath);
+        const deviceCandidates = [];
+        for (const t of toks.slice(1)) {
+            if (t.startsWith("-") && t !== "-") {
+                deviceCandidates.push(...attachedOptionPayloads(t));
+                continue;
+            }
+            deviceCandidates.push(t);
+        }
+        const deviceArgs = deviceCandidates.map(normalizeAbsPathLexically).filter(isBlockedDevicePath);
         const rescuedByHead = headBoundIsSmall(name, toks) && deviceArgs.every((d) => GENERATOR_DEVICES.has(d));
         if (!rescuedByHead && deviceArgs.length > 0) {
             return { reason: "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) " + NOT_AUTO_ALLOWED };

package/dist/tools/web.js

@@ -25,6 +25,31 @@ function resolveWebMaxBytes(value) {
     }
     return value;
 }
+function resolveWebTimeoutMs(value, knob, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0) {
+        const e = new Error(`${knob} must be a positive finite number of milliseconds (got ${String(value)}) — a non-finite or non-positive budget is not "no limit", it aborts every request within a millisecond`);
+        e.code = "config.web_timeout_invalid";
+        throw e;
+    }
+    if (value > 2_147_483_647) {
+        const e = new Error(`${knob} must not exceed 2147483647ms (~24.8 days) (got ${String(value)}) — a host timer truncates a larger delay and fires immediately, so widening the budget past this point aborts every request at once`);
+        e.code = "config.web_timeout_invalid";
+        throw e;
+    }
+    return value;
+}
+function resolveSearchMaxResults(value) {
+    if (value === undefined)
+        return 10;
+    if (!Number.isInteger(value) || value < 1) {
+        const e = new Error(`WebSearch maxResults must be a whole number of 1 or more (got ${String(value)}) — a zero, negative or unevaluable cap returns an empty result set from a backend that answered`);
+        e.code = "config.web_search_max_results_invalid";
+        throw e;
+    }
+    return value;
+}
 export const WEBFETCH_GROUNDING_MIN_TEXT_CHARS = 200;
 const GROUNDING_MIN_TEXT_RATIO = 0.01;
 const GROUNDING_RATIO_MAX_TEXT_CHARS = 2_000;
@@ -230,6 +255,7 @@ async function fetchAllowlisted(doFetch, start, allowHosts, userAgent, signal, o
 }
 export function webFetchToolSpec(config = {}) {
     const maxBytes = resolveWebMaxBytes(config.maxBytes);
+    const fetchTimeoutMs = resolveWebTimeoutMs(config.timeoutMs, "WebFetch timeoutMs", DEFAULT_FETCH_TIMEOUT_MS);
     const doFetch = config.fetchImpl ?? globalThis.fetch;
     const canSummarize = config.summarize !== undefined;
     return {
@@ -276,7 +302,7 @@ export function webFetchToolSpec(config = {}) {
             }
             if (!doFetch)
                 return failure("Error (WebFetch): no fetch implementation available in this environment.");
-            const timeoutMs = config.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+            const timeoutMs = fetchTimeoutMs;
             const ac = new AbortController();
             const timer = setTimeout(() => ac.abort(), timeoutMs);
             const onOuterAbort = () => ac.abort();
@@ -794,7 +820,8 @@ function webSearchResultAllowed(url, allowed, blocked) {
     return true;
 }
 export function createWebSearchTool(config) {
-    const max = config.maxResults ?? 10;
+    const max = resolveSearchMaxResults(config.maxResults);
+    const searchTimeoutMs = resolveWebTimeoutMs(config.timeoutMs, "WebSearch timeoutMs", DEFAULT_SEARCH_TIMEOUT_MS);
     const currentMonthYear = new Date().toLocaleString("en-US", { month: "long", year: "numeric" });
     return {
         name: "WebSearch",
@@ -831,7 +858,7 @@ export function createWebSearchTool(config) {
             if (queryChars > SEARCH_QUERY_MAX_CHARS) {
                 return errorResult(`Error (WebSearch): the query is ${queryChars} characters, over the ${SEARCH_QUERY_MAX_CHARS}-character limit. Shorten it to the terms that matter — an identical retry will fail the same way.`, failCard({ retryable: false }));
             }
-            const timeoutMs = config.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+            const timeoutMs = searchTimeoutMs;
             const ac = new AbortController();
             const timer = setTimeout(() => ac.abort(), timeoutMs);
             const onOuterAbort = () => ac.abort();
@@ -936,7 +963,7 @@ export function createWebSearchTool(config) {
 }
 export function createSearxngSearchBackend(baseUrl, options = {}) {
     const doFetch = options.fetchImpl ?? globalThis.fetch;
-    const timeoutMs = options.timeoutMs ?? 10_000;
+    const timeoutMs = resolveWebTimeoutMs(options.timeoutMs, "createSearxngSearchBackend timeoutMs", 10_000);
     const parsedBase = new URL(baseUrl);
     parsedBase.hash = "";
     parsedBase.pathname = `${parsedBase.pathname.replace(/\/+$/, "")}/search`;
@@ -966,9 +993,9 @@ export function createSearxngSearchBackend(baseUrl, options = {}) {
     };
 }
 export async function probeSearchBackend(search, options) {
-    const budget = options?.timeoutMs ?? 15_000;
     let timer;
     try {
+        const budget = resolveWebTimeoutMs(options?.timeoutMs, "probeSearchBackend timeoutMs", 15_000);
         const results = await Promise.race([
             search("connectivity probe", AbortSignal.timeout(budget)),
             new Promise((_, reject) => {

package/package.json

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