@roll-agent/browser-use-agent 0.14.0 → 0.16.0

package/dist/native-reload.d.ts

@@ -0,0 +1,30 @@
+export type NativeReloadController = {
+    evaluateJson<T = unknown>(expression: string): Promise<T>;
+    reload(options?: {
+        readonly url?: string;
+        readonly ignoreCache?: boolean;
+        readonly timeoutMs?: number;
+    }): Promise<void>;
+};
+export type ReloadNativePageOptions = {
+    readonly url: string;
+    readonly ignoreCache?: boolean;
+    readonly timeoutMs?: number;
+    readonly pollMs?: number;
+    readonly now?: () => number;
+    readonly delay?: (ms: number) => Promise<void>;
+    readonly createToken?: () => string;
+    readonly onReloadSent?: () => void;
+};
+/**
+ * Reloads the current native page via CDP `Page.reload` and waits until the
+ * document has actually been swapped.
+ *
+ * A reload keeps the same URL, so the navigate ready-poll (which anchors on a
+ * URL change) would falsely report readiness while the stale document is still
+ * `readyState === "complete"`. Instead we tag the live document with a window
+ * sentinel, trigger the reload, and only return once that sentinel is gone
+ * (window globals are wiped when the document is replaced) and the fresh
+ * document has reached an interactive/complete ready state.
+ */
+export declare function reloadNativePageAndWaitForSwap(controller: NativeReloadController, options: ReloadNativePageOptions): Promise<void>;

package/dist/pages/zhipin/native-page.d.ts

@@ -9,6 +9,22 @@ export type ZhipinNativePagePortOptions = {
     readonly target: BrowserInspectablePage;
     readonly controller: NativeCdpController;
 };
