minimal-agent 0.8.2 → 0.10.0

package/src/tools/toolProgressBridge.js

@@ -0,0 +1,48 @@
+/**
+ * ============================================================
+ *  src/tools/toolProgressBridge.ts —— 长时工具的「步内进度」宿主桥
+ * ------------------------------------------------------------
+ *  仿 askBridge 的宿主交互桥模式（全局 handler 注册表）：
+ *  长时工具（GenerateImage 批量生图,单步可达 10-30 分钟）在执行**中途**把
+ *  逐项进度行发布出来,有 UI 的宿主（TUI useChat）订阅后实时上屏——
+ *  否则整步在 LiveArea 上只有一行静态描述,十几分钟毫无变化,
+ *  用户必然误判死机（2026-07-02 真实事故:31 张生图 ~13 分钟被当成卡死,
+ *  差点手杀健康运行）。
+ *
+ *  两种宿主:
+ *    - TUI:useChat mount 时 setToolProgressHandler() 注册,更新 runningTools
+ *      对应条目的 progress 字段 → LiveArea tool_executing 行实时显示。
+ *    - 非交互（`-p` / gateway / 子进程）:没有 handler → publish 是 no-op,
+ *      零副作用（进度对结构化结局契约不可见,不污染 stdout/stderr）。
+ *
+ *  工具侧只依赖本模块,不 import ui/（与 askBridge 同样的中立位置理由:
+ *  它是工具与宿主之间的中介,避免 tools → ui 反向耦合）。
+ * ============================================================
+ */
+let handler = null;
+/**
+ * 注册 / 注销宿主处理器。
+ * TUI 的 useChat 在 mount 时注册、unmount 时传 null 注销。
+ * 单进程单 UI,模块级单例即可（与 askBridge 一致）。
+ */
+export function setToolProgressHandler(h) {
+    handler = h;
+}
+/** 是否有宿主在场（测试 / 诊断用）。 */
+export function hasToolProgressHandler() {
+    return handler !== null;
+}
+/**
+ * 发布一条进度行。无 handler 时 no-op;handler 抛异常也吞掉——
+ * 进度是锦上添花,绝不能让 UI 侧的 bug 反噬工具执行。
+ */
+export function publishToolProgress(toolName, line) {
+    if (!handler)
+        return;
+    try {
+        handler(toolName, line);
+    }
+    catch {
+        /* 进度上屏失败不阻断工具 */
+    }
+}

package/src/tools/webbrowser/agentBrowserPath.js

