@sema-agent/core 2.0.0 → 2.1.0

package/dist/tools/task-list.js

@@ -55,6 +55,17 @@ export function assertJsonMetadata(value, path = "metadata") {
     }
     throw new Error(`Task ${path} must be JSON-serializable (found ${t === "object" ? "non-plain object" : t}).`);
 }
+export function compareTaskIds(a, b) {
+    const num = (id) => (/^\d+$/.test(id) ? Number.parseInt(id, 10) : Number.NaN);
+    const [na, nb] = [num(a), num(b)];
+    if (Number.isFinite(na) && Number.isFinite(nb))
+        return na - nb || a.localeCompare(b);
+    if (Number.isFinite(na))
+        return -1;
+    if (Number.isFinite(nb))
+        return 1;
+    return a.localeCompare(b);
+}
 export function createMemoryTaskListStore() {
     const tasks = new Map();
     let nextId = 1;
@@ -69,7 +80,7 @@ export function createMemoryTaskListStore() {
             tasks.set(id, snapTask(item));
         },
         delete: (id) => tasks.delete(id),
-        list: () => [...tasks.values()].map(snapTask),
+        list: () => [...tasks.values()].sort((a, b) => compareTaskIds(a.id, b.id)).map(snapTask),
         allocateId: () => String(nextId++),
     };
 }
@@ -133,7 +144,7 @@ export function createTaskListTools(store) {
             activeForm: Type.Optional(Type.String({ description: 'Present continuous form shown when in_progress (e.g., "Running tests")' })),
             metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Arbitrary metadata to attach to the task" })),
         }),
-        effect: "idempotent",
+        effect: "write",
         execute: (args) => serialized(tasks, async (tx) => {
             const a = args;
             if (a.metadata)

package/dist/tools/web.js

@@ -576,6 +576,41 @@ 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;
+const DETAILS_QUERY_ECHO_MAX_CHARS = 500;
+function clipQueryEcho(query) {
+    const cps = [...query];
+    return cps.length > DETAILS_QUERY_ECHO_MAX_CHARS
+        ? cps.slice(0, DETAILS_QUERY_ECHO_MAX_CHARS).join("") + `…[${cps.length} chars total]`
+        : query;
+}
+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;
@@ -591,6 +626,18 @@ function hostMatchesDomain(host, domain) {
         return false;
     return h === d || h.endsWith("." + d);
 }
+const URL_SCHEME_PREFIX = /^([a-z][a-z0-9+.-]*):/i;
+function normalizeResultUrl(raw) {
+    const s = raw.trim();
+    if (!s)
+        return { url: raw, schemeAssumed: false };
+    if (s.startsWith("//"))
+        return { url: "https:" + s, schemeAssumed: true };
+    const scheme = URL_SCHEME_PREFIX.exec(s)?.[1];
+    if (scheme !== undefined && !scheme.includes("."))
+        return { url: s, schemeAssumed: false };
+    return { url: "https://" + s, schemeAssumed: true };
+}
 function webSearchResultAllowed(url, allowed, blocked) {
     let host;
     try {
@@ -634,14 +681,18 @@ export function createWebSearchTool(config) {
             const startedAt = Date.now();
             const failCard = (extra = {}) => ({
                 type: "web-search",
-                query,
+                query: clipQueryEcho(query),
                 results: [],
                 durationSeconds: (Date.now() - startedAt) / 1000,
                 searchCount: 0,
                 ...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 +703,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,19 +733,27 @@ 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);
                 ctx.signal?.removeEventListener("abort", onOuterAbort);
             }
-            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 normalized = results.map((r) => {
+                const n = normalizeResultUrl(r.url);
+                return { ...r, url: n.url, schemeAssumed: n.schemeAssumed };
+            });
+            const usable = normalized.filter((r) => webSearchResultAllowed(r.url));
+            const droppedUnusable = normalized.length - usable.length;
+            const domainFiltered = usable.filter((r) => webSearchResultAllowed(r.url, allowed_domains, blocked_domains));
+            const droppedByDomain = usable.length - domainFiltered.length;
+            const kept = domainFiltered.slice(0, max);
+            const schemeAssumed = kept.filter((r) => r.schemeAssumed).length;
             let clipped = false;
-            const shown = results.map((r) => {
+            const shown = kept.map((r) => {
                 const title = clipCodePoints(r.title, SEARCH_TITLE_MAX_CHARS);
                 const url = clipCodePoints(r.url, MAX_URL_LENGTH);
                 const snippet = clipCodePoints(r.snippet, SEARCH_SNIPPET_MAX_CHARS);
@@ -709,10 +768,19 @@ 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 schemeNote = schemeAssumed > 0
+                ? `\n\n[WebSearch: ${schemeAssumed} result(s) came back with no URL scheme (a bare domain or a protocol-relative URL) and are shown normalized to https:// — that scheme is this tool's assumption, not the backend's claim.]`
+                : "";
+            const tailReminder = shown.length > 0
+                ? "REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks."
+                : "REMINDER: this search returned ZERO usable sources — there is nothing above to cite. Do not fabricate sources, URLs or citations; tell the user the search returned no usable results (the notes above say why, when there is a why) and answer from what you already know, or try a different query.";
+            const modelText = `${fenced}${dropNote}${domainNote}${schemeNote}${clipNote}\n\n${tailReminder}`;
             return {
                 content: modelText,
                 details: {

package/package.json

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