@roll-agent/browser-use-agent 0.7.1 → 0.7.3

package/dist/pages/zhipin/recommend-filter.d.ts

@@ -0,0 +1,47 @@
+import type { Page } from "@roll-agent/browser";
+export declare const ZHIPIN_RECOMMEND_GENDER_VALUES: readonly ["不限", "男", "女"];
+export type ZhipinRecommendGender = (typeof ZHIPIN_RECOMMEND_GENDER_VALUES)[number];
+export declare const ZHIPIN_RECOMMEND_ACTIVITY_VALUES: readonly ["不限", "刚刚活跃", "今日活跃", "3日内活跃", "本周活跃", "本月活跃"];
+export type ZhipinRecommendActivity = (typeof ZHIPIN_RECOMMEND_ACTIVITY_VALUES)[number];
+export declare const ZHIPIN_RECOMMEND_FILTER_STATUS_VALUES: readonly ["applied", "recommend_not_ready", "filter_not_found", "requires_vip", "age_not_applied", "submit_failed", "error"];
+export type ZhipinRecommendFilterStatus = (typeof ZHIPIN_RECOMMEND_FILTER_STATUS_VALUES)[number];
+export type RecommendTarget = Page | NonNullable<ReturnType<Page["frame"]>>;
+type PageLocator = ReturnType<Page["locator"]>;
+export type ZhipinRecommendFilterRequest = {
+    readonly ageMin?: number;
+    readonly ageMax?: number;
+    readonly gender: ZhipinRecommendGender;
+    readonly activity: ZhipinRecommendActivity;
+};
+export type ZhipinRecommendFilterApplied = {
+    readonly ageMin?: number;
+    readonly ageMax?: number;
+    readonly gender: string;
+    readonly activity: string;
+};
+export type ZhipinRecommendFilterApplyResult = {
+    readonly status: ZhipinRecommendFilterStatus;
+    readonly requested: ZhipinRecommendFilterRequest;
+    readonly applied?: ZhipinRecommendFilterApplied;
+    readonly filterButtonText?: string;
+    readonly error?: string;
+};
+export type RecommendFilterVisualFeedback = {
+    readonly moveToLocator: (page: Page, locator: PageLocator, options?: {
+        readonly durationMs?: number;
+        readonly settleMs?: number;
+        readonly target?: RecommendTarget;
+    }) => Promise<boolean>;
+    readonly showClickOnLocator: (page: Page, locator: PageLocator, options?: {
+        readonly pulseDurationMs?: number;
+        readonly target?: RecommendTarget;
+    }) => Promise<boolean>;
+};
+type RecommendAgeState = {
+    readonly ageMin?: number;
+    readonly ageMax?: number;
+};
+export declare function parseRecommendAgeStateText(text: string): RecommendAgeState;
+export declare function waitForRecommendFilterSurface(target: RecommendTarget, timeout?: number): Promise<boolean>;
+export declare function applyRecommendFilter(page: Page, target: RecommendTarget, requested: ZhipinRecommendFilterRequest, visualFeedback?: RecommendFilterVisualFeedback): Promise<ZhipinRecommendFilterApplyResult>;
+export {};

package/dist/pages/zhipin/selectors.d.ts

@@ -87,9 +87,16 @@ export declare const ZHIPIN_SELECTORS: {
         readonly primary: ".nav-item.nav-logout .user-name";
         readonly fallbacks: readonly string[];
     };
