@mearl/native-host 2.6.0 → 2.7.0

package/README.md

@@ -45,6 +45,8 @@ mearl-native-host [options]
   --daemon                                                   独立 CDP daemon
   --cdp-port <port>                                          指定 CDP 端口
   --cdp-user-data-dir <dir>                                  指定 Chrome Profile
+  --agentbay-session-id <id>                                 连接 AgentBay CDP Session
+  --agentbay-idle-release-minutes <minutes>                  AgentBay 空闲回收时间（内部参数）
   --browser-id <id>                                          指定浏览器注册 ID
   --browser-name <name>                                      指定浏览器显示名称
   --version, -v                                             查看版本
@@ -63,6 +65,15 @@ Chrome Extension
 
 `browser_launch` 会为每个托管 Chrome 启动一个带独立 CDP 配置的 native-host 子进程，使多个 headless/Profile/TDBank 账号实例可以同时被现有浏览器注册表寻址。设计细节见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
+AgentBay 会话创建时使用官方 `LifecyclePolicy`：默认 30 分钟没有 Mearl 指令时由本地宿主执行优雅关闭，120 分钟达到云端最大运行时长时由 AgentBay 强制释放。优雅关闭会先同步持久化 Browser Context，再删除 Session 和本地注册记录；执行中的 Mearl action 不计为空闲。正常任务仍应主动调用 `browser_close`，超时只用于异常退出兜底。
+
+运维环境可覆盖默认值；两项均为正整数分钟，空闲时间至少为 3，最大运行时长不得小于空闲时间：
+
+```bash
+MEARL_AGENTBAY_IDLE_RELEASE_MINUTES=30
+MEARL_AGENTBAY_MAX_RUNTIME_MINUTES=120
+```
+
 ## 侧边栏 Agent Chat
 
 扩展侧边栏通过 Native Messaging 调用 native-host，再按用户选择启动持久的 Codex app-server 或 Qoder ACP 进程。两种 Provider 都支持流式消息、思考与工具进度、中断和审批，并复用各自 CLI 已保存的本地登录态。

package/dist/agentbay-browser.d.ts

