@sema-agent/core 2.12.0 → 3.0.0

package/dist/tools/monitor.js

@@ -29,6 +29,16 @@ const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its
     '- Wrong: `until grep -q "BUILD SUCCEEDED" build.log; do sleep 5; done` — if the build fails, this never exits and you wait until the watch times out.\n' +
     '- Right: `until grep -qE "BUILD (SUCCEEDED|FAILED)" build.log; do sleep 5; done` — every terminal state exits.\n' +
     "Before arming, ask: *if this process crashed right now, would my filter emit anything?* If not, widen it.";
+function envBackgroundWallSec(caps, requestedSec) {
+    const positive = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined);
+    const cap = positive(caps.maxBgTimeoutSec);
+    const base = requestedSec ?? positive(caps.defaultBgTimeoutSec);
+    if (base === undefined)
+        return cap;
+    if (cap === undefined)
+        return base;
+    return Math.min(base, cap);
+}
 export function createMonitorTool(env, opts) {
     return defineTool({
         name: "Monitor",
@@ -56,9 +66,10 @@ export function createMonitorTool(env, opts) {
             }
             const isPersistent = persistent === true;
             const timeoutMs = Math.min(MONITOR_MAX_TIMEOUT_MS, Math.max(1, Math.floor(timeout_ms ?? MONITOR_DEFAULT_TIMEOUT_MS)));
+            const spawnTimeoutSec = isPersistent ? undefined : Math.ceil(timeoutMs / 1000) + 5;
             const spawn = await env.spawnBackground(command, {
                 ...(opts.cwdRef !== undefined ? { cwd: opts.cwdRef.current } : {}),
-                ...(isPersistent ? {} : { timeout: Math.ceil(timeoutMs / 1000) + 5 }),
+                ...(spawnTimeoutSec !== undefined ? { timeout: spawnTimeoutSec } : {}),
             });
             if (!spawn.ok)
                 return errorResult(`Error (Monitor): ${spawn.error.message}`);
@@ -87,18 +98,50 @@ export function createMonitorTool(env, opts) {
                 });
             }
             catch (e) {
-                await env.killBackground(spawn.value.shellId).catch(() => undefined);
-                return errorResult(`Error (Monitor): the watch process was started but could not be registered (${e instanceof Error ? e.message : String(e)}); it has been terminated.`);
+                const why = e instanceof Error ? e.message : String(e);
+                let killDetail;
+                try {
+                    const kill = await env.killBackground(spawn.value.shellId);
+                    if (!kill.ok)
+                        killDetail = `${kill.error.code}: ${kill.error.message}`;
+                }
+                catch (killErr) {
+                    killDetail = killErr instanceof Error ? killErr.message : String(killErr);
+                }
+                return errorResult(killDetail === undefined
+                    ? `Error (Monitor): the watch process was started but could not be registered (${why}); it has been terminated.`
+                    : `Error (Monitor): the watch process was started but could not be registered (${why}), and it could NOT be terminated either (${killDetail}). ` +
+                        `It may still be running as background shell ${spawn.value.shellId}; no task id was minted, so TaskOutput/TaskStop cannot reach it — ` +
+                        "stop it out of band (the environment's own background time budget and its teardown sweep are the remaining backstops).");
             }
-            const bgTimeout = env.backgroundCapabilities.defaultBgTimeoutSec;
+            const bgTimeout = envBackgroundWallSec(env.backgroundCapabilities, spawnTimeoutSec);
             const wasClamped = timeout_ms !== undefined && timeout_ms !== timeoutMs;
             const clampNote = !isPersistent && wasClamped ? ` (clamped to ${timeoutMs}ms from your requested ${timeout_ms}ms)` : "";
             const timeoutIgnoredNote = isPersistent && timeout_ms !== undefined ? ` (the timeout_ms you passed is ignored because persistent is true)` : "";
+            const envWallMs = bgTimeout !== undefined ? bgTimeout * 1000 : undefined;
+            const envWallWins = !isPersistent && envWallMs !== undefined && envWallMs < timeoutMs;
+            const persistentBudget = bgTimeout !== undefined
+                ? `the execution environment kills background processes after ${bgTimeout}s`
+                : `the execution environment's background time budget still applies`;
+            const retainedByEnv = env.backgroundCapabilities.retainBackgroundProcesses === true;
+            const persistentAnchor = sessionScoped
+                ? retainedByEnv
+                    ? ". This environment declares retained background processes, so at the run teardown the watch is marked retained and " +
+                        "survives the session's release: only your TaskStop, the command's own exit, or that budget end it."
+                    : "; it runs until then, until you stop it, or until the session ends."
+                : retainedByEnv
+                    ? ". This mount carries no session identity, so the watch is NOT session-resident despite persistent: true; and because this " +
+                        "environment declares retained background processes it survives the session's release rather than being settled with the run — " +
+                        "nothing but your TaskStop, the command's own exit, or that budget will end it, and no later turn can reach it " +
+                        "(stop it explicitly with TaskStop before you finish)."
+                    : ". This mount carries no session identity, so the watch is NOT session-resident despite persistent: true — " +
+                        "it belongs to this task alone and the run teardown settles it, so do not count on it outliving this turn " +
+                        "(stop it explicitly with TaskStop when you are done).";
             const lifetime = isPersistent
-                ? typeof bgTimeout === "number"
-                    ? `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but the execution environment kills background processes after ${bgTimeout}s; it runs until then, until you stop it, or until the session ends.`
-                    : `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but the execution environment's background time budget still applies; it runs until then, until you stop it, or until the session ends.`
-                : `It will be killed after ${timeoutMs}ms${clampNote} if still running.`;
+                ? `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but ${persistentBudget}${persistentAnchor}`
+                : envWallWins
+                    ? `It will be killed after ${envWallMs}ms if still running — the execution environment's background time budget (${bgTimeout}s) is shorter than the ${timeoutMs}ms watch timeout${clampNote}, and the shorter of the two wins.`
+                    : `It will be killed after ${timeoutMs}ms${clampNote} if still running.`;
             const content = onNotify !== undefined
                 ? `Monitoring in background; task_id=${taskId}. Each stdout line becomes a notification event (lines within ` +
                     `~200ms are batched); you'll get a final notification with the exit code when it ends — do not poll. ` +
@@ -111,8 +154,11 @@ export function createMonitorTool(env, opts) {
                     type: "monitor-start",
                     taskId,
                     persistent: isPersistent,
+                    ...(bgTimeout !== undefined ? { envBudgetSec: bgTimeout } : {}),
+                    ...(envWallWins && envWallMs !== undefined ? { effectiveTimeoutMs: envWallMs } : {}),
                     ...(isPersistent
-                        ? { timeoutIgnored: timeout_ms !== undefined }
+                        ?
+                            { timeoutIgnored: timeout_ms !== undefined, sessionScoped, ...(retainedByEnv ? { retainedByEnv: true } : {}) }
                         : { timeoutMs, ...(timeout_ms !== undefined ? { requestedTimeoutMs: timeout_ms } : {}), wasClamped }),
                 },
             };