+    readonly nav: {
+        readonly sidebar: ".side-wrap.side-wrap-v2";
+        readonly chatLink: ".side-wrap.side-wrap-v2 a[href*=\"/web/chat/index\"]";
+        readonly recommendLink: ".side-wrap.side-wrap-v2 a[href*=\"/web/geek/recommend\"]";
+    };
     readonly recommend: {
         readonly iframe: "#recommendFrame";
         readonly resumeIframe: "iframe[src*=\"c-resume\"]";
+        readonly filterButton: ".recommend-filter .filter-label, .filter-label-wrap .filter-label, .filter-label";
+        readonly filterPanel: ".filter-panel";
         readonly candidateItem: "[data-geek], .geek-item";
         readonly candidateName: ".name";
         readonly candidateBaseInfo: ".base-info";

package/dist/pages/zhipin/sidebar-navigation.d.ts

@@ -0,0 +1,14 @@
+import type { Page } from "@roll-agent/browser";
+declare const ZHIPIN_SIDEBAR_SECTION_LABELS: {
+    readonly chat: "沟通";
+    readonly recommend: "推荐牛人";
+};
+export type ZhipinSidebarSection = keyof typeof ZHIPIN_SIDEBAR_SECTION_LABELS;
+type Locator = ReturnType<Page["locator"]>;
+export declare function getZhipinSidebarSectionLabel(section: ZhipinSidebarSection): string;
+export declare function findZhipinSidebarSectionLink(page: Page, section: ZhipinSidebarSection): Promise<Locator | null>;
+export declare function isZhipinRecommendSurfaceOpen(page: Page): boolean;
+export declare function isZhipinChatSurfaceOpen(page: Page): Promise<boolean>;
+export declare function waitForZhipinRecommendSurface(page: Page, timeout?: number, pollInterval?: number): Promise<boolean>;
+export declare function waitForZhipinChatSurface(page: Page, timeout?: number, pollInterval?: number): Promise<boolean>;
+export {};

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

@@ -10,6 +10,8 @@ export declare const browserStatus: import("@roll-agent/sdk").ToolDefinition<{},
         currentUrl?: string | undefined;
     }[];
     replyAuthorityKeysLoaded: boolean;
+    visualCursorEnabled: boolean;
+    visualActivityEnabled: boolean;
     effectiveEnvSources: Record<string, {
         present: boolean;
         fingerprint?: string | undefined;

package/dist/tools/navigate-active-tab.d.ts

@@ -1,3 +1,15 @@
+import { findTrackedPlatformPage } from "../pages/platform-page.ts";
+import { getContextManager } from "../runtime-holder.ts";
+import { detectPlatformFromUrl, matchesPlatformHost } from "../platforms.ts";
+import { toAttachedPageInfo } from "../page-info.ts";
+type NavigateActiveTabDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly detectPlatformFromUrl: typeof detectPlatformFromUrl;
+    readonly matchesPlatformHost: typeof matchesPlatformHost;
+    readonly findTrackedPlatformPage: typeof findTrackedPlatformPage;
+    readonly toAttachedPageInfo: typeof toAttachedPageInfo;
+};
+export declare function setNavigateActiveTabDepsForTests(override: Partial<NavigateActiveTabDeps> | undefined): void;
 export declare const navigateActiveTab: import("@roll-agent/sdk").ToolDefinition<{
     url: string;
 }, {
@@ -11,3 +23,4 @@ export declare const navigateActiveTab: import("@roll-agent/sdk").ToolDefinition
         isSelectedForPlatform: boolean;
     };
 }>;
+export {};

package/dist/tools/zhipin-exchange-wechat.d.ts

@@ -1,6 +1,7 @@
 export declare const zhipinExchangeWechat: import("@roll-agent/sdk").ToolDefinition<{
-    index?: number | undefined;
+    conversationId?: string | undefined;
     candidateName?: string | undefined;
+    index?: number | undefined;
 }, {
     success: boolean;
     exchanged: boolean;

package/dist/tools/zhipin-filter-recommend-candidates.d.ts

@@ -0,0 +1,40 @@
+import { getContextManager } from "../runtime-holder.ts";
+import { applyRecommendFilter, waitForRecommendFilterSurface, type RecommendTarget } from "../pages/zhipin/recommend-filter.ts";
+import { getRecommendTarget } from "../pages/zhipin/recommend-list.ts";
+import { VisualActivitySession } from "../visual-activity-session.ts";
+import { moveVisualCursorToLocator, showVisualClickOnLocator } from "../visual-cursor.ts";
+type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "retarget" | "succeed" | "fail">;
+type ZhipinFilterRecommendCandidatesDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly getRecommendTarget: typeof getRecommendTarget;
+    readonly waitForRecommendFilterSurface: typeof waitForRecommendFilterSurface;
+    readonly applyRecommendFilter: typeof applyRecommendFilter;
+    readonly moveVisualCursorToLocator: typeof moveVisualCursorToLocator;
+    readonly showVisualClickOnLocator: typeof showVisualClickOnLocator;
+    readonly createVisualActivitySession: (target: RecommendTarget) => VisualActivitySessionLike;
+};
+export declare function setZhipinFilterRecommendCandidatesDepsForTests(override: Partial<ZhipinFilterRecommendCandidatesDeps> | undefined): void;
+export declare const zhipinFilterRecommendCandidates: import("@roll-agent/sdk").ToolDefinition<{
+    activity?: "不限" | "刚刚活跃" | "今日活跃" | "3日内活跃" | "本周活跃" | "本月活跃" | undefined;
+    ageMin?: number | undefined;
+    ageMax?: number | undefined;
+    gender?: "不限" | "男" | "女" | undefined;
+}, {
+    status: "error" | "applied" | "recommend_not_ready" | "filter_not_found" | "requires_vip" | "age_not_applied" | "submit_failed";
+    success: boolean;
+    requested: {
+        activity: "不限" | "刚刚活跃" | "今日活跃" | "3日内活跃" | "本周活跃" | "本月活跃";
+        gender: "不限" | "男" | "女";
+        ageMin?: number | undefined;
+        ageMax?: number | undefined;
+    };
+    error?: string | undefined;
+    applied?: {
+        activity: string;
+        gender: string;
+        ageMin?: number | undefined;
+        ageMax?: number | undefined;
+    } | undefined;
+    filterButtonText?: string | undefined;
+}>;
+export {};

