mixdog 1.3.5 → 1.4.0

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.',
     },
   },
 };

package/src/runtime/browser-bridge/mail-links.mjs

@@ -0,0 +1,107 @@
+// Links in mails the runtime itself read for a session through Mixdog's own
+// Gmail connector (connectors/gmail-app-password.mjs): the one way a link
+// carrying a token (a sign-up or sign-in confirmation) becomes navigable in
+// Browser Use, whose desktop host refuses every other agent URL with one
+// (apps/desktop/src/main/browser/url-policy.ts). A link is recorded from the
+// read_email result the runtime received (session/loop/tool-exec/dispatch.mjs),
+// never from anything the model passes, and is offered only for that exact
+// link, in the same session, for a short time; the desktop checks it again.
+// Only a mail whose one From mailbox Gmail authenticated counts, and only the
+// link targets the connector read from it (its `links`: HTML hyperlinks and
+// the URIs of its text part, exactly as written).
+import { getDomain } from 'tldts';
+
+/** How long after the read a mail's link stays navigable: the lifetime the
+ *  desktop gives a sign-in flow, a 2-step check included
+ *  (apps/desktop/src/main/browser/linked-sign-in.ts FLOW_TTL_MS), which its
+ *  url-policy.ts MAIL_LINK_WINDOW_MS takes and enforces again. */
+export const MAIL_LINK_WINDOW_MS = 30 * 60_000;
+
+/** sessionId → [{ url, from_domain, read_at }], oldest first. */
+const linksBySession = new Map();
+
+/** `domain` as a URL host spells it (IDNs in punycode), '' when it is none. */
+function hostOf(domain) {
+  const text = String(domain || '').toLowerCase();
+  if (!/^[\p{L}\p{N}-]+(?:\.[\p{L}\p{N}-]+)+$/u.test(text)) return '';
+  try {
+    return new URL(`https://${text}/`).hostname;
+  } catch {
+    return '';
+  }
+}
+
+/** The Organizational Domain (RFC 7489 §3.2: by the public suffix list; its
+ *  private suffixes included, as the desktop's url-policy.ts reads it, so
+ *  `a.github.io` is not `b.github.io`); '' for none. */
+const siteOf = (host) => (host ? getDomain(host, { allowPrivateDomains: true }) || '' : '');
+
+/** The From domain of read_email header `head` (connectors/gmail-app-password.mjs)
+ *  when From names exactly one mailbox (with several, RFC 7489 §6.6.1 checks
+ *  each author domain, and one verdict cannot vouch for the one a link names)
+ *  and Gmail authenticated it: DMARC passed for that very
+ *  domain, or a passing DKIM signature's d= is aligned with it in relaxed
+ *  mode — the same Organizational Domain (RFC 7489 §3.1.1). '' otherwise. */
+function authenticatedSender(head) {
+  const from = Array.isArray(head?.fromAddresses) ? head.fromAddresses : [];
+  const address = from.length === 1 ? String(from[0]?.address || '') : '';
+  const host = address.includes('@') ? hostOf(address.slice(address.lastIndexOf('@') + 1)) : '';
+  if (!host) return '';
+  const { dmarc, dkim } = head.authentication || {};
+  if (dmarc?.result === 'pass' && hostOf(dmarc.from) === host) return host;
+  const site = siteOf(host);
+  const signed =
+    Array.isArray(dkim) && dkim.some((sig) => sig?.result === 'pass' && siteOf(hostOf(sig.domain)) === site);
+  return site && signed ? host : '';
+}
+
+/** The normalized https URL `raw` is, or ''. */
+function httpsHref(raw) {
+  try {
+    const url = new URL(raw);
+    return url.protocol === 'https:' && !url.username && !url.password ? url.href : '';
+  } catch {
+    return '';
+  }
+}
+
+function pruneExpired(now) {
+  for (const [sessionId, links] of linksBySession) {
+    const live = links.filter((link) => now - link.read_at <= MAIL_LINK_WINDOW_MS);
+    if (live.length) linksBySession.set(sessionId, live);
+    else linksBySession.delete(sessionId);
+  }
+}
+
+/** Records the https link targets of read_email result `result` (its header
+ *  line — `links` among its fields — a blank line, the body) for `sessionId`,
+ *  with the authenticated sender's domain. Links leave only by the window. */
+export function recordMailLinks(sessionId, result, now = Date.now()) {
+  pruneExpired(now);
+  const owner = String(sessionId || '');
+  if (!owner || typeof result !== 'string') return;
+  const split = result.indexOf('\n\n');
+  if (split < 0) return;
+  let head;
+  try {
+    head = JSON.parse(result.slice(0, split));
+  } catch {
+    return;
+  }
+  const from_domain = authenticatedSender(head);
+  if (!from_domain || !Array.isArray(head.links)) return;
+  const found = new Set(head.links.map((link) => (typeof link === 'string' ? httpsHref(link) : '')).filter(Boolean));
+  if (!found.size) return;
+  const kept = (linksBySession.get(owner) || []).filter((link) => !found.has(link.url));
+  for (const url of found) kept.push({ url, from_domain, read_at: now });
+  linksBySession.set(owner, kept);
+}
+
+/** `{ url, from_domain, read_at }` when `url` is exactly a link of a mail read
+ *  for `sessionId` within the window, else null. */
+export function mailLinkFor(sessionId, url, now = Date.now()) {
+  pruneExpired(now);
+  const href = httpsHref(String(url || '').trim());
+  const link = href ? linksBySession.get(String(sessionId || ''))?.find((entry) => entry.url === href) : null;
+  return link ? { ...link } : null;
+}

package/src/runtime/browser-bridge/tool-defs.mjs

@@ -22,7 +22,7 @@ import { BROWSER_INPUT_FIELDS } from './input-fields.mjs';
 const BROWSER_DESCRIPTION =
   "Drive Mixdog's in-app Chromium directly for rendered, signed-in or interactive pages; public page text uses web_fetch, external windows computer. " +
   'Load the browser-use skill before first use. ' +
-  'Background by default; reveal only via open for a deliverable or handoff. Respect user-closed panels. ' +
+  'Background by default; open (deliverable/handoff) says shown, not on screen yet, or failed; say only that. ' +
   'Task end cleans owned pages/restores temporary panels; user pages persist. ' +
   'hide folds the panel; close_tab closes named background pages only. ' +
   'Pages are session-local; sign-in/storage shared; never provide session_id. ' +