minimal-agent 0.10.0 → 0.12.0

package/src/tools/webbrowser/browserOutcome.ts

@@ -0,0 +1,306 @@
+/**
+ * ============================================================
+ *  browserOutcome.ts —— 浏览器动作的「成功率」设施
+ * ------------------------------------------------------------
+ *  三件事，全部是纯函数，因此可以被单测钉死：
+ *    ① 页面指纹与变化判定（动作到底生效了没有）
+ *    ② 选择器失败时的候选推荐（把「没找到」变成「最接近的是这几个」）
+ *    ③ 同一目标连续失败的熔断计数
+ *
+ *  为什么这些属于「成功率」而不是「锦上添花」：模型的每一次重试都是一个 LLM 往返，
+ *  而它重试时**手上没有当前页面**——失败只回了一句 `selector not found`。于是最常见
+ *  的失败形状不是「做错了」，是「原地换着选择器盲猜三五轮，然后放弃」。
+ * ============================================================
+ */
+
+/** 会被验证「是否真的改变了页面」的动作。 */
+export const VERIFIED_BROWSER_ACTIONS = new Set([
+  'click',
+  'fill',
+  'type',
+  'select',
+  'press',
+  'drag',
+]);
+
+export type BrowserEffect = 'changed' | 'unchanged' | 'unknown';
+
+/**
+ * 两份快照中内容不同的行号。行数不同则返回 null —— 那本身就是结构变化。
+ *
+ * ⚠️ 两边都先 `trim()`。动作前的快照是原始 stdout、动作后那份在别处被 trim 过，
+ * 一个尾随换行就让行数对不上、直接判成「结构变了」，于是**所有**动作都判 changed，
+ * 噪声扣除彻底失效。基准集跑出来才发现——纯逻辑单测里两边都是我手写的字符串，
+ * 永远不会有这种不对称。
+ */
+export function differingLineIndexes(a: string, b: string): Set<number> | null {
+  const left = a.trim().split('\n');
+  const right = b.trim().split('\n');
+  if (left.length !== right.length) return null;
+  const diff = new Set<number>();
+  for (let i = 0; i < left.length; i += 1) {
+    if (left[i].trim() !== right[i].trim()) diff.add(i);
+  }
+  return diff;
+}
+
+/**
+ * 一次生效判定的结论。
+ *
+ * `maskedLines` 不是调试信息，是**结论的可信度**：它是被当作噪声豁免掉的行数。
+ * 判定不可能区分「这一行在自己跳」和「这一行既在自己跳、又刚好被我的动作改了」——
+ * 信息论上就是不可分的。所以豁免多少必须随结论一起报出去，由模型自己权衡。
+ */
+export interface BrowserEffectVerdict {
+  effect: BrowserEffect;
+  /** 被噪声基线豁免掉的行数（仅 `unchanged` 时可能 > 0）。 */
+  maskedLines: number;
+}
+
+/**
+ * 判定一次动作是否真的改变了页面。
+ *
+ * **噪声是测出来的，不是猜出来的**：`after` 之后隔一小段再拍一张 `noiseAfter`，
+ * 两张之间自己变了的**行位置**就是噪声源（时钟、未读数、轮询列表）。再看
+ * 「动作前→动作后」变了的行里，除掉这些位置之后还剩不剩。
+ *
+ * ⚠️ 噪声基线取在**动作之后**而不是之前。噪声是页面的持续属性，前后测等价；
+ * 而放在后面换来两件事：`before === after` 时（正是要判 unchanged 的情形）根本
+ * 不必采样，零成本；采样的那段等待也不再推迟动作本身的发出。
+ *
+ * 三个实测踩过的坑，这里同时避开：
+ *   · 直接比全页文本 → 时钟每 200ms 一跳，恒判「变了」，判定形同虚设；
+ *   · 忽略所有文本只看结构 → 点击把 `StaticText "closed"` 变成 `"opened"` 这种
+ *     **真正生效**的纯文本变化被报成「完全没有变化」。误报比不报更糟：它在教模型
+ *     不要相信一个正确的动作；
+ *   · 按行**内容**标定噪声 → 时钟每次都是新值，永远匹配不上自己。所以按行**位置**。
+ *
+ * 行数一变就直接算 changed —— 结构动了，不必再细究。
+ */
+export function classifyPageEffect(
+  before: string | undefined,
+  after: string | undefined,
+  noiseAfter?: string,
+): BrowserEffectVerdict {
+  if (before === undefined || after === undefined) return { effect: 'unknown', maskedLines: 0 };
+  const actual = differingLineIndexes(before, after);
+  if (actual === null) return { effect: 'changed', maskedLines: 0 }; // 行数变了 = 结构变了
+  if (actual.size === 0) return { effect: 'unchanged', maskedLines: 0 };
+  const noisy = noiseAfter !== undefined ? differingLineIndexes(after, noiseAfter) : null;
+  // 没有可用的噪声基线时不做扣除：宁可把「生效了」判宽，也不能把一次真实变化
+  // 误报成没变——那会让模型放弃一条本来走通了的路。
+  if (noisy === null) return { effect: 'changed', maskedLines: 0 };
+  for (const index of actual) if (!noisy.has(index)) return { effect: 'changed', maskedLines: 0 };
+  return { effect: 'unchanged', maskedLines: actual.size };
+}
+
+/** 给模型的效果说明。措辞要让它知道**下一步该干什么**，不只是知道结果。 */
+export function describeEffect(verdict: BrowserEffectVerdict, action: string): string | null {
+  switch (verdict.effect) {
+    case 'changed':
+      return null; // 正常路径不加噪声
+    case 'unchanged':
+      return (
+        `⚠️ 动作已发出，但页面结构在动作前后**完全没有变化**。\n`
+        + `这通常意味着三种情况之一：${action} 命中的不是可交互元素、点击被遮挡层拦住了、`
+        + `或者这个操作本来就不改变页面（比如点了一个纯展示文本）。\n`
+        + `请对照下面的最新快照确认目标是否正确，不要用同一个选择器直接重试。`
+        // 豁免了行才提。这不是免责声明，是让模型知道这个结论有多硬：
+        // 被豁免的位置上，「自己在跳」和「被我改了又在跳」不可区分。
+        + (verdict.maskedLines > 0
+          ? `\n（说明：页面上有 ${verdict.maskedLines} 行在持续自行变化（时钟/轮询一类），`
+            + `已从判定中排除。若你这次操作本该影响的正是这些位置，这个结论可能不准。）`
+          : '')
+      );
+    case 'unknown':
+      return '（未能取得动作前后的页面快照，无法判断这次操作是否生效——请自行核对。）';
+  }
+}
+
+/** 从 `@eN` 快照里抽出的一个可点目标。 */
+export interface SnapshotCandidate {
+  ref: string;
+  line: string;
+}
+
+/**
+ * 解析快照里的元素引用行。
+ *
+ * 匹配 `ref=eN` 而不是 `[ref=eN]`：真实行是 `[level=1, ref=e1]`，ref 常和别的属性
+ * 混在同一个方括号里。第一版按 `[ref=` 起头写，于是带属性的行（heading/button 这类
+ * 最该被推荐的）全部漏掉——真实样本进测试之后才暴露。
+ *
+ * ⚠️ **两种形状都要认**。文档和工具描述里写的是 `@eN`，但 agent-browser 实际输出的是
+ * `[ref=e1]`：
+ *   `- link "Learn more" [ref=e2]`
+ * 第一版只认 `@eN`，于是候选推荐在真实页面上**一个都匹配不到** —— 单测全绿，实机零命中。
+ * 是跑了一次真的 example.com 才发现的。两种都收，并统一成 `@eN` 交给模型（那是它被教的
+ * 引用写法）。
+ */
+export function parseSnapshotCandidates(snapshot: string): SnapshotCandidate[] {
+  const out: SnapshotCandidate[] = [];
+  for (const raw of snapshot.split('\n')) {
+    const line = raw.trim();
+    const match = /@e(\d+)|\bref=e(\d+)/.exec(line);
+    if (!match) continue;
+    const id = match[1] ?? match[2];
+    out.push({ ref: `@e${id}`, line: line.slice(0, 160) });
+  }
+  return out;
+}
+
+/**
+ * 归一化成可比较的词：小写、去标点、拆词。
+ *
+ * ⚠️ 连字符和下划线**必须**当分隔符。真实 CSS 选择器几乎全是 `a.learn-more-link`、
+ * `#btn_submit`、`[data-testid=...]` 这个形状，不拆的话整串是一个词，和快照里的
+ * `link "Learn more"` 永远匹配不上 —— 功能在最常见的输入上直接失效。
+ * 第一版漏了这两个字符，单测（用的是中文与空格分词的样本）全绿，实机零命中。
+ */
+function tokenize(value: string): string[] {
+  return value
+    .toLowerCase()
+    .replace(/[#.>[\]="'`(),:{}\-_/*+~|]/g, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length > 1);
+}
+
+/**
+ * 选择器没命中时，从快照里挑出最像目标的几个候选。
+ *
+ * 打分只用「词重叠」这一件事，不引模糊匹配库：这里要的不是排序精度，是**给模型一个
+ * 能立刻拿去用的 `@eN` 列表**，而不是让它对着 `selector not found` 再猜一轮。
+ * 排名差一点无所谓，列表里有正确答案就赢了。
+ */
+export function suggestSelectorCandidates(
+  snapshot: string,
+  selector: string,
+  limit = 5,
+): SnapshotCandidate[] {
+  const wanted = tokenize(selector);
+  if (wanted.length === 0) return [];
+  const scored = parseSnapshotCandidates(snapshot)
+    .map((candidate) => {
+      const tokens = new Set(tokenize(candidate.line));
+      let score = 0;
+      for (const token of wanted) {
+        if (tokens.has(token)) score += 2;
+        else if (candidate.line.toLowerCase().includes(token)) score += 1;
+      }
+      return { candidate, score };
+    })
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+  return scored.map((entry) => entry.candidate);
+}
+
+/**
+ * 同一目标连续失败的熔断计数。
+ *
+ * 语义**刻意与 ComputerUse 的 `refuseWhenStuck` 一致**：清零的条件是「**这个动作**
+ * 成功了一次」，读取类动作（snapshot/getContent）成功**不清**写操作的账。
+ * 原因在那边写过：`失败 → snapshot → 失败 → snapshot …` 正是模型打转时最常见的形状，
+ * 让 snapshot 清零等于熔断永远数不到上限。
+ */
+export class BrowserAttemptLedger {
+  private counts = new Map<string, number>();
+
+  private static key(conversationKey: string, action: string, selector?: string): string {
+    return `${conversationKey}${action}${selector ?? ''}`;
+  }
+
+  recordFailure(conversationKey: string, action: string, selector?: string): number {
+    const key = BrowserAttemptLedger.key(conversationKey, action, selector);
+    const next = (this.counts.get(key) ?? 0) + 1;
+    this.counts.set(key, next);
+    return next;
+  }
+
+  recordSuccess(conversationKey: string, action: string, selector?: string): void {
+    this.counts.delete(BrowserAttemptLedger.key(conversationKey, action, selector));
+  }
+
+  failures(conversationKey: string, action: string, selector?: string): number {
+    return this.counts.get(BrowserAttemptLedger.key(conversationKey, action, selector)) ?? 0;
+  }
+
+  /** 会话结束时清账，避免长期驻留。 */
+  forget(conversationKey: string): void {
+    for (const key of [...this.counts.keys()]) {
+      if (key.startsWith(`${conversationKey}`)) this.counts.delete(key);
+    }
+  }
+}
+
+/** 同一 (动作, 选择器) 连续失败到这个次数就拒绝再试。 */
+export const BROWSER_FAILURE_LIMIT = 3;
+
+export const browserAttempts = new BrowserAttemptLedger();
+
+/** 单行最长保留字符数；超出就地截断，不因为一行长就丢掉整行的引用信息。 */
+const MAX_SNAPSHOT_LINE_CHARS = 300;
+
+/**
+ * 把快照收进上下文预算。
+ *
+ * 失败回执里带整份快照曾经是**最贵的一笔开销**：大页面 30k 字符 ≈ 8k token，而一次
+ * 失败往往连着几次。更糟的是这些 token 大半花在纯文本节点上——模型下一步要用的是
+ * **可引用的元素**（带 ref 的行），成段的正文对「换个目标重试」毫无帮助。
+ *
+ * 所以预算不是简单截断，是**按价值取舍**：带 ref 的行优先保留（那是可操作面），
+ * 纯文本行只在还有余量时补。
+ *
+ * ⚠️ 但取舍**只决定留哪些行，不决定行的顺序**。快照是一棵缩进树，把带 ref 的行
+ * 全部提到前面会让缩进层级与父子关系错位——模型看到的是一棵结构被打乱、看上去却
+ * 仍然合法的树，判断「这个按钮在哪个对话框里」时比截断更有害。所以输出严格按原序，
+ * 连续被删的段落就地留一条 `… 省略 N 行` 占位，让模型知道**哪里**有东西被省了。
+ */
+export function budgetSnapshot(
+  snapshot: string,
+  opts: { maxLines?: number; maxChars?: number } = {},
+): string {
+  const maxLines = opts.maxLines ?? 80;
+  const maxChars = opts.maxChars ?? 6_000;
+  const lines = snapshot.split('\n').filter((line) => line.trim().length > 0);
+  if (lines.length <= maxLines && snapshot.length <= maxChars) return snapshot;
+
+  const hasRef = (line: string): boolean => /@e\d+|\bref=e\d+/.test(line);
+  const clip = (line: string): string =>
+    line.length <= MAX_SNAPSHOT_LINE_CHARS ? line : `${line.slice(0, MAX_SNAPSHOT_LINE_CHARS)}…`;
+
+  // 两轮**只挑不排**：先在原序上标记要留的可操作行，再用余量补纯文本行。
+  const keep = new Array<boolean>(lines.length).fill(false);
+  let kept = 0;
+  let chars = 0;
+  const take = (index: number): void => {
+    if (keep[index] || kept >= maxLines) return;
+    const cost = clip(lines[index]).length + 1;
+    // 放不下就跳过这一行继续看下一行——`break` 会让一条超长行连累后面所有放得下的。
+    if (chars + cost > maxChars) return;
+    keep[index] = true;
+    kept += 1;
+    chars += cost;
+  };
+  for (let i = 0; i < lines.length; i += 1) if (hasRef(lines[i])) take(i);
+  for (let i = 0; i < lines.length; i += 1) if (!hasRef(lines[i])) take(i);
+
+  const out: string[] = [];
+  let gap = 0;
+  const flushGap = (): void => {
+    if (gap > 0) out.push(`  … 省略 ${gap} 行`);
+    gap = 0;
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    if (keep[i]) { flushGap(); out.push(clip(lines[i])); }
+    else gap += 1;
+  }
+  flushGap();
+
+  const dropped = lines.length - kept;
+  return (
+    `${out.join('\n')}\n`
+    + `… 为控制上下文，共省略 ${dropped} 行（按原顺序保留，优先保住可引用的元素）。`
+    + '需要完整页面请单独调用 snapshot，或用 getContent 读取正文。'
+  );
+}

package/src/tools/webbrowser/browserRunRegistry.js

@@ -0,0 +1,150 @@
+import { randomUUID } from 'node:crypto';
+const NEGATED_ACTION_PREFIX = /(?:不要|不需(?:要)?|不能|不可|别|禁止|避免|无需|切勿)(?:再|自动|直接|帮我|替我|进行)?[\s\S]{0,8}$|(?:do\s+not|don't|never|must\s+not|should\s+not|without)(?:\s+\w+){0,4}\s*$/i;
+function hasUnnegatedAction(text, pattern) {
+    for (const match of text.matchAll(pattern)) {
+        const prefix = text.slice(Math.max(0, (match.index ?? 0) - 32), match.index);
+        if (!NEGATED_ACTION_PREFIX.test(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Derive only task-level grants explicitly present in the owner's message.
+ * Page text and model-generated arguments never call this helper, so they
+ * cannot expand the current browser task's authority.
+ */
+export function inferBrowserTaskGrants(text) {
+    const grants = ['observe', 'interact'];
+    if (hasUnnegatedAction(text, /\b(?:upload|attach)\b(?!\s+(?:page|button|history|settings))|上传(?!页|页面|按钮|记录|历史|设置)|选择文件|添加文件/giu))
+        grants.push('upload');
+    if (hasUnnegatedAction(text, /\b(?:publish|submit|purchase|buy|delete|place\s+(?:an?\s+)?order|send)\b(?!\s+(?:page|button|history|record|settings))|发布(?!页|页面|按钮|记录|历史|设置)|发表(?!页|页面|按钮|记录|历史|设置)|提交(?!页|页面|按钮|记录|历史|设置)|购买|下单|删除|发送/giu))
+        grants.push('submit');
+    return grants;
+}
+/** Detect obvious final-action controls before they are clicked. */
+export function isLikelyIrreversibleBrowserTarget(label) {
+    const normalized = label.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return false;
+    return /(?:^|[\s"'=:_-])(?:publish|submit|purchase|buy now|place order|delete|confirm delete|send)(?:$|[\s"'=:_-])/i.test(normalized)
+        || /(?:发布|发表|提交|立即购买|确认购买|确认下单|删除|确认删除|发送)(?:$|[\s：:）)】\]])/.test(normalized);
+}
+/**
+ * Process-wide ownership registry for the shared browser profile.
+ *
+ * The Chrome profile intentionally spans conversations so login state can be
+ * reused. Tabs and control leases do not: every browser action must first bind
+ * to a conversation/run and may only target tabs claimed by that conversation.
+ */
+export class BrowserRunRegistry {
+    runs = new Map();
+    conversationTabs = new Map();
+    tabOwners = new Map();
+    ensure(input) {
+        const key = this.key(input.conversationKey, input.runId ?? 'workbench');
+        const existing = this.runs.get(key);
+        if (existing) {
+            if (input.grants)
+                existing.grants = [...new Set(input.grants)];
+            if (input.taskGrantId !== undefined)
+                existing.taskGrantId = input.taskGrantId;
+            if (input.allowedUploadRoots)
+                existing.allowedUploadRoots = [...new Set(input.allowedUploadRoots)];
+            return existing;
+        }
+        const context = {
+            conversationKey: input.conversationKey,
+            runId: input.runId ?? randomUUID(),
+            profileId: input.profileId ?? 'default',
+            claimedTabIds: [],
+            grants: [...new Set(input.grants ?? ['observe', 'interact'])],
+            allowedUploadRoots: [...new Set(input.allowedUploadRoots ?? [])],
+            ...(input.taskGrantId ? { taskGrantId: input.taskGrantId } : {}),
+        };
+        this.runs.set(this.key(context.conversationKey, context.runId), context);
+        return context;
+    }
+    find(conversationKey, runId) {
+        if (runId)
+            return this.runs.get(this.key(conversationKey, runId));
+        return [...this.runs.values()].find((item) => item.conversationKey === conversationKey);
+    }
+    claimedTabs(conversationKey) {
+        return [...(this.conversationTabs.get(conversationKey) ?? [])];
+    }
+    ownerOf(tabId) {
+        return this.tabOwners.get(tabId);
+    }
+    claimTab(context, tabId) {
+        const owner = this.tabOwners.get(tabId);
+        if (owner && owner !== context.conversationKey) {
+            throw new Error('该浏览器标签属于另一个会话，已阻止跨会话操作');
+        }
+        this.tabOwners.set(tabId, context.conversationKey);
+        const claimed = this.conversationTabs.get(context.conversationKey) ?? new Set();
+        claimed.add(tabId);
+        this.conversationTabs.set(context.conversationKey, claimed);
+        context.claimedTabIds = [...claimed];
+        context.activeTabId = tabId;
+    }
+    /**
+     * 清掉一个会话的全部登记（标签归属 + run 上下文）。
+     *
+     * 注册表原先只有「释放单个标签」，没有会话级收口：长驻进程里每个结束的会话都会把
+     * 自己的标签归属永久留在表里，后来的会话再想认领同一个标签就会被判成跨会话冲突。
+     * 测试里先撞上（基准集跑完不清理，把 browserTabs 的用例挤挂了），但这是生产同款问题。
+     */
+    forgetConversation(conversationKey) {
+        for (const tabId of this.claimedTabs(conversationKey))
+            this.releaseTab(conversationKey, tabId);
+        this.conversationTabs.delete(conversationKey);
+        for (const [key, run] of [...this.runs.entries()]) {
+            if (run.conversationKey === conversationKey)
+                this.runs.delete(key);
+        }
+    }
+    releaseTab(conversationKey, tabId) {
+        if (this.tabOwners.get(tabId) !== conversationKey)
+            return;
+        this.tabOwners.delete(tabId);
+        const claimed = this.conversationTabs.get(conversationKey);
+        claimed?.delete(tabId);
+        if (claimed?.size === 0)
+            this.conversationTabs.delete(conversationKey);
+        for (const run of this.runs.values()) {
+            if (run.conversationKey !== conversationKey)
+                continue;
+            run.claimedTabIds = [...(claimed ?? [])];
+            if (run.activeTabId === tabId)
+                run.activeTabId = run.claimedTabIds[0];
+        }
+    }
+    assertTab(context, tabId) {
+        if (this.tabOwners.get(tabId) !== context.conversationKey) {
+            throw new Error('当前标签未被本会话认领，已阻止浏览器操作');
+        }
+    }
+    requireGrant(context, grant) {
+        if (!context.grants.includes(grant)) {
+            throw new Error(`当前浏览器任务未获得 ${grant} 权限`);
+        }
+    }
+    acquireLease(context) {
+        if (context.controlLeaseId)
+            return context.controlLeaseId;
+        context.controlLeaseId = randomUUID();
+        return context.controlLeaseId;
+    }
+    releaseLease(context, leaseId) {
+        if (leaseId && context.controlLeaseId !== leaseId)
+            return;
+        context.controlLeaseId = undefined;
+    }
+    finish(conversationKey, runId) {
+        this.runs.delete(this.key(conversationKey, runId));
+    }
+    key(conversationKey, runId) {
+        return `${conversationKey}\u0000${runId}`;
+    }
+}
+export const browserRunRegistry = new BrowserRunRegistry();

package/src/tools/webbrowser/browserRunRegistry.ts

@@ -0,0 +1,179 @@
+import { randomUUID } from 'node:crypto';
+
+export type BrowserActionGrant = 'observe' | 'interact' | 'upload' | 'submit';
+
+const NEGATED_ACTION_PREFIX = /(?:不要|不需(?:要)?|不能|不可|别|禁止|避免|无需|切勿)(?:再|自动|直接|帮我|替我|进行)?[\s\S]{0,8}$|(?:do\s+not|don't|never|must\s+not|should\s+not|without)(?:\s+\w+){0,4}\s*$/i;
+
+function hasUnnegatedAction(text: string, pattern: RegExp): boolean {
+  for (const match of text.matchAll(pattern)) {
+    const prefix = text.slice(Math.max(0, (match.index ?? 0) - 32), match.index);
+    if (!NEGATED_ACTION_PREFIX.test(prefix)) return true;
+  }
+  return false;
+}
+
+/**
+ * Derive only task-level grants explicitly present in the owner's message.
+ * Page text and model-generated arguments never call this helper, so they
+ * cannot expand the current browser task's authority.
+ */
+export function inferBrowserTaskGrants(text: string): BrowserActionGrant[] {
+  const grants: BrowserActionGrant[] = ['observe', 'interact'];
+  if (hasUnnegatedAction(text, /\b(?:upload|attach)\b(?!\s+(?:page|button|history|settings))|上传(?!页|页面|按钮|记录|历史|设置)|选择文件|添加文件/giu)) grants.push('upload');
+  if (hasUnnegatedAction(
+    text,
+    /\b(?:publish|submit|purchase|buy|delete|place\s+(?:an?\s+)?order|send)\b(?!\s+(?:page|button|history|record|settings))|发布(?!页|页面|按钮|记录|历史|设置)|发表(?!页|页面|按钮|记录|历史|设置)|提交(?!页|页面|按钮|记录|历史|设置)|购买|下单|删除|发送/giu,
+  )) grants.push('submit');
+  return grants;
+}
+
+/** Detect obvious final-action controls before they are clicked. */
+export function isLikelyIrreversibleBrowserTarget(label: string): boolean {
+  const normalized = label.replace(/\s+/g, ' ').trim();
+  if (!normalized) return false;
+  return /(?:^|[\s"'=:_-])(?:publish|submit|purchase|buy now|place order|delete|confirm delete|send)(?:$|[\s"'=:_-])/i.test(normalized)
+    || /(?:发布|发表|提交|立即购买|确认购买|确认下单|删除|确认删除|发送)(?:$|[\s：:）)】\]])/.test(normalized);
+}
+
+export interface BrowserRunContext {
+  conversationKey: string;
+  runId: string;
+  profileId: string;
+  claimedTabIds: string[];
+  activeTabId?: string;
+  controlLeaseId?: string;
+  taskGrantId?: string;
+  grants: BrowserActionGrant[];
+  allowedUploadRoots: string[];
+}
+
+type BrowserRunInput = {
+  conversationKey: string;
+  runId?: string;
+  profileId?: string;
+  taskGrantId?: string;
+  grants?: BrowserActionGrant[];
+  allowedUploadRoots?: string[];
+};
+
+/**
+ * Process-wide ownership registry for the shared browser profile.
+ *
+ * The Chrome profile intentionally spans conversations so login state can be
+ * reused. Tabs and control leases do not: every browser action must first bind
+ * to a conversation/run and may only target tabs claimed by that conversation.
+ */
+export class BrowserRunRegistry {
+  private readonly runs = new Map<string, BrowserRunContext>();
+  private readonly conversationTabs = new Map<string, Set<string>>();
+  private readonly tabOwners = new Map<string, string>();
+
+  ensure(input: BrowserRunInput): BrowserRunContext {
+    const key = this.key(input.conversationKey, input.runId ?? 'workbench');
+    const existing = this.runs.get(key);
+    if (existing) {
+      if (input.grants) existing.grants = [...new Set(input.grants)];
+      if (input.taskGrantId !== undefined) existing.taskGrantId = input.taskGrantId;
+      if (input.allowedUploadRoots) existing.allowedUploadRoots = [...new Set(input.allowedUploadRoots)];
+      return existing;
+    }
+    const context: BrowserRunContext = {
+      conversationKey: input.conversationKey,
+      runId: input.runId ?? randomUUID(),
+      profileId: input.profileId ?? 'default',
+      claimedTabIds: [],
+      grants: [...new Set<BrowserActionGrant>(input.grants ?? ['observe', 'interact'])],
+      allowedUploadRoots: [...new Set(input.allowedUploadRoots ?? [])],
+      ...(input.taskGrantId ? { taskGrantId: input.taskGrantId } : {}),
+    };
+    this.runs.set(this.key(context.conversationKey, context.runId), context);
+    return context;
+  }
+
+  find(conversationKey: string, runId?: string): BrowserRunContext | undefined {
+    if (runId) return this.runs.get(this.key(conversationKey, runId));
+    return [...this.runs.values()].find((item) => item.conversationKey === conversationKey);
+  }
+
+  claimedTabs(conversationKey: string): string[] {
+    return [...(this.conversationTabs.get(conversationKey) ?? [])];
+  }
+
+  ownerOf(tabId: string): string | undefined {
+    return this.tabOwners.get(tabId);
+  }
+
+  claimTab(context: BrowserRunContext, tabId: string): void {
+    const owner = this.tabOwners.get(tabId);
+    if (owner && owner !== context.conversationKey) {
+      throw new Error('该浏览器标签属于另一个会话，已阻止跨会话操作');
+    }
+    this.tabOwners.set(tabId, context.conversationKey);
+    const claimed = this.conversationTabs.get(context.conversationKey) ?? new Set<string>();
+    claimed.add(tabId);
+    this.conversationTabs.set(context.conversationKey, claimed);
+    context.claimedTabIds = [...claimed];
+    context.activeTabId = tabId;
+  }
+
+  /**
+   * 清掉一个会话的全部登记（标签归属 + run 上下文）。
+   *
+   * 注册表原先只有「释放单个标签」，没有会话级收口：长驻进程里每个结束的会话都会把
+   * 自己的标签归属永久留在表里，后来的会话再想认领同一个标签就会被判成跨会话冲突。
+   * 测试里先撞上（基准集跑完不清理，把 browserTabs 的用例挤挂了），但这是生产同款问题。
+   */
+  forgetConversation(conversationKey: string): void {
+    for (const tabId of this.claimedTabs(conversationKey)) this.releaseTab(conversationKey, tabId);
+    this.conversationTabs.delete(conversationKey);
+    for (const [key, run] of [...this.runs.entries()]) {
+      if (run.conversationKey === conversationKey) this.runs.delete(key);
+    }
+  }
+
+  releaseTab(conversationKey: string, tabId: string): void {
+    if (this.tabOwners.get(tabId) !== conversationKey) return;
+    this.tabOwners.delete(tabId);
+    const claimed = this.conversationTabs.get(conversationKey);
+    claimed?.delete(tabId);
+    if (claimed?.size === 0) this.conversationTabs.delete(conversationKey);
+    for (const run of this.runs.values()) {
+      if (run.conversationKey !== conversationKey) continue;
+      run.claimedTabIds = [...(claimed ?? [])];
+      if (run.activeTabId === tabId) run.activeTabId = run.claimedTabIds[0];
+    }
+  }
+
+  assertTab(context: BrowserRunContext, tabId: string): void {
+    if (this.tabOwners.get(tabId) !== context.conversationKey) {
+      throw new Error('当前标签未被本会话认领，已阻止浏览器操作');
+    }
+  }
+
+  requireGrant(context: BrowserRunContext, grant: BrowserActionGrant): void {
+    if (!context.grants.includes(grant)) {
+      throw new Error(`当前浏览器任务未获得 ${grant} 权限`);
+    }
+  }
+
+  acquireLease(context: BrowserRunContext): string {
+    if (context.controlLeaseId) return context.controlLeaseId;
+    context.controlLeaseId = randomUUID();
+    return context.controlLeaseId;
+  }
+
+  releaseLease(context: BrowserRunContext, leaseId?: string): void {
+    if (leaseId && context.controlLeaseId !== leaseId) return;
+    context.controlLeaseId = undefined;
+  }
+
+  finish(conversationKey: string, runId: string): void {
+    this.runs.delete(this.key(conversationKey, runId));
+  }
+
+  private key(conversationKey: string, runId: string): string {
+    return `${conversationKey}\u0000${runId}`;
+  }
+}
+
+export const browserRunRegistry = new BrowserRunRegistry();

package/src/tools/webbrowser/browserService.js

@@ -5,17 +5,28 @@
  */
 export class BrowserService {
     tails = new Map();
-    async run(input) {
+    async exclusive(input, task) {
         const previous = this.tails.get(input.sessionName) ?? Promise.resolve();
         let release;
         const current = new Promise((resolve) => { release = resolve; });
-        const tail = previous.then(() => current);
+        // 链上永远接一个已消化的 previous：任何一环 reject 都不能顺着队列传下去，
+        // 否则后来者在 `await previous` 处抛出。
+        const tail = previous.catch(() => undefined).then(() => current);
         this.tails.set(input.sessionName, tail);
-        await previous;
+        // ⚠️ `await previous` **必须在 try 之内**。它曾经在 try 之外：previous 一旦 reject，
+        // 函数在进入 try 之前就抛出 → `release()` 永不执行 → `current` 永不 resolve →
+        // 后续所有该 session 的动作永久排队。症状是死锁而不是异常，排查起来极难。
+        // 当前 current 只 resolve 不 reject，所以实际安全 —— 但那是一条没写下来的不变量，
+        // 谁往链上加一个 .then 都可能打破它。把 await 挪进来，安全性就不再依赖它。
         try {
-            if (input.signal?.aborted)
-                return { code: -1, stdout: '', stderr: 'Browser action cancelled' };
-            return await input.runner(input.bin, input.args, input.signal);
+            await previous.catch(() => undefined);
+            const run = async (args) => {
+                if (input.signal?.aborted) {
+                    return { code: -1, stdout: '', stderr: 'Browser action cancelled' };
+                }
+                return input.runner(input.bin, args, input.signal);
+            };
+            return await task(run);
         }
         finally {
             release();
@@ -23,5 +34,8 @@ export class BrowserService {
                 this.tails.delete(input.sessionName);
         }
     }
+    async run(input) {
+        return this.exclusive(input, (run) => run(input.args));
+    }
 }
 export const browserService = new BrowserService();