package/dist/tools/zhipin-get-candidate-info.d.ts

@@ -1,6 +1,7 @@
 export declare const zhipinGetCandidateInfo: import("@roll-agent/sdk").ToolDefinition<{
-    index?: number | undefined;
+    conversationId?: string | undefined;
     candidateName?: string | undefined;
+    index?: number | undefined;
     maxMessages?: number | undefined;
 }, {
     success: boolean;

package/dist/tools/zhipin-get-candidate-list.d.ts

@@ -1,11 +1,25 @@
+import { getRecommendTarget, waitForRecommendList } from "../pages/zhipin/recommend-list.ts";
+import { getContextManager } from "../runtime-holder.ts";
+import { VisualActivitySession } from "../visual-activity-session.ts";
+type RecommendTarget = ReturnType<typeof getRecommendTarget>;
+type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail" | "retarget">;
+type ZhipinGetCandidateListDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly getRecommendTarget: typeof getRecommendTarget;
+    readonly waitForRecommendList: typeof waitForRecommendList;
+    readonly createVisualActivitySession: (target: RecommendTarget) => VisualActivitySessionLike;
+};
+export declare function setZhipinGetCandidateListDepsForTests(override: Partial<ZhipinGetCandidateListDeps> | undefined): void;
 export declare const zhipinGetCandidateList: import("@roll-agent/sdk").ToolDefinition<{
+    autoScroll?: boolean | undefined;
+    maxScrolls?: number | undefined;
     maxResults?: number | undefined;
 }, {
     success: boolean;
     candidates: {
         name: string;
-        index: number;
         candidateId: string;
+        index: number;
         expectedLocation: string;
         expectedPosition: string;
         age: string;
@@ -20,4 +34,19 @@ export declare const zhipinGetCandidateList: import("@roll-agent/sdk").ToolDefin
     }[];
     total: number;
     error?: string | undefined;
+    scrollStats?: {
+        stopReason: "target-count" | "boundary" | "no-new-items" | "max-steps";
+        containerLabel: string;
+        stepsRequested: number;
+        stepsCompleted: number;
+        reachedBoundary: boolean;
+        uniqueCount: number;
+        duplicateCount: number;
+        noNewRounds: number;
+        beforeItemCount: number;
+        afterItemCount: number;
+        beforeScrollHeight: number;
+        afterScrollHeight: number;
+    } | undefined;
 }>;
+export {};

package/dist/tools/zhipin-get-username.d.ts

