@mono-agent/agent-runtime 0.20.14 → 0.21.0

package/src/agent/tools/shared/path-resolver.js

@@ -7,8 +7,8 @@ import { resolveSandboxPolicy } from "./tool-context.js";
 // ToolContext is threaded (`ctx ?? readToolRuntime()`), so hosts that only call
 // the deep-path configureToolRuntime keep their historical behavior.
 function configured(ctx) {
-  const { workspace, repoRoot } = ctx ?? readToolRuntime();
-  return { workspace, repoRoot };
+  const { workspace, repoRoot, additionalReadRoots, additionalWriteRoots } = ctx ?? readToolRuntime();
+  return { workspace, repoRoot, additionalReadRoots, additionalWriteRoots };
 }
 
 export function workspaceRoot(workdir, ctx) {
@@ -50,8 +50,12 @@ function isPathAllowedFor(path, workdir, access, options) {
       && insideSandboxRoots(Array.isArray(field) ? field : [], r)
       && (access !== "write" || !sandboxDeniesWrite(policy, r, ctx));
   }
-  const { workspace, repoRoot } = configured(ctx);
-  return insideLegacyRoots([workdir, workspace, repoRoot, process.cwd(), "/tmp"], r);
+  const { workspace, repoRoot, additionalReadRoots, additionalWriteRoots } = configured(ctx);
+  const additionalRoots = access === "write"
+    ? additionalWriteRoots
+    : [...(additionalReadRoots ?? []), ...(additionalWriteRoots ?? [])];
+  return insideLegacyRoots([workdir, workspace, repoRoot, process.cwd(), "/tmp"], r)
+    || insideAdditionalRoots(Array.isArray(additionalRoots) ? additionalRoots : [], r);
 }
 
 function isPathLexicallyAllowedFor(path, workdir, access, options) {
@@ -64,8 +68,12 @@ function isPathLexicallyAllowedFor(path, workdir, access, options) {
       && insideLexicalRoots(Array.isArray(field) ? field : [], r)
       && (access !== "write" || !sandboxLexicallyDeniesWrite(policy, r, ctx));
   }
-  const { workspace, repoRoot } = configured(ctx);
-  return insideLegacyRoots([workdir, workspace, repoRoot, process.cwd(), "/tmp"], r);
+  const { workspace, repoRoot, additionalReadRoots, additionalWriteRoots } = configured(ctx);
+  const additionalRoots = access === "write"
+    ? additionalWriteRoots
+    : [...(additionalReadRoots ?? []), ...(additionalWriteRoots ?? [])];
+  return insideLegacyRoots([workdir, workspace, repoRoot, process.cwd(), "/tmp"], r)
+    || insideLexicalRoots(Array.isArray(additionalRoots) ? additionalRoots : [], r);
 }
 
 export function isWorkdirAllowed(workdir, options = {}) {
@@ -108,6 +116,17 @@ function insideSandboxRoots(roots, target) {
     && allowedRoots.some((root) => isInsidePath(root, real));
 }
 
+// Additional file-tool roots are an operator-authored capability boundary even
+// when process sandboxing is off. Unlike the legacy workspace allowance, keep
+// both lexical and real paths inside the configured set so an allowed symlink
+// cannot expose an unrelated path.
+function insideAdditionalRoots(roots, target) {
+  const allowedRoots = normalizeRoots(roots);
+  const real = realTargetPath(target);
+  return allowedRoots.some((root) => isInsidePath(root, target))
+    && allowedRoots.some((root) => isInsidePath(root, real));
+}
+
 // A protected root rejects either spelling: the lexical request and its
 // existing/nearest-existing realpath. This closes symlink aliases in both
 // directions without weakening ordinary readable/writable root checks.

package/src/agent/tools/shared/process-jobs.js

@@ -14,6 +14,7 @@ import { startPreparedProcess } from "./process-runner.js";
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
  *   description?: string,
+ *   wakeOnCompletion?: boolean,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   launch: (options?: {timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
@@ -30,6 +31,7 @@ import { startPreparedProcess } from "./process-runner.js";
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
  *   description?: string,
+ *   wakeOnCompletion?: boolean,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   startedAt: number,
@@ -42,6 +44,7 @@ export async function handOffProcessJob({
   prepared,
   summary,
   description,
+  wakeOnCompletion,
   timeoutMs,
   maxOutputChars,
   startedAt,
@@ -56,6 +59,7 @@ export async function handOffProcessJob({
       prepared: ownedPrepared,
       summary,
       ...(description === undefined ? {} : { description }),
+      ...(wakeOnCompletion === undefined ? {} : { wakeOnCompletion }),
       ...(timeoutMs === undefined ? {} : { timeoutMs }),
       ...(maxOutputChars === undefined ? {} : { maxOutputChars }),
       launch(options = {}) {
@@ -89,7 +93,7 @@ export async function handOffProcessJob({
       ...(result.maxRuntimeMs === undefined ? {} : { max_runtime_ms: result.maxRuntimeMs }),
     };
     return {
-      text: `${BACKGROUND_START_GUIDANCE}\n${JSON.stringify(payload)}`,
+      text: `${wakeOnCompletion === false ? "Background process job started with wake_on_completion=false: its terminal lifecycle card will update, but this conversation will not receive a completion turn. Do not report the work as finished yet." : BACKGROUND_START_GUIDANCE}\n${JSON.stringify(payload)}`,
       outcome: {
         status: "ok",
         code: "background_started",
@@ -147,6 +151,7 @@ const PUBLIC_BACKGROUND_START_FAILURES = Object.freeze({
   process_job_cleanup_incomplete: "Process-job cleanup could not be confirmed.",
   process_job_store_error: "Process-job storage failed.",
   process_job_wake_failed: "Process-job wake delivery failed.",
+  process_job_wake_unknown: "Process-job wake delivery outcome is unknown; replay was suppressed.",
   process_job_response_too_large: "The process-job response exceeded its size limit.",
   process_job_invalid: "The process-job request is invalid.",
 });

package/src/agent/tools/shared/process-runner.js

@@ -136,7 +136,7 @@ input.once("end", () => {
  * or exceeds that cap.
  *
  * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} commandSpec
- * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer}} [options]
+ * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer, exactEnvironment?: boolean}} [options]
  */
 export function runPreparedProcess(
   commandSpec,
@@ -145,6 +145,7 @@ export function runPreparedProcess(
     signal,
     maxBufferBytes = DEFAULT_PROCESS_BUFFER_BYTES,
     input,
+    exactEnvironment = false,
   } = {},
 ) {
   return startPreparedProcess(commandSpec, {
@@ -152,6 +153,7 @@ export function runPreparedProcess(
     signal,
     maxBufferBytes,
     input,
+    exactEnvironment,
   }).completion;
 }
 

package/src/agent/tools/shared/tool-context.js

@@ -18,6 +18,8 @@
 //   workspace        — fallback for tool workdir resolution. Default: process.cwd().
 //   repoRoot         — secondary allowed root (the host's installation root).
 //                      Tool path-allowlist checks accept this in addition to workspace.
+//   additionalReadRoots  — extra read-only roots for managed filesystem tools.
+//   additionalWriteRoots — extra read/write roots for managed filesystem tools.
 //   runId            — used as the subdirectory under toolArtifactDir for tool output.
 //   toolArtifactDir  — root for {dir}/tool-output/{runId}/{file} artifact writes
 //                      from capChars/formatSearchLines. Null = no persistence.
@@ -52,6 +54,8 @@ import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-bra
  * @typedef {Object} ToolContext
  * @property {string} [workspace]
  * @property {string} [repoRoot]
+ * @property {ReadonlyArray<string>} [additionalReadRoots]
+ * @property {ReadonlyArray<string>} [additionalWriteRoots]
  * @property {string} [runId]
  * @property {string} [toolArtifactDir]
  * @property {string} [ripgrepPath]
@@ -69,6 +73,8 @@ import { DEFAULT_RUNTIME_BRAND, resolveRuntimeBrand } from "../../../runtime-bra
 const TOOL_CONTEXT_KEYS = /** @type {const} */ ([
   "workspace",
   "repoRoot",
+  "additionalReadRoots",
+  "additionalWriteRoots",
   "runId",
   "toolArtifactDir",
   "ripgrepPath",
@@ -89,6 +95,8 @@ export function createToolContext(input = {}) {
   const ctx = {
     workspace: undefined,
     repoRoot: undefined,
+    additionalReadRoots: undefined,
+    additionalWriteRoots: undefined,
     runId: undefined,
     toolArtifactDir: undefined,
     ripgrepPath: undefined,

package/src/agent/tools/web-access-interstitial.js

@@ -0,0 +1,70 @@
+// @ts-check
+
+const MAX_INTERSTITIAL_SAMPLE_CHARS = 32 * 1024;
+
+/**
+ * Classify access and authentication interstitials without treating incidental
+ * words such as "captcha" or "access denied" as conclusive evidence.
+ *
+ * @param {{url?: string, text?: string, statusCode?: number}} input
+ * @returns {{code: "access_challenge"|"authentication_required", message: string}|undefined}
+ */
+export function classifyWebAccessInterstitial({ url, text, statusCode } = {}) {
+  const finalUrl = String(url || "");
+  const pathname = urlPathname(finalUrl);
+  const sample = normalizedSample(text);
+
+  const challengeArtifact = /\b(?:cf-chl-[\w-]+|cloudflare ray id|challenge-platform)\b/iu.test(sample);
+  const humanCheck = /\bverify (?:you are|that you are)(?: a)? human\b/iu.test(sample);
+  const browserCheck = /\bchecking your browser before accessing\b|\bunusual traffic from (?:your computer|this computer) network\b/iu.test(sample);
+  const securityVerification = /\bperforming security verification\b/iu.test(sample);
+  const javascriptCookieGate = /\benable javascript and cookies to continue\b/iu.test(sample);
+  const waitHeading = /\bjust a moment(?:\.{1,3})?\b/iu.test(sample);
+  const blockedAccess = /\baccess denied\b[\s\S]{0,240}\b(?:blocked|permission|reference|administrator)\b/iu.test(sample);
+
+  if (/\/(?:captcha|challenge)(?:\/|$)/iu.test(pathname)
+    || challengeArtifact
+    || humanCheck
+    || browserCheck
+    || blockedAccess
+    || (securityVerification && javascriptCookieGate)
+    || (waitHeading && (securityVerification || javascriptCookieGate))) {
+    return {
+      code: "access_challenge",
+      message: "Page presented an access challenge; no bypass was attempted.",
+    };
+  }
+
+  if (statusCode === 401 || statusCode === 407
+    || /\/(?:login|signin|sign-in)(?:\/|$)/iu.test(pathname)
+    || /\bauthentication required\b/iu.test(sample)
+    || /\b(?:sign|log) in to continue\b/iu.test(sample)
+    || (/\bsession (?:has )?expired\b/iu.test(sample) && /\b(?:sign|log) in\b/iu.test(sample))) {
+    return {
+      code: "authentication_required",
+      message: "Page requires authentication; no login was attempted.",
+    };
+  }
+  return undefined;
+}
+
+function urlPathname(value) {
+  try { return new URL(value).pathname; }
+  catch { return ""; }
+}
+
+/**
+ * @param {{url?: string, text?: string, statusCode?: number}} input
+ */
+export function assertNoWebAccessInterstitial(input) {
+  const classified = classifyWebAccessInterstitial(input);
+  if (classified) throw Object.assign(new Error(classified.message), { code: classified.code });
+}
+
+function normalizedSample(value) {
+  return String(value || "")
+    .slice(0, MAX_INTERSTITIAL_SAMPLE_CHARS)
+    .replace(/<[^>]*>/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+}

package/src/agent/tools/web-browser-render.js

@@ -7,11 +7,37 @@ import { passthroughSandbox } from "../sandbox-seam.js";
 import { runPreparedProcess } from "./shared/process-runner.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
 import { resolveSandboxPolicy } from "./shared/tool-context.js";
+import { assertNoWebAccessInterstitial } from "./web-access-interstitial.js";
 
 const BROWSER_TIMEOUT_MS = 20_000;
 const BROWSER_CLOSE_TIMEOUT_MS = 5_000;
 const BROWSER_OUTPUT_BYTES = 2 * 1024 * 1024;
 const MAX_BROWSER_NAMESPACE_CHARS = 16;
+const BROWSER_HOST_ENV_KEYS = [
+  "COMSPEC", "HOME", "LANG", "LC_ALL", "LC_CTYPE", "LOGNAME", "PATH", "PATHEXT",
+  "SHELL", "SystemRoot", "TEMP", "TMP", "TMPDIR", "USER", "WINDIR",
+];
+const BLOCKED_BROWSER_ENV_KEYS = [
+  "ALL_PROXY", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "all_proxy", "http_proxy", "https_proxy", "no_proxy",
+  "AGENT_BROWSER_ACTION_POLICY", "AGENT_BROWSER_ALLOWED_DOMAINS", "AGENT_BROWSER_ALLOW_FILE_ACCESS",
+  "AGENT_BROWSER_ANNOTATE", "AGENT_BROWSER_ARGS", "AGENT_BROWSER_CDP", "AGENT_BROWSER_COLOR_SCHEME",
+  "AGENT_BROWSER_CONFIRM_ACTIONS", "AGENT_BROWSER_CONFIRM_INTERACTIVE", "AGENT_BROWSER_CONTENT_BOUNDARIES",
+  "AGENT_BROWSER_DEFAULT_TIMEOUT", "AGENT_BROWSER_DOWNLOAD_PATH", "AGENT_BROWSER_ENABLE",
+  "AGENT_BROWSER_ENCRYPTION_KEY", "AGENT_BROWSER_ENGINE", "AGENT_BROWSER_EXECUTABLE_PATH",
+  "AGENT_BROWSER_EXTENSIONS", "AGENT_BROWSER_HEADED", "AGENT_BROWSER_HIDE_SCROLLBARS",
+  "AGENT_BROWSER_IDLE_TIMEOUT_MS", "AGENT_BROWSER_IGNORE_HTTPS_ERRORS", "AGENT_BROWSER_INIT_SCRIPTS",
+  "AGENT_BROWSER_IOS_DEVICE", "AGENT_BROWSER_IOS_UDID", "AGENT_BROWSER_MAX_OUTPUT",
+  "AGENT_BROWSER_NAMESPACE", "AGENT_BROWSER_NO_AUTO_DIALOG", "AGENT_BROWSER_NO_XVFB",
+  "AGENT_BROWSER_PLUGINS", "AGENT_BROWSER_PROFILE", "AGENT_BROWSER_PROVIDER", "AGENT_BROWSER_PROXY",
+  "AGENT_BROWSER_PROXY_BYPASS", "AGENT_BROWSER_RESTORE", "AGENT_BROWSER_RESTORE_CHECK_FN",
+  "AGENT_BROWSER_RESTORE_CHECK_TEXT", "AGENT_BROWSER_RESTORE_CHECK_URL", "AGENT_BROWSER_SANDBOX_VERSION",
+  "AGENT_BROWSER_SCREENSHOT_DIR", "AGENT_BROWSER_SCREENSHOT_FORMAT", "AGENT_BROWSER_SCREENSHOT_QUALITY",
+  "AGENT_BROWSER_SESSION", "AGENT_BROWSER_SESSION_NAME", "AGENT_BROWSER_SKILLS_DIR",
+  "AGENT_BROWSER_SNAPSHOT_ID", "AGENT_BROWSER_SOCKET_DIR", "AGENT_BROWSER_STATE",
+  "AGENT_BROWSER_STATE_EXPIRE_DAYS", "AGENT_BROWSER_STREAM_PORT", "AGENT_BROWSER_USER_AGENT",
+  "AGENT_BROWSER_WEBGPU",
+];
 
 /**
  * Render one public page in a fresh anonymous agent-browser session.
@@ -42,6 +68,13 @@ export async function renderWithAgentBrowser(
   let tempDir = null;
   let unregister = () => {};
   let closed = false;
+  const renderDeadlineAt = Date.now() + BROWSER_TIMEOUT_MS;
+
+  function remainingRenderMs() {
+    const remaining = renderDeadlineAt - Date.now();
+    if (remaining <= 0) throw Object.assign(new Error(`agent-browser timed out after ${BROWSER_TIMEOUT_MS}ms`), { code: "browser_render_failed" });
+    return remaining;
+  }
 
   async function closeSession() {
     if (closed) return;
@@ -85,59 +118,9 @@ export async function renderWithAgentBrowser(
         args: [...baseArgs, ...commandArgs],
         cwd: workspace,
         env: {
-          // Delete every documented agent-browser behavior/auth/persistence
-          // override inherited from the host. Empty strings are not safe here:
-          // agent-browser treats some of them (notably SESSION_NAME) as
-          // configured-but-invalid values.
-          AGENT_BROWSER_ACTION_POLICY: undefined,
-          AGENT_BROWSER_ALLOWED_DOMAINS: undefined,
-          AGENT_BROWSER_ANNOTATE: undefined,
-          AGENT_BROWSER_ARGS: undefined,
-          AGENT_BROWSER_COLOR_SCHEME: undefined,
-          AGENT_BROWSER_CONFIRM_ACTIONS: undefined,
-          AGENT_BROWSER_CONFIRM_INTERACTIVE: undefined,
-          AGENT_BROWSER_CONTENT_BOUNDARIES: undefined,
-          AGENT_BROWSER_DEFAULT_TIMEOUT: undefined,
-          AGENT_BROWSER_DOWNLOAD_PATH: undefined,
-          AGENT_BROWSER_ENABLE: undefined,
-          AGENT_BROWSER_ENCRYPTION_KEY: undefined,
-          AGENT_BROWSER_ENGINE: undefined,
-          AGENT_BROWSER_EXECUTABLE_PATH: undefined,
-          AGENT_BROWSER_EXTENSIONS: undefined,
-          AGENT_BROWSER_HEADED: undefined,
-          AGENT_BROWSER_HIDE_SCROLLBARS: undefined,
-          AGENT_BROWSER_IDLE_TIMEOUT_MS: undefined,
-          AGENT_BROWSER_INIT_SCRIPTS: undefined,
-          AGENT_BROWSER_IOS_DEVICE: undefined,
-          AGENT_BROWSER_IOS_UDID: undefined,
-          AGENT_BROWSER_MAX_OUTPUT: undefined,
-          AGENT_BROWSER_NAMESPACE: undefined,
-          AGENT_BROWSER_NO_AUTO_DIALOG: undefined,
-          AGENT_BROWSER_NO_XVFB: undefined,
-          AGENT_BROWSER_PLUGINS: undefined,
-          AGENT_BROWSER_PROFILE: undefined,
-          AGENT_BROWSER_PROVIDER: undefined,
-          AGENT_BROWSER_PROXY: undefined,
-          AGENT_BROWSER_PROXY_BYPASS: undefined,
-          AGENT_BROWSER_RESTORE: undefined,
-          AGENT_BROWSER_RESTORE_CHECK_FN: undefined,
-          AGENT_BROWSER_RESTORE_CHECK_TEXT: undefined,
-          AGENT_BROWSER_RESTORE_CHECK_URL: undefined,
-          AGENT_BROWSER_SCREENSHOT_DIR: undefined,
-          AGENT_BROWSER_SCREENSHOT_FORMAT: undefined,
-          AGENT_BROWSER_SCREENSHOT_QUALITY: undefined,
-          AGENT_BROWSER_SESSION: undefined,
-          AGENT_BROWSER_SESSION_NAME: undefined,
-          AGENT_BROWSER_SKILLS_DIR: undefined,
-          AGENT_BROWSER_SOCKET_DIR: undefined,
-          AGENT_BROWSER_STATE: undefined,
-          AGENT_BROWSER_STATE_EXPIRE_DAYS: undefined,
-          AGENT_BROWSER_STREAM_PORT: undefined,
-          AGENT_BROWSER_USER_AGENT: undefined,
-          AGENT_BROWSER_WEBGPU: undefined,
+          ...isolatedBrowserEnvironment(),
           AGENT_BROWSER_AUTO_CONNECT: "false",
           AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: "0",
-          AGENT_BROWSER_CDP: undefined,
           AGENT_BROWSER_CONFIG: configPath,
           AGENT_BROWSER_RESTORE_SAVE: "never",
           NO_COLOR: "1",
@@ -145,10 +128,14 @@ export async function renderWithAgentBrowser(
       },
     });
     try {
-      const result = await runPreparedProcess(prepared, {
+      const result = await runPreparedProcess({
+        ...prepared,
+        env: isolatedBrowserEnvironment(prepared.env, configPath),
+      }, {
         timeoutMs,
         signal: abortSignal,
         maxBufferBytes: BROWSER_OUTPUT_BYTES,
+        exactEnvironment: true,
       });
       if (result.timedOut) throw new Error(`agent-browser timed out after ${timeoutMs}ms`);
       if (result.aborted) throw new Error("agent-browser was aborted");
@@ -156,7 +143,7 @@ export async function renderWithAgentBrowser(
       if (result.spawnError) throw result.spawnError;
       if (result.signal) throw new Error(`agent-browser terminated by ${result.signal}`);
       if (result.code !== 0) {
-        throw new Error(`agent-browser exited ${result.code}: ${String(result.stderr || result.stdout).trim()}`);
+        throw new Error(`agent-browser exited ${result.code}`);
       }
       return String(result.stdout || "").trim();
     } finally {
@@ -168,17 +155,55 @@ export async function renderWithAgentBrowser(
     tempDir = await mkdtemp(join(workspace, ".mono-agent-web-"));
     await writeFile(join(tempDir, "agent-browser.json"), "{}\n", { encoding: "utf8", mode: 0o600 });
     unregister = registerCleanup?.(closeSession) ?? (() => {});
-    await run(["open", parsed.href]);
-    await run(["wait", "--load", "domcontentloaded"]);
-    const output = await run(["read"]);
+    await run(["open", parsed.href], remainingRenderMs());
+    await run(["wait", "--load", "domcontentloaded"], remainingRenderMs());
+    const finalUrlOutput = await run(["get", "url"], remainingRenderMs());
+    const finalUrl = validateFinalUrl(extractBrowserText(finalUrlOutput), parsed, sandbox, policy);
+    const output = await run(["read"], remainingRenderMs());
     const text = extractBrowserText(output);
     if (!text) throw new Error("agent-browser returned no readable rendered content");
-    return text;
+    assertNoWebAccessInterstitial({ url: finalUrl, text });
+    return { text, finalUrl };
   } finally {
     await closeSession();
   }
 }
 
+function validateFinalUrl(value, requested, sandbox, policy) {
+  let finalUrl;
+  try { finalUrl = new URL(String(value || "").trim()); }
+  catch { throw Object.assign(new Error("agent-browser returned an invalid final URL"), { code: "browser_render_failed" }); }
+  if (!["http:", "https:"].includes(finalUrl.protocol) || finalUrl.username || finalUrl.password) {
+    throw Object.assign(new Error("agent-browser navigated to an unsupported final URL"), { code: "network_denied" });
+  }
+  const requestedHost = requested.hostname.toLowerCase();
+  const finalHost = finalUrl.hostname.toLowerCase();
+  if (!(finalHost === requestedHost || finalHost.endsWith(`.${requestedHost}`))
+    || !sandbox.networkAllowsUrl(policy, finalUrl.href)) {
+    throw Object.assign(new Error("agent-browser final URL is outside the allowed domain policy"), { code: "network_denied" });
+  }
+  return finalUrl.href;
+}
+
+function isolatedBrowserEnvironment(source = process.env, configPath) {
+  /** @type {Record<string, string|undefined>} */
+  const env = {};
+  for (const key of BROWSER_HOST_ENV_KEYS) {
+    const value = source?.[key];
+    if (value !== undefined) env[key] = value;
+  }
+  // Undefined means deletion to the sandbox seam. runPreparedProcess then
+  // receives this map as an exact environment, so omitted host variables
+  // cannot reappear during its ordinary process.env merge.
+  for (const key of BLOCKED_BROWSER_ENV_KEYS) env[key] = undefined;
+  env.AGENT_BROWSER_AUTO_CONNECT = "false";
+  env.AGENT_BROWSER_AUTOSAVE_INTERVAL_MS = "0";
+  if (configPath !== undefined) env.AGENT_BROWSER_CONFIG = configPath;
+  env.AGENT_BROWSER_RESTORE_SAVE = "never";
+  env.NO_COLOR = "1";
+  return env;
+}
+
 function compactBrowserNamespace(value) {
   const candidate = String(value || "").trim();
   if (/^[A-Za-z0-9_-]+$/u.test(candidate) && candidate.length <= MAX_BROWSER_NAMESPACE_CHARS) {
@@ -206,7 +231,7 @@ function findText(value, depth = 0) {
     return value.map((entry) => findText(entry, depth + 1)).filter(Boolean).join("\n").trim();
   }
   if (typeof value !== "object") return "";
-  for (const key of ["markdown", "content", "text", "result", "output", "data"]) {
+  for (const key of ["markdown", "content", "text", "url", "result", "output", "data"]) {
     if (!(key in value)) continue;
     const text = findText(value[key], depth + 1);
     if (text) return text;

package/src/agent/tools/web-controller.js

@@ -1,10 +1,11 @@
 // @ts-check
 
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readToolRuntime } from "./shared/runtime-context.js";
 import { resolveSandboxPolicy } from "./shared/tool-context.js";
-import { performWebFetch } from "./web-fetch.js";
+import { performWebFetch, formatWebFetchDocument } from "./web-fetch.js";
 import { performWebSearch } from "./web-search.js";
+import { createWebSearchRunState, webSearchBudgetSnapshot } from "./web-search-state.js";
 
 const MAX_CACHE_ENTRIES = 64;
 const MAX_SHARED_SEARCH_ENTRIES = 256;
@@ -28,10 +29,12 @@ const sharedSearchCache = new Map();
  * cleanup. Search results are the exception: they live in the process-wide
  * cache above so sibling subagents and later turns can reuse them.
  *
- * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any, codexSearch?: any}} [options]
+ * @param {{coordinator?: any, searchConfig?: any, searchState?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any, codexSearch?: any}} [options]
  */
 export function createWebToolController({
+  coordinator,
   searchConfig,
+  searchState: suppliedSearchState,
   fetchConfig,
   sandboxPolicy,
   sandboxEngine,
@@ -46,6 +49,7 @@ export function createWebToolController({
   const fetchInFlight = new Map();
   const cleanups = new Set();
   let closed = false;
+  const searchState = createWebSearchRunState(searchConfig, suppliedSearchState);
 
   function registerCleanup(cleanup) {
     if (closed) {
@@ -74,7 +78,7 @@ export function createWebToolController({
       const result = await task;
       if (!result.error) {
         cache.set(key, cloneResult(result));
-        while (cache.size > MAX_CACHE_ENTRIES) {
+        while (cache.size > MAX_CACHE_ENTRIES || [...cache.values()].reduce((n, r) => n + Buffer.byteLength(r.document?.body || "", "utf8"), 0) > 32 * 1024 * 1024) {
           cache.delete(cache.keys().next().value);
         }
       }
@@ -88,12 +92,15 @@ export function createWebToolController({
    * @param {string} key
    * @param {() => Promise<any>} execute
    */
-  async function cachedSearch(key, execute) {
+  async function cachedSearch(key, query, execute) {
     if (closed) return closedResult();
     const cached = readSharedSearch(key);
-    if (cached) return withCacheHit(cached);
+    if (cached) return withSearchCacheHit(cached, searchState, query);
     const active = searchInFlight.get(key);
-    if (active) return withCacheHit(await active);
+    if (active) {
+      const result = await active;
+      return result.error ? withCacheHit(result) : withSearchCacheHit(result, searchState, query);
+    }
     const task = Promise.resolve().then(execute);
     searchInFlight.set(key, task);
     try {
@@ -111,6 +118,7 @@ export function createWebToolController({
     namespace,
 
     async search(params, execution = {}) {
+      if (execution.signal?.aborted) return { text: "Error: WebSearch was aborted.", error: true, outcome: { status: "error", code: "aborted" } };
       // The key must pin the backend, the endpoint AND the network policy the
       // search actually ran under. A params-only key was safe while the cache
       // lived and died with one run; process-wide it would let controllers with
@@ -132,30 +140,37 @@ export function createWebToolController({
       // strict as the key claims.
       const resolvedCtx = ctx ?? readToolRuntime();
       const policy = resolveSandboxPolicy(resolvedCtx, sandboxPolicy);
-      const key = stableKey({ params, searchConfig, policy });
-      return cachedSearch(key, async () => performWebSearch(params, {
+      const key = stableKey({ params, searchConfig: safeSearchCacheIdentity(searchConfig), policy, coordination: coordinator?.scope });
+      return cachedSearch(key, params.query, async () => performWebSearch(params, {
+        coordinator,
         searchConfig,
         sandboxPolicy: policy,
         ctx: resolvedCtx,
         fetchImpl,
         codexSearch,
+        searchState,
         signal: execution.signal,
       }));
     },
 
     async fetch(params, execution = {}) {
-      const key = stableKey(params);
-      return cachedRun(fetchCache, fetchInFlight, key, async () => performWebFetch(params, {
-        fetchConfig,
-        sandboxPolicy,
-        sandboxEngine,
-        ctx,
-        fetchImpl,
-        browserRenderer,
-        signal: execution.signal,
-        namespace,
-        registerCleanup,
+      if (execution.signal?.aborted) return { text: "Error: WebFetch was aborted.", error: true, outcome: { status: "error", code: "aborted" } };
+      const resolvedCtx = ctx ?? readToolRuntime();
+      const policy = resolveSandboxPolicy(resolvedCtx, sandboxPolicy);
+      const { start_line, max_lines, max_output_chars, ...request } = params;
+      if ((start_line !== undefined && (!Number.isSafeInteger(start_line) || start_line < 1))
+        || (max_lines !== undefined && (!Number.isSafeInteger(max_lines) || max_lines < 1 || max_lines > 10000))) {
+        return { text: "Error: Invalid WebFetch line range.", error: true, outcome: { status: "error", code: "invalid_range" } };
+      }
+      const key = stableKey({ request, fetchConfig, policy, coordination: coordinator?.scope });
+      const result = await cachedRun(fetchCache, fetchInFlight, key, async () => performWebFetch(request, {
+        documentOnly: true, coordinator, fetchConfig, sandboxPolicy: policy, sandboxEngine,
+        ctx: resolvedCtx, fetchImpl, browserRenderer, signal: execution.signal,
+        namespace, registerCleanup,
       }));
+      if (result.error || !result.document) return result;
+      const sliced = formatWebFetchDocument({ ...result.document, outcome: result.outcome }, params, resolvedCtx);
+      return { ...sliced, document: undefined, outcome: { ...sliced.outcome, cacheHit: result.outcome.cacheHit } };
     },
 
     async close() {
@@ -174,6 +189,19 @@ export function createWebToolController({
   };
 }
 
+function safeSearchCacheIdentity(searchConfig) {
+  if (!searchConfig || typeof searchConfig !== "object") return searchConfig;
+  const { maxRequestsPerRun: _budget, ...identity } = searchConfig;
+  if (typeof searchConfig?.ollama?.apiKey !== "string") return identity;
+  return {
+    ...identity,
+    ollama: {
+      ...searchConfig.ollama,
+      apiKey: `sha256:${createHash("sha256").update(searchConfig.ollama.apiKey).digest("hex")}`,
+    },
+  };
+}
+
 function readSharedSearch(key) {
   const entry = sharedSearchCache.get(key);
   if (!entry) return null;
@@ -218,7 +246,15 @@ function sortValue(value) {
 function cloneResult(result) {
   return {
     ...result,
-    outcome: result.outcome ? { ...result.outcome } : result.outcome,
+    outcome: result.outcome ? {
+      ...result.outcome,
+      ...(Array.isArray(result.outcome.providerAttempts)
+        ? { providerAttempts: result.outcome.providerAttempts.map((entry) => ({ ...entry })) }
+        : {}),
+      ...(Array.isArray(result.outcome.failureMetadata)
+        ? { failureMetadata: result.outcome.failureMetadata.map((entry) => ({ ...entry })) }
+        : {}),
+    } : result.outcome,
   };
 }
 
@@ -228,10 +264,65 @@ function withCacheHit(result) {
     outcome: {
       ...(result.outcome || {}),
       cacheHit: true,
+      attempts: 0, durationMs: 0, queueWaitMs: 0, backendDurationMs: 0,
+      cooldownSkipCount: 0, quotaSkipCount: 0,
+      ...(Number.isSafeInteger(result.outcome?.requestsThisCall) ? { requestsThisCall: 0 } : {}),
     },
   };
 }
 
+function withSearchCacheHit(result, searchState, requestedQuery) {
+  const cloned = withCacheHit(result);
+  const budget = webSearchBudgetSnapshot(searchState, 0);
+  const resultCount = Number.isSafeInteger(cloned.outcome?.resultCount) ? cloned.outcome.resultCount : 0;
+  const nextAction = resultCount > 0
+    ? "fetch_existing_sources"
+    : budget.requestsRemaining > 0 ? "refine_query" : "use_available_evidence";
+  const action = nextAction === "fetch_existing_sources"
+    ? "Use WebFetch on the strongest returned URLs before searching again."
+    : nextAction === "refine_query"
+      ? "Refine the query only for a material evidence gap."
+      : "Do not retry WebSearch in this run; use available evidence and state the limitation.";
+  const control = `[Search control: requests=${budget.requestsUsed}/${budget.maxRequestsPerRun}; remaining=${budget.requestsRemaining}; ${action}]`;
+  const query = collapseWhitespace(requestedQuery).slice(0, 500);
+  const metadata = `[Search metadata: backend=${cloned.outcome?.backend || "unknown"}; attempted=none; actual_query=${JSON.stringify(query)}; fallback=none]`;
+  const textWithControl = typeof cloned.text === "string" && cloned.text.startsWith("[Search control:")
+    ? cloned.text.replace(/^\[Search control:[^\n]*\]/u, control)
+    : `${control}\n${cloned.text}`;
+  const text = textWithControl.includes("[Search metadata:")
+    ? textWithControl.replace(/^\[Search metadata:[^\n]*\]/mu, metadata)
+    : textWithControl.replace("[BEGIN UNTRUSTED WEB SEARCH RESULTS]", `[BEGIN UNTRUSTED WEB SEARCH RESULTS]\n${metadata}`);
+  const {
+    retryAfterMs: _retryAfterMs,
+    retryAt: _retryAt,
+    retryAtMs: _retryAtMs,
+    ...cachedOutcome
+  } = cloned.outcome || {};
+  return {
+    ...cloned,
+    text,
+    outcome: {
+      ...cachedOutcome,
+      ...budget,
+      bytes: Buffer.byteLength(text, "utf8"),
+      attemptedBackends: [],
+      actualQueries: [],
+      providerAttempts: [],
+      failureMetadata: [],
+      providerFailureCount: 0,
+      rateLimited: false,
+      cooldownBackends: [],
+      fallbackUsed: false,
+      retryInRun: budget.requestsRemaining > 0,
+      nextAction,
+    },
+  };
+}
+
+function collapseWhitespace(value) {
+  return typeof value === "string" ? value.replace(/\s+/gu, " ").trim() : "";
+}
+
 function closedResult() {
   const text = "Error: Web tool controller has already closed.";
   return {