@sema-agent/core 1.452.0 → 2.0.1

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

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

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

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

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

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

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

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

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

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

package/dist/tools/scheduler-tools.d.ts

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

package/dist/tools/web.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool } from "../internal/harness.js";
+import type { AgentTool } from "../internal/harness-types.js";
 import type { Brain, ToolSpec } from "../core/types.js";
 import type { Model } from "../internal/llm.js";
 export interface WebFetchConfig {
@@ -14,7 +14,7 @@ export declare function webFetchToolSpec(config?: WebFetchConfig): ToolSpec;
 export declare function createWebFetchTool(config?: WebFetchConfig): AgentTool;
 export declare const WEBFETCH_SUMMARY_MAX_CONTENT = 100000;
 export declare const WEBFETCH_SUMMARY_GUIDELINES: string;
-export declare function makeWebFetchSummarizer(brain: Brain, model: Model): (content: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+export declare function createWebFetchSummarizer(brain: Brain, model: Model): (content: string, prompt: string, signal?: AbortSignal) => Promise<string>;
 export interface WebSearchConfig {
     search: (query: string, signal?: AbortSignal, opts?: {
         allowedDomains?: string[];

package/dist/tools/web.js

@@ -550,7 +550,7 @@ export const WEBFETCH_SUMMARY_GUIDELINES = `Provide a concise response based onl
     ` - Use quotation marks for exact language from articles; any language outside of the quotation should never be word-for-word the same.\n` +
     ` - You are not a lawyer and never comment on the legality of your own prompts and responses.\n` +
     ` - Never produce or reproduce exact song lyrics.\n`;
-export function makeWebFetchSummarizer(brain, model) {
+export function createWebFetchSummarizer(brain, model) {
     return async (content, prompt, signal) => {
         const truncated = content.length > WEBFETCH_SUMMARY_MAX_CONTENT
             ? content.slice(0, WEBFETCH_SUMMARY_MAX_CONTENT) + "\n\n[Content truncated due to length...]"
@@ -576,6 +576,34 @@ export function makeWebFetchSummarizer(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/dist/tools/worktree.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, ExecutionEnv } from "../internal/harness.js";
+import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
 import type { CwdRef } from "./fs/index.js";
 export interface ActiveWorktreeSession {
     worktreeDir: string;

package/package.json

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

package/dist/core/dynamic-recall.d.ts

@@ -1,32 +0,0 @@
-import type { AgentMessage } from "../internal/harness.js";
-import { type MemorySelector, encodeSurfacedKey } from "./memory-recall.js";
-import type { MemoryStore } from "./memory.js";
-export interface DynamicRecallConfig {
-    enabled?: boolean;
-    recentMessageWindow?: number;
-    maxQueryChars?: number;
-}
-export declare const DEFAULT_RECENT_MESSAGE_WINDOW = 6;
-export declare const DEFAULT_MAX_QUERY_CHARS = 4000;
-export declare function buildRecallQuery(messages: readonly AgentMessage[], window?: number, maxChars?: number): string;
-export interface DynamicRecallOutcome {
-    block: string | undefined;
-    surfacedIds: readonly string[];
-    surfacedKeys: readonly string[];
-}
-export interface DynamicRecallInput {
-    store: MemoryStore;
-    scopes: readonly string[];
-    selector: MemorySelector;
-    query: string;
-    recentTools?: string[];
-    maxSelected?: number;
-    maxLinked?: number;
-    timeoutMs?: number;
-    signal?: AbortSignal;
-    nowMs?: number;
-    priorSurfacedIds?: ReadonlySet<string>;
-    priorSurfacedKeys?: ReadonlySet<string>;
-}
-export declare function runDynamicRecall(input: DynamicRecallInput): Promise<DynamicRecallOutcome>;
-export { encodeSurfacedKey };

package/dist/core/dynamic-recall.js

@@ -1,76 +0,0 @@
-import { encodeSurfacedKey, selectAndComposeLayeredMemory, selectAndComposeMemory, } from "./memory-recall.js";
-export const DEFAULT_RECENT_MESSAGE_WINDOW = 6;
-export const DEFAULT_MAX_QUERY_CHARS = 4_000;
-export function buildRecallQuery(messages, window = DEFAULT_RECENT_MESSAGE_WINDOW, maxChars = DEFAULT_MAX_QUERY_CHARS) {
-    if (window <= 0 || maxChars <= 0)
-        return "";
-    const recent = messages.slice(-window);
-    const parts = [];
-    for (const m of recent) {
-        const text = messageText(m);
-        if (text)
-            parts.push(text);
-    }
-    const joined = parts.join("\n").trim();
-    if (joined.length <= maxChars)
-        return joined;
-    return joined.slice(joined.length - maxChars);
-}
-function messageText(m) {
-    const content = m.content;
-    if (typeof content === "string")
-        return content.trim();
-    if (Array.isArray(content)) {
-        const out = [];
-        for (const c of content) {
-            if (typeof c.text === "string" && c.text.length > 0)
-                out.push(c.text);
-        }
-        return out.join(" ").trim();
-    }
-    return "";
-}
-const EMPTY_OUTCOME = { block: undefined, surfacedIds: [], surfacedKeys: [] };
-export async function runDynamicRecall(input) {
-    if (input.scopes.length === 0 || input.query.trim().length === 0)
-        return EMPTY_OUTCOME;
-    if (input.scopes.length === 1) {
-        const res = await selectAndComposeMemory({
-            store: input.store,
-            scope: input.scopes[0],
-            objective: input.query,
-            selector: input.selector,
-            recentTools: input.recentTools,
-            maxSelected: input.maxSelected,
-            maxLinked: input.maxLinked,
-            timeoutMs: input.timeoutMs,
-            signal: input.signal,
-            nowMs: input.nowMs,
-            priorSurfacedIds: input.priorSurfacedIds,
-        });
-        if ("degrade" in res)
-            return EMPTY_OUTCOME;
-        if (res.block === undefined || res.surfacedIds.length === 0)
-            return EMPTY_OUTCOME;
-        return { block: res.block, surfacedIds: res.surfacedIds, surfacedKeys: [] };
-    }
-    const res = await selectAndComposeLayeredMemory({
-        store: input.store,
-        scopes: [...input.scopes],
-        objective: input.query,
-        selector: input.selector,
-        recentTools: input.recentTools,
-        maxSelected: input.maxSelected,
-        maxLinked: input.maxLinked,
-        timeoutMs: input.timeoutMs,
-        signal: input.signal,
-        nowMs: input.nowMs,
-        priorSurfacedKeys: input.priorSurfacedKeys,
-    });
-    if ("degrade" in res)
-        return EMPTY_OUTCOME;
-    if (res.block === undefined || res.surfacedKeys.length === 0)
-        return EMPTY_OUTCOME;
-    return { block: res.block, surfacedIds: [], surfacedKeys: res.surfacedKeys };
-}
-export { encodeSurfacedKey };