@@ -1,3 +1,15 @@
+import type { Page } from "@roll-agent/browser";
+import { getCurrentZhipinRecruiterIdentity } from "../pages/zhipin/recruiter-identity.ts";
+import { findHeaderScope } from "../pages/zhipin/username.ts";
+import { getContextManager } from "../runtime-holder.ts";
+import { VisualActivitySession } from "../visual-activity-session.ts";
+type ZhipinGetUsernameDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly findHeaderScope: typeof findHeaderScope;
+    readonly getCurrentZhipinRecruiterIdentity: typeof getCurrentZhipinRecruiterIdentity;
+    readonly createVisualActivitySession: (page: Page) => VisualActivitySession;
+};
+export declare function setZhipinGetUsernameDepsForTests(override: Partial<ZhipinGetUsernameDeps> | undefined): void;
 export declare const zhipinGetUsername: import("@roll-agent/sdk").ToolDefinition<{}, {
     success: boolean;
     username: string;
@@ -6,3 +18,4 @@ export declare const zhipinGetUsername: import("@roll-agent/sdk").ToolDefinition
     usedSelector?: string | undefined;
     usedStrategy?: string | undefined;
 }>;
+export {};

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

@@ -0,0 +1,36 @@
+import type { Page } from "@roll-agent/browser";
+import { randomDelay } from "../pages/zhipin/anti-detection.ts";
+import { findZhipinSidebarSectionLink, isZhipinChatSurfaceOpen, waitForZhipinChatSurface } from "../pages/zhipin/sidebar-navigation.ts";
+import { toAttachedPageInfo } from "../page-info.ts";
+import { getContextManager } from "../runtime-holder.ts";
+import { VisualActivitySession } from "../visual-activity-session.ts";
+import { moveVisualCursorToLocator, showVisualClickOnLocator } from "../visual-cursor.ts";
+type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "succeed" | "fail">;
+type ZhipinOpenChatPageDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly findZhipinSidebarSectionLink: typeof findZhipinSidebarSectionLink;
+    readonly isZhipinChatSurfaceOpen: typeof isZhipinChatSurfaceOpen;
+    readonly waitForZhipinChatSurface: typeof waitForZhipinChatSurface;
+    readonly moveVisualCursorToLocator: typeof moveVisualCursorToLocator;
+    readonly showVisualClickOnLocator: typeof showVisualClickOnLocator;
+    readonly randomDelay: typeof randomDelay;
+    readonly toAttachedPageInfo: typeof toAttachedPageInfo;
+    readonly createVisualActivitySession: (page: Page) => VisualActivitySessionLike;
+};
+export declare function setZhipinOpenChatPageDepsForTests(override: Partial<ZhipinOpenChatPageDeps> | undefined): void;
+export declare const zhipinOpenChatPage: import("@roll-agent/sdk").ToolDefinition<{}, {
+    success: boolean;
+    alreadyOnChat: boolean;
+    usedSidebarClick: boolean;
+    chatReady: boolean;
+    error?: string | undefined;
+    page?: {
+        url: string;
+        title: string;
+        pageId: string;
+        boundPlatform: "zhipin" | "yupao" | null;
+        detectedPlatform: "zhipin" | "yupao" | null;
+        isSelectedForPlatform: boolean;
+    } | undefined;
+}>;
+export {};

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

@@ -1,14 +1,17 @@
 export declare const zhipinOpenChat: import("@roll-agent/sdk").ToolDefinition<{
-    index?: number | undefined;
+    conversationId?: string | undefined;
     candidateName?: string | undefined;
+    index?: number | undefined;
     preferUnread?: boolean | undefined;
 }, {
     success: boolean;
+    conversationId: string;
+    candidateId: string;
+    candidateName: string;
+    index: number;
     hasUnread: boolean;
     unreadCount: number;
     lastMessageTime: string;
     messagePreview: string;
-    index: number;
-    candidateName: string;
     error?: string | undefined;
 }>;

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

