minimal-agent 0.10.0 → 0.12.0

package/src/tools/webbrowser/agentBrowserPath.ts

@@ -0,0 +1,286 @@
+/**
+ * ============================================================
+ *  src/tools/webbrowser/agentBrowserPath.ts —— 解析 agent-browser 可执行文件 + 内置浏览器
+ * ------------------------------------------------------------
+ *  内置 agent 浏览器底座（Step1）：WebBrowser 工具 / skill 脚本 / 工作流 bash 步
+ *  共用同一份「二进制定位 + 浏览器降级」逻辑 —— 单一事实源，完全对标
+ *  ripgrep 的 `src/tools/grep/rgPath.ts`。
+ *
+ *  引擎 = vercel-labs/agent-browser（原生 Rust CLI + CDP，已是 kakadeai 子模块，
+ *  只读引用）。它的原生二进制按 `agent-browser-<os>-<arch>[.exe]` 命名、从 GitHub
+ *  releases 下载；我们像 vendor/ripgrep 一样把它放进 vendor/agent-browser/<arch>-<platform>/。
+ *
+ *  ── agent-browser 二进制定位（按优先级，全程 existsSync 过滤）──
+ *    ① MINIMAL_AGENT_BROWSER_PATH 环境变量（手动指定，调试最高优先）
+ *    ② 项目自带 vendor/agent-browser/<arch>-<platform>/agent-browser(.exe)（默认，开箱即用）
+ *    ③ 绿色版（bun --compile）：exe 同级 vendor/agent-browser/...（compile 后 import.meta.url
+ *       是虚拟路径、② 命不中，绿色目录把 vendor/ 摆 exe 旁边从这捞回）
+ *    ④ 系统 PATH 上的 agent-browser（用户自己 npm i -g / brew / cargo 装的）
+ *    ⑤ 都没有 → null（调用方降级：返回可操作错误并提示回退 WebFetch）
+ *
+ *  ── 浏览器（Chrome）分层降级（落实「opt2+opt3 融合」）──
+ *    agent-browser 自己会：读 AGENT_BROWSER_EXECUTABLE_PATH → 自动探测系统
+ *    Chrome/Brave/Edge/Playwright/Puppeteer → 缺则可 `agent-browser install` 下完整
+ *    Chrome for Testing。我们只补**离线兜底**：当无系统浏览器且无法联网安装时，
+ *    用绿色版内置的轻量 chromium（resolveBundledChromium）保证「插上永远有浏览器」。
+ *    dev/npm 下 vendor/chromium 不存在 → 返回 null → 不影响 agent-browser 原生探测。
+ *
+ *  dev/npm 模式零副作用：execPath 指向 node/bun 二进制，其同级没有 vendor/；
+ *  findPackageRoot 在源码/安装态下指向真实包根，vendor/agent-browser 不存在时
+ *  existsSync 过滤掉 —— 与 rgPath/greenRoot 同一套「加性、命不中即丢弃」铁律。
+ *
+ *  可测性：核心解析 detectAgentBrowser / resolveBundledChromium 都接受可注入依赖
+ *  （env/exists/siblingDir/packageRoot/trySpawn），默认走真实实现；单测注入假依赖
+ *  确定性覆盖每条优先级分支，不碰真实 fs、不用 mock.module（见项目测试约定）。
+ * ============================================================
+ */
+
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve, win32 } from 'node:path';
+
+import { execSiblingDir } from '../../utils/greenRoot.js';
+import { findPackageRoot } from '../../utils/packageRoot.js';
+import { sanitizeCredentialEnv } from '../../config/configService.js';
+
+/** 可注入依赖（默认走真实实现，单测注入假实现）。 */
+export interface ResolveDeps {
+  env: NodeJS.ProcessEnv;
+  exists: (p: string) => boolean;
+  /** 绿色版 exe 同级目录。 */
+  siblingDir: () => string;
+  /** 包根目录；找不到（compile 虚拟路径）返回 null。 */
+  packageRoot: () => string | null;
+  /** 试跑 `<cmd> --version`，退出码 0 即 true。 */
+  trySpawn: (cmd: string) => Promise<boolean>;
+  /** 平台/架构（注入便于测试跨平台命名）。 */
+  platform: NodeJS.Platform;
+  arch: string;
+}
+
+function realDeps(): ResolveDeps {
+  return {
+    env: process.env,
+    exists: existsSync,
+    siblingDir: execSiblingDir,
+    packageRoot: () => {
+      try {
+        return findPackageRoot(import.meta.url);
+      } catch {
+        return null;
+      }
+    },
+    trySpawn: defaultTrySpawn,
+    platform: process.platform,
+    arch: process.arch,
+  };
+}
+
+let cachedBin: string | null | undefined;
+
+/**
+ * 解析一次 agent-browser 二进制路径，结果缓存（同进程复用）。
+ * 返回 null 表示找不到（调用方需降级）。
+ */
+export async function resolveAgentBrowserPath(): Promise<string | null> {
+  if (cachedBin !== undefined) return cachedBin;
+  cachedBin = await detectAgentBrowser(realDeps());
+  return cachedBin;
+}
+
+/** 仅供测试重置缓存。 */
+export function _resetAgentBrowserCache(): void {
+  cachedBin = undefined;
+}
+
+/**
+ * 把已解析到的 agent-browser 二进制所在目录前置进 PATH —— 让子进程（Bash 工具 /
+ * skill 脚本 / 工作流 bash 步）也能直接 `agent-browser ...`，实现 tools/skills/工作流
+ * **共用同一内置浏览器底座**。仅当解析到**绝对路径**（vendored/sibling/env）时生效；
+ * 解析到裸 'agent-browser'（已在 PATH）或 null（没装）时 no-op —— dev/npm 无 vendored
+ * 二进制时天然 no-op，与 greenRoot 同一套加性铁律。可纯函数化测试：注入 path/env。
+ *
+ * 注意：离线兜底的轻量 chromium 仅 WebBrowser 工具自动补 --executable-path 用；直接
+ * 经 CLI 调 agent-browser 的 skill/bash 走 agent-browser 自身的自动探测/在线安装。
+ */
+export async function ensureAgentBrowserOnPath(): Promise<void> {
+  applyBinToPath(await resolveAgentBrowserPath(), process.env, process.platform);
+}
+
+/** 纯函数：把 bin 所在目录前置进 env.PATH（已含则跳过；非绝对路径/null 不动）。 */
+export function applyBinToPath(
+  bin: string | null,
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+): void {
+  if (!bin || bin === 'agent-browser') return;
+  const pathApi = platform === 'win32' ? win32 : { dirname, isAbsolute };
+  if (!pathApi.isAbsolute(bin)) return;
+  const dir = pathApi.dirname(bin);
+  const sep = platform === 'win32' ? ';' : ':';
+  const cur = env.PATH ?? '';
+  if (cur.split(sep).includes(dir)) return;
+  env.PATH = cur ? `${dir}${sep}${cur}` : dir;
+}
+
+/** 纯解析（可注入依赖）：按 ①→⑤ 优先级返回 agent-browser 二进制路径或 null。 */
+export async function detectAgentBrowser(deps: ResolveDeps): Promise<string | null> {
+  const sub = subdir(deps);
+  const bin = binName(deps);
+
+  // ① 显式 env 覆盖
+  const fromEnv = deps.env.MINIMAL_AGENT_BROWSER_PATH;
+  if (fromEnv && deps.exists(fromEnv)) return fromEnv;
+
+  // ② 项目自带 vendored（默认路径，开箱即用）
+  const root = deps.packageRoot();
+  if (root) {
+    const vendored = resolve(root, 'vendor', 'agent-browser', sub, bin);
+    if (deps.exists(vendored)) {
+      ensureExecutable(vendored, deps.platform);
+      return vendored;
+    }
+  }
+
+  // ③ 绿色版 exe 同级
+  const sibling = resolve(deps.siblingDir(), 'vendor', 'agent-browser', sub, bin);
+  if (deps.exists(sibling)) {
+    ensureExecutable(sibling, deps.platform);
+    return sibling;
+  }
+
+  // ④ PATH 上的 agent-browser
+  if (await deps.trySpawn('agent-browser')) return 'agent-browser';
+
+  // ⑤ 找不到
+  return null;
+}
+
+/**
+ * 绿色版离线兜底：内置轻量 chromium 的可执行路径。返回 null 表示没带
+ * （dev/npm 常态，或绿色版未打包 chromium）—— 此时交回 agent-browser 自动探测/在线安装。
+ *
+ * 约定布局：vendor/chromium/<arch>-<platform>/ 下放该平台 chromium，可执行名按平台
+ * 探测一组常见相对路径（不同 chromium 构建解包名不一，宁可多探几个）。
+ */
+export function resolveBundledChromium(deps: ResolveDeps = realDeps()): string | null {
+  const sub = subdir(deps);
+  const roots: string[] = [resolve(deps.siblingDir(), 'vendor', 'chromium', sub)];
+  const root = deps.packageRoot();
+  if (root) roots.push(resolve(root, 'vendor', 'chromium', sub));
+
+  for (const r of roots) {
+    for (const rel of chromiumExeCandidates(deps.platform)) {
+      const p = resolve(r, rel);
+      if (deps.exists(p)) {
+        ensureExecutable(p, deps.platform);
+        return p;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Prefer a user-installed stable browser executable while keeping KakadeAI's
+ * own profile directory. This improves site compatibility without touching
+ * the user's normal Chrome profile or attempting fingerprint evasion.
+ */
+export function resolveSystemBrowser(deps: ResolveDeps = realDeps()): string | null {
+  const explicit = deps.env.MINIMAL_AGENT_BROWSER_EXECUTABLE_PATH
+    ?? deps.env.AGENT_BROWSER_EXECUTABLE_PATH;
+  if (explicit && deps.exists(explicit)) return explicit;
+
+  const home = deps.env.HOME ?? deps.env.USERPROFILE ?? '';
+  const candidates = deps.platform === 'darwin'
+    ? [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        home ? resolve(home, 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome') : '',
+      ]
+    : deps.platform === 'win32'
+      ? [
+          deps.env.PROGRAMFILES ? resolve(deps.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe') : '',
+          deps.env['PROGRAMFILES(X86)'] ? resolve(deps.env['PROGRAMFILES(X86)'], 'Microsoft/Edge/Application/msedge.exe') : '',
+          deps.env.LOCALAPPDATA ? resolve(deps.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe') : '',
+        ]
+      : [
+          '/usr/bin/google-chrome-stable',
+          '/usr/bin/google-chrome',
+          '/usr/bin/microsoft-edge-stable',
+          '/usr/bin/chromium',
+          '/usr/bin/chromium-browser',
+        ];
+  return candidates.find((candidate) => candidate && deps.exists(candidate)) ?? null;
+}
+
+/** vendor 子目录名 = <arch>-<platform>（对齐 rgPath.ts / build-green.ts 的 vendor 约定）。 */
+function subdir(deps: Pick<ResolveDeps, 'arch' | 'platform'>): string {
+  return `${deps.arch}-${deps.platform}`;
+}
+
+function binName(deps: Pick<ResolveDeps, 'platform'>): string {
+  return deps.platform === 'win32' ? 'agent-browser.exe' : 'agent-browser';
+}
+
+/** 各平台 chromium 可执行的候选相对路径（解包布局因构建而异，逐个探）。 */
+function chromiumExeCandidates(platform: NodeJS.Platform): string[] {
+  switch (platform) {
+    case 'win32':
+      return ['chrome.exe', 'chrome-headless-shell.exe'];
+    case 'darwin':
+      return [
+        'Chromium.app/Contents/MacOS/Chromium',
+        'Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        'chrome',
+        'chrome-headless-shell',
+      ];
+    default: // linux
+      return ['chrome', 'chrome-headless-shell', 'chromium'];
+  }
+}
+
+/**
+ * Unix 上 git/tarball/cp 偶尔丢可执行位；Windows 不需要。失败忽略（后续 spawn 会响亮报错）。
+ */
+function ensureExecutable(path: string, platform: NodeJS.Platform): void {
+  if (platform === 'win32') return;
+  try {
+    chmodSync(path, 0o755);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * 试 spawn `<cmd> --version`，退出码 0 即认为可用。
+ * 传命令名（非绝对路径）让 OS 解析 PATH；windowsHide 防弹窗；5s 兜底超时。
+ */
+function defaultTrySpawn(cmd: string): Promise<boolean> {
+  return new Promise((resolveP) => {
+    let settled = false;
+    const done = (ok: boolean) => {
+      if (settled) return;
+      settled = true;
+      resolveP(ok);
+    };
+    try {
+      const child = spawn(cmd, ['--version'], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        env: sanitizeCredentialEnv(),
+        windowsHide: true,
+      });
+      child.on('error', () => done(false));
+      child.on('close', (code) => done(code === 0));
+      setTimeout(() => {
+        try {
+          child.kill();
+        } catch {}
+        done(false);
+      }, 5_000);
+    } catch {
+      done(false);
+    }
+  });
+}

package/src/tools/webbrowser/browser.js

@@ -10,10 +10,12 @@
  * ============================================================
  */
 import { spawn } from 'node:child_process';
-import { chmod, mkdir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readdir, realpath, rm, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { sanitizeCredentialEnv } from '../../config/configService.js';
+import { pathContains, pathContainedByAny } from '../../utils/pathContains.js';
 /**
  * minimal-agent 进程级固定 session 名：隔离机器上其它 agent-browser 用法，
  * 同时让本进程多次调用复用同一浏览器（与原 playwright「一 session 一 page」语义一致）。
@@ -38,11 +40,40 @@ export async function ensureBrowserProfile(profileId = 'default') {
 export async function browserGlobalArgs(sessionName = BROWSER_SESSION, profileId = 'default') {
     return [...sessionArgs(sessionName), '--profile', await ensureBrowserProfile(profileId)];
 }
-/** 默认 spawn 运行器：收集 stdout/stderr，close 时 resolve；spawn 抛错也 resolve 成失败。 */
+/**
+ * 默认 spawn 运行器：收集 stdout/stderr 后结算；spawn 抛错也 resolve 成失败。
+ *
+ * ⚠️ 以 **'exit'（进程退出）为准结算，而非死等 'close'（全部 stdio 流关闭）**——这是「桌面首次
+ * 用浏览器卡死」的真根因修复：agent-browser 首次 `open` 会拉起一个 **detached daemon**，daemon
+ * 继承并长期攥着本进程给 client 的 stdout/stderr **pipe** 写端 → Node 的 `'close'` 事件**永不触发**
+ * → 若死等 'close'，spawnRunner 永久挂起（实测 client 已 `exit code=0 @800ms`，`close` 却 never），
+ * 连 AbortSignal 杀了 client 都没用（close 仍在等被 daemon 攥着的 pipe）。
+ * 正常命令（连既有 daemon、不派生）'close' 紧随 'exit' → 走 'close' 拿完整输出；只有拉 daemon 的
+ * 命令走 'exit' + 短宽限兜底（此时输出已写完、daemon 只是攥着空 pipe）。abort 同理经 'exit' 及时结算。
+ */
 export const spawnRunner = (bin, args, signal) => new Promise((resolveP) => {
     let stdout = '';
     let stderr = '';
+    let settled = false;
+    let graceTimer = null;
     let child;
+    const finish = (code, errMsg) => {
+        if (settled)
+            return;
+        settled = true;
+        if (graceTimer)
+            clearTimeout(graceTimer);
+        // 主动释放父侧 pipe 读端（daemon 攥着写端、我们已拿到结果，不再依赖它关闭）。
+        try {
+            child?.stdout?.destroy();
+        }
+        catch { }
+        try {
+            child?.stderr?.destroy();
+        }
+        catch { }
+        resolveP({ code: code ?? -1, stdout, stderr: stderr || errMsg || '' });
+    };
     try {
         child = spawn(bin, args, {
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -59,14 +90,186 @@ export const spawnRunner = (bin, args, signal) => new Promise((resolveP) => {
     child.stdout?.on('data', (c) => (stdout += c));
     child.stderr?.setEncoding('utf8');
     child.stderr?.on('data', (c) => (stderr += c));
-    child.on('error', (e) => resolveP({
-        code: -1,
-        stdout,
-        stderr: stderr || (e instanceof Error ? e.message : String(e)),
-    }));
-    child.on('close', (code) => resolveP({ code: code ?? -1, stdout, stderr }));
+    child.on('error', (e) => finish(-1, e instanceof Error ? e.message : String(e)));
+    // 正常路径：'close' 紧随 'exit'（pipe 关闭）→ 以完整输出立即结算，并清掉宽限计时器。
+    child.on('close', (code) => finish(code));
+    // 拉 daemon 的命令：daemon 继承 pipe → 'close' 永不来。以 'exit' 为准，给一小段宽限等 'close'
+    // （正常命令会在宽限内更早经 'close' 结算，不丢输出）；超时则强制结算，不再无限等 pipe。
+    child.on('exit', (code) => {
+        if (settled)
+            return;
+        graceTimer = setTimeout(() => finish(code), 500);
+    });
 });
-/** 生成截图/PDF 的临时输出路径。 */
-export function artifactPath(prefix = 'browser', ext = 'png') {
-    return path.join(os.tmpdir(), `${prefix}-${Date.now()}.${ext}`);
+/**
+ * 有界执行一次 agent-browser 命令：在 spawnRunner 之上加「超时 + 可中断」。
+ * 到 timeoutMs 或父 signal abort 即掐断子进程（spawnRunner 拿到 aborted signal → kill →
+ * close → resolve，不会挂），返回结果额外带 timedOut/aborted 标记，供调用方产出可操作错误
+ * 而不是把「被超时/中断杀掉」误当普通失败。timeoutMs 省略或 ≤0 则只受父 signal 约束。
+ */
+export async function runBounded(bin, args, opts = {}, runner = spawnRunner) {
+    const ac = new AbortController();
+    let timedOut = false;
+    const onParent = () => ac.abort(opts.signal?.reason);
+    const timer = opts.timeoutMs && opts.timeoutMs > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            ac.abort();
+        }, opts.timeoutMs)
+        : null;
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            ac.abort(opts.signal.reason);
+        else
+            opts.signal.addEventListener('abort', onParent, { once: true });
+    }
+    try {
+        const r = await runner(bin, args, ac.signal);
+        const abortedByParent = Boolean(opts.signal?.aborted) && !timedOut;
+        return {
+            ...r,
+            ...(timedOut ? { timedOut: true } : {}),
+            ...(abortedByParent ? { aborted: true } : {}),
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        opts.signal?.removeEventListener('abort', onParent);
+    }
+}
+/**
+ * 浏览器产物（截图 / PDF / 录像 / trace）的托管目录。
+ *
+ * 单独一层目录而不是直接扔 `os.tmpdir()`，是为了让「这些文件归我们管」这件事成立：
+ * 有明确边界才谈得上定期清理，也才谈得上把它当成输出路径的默认允许根。
+ */
+export function browserArtifactDir() {
+    return path.join(os.tmpdir(), 'kakadeai-browser-artifacts');
+}
+/** 产物保留时长。超过就在下一次生成产物时顺手清掉。 */
+const ARTIFACT_TTL_MS = 30 * 60_000;
+/**
+ * 清掉过期产物。
+ *
+ * 在**生成前**做而不是退出时做：进程可能被 kill、可能崩，「退出时清理」恰好在这些情况下
+ * 不执行，于是磁盘上留下的正是最不该留的那批。失败一律忽略——清理问题绝不能让一次截图失败。
+ *
+ * ⚠️ 这里之前**完全没有清理**：开了识图后每次 navigate/snapshot 都写一张 PNG 到 tmp，
+ * 永不删除。而浏览器截图拍的是用户已登录的页面，敏感度不低于桌面截图。
+ */
+async function pruneStaleArtifacts(dir) {
+    try {
+        const cutoff = Date.now() - ARTIFACT_TTL_MS;
+        const entries = await readdir(dir);
+        await Promise.all(entries.map(async (name) => {
+            const target = path.join(dir, name);
+            try {
+                const info = await stat(target);
+                if (info.mtimeMs < cutoff)
+                    await rm(target, { force: true, recursive: true });
+            }
+            catch { /* 单个文件清不掉不影响其它 */ }
+        }));
+    }
+    catch { /* 目录不存在或不可读：没什么可清的 */ }
+}
+/**
+ * 生成一个托管的产物输出路径，并确保目录存在、旧产物已清理。
+ *
+ * 文件名带 pid + 随机数：`Date.now()` 单独用会在同一毫秒内两次调用时撞名
+ * （两个并发截图互相覆盖，症状是「截出来的图不是那一刻的画面」）。
+ */
+export async function createArtifactPath(prefix = 'browser', ext = 'png') {
+    const dir = browserArtifactDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        await chmod(dir, 0o700).catch(() => undefined);
+    await pruneStaleArtifacts(dir);
+    const unique = `${Date.now()}-${process.pid}-${randomUUID().slice(0, 8)}`;
+    return path.join(dir, `${prefix}-${unique}.${ext}`);
+}
+/**
+ * 允许 `navigate` / `tab new` 打开的 scheme。
+ *
+ * 白名单而不是黑名单：新 scheme 层出不穷，漏一个就等于放行。
+ * 明确拒绝的两类各有理由——
+ *   · `javascript:` 是在页面里执行代码，那条路必须走 `eval`（受 Developer Mode 约束），
+ *     不能靠一个看起来像"打开网址"的动作绕过去；
+ *   · `data:` 可以直接构造一个带脚本的文档，等价于同一件事。
+ */
+const ALLOWED_URL_SCHEMES = new Set(['http', 'https', 'about', 'file']);
+/**
+ * 校验模型给的**输出**路径（截图 / PDF / 录像 / trace 落在哪）。
+ *
+ * ⚠️ 这里之前完全没有校验：`input.path` 由模型给出、直达子进程，等于一个不受限的
+ * 任意文件写入原语——可以覆盖项目文件、写进 `~/.ssh/`、覆盖配置。刺眼的是**同一个
+ * 文件里读方向做得很好**（`upload` 有 realpath + 包含判定），写方向一点没管。这个
+ * 不对称是无意的：防的时候只想到了"读进来"。
+ *
+ * 两道判据：
+ * ① 必须落在允许根之内（托管产物目录 / 工作目录 / 本次任务批准的文件范围）；
+ * ② **不允许静默覆盖托管目录之外的已有文件**——把截图写成 `package.json` 不该是
+ *    一次工具调用能顺手做到的事。
+ *
+ * 目标文件通常还不存在，所以 realpath 走的是**父目录**；父目录不存在直接拒绝，
+ * 而不是替调用方创建——凭一个路径参数就造目录树同样是越权。
+ */
+export async function validateArtifactOutputPath(candidate, allowedRoots) {
+    const absolute = path.isAbsolute(candidate) ? candidate : path.resolve(candidate);
+    const parent = path.dirname(absolute);
+    let realParent;
+    try {
+        realParent = await realpath(parent);
+    }
+    catch {
+        return { ok: false, error: `输出目录不存在：${parent}` };
+    }
+    const roots = await Promise.all(allowedRoots.map(async (root) => {
+        try {
+            return await realpath(root);
+        }
+        catch {
+            return path.resolve(root);
+        }
+    }));
+    if (!pathContainedByAny(roots, realParent)) {
+        return {
+            ok: false,
+            error: `输出路径超出允许范围：${absolute}\n`
+                + `允许写入：${roots.join('、')}\n`
+                + '省略 path 参数即可写到托管的临时目录。',
+        };
+    }
+    const managed = await realpath(browserArtifactDir()).catch(() => browserArtifactDir());
+    if (!pathContains(managed, realParent)) {
+        const exists = await stat(path.join(realParent, path.basename(absolute)))
+            .then(() => true)
+            .catch(() => false);
+        if (exists) {
+            return {
+                ok: false,
+                error: `目标文件已存在，拒绝静默覆盖：${absolute}。请换一个文件名，或省略 path 写到临时目录。`,
+            };
+        }
+    }
+    return { ok: true, path: path.join(realParent, path.basename(absolute)) };
+}
+export function isAllowedBrowserScheme(value) {
+    const match = /^([a-z][a-z0-9+.-]*):/i.exec(value.trim());
+    if (!match)
+        return true; // 无 scheme → normalizeUrl 会补 https://
+    return ALLOWED_URL_SCHEMES.has(match[1].toLowerCase());
+}
+/**
+ * 把用户/模型给的地址归一化成 agent-browser `open`/`tab new` 能吃的完整 URL：
+ * 已带 scheme（http:/https:/about:/file: 等）原样返回；否则补 `https://`。
+ * 工具（navigate/tabNew）与 web 桥（browser/navigate）共用这一份，杜绝「两处两套行为」
+ * ——曾出现桥归一化、工具原样透传 `open www.baidu.com` 导致无 scheme 不导航。
+ */
+export function normalizeUrl(value) {
+    const input = value.trim();
+    if (/^[a-z][a-z0-9+.-]*:/i.test(input))
+        return input;
+    return `https://${input}`;
 }