@livx.cc/agentx 0.99.38 → 0.99.40

package/dist/{Agent-DJwg1g8V.d.ts → Agent-D4-CLnxC.d.ts}

@@ -1,5 +1,5 @@
 import { IFilesystem } from '@livx.cc/wcli/core';
-import { M as Message, H as HostBridge, A as AgentTool, C as ChatLike, g as MessageContent, U as UserQuestion } from './tools-Byyh_bae.js';
+import { M as Message, H as HostBridge, A as AgentTool, C as ChatLike, g as MessageContent, U as UserQuestion } from './tools-BWzPQVy0.js';
 
 /**
  * Hooks — deterministic interception points around tool execution, run by the

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { H as Hooks, i as RunResult, R as ReasoningEffort, A as Agent } from './Agent-DJwg1g8V.js';
+import { H as Hooks, i as RunResult, R as ReasoningEffort, A as Agent } from './Agent-D4-CLnxC.js';
 import { IFilesystem } from '@livx.cc/wcli/core';
-import { M as Message, U as UserQuestion, H as HostBridge, c as ContentPart, g as MessageContent } from './tools-Byyh_bae.js';
+import { M as Message, U as UserQuestion, H as HostBridge, c as ContentPart, g as MessageContent } from './tools-BWzPQVy0.js';
 
 /**
  * On-disk session store for the CLI: each conversation is one JSON file at

package/dist/cli.js

@@ -258,13 +258,17 @@ function stripContent(content, stub) {
   });
   return changed ? out : content;
 }
+function clauses(sentence) {
+  return sentence.split(/[,;:]\s*|\s+(?:so|but|and|then|because|however|therefore|thus|although|though)\s+/i).map((c) => c.trim()).filter(Boolean);
+}
 function endsOnAnnouncedAction(text) {
   const sentences = text.split(/(?<=[.!?])\s+|\n+/).map((s) => s.trim()).filter(Boolean);
   const last = sentences[sentences.length - 1];
   if (!last || NEXT_STEP.test(last) || SIGN_OFF.test(last)) return false;
-  return ANNOUNCED_ACTION.test(last);
+  if (PROGRESSIVE.test(last)) return true;
+  return clauses(last).some((c) => !NEXT_STEP.test(c) && !SIGN_OFF.test(c) && COMMITMENT.test(c));
 }
-var log2, p_sep, IMAGE_ELIDE_STUB, IMAGE_REF_SCHEME, REF_REGISTRY_MAX, refRegistry, isImageRefUrl, bearsImage, ANNOUNCED_ACTION, NEXT_STEP, SIGN_OFF;
+var log2, p_sep, IMAGE_ELIDE_STUB, IMAGE_REF_SCHEME, REF_REGISTRY_MAX, refRegistry, isImageRefUrl, bearsImage, COMMITMENT, PROGRESSIVE, NEXT_STEP, SIGN_OFF;
 var init_llm = __esm({
   "src/llm.ts"() {
     "use strict";
@@ -277,7 +281,8 @@ var init_llm = __esm({
     refRegistry = /* @__PURE__ */ new Map();
     isImageRefUrl = (url) => !!url && url.startsWith(IMAGE_REF_SCHEME);
     bearsImage = (m) => messageHasImage(m.content) || toolImageRef(m.content) != null;
-    ANNOUNCED_ACTION = /^(?:also\s+|now\s+|then\s+)*(?:let me\b|i'?ll\b|i will\b|i'?m going to\b|(?:re-?)?(?:check|search|scan|read|verify|run|inspect|expand|look|examin|continu|proceed|try|fetch|load|open|test|build|grep|find|review|trac|dig|explor)\w*ing\b)/i;
+    COMMITMENT = /^(?:also\s+|now\s+|then\s+|so\s+)*(?:let me\b(?!\s+know\b)|i'?ll\b|i will\b|i'?m going to\b|i\s+(?:still\s+|now\s+|first\s+)*need to\b)/i;
+    PROGRESSIVE = /^(?:also\s+|now\s+|then\s+)*(?:re-?)?(?:check|search|scan|read|verify|run|inspect|expand|look|examin|continu|proceed|try|fetch|load|open|test|build|grep|find|review|trac|dig|explor)\w*ing\b/i;
     NEXT_STEP = /^next (?:step|run|up)\b/i;
     SIGN_OFF = /^let me know\b/i;
   }