@@ -0,0 +1,38 @@
+import { randomDelay } from "../pages/zhipin/anti-detection.ts";
+import { getRecommendTarget } from "../pages/zhipin/recommend-list.ts";
+import { findZhipinSidebarSectionLink, isZhipinRecommendSurfaceOpen, waitForZhipinRecommendSurface } from "../pages/zhipin/sidebar-navigation.ts";
+import { toAttachedPageInfo } from "../page-info.ts";
+import { getContextManager } from "../runtime-holder.ts";
+import { VisualActivitySession } from "../visual-activity-session.ts";
+import { moveVisualCursorToLocator, showVisualClickOnLocator } from "../visual-cursor.ts";
+type RecommendTarget = ReturnType<typeof getRecommendTarget>;
+type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "retarget" | "succeed" | "fail">;
+type ZhipinOpenRecommendPageDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly getRecommendTarget: typeof getRecommendTarget;
+    readonly findZhipinSidebarSectionLink: typeof findZhipinSidebarSectionLink;
+    readonly isZhipinRecommendSurfaceOpen: typeof isZhipinRecommendSurfaceOpen;
+    readonly waitForZhipinRecommendSurface: typeof waitForZhipinRecommendSurface;
+    readonly moveVisualCursorToLocator: typeof moveVisualCursorToLocator;
+    readonly showVisualClickOnLocator: typeof showVisualClickOnLocator;
+    readonly randomDelay: typeof randomDelay;
+    readonly toAttachedPageInfo: typeof toAttachedPageInfo;
+    readonly createVisualActivitySession: (target: RecommendTarget) => VisualActivitySessionLike;
+};
+export declare function setZhipinOpenRecommendPageDepsForTests(override: Partial<ZhipinOpenRecommendPageDeps> | undefined): void;
+export declare const zhipinOpenRecommendPage: import("@roll-agent/sdk").ToolDefinition<{}, {
+    success: boolean;
+    usedSidebarClick: boolean;
+    alreadyOnRecommend: boolean;
+    recommendReady: boolean;
+    error?: string | undefined;
+    page?: {
+        url: string;
+        title: string;
+        pageId: string;
+        boundPlatform: "zhipin" | "yupao" | null;
+        detectedPlatform: "zhipin" | "yupao" | null;
+        isSelectedForPlatform: boolean;
+    } | undefined;
+}>;
+export {};

package/dist/tools/zhipin-read-messages.d.ts

@@ -2,6 +2,8 @@ export declare const zhipinReadMessages: import("@roll-agent/sdk").ToolDefinitio
     limit?: number | undefined;
     onlyUnread?: boolean | undefined;
     sortBy?: "name" | "time" | "unreadCount" | undefined;
