@sema-agent/core 2.0.0 → 2.0.1

package/dist/core/tools.js

@@ -47,6 +47,7 @@ export function defineTool(spec) {
                     content: [{ type: "text", text: `${detail} Fix the arguments and call again.` }],
                     details: { invalidArguments: true },
                     terminate: false,
+                    isError: true,
                 };
             }
             let ret;

package/dist/engine/loop/agent-loop.d.ts

@@ -2,7 +2,7 @@ import { type AgentCoreStreamRuntimeDeps } from "./runtime-deps.js";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 export type LoopContinueReason = "next_turn" | "steer_injected" | "follow_up_injected" | "reactive_compact_retry" | "max_output_tokens_recovery" | "malformed_tool_use_retry" | "thinking_only_retry" | "midstream_partial_recovery" | "degenerate_output_recovery" | "walltime_cutoff_recovery";
-export type LoopTerminalReason = "completed" | "aborted_before_stream" | "assistant_error" | "stop_requested" | "malformed_tool_use_exhausted";
+export type LoopTerminalReason = "completed" | "aborted_before_stream" | "assistant_error" | "stop_requested" | "malformed_tool_use_exhausted" | "truncated_output_exhausted";
 export type LoopStep = {
     kind: "continue";
     reason: LoopContinueReason;

package/dist/engine/loop/agent-loop.js

@@ -375,15 +375,16 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
     state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
     const truncated = state.config.recovery?.truncatedOutput;
     if (message.stopReason === "length") {
-        if (truncated &&
-            toolCalls.length === 0 &&
-            state.pendingMessages.length === 0 &&
-            state.truncatedOutputContinues < (truncated.maxContinues ?? 3)) {
-            state.truncatedOutputContinues++;
-            state.midstreamPartialContinues = 0;
-            const noVisibleText = !message.content.some((c) => c.type === "text" && c.text.trim() !== "");
-            state.pendingMessages = [...state.pendingMessages, noVisibleText ? createReasoningCutContinueNudge() : createContinueNudge()];
-            return { kind: "ran", recovered: "max_output_tokens_recovery" };
+        if (truncated && toolCalls.length === 0 && state.pendingMessages.length === 0) {
+            if (state.truncatedOutputContinues < (truncated.maxContinues ?? 3)) {
+                state.truncatedOutputContinues++;
+                state.midstreamPartialContinues = 0;
+                const noVisibleText = !message.content.some((c) => c.type === "text" && c.text.trim() !== "");
+                state.pendingMessages = [...state.pendingMessages, noVisibleText ? createReasoningCutContinueNudge() : createContinueNudge()];
+                return { kind: "ran", recovered: "max_output_tokens_recovery" };
+            }
+            await emit({ type: "agent_end", messages: state.newMessages });
+            return { kind: "terminal", reason: "truncated_output_exhausted" };
         }
     }
     else {

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

@@ -1,5 +1,5 @@
 import { join, resolve, sep } from "node:path";
-import { existsSync, realpathSync } from "node:fs";
+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";
 function realpathSyncSafe(p) {
@@ -11,6 +11,16 @@ function realpathSyncSafe(p) {
     }
 }
 const sharedBoxes = new Map();
+function listBoxFiles(scopeDir) {
+    try {
+        return readdirSync(scopeDir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(".jsonl"))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
 const pathLocks = new Map();
 function withPathLock(key, fn) {
     const prev = pathLocks.get(key) ?? Promise.resolve();
@@ -157,7 +167,8 @@ export class FileMailboxStore {
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;
-        const prefix = join(this.dir, sanitizeScope(scope)) + sep;
+        const scopeDir = join(this.dir, sanitizeScope(scope));
+        const prefix = scopeDir + sep;
         const maxAgeMs = opts.maxAgeMs;
         for (const [key, b] of [...sharedBoxes]) {
             if (!b.path.startsWith(prefix))
@@ -180,6 +191,26 @@ export class FileMailboxStore {
             if (swept)
                 dropped++;
         }
+        for (const name of listBoxFiles(scopeDir)) {
+            const path = join(scopeDir, name);
+            const key = canonicalStoreKey(path);
+            if (sharedBoxes.has(key))
+                continue;
+            const swept = await withPathLock(key, () => {
+                if (sharedBoxes.has(key))
+                    return false;
+                const b = { messages: [], nextSeq: 1 };
+                for (const ev of readJsonlRecords(path))
+                    applyEvent(b, ev);
+                const newest = newestSentAt(b.messages);
+                if (newest === undefined || newest >= now - maxAgeMs)
+                    return false;
+                atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ t: "lease", owner: "", expiresAt: 0, maxSeq: b.nextSeq - 1 })}\n`);
+                return true;
+            });
+            if (swept)
+                dropped++;
+        }
         return dropped;
     }
     close() {

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

@@ -151,6 +151,8 @@ export function createGlobTool(env, rootCanonical, additionalRoots) {
                 scoped = r.key;
             }
             const r2 = await runGlobDetailed(env, rootCanonical, pattern, { path: scoped, max: max_results }, ctx.signal);
+            if (r2.error !== undefined)
+                return errorResult(r2.error);
             return {
                 content: r2.text,
                 details: { type: "glob", filenames: r2.filenames, numFiles: r2.numFiles, truncated: r2.truncated, durationMs: r2.durationMs, totalMatches: r2.totalMatches, countIsComplete: r2.countIsComplete },
@@ -162,7 +164,7 @@ export const HAND_TOOL_EFFECTS = {
     Read: "read",
     Edit: "write",
     MultiEdit: "write",
-    Write: "idempotent",
+    Write: "write",
     NotebookEdit: "write",
     Grep: "read",
     Glob: "read",

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

@@ -18,7 +18,8 @@ export declare function persistedTextOf(encoded: string | Uint8Array): string;
 export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: {
     code: string;
     message: string;
-}, signal?: AbortSignal): Promise<string>;
+    partialView?: boolean;
+}, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
 export declare const MAX_IMAGE_READ_BYTES: number;
 export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
 export type ReadImageDownsamplerOption = ImageDownsampler | false | undefined;

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { clipWithFilePointer } from "../../core/tool-errors.js";
-import { sha256, similarNameSuggestion, OVERSIZE_READ_ESCAPE_HINT, } from "./safety.js";
+import { sha256, similarNameSuggestion, OVERSIZE_READ_ESCAPE_HINT, PARTIAL_VIEW_READ_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, normalizeFileText } from "./encoding.js";
 import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
@@ -30,10 +30,14 @@ export function decodeEditBytes(bytes, path) {
 export function persistedTextOf(encoded) {
     return decodeTextBytes(typeof encoded === "string" ? Buffer.from(encoded, "utf8") : encoded).text;
 }
-export async function notReadRefusalText(env, toolName, key, v, signal) {
+export async function notReadRefusalText(env, toolName, key, v, signal, fallbackHint) {
     const base = `Error (${toolName}): ${v.message}`;
+    if (v.partialView === true && !isNotebookPath(key))
+        return `${base} ${PARTIAL_VIEW_READ_ESCAPE_HINT}`;
     const info = await env.fileInfo(key, signal);
-    return info.ok && info.value.kind !== "directory" && info.value.size > MAX_READ_BYTES && !isNotebookPath(key) ? `${base} ${OVERSIZE_READ_ESCAPE_HINT}` : base;
+    if (info.ok && info.value.kind !== "directory" && info.value.size > MAX_READ_BYTES && !isNotebookPath(key))
+        return `${base} ${OVERSIZE_READ_ESCAPE_HINT}`;
+    return fallbackHint === undefined ? base : `${base} ${fallbackHint}`;
 }
 export const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
 export const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;

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

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, } from "./safety.js";
-import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText, splitLeadingBom } from "./encoding.js";
+import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_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";
 async function gateToolWrite(hook, tool, path, key, content) {
     if (hook === undefined)
@@ -218,7 +218,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             ...FILE_PATH_PARAMS,
             content: Type.String({ description: "The content to write to the file" }),
         }),
-        effect: "idempotent",
+        effect: "write",
         execute: async (args, ctx) => {
             const { content } = args;
             const path = fileArgPath(args);
@@ -237,8 +237,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             if (exists.value) {
                 const notRead = requireRead(state, r.key);
                 if (notRead) {
-                    return errorResult(`${violationText("Write", notRead)} ` +
-                        `(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. \`rm\` + rewrite, or \`iconv\`.)`);
+                    return errorResult(await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT));
                 }
                 const readBin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!readBin.ok)
@@ -253,16 +252,15 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 const gated = await gateToolWrite(beforeWrite, "Write", path, r.key, content);
                 if (gated !== undefined)
                     return errorResult(gated);
-                const outgoing = splitLeadingBom(content);
-                const writeEncoding = outgoing.hadBom && !decodedPrev.encoding.hadBom ? { ...decodedPrev.encoding, hadBom: true } : decodedPrev.encoding;
-                const write = await env.writeFile(r.key, encodeTextForFile(outgoing.text, writeEncoding, "preserve"), ctx.signal);
+                const encodedWrite = encodeTextForFile(content, decodedPrev.encoding, "preserve");
+                const write = await env.writeFile(r.key, encodedWrite, ctx.signal);
                 if (!write.ok)
                     return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
-                const totalLines = countLines(outgoing.text);
-                state.set(r.key, { hash: sha256(normalizeFileText(content)), totalLines, truncated: false, lastReadAt: Date.now() });
+                const persistedWrite = persistedTextOf(encodedWrite);
+                state.set(r.key, { hash: sha256(persistedWrite), totalLines: countLines(persistedWrite), truncated: false, lastReadAt: Date.now() });
                 return {
                     content: `The file ${path} has been updated successfully.${FILE_STATE_TRAILER}`,
-                    details: { type: "update", filePath: path, content: normalizeFileText(content), originalFile },
+                    details: { type: "update", filePath: path, content: persistedWrite, originalFile },
                 };
             }
             const gatedCreate = await gateToolWrite(beforeWrite, "Write", path, r.key, content);

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

@@ -17,6 +17,7 @@ export type ReadFileState = Map<string, ReadEntry>;
 export declare function sha256(content: string): string;
 export interface FsViolation {
     code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid";
+    partialView?: true;
     message: string;
 }
 export declare function isBlockedDevicePath(key: string): boolean;
@@ -44,6 +45,8 @@ export declare function canonicalizeTarget(env: ExecutionEnv, path: string, sign
 export declare function violationText(toolName: string, v: FsViolation): string;
 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.)";
+export declare const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
 export declare function checkNoChange(oldString: string, newString: string): FsViolation | undefined;
 export declare function checkStale(entry: ReadEntry, currentHash: string): FsViolation | undefined;
 export declare function countOccurrences(haystack: string, needle: string): number;

package/dist/tools/fs/safety.js

@@ -230,11 +230,17 @@ export function violationText(toolName, v) {
 export function requireRead(state, key) {
     const entry = state.get(key);
     if (entry === undefined || entry.isPartialView) {
-        return { code: "not_read", message: "File has not been read yet. Read it first before writing to it." };
+        return {
+            code: "not_read",
+            message: "File has not been read yet. Read it first before writing to it.",
+            ...(entry?.isPartialView ? { partialView: true } : {}),
+        };
     }
     return undefined;
 }
 export const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused — 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 const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view — 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.)";
+export const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. `rm` + rewrite, or `iconv`.)";
 export function checkNoChange(oldString, newString) {
     if (oldString === newString) {
         return { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." };

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

@@ -69,4 +69,5 @@ export declare function runGlobDetailed(env: ExecutionEnv, root: string, pattern
     durationMs: number;
     totalMatches: number;
     countIsComplete: boolean;
+    error?: string;
 }>;

package/dist/tools/fs/search.js

@@ -1089,6 +1089,13 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, 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;
+    if (opts.path !== undefined) {
+        const probe = await env.fileInfo(start, signal);
+        if (!probe.ok && probe.error.code === "not_found") {
+            const error = `Error (Glob): path ${JSON.stringify(opts.path)} does not exist — check the path, or omit \`path\` to search the whole root.`;
+            return { text: error, error, filenames: [], numFiles: 0, truncated: false, durationMs: Date.now() - t0, totalMatches: 0, countIsComplete: false };
+        }
+    }
     const pat = normalizeGlobToken(pattern);
     const anchored = globIsAnchored(pattern);
     const re = globTokenToRegExp(pat, anchored, true);
@@ -1131,6 +1138,7 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
         return k < starStarIdx ? literalAt[k] === segs[k] : literalAfterStarStar.has(segs[k]);
     };
     let ignoredDirs = 0;
+    let ignoredFiles = 0;
     const rescued = [];
     const ignore = (relPath, isDir) => {
         const sr = toStartRel(relPath);
@@ -1144,8 +1152,12 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
         if (rescued.length > 0 && rescued.some((r) => sr.startsWith(r)))
             return false;
         const ig = baseIgnore(relPath, isDir);
-        if (ig && isDir)
-            ignoredDirs++;
+        if (ig) {
+            if (isDir)
+                ignoredDirs++;
+            else
+                ignoredFiles++;
+        }
         return ig;
     };
     const walked = await walk(env, root, start, ignore, signal);
@@ -1173,6 +1185,12 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     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;
+    const ignoredFileNote = matched.length === 0 && ignoredFiles > 0
+        ? `\n[note: ${ignoredFiles} file(s) matching an ignore rule (.gitignore) were skipped — an empty result here is NOT proof the file is absent; name it literally with a root-anchored path (e.g. "/notes.secret", "logs/app.log") to include it, or read it directly]`
+        : "";
+    const budgetNote = matched.length === 0 && walked.incomplete
+        ? `\n[note: the file-walk budget (${WALK_MAX_FILES} files / ${WALK_MAX_DEPTH} directory levels) ran out before the whole tree was scanned — this empty result is NOT proof the file is absent; scope the search with \`path\`, or use a root-anchored pattern (e.g. "src/**/*.ts") so the walk is pruned toward it, then retry]`
+        : "";
+    const text = matched.length === 0 ? "No files matched." + ignoreNote + ignoredFileNote + budgetNote + caveat : matched.join("\n") + capNote + caveat;
     return { text, filenames: matched, numFiles: matched.length, truncated, durationMs: Date.now() - t0, totalMatches, countIsComplete };
 }

package/dist/tools/web.js

@@ -576,6 +576,34 @@ export function createWebFetchSummarizer(brain, model) {
 }
 const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
 const SEARCH_ERROR_EXCERPT_CHARS = 2048;
+const SEARCH_QUERY_MAX_CHARS = 2_000;
+function classifySearchFailure(message) {
+    const m = message.toLowerCase();
+    const status = /(?:\bhttp\b|\bstatus\b|\bcode\b|\berror\b)\D{0,12}?(\d{3})\b/.exec(m)?.[1];
+    const code = status === undefined ? undefined : Number(status);
+    if (code === 429 || /\brate[- ]?limit/.test(m)) {
+        return { retryable: true, hint: "The backend rate-limited this request — retry after a pause, not immediately." };
+    }
+    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)) {
+        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) {
+        return { retryable: true, hint: `The backend reported a server-side fault (HTTP ${code}) — retry once; if it repeats, continue without search results.` };
+    }
+    if (code !== undefined && code >= 400 && code <= 499) {
+        return {
+            retryable: false,
+            hint: `The backend REJECTED the request (HTTP ${code}) — an identical retry will fail the same way. Change the query or the domain filters, or report that the search backend's configuration/credentials need attention.`,
+        };
+    }
+    return {
+        retryable: "unknown",
+        hint: "Whether a retry helps cannot be determined from the backend's message — at most one retry, then continue without search results.",
+    };
+}
 const SEARCH_TITLE_MAX_CHARS = 300;
 const SEARCH_SNIPPET_MAX_CHARS = 1_000;
 const SEARCH_BODY_MAX_CHARS = 100_000;
@@ -641,7 +669,11 @@ export function createWebSearchTool(config) {
                 ...extra,
             });
             if (allowed_domains?.length && blocked_domains?.length) {
-                return errorResult("Error: Cannot specify both allowed_domains and blocked_domains in the same request", failCard());
+                return errorResult("Error: Cannot specify both allowed_domains and blocked_domains in the same request", failCard({ retryable: false }));
+            }
+            const queryChars = [...query].length;
+            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 ac = new AbortController();
@@ -652,8 +684,8 @@ export function createWebSearchTool(config) {
             else
                 ctx.signal?.addEventListener("abort", onOuterAbort, { once: true });
             const TIMED_OUT = Symbol("websearch-timeout");
-            const abortedFrame = () => errorResult("Error (WebSearch): the search was interrupted (aborted) before completion. No results were retrieved.", failCard({ aborted: true }));
-            const timedOutFrame = () => errorResult(`Error (WebSearch): the search backend did not respond within ${timeoutMs}ms. The tool stopped waiting; the backend may still be executing the request.`, failCard({ timedOut: true }));
+            const abortedFrame = () => errorResult("Error (WebSearch): the search was interrupted (aborted) before completion. No results were retrieved. The interruption came from the caller, not the backend — do not retry on your own initiative.", failCard({ aborted: true, retryable: false }));
+            const timedOutFrame = () => errorResult(`Error (WebSearch): the search backend did not respond within ${timeoutMs}ms. The tool stopped waiting; the backend may still be executing the request. A retry may succeed — a narrower query, or fewer domain filters, tends to return faster.`, failCard({ timedOut: true, retryable: true }));
             let results;
             try {
                 const work = Promise.resolve(config.search(query, ac.signal, { allowedDomains: allowed_domains, blockedDomains: blocked_domains }));
@@ -682,9 +714,10 @@ export function createWebSearchTool(config) {
                     return timedOutFrame();
                 const msg = redactSecrets(e instanceof Error ? e.message : String(e)).trim();
                 const headline = "Error (WebSearch): the search backend failed.";
-                return errorResult(msg
+                const verdict = classifySearchFailure(msg);
+                return errorResult((msg
                     ? `${headline} The backend's error text follows:\n\n${delimitUntrusted("WebSearch backend error", msg, SEARCH_ERROR_EXCERPT_CHARS)}`
-                    : headline, failCard());
+                    : headline) + `\n\n${verdict.hint}`, failCard({ retryable: verdict.retryable }));
             }
             finally {
                 clearTimeout(timer);
@@ -692,7 +725,9 @@ export function createWebSearchTool(config) {
             }
             const usable = results.filter((r) => webSearchResultAllowed(r.url));
             const droppedUnusable = results.length - usable.length;
-            results = usable.filter((r) => webSearchResultAllowed(r.url, allowed_domains, blocked_domains)).slice(0, max);
+            const domainFiltered = usable.filter((r) => webSearchResultAllowed(r.url, allowed_domains, blocked_domains));
+            const droppedByDomain = usable.length - domainFiltered.length;
+            results = domainFiltered.slice(0, max);
             let clipped = false;
             const shown = results.map((r) => {
                 const title = clipCodePoints(r.title, SEARCH_TITLE_MAX_CHARS);
@@ -709,10 +744,13 @@ export function createWebSearchTool(config) {
             const dropNote = droppedUnusable > 0
                 ? `\n\n[WebSearch: ${droppedUnusable} result(s) returned by the backend were dropped — their URL was not a usable http(s) link]`
                 : "";
+            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 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.]"
                 : "";
-            const modelText = `${fenced}${dropNote}${clipNote}\n\nREMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.`;
+            const modelText = `${fenced}${dropNote}${domainNote}${clipNote}\n\nREMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.`;
             return {
                 content: modelText,
                 details: {

package/package.json

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