minimal-agent 0.10.0 → 0.12.0

package/src/tools/webbrowser/browserService.ts

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

package/src/tools/webbrowser/browserStream.js

@@ -11,10 +11,15 @@ class SessionBrowserStream {
     status = { connected: false, screencasting: false };
     picker;
     marked = [];
-    control = new BrowserControlCoordinator();
+    control;
     constructor(sessionName) {
         this.sessionName = sessionName;
+        this.control = new BrowserControlCoordinator({ conversationKey: `browser:${sessionName}` });
         this.control.subscribe((state) => this.emit({ type: 'control_state', state }));
+        this.control.subscribeInterventions((event) => this.emit({
+            type: event.type === 'started' ? 'human_intervention_started' : 'human_intervention_resolved',
+            event,
+        }));
     }
     async connect() {
         if (this.socket?.readyState === WebSocket.OPEN)
@@ -77,17 +82,41 @@ class SessionBrowserStream {
         this.emit({ type: 'marked_elements', elements: this.marked });
     }
     clearMarkedElements() { this.marked = []; this.emit({ type: 'marked_elements', elements: [] }); }
+    unmarkElement(ref) {
+        const next = this.marked.filter((item) => item.ref !== ref);
+        if (next.length !== this.marked.length) {
+            this.marked = next;
+            this.emit({ type: 'marked_elements', elements: this.marked });
+        }
+    }
     setAgentActing(acting, action, target) {
         this.emit({ type: 'agent_acting', acting, action, target });
     }
+    setAgentCandidates(candidates, selector) {
+        this.emit({ type: 'agent_candidates', candidates, selector });
+    }
+    setAgentOutcome(outcome) {
+        this.emit({ type: 'agent_outcome', ...outcome });
+    }
+    setAgentPointer(pointer) {
+        // 只发语义终点（目标元素中心 + 动作类型）；平滑移动交给面板 CSS 过渡，内核不做逐帧插值（避免 WS 洪泛 + 双层缓动打架）。
+        this.emit({ type: 'agent_pointer', ...pointer });
+    }
     getControlState() { return this.control.getState(); }
     subscribeControl(listener) { return this.control.subscribe(listener); }
+    subscribeInterventions(listener) { return this.control.subscribeInterventions(listener); }
     beginAgentAction(input) { this.control.beginAgent(input); }
     finishAgentAction(runId) { this.control.finishAgent(runId); }
     requestHuman(reason, input) { return this.control.requestHuman(reason, input); }
     takeControl(input) { this.control.takeInteractive(input); }
     resumeControl(token) { return this.control.resume(token); }
     stopControl(token) { return this.control.stop(token); }
+    resumeIntervention(credential) {
+        return this.control.resumeIntervention(credential);
+    }
+    cancelIntervention(credential) {
+        return this.control.cancelIntervention(credential);
+    }
     waitForHuman(signal) { return this.control.waitForHuman(signal); }
     emit(event) {
         for (const listener of this.listeners)

package/src/tools/webbrowser/browserStream.ts

@@ -0,0 +1,216 @@
+import { getStreamPort, waitForStreamPort } from './browserDaemon.js';
+import { BrowserControlCoordinator, type BrowserControlState, type BrowserHumanReason } from './browserControl.js';
+import type { HumanInterventionCredential, HumanInterventionEvent } from '../../humanIntervention.js';
+
+export type BrowserMode = 'browse' | 'assist' | 'auto';
+export type PickedBrowserElement = {
+  ref: string;
+  tag: string;
+  role?: string;
+  accessibleName?: string;
+  text?: string;
+  boundingBox?: { x: number; y: number; width: number; height: number };
+  attributes?: Record<string, string>;
+};
+export type MarkedBrowserElement = PickedBrowserElement & { label?: string; color?: string };
+export type BrowserStreamEvent = Record<string, unknown> & { type: string };
+
+export interface BrowserStream {
+  connect(): Promise<void>;
+  disconnect(): void;
+  send(frame: unknown): void;
+  dispose(): void;
+  subscribe(listener: (event: BrowserStreamEvent) => void): () => void;
+  getStatus(): Record<string, unknown>;
+  getPort(): number | null;
+  isConnected(): boolean;
+  setMode(mode: BrowserMode): void;
+  getMode(): BrowserMode;
+  getCurrentUrl(): string;
+  setCurrentUrl(url: string): void;
+  pickElement(x: number, y: number): Promise<PickedBrowserElement | null>;
+  setPicker(picker: (x: number, y: number) => Promise<PickedBrowserElement | null>): void;
+  markElement(element: MarkedBrowserElement): void;
+  clearMarkedElements(): void;
+  /** Remove a single marked element by ref (does not affect other marks). */
+  unmarkElement(ref: string): void;
+  setAgentActing(acting: boolean, action?: string, target?: string): void;
+  /**
+   * 把「这次没找到目标，最像的是这几个」推给可见面板。
+   *
+   * 候选只进对话的话，盯着浏览器的人看到的是 AI 忽然停住；推到面板上他可以一眼看出
+   * AI 卡在哪，并点一下把正确的那个喂回去 —— 人的判断比模型再猜一轮便宜得多。
+   */
+  setAgentCandidates(candidates: Array<{ ref: string; line: string }>, selector?: string): void;
+  /**
+   * 发布一次动作**做完之后**的生效结论（只在结论不是「变了」时调用）。
+   *
+   * 与 `setAgentActing` 分开是必须的：acting 在 `finally` 里被无条件置回 false，
+   * 把结论挂上去等于发完立刻抹掉。结论要活到下一次动作开始或页面切换。
+   */
+  setAgentOutcome(outcome: {
+    action: string;
+    effect: 'unchanged' | 'unknown';
+    selector?: string;
+    maskedLines?: number;
+  }): void;
+  /** C4：发布 AI 指针语义终点给可见面板（宿主用 CSS 过渡平滑移动 + 渲染点击动效）。 */
+  setAgentPointer(pointer: { x: number; y: number; visible: boolean; action?: 'move' | 'click' | 'type' | 'hover' | 'scroll' | 'idle'; elementRef?: string }): void;
+  getControlState(): BrowserControlState;
+  /** 订阅控制权状态变化（立即以当前状态回调一次）；供工具即时感知「用户接管 / 进入 waiting_human」以掐断在跑动作。 */
+  subscribeControl(listener: (state: BrowserControlState) => void): () => void;
+  subscribeInterventions(listener: (event: HumanInterventionEvent) => void): () => void;
+  beginAgentAction(input: { runId: string; conversationKey?: string; action?: string }): void;
+  finishAgentAction(runId: string): void;
+  requestHuman(reason: BrowserHumanReason, input?: { runId?: string; conversationKey?: string; ownerId?: string; summary?: string }): string;
+  takeControl(input?: { runId?: string; conversationKey?: string }): void;
+  resumeControl(token?: string): boolean;
+  stopControl(token?: string): boolean;
+  resumeIntervention(credential: HumanInterventionCredential): boolean;
+  cancelIntervention(credential: HumanInterventionCredential): boolean;
+  waitForHuman(signal?: AbortSignal): Promise<'resumed' | 'stopped'>;
+}
+
+class SessionBrowserStream implements BrowserStream {
+  private socket: WebSocket | null = null;
+  private connecting: Promise<void> | null = null;
+  private listeners = new Set<(event: BrowserStreamEvent) => void>();
+  private port: number | null = null;
+  private mode: BrowserMode = 'browse';
+  private currentUrl = 'about:blank';
+  private status: Record<string, unknown> = { connected: false, screencasting: false };
+  private picker?: (x: number, y: number) => Promise<PickedBrowserElement | null>;
+  private marked: MarkedBrowserElement[] = [];
+  private control: BrowserControlCoordinator;
+
+  constructor(private readonly sessionName: string) {
+    this.control = new BrowserControlCoordinator({ conversationKey: `browser:${sessionName}` });
+    this.control.subscribe((state) => this.emit({ type: 'control_state', state }));
+    this.control.subscribeInterventions((event) => this.emit({
+      type: event.type === 'started' ? 'human_intervention_started' : 'human_intervention_resolved',
+      event,
+    }));
+  }
+
+  async connect(): Promise<void> {
+    if (this.socket?.readyState === WebSocket.OPEN) return;
+    if (this.connecting) return this.connecting;
+    this.connecting = (async () => {
+      this.port = (await getStreamPort(this.sessionName)) ?? (await waitForStreamPort(this.sessionName));
+      await new Promise<void>((resolve, reject) => {
+        const socket = new WebSocket(`ws://127.0.0.1:${this.port}`);
+        const timer = setTimeout(() => {
+          socket.close();
+          reject(new Error('连接浏览器实时画面超时'));
+        }, 8_000);
+        socket.onopen = () => {
+          clearTimeout(timer);
+          this.socket = socket;
+          this.status = { ...this.status, connected: true };
+          this.emit({ type: 'status', ...this.status });
+          resolve();
+        };
+        socket.onerror = () => {
+          clearTimeout(timer);
+          reject(new Error('无法连接浏览器实时画面'));
+        };
+        socket.onclose = () => {
+          if (this.socket === socket) this.socket = null;
+          this.status = { ...this.status, connected: false, screencasting: false };
+          this.emit({ type: 'status', ...this.status });
+        };
+        socket.onmessage = (event) => this.onMessage(event.data);
+      });
+    })().finally(() => { this.connecting = null; });
+    return this.connecting;
+  }
+
+  disconnect(): void { this.socket?.close(); this.socket = null; }
+  dispose(): void { this.disconnect(); this.listeners.clear(); }
+  send(frame: unknown): void {
+    if (this.socket?.readyState === WebSocket.OPEN) this.socket.send(JSON.stringify(frame));
+  }
+  subscribe(listener: (event: BrowserStreamEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  getStatus(): Record<string, unknown> { return this.status; }
+  getPort(): number | null { return this.port; }
+  isConnected(): boolean { return this.socket?.readyState === WebSocket.OPEN; }
+  setMode(mode: BrowserMode): void { this.mode = mode; this.emit({ type: 'mode', mode }); }
+  getMode(): BrowserMode { return this.mode; }
+  getCurrentUrl(): string { return this.currentUrl; }
+  setCurrentUrl(url: string): void { this.currentUrl = url; this.emit({ type: 'url', url }); }
+  setPicker(picker: (x: number, y: number) => Promise<PickedBrowserElement | null>): void { this.picker = picker; }
+  pickElement(x: number, y: number): Promise<PickedBrowserElement | null> {
+    return this.picker ? this.picker(x, y) : Promise.resolve(null);
+  }
+  markElement(element: MarkedBrowserElement): void {
+    this.marked = [...this.marked.filter((item) => item.ref !== element.ref), element];
+    this.emit({ type: 'marked_elements', elements: this.marked });
+  }
+  clearMarkedElements(): void { this.marked = []; this.emit({ type: 'marked_elements', elements: [] }); }
+  unmarkElement(ref: string): void {
+    const next = this.marked.filter((item) => item.ref !== ref);
+    if (next.length !== this.marked.length) {
+      this.marked = next;
+      this.emit({ type: 'marked_elements', elements: this.marked });
+    }
+  }
+  setAgentActing(acting: boolean, action?: string, target?: string): void {
+    this.emit({ type: 'agent_acting', acting, action, target });
+  }
+  setAgentCandidates(candidates: Array<{ ref: string; line: string }>, selector?: string): void {
+    this.emit({ type: 'agent_candidates', candidates, selector });
+  }
+  setAgentOutcome(outcome: {
+    action: string;
+    effect: 'unchanged' | 'unknown';
+    selector?: string;
+    maskedLines?: number;
+  }): void {
+    this.emit({ type: 'agent_outcome', ...outcome });
+  }
+  setAgentPointer(pointer: { x: number; y: number; visible: boolean; action?: 'move' | 'click' | 'type' | 'hover' | 'scroll' | 'idle'; elementRef?: string }): void {
+    // 只发语义终点（目标元素中心 + 动作类型）；平滑移动交给面板 CSS 过渡，内核不做逐帧插值（避免 WS 洪泛 + 双层缓动打架）。
+    this.emit({ type: 'agent_pointer', ...pointer });
+  }
+  getControlState(): BrowserControlState { return this.control.getState(); }
+  subscribeControl(listener: (state: BrowserControlState) => void): () => void { return this.control.subscribe(listener); }
+  subscribeInterventions(listener: (event: HumanInterventionEvent) => void): () => void { return this.control.subscribeInterventions(listener); }
+  beginAgentAction(input: { runId: string; conversationKey?: string; action?: string }): void { this.control.beginAgent(input); }
+  finishAgentAction(runId: string): void { this.control.finishAgent(runId); }
+  requestHuman(reason: BrowserHumanReason, input?: { runId?: string; conversationKey?: string; ownerId?: string; summary?: string }): string { return this.control.requestHuman(reason, input); }
+  takeControl(input?: { runId?: string; conversationKey?: string }): void { this.control.takeInteractive(input); }
+  resumeControl(token?: string): boolean { return this.control.resume(token); }
+  stopControl(token?: string): boolean { return this.control.stop(token); }
+  resumeIntervention(credential: HumanInterventionCredential): boolean {
+    return this.control.resumeIntervention(credential);
+  }
+  cancelIntervention(credential: HumanInterventionCredential): boolean {
+    return this.control.cancelIntervention(credential);
+  }
+  waitForHuman(signal?: AbortSignal): Promise<'resumed' | 'stopped'> { return this.control.waitForHuman(signal); }
+
+  private emit(event: BrowserStreamEvent): void {
+    for (const listener of this.listeners) listener(event);
+  }
+  private onMessage(data: unknown): void {
+    try {
+      const text = typeof data === 'string' ? data : Buffer.from(data as ArrayBuffer).toString('utf8');
+      const event = JSON.parse(text) as BrowserStreamEvent;
+      if (event.type === 'url' && typeof event.url === 'string') this.currentUrl = event.url;
+      if (event.type === 'status') this.status = { ...this.status, ...event };
+      this.emit(event);
+    } catch (error) {
+      this.emit({ type: 'error', message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+}
+
+const streams = new Map<string, SessionBrowserStream>();
+export function getBrowserStream(sessionName = 'minimal-agent'): BrowserStream {
+  let stream = streams.get(sessionName);
+  if (!stream) { stream = new SessionBrowserStream(sessionName); streams.set(sessionName, stream); }
+  return stream;
+}

package/src/tools/webbrowser/browserTabs.js

@@ -0,0 +1,143 @@
+import { browserService } from './browserService.js';
+import { browserRunRegistry, } from './browserRunRegistry.js';
+export function parseTabList(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return (parsed.data?.tabs ?? []).flatMap((tab) => {
+            const id = typeof tab.tabId === 'string' && tab.tabId
+                ? tab.tabId
+                : typeof tab.id === 'string' && tab.id
+                    ? tab.id
+                    : Number.isInteger(tab.index)
+                        ? String(tab.index)
+                        : '';
+            return id ? [{
+                    id,
+                    active: Boolean(tab.active),
+                    ...(typeof tab.url === 'string' ? { url: tab.url } : {}),
+                    ...(typeof tab.title === 'string' ? { title: tab.title } : {}),
+                    ...(typeof tab.type === 'string' ? { type: tab.type } : {}),
+                }] : [];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export class BrowserTabError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BrowserTabError';
+    }
+}
+function parseListedTabs(result) {
+    if (result.code !== 0) {
+        throw new BrowserTabError('browser_unavailable', result.stderr || result.stdout || '无法读取浏览器标签');
+    }
+    const tabs = parseTabList(result.stdout);
+    let reportedCount = 0;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        reportedCount = Array.isArray(parsed.data?.tabs) ? parsed.data.tabs.length : 0;
+    }
+    catch {
+        throw new BrowserTabError('browser_protocol_mismatch', '浏览器标签列表不是有效 JSON');
+    }
+    if (reportedCount > 0 && tabs.length === 0) {
+        throw new BrowserTabError('browser_protocol_mismatch', '浏览器返回了无法识别的标签格式，请更新 Runtime 或 agent-browser');
+    }
+    return tabs;
+}
+export async function listBrowserTabs(input) {
+    const result = await browserService.run({
+        sessionName: input.sessionName,
+        bin: input.bin,
+        args: [...input.globals, 'tab', 'list', '--json'],
+        runner: input.runner,
+        signal: input.signal,
+    });
+    return parseListedTabs(result);
+}
+function assertSwitched(switched) {
+    if (switched.code !== 0) {
+        throw new BrowserTabError('tab_not_found', switched.stderr || switched.stdout || '无法切换到会话浏览器标签');
+    }
+}
+export async function createConversationTab(input, url = 'about:blank') {
+    return browserService.exclusive({
+        sessionName: input.sessionName,
+        bin: input.bin,
+        runner: input.runner,
+        signal: input.signal,
+    }, async (run) => {
+        const before = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+        const beforeIds = new Set(before.map((tab) => tab.id));
+        const created = await run([...input.globals, 'tab', 'new', url]);
+        if (created.code !== 0) {
+            throw new BrowserTabError('tab_bootstrap_failed', created.stderr || created.stdout || '无法创建会话浏览器标签');
+        }
+        const after = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+        const added = after.filter((tab) => !beforeIds.has(tab.id));
+        const tab = added.find((candidate) => candidate.active) ?? added.at(-1);
+        if (!tab) {
+            throw new BrowserTabError('tab_bootstrap_failed', '新标签创建成功，但 Runtime 未返回其标签 ID');
+        }
+        try {
+            browserRunRegistry.claimTab(input.context, tab.id);
+        }
+        catch (error) {
+            throw new BrowserTabError('tab_owned_by_other_conversation', error instanceof Error ? error.message : String(error));
+        }
+        assertSwitched(await run([...input.globals, 'tab', tab.id]));
+        return tab.id;
+    });
+}
+export async function ensureConversationTab(input) {
+    return browserService.exclusive({
+        sessionName: input.sessionName,
+        bin: input.bin,
+        runner: input.runner,
+        signal: input.signal,
+    }, async (run) => {
+        const tabs = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+        let tabId = input.context.activeTabId;
+        if (!tabId || !tabs.some((tab) => tab.id === tabId)) {
+            const claimed = browserRunRegistry.claimedTabs(input.context.conversationKey);
+            tabId = claimed.find((candidate) => tabs.some((tab) => tab.id === candidate));
+        }
+        if (!tabId) {
+            const hasClaimedTabs = browserRunRegistry.claimedTabs(input.context.conversationKey).length > 0;
+            const reusableBlank = !hasClaimedTabs
+                ? tabs.find((tab) => tab.url === 'about:blank' && browserRunRegistry.ownerOf(tab.id) === undefined)
+                : undefined;
+            if (reusableBlank) {
+                tabId = reusableBlank.id;
+            }
+            else {
+                const beforeIds = new Set(tabs.map((tab) => tab.id));
+                const created = await run([...input.globals, 'tab', 'new', 'about:blank']);
+                if (created.code !== 0) {
+                    throw new BrowserTabError('tab_bootstrap_failed', created.stderr || created.stdout || '无法创建会话浏览器标签');
+                }
+                const after = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+                const added = after.filter((tab) => !beforeIds.has(tab.id));
+                tabId = (added.find((candidate) => candidate.active) ?? added.at(-1))?.id;
+                if (!tabId) {
+                    throw new BrowserTabError('tab_bootstrap_failed', '新标签创建成功，但 Runtime 未返回其标签 ID');
+                }
+            }
+        }
+        try {
+            browserRunRegistry.claimTab(input.context, tabId);
+        }
+        catch (error) {
+            throw new BrowserTabError('tab_owned_by_other_conversation', error instanceof Error ? error.message : String(error));
+        }
+        assertSwitched(await run([...input.globals, 'tab', tabId]));
+        return tabId;
+    });
+}
+/** Compatibility alias for callers compiled against the previous helper name. */
+export const claimConversationTab = ensureConversationTab;

package/src/tools/webbrowser/browserTabs.ts

@@ -0,0 +1,210 @@
+import type { AgentBrowserRun, AgentBrowserRunner } from './browser.js';
+import { browserService } from './browserService.js';
+import {
+  browserRunRegistry,
+  type BrowserRunContext,
+} from './browserRunRegistry.js';
+
+export interface BrowserTabRecord {
+  id: string;
+  active: boolean;
+  url?: string;
+  title?: string;
+  type?: string;
+}
+
+export function parseTabList(text: string): BrowserTabRecord[] {
+  try {
+    const parsed = JSON.parse(text) as {
+      data?: {
+        tabs?: Array<{
+          tabId?: string;
+          id?: string;
+          index?: number;
+          active?: boolean;
+          url?: string;
+          title?: string;
+          type?: string;
+        }>;
+      };
+    };
+    return (parsed.data?.tabs ?? []).flatMap((tab) => {
+      const id = typeof tab.tabId === 'string' && tab.tabId
+        ? tab.tabId
+        : typeof tab.id === 'string' && tab.id
+          ? tab.id
+          : Number.isInteger(tab.index)
+            ? String(tab.index)
+            : '';
+      return id ? [{
+        id,
+        active: Boolean(tab.active),
+        ...(typeof tab.url === 'string' ? { url: tab.url } : {}),
+        ...(typeof tab.title === 'string' ? { title: tab.title } : {}),
+        ...(typeof tab.type === 'string' ? { type: tab.type } : {}),
+      }] : [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+export class BrowserTabError extends Error {
+  constructor(
+    public readonly code:
+      | 'browser_unavailable'
+      | 'tab_bootstrap_failed'
+      | 'tab_not_found'
+      | 'tab_owned_by_other_conversation'
+      | 'browser_protocol_mismatch',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'BrowserTabError';
+  }
+}
+
+type BrowserTabInput = {
+  context: BrowserRunContext;
+  sessionName: string;
+  bin: string;
+  globals: string[];
+  runner: AgentBrowserRunner;
+  signal?: AbortSignal;
+};
+
+function parseListedTabs(result: AgentBrowserRun): BrowserTabRecord[] {
+  if (result.code !== 0) {
+    throw new BrowserTabError(
+      'browser_unavailable',
+      result.stderr || result.stdout || '无法读取浏览器标签',
+    );
+  }
+  const tabs = parseTabList(result.stdout);
+  let reportedCount = 0;
+  try {
+    const parsed = JSON.parse(result.stdout) as { data?: { tabs?: unknown[] } };
+    reportedCount = Array.isArray(parsed.data?.tabs) ? parsed.data.tabs.length : 0;
+  } catch {
+    throw new BrowserTabError('browser_protocol_mismatch', '浏览器标签列表不是有效 JSON');
+  }
+  if (reportedCount > 0 && tabs.length === 0) {
+    throw new BrowserTabError(
+      'browser_protocol_mismatch',
+      '浏览器返回了无法识别的标签格式，请更新 Runtime 或 agent-browser',
+    );
+  }
+  return tabs;
+}
+
+export async function listBrowserTabs(input: Omit<BrowserTabInput, 'context'>): Promise<BrowserTabRecord[]> {
+  const result = await browserService.run({
+    sessionName: input.sessionName,
+    bin: input.bin,
+    args: [...input.globals, 'tab', 'list', '--json'],
+    runner: input.runner,
+    signal: input.signal,
+  });
+  return parseListedTabs(result);
+}
+
+function assertSwitched(switched: AgentBrowserRun): void {
+  if (switched.code !== 0) {
+    throw new BrowserTabError(
+      'tab_not_found',
+      switched.stderr || switched.stdout || '无法切换到会话浏览器标签',
+    );
+  }
+}
+
+export async function createConversationTab(
+  input: BrowserTabInput,
+  url = 'about:blank',
+): Promise<string> {
+  return browserService.exclusive({
+    sessionName: input.sessionName,
+    bin: input.bin,
+    runner: input.runner,
+    signal: input.signal,
+  }, async (run) => {
+    const before = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+    const beforeIds = new Set(before.map((tab) => tab.id));
+    const created = await run([...input.globals, 'tab', 'new', url]);
+    if (created.code !== 0) {
+      throw new BrowserTabError(
+        'tab_bootstrap_failed',
+        created.stderr || created.stdout || '无法创建会话浏览器标签',
+      );
+    }
+    const after = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+    const added = after.filter((tab) => !beforeIds.has(tab.id));
+    const tab = added.find((candidate) => candidate.active) ?? added.at(-1);
+    if (!tab) {
+      throw new BrowserTabError('tab_bootstrap_failed', '新标签创建成功，但 Runtime 未返回其标签 ID');
+    }
+    try {
+      browserRunRegistry.claimTab(input.context, tab.id);
+    } catch (error) {
+      throw new BrowserTabError(
+        'tab_owned_by_other_conversation',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    assertSwitched(await run([...input.globals, 'tab', tab.id]));
+    return tab.id;
+  });
+}
+
+export async function ensureConversationTab(input: BrowserTabInput): Promise<string> {
+  return browserService.exclusive({
+    sessionName: input.sessionName,
+    bin: input.bin,
+    runner: input.runner,
+    signal: input.signal,
+  }, async (run) => {
+    const tabs = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+    let tabId = input.context.activeTabId;
+    if (!tabId || !tabs.some((tab) => tab.id === tabId)) {
+      const claimed = browserRunRegistry.claimedTabs(input.context.conversationKey);
+      tabId = claimed.find((candidate) => tabs.some((tab) => tab.id === candidate));
+    }
+    if (!tabId) {
+      const hasClaimedTabs = browserRunRegistry.claimedTabs(input.context.conversationKey).length > 0;
+      const reusableBlank = !hasClaimedTabs
+        ? tabs.find((tab) => tab.url === 'about:blank' && browserRunRegistry.ownerOf(tab.id) === undefined)
+        : undefined;
+      if (reusableBlank) {
+        tabId = reusableBlank.id;
+      } else {
+        const beforeIds = new Set(tabs.map((tab) => tab.id));
+        const created = await run([...input.globals, 'tab', 'new', 'about:blank']);
+        if (created.code !== 0) {
+          throw new BrowserTabError(
+            'tab_bootstrap_failed',
+            created.stderr || created.stdout || '无法创建会话浏览器标签',
+          );
+        }
+        const after = parseListedTabs(await run([...input.globals, 'tab', 'list', '--json']));
+        const added = after.filter((tab) => !beforeIds.has(tab.id));
+        tabId = (added.find((candidate) => candidate.active) ?? added.at(-1))?.id;
+        if (!tabId) {
+          throw new BrowserTabError('tab_bootstrap_failed', '新标签创建成功，但 Runtime 未返回其标签 ID');
+        }
+      }
+    }
+
+    try {
+      browserRunRegistry.claimTab(input.context, tabId);
+    } catch (error) {
+      throw new BrowserTabError(
+        'tab_owned_by_other_conversation',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    assertSwitched(await run([...input.globals, 'tab', tabId]));
+    return tabId;
+  });
+}
+
+/** Compatibility alias for callers compiled against the previous helper name. */
+export const claimConversationTab = ensureConversationTab;