@@ -0,0 +1,258 @@
+/**
+ * ============================================================
+ *  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';
+function realDeps() {
+    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;
+/**
+ * 解析一次 agent-browser 二进制路径，结果缓存（同进程复用）。
+ * 返回 null 表示找不到（调用方需降级）。
+ */
+export async function resolveAgentBrowserPath() {
+    if (cachedBin !== undefined)
+        return cachedBin;
+    cachedBin = await detectAgentBrowser(realDeps());
+    return cachedBin;
+}
+/** 仅供测试重置缓存。 */
+export function _resetAgentBrowserCache() {
+    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() {
+    applyBinToPath(await resolveAgentBrowserPath(), process.env, process.platform);
+}
+/** 纯函数：把 bin 所在目录前置进 env.PATH（已含则跳过；非绝对路径/null 不动）。 */
+export function applyBinToPath(bin, env, platform) {
+    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) {
+    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 = realDeps()) {
+    const sub = subdir(deps);
+    const roots = [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 = realDeps()) {
+    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) {
+    return `${deps.arch}-${deps.platform}`;
+}
+function binName(deps) {
+    return deps.platform === 'win32' ? 'agent-browser.exe' : 'agent-browser';
+}
+/** 各平台 chromium 可执行的候选相对路径（解包布局因构建而异，逐个探）。 */
+function chromiumExeCandidates(platform) {
+    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, platform) {
+    if (platform === 'win32')
+        return;
+    try {
+        chmodSync(path, 0o755);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * 试 spawn `<cmd> --version`，退出码 0 即认为可用。
+ * 传命令名（非绝对路径）让 OS 解析 PATH；windowsHide 防弹窗；5s 兜底超时。
+ */
+function defaultTrySpawn(cmd) {
+    return new Promise((resolveP) => {
+        let settled = false;
+        const done = (ok) => {
+            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

@@ -1,55 +1,72 @@
 /**
  * ============================================================
- *  src/tools/browser.ts —— Playwright Browser 单例
+ *  src/tools/webbrowser/browser.ts —— agent-browser 子进程运行器
  * ------------------------------------------------------------
- *  整个 session 复用同一个 headless Chromium page。
- *  动态 import playwright-core，按需加载，避免未安装时拖累主程序。
+ *  内置 agent 浏览器底座的执行层：把命令发给 agent-browser CLI（原生 Rust + CDP，
+ *  daemon 模型——多次调用复用同一后台浏览器进程）。取代原 playwright 单例。
+ *
+ *  二进制定位、Chrome 分层降级见 `agentBrowserPath.ts`。本文件只负责 spawn + 收集输出。
+ *  全局 flag（--session / --executable-path）必须排在 subcommand 之前（agent-browser 约定）。
  * ============================================================
  */
+import { spawn } from 'node:child_process';
+import { chmod, mkdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-let browserInstance = null;
-let pageInstance = null;
+import { sanitizeCredentialEnv } from '../../config/configService.js';
 /**
- * 获取或创建 browser page 单例。
- * 每次导航后手动更新 pageInstance.url()。
+ * minimal-agent 进程级固定 session 名：隔离机器上其它 agent-browser 用法，
+ * 同时让本进程多次调用复用同一浏览器（与原 playwright「一 session 一 page」语义一致）。
  */
-export async function getBrowserPage() {
-    if (!browserInstance) {
-        // 动态 import，按需加载
-        const { chromium } = await import('playwright-core');
-        try {
-            browserInstance = await chromium.launch({
-                headless: true,
-                args: ['--no-sandbox', '--disable-setuid-sandbox'],
-            });
-        }
-        catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            throw new Error(`Failed to launch browser: ${message}\n` +
-                `请先安装 playwright 及浏览器：\n` +
-                `  npm install playwright-core\n` +
-                `  npx playwright install chromium`);
-        }
-    }
-    if (!pageInstance) {
-        pageInstance = await browserInstance.newPage();
-        await pageInstance.setViewportSize({ width: 1280, height: 720 });
-    }
-    return pageInstance;
+export const BROWSER_SESSION = 'minimal-agent';
+/** 全局 session flag（排在 subcommand 之前）。 */
+export function sessionArgs(sessionName = BROWSER_SESSION) {
+    return ['--session', sessionName];
+}
+/** KakadeAI-owned persistent browser profile. It is never the user's system Chrome profile. */
+export function browserProfilePath(profileId = 'default') {
+    const safe = /^[a-zA-Z0-9._-]+$/.test(profileId) ? profileId : 'default';
+    return path.join(process.env.MINIMAL_AGENT_HOME ?? os.homedir(), '.minimal-agent', 'browser', 'profiles', safe);
 }
-/** 关闭浏览器（session 结束时调用） */
-export async function closeBrowser() {
-    if (pageInstance) {
-        await pageInstance.close();
-        pageInstance = null;
+export async function ensureBrowserProfile(profileId = 'default') {
+    const profile = browserProfilePath(profileId);
+    await mkdir(profile, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        await chmod(profile, 0o700).catch(() => undefined);
+    return profile;
+}
+export async function browserGlobalArgs(sessionName = BROWSER_SESSION, profileId = 'default') {
+    return [...sessionArgs(sessionName), '--profile', await ensureBrowserProfile(profileId)];
+}
+/** 默认 spawn 运行器：收集 stdout/stderr，close 时 resolve；spawn 抛错也 resolve 成失败。 */
+export const spawnRunner = (bin, args, signal) => new Promise((resolveP) => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    try {
+        child = spawn(bin, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: sanitizeCredentialEnv(),
+            windowsHide: true,
+            signal,
+        });
     }
-    if (browserInstance) {
-        await browserInstance.close();
-        browserInstance = null;
+    catch (e) {
+        resolveP({ code: -1, stdout: '', stderr: e instanceof Error ? e.message : String(e) });
+        return;
     }
-}
-/** 生成截图路径 */
-export function screenshotPath(prefix = 'browser') {
-    return path.join(os.tmpdir(), `${prefix}-${Date.now()}.png`);
+    child.stdout?.setEncoding('utf8');
+    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 }));
+});
+/** 生成截图/PDF 的临时输出路径。 */
+export function artifactPath(prefix = 'browser', ext = 'png') {
+    return path.join(os.tmpdir(), `${prefix}-${Date.now()}.${ext}`);
 }

package/src/tools/webbrowser/browserControl.js

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+const CAPTCHA_PATTERNS = [
+    /captcha/i,
+    /验证码|安全验证|人机验证|完成.{0,8}验证|拖动.{0,12}(滑块|拼图)|滑动.{0,12}(滑块|拼图)/i,
+    /verify\s+(?:you are|that you are)\s+(?:a\s+)?human/i,
+];
+const OTP_PATTERNS = [/一次性密码|短信验证码|邮件验证码|动态口令|\botp\b|one[- ]time (?:password|code)/i];
+const LOGIN_PATTERNS = [/请先登录|登录后继续|扫码登录|sign in to continue|log in to continue/i];
+const BLOCK_PATTERNS = [/操作存在异常|访问请求.{0,8}(暂停|拦截)|请求过于频繁|访问受限|access denied|unusual traffic|temporarily blocked/i];
+const PERMISSION_PATTERNS = [/需要授权|请求权限|permission required|allow access/i];
+/** Classifies only explicit page signals. It never attempts to solve or bypass a challenge. */
+export function detectBrowserChallenge(text) {
+    const normalized = text.replace(/\s+/g, ' ').slice(0, 200_000);
+    if (OTP_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'otp', summary: '页面需要人工输入一次性验证码' };
+    if (CAPTCHA_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'captcha', summary: '页面需要人工完成安全验证' };
+    if (LOGIN_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'login', summary: '页面需要人工登录' };
+    if (BLOCK_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'blocked', summary: '网站已暂停或拦截当前访问' };
+    if (PERMISSION_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'permission', summary: '页面需要人工确认权限' };
+    return null;
+}
+export class BrowserControlCoordinator {
+    state = { owner: 'none', status: 'idle' };
+    listeners = new Set();
+    waiter = null;
+    getState() { return this.state; }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.state);
+        return () => this.listeners.delete(listener);
+    }
+    beginAgent(input) {
+        if (this.state.status === 'waiting_human')
+            return;
+        this.setState({ owner: 'agent', status: 'running', ...input });
+    }
+    finishAgent(runId) {
+        if (this.state.status === 'running' && this.state.runId === runId)
+            this.setState({ owner: 'none', status: 'idle' });
+    }
+    requestHuman(reason, input) {
+        if (this.state.status === 'waiting_human')
+            return this.state.resumeToken;
+        const running = this.state.status === 'running' ? this.state : null;
+        const resumeToken = randomUUID();
+        this.setState({
+            owner: 'user',
+            status: 'waiting_human',
+            runId: input?.runId ?? running?.runId ?? randomUUID(),
+            conversationKey: input?.conversationKey ?? running?.conversationKey,
+            reason,
+            resumeToken,
+        });
+        return resumeToken;
+    }
+    takeInteractive(input) {
+        this.resolveWaiter('resumed');
+        this.setState({ owner: 'user', status: 'interactive', runId: input?.runId, conversationKey: input?.conversationKey });
+    }
+    resume(token) {
+        if (this.state.status !== 'waiting_human' || (token && token !== this.state.resumeToken))
+            return false;
+        const previous = this.state;
+        this.resolveWaiter('resumed');
+        this.setState({ owner: 'agent', status: 'running', runId: previous.runId, conversationKey: previous.conversationKey, action: '正在检查人工操作结果' });
+        return true;
+    }
+    stop(token) {
+        if (this.state.status === 'waiting_human' && token && token !== this.state.resumeToken)
+            return false;
+        this.resolveWaiter('stopped');
+        this.setState({ owner: 'user', status: 'interactive' });
+        return true;
+    }
+    waitForHuman(signal) {
+        if (this.state.status !== 'waiting_human')
+            return Promise.resolve('resumed');
+        if (this.waiter)
+            return new Promise((resolve) => {
+                const unsubscribe = this.subscribe((state) => {
+                    if (state.status !== 'waiting_human') {
+                        unsubscribe();
+                        resolve(state.status === 'running' ? 'resumed' : 'stopped');
+                    }
+                });
+            });
+        return new Promise((resolve, reject) => {
+            const token = this.state.status === 'waiting_human' ? this.state.resumeToken : '';
+            const onAbort = () => {
+                cleanup();
+                this.waiter = null;
+                reject(new DOMException('aborted', 'AbortError'));
+            };
+            const cleanup = () => signal?.removeEventListener('abort', onAbort);
+            this.waiter = { token, resolve, cleanup };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+        });
+    }
+    resolveWaiter(result) {
+        const waiter = this.waiter;
+        if (!waiter)
+            return;
+        this.waiter = null;
+        waiter.cleanup();
+        waiter.resolve(result);
+    }
+    setState(state) {
+        this.state = state;
+        for (const listener of this.listeners)
+            listener(state);
+    }
+}

package/src/tools/webbrowser/browserDaemon.js

@@ -0,0 +1,97 @@
+import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser } from './agentBrowserPath.js';
+import { browserGlobalArgs, sessionArgs, spawnRunner } from './browser.js';
+const ports = new Map();
+const starts = new Map();
+function parsePort(text) {
+    const match = text.match(/ws:\/\/(?:127\.0\.0\.1|localhost):([0-9]+)/i);
+    if (!match)
+        return null;
+    const port = Number(match[1]);
+    return Number.isInteger(port) && port > 0 && port < 65_536 ? port : null;
+}
+function browserRuntimeMissing(text) {
+    return /browser\s+(?:not found|was not found)|chrom(?:e|ium).*(?:not found|missing)|executable.*(?:not found|does not exist)|run ['\"]?agent-browser install/i.test(text);
+}
+export { browserRuntimeMissing as _browserRuntimeMissing };
+async function readStatus(bin, sessionName) {
+    // Profile/executable flags are launch-only. Repeating them against a running
+    // daemon makes agent-browser ignore the profile and emit misleading warnings.
+    const result = await spawnRunner(bin, [...sessionArgs(sessionName), 'stream', 'status']);
+    if (result.code !== 0)
+        return { port: null, connected: false };
+    const text = `${result.stdout}\n${result.stderr}`;
+    return { port: parsePort(text), connected: /Connected:\s*true/i.test(text) };
+}
+export async function ensureDaemon(sessionName = 'minimal-agent') {
+    const bin = await resolveAgentBrowserPath();
+    if (!bin)
+        throw new Error('未找到 agent-browser 可执行文件');
+    const status = await readStatus(bin, sessionName);
+    if (status.port && status.connected) {
+        ports.set(sessionName, status.port);
+        return { sessionName, streamPort: status.port, alreadyRunning: true };
+    }
+    const pending = starts.get(sessionName);
+    if (pending)
+        return pending;
+    const start = (async () => {
+        const globals = await browserGlobalArgs(sessionName);
+        // Prefer a stable system browser executable, but always use KakadeAI's
+        // isolated profile. Bundled Chromium remains an offline fallback.
+        const systemBrowser = resolveSystemBrowser();
+        let opened = await spawnRunner(bin, [
+            ...globals,
+            ...(systemBrowser ? ['--executable-path', systemBrowser] : []),
+            'open',
+            'about:blank',
+        ]);
+        if (opened.code !== 0 && browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
+            const chromium = resolveBundledChromium();
+            if (chromium) {
+                opened = await spawnRunner(bin, [...globals, '--executable-path', chromium, 'open', 'about:blank']);
+            }
+            else {
+                const installed = await spawnRunner(bin, ['install']);
+                if (installed.code === 0)
+                    opened = await spawnRunner(bin, [...globals, 'open', 'about:blank']);
+            }
+        }
+        if (opened.code !== 0) {
+            throw new Error((opened.stderr || opened.stdout || '浏览器启动失败').trim());
+        }
+        const streamPort = await waitForStreamPort(sessionName, 10_000);
+        ports.set(sessionName, streamPort);
+        return { sessionName, streamPort, alreadyRunning: false };
+    })().finally(() => starts.delete(sessionName));
+    starts.set(sessionName, start);
+    return start;
+}
+export async function stopDaemon(sessionName = 'minimal-agent') {
+    const bin = await resolveAgentBrowserPath();
+    ports.delete(sessionName);
+    if (!bin)
+        return;
+    await spawnRunner(bin, [...sessionArgs(sessionName), 'close']);
+}
+export async function getStreamPort(sessionName = 'minimal-agent') {
+    const cached = ports.get(sessionName);
+    if (cached)
+        return cached;
+    const bin = await resolveAgentBrowserPath();
+    if (!bin)
+        return null;
+    const port = (await readStatus(bin, sessionName)).port;
+    if (port)
+        ports.set(sessionName, port);
+    return port;
+}
+export async function waitForStreamPort(sessionName = 'minimal-agent', timeoutMs = 10_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const port = await getStreamPort(sessionName);
+        if (port)
+            return port;
+        await new Promise((resolve) => setTimeout(resolve, 120));
+    }
+    throw new Error('浏览器已启动，但实时画面端口未就绪');
+}

package/src/tools/webbrowser/browserService.js

@@ -0,0 +1,27 @@
+/**
+ * Process-wide action coordinator for the supervised browser. Desktop input,
+ * Agent tools, TUI and workflows share the same daemon, so CDP mutations must
+ * be serialized instead of racing through separate command adapters.
+ */
+export class BrowserService {
+    tails = new Map();
+    async run(input) {
+        const previous = this.tails.get(input.sessionName) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => current);
+        this.tails.set(input.sessionName, tail);
+        await previous;
+        try {
+            if (input.signal?.aborted)
+                return { code: -1, stdout: '', stderr: 'Browser action cancelled' };
+            return await input.runner(input.bin, input.args, input.signal);
+        }
+        finally {
+            release();
+            if (this.tails.get(input.sessionName) === tail)
+                this.tails.delete(input.sessionName);
+        }
+    }
+}
+export const browserService = new BrowserService();