minimal-agent 0.12.0 → 0.14.0

package/src/tools/webbrowser/browserContent.ts

@@ -0,0 +1,438 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+
+import type { CdpConnection } from './browserAutomation.js';
+
+export type BrowserPageAsset = {
+  kind:
+    | 'image'
+    | 'video'
+    | 'audio'
+    | 'stylesheet'
+    | 'script'
+    | 'font'
+    | 'icon'
+    | 'other';
+  url: string;
+  source: 'dom' | 'performance' | 'inline';
+  name?: string;
+  alt?: string;
+  type?: string;
+  width?: number;
+  height?: number;
+  inline?: boolean;
+  content?: string;
+};
+
+export type BrowserPageContent = {
+  url: string;
+  title: string;
+  text: string;
+  html?: string;
+  format:
+    | 'text'
+    | 'txt'
+    | 'markdown'
+    | 'md'
+    | 'html'
+    | 'json'
+    | 'page'
+    | 'google-workspace'
+    | 'youtube-transcript'
+    | 'pdf'
+    | 'docx'
+    | 'xlsx'
+    | 'csv'
+    | 'pptx';
+};
+
+export type BrowserWorkspaceExportFormat =
+  | 'pdf'
+  | 'docx'
+  | 'xlsx'
+  | 'csv'
+  | 'pptx';
+
+/**
+ * The browser evaluates these fixed expressions. They are deliberately not
+ * user supplied JavaScript: page inspection and clipboard are first-class
+ * browser capabilities, while arbitrary eval remains a separate developer
+ * action.
+ */
+export const PAGE_ASSETS_EXPRESSION = `(() => {
+  const absolute = (value) => { try { return new URL(value, location.href).href; } catch { return ''; } };
+  const result = [];
+  const add = (kind, value, source, extra = {}) => {
+    const url = absolute(value);
+    if (!url || url.startsWith('javascript:')) return;
+    result.push({ kind, url, source, ...extra });
+  };
+  for (const el of document.images) add('image', el.currentSrc || el.src, 'dom', {
+    name: el.getAttribute('name') || undefined,
+    alt: el.alt || undefined,
+    width: Math.round(el.naturalWidth || el.getBoundingClientRect().width || 0) || undefined,
+    height: Math.round(el.naturalHeight || el.getBoundingClientRect().height || 0) || undefined,
+  });
+  for (const el of document.querySelectorAll('video, audio')) add(el.tagName.toLowerCase(), el.currentSrc || el.src, 'dom', {
+    type: el.getAttribute('type') || undefined,
+    width: Math.round(el.getBoundingClientRect().width || 0) || undefined,
+    height: Math.round(el.getBoundingClientRect().height || 0) || undefined,
+  });
+  for (const el of document.querySelectorAll('source')) add(el.parentElement?.tagName.toLowerCase() === 'audio' ? 'audio' : 'video', el.src, 'dom', { type: el.type || undefined });
+  for (const el of document.querySelectorAll('link[rel~="stylesheet"], link[rel~="icon"], link[rel="preload"]')) {
+    const rel = (el.rel || '').toLowerCase();
+    add(rel.includes('icon') ? 'icon' : rel.includes('stylesheet') ? 'stylesheet' : 'other', el.href, 'dom', { type: el.as || el.type || undefined });
+  }
+  for (const el of document.querySelectorAll('script[src]')) add('script', el.src, 'dom', { type: el.type || undefined });
+  for (const el of document.querySelectorAll('style')) {
+    const text = el.textContent || '';
+    if (text) result.push({ kind: 'stylesheet', url: 'inline:style-' + result.length, source: 'inline', inline: true, type: 'text/css', content: text.slice(0, 200000) });
+  }
+  for (const entry of performance.getEntriesByType('resource')) {
+    const name = entry.name || '';
+    if (/\\.(?:woff2?|ttf|otf)(?:[?#]|$)/i.test(name)) add('font', name, 'performance');
+  }
+  const seen = new Set();
+  return result.filter((item) => { const key = item.kind + '|' + item.url; if (seen.has(key)) return false; seen.add(key); return true; });
+})()`;
+
+export const CLIPBOARD_READ_TEXT_EXPRESSION = 'navigator.clipboard.readText()';
+
+/** Fetch one page asset inside the authenticated browser context. */
+export function browserAssetFetchExpression(url: string): string {
+  return `(async () => {
+    const response = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    return { ok: response.ok, status: response.status, type: response.headers.get('content-type') || '', base64: btoa(binary) };
+  })()`;
+}
+
+export const CLIPBOARD_READ_EXPRESSION = `(() => navigator.clipboard.read().then(async (items) => {
+  const result = [];
+  for (const item of items) {
+    for (const type of item.types) {
+      const blob = await item.getType(type);
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      let binary = '';
+      const chunk = 0x8000;
+      for (let i = 0; i < bytes.length; i += chunk) binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+      result.push({ type, base64: btoa(binary), size: bytes.length });
+    }
+  }
+  return result;
+}))()`;
+
+export function clipboardWriteExpression(
+  items: Array<{ type: string; base64: string }>,
+): string {
+  return `(async () => {
+    const items = ${JSON.stringify(items)};
+    await navigator.clipboard.write([new ClipboardItem(Object.fromEntries(items.map((item) => [item.type, fetch('data:' + item.type + ';base64,' + item.base64).then((response) => response.blob())])))]);
+    return true;
+  })()`;
+}
+
+export function clipboardWriteTextExpression(value: string): string {
+  return `navigator.clipboard.writeText(${JSON.stringify(value)}).then(() => true)`;
+}
+
+export function pageContentExpression(
+  format: BrowserPageContent['format'],
+  selector?: string,
+): string {
+  if (['pdf', 'docx', 'xlsx', 'csv', 'pptx'].includes(format)) {
+    return googleWorkspaceExportExpression(
+      format as BrowserWorkspaceExportFormat,
+    );
+  }
+  const selectorLiteral = JSON.stringify(selector || 'body');
+  return `(() => {
+    const root = document.querySelector(${selectorLiteral}) || document.body;
+    const text = (root.innerText || root.textContent || '').trim();
+    const html = root.outerHTML || '';
+    const title = document.title || '';
+    const url = location.href;
+    const value = { url, title, text, html, format: ${JSON.stringify(format)} };
+    if (${JSON.stringify(format)} === 'youtube-transcript') {
+      value.text = Array.from(document.querySelectorAll('ytd-transcript-segment-renderer, [data-purpose="transcript-segment"], .transcript-segment')).map((el) => (el.innerText || el.textContent || '').trim()).filter(Boolean).join('\\n') || text;
+    }
+    if (${JSON.stringify(format)} === 'google-workspace') {
+      value.text = Array.from(root.querySelectorAll('[contenteditable="true"], [role="textbox"], p, li, table')).map((el) => (el.innerText || el.textContent || '').trim()).filter(Boolean).join('\\n');
+    }
+    if (['text', 'txt', 'markdown', 'md', 'youtube-transcript', 'google-workspace'].includes(${JSON.stringify(format)})) delete value.html;
+    return value;
+  })()`;
+}
+
+/**
+ * Export an authenticated Google Workspace document from the current tab.
+ * The browser performs the request so the current login/session cookies are
+ * preserved; the agent never receives or stores cookies itself. The result is
+ * a compact base64 envelope consumed by BrowserBatch's deliverable writer.
+ */
+export function googleWorkspaceExportExpression(
+  format: BrowserWorkspaceExportFormat,
+): string {
+  return `(() => {
+    const href = location.href;
+    const match = href.match(/https?:\\/\\/(?:docs|sheets|slides)\\.google\\.com\\/(document|spreadsheets|presentation)\\/d\\/([^/]+)/i);
+    if (!match) return { error: '当前页面不是可导出的 Google Workspace 文档' };
+    const kind = match[1];
+    const id = match[2];
+    const format = ${JSON.stringify(format)};
+    const base = kind === 'document'
+      ? 'https://docs.google.com/document/d/' + id + '/export?format=' + format
+      : kind === 'spreadsheets'
+        ? 'https://docs.google.com/spreadsheets/d/' + id + '/export?format=' + format
+        : format === 'pptx'
+          ? 'https://docs.google.com/presentation/d/' + id + '/export/pptx'
+          : 'https://docs.google.com/presentation/d/' + id + '/export?format=' + format;
+    return fetch(base, { credentials: 'include' }).then(async (response) => {
+      if (!response.ok) return { error: 'Workspace 导出失败 HTTP ' + response.status, url: base };
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      let binary = '';
+      const chunk = 0x8000;
+      for (let i = 0; i < bytes.length; i += chunk) binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+      return { __browser_binary_base64: btoa(binary), format, url: base, size: bytes.length };
+    });
+  })()`;
+}
+
+export function markdownFromPageContent(
+  content: Pick<BrowserPageContent, 'title' | 'url' | 'text'>,
+): string {
+  const heading = content.title ? `# ${content.title}\n\n` : '';
+  return `${`${heading}${content.text}${content.url ? `\n\nSource: ${content.url}` : ''}`.trim()}\n`;
+}
+
+export function assetFileName(asset: BrowserPageAsset, index: number): string {
+  if (asset.url.startsWith('inline:'))
+    return `${asset.url.slice('inline:'.length)}.css`;
+  try {
+    const parsed = new URL(asset.url);
+    const name = basename(parsed.pathname) || `asset-${index}`;
+    const extension =
+      extname(name) ||
+      (asset.kind === 'stylesheet'
+        ? '.css'
+        : asset.kind === 'script'
+          ? '.js'
+          : '');
+    return `${String(index + 1).padStart(3, '0')}-${name.replace(/[^a-zA-Z0-9._-]/g, '_')}${extension && !name.endsWith(extension) ? extension : ''}`;
+  } catch {
+    return `${String(index + 1).padStart(3, '0')}-asset`;
+  }
+}
+
+export function assetBundleManifest(
+  assets: BrowserPageAsset[],
+  directory: string,
+): string {
+  return `${JSON.stringify(
+    { version: 1, directory: join(directory, 'assets'), assets },
+    null,
+    2,
+  )}\n`;
+}
+
+export async function bundlePageAssets(
+  assets: BrowserPageAsset[],
+  directory: string,
+  fetchImpl: (url: string) => Promise<Response> = (url) => fetch(url),
+): Promise<{
+  directory: string;
+  files: string[];
+  failures: Array<{ url: string; error: string }>;
+}> {
+  const assetDirectory = join(directory, 'assets');
+  await mkdir(assetDirectory, { recursive: true, mode: 0o700 });
+  const files: string[] = [];
+  const failures: Array<{ url: string; error: string }> = [];
+  for (const [index, asset] of assets.entries()) {
+    if (asset.inline && asset.content) {
+      const path = join(assetDirectory, assetFileName(asset, index));
+      await writeFile(path, asset.content, { mode: 0o600 });
+      files.push(path);
+      continue;
+    }
+    if (!/^https?:\/\//i.test(asset.url)) continue;
+    try {
+      const response = await fetchImpl(asset.url);
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      const path = join(assetDirectory, assetFileName(asset, index));
+      await writeFile(path, Buffer.from(await response.arrayBuffer()), {
+        mode: 0o600,
+      });
+      files.push(path);
+    } catch (error) {
+      failures.push({
+        url: asset.url,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  await writeFile(
+    join(directory, 'manifest.json'),
+    assetBundleManifest(assets, directory),
+    { mode: 0o600 },
+  );
+  return { directory, files, failures };
+}
+
+function cdpValue(result: unknown): unknown {
+  if (!result || typeof result !== 'object') return undefined;
+  const value = (result as { result?: { value?: unknown } }).result?.value;
+  return value;
+}
+
+/** Read URLs in short-lived background targets and always close those targets. */
+export async function readUrlsInBackground(
+  cdp: CdpConnection,
+  urls: string[],
+  timeoutMs: number,
+  contentType: 'text' | 'html' | 'domSnapshot' = 'text',
+  concurrency = 3,
+  signal?: AbortSignal,
+): Promise<
+  Array<{
+    url: string;
+    finalUrl?: string;
+    title?: string;
+    text?: string;
+    error?: string;
+  }>
+> {
+  const results: Array<{
+    url: string;
+    finalUrl?: string;
+    title?: string;
+    text?: string;
+    error?: string;
+  }> = [];
+  let next = 0;
+  const worker = async () => {
+    while (true) {
+      const index = next++;
+      if (index >= urls.length) return;
+      if (signal?.aborted) return;
+      const url = urls[index]!;
+      let targetId = '';
+      try {
+        const created = (await cdp.send(
+          'Target.createTarget',
+          { url },
+          undefined,
+          timeoutMs,
+          signal,
+        )) as {
+          targetId?: string;
+        };
+        targetId = created.targetId ?? '';
+        if (!targetId) throw new Error('浏览器未返回后台标签 ID');
+        const attached = (await cdp.send(
+          'Target.attachToTarget',
+          { targetId, flatten: true },
+          undefined,
+          timeoutMs,
+          signal,
+        )) as { sessionId?: string };
+        const sessionId = attached.sessionId;
+        if (!sessionId) throw new Error('无法连接后台标签');
+        const deadline = Date.now() + timeoutMs;
+        let state: unknown;
+        while (Date.now() < deadline) {
+          state = cdpValue(
+            await cdp
+              .send(
+                'Runtime.evaluate',
+                {
+                  expression:
+                    '({ready: document.readyState, url: location.href, title: document.title})',
+                  returnByValue: true,
+                },
+                sessionId,
+                timeoutMs,
+                signal,
+              )
+              .catch(() => ({})),
+          );
+          if (
+            state &&
+            typeof state === 'object' &&
+            ['interactive', 'complete'].includes(
+              String((state as { ready?: unknown }).ready),
+            )
+          )
+            break;
+          await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        let page: unknown;
+        if (contentType === 'domSnapshot') {
+          const ax = await cdp
+            .send('Accessibility.getFullAXTree', {}, sessionId)
+            .catch(() => undefined);
+          page = {
+            url: String((state as { url?: unknown } | undefined)?.url ?? url),
+            title: String(
+              (state as { title?: unknown } | undefined)?.title ?? '',
+            ),
+            text: JSON.stringify(ax ?? { nodes: [] }).slice(0, 300000),
+          };
+        } else {
+          const expression =
+            contentType === 'html'
+              ? `({url: location.href, title: document.title, text: document.documentElement?.outerHTML?.slice(0, 300000) || ''})`
+              : `({url: location.href, title: document.title, text: (document.body?.innerText || document.body?.textContent || '').slice(0, 200000)})`;
+          page = cdpValue(
+            await cdp.send(
+              'Runtime.evaluate',
+              {
+                expression,
+                returnByValue: true,
+              },
+              sessionId,
+              timeoutMs,
+              signal,
+            ),
+          );
+        }
+        if (!page || typeof page !== 'object')
+          throw new Error('无法读取后台页面内容');
+        results[index] = {
+          url,
+          finalUrl: String((page as { url?: unknown }).url ?? ''),
+          title: String((page as { title?: unknown }).title ?? ''),
+          text: String((page as { text?: unknown }).text ?? ''),
+        };
+      } catch (error) {
+        results[index] = {
+          url,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      } finally {
+        if (targetId)
+          await cdp
+            .send(
+              'Target.closeTarget',
+              { targetId },
+              undefined,
+              timeoutMs,
+              signal,
+            )
+            .catch(() => undefined);
+      }
+    }
+  };
+  await Promise.all(
+    Array.from(
+      { length: Math.max(1, Math.min(concurrency, urls.length)) },
+      () => worker(),
+    ),
+  );
+  return results.filter((result): result is NonNullable<typeof result> =>
+    Boolean(result),
+  );
+}

package/src/tools/webbrowser/browserControl.js

@@ -10,22 +10,32 @@ const CAPTCHA_PATTERNS = [
     /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 OTP_PATTERNS = [
+    /一次性密码|短信验证码|邮件验证码|动态口令|\botp\b|one[- ]time (?:password|code)/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,
+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,
+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];
+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);
@@ -47,6 +57,18 @@ export function detectBrowserChallenge(text) {
         return { reason: 'permission', summary: '页面需要人工确认权限' };
     return null;
 }
+/**
+ * 判定「持有者已经死了」的阈值。
+ *
+ * 取值有依据，不是拍脑袋：单次动作的 `timeout` 在 zod schema 里是 `.max(300_000)`，
+ * 语义是**整个序列**（前置探测 + 动作 + 收尾重探）的总时长。所以任何合法的 running
+ * 都有 300s 的硬上界，取 2× 作阈值 —— 合法长动作绝不会被误接管，而泄漏的锁在一个
+ * 动作周期后自动可用，不再是「本进程剩余生命周期内浏览器永久不可用」。
+ *
+ * ⚠️ 改小之前先确认 webbrowser.ts 里 preTimer 与 runSequence 各自的计时器在最长路径上
+ * 不会叠加；`browserControl.test.ts` 用假时钟锁住了这个不变量的行为面。
+ */
+export const DEFAULT_STALE_AFTER_MS = 600_000;
 export class BrowserControlCoordinator {
     state = { owner: 'none', status: 'idle' };
     listeners = new Set();
@@ -55,11 +77,29 @@ export class BrowserControlCoordinator {
     interventions = new HumanInterventionCoordinator();
     defaultOwnerId;
     defaultConversationKey;
+    staleAfterMs;
+    now;
+    onStaleTakeover;
+    /** 进入 running 的时刻；由 setState 统一维护，所以 resume 之后也会重新计时。 */
+    runningSince = 0;
     constructor(input = {}) {
         this.defaultOwnerId = input.ownerId ?? 'local-owner';
         this.defaultConversationKey = input.conversationKey ?? 'browser:default';
+        this.now = input.now ?? (() => Date.now());
+        this.staleAfterMs = input.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+        // 接管**绝不能静默**：不留痕的话，「这把锁曾经泄漏过」就再也查不到了，
+        // 而下一次排查会从一个已经自愈的现场开始 —— 那比报错更难查。
+        this.onStaleTakeover =
+            input.onStaleTakeover ??
+                ((info) => {
+                    process.stderr.write(`[browser] 上一个持有者（runId=${info.previousRunId ?? '?'}` +
+                        `${info.previousAction ? `, action=${info.previousAction}` : ''}）` +
+                        `已持锁 ${Math.round(info.heldMs / 1000)}s，超过 ${Math.round(this.staleAfterMs / 1000)}s 判为泄漏，已接管。\n`);
+                });
+    }
+    getState() {
+        return this.state;
     }
-    getState() { return this.state; }
     subscribe(listener) {
         this.listeners.add(listener);
         listener(this.state);
@@ -75,7 +115,24 @@ export class BrowserControlCoordinator {
             throw new Error('浏览器正在等待另一个任务的人工处理');
         }
         if (this.state.status === 'running' && this.state.runId !== input.runId) {
-            throw new Error('浏览器正在执行另一个会话的原子操作');
+            const heldMs = this.now() - this.runningSince;
+            if (heldMs < this.staleAfterMs) {
+                // 带上持锁者身份与已持有时长：这把锁是进程级单例，一旦泄漏，后续每次调用都撞
+                // 同一句话，而"另一个会话"是谁、卡在哪个动作上、卡了多久，现场早就没了。
+                // 时长尤其关键 —— 它把「真并发」和「已泄漏」在报错里一眼分开。
+                throw new Error(`浏览器正在执行另一个会话的原子操作（持有者 runId=${this.state.runId ?? '?'}` +
+                    `${this.state.action ? `, action=${this.state.action}` : ''}` +
+                    `${this.activeIdentity?.conversationKey ? `, conversation=${this.activeIdentity.conversationKey}` : ''}` +
+                    `, 已持有 ${Math.round(heldMs / 1000)}s）`);
+            }
+            // 超过任何合法动作的上界 —— 持有者的 finally 没能跑（进程被外部掐断、
+            // finally 自身抛错、或将来某条还没被想到的路径）。不接管的话，这个进程里的
+            // 浏览器就永久不可用了。接管并留痕，让「失败一次」不再等于「彻底报废」。
+            this.onStaleTakeover({
+                previousRunId: this.state.runId,
+                previousAction: this.state.action,
+                heldMs,
+            });
         }
         this.activeIdentity = {
             ownerId: this.defaultOwnerId,
@@ -99,11 +156,14 @@ export class BrowserControlCoordinator {
         const running = this.state.status === 'running' ? this.state : null;
         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(),
+            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,
@@ -131,21 +191,37 @@ export class BrowserControlCoordinator {
         }
         this.activeIntervention = null;
         this.activeIdentity = null;
-        this.setState({ owner: 'user', status: 'interactive', runId: input?.runId, conversationKey: input?.conversationKey });
+        this.setState({
+            owner: 'user',
+            status: 'interactive',
+            runId: input?.runId,
+            conversationKey: input?.conversationKey,
+        });
     }
     resume(token) {
-        if (this.state.status !== 'waiting_human' || !token || !this.activeIntervention || !this.activeIdentity)
+        if (this.state.status !== 'waiting_human' ||
+            !token ||
+            !this.activeIntervention ||
+            !this.activeIdentity)
             return false;
         const previous = this.state;
         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: '正在检查人工操作结果' });
+        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)
+        if (this.state.status !== 'waiting_human' ||
+            !this.activeIntervention ||
+            !this.activeIdentity)
             return false;
         const previous = this.state;
         if (!this.interventions.resume(credential))
@@ -175,7 +251,9 @@ export class BrowserControlCoordinator {
         return true;
     }
     cancelIntervention(credential) {
-        if (this.state.status !== 'waiting_human' || !this.activeIntervention || !this.activeIdentity)
+        if (this.state.status !== 'waiting_human' ||
+            !this.activeIntervention ||
+            !this.activeIdentity)
             return false;
         if (!this.interventions.cancel(credential))
             return false;
@@ -191,12 +269,26 @@ export class BrowserControlCoordinator {
         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'));
+        return this.interventions
+            .wait(waiter.interventionId, signal)
+            .then((resolution) => resolution.status === 'resumed' ? 'resumed' : 'stopped');
     }
     setState(state) {
+        // 所有进入 running 的路径都在这里重新计时（beginAgent 之外，还有 resume /
+        // resumeIntervention 从人工处理回到 agent 手里）。⚠️ 少了这一条，人工处理
+        // 花掉的时间会被算进持锁时长 —— 用户认真填了十分钟验证码，恢复的瞬间就被判成
+        // 「泄漏」让别人接管，正好惩罚了最该被保护的那条路径。
+        if (state.status === 'running')
+            this.runningSince = this.now();
         this.state = state;
-        for (const listener of this.listeners)
-            listener(state);
+        for (const listener of this.listeners) {
+            try {
+                listener(state);
+            }
+            catch {
+                // Observers are telemetry/UI extensions; control state must remain authoritative.
+            }
+        }
     }
     credential(intervention, identity, resumeToken = intervention.resumeToken) {
         return {
@@ -210,14 +302,23 @@ export class BrowserControlCoordinator {
 }
 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 '用户已接管浏览器';
+        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 '用户已接管浏览器';
     }
 }