mixdog 1.3.4 → 1.4.0

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/shell-cwd.mjs

@@ -0,0 +1,38 @@
+// The shell tool's optional `cwd` argument: where one command runs. Omitted,
+// the command runs in the session cwd; a relative value resolves against it.
+import { stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+// `~`, `~/x` (and `~\x` on Windows) name the user's home folder.
+function expandHome(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/') || (process.platform === 'win32' && path.startsWith('~\\'))) {
+    return resolve(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+/** The directory a shell call runs in: its `cwd` argument resolved against the session cwd. */
+export function effectiveShellCwd(args, sessionCwd) {
+  const requested = args?.cwd;
+  // Trim only decides blank; a name with edge spaces is used as given.
+  if (typeof requested !== 'string' || requested.trim() === '') return sessionCwd;
+  return resolve(sessionCwd || process.cwd(), expandHome(requested));
+}
+
+/** The cwd hooks and approvals see for a tool call: the effective one for shell, the session cwd otherwise. */
+export function effectiveToolCwd(toolName, args, sessionCwd) {
+  return toolName === 'shell' ? effectiveShellCwd(args, sessionCwd) : sessionCwd;
+}
+
+/** An error naming the path when `dir` is not an existing directory, else null. */
+export async function shellCwdError(dir) {
+  let info;
+  try {
+    info = await stat(dir);
+  } catch {
+    return `shell cwd "${dir}" does not exist`;
+  }
+  return info.isDirectory() ? null : `shell cwd "${dir}" is not a directory`;
+}

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool.mjs

@@ -25,6 +25,8 @@ import { planShellDeadlines } from './bash-tool/deadline-plan.mjs';
 import { planShellInvocation } from './bash-tool/invocation-plan.mjs';
 import { renderBackgroundedResult } from './bash-tool/backgrounded-result.mjs';
 import { renderCompletedResult } from './bash-tool/completed-result.mjs';
+import { effectiveShellCwd, shellCwdError } from './bash-tool/shell-cwd.mjs';
+import { guardShellCall, requestedShellType } from './bash-tool/misuse-guard.mjs';
 
 export {
   SURVIVING_DESCENDANTS_WARNING,
@@ -64,9 +66,26 @@ function settleMutationCaches(shellEffects, backgroundJobId, runSettled = null)
 }
 
 export async function executeBashTool(args, workDir, options = {}) {
-  // Every call starts from the current Project root. A command-local `cd`
-  // never creates a second session cwd authority beside the dedicated cwd tool.
-  const bashWorkDir = workDir;
+  // The tool-exec layer already guarded the call before its hooks ran and left
+  // its notes; a direct caller is guarded here.
+  const guarded = Array.isArray(options?.shellGuardNotes)
+    ? { args, notes: options.shellGuardNotes }
+    : guardShellCall(args, {
+        shellType: requestedShellType(args),
+        agent: options?.agent,
+        sessionId: options?.sessionId,
+        telemetry: options?.resultTelemetry,
+      });
+  if (guarded.failure) return guarded.failure;
+  args = guarded.args;
+  const guardNotes = guarded.notes;
+  // A call starts from the current Project root unless it names a `cwd`. A
+  // command-local `cd` never creates a second session cwd authority beside it.
+  const bashWorkDir = effectiveShellCwd(args, workDir);
+  if (bashWorkDir !== workDir) {
+    const cwdError = await shellCwdError(bashWorkDir);
+    if (cwdError) return formatShellToolFailure(cwdError);
+  }
   // Approval comes from the runtime's options, never from model-supplied args.
   const elevationApproved = options?.elevationApproved === true;
   const prepared = prepareShellCommand(args, { elevationApproved });
@@ -106,6 +125,7 @@ export async function executeBashTool(args, workDir, options = {}) {
       shellArg: invocation.execShellArg,
       shellArgs: invocation.execShellArgs,
       command: invocation.wrappedCommand,
+      displayCommand: command,
       execScript: invocation.execScript,
       directArgv: invocation.directArgv,
       elevationApproved,
@@ -147,12 +167,12 @@ export async function executeBashTool(args, workDir, options = {}) {
       stdout,
       stderr,
     };
-    if (backgrounded) return renderBackgroundedResult(rendering);
+    if (backgrounded) return renderBackgroundedResult({ ...rendering, notes: guardNotes.join('\n') });
     return renderCompletedResult({
       ...rendering,
       analysisCommand,
       timeout: deadlines.timeout,
-      rewriteNote: [wmicRewrite?.note, bashismRewrite?.note].filter(Boolean).join('\n'),
+      rewriteNote: [wmicRewrite?.note, bashismRewrite?.note, ...guardNotes].filter(Boolean).join('\n'),
     });
   } finally {
     inputWake?.dispose();

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -27,13 +27,67 @@ export const TASK_WAIT_TIMEOUT_DEFAULT_MS = TASK_WAIT_DEFAULT_MS;
 export const TASK_WAIT_TIMEOUT_MIN_MS = TASK_WAIT_MIN_MS;
 export const TASK_WAIT_TIMEOUT_MAX_MS = TASK_WAIT_MAX_MS;
 const _holdS = budgetSeconds(SHELL_HOLD_DEFAULT_MS);
-const _shellSyntaxCheat =
-  process.platform === 'win32'
-    ? " PowerShell: ; between independent commands, if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } between dependent ones; no heredoc, </dev/null or | head/tail/wc (Select-Object -First/-Last); multiline python/node via @'…'@ | python - (node -); 2>$null; /c/→C:\\; $PID is reserved."
-    : ' Bash: chain dependent commands with &&; multiline input via a quoted heredoc delimiter, not extra quoting/escape layers.';
 // Process-stable switch used to describe foreground-only execution accurately.
 const _shellBackgroundDisabled = envFlag('MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS');
 
+// Shell kinds the description is written for: 'powershell' or 'posix' (bash,
+// zsh, sh, Git Bash, WSL), the `shellType` of the runtime's resolved shell.
+// BUILTIN_TOOLS is static, so it carries the platform's default kind; a
+// session whose configured system shell is the other kind gets the matching
+// text through bindShellKind where the session tool schema is assembled.
+const _defaultShellKind = process.platform === 'win32' ? 'powershell' : 'posix';
+
+// The kind's banned commands → replacement tool. `edit/apply_patch` is
+// rewritten per model by the edit-dialect surface filter.
+export function buildShellRoutingRules(kind = _defaultShellKind) {
+  const pairs =
+    kind === 'powershell'
+      ? 'Get-Content/gc/cat/type→read; Get-ChildItem/dir/ls→list/glob/find; Select-String/findstr→grep; Set-Content/Add-Content/Out-File/`>`→edit/apply_patch'
+      : 'cat/head/tail/less→read; ls/tree→list; find→glob/find; grep/rg/ag→grep; file authoring via sed/awk/echo >/tee/heredoc→edit/apply_patch';
+  return `Never use shell commands/scripts for work other tools cover: ${pairs}; git→git (-C <dir> for other folders); code structure→code_graph.`;
+}
+
+function buildShellDescription(kind) {
+  const run = _shellBackgroundDisabled
+    ? 'Commands run in the foreground until completion.'
+    : `Holds ${_holdS}s; then, or on input/task notification, backgrounds with task_id (command keeps running). Completion is automatic; never poll, and never sleep/poll-loop inside the shell (background:true or wait_ms instead; for an external job, background a command that exits when it ends). Result needed now: task wait. Known-long finite run: wait_ms up to ${SHELL_HOLD_MAX_MS}. Independent long runs, servers/watchers: background:true; cancel them when done.`;
+  return `Run programs, builds, tests and computation. ${buildShellRoutingRules(kind)} ${run}`;
+}
+
+function buildShellCommandDescription(kind) {
+  const cheat =
+    kind === 'powershell'
+      ? " PowerShell: ; between independent commands, if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } between dependent ones; no Bash heredocs or </dev/null; Select-Object shapes program output, not file reads; multiline python/node via @'…'@ | python - (node -); 2>$null; /c/→C:\\; $PID is reserved."
+      : ' Bash: chain dependent commands with &&; multiline input via a quoted heredoc delimiter, not extra quoting/escape layers.';
+  return `Command.${cheat}`;
+}
+
+// One bound copy per (tool, kind), so a session's shell tool keeps its identity
+// and bytes from turn to turn.
+const _boundShellTools = new WeakMap();
+
+/** The shell tool with the text of `kind`, when that differs from the static default. */
+export function bindShellKind(tool, kind) {
+  if (tool?.name !== 'shell' || kind === _defaultShellKind || (kind !== 'powershell' && kind !== 'posix')) return tool;
+  const cached = _boundShellTools.get(tool)?.get(kind);
+  if (cached) return cached;
+  const properties = tool.inputSchema?.properties || {};
+  const bound = {
+    ...tool,
+    description: buildShellDescription(kind),
+    inputSchema: {
+      ...tool.inputSchema,
+      properties: {
+        ...properties,
+        command: { ...properties.command, description: buildShellCommandDescription(kind) },
+      },
+    },
+  };
+  if (!_boundShellTools.has(tool)) _boundShellTools.set(tool, new Map());
+  _boundShellTools.get(tool).set(kind, bound);
+  return bound;
+}
+
 export const BUILTIN_TOOLS = [
   {
     name: 'read',
@@ -151,11 +205,15 @@ export const BUILTIN_TOOLS = [
       openWorldHint: true,
       compressible: true,
     },
-    description: `Run programs, builds, tests and computation. Never use shell commands or scripts for work covered by dedicated tools: cat/head/tail→read, ls→list, find→glob, filename lookup→find, grep/rg→grep, code structure→code_graph, file edits/writes (sed/awk/redirection)→edit/apply_patch, Git→git when that tool is on the surface. Tool names are not shell commands. ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : `Holds up to ${_holdS}s for the result. Still running at ${_holdS}s, or new user input or a task notification arrives: it moves to the background (never killed) and returns task_id plus output so far. Completion is delivered automatically; task wait only when you need the result now. If no execution slot frees, the command is queued as a background task. Dev servers/watchers: background:true, and stop them with task cancel when done.`}`,
+    description: buildShellDescription(_defaultShellKind),
     inputSchema: {
       type: 'object',
       properties: {
-        command: { type: 'string', description: `Command.${_shellSyntaxCheat}` },
+        command: { type: 'string', description: buildShellCommandDescription(_defaultShellKind) },
+        cwd: {
+          type: 'string',
+          description: 'Working directory; default the Project. Use it instead of cd/Set-Location.',
+        },
         timeout_ms: {
           type: 'integer',
           minimum: 0,
@@ -165,7 +223,7 @@ export const BUILTIN_TOOLS = [
           type: 'integer',
           minimum: SHELL_HOLD_MIN_MS,
           maximum: SHELL_HOLD_MAX_MS,
-          description: `Hold in ms before a still-running command moves to the background (default ${SHELL_HOLD_DEFAULT_MS}). Usually omit.`,
+          description: `Hold in ms before a still-running command moves to the background (default ${SHELL_HOLD_DEFAULT_MS}). Usually omit; for a long finite command needed next, set up to ${SHELL_HOLD_MAX_MS}.`,
         },
         background: {
           type: 'boolean',

package/src/runtime/agent/orchestrator/tools/builtin/shell-runtime.mjs

@@ -17,6 +17,10 @@ export function setConfiguredShell(value = '') {
   _resolvedShellByKind.clear();
 }
 
+export function getConfiguredShell() {
+  return _configuredShell || '';
+}
+
 function shellTypeFor(shell) {
   const stem = basename(String(shell || ''))
     .toLowerCase()
@@ -49,7 +53,9 @@ function allExistingPathsFromPath(commandName) {
   let cwd = '';
   try {
     cwd = process.cwd();
-  } catch {}
+  } catch {
+    // the working directory may have been removed; search PATH entries only
+  }
   const entries = [cwd, ...rawPath.split(delimiter)]
     .map((entry) => entry.trim().replace(/^"(.*)"$/, '$1'))
     .filter(Boolean);

package/src/runtime/agent/orchestrator/tools/shell-command.mjs

@@ -112,7 +112,9 @@ function _abortableDelay(ms, signal) {
       if (onAbort && signal) {
         try {
           signal.removeEventListener('abort', onAbort);
-        } catch {}
+        } catch {
+          // the abort listener may already be gone
+        }
       }
       resolveDelay();
     }, ms);
@@ -173,7 +175,9 @@ async function acquireShellLeaseBounded(
     } catch {
       try {
         ctl.abort();
-      } catch {}
+      } catch {
+        // the controller may already be aborted
+      }
     }
   };
   if (abortSignal) {
@@ -184,7 +188,9 @@ async function acquireShellLeaseBounded(
   const deadline = setTimeout(() => {
     try {
       ctl.abort(_admissionSaturationError(admission, waitMs, ownerKey));
-    } catch {}
+    } catch {
+      // the controller may already be aborted
+    }
   }, waitMs);
   if (deadline.unref) deadline.unref();
   try {
@@ -212,7 +218,9 @@ async function acquireShellLeaseBounded(
     if (abortSignal) {
       try {
         abortSignal.removeEventListener('abort', onAbort);
-      } catch {}
+      } catch {
+        // the abort listener may already be gone
+      }
     }
   }
 }
@@ -238,7 +246,7 @@ async function admitAndSpawn(run, params, { admissionWaitMs, onSaturated }) {
     run.resourceLease = await acquireShellLeaseBounded(admission, {
       abortSignal,
       waitMs: admissionWaitMs,
-      label: `[task_id: ${run.foregroundRecordId}] ${String(command || '').slice(0, 120)}`,
+      label: `[task_id: ${run.foregroundRecordId}] ${String(params.displayCommand ?? command ?? '').slice(0, 120)}`,
       ownerKey: ownerSessionId,
     });
     const policyErr = await _execPolicyBlockMessage(command, elevationApproved === true);
@@ -295,11 +303,11 @@ function queueSaturatedAsTask(run, saturation, spec) {
       taskId,
       surface: 'shell',
       operation: 'shell',
-      label: String(spec.command || '')
+      label: String(spec.displayCommand ?? spec.command ?? '')
         .replace(/\s+/g, ' ')
         .slice(0, 120),
       context: { callerSessionId: spec.ownerSessionId, clientHostPid: spec.clientHostPid },
-      input: { command: spec.command, cwd: spec.cwd },
+      input: { command: spec.displayCommand ?? spec.command, cwd: spec.cwd },
       meta: { task_id: taskId, stdout: null, stderr: null, cwd: spec.cwd, timeoutMs: spec.backgroundDeadlineMs || 0 },
       resultType: 'shell_task_result',
       // While the command runs in the foreground, its abort handler snapshots
@@ -311,7 +319,9 @@ function queueSaturatedAsTask(run, saturation, spec) {
         if (!promotedJobId) return;
         try {
           killShellJob(promotedJobId);
-        } catch {}
+        } catch {
+          // the job may already have exited
+        }
       },
       run: async () => {
         const result = await execShellCommand({
@@ -332,7 +342,9 @@ function queueSaturatedAsTask(run, saturation, spec) {
           if (queuedAbort.signal.aborted) {
             try {
               killShellJob(promotedJobId);
-            } catch {}
+            } catch {
+              // the promoted job may already have exited
+            }
           }
           return settleQueuedPromotion(promotedJobId);
         }
@@ -375,7 +387,9 @@ function settleSetupFailure(run, err) {
   clearForegroundTimers(run);
   try {
     treeKill(run.child);
-  } catch {}
+  } catch {
+    // the child may already have exited
+  }
   void releaseResourceLease(run);
   run.resolveResult(failedResult(run, String(err?.message || err), 'spawn failed'));
 }
@@ -451,7 +465,9 @@ function armProgressTimers(run, { onProgress, onOutputTail }) {
       const secs = Math.round(elapsedSinceStart(run) / 1000);
       try {
         onProgress(`running ${secs}s`);
-      } catch {}
+      } catch {
+        // the progress sink is advisory
+      }
     }, 2000);
     if (run.progressTimer.unref) run.progressTimer.unref();
   }
@@ -549,7 +565,9 @@ function armDeadlines(
     };
     try {
       abortSignal.addEventListener('abort', run.abortHandler, { once: true });
-    } catch {}
+    } catch {
+      // caller cancellation registration is best-effort
+    }
   }
 }
 
@@ -588,6 +606,10 @@ export function execShellCommand(options) {
     // hands the script to the shell out-of-band — see the POSIX env+eval path in
     // bash-tool.mjs, which keeps the command body out of the child's argv.
     execScript = null,
+    // What the agent passed, when `command` carries execution wrappers (the
+    // PowerShell UTF-8 prefix, the filter-tee rewrite). Job labels and
+    // records show this text; only the spawn runs `command`.
+    displayCommand = null,
     // The user approved this call's elevation 'ask' decision (runtime-set).
     elevationApproved = false,
   } = options;
@@ -612,6 +634,7 @@ export function execShellCommand(options) {
             abortSignal,
             directArgv,
             execScript,
+            displayCommand,
             elevationApproved,
             ownerSessionId,
             clientHostPid,
@@ -635,7 +658,7 @@ export function execShellCommand(options) {
         attachChildExit(run, releasePromotedCapture);
         const fireAutoBackground = createAutoBackground({
           run,
-          command,
+          command: displayCommand ?? command,
           cwd,
           clientHostPid,
           ownerSessionId,

package/src/runtime/browser-bridge/action-schema.mjs

@@ -101,7 +101,7 @@ const CONTRACT_ROWS = [
   // the host.
   contract(
     'fill',
-    [...POST_ACTION_SNAPSHOT, 'ref', 'target', 'text', 'checked', 'fields', 'submit', 'savedAccount'],
+    [...POST_ACTION_SNAPSHOT, 'ref', 'target', 'text', 'checked', 'fields', 'submit', 'savedAccount', 'sensitive'],
     [['ref', 'text'], ['target', 'text'], ['ref', 'checked'], ['target', 'checked'], ['fields'], ['savedAccount']]
   ),
   contract(
@@ -257,7 +257,6 @@ const SEQUENCE_STEP_STRING_LIMITS = [
   ['textGone', 10_000],
   ['url', 8_192],
   ['key', 100],
-  ['savedAccount', 320],
 ];
 
 // The validation error of one sequence step, '' when it is well-formed.
@@ -688,10 +687,22 @@ function ruleOperationError(action, input) {
   return '';
 }
 
+/** A sensitive fill's text is kept out of every stored transcript (sensitive-values.mjs)
+ *  at any length; an empty one has nothing to protect and is refused. */
+function sensitiveFillError(action, input) {
+  if (action !== 'fill' || input.sensitive !== true) return '';
+  const fields = Array.isArray(input.fields) ? input.fields : [];
+  const values = [input.text, ...fields.flatMap((field) => [field?.text, field?.value])];
+  return values.some((value) => typeof value === 'string' && value.length === 0)
+    ? 'browser action "fill" input.sensitive text must not be empty'
+    : '';
+}
+
 // Action-specific rules, in the order they are reported.
 const ACTION_RULES = [
   navigateError,
   fillFieldsError,
+  sensitiveFillError,
   scrollError,
   screenshotOptionsError,
   snapshotTargetError,

package/src/runtime/browser-bridge/client.mjs

@@ -9,6 +9,7 @@
  */
 import { BROWSER_OBSERVATION_ACTIONS, validateBrowserToolArgs } from './action-schema.mjs';
 import { bridgeDiscoveryChanged, readBridgeDiscovery, readBridgeDiscoveryDetail } from '../bridge-discovery.mjs';
+import { mailLinkFor } from './mail-links.mjs';
 import { traceBrowserTiming } from './timing.mjs';
 import { base64ByteLength, inlineFileKind } from '../shared/inline-file-kind.mjs';
 import { MAX_IMAGE_BYTES, SUPPORTED_IMAGE_MIME_TYPES } from '../attachments/limits.mjs';
@@ -28,6 +29,39 @@ const MAX_IMAGE_BASE64_CHARS = Math.ceil((MAX_IMAGE_BYTES * 4) / 3) + 4;
 const MAX_FILE_BASE64_CHARS = Math.ceil((8 * 1024 * 1024 * 4) / 3) + 4;
 const RETRYABLE_ACTIONS = new Set(BROWSER_OBSERVATION_ACTIONS);
 const browserTurns = new Map();
+/** Sessions that have issued a browser command; only they have turn
+ *  boundaries worth telling the desktop. */
+const browserSessions = new Set();
+
+/** A turn's start, sent before it reasons or runs any tool: the desktop keeps
+ *  the session's pages out of reclaim while a turn is live, even one that never
+ *  issues a browser command. Remembers the bridge so the turn's end reaches it.
+ *  A session that never used the browser has nothing to tell the desktop (its
+ *  first command marks it live there). */
+export async function beginBrowserTurn(sessionId, turnId) {
+  if (!browserSessions.has(sessionId)) return;
+  const discovery = readBridgeDiscovery(DISCOVERY_FILE);
+  if (!discovery || !(turnId > 0)) return;
+  rememberBrowserTurn(sessionId, turnId, discovery);
+  const result = await requestBridgeWithin(
+    discovery,
+    JSON.stringify({ action: 'begin_turn', session_id: sessionId, turn_id: turnId }),
+    undefined,
+    { sessionId, turnId, action: 'begin_turn' }
+  );
+  if (result.status !== 200 || result.body?.ok === false || result.body?.error) {
+    throw new Error(
+      `Browser turn start failed (HTTP ${result.status}): ${result.body?.error || 'bridge rejected start'}`
+    );
+  }
+}
+
+/** The session is gone for good (deleted): it no longer has turn boundaries to
+ *  tell the desktop, and no turn of it will finish. */
+export function forgetBrowserSession(sessionId) {
+  browserSessions.delete(sessionId);
+  browserTurns.delete(sessionId);
+}
 
 /** Terminal lifecycle cleanup uses the exact bridge that owned this turn.
  * It is never retried after dispatch and never inherits the cancelled tool signal. */
@@ -57,13 +91,16 @@ export async function finishBrowserTurn(sessionId, turnId, { aborted = false } =
   }
 }
 
+const SECRET_FILL_OUTCOMES = new Set(['entered', 'no_field', 'page_changed', 'blocked', 'expired']);
+
 /** Runtime-only: fill the secret the user handed the desktop for `requestId`
- *  into the page's focused password field through the host's isolated-world
- *  fill. The value never passes through here; the host answers only
- *  'provided' or 'skipped'. */
+ *  into the field of the page it was bound to (browserHandoffPage), through
+ *  the host's isolated-world fill. The value never passes through here; the
+ *  host answers only the outcome ('entered', 'no_field', 'page_changed',
+ *  'blocked', 'expired'); no desktop or an unknown answer is 'blocked'. */
 export async function browserSecretInput(sessionId, requestId, { signal } = {}) {
   const discovery = readBridgeDiscovery(DISCOVERY_FILE);
-  if (!discovery || !sessionId || !requestId) return 'skipped';
+  if (!discovery || !sessionId || !requestId) return 'blocked';
   try {
     const result = await requestBridgeWithin(
       discovery,
@@ -71,11 +108,33 @@ export async function browserSecretInput(sessionId, requestId, { signal } = {})
       signal,
       { sessionId, action: 'secret_input' }
     );
-    return result.status === 200 && result.body?.ok !== false && result.body?.value?.text === 'provided'
-      ? 'provided'
-      : 'skipped';
+    const text = result.status === 200 && result.body?.ok !== false ? result.body?.value?.text : '';
+    return SECRET_FILL_OUTCOMES.has(text) ? text : 'blocked';
+  } catch {
+    return 'blocked';
+  }
+}
+
+/** Runtime-only facts about a session's page for an ask_user handoff, with no
+ *  value in either direction: `secret_bind` binds `request_id` to the page
+ *  (`tab`, else the agent's page) and says its origin and field kind;
+ *  `login_accounts` lists the masked saved logins of `url`'s origin;
+ *  `page_url` says where the page is now. null when the desktop is absent or
+ *  refuses. */
+export async function browserHandoffPage(sessionId, action, fields = {}, { signal } = {}) {
+  const discovery = readBridgeDiscovery(DISCOVERY_FILE);
+  if (!discovery || !sessionId) return null;
+  try {
+    const result = await requestBridgeWithin(
+      discovery,
+      JSON.stringify({ ...fields, action, session_id: String(sessionId) }),
+      signal,
+      { sessionId, action }
+    );
+    const value = result.status === 200 && result.body?.ok !== false ? result.body?.value : null;
+    return value && typeof value === 'object' ? value : null;
   } catch {
-    return 'skipped';
+    return null;
   }
 }
 
@@ -271,10 +330,15 @@ export async function executeBrowserTool(args, options = {}) {
   if (!validated.ok) return browserToolError(validated.error);
   const sessionId = String(options.sessionId || '').trim();
   if (!sessionId) return browserToolError('browser session context is unavailable');
+  const mailLink = validated.action === 'navigate' ? mailLinkFor(sessionId, validated.input.url) : null;
   const payload = {
     action: validated.action,
     ...validated.input,
     session_id: sessionId,
+    // Runtime-set, never from the model's arguments: this exact URL is a link
+    // of a mail the runtime read for this session (mail-links.mjs), which the
+    // desktop may open although it carries a token.
+    ...(mailLink ? { mail_link: mailLink } : {}),
     // Set by the runtime from the session, never from the model's arguments: a
     // schedule/webhook run (or work it started) whose saved routine is the
     // user's grant for submits, posts and uploads (human-gate/run-policy.mjs).
@@ -291,6 +355,7 @@ export async function executeBrowserTool(args, options = {}) {
   }
   let discovery = readBridgeDiscovery(DISCOVERY_FILE);
   if (!discovery) return browserToolError(unavailableMessage());
+  browserSessions.add(sessionId);
   rememberBrowserTurn(sessionId, payload.turn_id, discovery);
   // An observation can be reported as a plain failure; a state-changing action
   // that may already have run must say so instead.

package/src/runtime/browser-bridge/input-fields.mjs

@@ -56,7 +56,7 @@ export const BROWSER_INPUT_FIELDS = {
       type: 'string',
       enum: ['semantic', 'visual', 'both'],
       description:
-        'snapshot only: semantic refs (default), visual image, or both. Coordinates need both; fullPage and ref/target crops need visual. navigate uses includeScreenshot.',
+        'snapshot only: semantic refs (default), visual, or both. Coordinates need both; fullPage and ref/target crops need visual. navigate: includeScreenshot.',
     },
     fullPage: { type: 'boolean', description: 'Full-document screenshot; inspection-only.' },
     format: {
@@ -132,7 +132,7 @@ export const BROWSER_INPUT_FIELDS = {
       items: { type: 'string', maxLength: 60 },
       minItems: 1,
       maxItems: 12,
-      description: 'extract only: attribute names per match; text and name always included.',
+      description: 'extract only: attribute names per match (text and name always come).',
     },
     operation: {
       type: 'string',
@@ -233,8 +233,7 @@ export const BROWSER_INPUT_FIELDS = {
     downloadId: {
       type: 'string',
       maxLength: 100,
-      description:
-        'downloads only: d1/d2 ID; omitted, wait pins the newest (or next) download and attach takes the newest completed file.',
+      description: 'downloads only: d1/d2 ID; omitted: wait pins the newest (or next), attach the newest completed.',
     },
     wait: { type: 'boolean', description: 'downloads only: wait up to timeoutMs for completion.' },
     attach: { type: 'boolean', description: 'downloads only: attach the completed file (≤ 8 MiB) to the result.' },
@@ -245,11 +244,11 @@ export const BROWSER_INPUT_FIELDS = {
     },
     textGone: { type: 'string', maxLength: 10000, description: 'wait: page-text substring that must disappear.' },
     submit: { type: 'boolean', description: 'fill or type: press Enter afterward.' },
+    sensitive: { type: 'boolean', description: 'fill: code/secret text; redacted in output and transcript.' },
     savedAccount: {
       type: 'string',
-      maxLength: 320,
       description:
-        'fill: account or masked label saved for this HTTPS site; fills the whole sign-in form, password kept on the host. No ref/target/text; submit presses Enter.',
+        'fill: saved login (account or masked label) of this HTTPS site; fills the sign-in form, password stays on the host. No ref/target/text.',
     },
     key: {
       type: 'string',
@@ -326,7 +325,7 @@ export const BROWSER_INPUT_FIELDS = {
           checked: { type: 'boolean' },
           key: { type: 'string', maxLength: 100 },
           submit: { type: 'boolean' },
-          savedAccount: { type: 'string', maxLength: 320, description: 'fill: as input.savedAccount.' },
+          savedAccount: { type: 'string', description: 'fill: as input.savedAccount.' },
           dx: { type: 'integer' },
           dy: { type: 'integer' },
           textGone: { type: 'string', maxLength: 10000 },
@@ -399,12 +398,12 @@ export const BROWSER_INPUT_FIELDS = {
       type: 'string',
       maxLength: 64,
       description:
-        'Session-local page ID p1/p2… from list_tabs (v1/v2 aliases work), or a background page name; background:true creates one. Popups are named background pages.',
+        'Page ID p1/p2… from list_tabs (or v1/v2), or a background page name (background:true makes one; popups get one).',
     },
     background: {
       type: 'boolean',
       description:
-        'true creates/targets a hidden support page; false reveals it until task end; omitted never promotes a named one. open without true keeps it for user handoff.',
+        'true: create/target a hidden support page; false: reveal it until task end; omitted never promotes a named one. open without true keeps it for handoff.',
     },
   },
 };