@@ -9,6 +9,7 @@ export interface AgentBayBrowserRecord extends DaemonRecord {
     name: string;
     sessionId: string;
     imageId?: string;
+    userAgentMode?: 'default' | 'desktop';
     persistent?: boolean;
     contextId?: string;
     contextName?: string;
@@ -93,12 +94,21 @@ export interface AgentBayBrowserSummary {
     copiedCookies?: AgentBayBrowserRecord['copiedCookies'];
     running: boolean;
 }
+export interface AgentBayBrowserLaunchResult extends AgentBayBrowserSummary {
+    created: boolean;
+    reused: boolean;
+}
 export interface AgentBayBrowserManagerDeps {
     nativeHostScript: string;
     exportCookies: (domains: string[]) => Promise<TransferableCookie[]>;
     getBrowserUserAgent: () => Promise<string>;
     log: (...args: any[]) => void;
     createAgentBayClient?: (apiKey: string) => Promise<AgentBayClientLike>;
+    connectCdp?: ConnectAgentBayCdp;
+    findBrowserRecord?: (selector: string) => {
+        record: AgentBayBrowserRecord;
+        running: boolean;
+    } | null;
     persistBrowserRecord?: (record: AgentBayBrowserRecord) => void;
     resolveApiKey?: () => string;
 }
@@ -124,7 +134,8 @@ export declare function getAgentBayAccessUrl(sessionId: string, dependencies?: P
 export declare function resolveAgentBayEndpoint(sessionId: string): Promise<string>;
 export declare function keepAgentBaySessionAlive(sessionId: string): Promise<void>;
 export declare function initializeAgentBayBrowserSession(session: Pick<AgentBaySessionLike, 'browser'>, input: Pick<BrowserLaunchParams, 'url'>, cookies: TransferableCookie[], options?: AgentBayBrowserSessionInitOptions): Promise<number>;
-export declare function launchAgentBayBrowser(input: BrowserLaunchParams, deps: AgentBayBrowserManagerDeps): Promise<AgentBayBrowserSummary>;
+export declare function reuseAgentBayBrowserSession(session: Pick<AgentBaySessionLike, 'browser'>, input: Pick<BrowserLaunchParams, 'url'>, cookies: TransferableCookie[], options?: Pick<AgentBayBrowserSessionInitOptions, 'connectCdp'>): Promise<number>;
+export declare function launchAgentBayBrowser(input: BrowserLaunchParams, deps: AgentBayBrowserManagerDeps): Promise<AgentBayBrowserLaunchResult>;
 export declare function releaseAgentBayBrowserResources(record: AgentBayBrowserRecord, agentBay: AgentBayClientLike, options?: {
     deleteProfile?: boolean;
     persistRecord?: (record: AgentBayBrowserRecord) => void;

package/dist/agentbay-lifecycle.d.ts

@@ -0,0 +1,38 @@
+export declare const MIN_AGENTBAY_IDLE_RELEASE_MINUTES = 3;
+export declare const DEFAULT_AGENTBAY_IDLE_RELEASE_MINUTES = 30;
+export declare const DEFAULT_AGENTBAY_MAX_RUNTIME_MINUTES = 120;
+export declare const DEFAULT_AGENTBAY_LIFECYCLE_CHECK_INTERVAL_MS = 60000;
+export interface AgentBayLifecycleConfig {
+    idleReleaseTimeout: number;
+    maxRuntime: number;
+}
+interface AgentBaySessionWatchdogOptions {
+    idleTimeoutMs: number;
+    checkIntervalMs?: number;
+    now?: () => number;
+    keepAlive: () => Promise<void>;
+    close: () => Promise<void>;
+    log: (...args: unknown[]) => void;
+}
+export declare function resolveAgentBayLifecycleConfig(env?: NodeJS.ProcessEnv): AgentBayLifecycleConfig;
+export declare class AgentBaySessionWatchdog {
+    private readonly idleTimeoutMs;
+    private readonly checkIntervalMs;
+    private readonly now;
+    private readonly keepAlive;
+    private readonly close;
+    private readonly log;
+    private activeRequests;
+    private lastActivityAt;
+    private timer;
+    private checking;
+    private closing;
+    private stopped;
+    constructor(options: AgentBaySessionWatchdogOptions);
+    start(): void;
+    stop(): void;
+    beginActivity(): boolean;
+    endActivity(): void;
+    checkNow(): Promise<void>;
+}
+export {};

package/dist/cdp-backend/cdp-utils.d.ts

@@ -4,7 +4,7 @@
  * Contains: HTTP helper (nodeFetch), cookie utilities, page-load waiters,
  * viewport helpers, and serialized function sources for page injection.
  */
-import { type PageClickPointerType } from '@mearl/browser-core';
+import { type PageClickPointerType, type PageDragPoint, type PageDragPointerType } from '@mearl/browser-core';
 import type { PageSession } from './cdp-session.js';
 export declare const TYPE_INTO_ELEMENT_SRC: string;
 export declare const CLICK_ELEMENT_VIA_JS_SRC: string;
@@ -61,4 +61,7 @@ export declare function toCdpInputPoint(session: PageSession, x: number, y: numb
     y: number;
 }>;
 export declare function dispatchCdpClick(session: PageSession, x: number, y: number, pointerType: PageClickPointerType): Promise<void>;
+export declare function dispatchCdpDrag(session: PageSession, from: PageDragPoint, to: PageDragPoint, pointerType: PageDragPointerType, durationMs: number): Promise<{
+    steps: number;
+}>;
 export declare function resolveBackendNodeObjectId(session: PageSession, backendNodeId: number): Promise<string>;

package/dist/cdp-backend/interaction-handlers.d.ts

@@ -3,9 +3,10 @@
  *
  * Covers: click, type, scroll, eval, press, wait, navigate, upload, device emulation.
  */
-import { type PageClickParams, type PageEvalParams, type PageHoverParams, type PageNavigateParams, type PagePressParams, type PageScrollParams, type PageTypeParams, type PageUploadParams, type PageWaitParams, type SetDeviceEmulationParams } from '@mearl/browser-core';
+import { type PageClickParams, type PageDragParams, type PageDragResultData, type PageEvalParams, type PageHoverParams, type PageNavigateParams, type PagePressParams, type PageScrollParams, type PageTypeParams, type PageUploadParams, type PageWaitParams, type SetDeviceEmulationParams } from '@mearl/browser-core';
 import type { PageSession } from './cdp-session.js';
 export declare function cdpPageClick(session: PageSession, data: PageClickParams): Promise<any>;
+export declare function cdpPageDrag(session: PageSession, data: PageDragParams): Promise<PageDragResultData>;
 export declare function cdpPageType(session: PageSession, data: PageTypeParams): Promise<any>;
 export declare function cdpPageScroll(session: PageSession, data: PageScrollParams): Promise<any>;
 export declare function cdpPageEval(session: PageSession, data: PageEvalParams): Promise<any>;

package/dist/index.js

@@ -2068,6 +2068,83 @@ function getClickCoordsFromNode() {
   };
 }
 
+// ../browser-core/dist/pageDragging.js
+var PAGE_DRAG_DEFAULT_DURATION_MS = 400;
+var PAGE_DRAG_MAX_DURATION_MS = 5e3;
+var PAGE_DRAG_STEP_INTERVAL_MS = 25;
+var PAGE_DRAG_MIN_STEPS = 2;
+var PAGE_DRAG_MAX_STEPS = 60;
+function isPageDragPoint(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const point = value;
+  return Number.isFinite(point.x) && Number.isFinite(point.y) && point.x >= 0 && point.y >= 0;
+}
+function resolveEndpoint(value, name) {
+  if (typeof value === "string" && value.trim().length > 0)
+    return value.trim();
+  if (isPageDragPoint(value))
+    return { x: value.x, y: value.y };
+  throw new Error(`page_drag: "${name}" must be a non-empty CSS/@ref selector or { x, y } viewport point.`);
+}
+function resolvePageDragInput(data) {
+  if (!data || typeof data !== "object") {
+    throw new Error("page_drag: payload is required");
+  }
+  if (data.dragMode !== void 0 && !["auto", "mouse", "touch"].includes(data.dragMode)) {
+    throw new Error('page_drag: "dragMode" must be one of auto, mouse, touch');
+  }
+  const durationMs = data.durationMs ?? PAGE_DRAG_DEFAULT_DURATION_MS;
+  if (!Number.isFinite(durationMs) || durationMs < 0 || durationMs > PAGE_DRAG_MAX_DURATION_MS) {
+    throw new Error(`page_drag: "durationMs" must be between 0 and ${PAGE_DRAG_MAX_DURATION_MS}.`);
+  }
+  return {
+    from: resolveEndpoint(data.from, "from"),
+    to: resolveEndpoint(data.to, "to"),
+    dragMode: data.dragMode ?? "auto",
+    durationMs: Math.round(durationMs)
+  };
+}
+function buildPageDragPath(from, to, durationMs) {
+  const steps = Math.max(PAGE_DRAG_MIN_STEPS, Math.min(PAGE_DRAG_MAX_STEPS, Math.ceil(durationMs / PAGE_DRAG_STEP_INTERVAL_MS)));
+  const points = Array.from({ length: steps }, (_, index) => {
+    const ratio = (index + 1) / steps;
+    return {
+      x: from.x + (to.x - from.x) * ratio,
+      y: from.y + (to.y - from.y) * ratio
+    };
+  });
+  return { points, intervalMs: durationMs / steps };
+}
+function getDragCoordsFromNode() {
+  const el = this.nodeType === Node.TEXT_NODE ? this.parentElement : this;
+  if (!el || typeof el.getBoundingClientRect !== "function")
+    return null;
+  const rect = el.getBoundingClientRect();
+  const viewportWidth = window.visualViewport?.width ?? window.innerWidth;
+  const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
+  if (rect.width <= 0 || rect.height <= 0) {
+    return { x: 0, y: 0, tag: "", text: "", error: "Element has no visible bounds" };
+  }
+  if (rect.right <= 0 || rect.bottom <= 0 || rect.left >= viewportWidth || rect.top >= viewportHeight) {
+    return {
+      x: 0,
+      y: 0,
+      tag: "",
+      text: "",
+      error: "Element is outside the current viewport; scroll it into view before dragging"
+    };
+  }
+  const x = Math.min(Math.max(rect.left + rect.width / 2, 0), Math.max(viewportWidth - 1, 0));
+  const y = Math.min(Math.max(rect.top + rect.height / 2, 0), Math.max(viewportHeight - 1, 0));
+  return {
+    x,
+    y,
+    tag: el.tagName?.toLowerCase() ?? "",
+    text: (el.textContent ?? "").trim().slice(0, 100)
+  };
+}
+
 // ../browser-core/dist/axSnapshot.js
 var PAGE_SNAPSHOT_QUERY_MAX_MATCHES = 100;
 var PAGE_SNAPSHOT_QUERY_MAX_BYTES = 256 * 1024;
@@ -3372,6 +3449,7 @@ var SEND_REQUEST_MAX_TOTAL_FILE_BYTES = 40 * 1024 * 1024;
 var SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES = 7 * 1024 * 1024;
 var PAGE_ACT_ACTIONS = [
   "page_click",
+  "page_drag",
   "page_type",
   "page_hover",
   "page_scroll",
@@ -3402,6 +3480,7 @@ var BROWSER_COMMAND_ACTIONS = {
   tab_close: true,
   tab_list: true,
   page_click: true,
+  page_drag: true,
   page_type: true,
   page_scroll: true,
   page_hover: true,
@@ -3442,6 +3521,7 @@ var EXTENSION_BROWSER_ACTIONS = {
   tab_close: true,
   tab_list: true,
   page_click: true,
+  page_drag: true,
   page_type: true,
   page_scroll: true,
   page_hover: true,
@@ -4339,6 +4419,12 @@ function resolveSetCookieTarget(currentUrl, input) {
 }
 
 // ../browser-core/dist/controlledFavicon.js
+function normalizeControlSource(source) {
+  return source === "remote" || source === "cloud" ? "remote" : "local";
+}
+function toControlSourceWireValue(source) {
+  return source === "remote" ? "cloud" : "local";
+}
 var BASE_ICON = `
   <rect width="128" height="128" rx="28" fill="#3273E8"/>
   <path d="M36 90V40L64 68L92 40V90" stroke="#FFFFFF" stroke-width="14"
@@ -4348,7 +4434,7 @@ var SOURCE_BADGES = {
   local: `
     <circle cx="104" cy="104" r="21" fill="#16A34A" stroke="#FFFFFF" stroke-width="6"/>
   `,
-  cloud: `
+  remote: `
     <circle cx="104" cy="104" r="21" fill="#FF7A00" stroke="#FFFFFF" stroke-width="6"/>
   `
 };
@@ -5949,6 +6035,85 @@ async function dispatchCdpClick(session, x, y, pointerType) {
     clickCount: 1
   });
 }
+async function dispatchCdpDrag(session, from, to, pointerType, durationMs) {
+  const [start, end] = await Promise.all([
+    toCdpInputPoint(session, from.x, from.y),
+    toCdpInputPoint(session, to.x, to.y)
+  ]);
+  const path15 = buildPageDragPath(start, end, durationMs);
+  const waitForNextPoint = async () => {
+    if (path15.intervalMs <= 0) return;
+    await new Promise((resolve2) => setTimeout(resolve2, path15.intervalMs));
+  };
+  if (pointerType === "touch") {
+    await sendCdpInputCommand(session, "Input.dispatchTouchEvent", {
+      type: "touchStart",
+      touchPoints: [start]
+    });
+    let primaryError2;
+    try {
+      for (const point of path15.points) {
+        await waitForNextPoint();
+        await sendCdpInputCommand(session, "Input.dispatchTouchEvent", {
+          type: "touchMove",
+          touchPoints: [point]
+        });
+      }
+    } catch (error48) {
+      primaryError2 = error48;
+      throw error48;
+    } finally {
+      await sendCdpInputCommand(session, "Input.dispatchTouchEvent", {
+        type: "touchEnd",
+        touchPoints: []
+      }).catch((error48) => {
+        if (primaryError2 === void 0) throw error48;
+      });
+    }
+    return { steps: path15.points.length };
+  }
+  await sendCdpInputCommand(session, "Input.dispatchMouseEvent", {
+    type: "mouseMoved",
+    x: start.x,
+    y: start.y
+  });
+  await sendCdpInputCommand(session, "Input.dispatchMouseEvent", {
+    type: "mousePressed",
+    x: start.x,
+    y: start.y,
+    button: "left",
+    buttons: 1,
+    clickCount: 1
+  });
+  let primaryError;
+  try {
+    for (const point of path15.points) {
+      await waitForNextPoint();
+      await sendCdpInputCommand(session, "Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x: point.x,
+        y: point.y,
+        button: "left",
+        buttons: 1
+      });
+    }
+  } catch (error48) {
+    primaryError = error48;
+    throw error48;
+  } finally {
+    await sendCdpInputCommand(session, "Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      x: end.x,
+      y: end.y,
+      button: "left",
+      buttons: 0,
+      clickCount: 1
+    }).catch((error48) => {
+      if (primaryError === void 0) throw error48;
+    });
+  }
+  return { steps: path15.points.length };
+}
 async function sendCdpInputCommand(session, method, params) {
   try {
     await session.client.sendCommand(method, params, PAGE_CLICK_INPUT_TIMEOUT_MS);
@@ -7940,6 +8105,7 @@ registerActions([
 ]);
 
 // src/cdp-backend/interaction-handlers.ts
+var GET_DRAG_COORDS_FROM_NODE_SRC = getDragCoordsFromNode.toString();
 function resolveSnapshotRef(session, ref) {
   const entry = resolvePageRef(session, ref);
   if (!entry) {
@@ -8251,6 +8417,102 @@ ${candidates}`
     )
   );
 }
+async function scrollDragSourceIntoView(session, endpoint) {
+  if (typeof endpoint !== "string") return;
+  validatePageElementSelector(endpoint, "page_drag from");
+  if (endpoint.startsWith("@e")) {
+    const entry = resolveSnapshotRef(session, endpoint);
+    const objectId = await resolveBackendNodeObjectId(session, entry.backendNodeId);
+    await session.client.sendCommand("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: `function() {
+        const el = this.nodeType === Node.TEXT_NODE ? this.parentElement : this;
+        if (!el) return false;
+        el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+        return true;
+      }`,
+      returnByValue: true
+    });
+    return;
+  }
+  const result = await session.client.sendCommand("Runtime.evaluate", {
+    expression: `(() => {
+      const selector = ${JSON.stringify(endpoint)};
+      const el = document.querySelector(selector);
+      if (!el) return { error: 'Element not found: ' + selector };
+      el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+      return { scrolled: true };
+    })()`,
+    returnByValue: true
+  });
+  const value = result.result?.value;
+  if (value?.error) throw new Error(`page_drag: ${value.error}`);
+}
+function unwrapDragElementCoords(value, endpoint) {
+  if (!value) throw new Error(`page_drag: cannot resolve element coordinates for "${endpoint}"`);
+  if (value.error) throw new Error(`page_drag: ${value.error}: "${endpoint}"`);
+  return value;
+}
+async function resolveDragEndpoint(session, endpoint) {
+  if (typeof endpoint !== "string") {
+    return { requested: endpoint, point: endpoint };
+  }
+  validatePageElementSelector(endpoint, "page_drag endpoint");
+  let coords;
+  if (endpoint.startsWith("@e")) {
+    const entry = resolveSnapshotRef(session, endpoint);
+    const objectId = await resolveBackendNodeObjectId(session, entry.backendNodeId);
+    const result = await session.client.sendCommand("Runtime.callFunctionOn", {
+      objectId,
+      functionDeclaration: GET_DRAG_COORDS_FROM_NODE_SRC,
+      returnByValue: true
+    });
+    coords = unwrapDragElementCoords(result.result?.value, endpoint);
+  } else {
+    const result = await session.client.sendCommand("Runtime.evaluate", {
+      expression: `(() => {
+        const selector = ${JSON.stringify(endpoint)};
+        const el = document.querySelector(selector);
+        if (!el) return { error: 'Element not found: ' + selector };
+        return (${GET_DRAG_COORDS_FROM_NODE_SRC}).call(el);
+      })()`,
+      returnByValue: true
+    });
+    coords = unwrapDragElementCoords(result.result?.value, endpoint);
+  }
+  return {
+    requested: endpoint,
+    point: { x: coords.x, y: coords.y },
+    tag: coords.tag,
+    text: coords.text
+  };
+}
+async function cdpPageDrag(session, data) {
+  const input = resolvePageDragInput(data);
+  await scrollDragSourceIntoView(session, input.from);
+  const from = await resolveDragEndpoint(session, input.from);
+  const to = await resolveDragEndpoint(session, input.to);
+  if (Math.hypot(to.point.x - from.point.x, to.point.y - from.point.y) < 1) {
+    throw new Error("page_drag: resolved endpoints must be at least 1 viewport pixel apart");
+  }
+  const pointerType = input.dragMode === "auto" ? await prefersTouchInput(session) ? "touch" : "mouse" : input.dragMode;
+  const { steps } = await dispatchCdpDrag(
+    session,
+    from.point,
+    to.point,
+    pointerType,
+    input.durationMs
+  );
+  return {
+    dragged: true,
+    from,
+    to,
+    dispatchMode: "trusted-input",
+    pointerType,
+    durationMs: input.durationMs,
+    steps
+  };
+}
 async function cdpPageType(session, data) {
   const { selector, text, clearFirst = true } = data;
   if (!selector || typeof selector !== "string") {
@@ -8571,6 +8833,7 @@ async function cdpPageHover(session, data) {
 }
 registerActions([
   { name: "page_click", session: "page", handler: cdpPageClick },
+  { name: "page_drag", session: "page", handler: cdpPageDrag },
   { name: "page_type", session: "page", handler: cdpPageType },
   { name: "page_hover", session: "page", handler: cdpPageHover },
   { name: "page_scroll", session: "page", handler: cdpPageScroll },
@@ -9373,6 +9636,12 @@ function acquireLaunchLock(browserId) {
   };
 }
 async function launchManagedBrowser(input, deps) {
+  if (input.reuse !== void 0 && input.reuse !== "never" && input.reuse !== "prefer" && input.reuse !== "require") {
+    throw new Error('reuse must be "never", "prefer", or "require"');
+  }
+  if (input.reuse === "prefer" || input.reuse === "require") {
+    throw new Error("reuse is currently supported only by the AgentBay browser provider");
+  }
   if (input.imageId !== void 0) {
     throw new Error("imageId is only supported by the AgentBay browser provider");
   }
@@ -9477,7 +9746,11 @@ async function launchManagedBrowser(input, deps) {
     recordWritten = true;
     await waitForBrowserRegistration(browserId, hostPid);
     deps.log(`managed browser launched: ${browserId}, chrome=${chromePid}, host=${hostPid}`);
-    return browserSummary(record2, true);
+    return {
+      ...browserSummary(record2, true),
+      created: true,
+      reused: false
+    };
   } catch (error48) {
     session?.close();
     if (hostPid) await stopProcess(hostPid, `--browser-id ${browserId}`);
@@ -9513,6 +9786,127 @@ import { spawn as spawn4 } from "node:child_process";
 import { homedir as homedir2 } from "node:os";
 import { dirname as dirname3, join as join4, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+
+// src/agentbay-lifecycle.ts
+var MIN_AGENTBAY_IDLE_RELEASE_MINUTES = 3;
+var DEFAULT_AGENTBAY_IDLE_RELEASE_MINUTES = 30;
+var DEFAULT_AGENTBAY_MAX_RUNTIME_MINUTES = 120;
+var DEFAULT_AGENTBAY_LIFECYCLE_CHECK_INTERVAL_MS = 6e4;
+function positiveIntegerMinutes(value, name, fallback) {
+  if (value === void 0 || !value.trim()) return fallback;
+  const minutes = Number(value);
+  if (!Number.isInteger(minutes) || minutes <= 0) {
+    throw new Error(`${name} must be a positive integer in minutes`);
+  }
+  return minutes;
+}
+function resolveAgentBayLifecycleConfig(env = process.env) {
+  const idleReleaseTimeout = positiveIntegerMinutes(
+    env.MEARL_AGENTBAY_IDLE_RELEASE_MINUTES,
+    "MEARL_AGENTBAY_IDLE_RELEASE_MINUTES",
+    DEFAULT_AGENTBAY_IDLE_RELEASE_MINUTES
+  );
+  const maxRuntime = positiveIntegerMinutes(
+    env.MEARL_AGENTBAY_MAX_RUNTIME_MINUTES,
+    "MEARL_AGENTBAY_MAX_RUNTIME_MINUTES",
+    DEFAULT_AGENTBAY_MAX_RUNTIME_MINUTES
+  );
+  if (idleReleaseTimeout < MIN_AGENTBAY_IDLE_RELEASE_MINUTES) {
+    throw new Error(
+      `MEARL_AGENTBAY_IDLE_RELEASE_MINUTES must be at least ${MIN_AGENTBAY_IDLE_RELEASE_MINUTES}`
+    );
+  }
+  if (maxRuntime < idleReleaseTimeout) {
+    throw new Error(
+      "MEARL_AGENTBAY_MAX_RUNTIME_MINUTES must be greater than or equal to MEARL_AGENTBAY_IDLE_RELEASE_MINUTES"
+    );
+  }
+  return { idleReleaseTimeout, maxRuntime };
+}
+var AgentBaySessionWatchdog = class {
+  idleTimeoutMs;
+  checkIntervalMs;
+  now;
+  keepAlive;
+  close;
+  log;
+  activeRequests = 0;
+  lastActivityAt;
+  timer = null;
+  checking = false;
+  closing = false;
+  stopped = false;
+  constructor(options) {
+    if (!Number.isFinite(options.idleTimeoutMs) || options.idleTimeoutMs <= 0) {
+      throw new Error("AgentBay idle timeout must be positive");
+    }
+    this.idleTimeoutMs = options.idleTimeoutMs;
+    this.checkIntervalMs = options.checkIntervalMs ?? DEFAULT_AGENTBAY_LIFECYCLE_CHECK_INTERVAL_MS;
+    if (!Number.isFinite(this.checkIntervalMs) || this.checkIntervalMs <= 0) {
+      throw new Error("AgentBay lifecycle check interval must be positive");
+    }
+    this.now = options.now ?? Date.now;
+    this.keepAlive = options.keepAlive;
+    this.close = options.close;
+    this.log = options.log;
+    this.lastActivityAt = this.now();
+  }
+  start() {
+    if (this.timer || this.stopped) return;
+    this.timer = setInterval(() => void this.checkNow(), this.checkIntervalMs);
+    this.timer.unref();
+  }
+  stop() {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  beginActivity() {
+    if (this.stopped || this.closing) return false;
+    this.activeRequests += 1;
+    this.lastActivityAt = this.now();
+    return true;
+  }
+  endActivity() {
+    if (this.activeRequests > 0) this.activeRequests -= 1;
+    this.lastActivityAt = this.now();
+  }
+  async checkNow() {
+    if (this.stopped || this.checking || this.closing) return;
+    this.checking = true;
+    try {
+      const idleForMs = this.now() - this.lastActivityAt;
+      if (this.activeRequests > 0 || idleForMs < this.idleTimeoutMs) {
+        try {
+          await this.keepAlive();
+        } catch (error48) {
+          this.log(
+            "AgentBay keepalive failed:",
+            error48 instanceof Error ? error48.message : String(error48)
+          );
+        }
+        return;
+      }
+      this.closing = true;
+      this.log(`AgentBay browser reached the idle timeout after ${idleForMs}ms; closing`);
+      try {
+        await this.close();
+      } catch (error48) {
+        this.closing = false;
+        this.log(
+          "AgentBay idle close failed:",
+          error48 instanceof Error ? error48.message : String(error48)
+        );
+      }
+    } finally {
+      this.checking = false;
+    }
+  }
+};
+
+// src/agentbay-browser.ts
 var AGENTBAY_BROWSERS_SUBDIR = "agentbay-browsers";
 var DEFAULT_AGENTBAY_IMAGE_ID = "imgc-0aae4rgl8kvagdv1j";
 var sdkPromise = null;
@@ -9589,6 +9983,24 @@ function validateAgentBayInput(input) {
     throw new Error("TDBank login parameters are only supported by the local browser provider");
   }
 }
+function resolveReuseMode(value) {
+  if (value === void 0) return "never";
+  if (value === "never" || value === "prefer" || value === "require") return value;
+  throw new Error('reuse must be "never", "prefer", or "require"');
+}
+function validateReusableAgentBayConfiguration(input, record2) {
+  if (input.imageId !== void 0 && resolveAgentBayImageId(input.imageId) !== record2.imageId) {
+    throw new Error(`Cannot change imageId while reusing AgentBay browser: ${record2.browserId}`);
+  }
+  if (input.persistent !== void 0 && input.persistent !== (record2.persistent === true)) {
+    throw new Error(`Cannot change persistent while reusing AgentBay browser: ${record2.browserId}`);
+  }
+  if (input.userAgentMode !== void 0 && record2.userAgentMode !== void 0 && input.userAgentMode !== record2.userAgentMode) {
+    throw new Error(
+      `Cannot change userAgentMode while reusing AgentBay browser: ${record2.browserId}`
+    );
+  }
+}
 function resolveAgentBayImageId(value) {
   if (value === void 0) return DEFAULT_AGENTBAY_IMAGE_ID;
   const imageId = typeof value === "string" ? value.trim() : "";
@@ -9647,11 +10059,14 @@ function listRecords2() {
   }
   return records;
 }
-function findRecord(selector) {
+function findRecordWithStatus(selector) {
   const normalized = selector.trim().toLowerCase();
   return listRecords2().find(
     ({ record: record2 }) => record2.browserId.toLowerCase() === normalized || record2.name.toLowerCase() === normalized
-  )?.record ?? null;
+  ) ?? null;
+}
+function findRecord(selector) {
+  return findRecordWithStatus(selector)?.record ?? null;
 }
 function hasAgentBayBrowser(selector) {
   return findRecord(selector) !== null;
@@ -9723,13 +10138,9 @@ async function keepAgentBaySessionAlive(sessionId) {
   const result = await session.keepAlive();
   if (result.success === false) throw new Error(result.errorMessage || "AgentBay keepalive failed");
 }
-async function initializeAgentBayBrowserSession(session, input, cookies, options = {}) {
-  const initialized = await session.browser.initializeAsync(
-    options.userAgent ? { userAgent: options.userAgent } : {}
-  );
-  if (!initialized) throw new Error("AgentBay browser initialization failed");
+async function configureAgentBayBrowserSession(session, input, cookies, connectCdp = (url2) => CdpClient.connect(url2)) {
   const endpoint = await session.browser.getEndpointUrl();
-  const cdp = await (options.connectCdp ?? ((url2) => CdpClient.connect(url2)))(endpoint);
+  const cdp = await connectCdp(endpoint);
   try {
     await cdp.sendCommand("Browser.getVersion", {}, 1e4);
     const copiedCookieCount = await cdpImportCookiesWithClient(cdp, cookies);
@@ -9741,32 +10152,76 @@ async function initializeAgentBayBrowserSession(session, input, cookies, options
     cdp.close();
   }
 }
+async function initializeAgentBayBrowserSession(session, input, cookies, options = {}) {
+  const initialized = await session.browser.initializeAsync(
+    options.userAgent ? { userAgent: options.userAgent } : {}
+  );
+  if (!initialized) throw new Error("AgentBay browser initialization failed");
+  return configureAgentBayBrowserSession(session, input, cookies, options.connectCdp);
+}
+async function reuseAgentBayBrowserSession(session, input, cookies, options = {}) {
+  return configureAgentBayBrowserSession(session, input, cookies, options.connectCdp);
+}
 async function launchAgentBayBrowser(input, deps) {
   const name = validateName(input.name);
   const browserId = agentBayBrowserId(name);
   validateAgentBayInput(input);
+  const reuseMode = resolveReuseMode(input.reuse);
   const imageId = resolveAgentBayImageId(input.imageId);
   const persistent = input.persistent === true;
   const userAgentMode = resolveUserAgentMode(input.userAgentMode);
   const copyCookieDomains = input.copyCookieDomains === void 0 ? [] : normalizeCookieDomains(input.copyCookieDomains);
   const apiKey = (deps.resolveApiKey ?? resolveAgentBayApiKey)();
+  const lifecycle = resolveAgentBayLifecycleConfig();
   const releaseLock = acquireLaunchLock(browserId);
   const persistBrowserRecord = deps.persistBrowserRecord ?? ((record2) => writeRecord(keyedConfigFile(AGENTBAY_BROWSERS_SUBDIR, record2.browserId), record2));
+  const findBrowserRecord = deps.findBrowserRecord ?? findRecordWithStatus;
   let session = null;
   let context;
   let hostPid = 0;
   let recordWritten = false;
   try {
-    if (findRecord(browserId)) throw new Error(`AgentBay browser already exists: ${browserId}`);
+    const existing = findBrowserRecord(browserId);
+    if (existing) {
+      if (reuseMode === "never") {
+        throw new Error(`AgentBay browser already exists: ${browserId}`);
+      }
+      if (!existing.running) {
+        throw new Error(`AgentBay browser is not running and cannot be reused: ${browserId}`);
+      }
+      validateReusableAgentBayConfiguration(input, existing.record);
+      const cookies2 = copyCookieDomains.length > 0 ? await deps.exportCookies(copyCookieDomains) : [];
+      const agentBay2 = await (deps.createAgentBayClient ?? createClient)(apiKey);
+      const existingSession = await requireSessionFromClient(agentBay2, existing.record.sessionId);
+      const copiedCookieCount2 = await reuseAgentBayBrowserSession(existingSession, input, cookies2, {
+        connectCdp: deps.connectCdp
+      });
+      const record3 = {
+        ...existing.record,
+        ...copyCookieDomains.length > 0 ? { copiedCookies: { domains: copyCookieDomains, count: copiedCookieCount2 } } : {}
+      };
+      if (copyCookieDomains.length > 0) persistBrowserRecord(record3);
+      deps.log(`AgentBay browser reused: ${browserId}, host=${record3.pid}`);
+      return {
+        ...browserSummary2(record3, true),
+        created: false,
+        reused: true
+      };
+    }
+    if (reuseMode === "require") {
+      throw new Error(`AgentBay browser is not running and reuse=require: ${browserId}`);
+    }
     const [cookies, userAgent] = await Promise.all([
       copyCookieDomains.length > 0 ? deps.exportCookies(copyCookieDomains) : Promise.resolve([]),
       userAgentMode === "desktop" ? deps.getBrowserUserAgent().then(normalizeDesktopUserAgent) : Promise.resolve(void 0)
     ]);
     const agentBay = await (deps.createAgentBayClient ?? createClient)(apiKey);
     context = persistent ? await resolvePersistentContext(agentBay, browserId) : void 0;
+    const { LifecyclePolicy } = await loadSdk();
     const created = await agentBay.create({
       imageId,
       framework: "mearl",
+      lifecyclePolicy: new LifecyclePolicy(lifecycle),
       ...context ? {
         browserContext: {
           contextId: context.id,
@@ -9780,7 +10235,8 @@ async function launchAgentBayBrowser(input, deps) {
     }
     session = created.session;
     const copiedCookieCount = await initializeAgentBayBrowserSession(session, input, cookies, {
-      userAgent
+      userAgent,
+      connectCdp: deps.connectCdp
     });
     const host = spawn4(
       process.execPath,
@@ -9792,7 +10248,9 @@ async function launchAgentBayBrowser(input, deps) {
         "--browser-id",
         browserId,
         "--browser-name",
-        name
+        name,
+        "--agentbay-idle-release-minutes",
+        String(lifecycle.idleReleaseTimeout)
       ],
       {
         detached: true,
@@ -9813,6 +10271,7 @@ async function launchAgentBayBrowser(input, deps) {
       name,
       sessionId: session.sessionId,
       imageId,
+      userAgentMode,
       persistent,
       ...context ? { contextId: context.id, contextName: context.name } : {},
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -9822,7 +10281,11 @@ async function launchAgentBayBrowser(input, deps) {
     recordWritten = true;
     await waitForBrowserRegistration(browserId, hostPid);
     deps.log(`AgentBay browser launched: ${browserId}, host=${hostPid}`);
-    return browserSummary2(record2, true);
+    return {
+      ...browserSummary2(record2, true),
+      created: true,
+      reused: false
+    };
   } catch (error48) {
     if (hostPid) await stopProcess(hostPid, `--browser-id ${browserId}`);
     if (recordWritten) {
@@ -9846,6 +10309,7 @@ async function launchAgentBayBrowser(input, deps) {
           name,
           sessionId: session.sessionId,
           imageId,
+          userAgentMode,
           persistent,
           ...context ? { contextId: context.id, contextName: context.name } : {},
           createdAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -9940,31 +10404,38 @@ async function releaseAgentBayBrowserResources(record2, agentBay, options = {})
   };
 }
 async function closeAgentBayBrowser(selector, options = {}) {
-  const record2 = findRecord(selector);
+  let record2 = findRecord(selector);
   if (!record2) throw new Error(`AgentBay browser not found: ${selector}`);
   const agentBay = await createClient(resolveAgentBayApiKey());
-  const released = await releaseAgentBayBrowserResources(record2, agentBay, {
-    ...options,
-    persistRecord: (updatedRecord) => writeRecord(
-      keyedConfigFile(AGENTBAY_BROWSERS_SUBDIR, updatedRecord.browserId),
-      updatedRecord
-    )
-  });
-  const closingOwnHost = record2.pid === process.pid;
-  if (!closingOwnHost) await stopProcess(record2.pid, `--browser-id ${record2.browserId}`);
-  removeRecord(keyedConfigFile(AGENTBAY_BROWSERS_SUBDIR, record2.browserId));
-  removeRecord(keyedConfigFile("browsers", record2.browserId));
-  if (closingOwnHost) {
-    const timer = setTimeout(() => process.kill(process.pid, "SIGTERM"), 250);
-    timer.unref();
+  const releaseLock = acquireLaunchLock(record2.browserId);
+  try {
+    record2 = findRecord(record2.browserId);
+    if (!record2) throw new Error(`AgentBay browser not found: ${selector}`);
+    const released = await releaseAgentBayBrowserResources(record2, agentBay, {
+      ...options,
+      persistRecord: (updatedRecord) => writeRecord(
+        keyedConfigFile(AGENTBAY_BROWSERS_SUBDIR, updatedRecord.browserId),
+        updatedRecord
+      )
+    });
+    const closingOwnHost = record2.pid === process.pid;
+    if (!closingOwnHost) await stopProcess(record2.pid, `--browser-id ${record2.browserId}`);
+    removeRecord(keyedConfigFile(AGENTBAY_BROWSERS_SUBDIR, record2.browserId));
+    removeRecord(keyedConfigFile("browsers", record2.browserId));
+    if (closingOwnHost) {
+      const timer = setTimeout(() => process.kill(process.pid, "SIGTERM"), 250);
+      timer.unref();
+    }
+    return {
+      browserId: record2.browserId,
+      provider: "agentbay",
+      closed: true,
+      ...released,
+      ...record2.persistent === true ? { profileDeleted: options.deleteProfile === true } : { profileDeleted: true }
+    };
+  } finally {
+    releaseLock();
   }
-  return {
-    browserId: record2.browserId,
-    provider: "agentbay",
-    closed: true,
-    ...released,
-    ...record2.persistent === true ? { profileDeleted: options.deleteProfile === true } : { profileDeleted: true }
-  };
 }
 
 // src/browser-registry.ts
@@ -10163,7 +10634,7 @@ import os2 from "node:os";
 import { randomUUID as randomUUID4 } from "node:crypto";
 
 // src/version.ts
-var NATIVE_HOST_VERSION = true ? "2.6.0" : "unknown";
+var NATIVE_HOST_VERSION = true ? "2.7.0" : "unknown";
 
 // src/analytics.ts
 var MEASUREMENT_ID = "G-W84LJDZ6PH";
@@ -30153,6 +30624,7 @@ var AgentSkillManager = class {
       "--agent",
       providerId,
       scope === "global" ? "--global" : "--project",
+      "--full-depth",
       "--yes"
     ];
     const output = await this.run(executable, args, cwd);
@@ -30229,7 +30701,7 @@ function createExtensionRequestMessage(id, action, data, trustedInternal = false
     id,
     action,
     data,
-    controlSource,
+    controlSource: toControlSourceWireValue(controlSource),
     ...trustedInternal ? { trustedInternal: true } : {}
   };
 }
@@ -30654,9 +31126,22 @@ function positivePort(value, fallback) {
   }
   return port;
 }
+function agentBayIdleReleaseMinutes(value) {
+  if (value === void 0) return void 0;
+  const minutes = Number(value);
+  if (!Number.isInteger(minutes) || minutes < MIN_AGENTBAY_IDLE_RELEASE_MINUTES) {
+    throw new Error(
+      `Invalid --agentbay-idle-release-minutes: ${value}. Expected an integer of at least ${MIN_AGENTBAY_IDLE_RELEASE_MINUTES}.`
+    );
+  }
+  return minutes;
+}
 var CDP_PORT = positivePort(cliOption("--cdp-port"), 9222);
 var CDP_USER_DATA_DIR = cliOption("--cdp-user-data-dir");
 var AGENTBAY_SESSION_ID = cliOption("--agentbay-session-id");
+var AGENTBAY_IDLE_RELEASE_MINUTES = agentBayIdleReleaseMinutes(
+  cliOption("--agentbay-idle-release-minutes")
+);
 var CDP_BROWSER_ID = cliOption("--browser-id") ?? "cdp";
 var CDP_BROWSER_NAME = cliOption("--browser-name") ?? "CDP";
 if (cliArg === "--init" || cliArg === "--uninstall") {
@@ -30684,6 +31169,8 @@ Options:
   --cdp-port <port>          CDP port for daemon mode (default 9222)
   --cdp-user-data-dir <dir>  Read DevToolsActivePort from this Chrome profile
   --agentbay-session-id <id> Connect to an AgentBay browser session over CDP
+  --agentbay-idle-release-minutes <minutes>
+                             Close an idle AgentBay browser (minimum 3 minutes)
   --browser-id <id>          Registry id for this CDP browser
   --browser-name <name>      Human-readable registry name
   --version, -v              Show version
@@ -30808,7 +31295,7 @@ function buildVersionWarning(clientVersion) {
     versionList,
     "",
     "This may cause unexpected behavior. To update:",
-    "  npm install -g @mearl/native-host@latest @mearl/client@latest",
+    "  npx @mearl/setup update --local",
     `  Browser extension: ${EXTENSION_INSTALL_URL}`
   ].join("\n");
 }
@@ -30818,6 +31305,7 @@ var socketServer = null;
 var legacyServer = null;
 var inventoryExitTimer = null;
 var cdpRegistrationTimer = null;
+var agentBaySessionWatchdog = null;
 function scheduleInventoryExit() {
   if (inventoryExitTimer) clearTimeout(inventoryExitTimer);
   inventoryExitTimer = setTimeout(() => cleanupAndExit(0), INVENTORY_IDLE_EXIT_MS);
@@ -31085,7 +31573,7 @@ function toTimeoutMs(action, data) {
   }
   return DEFAULT_TIMEOUT_MS;
 }
-async function handleSocketLine(socket, line) {
+async function handleSocketRequest(socket, line) {
   let request;
   try {
     request = JSON.parse(line);
@@ -31096,7 +31584,7 @@ async function handleSocketLine(socket, line) {
     return;
   }
   const { id = "", action, data = {}, version: clientVersion } = request;
-  const controlSource = request.controlSource === "cloud" ? "cloud" : "local";
+  const controlSource = normalizeControlSource(request.controlSource);
   if (action === "start_cloud_connector") {
     const serverUrl = data?.serverUrl;
     if (!serverUrl || typeof serverUrl !== "string") {
@@ -31386,6 +31874,33 @@ async function handleSocketLine(socket, line) {
     socket.write(JSON.stringify({ id, success: false, error: message }) + "\n");
   }
 }
+async function handleSocketLine(socket, line) {
+  const watchdog = agentBaySessionWatchdog;
+  if (!watchdog) {
+    await handleSocketRequest(socket, line);
+    return;
+  }
+  if (!watchdog.beginActivity()) {
+    let id = "";
+    try {
+      id = JSON.parse(line)?.id ?? "";
+    } catch {
+    }
+    socket.write(
+      JSON.stringify({
+        id,
+        success: false,
+        error: "AgentBay browser is closing after reaching its idle timeout"
+      }) + "\n"
+    );
+    return;
+  }
+  try {
+    await handleSocketRequest(socket, line);
+  } finally {
+    watchdog.endActivity();
+  }
+}
 async function handleViaCdp(action, data, _timeoutMs, controlSource) {
   if (action === "set_rule" || action === "get_rules") {
     throw new Error(
@@ -31544,6 +32059,8 @@ function cleanupAndExit(code) {
     clearInterval(cdpRegistrationTimer);
     cdpRegistrationTimer = null;
   }
+  agentBaySessionWatchdog?.stop();
+  agentBaySessionWatchdog = null;
   cdpSession?.close();
   agentChatManager?.dispose();
   agentChatManager = null;
@@ -31630,15 +32147,17 @@ async function main() {
     await monitorDaemonBrowser();
   }
   if (AGENTBAY_SESSION_ID) {
-    const keepAliveTimer = setInterval(() => {
-      keepAgentBaySessionAlive(AGENTBAY_SESSION_ID).catch((error48) => {
-        log(
-          `AgentBay keepalive failed for ${AGENTBAY_SESSION_ID}:`,
-          error48 instanceof Error ? error48.message : String(error48)
-        );
-      });
-    }, 6e4);
-    keepAliveTimer.unref();
+    const idleReleaseMinutes = AGENTBAY_IDLE_RELEASE_MINUTES ?? resolveAgentBayLifecycleConfig().idleReleaseTimeout;
+    agentBaySessionWatchdog = new AgentBaySessionWatchdog({
+      idleTimeoutMs: idleReleaseMinutes * 6e4,
+      keepAlive: () => keepAgentBaySessionAlive(AGENTBAY_SESSION_ID),
+      close: async () => {
+        await closeAgentBayBrowser(CDP_BROWSER_ID);
+      },
+      log
+    });
+    agentBaySessionWatchdog.start();
+    log(`AgentBay idle close enabled for ${AGENTBAY_SESSION_ID}: ${idleReleaseMinutes} minutes`);
   }
   process.on("SIGINT", () => cleanupAndExit(0));
   process.on("SIGTERM", () => cleanupAndExit(0));

package/dist/internal-extension-actions.d.ts

@@ -1,8 +1,9 @@
+import { type ControlSource, type ControlSourceWireValue } from '@mearl/browser-core';
 export declare function isInternalExtensionAction(action: unknown): boolean;
-export declare function createExtensionRequestMessage(id: string, action: string, data: any, trustedInternal?: boolean, controlSource?: 'local' | 'cloud'): {
+export declare function createExtensionRequestMessage(id: string, action: string, data: any, trustedInternal?: boolean, controlSource?: ControlSource): {
     id: string;
     action: string;
     data: any;
-    controlSource: 'local' | 'cloud';
+    controlSource: ControlSourceWireValue;
     trustedInternal?: true;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/native-host",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Native Messaging Host for Mearl — bridges Chrome Extension and local socket server",
   "type": "module",
   "main": "dist/install.js",
@@ -37,9 +37,9 @@
     "@types/ws": "^8.18.1",
     "esbuild": "^0.25.2",
     "typescript": "^5.8.3",
-    "@mearl/browser-core": "2.6.0",
-    "@mearl/daemon-core": "2.6.0",
-    "@mearl/setup": "2.6.0"
+    "@mearl/browser-core": "2.7.0",
+    "@mearl/daemon-core": "2.7.0",
+    "@mearl/setup": "2.7.0"
   },
   "scripts": {
     "build": "rm -rf dist/ && node build.mjs",