+    autoScroll?: boolean | undefined;
+    maxScrolls?: number | undefined;
 }, {
     success: boolean;
     candidates: {

package/dist/tools/zhipin-say-hello.d.ts

@@ -1,3 +1,23 @@
+import { getContextManager } from "../runtime-holder.ts";
+import { humanDelay, shouldAddRandomBehavior, performRandomScroll } from "../pages/zhipin/anti-detection.ts";
+import { getRecommendTarget, inspectRecommendCard, waitForRecommendList } from "../pages/zhipin/recommend-list.ts";
+import { VisualActivitySession } from "../visual-activity-session.ts";
+import { moveVisualCursorToLocator, showVisualClickOnLocator } from "../visual-cursor.ts";
+type RecommendTarget = ReturnType<typeof getRecommendTarget>;
+type VisualActivitySessionLike = Pick<VisualActivitySession, "begin" | "highlightSelector" | "highlightLocator" | "succeed" | "fail" | "retarget">;
+type ZhipinSayHelloDeps = {
+    readonly getContextManager: typeof getContextManager;
+    readonly getRecommendTarget: typeof getRecommendTarget;
+    readonly waitForRecommendList: typeof waitForRecommendList;
+    readonly inspectRecommendCard: typeof inspectRecommendCard;
+    readonly moveVisualCursorToLocator: typeof moveVisualCursorToLocator;
+    readonly showVisualClickOnLocator: typeof showVisualClickOnLocator;
+    readonly humanDelay: typeof humanDelay;
+    readonly shouldAddRandomBehavior: typeof shouldAddRandomBehavior;
+    readonly performRandomScroll: typeof performRandomScroll;
+    readonly createVisualActivitySession: (target: RecommendTarget) => VisualActivitySessionLike;
+};
+export declare function setZhipinSayHelloDepsForTests(override: Partial<ZhipinSayHelloDeps> | undefined): void;
 export declare const zhipinSayHello: import("@roll-agent/sdk").ToolDefinition<{
     indices: number[];
 }, {
@@ -9,9 +29,10 @@ export declare const zhipinSayHello: import("@roll-agent/sdk").ToolDefinition<{
     success: boolean;
     results: {
         success: boolean;
-        index: number;
         candidateId: string;
         candidateName: string;
+        index: number;
         error?: string | undefined;
     }[];
 }>;
+export {};

package/dist/tools/zhipin-scroll-view.d.ts

@@ -0,0 +1,35 @@
+export declare const zhipinScrollView: import("@roll-agent/sdk").ToolDefinition<{
+    surface: "chat-list" | "chat-history" | "recommend-list";
+    direction?: "up" | "down" | undefined;
+    distance?: number | undefined;
+    steps?: number | undefined;
+    settleMs?: number | undefined;
+}, {
+    success: boolean;
+    direction: "up" | "down";
+    stepsRequested: number;
+    stepsCompleted: number;
+    before: {
+        containerFound: boolean;
+        containerLabel: string;
+        scrollTop: number;
+        scrollHeight: number;
+        clientHeight: number;
+        atStart: boolean;
+        atEnd: boolean;
+        itemCount: number;
+    };
+    after: {
+        containerFound: boolean;
+        containerLabel: string;
+        scrollTop: number;
+        scrollHeight: number;
+        clientHeight: number;
+        atStart: boolean;
+        atEnd: boolean;
+        itemCount: number;
+    };
+    reachedBoundary: boolean;
+    surface: "chat-list" | "chat-history" | "recommend-list";
+    error?: string | undefined;
+}>;

package/dist/tools/zhipin-send-reply.d.ts

@@ -1,7 +1,7 @@
 export declare const zhipinSendReply: import("@roll-agent/sdk").ToolDefinition<{
     signedEnvelope: string;
-    index?: number | undefined;
     candidateName?: string | undefined;
+    index?: number | undefined;
 }, {
     success: boolean;
     sentMessage: string;

package/dist/visual-activity-session.d.ts

@@ -0,0 +1,21 @@
+import type { Page } from "@roll-agent/browser";
+import type { VisualActivityTone, VisualTarget } from "./visual-activity.ts";
+type PageLocator = ReturnType<Page["locator"]>;
+type VisualActivityHighlightOptions = {
+    readonly label?: string;
+    readonly padding?: number;
+    readonly tone?: VisualActivityTone;
+};
+export declare class VisualActivitySession {
+    page: Page;
+    target: VisualTarget;
+    constructor(initialTarget: VisualTarget);
+    retarget(nextTarget: VisualTarget): Promise<boolean>;
+    begin(label: string, tone?: VisualActivityTone): Promise<boolean>;
+    highlightSelector(selector: string, options?: VisualActivityHighlightOptions): Promise<boolean>;
+    highlightLocator(locator: PageLocator, options?: VisualActivityHighlightOptions): Promise<boolean>;
+    succeed(label: string, lingerMs?: number): Promise<boolean>;
+    fail(label: string, lingerMs?: number): Promise<boolean>;
+    clear(): Promise<boolean>;
+}
+export {};

package/dist/visual-activity.d.ts

@@ -0,0 +1,60 @@
+import type { Page } from "@roll-agent/browser";
+type PageLocator = ReturnType<Page["locator"]>;
+export type VisualTarget = Page | NonNullable<ReturnType<Page["frame"]>>;
+type VisualActivityOptions = {
+    readonly label: string;
+    readonly target?: VisualTarget;
+    readonly tone?: VisualActivityTone;
+};
+type VisualHighlightOptions = {
+    readonly label?: string;
+    readonly padding?: number;
+    readonly target?: VisualTarget;
+    readonly tone?: VisualActivityTone;
+};
+type VisualCompletionOptions = {
+    readonly label: string;
+    readonly lingerMs?: number;
+    readonly status?: "success" | "error";
+    readonly target?: VisualTarget;
+};
+declare const VISUAL_ACTIVITY_THEMES: {
+    readonly info: {
+        readonly accent: "#14b8a6";
+        readonly accentSoft: "rgba(20, 184, 166, 0.42)";
+        readonly accentGlow: "rgba(20, 184, 166, 0.18)";
+        readonly capsuleBg: "rgba(15, 23, 42, 0.82)";
+        readonly capsuleBorder: "rgba(45, 212, 191, 0.38)";
+        readonly text: "#F8FAFC";
+        readonly dot: "#2DD4BF";
+    };
+    readonly success: {
+        readonly accent: "#22c55e";
+        readonly accentSoft: "rgba(34, 197, 94, 0.42)";
+        readonly accentGlow: "rgba(34, 197, 94, 0.18)";
+        readonly capsuleBg: "rgba(10, 24, 16, 0.86)";
+        readonly capsuleBorder: "rgba(74, 222, 128, 0.38)";
+        readonly text: "#F0FDF4";
+        readonly dot: "#4ADE80";
+    };
+    readonly error: {
+        readonly accent: "#f59e0b";
+        readonly accentSoft: "rgba(245, 158, 11, 0.42)";
+        readonly accentGlow: "rgba(245, 158, 11, 0.2)";
+        readonly capsuleBg: "rgba(41, 24, 10, 0.88)";
+        readonly capsuleBorder: "rgba(251, 191, 36, 0.4)";
+        readonly text: "#FFFBEB";
+        readonly dot: "#FBBF24";
+    };
+};
+export type VisualActivityTone = keyof typeof VISUAL_ACTIVITY_THEMES;
+export declare function isVisualActivityEnabled(): boolean;
+export declare function setVisualActivityEnabledForTests(value: boolean | undefined): void;
+export declare function beginVisualActivity(page: Page, options: VisualActivityOptions): Promise<boolean>;
+export declare function highlightVisualRegionForLocator(page: Page, locator: PageLocator, options?: VisualHighlightOptions): Promise<boolean>;
+export declare function highlightVisualRegionForSelector(page: Page, selector: string, options?: VisualHighlightOptions): Promise<boolean>;
+export declare function completeVisualActivity(page: Page, options: VisualCompletionOptions): Promise<boolean>;
+export declare function clearVisualActivity(page: Page, options?: {
+    readonly target?: VisualTarget;
+}): Promise<boolean>;
+export {};

package/dist/visual-cursor.d.ts

@@ -0,0 +1,22 @@
+import type { Page } from "@roll-agent/browser";
+type PageLocator = ReturnType<Page["locator"]>;
+type VisualTarget = Page | NonNullable<ReturnType<Page["frame"]>>;
+type CursorMoveOptions = {
+    readonly durationMs?: number;
+    readonly settleMs?: number;
+    readonly target?: VisualTarget;
+};
+type CursorClickOptions = {
+    readonly pulseDurationMs?: number;
+    readonly target?: VisualTarget;
+};
+export declare function isVisualCursorEnabled(): boolean;
+export declare function setVisualCursorEnabledForTests(value: boolean | undefined): void;
+export declare function clearVisualCursor(page: Page, options?: {
+    readonly preserveTarget?: VisualTarget;
+}): Promise<boolean>;
+export declare function moveVisualCursorToLocator(page: Page, locator: PageLocator, options?: CursorMoveOptions): Promise<boolean>;
+export declare function showVisualClickOnLocator(page: Page, locator: PageLocator, options?: CursorClickOptions): Promise<boolean>;
+export declare function moveVisualCursorToSelector(page: Page, selector: string, options?: CursorMoveOptions): Promise<boolean>;
+export declare function showVisualClickOnSelector(page: Page, selector: string): Promise<boolean>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roll-agent/browser-use-agent",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "type": "module",
   "repository": {
     "type": "git",

package/references/env.yaml

@@ -2,3 +2,12 @@ required:
   - name: REPLY_AUTHORITY_KEYS_URL
     purpose: Reply Authority Service 公钥分发端点；`zhipin_send_reply` 启动预热和本地 Ed25519 验签都依赖它
     example: https://reply-authority.duliday.com/.well-known/reply-authority-keys
+optional:
+  - name: BROWSER_VISUAL_CURSOR
+    purpose: 在可见浏览器页面内显示 browser-use 的页内虚拟指针和点击波纹；默认开启，设为 `"false"` 可关闭
+    default: "true"
+    example: "false"
+  - name: BROWSER_VISUAL_ACTIVITY
+    purpose: 在消息读取、账号识别、聊天详情提取等非点击型操作期间显示页内状态胶囊、区域柔光和完成态反馈；默认开启，设为 `"false"` 可关闭
+    default: "true"
+    example: "true"