+export type ZhipinNativeReloadOptions = {
+    readonly url: string;
+    readonly ignoreCache?: boolean;
+    readonly onReloadSent?: () => void;
+};
+export declare const ZHIPIN_CHAT_RELOAD_SKIPPED_REASONS: readonly ["not_chat_page"];
+export type ZhipinChatReloadSkippedReason = (typeof ZHIPIN_CHAT_RELOAD_SKIPPED_REASONS)[number];
+export type ZhipinChatReloadTarget = {
+    readonly ok: true;
+    readonly url: string;
+} | {
+    readonly ok: false;
+    readonly url: string;
+    readonly skippedReason: ZhipinChatReloadSkippedReason;
+    readonly error: string;
+};
 export type ReadNativeChatCandidatesOptions = {
     readonly targetCount?: number;
     readonly autoScroll?: boolean;
@@ -176,6 +192,8 @@ export declare class ZhipinNativePagePort {
     waitForSelector(selector: string, timeoutMs?: number): Promise<boolean>;
     evaluateJson<T = unknown>(expression: string): Promise<T>;
     bringToFront(): Promise<void>;
+    inspectChatReloadTarget(): Promise<ZhipinChatReloadTarget>;
+    reload(options: ZhipinNativeReloadOptions): Promise<void>;
     isChatSurfaceOpen(): Promise<boolean>;
     waitForChatSurface(timeoutMs?: number): Promise<boolean>;
     isRecommendSurfaceOpen(): Promise<boolean>;

package/dist/runtime-config.d.ts

@@ -13,6 +13,7 @@ export declare const BrowserInstanceConfigSchema: z.ZodEffects<z.ZodObject<{
     sessionsDir: z.ZodOptional<z.ZodString>;
     args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     profileName: z.ZodOptional<z.ZodString>;
+    profileColor: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     windowBounds: z.ZodOptional<z.ZodObject<{
         x: z.ZodOptional<z.ZodNumber>;
         y: z.ZodOptional<z.ZodNumber>;
@@ -37,6 +38,7 @@ export declare const BrowserInstanceConfigSchema: z.ZodEffects<z.ZodObject<{
     userDataDir: string;
     headless?: boolean | undefined;
     profileName?: string | undefined;
+    profileColor?: string | undefined;
     cdpUrl?: string | undefined;
     cdpPort?: number | undefined;
     executablePath?: string | undefined;
@@ -55,6 +57,7 @@ export declare const BrowserInstanceConfigSchema: z.ZodEffects<z.ZodObject<{
     mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
     headless?: boolean | undefined;
     profileName?: string | undefined;
+    profileColor?: string | undefined;
     cdpUrl?: string | undefined;
     cdpHost?: string | undefined;
     cdpPort?: number | undefined;
@@ -77,6 +80,7 @@ export declare const BrowserInstanceConfigSchema: z.ZodEffects<z.ZodObject<{
     userDataDir: string;
     headless?: boolean | undefined;
     profileName?: string | undefined;
+    profileColor?: string | undefined;
     cdpUrl?: string | undefined;
     cdpPort?: number | undefined;
     executablePath?: string | undefined;
@@ -95,6 +99,7 @@ export declare const BrowserInstanceConfigSchema: z.ZodEffects<z.ZodObject<{
     mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
     headless?: boolean | undefined;
     profileName?: string | undefined;
+    profileColor?: string | undefined;
     cdpUrl?: string | undefined;
     cdpHost?: string | undefined;
     cdpPort?: number | undefined;
@@ -126,6 +131,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         sessionsDir: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         profileName: z.ZodOptional<z.ZodString>;
+        profileColor: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         windowBounds: z.ZodOptional<z.ZodObject<{
             x: z.ZodOptional<z.ZodNumber>;
             y: z.ZodOptional<z.ZodNumber>;
@@ -150,6 +156,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         userDataDir: string;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpPort?: number | undefined;
         executablePath?: string | undefined;
@@ -168,6 +175,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpHost?: string | undefined;
         cdpPort?: number | undefined;
@@ -190,6 +198,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         userDataDir: string;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpPort?: number | undefined;
         executablePath?: string | undefined;
@@ -208,6 +217,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpHost?: string | undefined;
         cdpPort?: number | undefined;
@@ -232,6 +242,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         userDataDir: string;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpPort?: number | undefined;
         executablePath?: string | undefined;
@@ -253,6 +264,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpHost?: string | undefined;
         cdpPort?: number | undefined;
@@ -278,6 +290,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         userDataDir: string;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpPort?: number | undefined;
         executablePath?: string | undefined;
@@ -299,6 +312,7 @@ export declare const BrowserInstancesConfigSchema: z.ZodEffects<z.ZodObject<{
         mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
         headless?: boolean | undefined;
         profileName?: string | undefined;
+        profileColor?: string | undefined;
         cdpUrl?: string | undefined;
         cdpHost?: string | undefined;
         cdpPort?: number | undefined;

package/dist/tools/browser-reload-active-tab.d.ts

@@ -0,0 +1,28 @@
+import { getContextManager, getRuntime } from "../runtime-holder.ts";
+import { toNativePageInfo } from "../page-info.ts";
+import { reloadNativePageAndWaitForSwap } from "../native-reload.ts";
+type ReloadActiveTabDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly getRuntime: typeof getRuntime;
+    readonly toNativePageInfo: typeof toNativePageInfo;
+    readonly reloadNativePageAndWaitForSwap: typeof reloadNativePageAndWaitForSwap;
+};
+export declare function setReloadActiveTabDepsForTests(override: Partial<ReloadActiveTabDeps> | undefined): void;
+export declare const browserReloadActiveTab: import("@roll-agent/sdk").ToolDefinition<{
+    ignoreCache?: boolean | undefined;
+    browserActionApproval?: {
+        id: string;
+    } | undefined;
+}, {
+    success: boolean;
+    reloaded: boolean;
+    page: {
+        pageId: string;
+        url: string;
+        title: string;
+        boundPlatform: "zhipin" | "yupao" | null;
+        detectedPlatform: "zhipin" | "yupao" | null;
+        isSelectedForPlatform: boolean;
+    };
+}>;
+export {};

package/dist/tools/browser-stop.d.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { type BrowserInstanceStopResult } from "../browser-instance-pool.ts";
+declare const BrowserStopInputSchema: z.ZodEffects<z.ZodObject<{
+    browserInstance: z.ZodOptional<z.ZodString>;
+    browserInstances: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    all: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    browserInstance?: string | undefined;
+    browserInstances?: string[] | undefined;
+    all?: boolean | undefined;
+}, {
+    browserInstance?: string | undefined;
+    browserInstances?: string[] | undefined;
+    all?: boolean | undefined;
+}>, {
+    browserInstance?: string | undefined;
+    browserInstances?: string[] | undefined;
+    all?: boolean | undefined;
+}, {
+    browserInstance?: string | undefined;
+    browserInstances?: string[] | undefined;
+    all?: boolean | undefined;
+}>;
+declare const BrowserStopOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    stopped: z.ZodNumber;
+    results: z.ZodArray<z.ZodObject<{
+        browserInstance: z.ZodString;
+        status: z.ZodEnum<["stopped", "not_running", "not_found", "failed"]>;
+        mode: z.ZodOptional<z.ZodEnum<["managed-cdp", "remote-cdp", "existing-session"]>>;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "not_found" | "failed" | "stopped" | "not_running";
+        browserInstance: string;
+        message?: string | undefined;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+    }, {
+        status: "not_found" | "failed" | "stopped" | "not_running";
+        browserInstance: string;
+        message?: string | undefined;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    stopped: number;
+    ok: boolean;
+    results: {
+        status: "not_found" | "failed" | "stopped" | "not_running";
+        browserInstance: string;
+        message?: string | undefined;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+    }[];
+}, {
+    stopped: number;
+    ok: boolean;
+    results: {
+        status: "not_found" | "failed" | "stopped" | "not_running";
+        browserInstance: string;
+        message?: string | undefined;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+    }[];
+}>;
+type BrowserStopInput = z.infer<typeof BrowserStopInputSchema>;
+type BrowserStopOutput = z.infer<typeof BrowserStopOutputSchema>;
+export declare const browserStop: import("@roll-agent/sdk").ToolDefinition<{
+    browserInstance?: string | undefined;
+    browserInstances?: string[] | undefined;
+    all?: boolean | undefined;
+}, {
+    stopped: number;
+    ok: boolean;
+    results: {
+        status: "not_found" | "failed" | "stopped" | "not_running";
+        browserInstance: string;
+        message?: string | undefined;
+        mode?: "managed-cdp" | "remote-cdp" | "existing-session" | undefined;
+    }[];
+}>;
+export declare function resolveBrowserStopTargets(input: BrowserStopInput, availableInstances: readonly string[]): readonly string[];
+export declare function createBrowserStopOutput(results: readonly BrowserInstanceStopResult[]): BrowserStopOutput;
+export {};

package/dist/tools/zhipin-open-chat-page.d.ts

@@ -1,18 +1,25 @@
 import { NativeVisualActivitySession } from "../native-visual-activity-session.ts";
 import { openZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
-import type { ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
-import { getContextManager } from "../runtime-holder.ts";
+import { type ZhipinNativePagePort } from "../pages/zhipin/native-page.ts";
+import { getContextManager, getRuntime } from "../runtime-holder.ts";
 type NativeVisualActivitySessionLike = Pick<NativeVisualActivitySession, "begin" | "highlightSelector" | "previewMouseMotion" | "succeed" | "fail">;
 type ZhipinOpenChatPageDeps = {
     readonly getContextManager: typeof getContextManager;
+    readonly getRuntime: typeof getRuntime;
     readonly openNativePagePort: typeof openZhipinNativePagePort;
     readonly createNativeVisualActivitySession: (page: ZhipinNativePagePort) => NativeVisualActivitySessionLike;
 };
 export declare function setZhipinOpenChatPageDepsForTests(override: Partial<ZhipinOpenChatPageDeps> | undefined): void;
-export declare const zhipinOpenChatPage: import("@roll-agent/sdk").ToolDefinition<{}, {
+export declare const zhipinOpenChatPage: import("@roll-agent/sdk").ToolDefinition<{
+    browserActionApproval?: {
+        id: string;
+    } | undefined;
+    forceReload?: boolean | undefined;
+}, {
     success: boolean;
     alreadyOnChat: boolean;
     usedSidebarClick: boolean;
+    usedReload: boolean;
     chatReady: boolean;
     error?: string | undefined;
     page?: {
@@ -23,5 +30,6 @@ export declare const zhipinOpenChatPage: import("@roll-agent/sdk").ToolDefinitio
         detectedPlatform: "zhipin" | "yupao" | null;
         isSelectedForPlatform: boolean;
     } | undefined;
+    reloadSkippedReason?: "not_chat_page" | undefined;
 }>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/browser-use-agent",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
     "zod": "^3.25.76",
     "@roll-agent/reply-authority-client": "0.1.2",
     "@roll-agent/sdk": "0.2.0",
-    "@roll-agent/browser": "0.7.0"
+    "@roll-agent/browser": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/references/env.yaml

@@ -31,9 +31,12 @@ optional:
     purpose: browser-use 工具级业务策略 JSON；可按 exact tool name 配置 log、deny、confirm
     default: '{"approvalTtlMs":300000,"tools":{}}'
     example: '{"approvalTtlMs":300000,"tools":{"zhipin_send_prepared_reply":{"policy":"confirm"}}}'
+  - name: BROWSER_PROFILE_COLOR
+    purpose: legacy 单浏览器运行时的 Chrome profile 颜色，格式为 `#RRGGBB`；配置了 `browser.instances` 时由每个实例的 profileColor 接管，此 env 会被忽略
+    example: "#2563EB"
   - name: BROWSER_INSTANCES_JSON
-    purpose: Roll core 注入的多浏览器实例声明 JSON；由 `browser.instances` 派生，包含每个实例的 profile、CDP 端口、session 目录、可选 profileName/windowBounds 和招聘事件归因 ID；orchestrator 不应手工拼接，手工配置时必须保持 cdpPort/userDataDir 唯一
-    example: '{"defaultInstance":"boss-a","instances":{"boss-a":{"platform":"zhipin","mode":"managed-cdp","cdpPort":9222,"userDataDir":"/tmp/roll-browser/profiles/boss-a","profileName":"boss-a","windowBounds":{"x":0,"y":0,"width":680,"height":1000},"trackingAgentId":"zhipin-boss-a"}}}'
+    purpose: Roll core 注入的多浏览器实例声明 JSON；由 `browser.instances` 派生，包含每个实例的 profile、CDP 端口、session 目录、可选 profileName/profileColor/windowBounds 和招聘事件归因 ID；orchestrator 不应手工拼接，手工配置时必须保持 cdpPort/userDataDir 唯一
+    example: '{"defaultInstance":"boss-a","instances":{"boss-a":{"platform":"zhipin","mode":"managed-cdp","cdpPort":9222,"userDataDir":"/tmp/roll-browser/profiles/boss-a","profileName":"boss-a","profileColor":"#2563EB","windowBounds":{"x":0,"y":0,"width":680,"height":1000},"trackingAgentId":"zhipin-boss-a"}}}'
   - name: BROWSER_VISUAL_CURSOR
     purpose: 在可见浏览器页面内显示 browser-use 的页内虚拟指针和点击波纹；默认开启，设为 `"false"` 可关闭
     default: "true"

package/references/zhipin-workflows.md

@@ -68,7 +68,7 @@
 `jobRef` 规则：
 
 - `jobRef` 格式如 `@j1`，只来自 `zhipin_list_recommend_jobs()` 输出。
-- `jobRef` 只对最近一次岗位下拉快照有效；筛选、搜索、刷新或页面重开后必须重新读取。
+- `jobRef` 只对最近一次岗位下拉快照有效；筛选、搜索、刷新、页面 reload 或页面重开后必须重新读取。
 - orchestrator 不要自行构造 `jobRef`。
 - `jobRef` 不是安全边界，只是降低编排认知负担；真实 DOM 点击仍由工具解析到 `value` / `index` 后执行。
 - 默认不要传 `forceClick:true`；只有需要重新点击已选中的岗位项时才使用。
@@ -191,7 +191,7 @@ recommend-list  -> 推荐牛人列表，默认向下滚动，去重主键 candid
 
 1. 上层 orchestrator 优先把 `candidateRef` 传给 `zhipin_say_hello({ candidateRefs })` 或 `zhipin_open_resume({ candidateRef })`。
 2. `indices` / `index` 只作为当前 DOM 快照兜底。
-3. 筛选、滚动加载、搜索、刷新或页面重开后必须重新调用 `zhipin_get_candidate_list`，不要复用旧 `candidateRef`。
+3. 筛选、滚动加载、搜索、刷新、页面 reload 或页面重开后必须重新调用 `zhipin_get_candidate_list`，不要复用旧 `candidateRef`。
 4. 不要由 orchestrator 自己构造 `@c1`；只使用 tool 输出中的 `candidateRef`。
 5. 聊天消息列表没有 `candidateRef`；聊天回复链路继续使用 `conversationId` / `candidateId`。
 6. 调 `zhipin_say_hello` 前先过滤 `buttonText:"打招呼"`；`buttonText` 为空通常表示已打过招呼，不应重复点击。
@@ -202,3 +202,16 @@ recommend-list  -> 推荐牛人列表，默认向下滚动，去重主键 candid
 - 如果 `candidateRef` 对应的 `candidateId` / `name` 与当前 DOM 不一致，工具会返回 `success:false` 并提示“候选人引用已过期”。
 - 收到过期提示后，重新执行推荐候选人链路的第 3 步，再提交新的 `candidateRefs`。
 - 同一快照内可以一次提交多个 `candidateRefs` 连续打招呼；如果 BOSS 在点击后重排列表，工具会拒绝过期 ref，orchestrator 应刷新列表后只重试剩余目标。
+
+## 长跑 tab 的 reload recovery
+
+Chrome 全天不关、同一沟通 tab 连续跑多批任务时，前端 SPA 状态会在同一 renderer 内累积，常见症状是 `.geek-item.selected` 选中态丢失、依赖「当前选中聊天」的工具（如 `zhipin_exchange_wechat`）失败，且失败率随运行时长上升。
+
+recovery 优先级与边界：
+
+1. `zhipin_open_chat_page({ forceReload: true })`：只对当前沟通页执行 native CDP `Page.reload`，等价手动 F5，清空当前 document 的 DOM 与页面内 SPA 状态，保留 Chrome 窗口与 profile 登录态；reload 后返回 `usedReload: true` 与 `chatReady`。如果实时页面已不是沟通页，会跳过 reload 并返回 `reloadSkippedReason`。
+2. 通用 `browser_reload_active_tab`：对当前 tracked native page 做同样的 reload，用于非沟通页或不需要确认聊天就绪的场景。
+3. 普通 `zhipin_open_chat_page()`（不带 forceReload）在已处于沟通页时只返回 `alreadyOnChat: true`，**不会**卸载 document，无法清状态。
+4. `roll browser stop` 才能回收 renderer 进程内存，但会关闭浏览器窗口；reload 只清 document 级状态，**不保证** renderer 把内存归还 OS。
+
+reload / 页面重开后，所有 `@eN` / `candidateRef` / `jobRef` 一律失效，必须重新 `browser_snapshot` 或重新读列表后再继续。