@@ -902,6 +907,8 @@ function makeWebFetchTool(options = {}) {
   return {
     name: "WebFetch",
     description: "Fetch an http/https URL and return its readable text (HTML is stripped to text). Use to read docs or web pages. Returns the status line then up to ~100k chars of content.",
+    // Declared so a transport above the loop sizes its deadline around this one (see AgentTool.maxDurationMs).
+    maxDurationMs: timeoutMs,
     parameters: { type: "object", required: ["url"], properties: { url: { type: "string", description: "absolute http(s) URL" } } },
     async run({ url }) {
       const doFetch = options.fetch ?? globalThis.fetch;
@@ -2105,6 +2112,7 @@ var init_shell_sandbox = __esm({
 var tools_shell_exports = {};
 __export(tools_shell_exports, {
   ShellJobRegistry: () => ShellJobRegistry,
+  formatJobExit: () => formatJobExit,
   makeRealShellTool: () => makeRealShellTool,
   makeShellJobTools: () => makeShellJobTools
 });
@@ -2135,12 +2143,27 @@ async function nodeSpawn() {
   if (!_spawn) _spawn = (await import("child_process")).spawn;
   return _spawn;
 }
+function formatJobExit(n) {
+  return `[background job ${n.id} ${n.status}${n.exitCode != null ? ` exit ${n.exitCode}` : ""}] \`${n.command}\`
+` + (n.tail ? `${n.tail}
+` : "(no output)\n") + `Read the full output with ShellOutput({id:"${n.id}"}).`;
+}
 function makeRealShellTool(options) {
   const defaultTimeoutMs = options.timeoutMs ?? 12e4;
   const maxTimeoutMs = Math.max(options.maxTimeoutMs ?? 6e5, defaultTimeoutMs);
+  const backgroundDoc = () => {
+    const base = "Set `background:true` for long-running processes (servers, watchers) and for anything that already timed out in the foreground \u2014 returns a job id immediately; poll with ShellOutput/ShellStatus, stop with ShellKill. ";
+    const notify = options.registry?.notifiesOnExit ? "Its completion is reported back to you when it finishes." : "NOTE: nothing will tell you when it finishes \u2014 poll ShellOutput/ShellStatus yourself, or you will never see its result.";
+    const survival = options.jobsSurviveRun === false ? "The job does NOT survive the end of this run, so do not stop while you still need its result." : "It keeps running across turns.";
+    return `${base}${notify} ${survival}`;
+  };
   return {
     name: "Shell",
-    description: `Run a shell command via /bin/sh in the working directory. Executes any installed binary \u2014 ls, cat, grep, git, bun, node, curl, scripts, etc. Returns combined stdout+stderr; non-zero exits are prefixed \`[exit N]\`. Runs non-interactively with no terminal (stdin is /dev/null): commands that prompt for input fail fast rather than hang \u2014 for privileged actions use a non-interactive flag (e.g. \`sudo -n\`), or ask the user to run the command themselves. Each command is killed after ${defaultTimeoutMs}ms (result \`[exit 124]\` with whatever output it produced) \u2014 pass \`timeoutMs\` (max ${maxTimeoutMs}) for a legitimately slower command, and always bound network commands yourself (e.g. \`curl -m 10\`). Set \`background:true\` for long-running processes (servers, watchers) \u2014 returns a job id immediately; poll with ShellOutput, stop with ShellKill.`,
+    get description() {
+      return `Run a shell command via /bin/sh in the working directory. Executes any installed binary \u2014 ls, cat, grep, git, bun, node, curl, scripts, etc. Returns combined stdout+stderr; non-zero exits are prefixed \`[exit N]\`. Runs non-interactively with no terminal (stdin is /dev/null): commands that prompt for input fail fast rather than hang \u2014 for privileged actions use a non-interactive flag (e.g. \`sudo -n\`), or ask the user to run the command themselves. Each command is killed after ${defaultTimeoutMs}ms (result \`[exit 124]\` with whatever output it produced) \u2014 pass \`timeoutMs\` (max ${maxTimeoutMs}) for a legitimately slower command, and always bound network commands yourself (e.g. \`curl -m 10\`). ` + backgroundDoc();
+    },
+    // Declared so transports above the agent loop can size their own deadline with headroom (see AgentTool.maxDurationMs).
+    maxDurationMs: maxTimeoutMs,
     parameters: {
       type: "object",
       required: ["command"],
@@ -2150,9 +2173,10 @@ function makeRealShellTool(options) {
         timeoutMs: { type: "number", description: "wall-clock cap for THIS command, overriding the default (clamped to the tool max)" }
       }
     },
-    async run({ command, background, timeoutMs: askedTimeoutMs }, ctx) {
+    async run({ command, background, timeoutMs: askedTimeoutMs, timeout: aliasTimeout }, ctx) {
       const cmd = String(command ?? "");
-      const timeoutMs = Number.isFinite(askedTimeoutMs) && Number(askedTimeoutMs) > 0 ? Math.min(Number(askedTimeoutMs), maxTimeoutMs) : defaultTimeoutMs;
+      const asked = Number.isFinite(askedTimeoutMs) ? askedTimeoutMs : aliasTimeout;
+      const timeoutMs = Number.isFinite(asked) && Number(asked) > 0 ? Math.min(Number(asked), maxTimeoutMs) : defaultTimeoutMs;
       if (!cmd.trim()) return "[exit 1] empty command";
       if (background) {
         if (!options.registry) return "Error: background execution is not enabled in this host (no job registry).";
@@ -2241,8 +2265,9 @@ function makeRealShellTool(options) {
   };
 }
 function reasonFor(timedOut, timeoutMs, body) {
-  const head = timedOut ? `[exit 124] timed out after ${timeoutMs}ms (killed)` : "[exit 130] cancelled (killed)";
+  const head = timedOut ? `[exit 124] timed out after ${timeoutMs}ms (killed). Re-running this command unchanged will time out again. Either re-run it with background:true (returns a job id immediately; poll with ShellOutput/ShellStatus, stop with ShellKill) or narrow it so it can finish \u2014 bound it, scope it, or ask for less.` : "[exit 130] cancelled (killed)";
   return body ? `${head}
+Partial output before the kill:
 ${body}` : head;
 }
 function makeShellJobTools(registry) {
@@ -2323,12 +2348,14 @@ var init_tools_shell = __esm({
               job.status = "error";
               append(`
 [error] ${err2?.message ?? err2}`);
+              this.notifyExit(id, job);
             }
           });
           proc.on("close", (code) => {
             if (job.status === "running") {
               job.status = "exited";
               job.exitCode = code ?? void 0;
+              this.notifyExit(id, job);
             }
           });
         } catch (e) {
@@ -2338,6 +2365,29 @@ var init_tools_shell = __esm({
         this.jobs.set(id, job);
         return id;
       }
+      /** Fire `onExit` at most once per job, with the tail so the model can act without a second round-trip. */
+      notified = /* @__PURE__ */ new Set();
+      notifyExit(id, job) {
+        if (this.notified.has(id) || !this.cfg.onExit) return;
+        this.notified.add(id);
+        try {
+          this.cfg.onExit({ id, command: job.command, status: job.status, exitCode: job.exitCode, tail: clean(job.buf).slice(-4e3) });
+        } catch {
+        }
+      }
+      /**
+       * Wire (or rewire) the completion callback AFTER construction. A host that only gets its agent handle
+       * once the Agent is constructed (the library's own `fullAgentOptions` preset, any embedder) could not
+       * pass `onExit` up front, so background completions were silently REPL-only. Set it here instead.
+       */
+      setOnExit(fn) {
+        this.cfg.onExit = fn;
+      }
+      /** Whether a finished job will actually be reported to the model. The Shell tool's description reads
+       *  this so it can't promise a completion notice on a host that discards it. */
+      get notifiesOnExit() {
+        return !!this.cfg.onExit;
+      }
       /** Current tail output for a job (null = no such job). */
       output(id) {
         return this.jobs.get(id)?.buf ?? (this.jobs.has(id) ? "" : null);
@@ -3098,6 +3148,30 @@ async function boundedPool(items, limit, fn) {
   await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
   return out;
 }
+var SUBAGENT_MAX_DURATION_MS = 18e5;
+function wallClock(parent, ms) {
+  const ac = new AbortController();
+  let fired = false;
+  const onParent = () => ac.abort();
+  const timer = setTimeout(() => {
+    fired = true;
+    ac.abort();
+  }, ms);
+  if (parent) {
+    if (parent.aborted) ac.abort();
+    else parent.addEventListener("abort", onParent, { once: true });
+  }
+  return {
+    signal: ac.signal,
+    timedOut: () => fired,
+    dispose: () => {
+      clearTimeout(timer);
+      parent?.removeEventListener("abort", onParent);
+    }
+  };
+}
+var deadlineNote = (ms) => `
+[It was stopped by the sub-task wall-clock deadline of ${Math.round(ms / 1e3)}s \u2014 not by the user. Re-delegate a NARROWER sub-task (or continue from the trace); the same prompt will hit the same deadline again.]`;
 function sanitizeSlug(raw) {
   return raw.replace(/[^a-zA-Z0-9._-]/g, "-").replace(/-+/g, "-").slice(0, 40);
 }
@@ -3160,14 +3234,25 @@ function abortHint(label, res, file) {
 }
 async function runChildTraced(args) {
   const { opts, label, agentType, prompt } = args;
-  if (args.signal) args.childOpts.signal = args.signal;
+  const deadlineMs = opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS;
+  const wc = wallClock(args.signal, deadlineMs);
+  args.childOpts.signal = wc.signal;
   const file = opts.traceDir ? traceFileFor(opts.traceDir, label, args.childDepth) : void 0;
   const meta = { label, agentType, prompt };
   const child = new Agent(args.childOpts);
   if (file) installTrace(child, file, meta);
-  const res = await child.run(prompt);
-  if (file) flushTrace(file, meta, child.transcript, res.finishReason);
-  const result = res.finishReason === "stop" ? res.text || `(child '${label}' finished with no summary; finishReason=${res.finishReason})` : abortHint(label, res, file);
+  let res;
+  try {
+    res = await child.run(prompt);
+  } finally {
+    wc.dispose();
+  }
+  if (file) flushTrace(file, meta, child.transcript, wc.timedOut() ? "deadline" : res.finishReason);
+  let result = res.finishReason === "stop" ? res.text || `(child '${label}' finished with no summary; finishReason=${res.finishReason})` : abortHint(label, res, file);
+  if (wc.timedOut()) {
+    log5.warn(`sub-task '${label}' hit its ${deadlineMs}ms wall-clock deadline (steps=${res.steps})`);
+    result += deadlineNote(deadlineMs);
+  }
   await opts.hooks?.onSubagentStop?.(result, { label, agentType });
   return { res, result };
 }
@@ -3194,7 +3279,7 @@ function makeTaskTool(opts) {
   const maxDepth = opts.maxDepth ?? 2;
   return {
     name: "Task",
-    description: 'Delegate a self-contained sub-task to a child agent over the same filesystem. It runs autonomously with its own step budget and returns a concise summary \u2014 use to isolate context-heavy work (broad search, a scoped refactor). Provide a short `description` and a full `prompt`. If it is interrupted or fails, the result is a STATUS HINT with a pointer to its full transcript (Read it to recover what it did, then decide whether to continue or restart) \u2014 do not assume an incomplete sub-task succeeded. Set `background: true` to run it detached (returns a job id to poll with JobOutput while you keep working); its file edits are overlay-isolated and commit when it finishes. Set `isolation: "worktree"` to run in a real git worktree (needed when the child uses real shell commands that must see/modify actual files) \u2014 slower (~200ms setup), auto-cleaned if no changes.',
+    description: 'Delegate a self-contained sub-task to a child agent over the same filesystem. It runs autonomously with its own step budget and a wall-clock deadline, and returns a concise summary \u2014 use to isolate context-heavy work (broad search, a scoped refactor). Provide a short `description` and a full `prompt`. If it is interrupted or fails, the result is a STATUS HINT with a pointer to its full transcript (Read it to recover what it did, then decide whether to continue or restart) \u2014 do not assume an incomplete sub-task succeeded. Set `background: true` to run it detached (returns a job id to poll with JobOutput while you keep working); its file edits are overlay-isolated and commit when it finishes. Set `isolation: "worktree"` to run in a real git worktree (needed when the child uses real shell commands that must see/modify actual files) \u2014 slower (~200ms setup), auto-cleaned if no changes.',
     parameters: {
       type: "object",
       required: ["description", "prompt"],
@@ -3206,6 +3291,12 @@ function makeTaskTool(opts) {
         isolation: { type: "string", enum: ["overlay", "worktree"], description: 'isolation mode: "overlay" (default, VFS layer) or "worktree" (real git worktree for shell-heavy work)' }
       }
     },
+    // Declared because it is ENFORCED (see runChildTraced) — a transport above the loop sizes its own
+    // deadline around this one (AgentTool.maxDurationMs). Declaring an unenforced number would be a lie;
+    // declaring nothing left `Task` invisible to toolTimeoutViolations, which is the same hole.
+    maxDurationMs: opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS,
+    maxDurationEnforced: true,
+    // the wall clock below ABORTS the child at this bound — it cannot be overrun, so the transport needs slack, not a doubling
     async run({ description, prompt, agentType, background, isolation }, ctx) {
       if (depth >= maxDepth) {
         return `Error: Task depth limit reached (maxDepth ${maxDepth}). Cannot spawn another child agent \u2014 do this work directly instead.`;
@@ -3309,11 +3400,18 @@ function makeTaskBatchTool(opts) {
         isolation: { type: "string", enum: ["overlay", "worktree"], description: 'isolation mode for ALL children: "overlay" (default) or "worktree" (real git worktree each)' }
       }
     },
+    // Same enforced bound as `Task`, applied to the WHOLE batch (below), not per child — otherwise the
+    // honest ceiling would be ceil(n/maxParallel) x the per-child deadline, i.e. unbounded in `tasks`.
+    maxDurationMs: opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS,
+    maxDurationEnforced: true,
+    // the wall clock below ABORTS the child at this bound — it cannot be overrun, so the transport needs slack, not a doubling
     async run({ tasks, isolation }, ctx) {
       if (depth >= maxDepth) return `Error: Task depth limit reached (maxDepth ${maxDepth}). Cannot spawn child agents \u2014 do this work directly instead.`;
       const list = Array.isArray(tasks) ? tasks : [];
       if (!list.length) return "Error: TaskBatch needs a non-empty `tasks` array.";
       const useWorktree = isolation === "worktree";
+      const batchDeadlineMs = opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS;
+      const batchClock = wallClock(ctx.signal, batchDeadlineMs);
       const results = await boundedPool(list, maxParallel, async (t, i) => {
         const label = String(t?.description ?? t?.agentType ?? `task ${i + 1}`);
         let fs;
@@ -3332,12 +3430,12 @@ function makeTaskBatchTool(opts) {
         if (typeof childOpts === "string") return { label, error: childOpts, ok: false };
         try {
           const childPrompt = wtHandle ? worktreePromptPrefix(wtHandle.branch) + String(t?.prompt ?? "") : String(t?.prompt ?? "");
-          const { res, result } = await runChildTraced({ opts, childOpts, prompt: childPrompt, label, agentType: t?.agentType, childDepth: depth + 1, signal: ctx.signal });
+          const { res, result } = await runChildTraced({ opts, childOpts, prompt: childPrompt, label, agentType: t?.agentType, childDepth: depth + 1, signal: batchClock.signal });
           return { label, text: result, overlay, wtHandle, ok: res.finishReason !== "error" && res.finishReason !== "aborted" };
         } catch (e) {
           return { label, error: e instanceof Error ? e.message : String(e), wtHandle, ok: false };
         }
-      });
+      }).finally(() => batchClock.dispose());
       const lines = [];
       for (const r of results) {
         if (r.ok && r.overlay) await r.overlay.commit().catch(() => {
@@ -3351,7 +3449,7 @@ function makeTaskBatchTool(opts) {
         lines.push(`### ${lines.length + 1}. ${r.label}
 ${r.error ? `ERROR: ${r.error}` : r.text || "(no summary)"}${extra}`);
       }
-      return lines.join("\n\n");
+      return lines.join("\n\n") + (batchClock.timedOut() ? deadlineNote(batchDeadlineMs) : "");
     }
   };
 }
@@ -4115,7 +4213,17 @@ var Agent = class _Agent {
       const frag = reasoningToChatFragment(o.model, o.reasoning);
       const sentTools = o.model.startsWith("claude-code/") ? [] : wireTools;
       const isCursorWithTools = o.model.startsWith("cursor/") && wireTools.length > 0;
+      const hostToolTimeoutMs = o.providerOptions?.toolTimeoutMs;
+      const derivedToolTimeoutMs = Math.max(TRANSPORT_TOOL_TIMEOUT_FLOOR_MS, ...this.activeTools.map(transportHeadroomMs));
+      const effectiveToolTimeoutMs = typeof hostToolTimeoutMs === "number" ? Math.max(hostToolTimeoutMs, derivedToolTimeoutMs) : derivedToolTimeoutMs;
+      if (isCursorWithTools) {
+        if (typeof hostToolTimeoutMs === "number" && effectiveToolTimeoutMs !== hostToolTimeoutMs) {
+          log6.warn(`providerOptions.toolTimeoutMs=${hostToolTimeoutMs}ms is below what the registered tools need \u2014 RAISED to ${effectiveToolTimeoutMs}ms. ${toolTimeoutViolations(this.activeTools, hostToolTimeoutMs).length} tool(s) could outlive it, and the transport would have destroyed their results. To lower it, lower the tools' own maxDurationMs (e.g. the Shell tool's maxTimeoutMs) instead.`);
+        }
+        for (const v of toolTimeoutViolations(this.activeTools, effectiveToolTimeoutMs)) log6.warn(v);
+      }
       const cursorPo = isCursorWithTools ? {
+        toolTimeoutMs: effectiveToolTimeoutMs,
         toolExecutor: async (name, args) => {
           const tc = { id: `cursor-${Date.now()}`, type: "function", function: { name, arguments: JSON.stringify(args) } };
           return await this.dispatch(tc);
@@ -4217,14 +4325,12 @@ var Agent = class _Agent {
           })() } }))
         });
         for (const a of delegatedTools) {
-          const out = typeof a.output === "string" ? a.output : a.output == null ? "" : (() => {
-            try {
-              return JSON.stringify(a.output);
-            } catch {
-              return String(a.output);
-            }
-          })();
-          this.transcript.push({ role: "tool", tool_call_id: a.id, content: cap > 0 && out.length > cap ? cropResult(out, cap) : out });
+          const name = a.name || "tool";
+          const r = delegatedResult(a.output);
+          const text = r.images.length ? r.text : nonEmptyResult(isVacuous(a.output) ? "" : r.text, name, deliveryOf(a.output, a.status));
+          const body = cap > 0 && text.length > cap ? cropResult(text, cap) : text;
+          const content = r.images.length ? [{ type: "text", text: body }, ...r.images.map((i) => imagePart(`data:${i.mimeType};base64,${i.data}`))] : body;
+          this.transcript.push({ role: "tool", tool_call_id: a.id, content });
         }
       }
       const toolCalls = res.toolCalls ?? [];
@@ -4277,9 +4383,10 @@ var Agent = class _Agent {
         const raw = await this.dispatch(tc);
         let content;
         if (typeof raw === "string") {
-          content = raw;
+          content = nonEmptyResult(raw, tc.function.name);
         } else {
-          const parts = [{ type: "text", text: raw.text }];
+          const hasImages = !!raw.images?.length;
+          const parts = [{ type: "text", text: hasImages ? raw.text : nonEmptyResult(raw.text ?? "", tc.function.name) }];
           for (const img of raw.images ?? []) parts.push(imagePart(`data:${img.mimeType};base64,${img.data}`));
           content = parts;
         }
@@ -4588,6 +4695,76 @@ var isAnthropicModel = (m) => !!m && (m.startsWith("anthropic/") || /(^|\/)claud
 function estimateTokens(m, keepRecentImages = 1) {
   return Math.ceil(sendBytes(m, keepRecentImages) / 4);
 }
+var TRANSPORT_TOOL_TIMEOUT_FLOOR_MS = 18e5;
+function transportHeadroomMs(t) {
+  const d = Number(t.maxDurationMs) || 0;
+  if (!d) return 0;
+  return t.maxDurationEnforced ? d + 6e4 : d * 2 + 6e4;
+}
+function toolTimeoutViolations(tools, transportMs) {
+  const out = [];
+  for (const t of tools) {
+    const d = Number(t.maxDurationMs) || 0;
+    if (d && d >= transportMs) {
+      out.push(`tool-timeout layering VIOLATED: '${t.name}' may run up to ${d}ms but the transport deadline is ${transportMs}ms \u2014 the transport wins the race and the tool's real result is destroyed. Raise providerOptions.toolTimeoutMs above ${d}ms.`);
+    }
+  }
+  return out;
+}
+function nonEmptyResult(out, name = "tool", delivery = "ran") {
+  if (out.trim()) return out;
+  if (delivery === "error") return `[${name}] failed with no error message \u2014 the tool reported an error but produced no detail. Its effect is UNKNOWN: verify the state before assuming it did or did not happen.`;
+  if (delivery === "missing") {
+    const base = `[${name}] returned no result. This is a transport failure, not an empty answer \u2014 the call's outcome is UNKNOWN, so do not assume it succeeded or failed.`;
+    return name === "Shell" ? `${base} Do NOT re-issue the same long-running command: run it with background:true and poll ShellOutput/ShellStatus, or narrow it so it can finish.` : `${base} Retry it, or verify the state another way before continuing.`;
+  }
+  return `[${name}] ran and returned no output. The call completed \u2014 this is an empty answer, not a failure.`;
+}
+function isVacuous(v, seen = /* @__PURE__ */ new Set(), depth = 0) {
+  if (v == null) return true;
+  if (typeof v === "string") return v.trim() === "";
+  if (typeof v !== "object") return false;
+  if (seen.has(v) || depth >= 64) return false;
+  seen.add(v);
+  try {
+    if (Array.isArray(v)) return v.every((x) => isVacuous(x, seen, depth + 1));
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) return false;
+    const vals = Object.values(v);
+    return vals.length === 0 || vals.every((x) => isVacuous(x, seen, depth + 1));
+  } finally {
+    seen.delete(v);
+  }
+}
+function delegatedResult(output) {
+  if (typeof output === "string") return { text: output, images: [] };
+  if (output == null) return { text: "", images: [] };
+  const isImg = (i) => i && typeof i.data === "string" && typeof i.mimeType === "string";
+  const o = output;
+  if (Array.isArray(o.images)) {
+    const images = o.images.filter(isImg);
+    if (images.length) return { text: typeof o.text === "string" ? o.text : "", images };
+  }
+  const blocks = Array.isArray(output) ? output : Array.isArray(o.content) ? o.content : void 0;
+  if (blocks) {
+    const images = blocks.filter((b) => b?.type === "image" && isImg(b)).map((b) => ({ mimeType: b.mimeType, data: b.data }));
+    if (images.length) {
+      const text = blocks.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n");
+      return { text, images };
+    }
+  }
+  try {
+    return { text: JSON.stringify(output), images: [] };
+  } catch {
+    return { text: String(output), images: [] };
+  }
+}
+function deliveryOf(output, status) {
+  if (status === "error") return "error";
+  if (output == null) return "missing";
+  if (status != null && status !== "completed") return "missing";
+  return "ran";
+}
 function cropResult(result, cap) {
   const head = result.slice(0, cap);
   const nl = head.lastIndexOf("\n");
@@ -8333,13 +8510,29 @@ function toResult(result) {
   }
   return { text: JSON.stringify(result) };
 }
-function mcpToolToAgentTool(spec, callTool, prefix = "mcp__") {
+var MCP_CALL_TIMEOUT_MS = 3e5;
+var TIMED_OUT = /* @__PURE__ */ Symbol("mcp-timeout");
+async function withDeadline(p, ms) {
+  let t;
+  try {
+    return await Promise.race([p, new Promise((res) => {
+      t = setTimeout(() => res(TIMED_OUT), ms);
+    })]);
+  } finally {
+    clearTimeout(t);
+  }
+}
+var mcpTimedOut = (name, ms = MCP_CALL_TIMEOUT_MS) => `[${name}] no response after ${ms / 1e3}s \u2014 the MCP server never answered. The call's outcome is UNKNOWN: do not assume it ran or that it failed. Verify the state (or pick a bounded/narrower call) before retrying.`;
+function mcpToolToAgentTool(spec, callTool, prefix = "mcp__", timeoutMs = MCP_CALL_TIMEOUT_MS) {
   return {
     name: `${prefix}${spec.name}`,
     description: spec.description ?? `MCP tool ${spec.name}`,
     parameters: spec.inputSchema ?? { type: "object", properties: {} },
+    maxDurationMs: timeoutMs,
     async run(args, _ctx) {
-      const r = toResult(await callTool(spec.name, args ?? {}));
+      const raw = await withDeadline(callTool(spec.name, args ?? {}), timeoutMs);
+      if (raw === TIMED_OUT) return mcpTimedOut(spec.name, timeoutMs);
+      const r = toResult(raw);
       return r.images?.length ? r : r.text;
     }
   };
@@ -8354,6 +8547,7 @@ function describeSpec(s) {
 }
 function makeMcpToolSearch(specs, callTool, options = {}) {
   const maxResults = options.maxResults ?? 10;
+  const callTimeoutMs = options.timeoutMs ?? MCP_CALL_TIMEOUT_MS;
   const byName = new Map(specs.map((s) => [s.name, s]));
   const catalogLine = `${specs.length} MCP tool(s) available \u2014 search by keyword, then call by exact name.`;
   const searchTool = {
@@ -8379,10 +8573,13 @@ function makeMcpToolSearch(specs, callTool, options = {}) {
         args: { type: "object", description: "arguments object for the tool (per its schema)" }
       }
     },
+    maxDurationMs: callTimeoutMs,
     async run({ name, args }) {
       const n = String(name ?? "");
       if (!byName.has(n)) return `Error: unknown MCP tool '${n}'. Use ToolSearch to find valid names.`;
-      const r = toResult(await callTool(n, args ?? {}));
+      const raw = await withDeadline(callTool(n, args ?? {}), callTimeoutMs);
+      if (raw === TIMED_OUT) return mcpTimedOut(n, callTimeoutMs);
+      const r = toResult(raw);
       return r.images?.length ? r : r.text;
     }
   };
@@ -9185,14 +9382,20 @@ Reference files in them by their mount path (the left side).`;
   const memoryWriteDir = memoryDir[0];
   const hooks = o.learnFromMistakes && memoryWriteDir ? composeHooks(o.hooks, lessonCapture({ fs, dir: memoryWriteDir, minRepeats: 2 })) : o.hooks;
   let realShell = [];
+  const agentRef = {};
   const useRealShell = o.realShell ?? !virtual;
   if (useRealShell && !virtual && !isClaudeCode) {
-    const jobs = new ShellJobRegistry({ cwd, killOnExit: true, osSandbox: o.osSandbox });
-    realShell = [makeRealShellTool({ cwd, registry: jobs, osSandbox: o.osSandbox }), ...makeShellJobTools(jobs)];
+    const jobs = new ShellJobRegistry({
+      cwd,
+      killOnExit: true,
+      osSandbox: o.osSandbox,
+      onExit: (n) => agentRef.agent?.inject(formatJobExit(n))
+    });
+    realShell = [makeRealShellTool({ cwd, registry: jobs, osSandbox: o.osSandbox, jobsSurviveRun: o.singleRun !== true }), ...makeShellJobTools(jobs)];
   }
   const scratchDir = o.scratch ? o.scratchDir ?? (virtual ? `${cwd}/.agent/scratch` : `${tmpdir()}/agentx-scratch-${process.pid}`) : void 0;
   const scratch = scratchDir ? new Scratch(fs, { dir: scratchDir }) : void 0;
-  return new Agent({
+  return agentRef.agent = new Agent({
     ai: o.ai,
     fs,
     model: o.model ?? "anthropic/claude-sonnet-4-6",