package/dist/tools/scheduler-tools.js

@@ -158,6 +158,12 @@ export function createSchedulerTools(env, ctx) {
         return [];
     const sched = env;
     const schedCtx = toSchedulerContext(ctx);
+    let cronCreateChain = Promise.resolve();
+    const serializedCronCreateOp = (fn) => {
+        const next = cronCreateChain.then(fn, fn);
+        cronCreateChain = next.then(() => undefined, () => undefined);
+        return next;
+    };
     const cronCreateDescription = `Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders. The task runs UNATTENDED when it fires, so write a fully self-contained \`prompt\` (it will not see this conversation). Use CronList to see what you've scheduled, CronDelete to remove one.
 
 ## One-shot tasks (schedule kind "delay" or "at")
@@ -210,7 +216,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             label: Type.Optional(Type.String({ description: "Short label (also a dedup key with the schedule)." })),
         }),
         effect: "write",
-        execute: async (args) => {
+        execute: async (args) => serializedCronCreateOp(async () => {
             const a = args;
             if (a.schedule !== undefined && a.cron !== undefined) {
                 return errorResult("Error (CronCreate): pass exactly one of `schedule` (object form) or `cron` (string form), not both.");
@@ -224,7 +230,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             const when = a.schedule ?? { kind: "cron", expr: a.cron };
             if (when.kind === "cron") {
                 if (!isValidCronExpr(when.expr)) {
-                    return errorResult(`Error (CronCreate): invalid cron expression "${when.expr}" — only 5/6 space-separated cron fields (digits and * / , -) are allowed.`);
+                    return errorResult(`Error (CronCreate): invalid cron expression "${when.expr}" — only 5 space-separated cron fields (digits and * / , -) are allowed (a 6th leading seconds field is parsed but always rejected next — this scheduler has no seconds hand).`);
                 }
                 const deepErr = cronScheduleError(when.expr);
                 if (deepErr)
@@ -277,7 +283,7 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
                     ...(replaced !== undefined ? { replaced } : {}),
                 },
             };
-        },
+        }),
     });
     const cronCancel = defineTool({
         name: "CronDelete",

package/dist/tools/web.d.ts

@@ -6,7 +6,10 @@ export interface WebFetchConfig {
     fetchImpl?: typeof fetch;
     maxBytes?: number;
     timeoutMs?: number;
-    summarize?: (content: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+    summarize?: (content: string, prompt: string, signal?: AbortSignal) => Promise<string | {
+        text: string;
+        truncated?: boolean;
+    }>;
     userAgent?: string;
 }
 export declare function htmlToText(html: string): string;
@@ -14,7 +17,10 @@ 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 createWebFetchSummarizer(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 | {
+    text: string;
+    truncated?: boolean;
+}>;
 export interface WebSearchConfig {
     search: (query: string, signal?: AbortSignal, opts?: {
         allowedDomains?: string[];

package/dist/tools/web.js

@@ -495,6 +495,7 @@ export function webFetchToolSpec(config = {}) {
             }
             const text = /html/i.test(contentType) || /^\s*</.test(raw) ? htmlToText(raw) : raw;
             let out = text;
+            let summaryTruncated = false;
             let note;
             if (prompt && bodyCut) {
                 note =
@@ -503,7 +504,17 @@ export function webFetchToolSpec(config = {}) {
             }
             else if (prompt && config.summarize) {
                 try {
-                    out = await config.summarize(text, prompt, ctx.signal);
+                    const summarized = await config.summarize(text, prompt, ctx.signal);
+                    if (typeof summarized === "string") {
+                        out = summarized;
+                    }
+                    else {
+                        out = summarized.text;
+                        if (summarized.truncated) {
+                            summaryTruncated = true;
+                            note = `[note: the summary below is INCOMPLETE — the summarizer hit its output limit before finishing]`;
+                        }
+                    }
                 }
                 catch (e) {
                     out = text;
@@ -534,7 +545,7 @@ export function webFetchToolSpec(config = {}) {
                     bytes: bodyBytes ? bodyBytes.length : raw.length,
                     result: out.length > RESULT_PREVIEW_CHARS ? `${out.slice(0, RESULT_PREVIEW_CHARS)}\n…[${out.length - RESULT_PREVIEW_CHARS} chars truncated — full text in the tool output]` : out,
                     durationMs: Date.now() - startedAt,
-                    ...(truncationNote ? { truncated: true } : {}),
+                    ...(truncationNote || summaryTruncated ? { truncated: true } : {}),
                     ...transferStateDetails,
                 },
             };
@@ -560,18 +571,17 @@ export function createWebFetchSummarizer(brain, model) {
         const msg = brain.complete
             ? await brain.complete(model, context, { signal })
             : await (await Promise.resolve(brain.stream(model, context, { signal }))).result();
-        const am = msg;
-        if (am?.stopReason === "error" || am?.stopReason === "aborted") {
-            throw new Error(am.errorMessage ?? `summarizer stopped with ${am.stopReason}`);
+        if (msg.stopReason === "error" || msg.stopReason === "aborted") {
+            throw new Error(msg.errorMessage ?? `summarizer stopped with ${msg.stopReason}`);
         }
-        const text = (am?.content ?? [])
-            .filter((b) => b?.type === "text" && typeof b.text === "string")
+        const text = msg.content
+            .filter((b) => b.type === "text" && typeof b.text === "string")
             .map((b) => b.text)
             .join("\n")
             .trim();
         if (!text)
             throw new Error("summarizer returned no text");
-        return text;
+        return msg.stopReason === "length" || msg.partialFinalized === true ? { text, truncated: true } : text;
     };
 }
 const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
@@ -801,25 +811,27 @@ export function createWebSearchTool(config) {
 export function createSearxngSearchBackend(baseUrl, options = {}) {
     const doFetch = options.fetchImpl ?? globalThis.fetch;
     const timeoutMs = options.timeoutMs ?? 10_000;
-    const base = baseUrl.replace(/\/+$/, "");
+    const parsedBase = new URL(baseUrl);
+    parsedBase.hash = "";
+    parsedBase.pathname = `${parsedBase.pathname.replace(/\/+$/, "")}/search`;
     return async (query, signal, opts) => {
         const q = opts?.allowedDomains && opts.allowedDomains.length > 0
             ? `${opts.allowedDomains.map((d) => `site:${d}`).join(" OR ")} ${query}`
             : query;
-        const url = new URL(`${base}/search`);
-        url.searchParams.set("q", q);
-        url.searchParams.set("format", "json");
+        const url = new URL(parsedBase);
         for (const [k, v] of Object.entries(options.extraParams ?? {}))
             url.searchParams.set(k, v);
+        url.searchParams.set("q", q);
+        url.searchParams.set("format", "json");
         const timeout = AbortSignal.timeout(timeoutMs);
         const res = await doFetch(url, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, headers: { accept: "application/json" } });
         if (!res.ok)
-            throw new Error(`SearXNG ${res.status} ${res.statusText} from ${base}/search`);
+            throw new Error(`SearXNG ${res.status} ${res.statusText} from ${url.origin}${url.pathname}`);
         const body = (await res.json());
         if (!Array.isArray(body.results))
-            throw new Error(`SearXNG returned no results array from ${base}/search — is format=json enabled on this instance?`);
+            throw new Error(`SearXNG returned no results array from ${url.origin}${url.pathname} — is format=json enabled on this instance?`);
         return body.results
-            .filter((r) => typeof r.url === "string" && r.url !== "")
+            .filter((r) => typeof r === "object" && r !== null && typeof r.url === "string" && r.url !== "")
             .map((r) => ({
             title: typeof r.title === "string" && r.title !== "" ? r.title : r.url,
             url: r.url,
@@ -829,14 +841,31 @@ export function createSearxngSearchBackend(baseUrl, options = {}) {
 }
 export async function probeSearchBackend(search, options) {
     const budget = options?.timeoutMs ?? 15_000;
+    let timer;
     try {
         const results = await Promise.race([
             search("connectivity probe", AbortSignal.timeout(budget)),
-            new Promise((_, reject) => setTimeout(() => reject(new Error(`probe timed out after ${budget}ms`)), budget)),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`probe timed out after ${budget}ms`)), budget);
+            }),
         ]);
         return { ok: true, results: results.length };
     }
     catch (e) {
-        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+        let text;
+        if (e instanceof Error)
+            text = e.message;
+        else {
+            try {
+                text = String(e);
+            }
+            catch {
+                text = Object.prototype.toString.call(e);
+            }
+        }
+        return { ok: false, error: text };
+    }
+    finally {
+        clearTimeout(timer);
     }
 }

package/dist/tools/worktree.d.ts

@@ -8,6 +8,8 @@ export interface ActiveWorktreeSession {
 }
 export interface WorktreeSessionRef {
     current?: ActiveWorktreeSession;
+    exiting?: boolean;
+    entering?: boolean;
 }
 export interface WorktreeToolsOptions {
     repoRoot: string;