浏览器会话

agent 驱动的是目标计算机上的真实浏览器。在已登记机器上，daemon 经由 Chrome DevTools Protocol（CDP）启动并拥有自己的浏览器实例；在你自己的机器上，浏览器扩展无需 daemon 启动任何东西即可提供页面访问。本页讲的是 daemon 启动的会话：标签页如何管理、会话如何隔离，以及多个任务共享一台计算机时云端 agent 运行时如何调度它们。

会话与实例

daemon 维护着一个浏览器会话资源池，以会话 id 为键。每个会话都是一个完全独立的浏览器实例——自己的进程、自己的 profile 目录、自己的 DevTools 端口。实例之间不共享任何东西。

多数浏览器命令接受可选的 sessionId。只有一个会话在跑时，命令自动指向它。有多个会话在跑时，调用必须指名会话——省略 id 得到的是一个会列出当前存活会话的错误，而不是一次猜测。

打开标签页时传 newInstance: true 会启动一个全新的独立实例（全新进程、profile 与端口），而不是复用池中实例。tabId 永远无法引用由同一次调用刚创建的那个实例里的标签页。

标签页管理

四个标签页操作，各自以会话为作用域：

快照与导航也接受 tabId；省略时使用该会话当前激活的标签页。channel 字段对 daemon 启动的会话恒为 cdp，以此与扩展通道的页面区分。

句柄规则

• sessionId 标识资源池中的一个会话（其页面 id）。省略时解析为当前跟踪的会话；不存在则启动一个新会话。
• tabId 是一个会话内的 CDP target id。激活或关闭之前，daemon 会核实该标签页确实属于那个会话——来自另一个会话（或另一台计算机）的标签页句柄无法解析。
• browser.close 关停一个池中实例并删除其 profile 目录。它从不触碰扩展通道或你自己的浏览器。
• 所有标签页操作只作用于 daemon 启动的会话。在一台只有你自己的浏览器的机器上（扩展通道），标签页管理会显式失败，而不是动你的浏览器。

会话生命周期

• 空闲回收——空闲超过 10 分钟的会话（以及进程已死的会话）由 daemon 的 reaper 回收。超时是显式常量；测试与沙箱可用 MAGICFROG_BROWSER_IDLE_TIMEOUT_MS 覆盖。
• 显式关闭——browser.close 立即拆除一个会话并移除其 profile 目录。
• 不留孤儿——daemon 等待端口之前，每次启动都会先记录进一份持久 manifest（~/.magicfrog/browser-sessions.json）。daemon 重启时会清扫此前运行留下的残余，只杀能在 manifest 中核实的进程——绝不凭 pid 猜测。

在没有 GUI 会话的地方（例如已登记服务器），浏览器以 headless 运行，浏览器方法照常可用。如果计算机根本没有声明浏览器能力，操作会以显式能力错误拒绝——绝不静默跳过。

云端 agent 调度

多个 agent 任务共享一台计算机时，一个会话分配器坐在任务与会话资源池之间：

• 按任务绑定——每个任务有自己的会话。复用别的任务的会话需要显式策略；任务尝试在它未绑定的计算机上获取会话，会以类型化错误失败。会话、句柄与审计记录始终可归因到各自的任务。
• 并发上限——每台计算机有显式上限：4 个并发浏览器会话。到达上限时，后到的任务要么按 FIFO 排队（默认；30 秒预算内没有空位释放，则以超时错误失败），要么按请求的策略被显式拒绝。排队的任务绝不静默抢占正在运行的任务。
• 终态回收——任务到达终态（完成、失败或取消）时，其会话被回收。运行时没能关闭的会话记为泄漏，并出现在分配器的统计里，泄漏因此可观测，而非无声。
• 审计——分配与回收事件都会记录，每条都写明所涉任务与计算机。

扩展通道

在用你自己的浏览器的机器上，MagicFrog 浏览器扩展提供该浏览器内页面的导航与结构化 DOM 快照——没有 daemon 启动的浏览器，没有调试端口。扩展通道不暴露标签页管理，daemon 的标签页操作也从不作用于它；它与上述 CDP 会话是两个不同的面。标签页响应中的 channel 字段告诉你应答的是哪个面——daemon 启动的会话为 cdp。

关于工具调用最初如何到达某台指定计算机，见 Computer ID 路由；关于计算机本身的创建与登记，见云电脑。