minimal-agent 0.10.0 → 0.12.0

package/src/tools/webbrowser/browser.ts

@@ -0,0 +1,293 @@
+/**
+ * ============================================================
+ *  src/tools/webbrowser/browser.ts —— agent-browser 子进程运行器
+ * ------------------------------------------------------------
+ *  内置 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 { 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';
+
+export interface AgentBrowserRun {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** 运行器签名：给 bin + 完整 args（含全局 flag），返回退出码与输出。可被测试注入。 */
+export type AgentBrowserRunner = (
+  bin: string,
+  args: string[],
+  signal?: AbortSignal,
+) => Promise<AgentBrowserRun>;
+
+/**
+ * minimal-agent 进程级固定 session 名：隔离机器上其它 agent-browser 用法，
+ * 同时让本进程多次调用复用同一浏览器（与原 playwright「一 session 一 page」语义一致）。
+ */
+export const BROWSER_SESSION = 'minimal-agent';
+
+/** 全局 session flag（排在 subcommand 之前）。 */
+export function sessionArgs(sessionName = BROWSER_SESSION): string[] {
+  return ['--session', sessionName];
+}
+
+/** KakadeAI-owned persistent browser profile. It is never the user's system Chrome profile. */
+export function browserProfilePath(profileId = 'default'): string {
+  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);
+}
+
+export async function ensureBrowserProfile(profileId = 'default'): Promise<string> {
+  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'): Promise<string[]> {
+  return [...sessionArgs(sessionName), '--profile', await ensureBrowserProfile(profileId)];
+}
+
+/**
+ * 默认 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: AgentBrowserRunner = (bin, args, signal) =>
+  new Promise<AgentBrowserRun>((resolveP) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let graceTimer: ReturnType<typeof setTimeout> | null = null;
+    let child: ReturnType<typeof spawn>;
+    const finish = (code: number | null, errMsg?: string) => {
+      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'],
+        env: sanitizeCredentialEnv(),
+        windowsHide: true,
+        signal,
+      });
+    } catch (e) {
+      resolveP({ code: -1, stdout: '', stderr: e instanceof Error ? e.message : String(e) });
+      return;
+    }
+    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) => 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);
+    });
+  });
+
+/**
+ * 有界执行一次 agent-browser 命令：在 spawnRunner 之上加「超时 + 可中断」。
+ * 到 timeoutMs 或父 signal abort 即掐断子进程（spawnRunner 拿到 aborted signal → kill →
+ * close → resolve，不会挂），返回结果额外带 timedOut/aborted 标记，供调用方产出可操作错误
+ * 而不是把「被超时/中断杀掉」误当普通失败。timeoutMs 省略或 ≤0 则只受父 signal 约束。
+ */
+export async function runBounded(
+  bin: string,
+  args: string[],
+  opts: { signal?: AbortSignal; timeoutMs?: number } = {},
+  runner: AgentBrowserRunner = spawnRunner,
+): Promise<AgentBrowserRun & { timedOut?: boolean; aborted?: boolean }> {
+  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(): string {
+  return path.join(os.tmpdir(), 'kakadeai-browser-artifacts');
+}
+
+/** 产物保留时长。超过就在下一次生成产物时顺手清掉。 */
+const ARTIFACT_TTL_MS = 30 * 60_000;
+
+/**
+ * 清掉过期产物。
+ *
+ * 在**生成前**做而不是退出时做：进程可能被 kill、可能崩，「退出时清理」恰好在这些情况下
+ * 不执行，于是磁盘上留下的正是最不该留的那批。失败一律忽略——清理问题绝不能让一次截图失败。
+ *
+ * ⚠️ 这里之前**完全没有清理**：开了识图后每次 navigate/snapshot 都写一张 PNG 到 tmp，
+ * 永不删除。而浏览器截图拍的是用户已登录的页面，敏感度不低于桌面截图。
+ */
+async function pruneStaleArtifacts(dir: string): Promise<void> {
+  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'): Promise<string> {
+  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: string,
+  allowedRoots: string[],
+): Promise<{ ok: true; path: string } | { ok: false; error: string }> {
+  const absolute = path.isAbsolute(candidate) ? candidate : path.resolve(candidate);
+  const parent = path.dirname(absolute);
+  let realParent: string;
+  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: string): boolean {
+  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: string): string {
+  const input = value.trim();
+  if (/^[a-z][a-z0-9+.-]*:/i.test(input)) return input;
+  return `https://${input}`;
+}

package/src/tools/webbrowser/browserControl.js

@@ -1,13 +1,31 @@
 import { randomUUID } from 'node:crypto';
+import { HumanInterventionCoordinator, } from '../../humanIntervention.js';
 const CAPTCHA_PATTERNS = [
     /captcha/i,
     /验证码|安全验证|人机验证|完成.{0,8}验证|拖动.{0,12}(滑块|拼图)|滑动.{0,12}(滑块|拼图)/i,
     /verify\s+(?:you are|that you are)\s+(?:a\s+)?human/i,
+    // Additional patterns: reCAPTCHA / hCaptcha / Turnstile / Cloudflare / etc.
+    /i\s*'?m\s+not\s+a\s+robot/i,
+    /checking\s+your\s+browser/i,
+    /press\s+&?\s*hold|click\s+to\s+verify|verifying\s+you/i,
+    /点击验证|按住滑块|图片验证|行为验证/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 PASSWORD_PATTERNS = [
+    /请输入.{0,12}(?:密码|口令)|(?:密码|口令).{0,12}(?:必填|不能为空)/i,
+    /(?:enter|type).{0,20}(?:password|passcode)|(?:password|passcode).{0,20}(?:required|cannot be empty)/i,
+];
+const QR_LOGIN_PATTERNS = [/扫码登录|二维码登录|scan (?:the )?qr|qr code.{0,20}(?:login|sign in)/i];
+const LOGIN_PATTERNS = [/请先登录|登录后继续|扫码登录|sign in to continue|log in to continue/i,
+    /please\s+(?:log|sign)\s+in/i,
+];
+const BLOCK_PATTERNS = [/操作存在异常|访问请求.{0,8}(暂停|拦截)|请求过于频繁|访问受限|access denied|unusual traffic|temporarily blocked/i,
+    // 403/429 必须落在 HTTP/错误语境里再判风控，避免把「售价 $429」「forbidden fruit」这类正常正文误判成拦截。
+    /rate\s+limit(?:ed)?|too\s+many\s+requests|\b403\s+forbidden\b|http[^\n]{0,10}\b(?:403|429)\b|\b(?:error|status)\s*(?:code)?\s*[:：]?\s*(?:403|429)\b/i,
+    /被封禁|风控拦截|系统异常/i,
+];
 const PERMISSION_PATTERNS = [/需要授权|请求权限|permission required|allow access/i];
+const SECURITY_WARNING_PATTERNS = [/安全警告|风险提示|security warning|untrusted (?:application|site|publisher)/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);
@@ -15,10 +33,16 @@ export function detectBrowserChallenge(text) {
         return { reason: 'otp', summary: '页面需要人工输入一次性验证码' };
     if (CAPTCHA_PATTERNS.some((pattern) => pattern.test(normalized)))
         return { reason: 'captcha', summary: '页面需要人工完成安全验证' };
+    if (QR_LOGIN_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'qr_login', summary: '页面需要人工扫码登录' };
+    if (PASSWORD_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'password', 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 (SECURITY_WARNING_PATTERNS.some((pattern) => pattern.test(normalized)))
+        return { reason: 'security_warning', summary: '页面需要人工处理安全警告' };
     if (PERMISSION_PATTERNS.some((pattern) => pattern.test(normalized)))
         return { reason: 'permission', summary: '页面需要人工确认权限' };
     return null;
@@ -26,93 +50,174 @@ export function detectBrowserChallenge(text) {
 export class BrowserControlCoordinator {
     state = { owner: 'none', status: 'idle' };
     listeners = new Set();
-    waiter = null;
+    activeIdentity = null;
+    activeIntervention = null;
+    interventions = new HumanInterventionCoordinator();
+    defaultOwnerId;
+    defaultConversationKey;
+    constructor(input = {}) {
+        this.defaultOwnerId = input.ownerId ?? 'local-owner';
+        this.defaultConversationKey = input.conversationKey ?? 'browser:default';
+    }
     getState() { return this.state; }
     subscribe(listener) {
         this.listeners.add(listener);
         listener(this.state);
         return () => this.listeners.delete(listener);
     }
+    subscribeInterventions(listener) {
+        return this.interventions.subscribe(listener);
+    }
     beginAgent(input) {
-        if (this.state.status === 'waiting_human')
-            return;
+        if (this.state.status === 'waiting_human') {
+            if (this.state.runId === input.runId)
+                return;
+            throw new Error('浏览器正在等待另一个任务的人工处理');
+        }
+        if (this.state.status === 'running' && this.state.runId !== input.runId) {
+            throw new Error('浏览器正在执行另一个会话的原子操作');
+        }
+        this.activeIdentity = {
+            ownerId: this.defaultOwnerId,
+            conversationKey: input.conversationKey ?? this.defaultConversationKey,
+            runId: input.runId,
+        };
         this.setState({ owner: 'agent', status: 'running', ...input });
     }
     finishAgent(runId) {
-        if (this.state.status === 'running' && this.state.runId === runId)
+        if (this.state.status === 'running' && this.state.runId === runId) {
+            this.activeIdentity = null;
             this.setState({ owner: 'none', status: 'idle' });
+        }
     }
     requestHuman(reason, input) {
-        if (this.state.status === 'waiting_human')
-            return this.state.resumeToken;
+        if (this.state.status === 'waiting_human') {
+            if (!input?.runId || this.state.runId === input.runId)
+                return this.state.resumeToken;
+            throw new Error('另一个浏览器任务正在等待人工处理');
+        }
         const running = this.state.status === 'running' ? this.state : null;
-        const resumeToken = randomUUID();
+        const identity = {
+            ownerId: input?.ownerId ?? this.activeIdentity?.ownerId ?? this.defaultOwnerId,
+            conversationKey: input?.conversationKey
+                ?? this.activeIdentity?.conversationKey
+                ?? running?.conversationKey
+                ?? this.defaultConversationKey,
+            runId: input?.runId ?? this.activeIdentity?.runId ?? running?.runId ?? randomUUID(),
+        };
+        const intervention = this.interventions.request({
+            ...identity,
+            surface: 'browser',
+            reason,
+            sanitizedSummary: input?.summary ?? summaryForReason(reason),
+        });
+        this.activeIdentity = identity;
+        this.activeIntervention = intervention;
         this.setState({
             owner: 'user',
             status: 'waiting_human',
-            runId: input?.runId ?? running?.runId ?? randomUUID(),
-            conversationKey: input?.conversationKey ?? running?.conversationKey,
+            runId: identity.runId,
+            conversationKey: identity.conversationKey,
             reason,
-            resumeToken,
+            interventionId: intervention.id,
+            resumeToken: intervention.resumeToken,
+            ownerId: identity.ownerId,
         });
-        return resumeToken;
+        return intervention.resumeToken;
     }
     takeInteractive(input) {
-        this.resolveWaiter('resumed');
+        if (this.activeIntervention && this.activeIdentity) {
+            this.interventions.cancel(this.credential(this.activeIntervention, this.activeIdentity));
+        }
+        this.activeIntervention = null;
+        this.activeIdentity = null;
         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))
+        if (this.state.status !== 'waiting_human' || !token || !this.activeIntervention || !this.activeIdentity)
             return false;
         const previous = this.state;
-        this.resolveWaiter('resumed');
+        const ok = this.interventions.resume(this.credential(this.activeIntervention, this.activeIdentity, token));
+        if (!ok)
+            return false;
+        this.activeIntervention = null;
         this.setState({ owner: 'agent', status: 'running', runId: previous.runId, conversationKey: previous.conversationKey, action: '正在检查人工操作结果' });
         return true;
     }
+    resumeIntervention(credential) {
+        if (this.state.status !== 'waiting_human' || !this.activeIntervention || !this.activeIdentity)
+            return false;
+        const previous = this.state;
+        if (!this.interventions.resume(credential))
+            return false;
+        this.activeIntervention = null;
+        this.activeIdentity = null;
+        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)
+        if (this.state.status === 'waiting_human') {
+            if (!token || !this.activeIntervention || !this.activeIdentity)
+                return false;
+            const ok = this.interventions.cancel(this.credential(this.activeIntervention, this.activeIdentity, token));
+            if (!ok)
+                return false;
+        }
+        this.activeIntervention = null;
+        this.activeIdentity = null;
+        this.setState({ owner: 'user', status: 'interactive' });
+        return true;
+    }
+    cancelIntervention(credential) {
+        if (this.state.status !== 'waiting_human' || !this.activeIntervention || !this.activeIdentity)
+            return false;
+        if (!this.interventions.cancel(credential))
             return false;
-        this.resolveWaiter('stopped');
+        this.activeIntervention = null;
+        this.activeIdentity = null;
         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);
+        const intervention = this.activeIntervention;
+        if (!intervention)
+            return Promise.resolve('stopped');
+        const waiter = { interventionId: intervention.id };
+        return this.interventions.wait(waiter.interventionId, signal).then((resolution) => (resolution.status === 'resumed' ? 'resumed' : 'stopped'));
     }
     setState(state) {
         this.state = state;
         for (const listener of this.listeners)
             listener(state);
     }
+    credential(intervention, identity, resumeToken = intervention.resumeToken) {
+        return {
+            id: intervention.id,
+            resumeToken,
+            ownerId: identity.ownerId,
+            conversationKey: identity.conversationKey,
+            runId: identity.runId,
+        };
+    }
+}
+function summaryForReason(reason) {
+    switch (reason) {
+        case 'captcha': return '页面需要人工完成安全验证';
+        case 'otp': return '页面需要人工输入一次性验证码';
+        case 'password': return '页面需要人工输入密码';
+        case 'qr_login': return '页面需要人工扫码登录';
+        case 'login': return '页面需要人工登录';
+        case 'permission': return '页面需要人工确认权限';
+        case 'security_warning': return '页面需要人工处理安全警告';
+        case 'blocked': return '网站已暂停或拦截当前访问';
+        case 'manual': return '用户已接管浏览器';
+    }
 }