@alfe.ai/openclaw-remote 0.0.19 → 0.1.0

package/README.md

@@ -40,6 +40,27 @@ Validation failures deliberately safe for the model are returned as structured
 tool errors. Unexpected browser, relay, and API diagnostics are redacted.
 Screenshots use OpenClaw image content and keep base64 out of JSON details.
 
+## Trusted local adapters
+
+The root library exports two helpers for plugins in the same OpenClaw process:
+
+- `withRemoteBrowserOperation(callback, { signal? })` invokes the callback with
+  `{ browserWSEndpoint, targetId, signal }` under the existing automation queue.
+  Connect to that exact target; reuse its profile and authenticated page.
+  Disconnect the attachment and await child exit before the callback settles,
+  including when aborted. Never close the owned Chrome or expose its endpoint.
+- `requestRemoteBrowserTakeover({ instructions, conversationId?, timeout?, signal? })`
+  uses the existing takeover session and waits for hand-back. `timeout` is in
+  milliseconds. Tell the user to open the Browser tab before invoking; provide
+  `conversationId` to deliver the chat card during the wait. Its result includes
+  `sessionId`, optional `controlUrl`, `released`, `timedOut`, `url`, and `title`.
+
+Finish an operation before requesting takeover, then acquire a fresh operation
+after hand-back. Nested operations/handoffs deadlock on the shared queue.
+These helpers never launch a second runtime; an absent or outdated owner needs
+the remote plugin started or updated/restarted. A CDP adapter is trusted code,
+not a target-isolated sandbox. Its consuming tools must redact raw failures.
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -9,3 +9,5 @@ exports.createRemotePluginRuntimeState = require_runtime.createRemotePluginRunti
 exports.deriveDashboardBaseUrl = require_runtime.deriveDashboardBaseUrl;
 exports.deriveRemoteWsUrl = require_runtime.deriveRemoteWsUrl;
 exports.parseRemotePluginConfig = require_runtime.parseRemotePluginConfig;
+exports.requestRemoteBrowserTakeover = require_runtime.requestRemoteBrowserTakeover;
+exports.withRemoteBrowserOperation = require_runtime.withRemoteBrowserOperation;

package/dist/index.d.cts

@@ -89,6 +89,18 @@ interface Logger$2 {
 //#endregion
 //#endregion
 //#region src/types.d.ts
+/** Private local capability for a trusted adapter, never a tool result. */
+interface BrowserOperationContext {
+  /** Loopback Chrome endpoint. Do not log, persist, or expose to a viewer/model. */
+  browserWSEndpoint: string;
+  /** The exact active page's CDP target; never choose the first context/page. */
+  targetId: string;
+  /** On abort, stop and await all external work before returning. */
+  signal: AbortSignal;
+}
+interface BrowserOperationOptions {
+  signal?: AbortSignal;
+}
 interface BrowserSessionOptions {
   /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
   executablePath: string;
@@ -284,11 +296,13 @@ interface BrowserSurfaceLike {
     }): Promise<void>;
     screenshot(): Promise<string>;
     evaluate(expression: string): Promise<unknown>;
+    /** Optional only to recognize an older process-global owner during upgrade. */
+    withCdpOperation?<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
   };
   openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
   closeSession(sessionId: number): void;
   handleFrame(frame: RemoteFrame): void;
-  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  requestHandoff(timeoutMs: number, signal?: AbortSignal): Promise<HandoffResult>;
   addHold(): void;
   removeHold(): void;
   shutdown(): Promise<void>;
@@ -330,6 +344,26 @@ interface RemotePluginDependencies {
   runtimeState?: RemotePluginRuntimeState;
 }
 declare function createRemotePluginRuntimeState(): RemotePluginRuntimeState;
+interface RemoteBrowserTakeoverOptions {
+  instructions: string;
+  conversationId?: string;
+  /** Milliseconds, 1000..1800000; defaults to the remote runtime's timeout. */
+  timeout?: number;
+  signal?: AbortSignal;
+}
+interface RemoteBrowserTakeoverResult extends HandoffResult {
+  sessionId: string;
+  controlUrl?: string;
+}
+/** Trusted in-process adapter bridge, not a model-facing endpoint-discovery tool.
+ * The callback owns its CDP attachment/children and MUST await their cleanup
+ * before settling, including on signal abort. Never close Chrome, retain the
+ * endpoint, or call nested browser operations/takeover from this callback. */
+declare function withRemoteBrowserOperation<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
+/** Create the existing takeover request and await human hand-back. Tell the
+ * user to open the agent Browser tab before invoking; the URL returns afterward.
+ * Call between operations, never while holding a withRemoteBrowserOperation. */
+declare function requestRemoteBrowserTakeover(options: RemoteBrowserTakeoverOptions): Promise<RemoteBrowserTakeoverResult>;
 /**
  * Derive the relay WebSocket URL from the agent's cloud apiUrl when the
  * manifest doesn't provide one — mirrors @alfe.ai/console-client's
@@ -397,4 +431,4 @@ declare function buildIsNavigationAllowed(policy: SsrfPolicy | undefined, log?:
   warn(msg: string): void;
 }): (url: string) => boolean;
 //#endregion
-export { type BrowserSurfaceLike, PLUGIN_VERSION, REMOTE_ACTIVATION_KEY, type RemoteApiClient, type RemoteClientLike, type RemotePluginConfig, type RemotePluginDependencies, type RemotePluginRuntimeState, type SsrfPolicy, type TerminalSurfaceLike, buildControlUrl, buildIsNavigationAllowed, createRemotePlugin, createRemotePluginRuntimeState, deriveDashboardBaseUrl, deriveRemoteWsUrl, parseRemotePluginConfig };
+export { type BrowserOperationContext, type BrowserOperationOptions, type BrowserSurfaceLike, PLUGIN_VERSION, REMOTE_ACTIVATION_KEY, type RemoteApiClient, type RemoteBrowserTakeoverOptions, type RemoteBrowserTakeoverResult, type RemoteClientLike, type RemotePluginConfig, type RemotePluginDependencies, type RemotePluginRuntimeState, type SsrfPolicy, type TerminalSurfaceLike, buildControlUrl, buildIsNavigationAllowed, createRemotePlugin, createRemotePluginRuntimeState, deriveDashboardBaseUrl, deriveRemoteWsUrl, parseRemotePluginConfig, requestRemoteBrowserTakeover, withRemoteBrowserOperation };

package/dist/index.d.ts

@@ -89,6 +89,18 @@ interface Logger$2 {
 //#endregion
 //#endregion
 //#region src/types.d.ts
+/** Private local capability for a trusted adapter, never a tool result. */
+interface BrowserOperationContext {
+  /** Loopback Chrome endpoint. Do not log, persist, or expose to a viewer/model. */
+  browserWSEndpoint: string;
+  /** The exact active page's CDP target; never choose the first context/page. */
+  targetId: string;
+  /** On abort, stop and await all external work before returning. */
+  signal: AbortSignal;
+}
+interface BrowserOperationOptions {
+  signal?: AbortSignal;
+}
 interface BrowserSessionOptions {
   /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
   executablePath: string;
@@ -284,11 +296,13 @@ interface BrowserSurfaceLike {
     }): Promise<void>;
     screenshot(): Promise<string>;
     evaluate(expression: string): Promise<unknown>;
+    /** Optional only to recognize an older process-global owner during upgrade. */
+    withCdpOperation?<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
   };
   openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
   closeSession(sessionId: number): void;
   handleFrame(frame: RemoteFrame): void;
-  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  requestHandoff(timeoutMs: number, signal?: AbortSignal): Promise<HandoffResult>;
   addHold(): void;
   removeHold(): void;
   shutdown(): Promise<void>;
@@ -330,6 +344,26 @@ interface RemotePluginDependencies {
   runtimeState?: RemotePluginRuntimeState;
 }
 declare function createRemotePluginRuntimeState(): RemotePluginRuntimeState;
+interface RemoteBrowserTakeoverOptions {
+  instructions: string;
+  conversationId?: string;
+  /** Milliseconds, 1000..1800000; defaults to the remote runtime's timeout. */
+  timeout?: number;
+  signal?: AbortSignal;
+}
+interface RemoteBrowserTakeoverResult extends HandoffResult {
+  sessionId: string;
+  controlUrl?: string;
+}
+/** Trusted in-process adapter bridge, not a model-facing endpoint-discovery tool.
+ * The callback owns its CDP attachment/children and MUST await their cleanup
+ * before settling, including on signal abort. Never close Chrome, retain the
+ * endpoint, or call nested browser operations/takeover from this callback. */
+declare function withRemoteBrowserOperation<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
+/** Create the existing takeover request and await human hand-back. Tell the
+ * user to open the agent Browser tab before invoking; the URL returns afterward.
+ * Call between operations, never while holding a withRemoteBrowserOperation. */
+declare function requestRemoteBrowserTakeover(options: RemoteBrowserTakeoverOptions): Promise<RemoteBrowserTakeoverResult>;
 /**
  * Derive the relay WebSocket URL from the agent's cloud apiUrl when the
  * manifest doesn't provide one — mirrors @alfe.ai/console-client's
@@ -397,4 +431,4 @@ declare function buildIsNavigationAllowed(policy: SsrfPolicy | undefined, log?:
   warn(msg: string): void;
 }): (url: string) => boolean;
 //#endregion
-export { type BrowserSurfaceLike, PLUGIN_VERSION, REMOTE_ACTIVATION_KEY, type RemoteApiClient, type RemoteClientLike, type RemotePluginConfig, type RemotePluginDependencies, type RemotePluginRuntimeState, type SsrfPolicy, type TerminalSurfaceLike, buildControlUrl, buildIsNavigationAllowed, createRemotePlugin, createRemotePluginRuntimeState, deriveDashboardBaseUrl, deriveRemoteWsUrl, parseRemotePluginConfig };
+export { type BrowserOperationContext, type BrowserOperationOptions, type BrowserSurfaceLike, PLUGIN_VERSION, REMOTE_ACTIVATION_KEY, type RemoteApiClient, type RemoteBrowserTakeoverOptions, type RemoteBrowserTakeoverResult, type RemoteClientLike, type RemotePluginConfig, type RemotePluginDependencies, type RemotePluginRuntimeState, type SsrfPolicy, type TerminalSurfaceLike, buildControlUrl, buildIsNavigationAllowed, createRemotePlugin, createRemotePluginRuntimeState, deriveDashboardBaseUrl, deriveRemoteWsUrl, parseRemotePluginConfig, requestRemoteBrowserTakeover, withRemoteBrowserOperation };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as createRemotePluginRuntimeState, c as parseRemotePluginConfig, i as createRemotePlugin, l as buildIsNavigationAllowed, n as REMOTE_ACTIVATION_KEY, o as deriveDashboardBaseUrl, r as buildControlUrl, s as deriveRemoteWsUrl, t as PLUGIN_VERSION } from "./runtime.js";
-export { PLUGIN_VERSION, REMOTE_ACTIVATION_KEY, buildControlUrl, buildIsNavigationAllowed, createRemotePlugin, createRemotePluginRuntimeState, deriveDashboardBaseUrl, deriveRemoteWsUrl, parseRemotePluginConfig };
+import { a as createRemotePluginRuntimeState, c as parseRemotePluginConfig, d as buildIsNavigationAllowed, i as createRemotePlugin, l as requestRemoteBrowserTakeover, n as REMOTE_ACTIVATION_KEY, o as deriveDashboardBaseUrl, r as buildControlUrl, s as deriveRemoteWsUrl, t as PLUGIN_VERSION, u as withRemoteBrowserOperation } from "./runtime.js";
+export { PLUGIN_VERSION, REMOTE_ACTIVATION_KEY, buildControlUrl, buildIsNavigationAllowed, createRemotePlugin, createRemotePluginRuntimeState, deriveDashboardBaseUrl, deriveRemoteWsUrl, parseRemotePluginConfig, requestRemoteBrowserTakeover, withRemoteBrowserOperation };

package/dist/runtime.cjs

@@ -148,6 +148,70 @@ function createRemotePluginRuntimeState() {
 		stopPromise: null
 	};
 }
+/** Trusted in-process adapter bridge, not a model-facing endpoint-discovery tool.
+* The callback owns its CDP attachment/children and MUST await their cleanup
+* before settling, including on signal abort. Never close Chrome, retain the
+* endpoint, or call nested browser operations/takeover from this callback. */
+async function withRemoteBrowserOperation(operation, options = {}) {
+	const state = requireGlobalRuntimeState();
+	const surface = requireBrowserSurface(state);
+	const generation = state.generation;
+	if (!surface.automation.withCdpOperation) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Shared browser adapter support is unavailable; update and restart the remote plugin.");
+	const assertCurrent = () => {
+		if (state.generation !== generation || state.browserSurface !== surface || state.stopPromise !== null) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Remote browser restarted during the operation; retry after it reconnects.");
+	};
+	const result = await surface.automation.withCdpOperation(async (context) => {
+		assertCurrent();
+		const value = await operation(context);
+		assertCurrent();
+		return value;
+	}, options);
+	assertCurrent();
+	return result;
+}
+/** Create the existing takeover request and await human hand-back. Tell the
+* user to open the agent Browser tab before invoking; the URL returns afterward.
+* Call between operations, never while holding a withRemoteBrowserOperation. */
+async function requestRemoteBrowserTakeover(options) {
+	return requestBrowserTakeover(requireGlobalRuntimeState(), options);
+}
+function requireBrowserSurface(state) {
+	if (!state.browserSurface || state.stopPromise !== null) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Browser surface is unavailable; retry after the remote service connects.");
+	return state.browserSurface;
+}
+async function requestBrowserTakeover(state, options) {
+	const surface = requireBrowserSurface(state);
+	const client = state.apiClient;
+	if (!client) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Remote service is unavailable; retry after it connects.");
+	if (options.signal && !surface.automation.withCdpOperation) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Cancellable browser takeover is unavailable; update and restart the remote plugin.");
+	options.signal?.throwIfAborted();
+	const generation = state.generation;
+	const instructions = requireString(options.instructions, "instructions", MAX_INSTRUCTIONS_CHARS);
+	const conversationId = optionalString(options.conversationId, "conversationId", MAX_CONVERSATION_ID_CHARS);
+	const url = options.url === void 0 ? void 0 : requireHttpUrl(options.url, "url", 2048);
+	const timeout = optionalInteger(options.timeout, "timeout", 1e3, 1800 * 1e3) ?? state.handoffTimeoutMs;
+	let sessionId;
+	surface.addHold();
+	try {
+		sessionId = requireTrustedString((await client.requestBrowserTakeover({
+			instructions,
+			url,
+			conversationId
+		})).sessionId, "remote session ID", MAX_SESSION_ID_CHARS);
+		options.signal?.throwIfAborted();
+		if (state.generation !== generation || state.browserSurface !== surface || state.apiClient !== client || state.stopPromise !== null) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Remote browser restarted while creating the takeover; retry the request.");
+		const controlUrl = buildControlUrl(state.dashboardBaseUrl, state.selfAgentId, sessionId);
+		const result = options.signal ? await surface.requestHandoff(timeout, options.signal) : await surface.requestHandoff(timeout);
+		return {
+			sessionId,
+			controlUrl,
+			...result
+		};
+	} finally {
+		surface.removeHold();
+		if (sessionId) await client.completeRemoteSession(sessionId).catch(() => void 0);
+	}
+}
 /**
 * Derive the relay WebSocket URL from the agent's cloud apiUrl when the
 * manifest doesn't provide one — mirrors @alfe.ai/console-client's
@@ -208,16 +272,28 @@ function dispatchFrame(state, frame, log) {
 		const handler = open.surface === "terminal" ? state.terminalSurface : state.browserSurface;
 		if (!handler) {
 			log.warn("Remote session surface is unavailable");
+			closeUnavailableSession(state.remoteClient, frame.sessionId, log);
 			return;
 		}
+		const client = state.remoteClient;
+		const generation = state.generation;
+		const sessions = state.sessionSurfaces;
 		state.sessionSurfaces.set(frame.sessionId, open.surface);
-		Promise.resolve(handler.openSession(frame.sessionId, open)).catch(() => {
-			if (state.sessionSurfaces.get(frame.sessionId) === open.surface) state.sessionSurfaces.delete(frame.sessionId);
-			try {
-				handler.closeSession(frame.sessionId);
-			} catch {}
+		const failOpen = () => {
+			if (state.generation === generation && state.remoteClient === client && state.sessionSurfaces === sessions && state.sessionSurfaces.get(frame.sessionId) === open.surface) {
+				state.sessionSurfaces.delete(frame.sessionId);
+				try {
+					handler.closeSession(frame.sessionId);
+				} catch {}
+				closeUnavailableSession(client, frame.sessionId, log);
+			}
 			log.warn("Remote session could not be opened");
-		});
+		};
+		try {
+			Promise.resolve(handler.openSession(frame.sessionId, open)).catch(failOpen);
+		} catch {
+			failOpen();
+		}
 		return;
 	}
 	const surface = state.sessionSurfaces.get(frame.sessionId);
@@ -238,6 +314,13 @@ function dispatchFrame(state, frame, log) {
 		log.warn("Remote session frame handling failed");
 	}
 }
+function closeUnavailableSession(client, sessionId, log) {
+	try {
+		client?.sendFrame((0, _alfe_ai_remote.encodeJsonFrame)(_alfe_ai_remote.RemoteFrameType.SESSION_CLOSE, sessionId, { reason: "surface_unavailable" }));
+	} catch {
+		log.warn("Could not close unavailable remote session");
+	}
+}
 function startService(pluginConfig, ssrfPolicy, workspaceDir, log, dependencies, state) {
 	(0, _alfe_ai_openclaw_plugin_kit.guardedStart)(REMOTE_ACTIVATION_KEY, log, () => {
 		if (pluginConfig === null) {
@@ -377,12 +460,10 @@ function closeAllSessions(state, log) {
 		}
 	}
 	state.sessionSurfaces.clear();
+	state.sessionSurfaces = /* @__PURE__ */ new Map();
 }
 function registerTools(api, state) {
-	const needBrowser = () => {
-		if (!state.browserSurface) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Browser surface is unavailable; retry after the remote service connects.");
-		return state.browserSurface;
-	};
+	const needBrowser = () => requireBrowserSurface(state);
 	api.registerTool(remoteTool({
 		name: "browser_navigate",
 		description: "Navigate the shared browser to a URL. Returns the final URL and page title.",
@@ -527,7 +608,7 @@ function registerTools(api, state) {
 	}));
 	api.registerTool(remoteTool({
 		name: "request_browser_takeover",
-		description: "Ask a human to take over the live browser for a manual step. Share the returned control URL with the user, then wait for the hand-back.",
+		description: "Ask a human to take over the live shared browser for a manual step. Tell the user to open this agent's Browser tab before calling: this tool waits until hand-back or timeout, so its returned URL arrives afterward. Supply the current conversationId when available to show the takeover card in chat. The optional URL is context only; navigate the browser before requesting takeover.",
 		parameters: {
 			type: "object",
 			properties: {
@@ -553,36 +634,16 @@ function registerTools(api, state) {
 			additionalProperties: false
 		},
 		handler: async (params) => {
-			const surface = needBrowser();
-			const client = state.apiClient;
-			if (!client) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Remote service is unavailable; retry after it connects.");
-			const generation = state.generation;
-			const instructions = requireString(params.instructions, "instructions", MAX_INSTRUCTIONS_CHARS);
-			const url = params.url === void 0 ? void 0 : requireHttpUrl(params.url, "url", 2048);
-			const conversationId = optionalString(params.conversationId, "conversationId", MAX_CONVERSATION_ID_CHARS);
-			const sessionId = requireTrustedString((await client.requestBrowserTakeover({
-				instructions,
-				url,
-				conversationId
-			})).sessionId, "remote session ID", MAX_SESSION_ID_CHARS);
-			if (state.generation !== generation || state.browserSurface !== surface || state.apiClient !== client) {
-				await client.completeRemoteSession(sessionId).catch(() => void 0);
-				throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Remote browser restarted while creating the takeover; retry the request.");
-			}
-			const controlUrl = buildControlUrl(state.dashboardBaseUrl, state.selfAgentId, sessionId);
-			const message = controlUrl ? `Browser takeover requested (session ${sessionId}). Ask the user to open ${controlUrl}, complete the task, and hand control back.` : `Browser takeover requested (session ${sessionId}). Ask the user to open this agent's Browser tab in the Alfe dashboard, complete the task, and hand control back.`;
-			surface.addHold();
-			try {
-				return {
-					sessionId,
-					controlUrl,
-					message,
-					...await surface.requestHandoff(state.handoffTimeoutMs)
-				};
-			} finally {
-				surface.removeHold();
-				await client.completeRemoteSession(sessionId).catch(() => void 0);
-			}
+			const result = await requestBrowserTakeover(state, {
+				instructions: requireString(params.instructions, "instructions", MAX_INSTRUCTIONS_CHARS),
+				url: params.url === void 0 ? void 0 : requireHttpUrl(params.url, "url", 2048),
+				conversationId: optionalString(params.conversationId, "conversationId", MAX_CONVERSATION_ID_CHARS)
+			});
+			const message = result.timedOut ? "Browser takeover timed out. Request a new takeover if the user still needs to complete the task." : "Browser control returned to the agent. Continue on the existing page and check whether the user completed the task.";
+			return {
+				...result,
+				message
+			};
 		}
 	}));
 }
@@ -748,6 +809,11 @@ function getGlobalRuntimeState() {
 	root[RUNTIME_STATE_KEY] = state;
 	return state;
 }
+function requireGlobalRuntimeState() {
+	const existing = globalThis[RUNTIME_STATE_KEY];
+	if (!isRuntimeState(existing)) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Shared browser runtime is unavailable; start or update and restart the remote plugin.");
+	return existing;
+}
 function isRuntimeState(value) {
 	if (!isRecord(value)) return false;
 	return typeof value.generation === "number" && Number.isSafeInteger(value.generation) && value.generation >= 0 && typeof value.handoffTimeoutMs === "number" && Number.isInteger(value.handoffTimeoutMs) && value.handoffTimeoutMs >= 1e3 && value.handoffTimeoutMs <= 1800 * 1e3 && value.sessionSurfaces instanceof Map && (value.stopPromise === null || value.stopPromise instanceof Promise) && (value.remoteClient === null || isRemoteClient(value.remoteClient)) && (value.browserSurface === null || isBrowserSurface(value.browserSurface)) && (value.terminalSurface === null || isTerminalSurface(value.terminalSurface)) && (value.apiClient === null || isRemoteApiClient(value.apiClient));
@@ -840,3 +906,15 @@ Object.defineProperty(exports, "parseRemotePluginConfig", {
 		return parseRemotePluginConfig;
 	}
 });
+Object.defineProperty(exports, "requestRemoteBrowserTakeover", {
+	enumerable: true,
+	get: function() {
+		return requestRemoteBrowserTakeover;
+	}
+});
+Object.defineProperty(exports, "withRemoteBrowserOperation", {
+	enumerable: true,
+	get: function() {
+		return withRemoteBrowserOperation;
+	}
+});

package/dist/runtime.js

@@ -4,7 +4,7 @@ import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-clie
 import { BrowserSurface } from "@alfe.ai/browser";
 import { resolveConfig } from "@alfe.ai/config";
 import { PublicToolError, defineTool, errResult, getActivationKey, guardedStart, publicToolError, resetActivation } from "@alfe.ai/openclaw-plugin-kit";
-import { RemoteFrameType, RemoteServiceClient, decodeSessionOpenPayload } from "@alfe.ai/remote";
+import { RemoteFrameType, RemoteServiceClient, decodeSessionOpenPayload, encodeJsonFrame } from "@alfe.ai/remote";
 import { TerminalSurface } from "@alfe.ai/terminal";
 //#region src/ssrf.ts
 /** Hostnames blocked outright (case-insensitive, exact match). */
@@ -148,6 +148,70 @@ function createRemotePluginRuntimeState() {
 		stopPromise: null
 	};
 }
+/** Trusted in-process adapter bridge, not a model-facing endpoint-discovery tool.
+* The callback owns its CDP attachment/children and MUST await their cleanup
+* before settling, including on signal abort. Never close Chrome, retain the
+* endpoint, or call nested browser operations/takeover from this callback. */
+async function withRemoteBrowserOperation(operation, options = {}) {
+	const state = requireGlobalRuntimeState();
+	const surface = requireBrowserSurface(state);
+	const generation = state.generation;
+	if (!surface.automation.withCdpOperation) throw publicToolError("Shared browser adapter support is unavailable; update and restart the remote plugin.");
+	const assertCurrent = () => {
+		if (state.generation !== generation || state.browserSurface !== surface || state.stopPromise !== null) throw publicToolError("Remote browser restarted during the operation; retry after it reconnects.");
+	};
+	const result = await surface.automation.withCdpOperation(async (context) => {
+		assertCurrent();
+		const value = await operation(context);
+		assertCurrent();
+		return value;
+	}, options);
+	assertCurrent();
+	return result;
+}
+/** Create the existing takeover request and await human hand-back. Tell the
+* user to open the agent Browser tab before invoking; the URL returns afterward.
+* Call between operations, never while holding a withRemoteBrowserOperation. */
+async function requestRemoteBrowserTakeover(options) {
+	return requestBrowserTakeover(requireGlobalRuntimeState(), options);
+}
+function requireBrowserSurface(state) {
+	if (!state.browserSurface || state.stopPromise !== null) throw publicToolError("Browser surface is unavailable; retry after the remote service connects.");
+	return state.browserSurface;
+}
+async function requestBrowserTakeover(state, options) {
+	const surface = requireBrowserSurface(state);
+	const client = state.apiClient;
+	if (!client) throw publicToolError("Remote service is unavailable; retry after it connects.");
+	if (options.signal && !surface.automation.withCdpOperation) throw publicToolError("Cancellable browser takeover is unavailable; update and restart the remote plugin.");
+	options.signal?.throwIfAborted();
+	const generation = state.generation;
+	const instructions = requireString(options.instructions, "instructions", MAX_INSTRUCTIONS_CHARS);
+	const conversationId = optionalString(options.conversationId, "conversationId", MAX_CONVERSATION_ID_CHARS);
+	const url = options.url === void 0 ? void 0 : requireHttpUrl(options.url, "url", 2048);
+	const timeout = optionalInteger(options.timeout, "timeout", 1e3, 1800 * 1e3) ?? state.handoffTimeoutMs;
+	let sessionId;
+	surface.addHold();
+	try {
+		sessionId = requireTrustedString((await client.requestBrowserTakeover({
+			instructions,
+			url,
+			conversationId
+		})).sessionId, "remote session ID", MAX_SESSION_ID_CHARS);
+		options.signal?.throwIfAborted();
+		if (state.generation !== generation || state.browserSurface !== surface || state.apiClient !== client || state.stopPromise !== null) throw publicToolError("Remote browser restarted while creating the takeover; retry the request.");
+		const controlUrl = buildControlUrl(state.dashboardBaseUrl, state.selfAgentId, sessionId);
+		const result = options.signal ? await surface.requestHandoff(timeout, options.signal) : await surface.requestHandoff(timeout);
+		return {
+			sessionId,
+			controlUrl,
+			...result
+		};
+	} finally {
+		surface.removeHold();
+		if (sessionId) await client.completeRemoteSession(sessionId).catch(() => void 0);
+	}
+}
 /**
 * Derive the relay WebSocket URL from the agent's cloud apiUrl when the
 * manifest doesn't provide one — mirrors @alfe.ai/console-client's
@@ -208,16 +272,28 @@ function dispatchFrame(state, frame, log) {
 		const handler = open.surface === "terminal" ? state.terminalSurface : state.browserSurface;
 		if (!handler) {
 			log.warn("Remote session surface is unavailable");
+			closeUnavailableSession(state.remoteClient, frame.sessionId, log);
 			return;
 		}
+		const client = state.remoteClient;
+		const generation = state.generation;
+		const sessions = state.sessionSurfaces;
 		state.sessionSurfaces.set(frame.sessionId, open.surface);
-		Promise.resolve(handler.openSession(frame.sessionId, open)).catch(() => {
-			if (state.sessionSurfaces.get(frame.sessionId) === open.surface) state.sessionSurfaces.delete(frame.sessionId);
-			try {
-				handler.closeSession(frame.sessionId);
-			} catch {}
+		const failOpen = () => {
+			if (state.generation === generation && state.remoteClient === client && state.sessionSurfaces === sessions && state.sessionSurfaces.get(frame.sessionId) === open.surface) {
+				state.sessionSurfaces.delete(frame.sessionId);
+				try {
+					handler.closeSession(frame.sessionId);
+				} catch {}
+				closeUnavailableSession(client, frame.sessionId, log);
+			}
 			log.warn("Remote session could not be opened");
-		});
+		};
+		try {
+			Promise.resolve(handler.openSession(frame.sessionId, open)).catch(failOpen);
+		} catch {
+			failOpen();
+		}
 		return;
 	}
 	const surface = state.sessionSurfaces.get(frame.sessionId);
@@ -238,6 +314,13 @@ function dispatchFrame(state, frame, log) {
 		log.warn("Remote session frame handling failed");
 	}
 }
+function closeUnavailableSession(client, sessionId, log) {
+	try {
+		client?.sendFrame(encodeJsonFrame(RemoteFrameType.SESSION_CLOSE, sessionId, { reason: "surface_unavailable" }));
+	} catch {
+		log.warn("Could not close unavailable remote session");
+	}
+}
 function startService(pluginConfig, ssrfPolicy, workspaceDir, log, dependencies, state) {
 	guardedStart(REMOTE_ACTIVATION_KEY, log, () => {
 		if (pluginConfig === null) {
@@ -377,12 +460,10 @@ function closeAllSessions(state, log) {
 		}
 	}
 	state.sessionSurfaces.clear();
+	state.sessionSurfaces = /* @__PURE__ */ new Map();
 }
 function registerTools(api, state) {
-	const needBrowser = () => {
-		if (!state.browserSurface) throw publicToolError("Browser surface is unavailable; retry after the remote service connects.");
-		return state.browserSurface;
-	};
+	const needBrowser = () => requireBrowserSurface(state);
 	api.registerTool(remoteTool({
 		name: "browser_navigate",
 		description: "Navigate the shared browser to a URL. Returns the final URL and page title.",
@@ -527,7 +608,7 @@ function registerTools(api, state) {
 	}));
 	api.registerTool(remoteTool({
 		name: "request_browser_takeover",
-		description: "Ask a human to take over the live browser for a manual step. Share the returned control URL with the user, then wait for the hand-back.",
+		description: "Ask a human to take over the live shared browser for a manual step. Tell the user to open this agent's Browser tab before calling: this tool waits until hand-back or timeout, so its returned URL arrives afterward. Supply the current conversationId when available to show the takeover card in chat. The optional URL is context only; navigate the browser before requesting takeover.",
 		parameters: {
 			type: "object",
 			properties: {
@@ -553,36 +634,16 @@ function registerTools(api, state) {
 			additionalProperties: false
 		},
 		handler: async (params) => {
-			const surface = needBrowser();
-			const client = state.apiClient;
-			if (!client) throw publicToolError("Remote service is unavailable; retry after it connects.");
-			const generation = state.generation;
-			const instructions = requireString(params.instructions, "instructions", MAX_INSTRUCTIONS_CHARS);
-			const url = params.url === void 0 ? void 0 : requireHttpUrl(params.url, "url", 2048);
-			const conversationId = optionalString(params.conversationId, "conversationId", MAX_CONVERSATION_ID_CHARS);
-			const sessionId = requireTrustedString((await client.requestBrowserTakeover({
-				instructions,
-				url,
-				conversationId
-			})).sessionId, "remote session ID", MAX_SESSION_ID_CHARS);
-			if (state.generation !== generation || state.browserSurface !== surface || state.apiClient !== client) {
-				await client.completeRemoteSession(sessionId).catch(() => void 0);
-				throw publicToolError("Remote browser restarted while creating the takeover; retry the request.");
-			}
-			const controlUrl = buildControlUrl(state.dashboardBaseUrl, state.selfAgentId, sessionId);
-			const message = controlUrl ? `Browser takeover requested (session ${sessionId}). Ask the user to open ${controlUrl}, complete the task, and hand control back.` : `Browser takeover requested (session ${sessionId}). Ask the user to open this agent's Browser tab in the Alfe dashboard, complete the task, and hand control back.`;
-			surface.addHold();
-			try {
-				return {
-					sessionId,
-					controlUrl,
-					message,
-					...await surface.requestHandoff(state.handoffTimeoutMs)
-				};
-			} finally {
-				surface.removeHold();
-				await client.completeRemoteSession(sessionId).catch(() => void 0);
-			}
+			const result = await requestBrowserTakeover(state, {
+				instructions: requireString(params.instructions, "instructions", MAX_INSTRUCTIONS_CHARS),
+				url: params.url === void 0 ? void 0 : requireHttpUrl(params.url, "url", 2048),
+				conversationId: optionalString(params.conversationId, "conversationId", MAX_CONVERSATION_ID_CHARS)
+			});
+			const message = result.timedOut ? "Browser takeover timed out. Request a new takeover if the user still needs to complete the task." : "Browser control returned to the agent. Continue on the existing page and check whether the user completed the task.";
+			return {
+				...result,
+				message
+			};
 		}
 	}));
 }
@@ -748,6 +809,11 @@ function getGlobalRuntimeState() {
 	root[RUNTIME_STATE_KEY] = state;
 	return state;
 }
+function requireGlobalRuntimeState() {
+	const existing = globalThis[RUNTIME_STATE_KEY];
+	if (!isRuntimeState(existing)) throw publicToolError("Shared browser runtime is unavailable; start or update and restart the remote plugin.");
+	return existing;
+}
 function isRuntimeState(value) {
 	if (!isRecord(value)) return false;
 	return typeof value.generation === "number" && Number.isSafeInteger(value.generation) && value.generation >= 0 && typeof value.handoffTimeoutMs === "number" && Number.isInteger(value.handoffTimeoutMs) && value.handoffTimeoutMs >= 1e3 && value.handoffTimeoutMs <= 1800 * 1e3 && value.sessionSurfaces instanceof Map && (value.stopPromise === null || value.stopPromise instanceof Promise) && (value.remoteClient === null || isRemoteClient(value.remoteClient)) && (value.browserSurface === null || isBrowserSurface(value.browserSurface)) && (value.terminalSurface === null || isTerminalSurface(value.terminalSurface)) && (value.apiClient === null || isRemoteApiClient(value.apiClient));
@@ -786,4 +852,4 @@ function validatePackageVersion(value) {
 	return value;
 }
 //#endregion
-export { createRemotePluginRuntimeState as a, parseRemotePluginConfig as c, createRemotePlugin as i, buildIsNavigationAllowed as l, REMOTE_ACTIVATION_KEY as n, deriveDashboardBaseUrl as o, buildControlUrl as r, deriveRemoteWsUrl as s, PLUGIN_VERSION as t };
+export { createRemotePluginRuntimeState as a, parseRemotePluginConfig as c, buildIsNavigationAllowed as d, createRemotePlugin as i, requestRemoteBrowserTakeover as l, REMOTE_ACTIVATION_KEY as n, deriveDashboardBaseUrl as o, buildControlUrl as r, deriveRemoteWsUrl as s, PLUGIN_VERSION as t, withRemoteBrowserOperation as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/openclaw-remote",
-  "version": "0.0.19",
+  "version": "0.1.0",
   "description": "OpenClaw plugin for Alfe's interactive remote-control relay — browser co-browse + web terminal surfaces over one outbound WS",
   "type": "module",
   "main": "./dist/plugin.js",
@@ -28,12 +28,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@alfe.ai/agent-api-client": "^0.18.0",
+    "@alfe.ai/agent-api-client": "^0.19.0",
     "@alfe.ai/openclaw-plugin-kit": "0.2.0",
-    "@alfe.ai/browser": "^0.2.1",
+    "@alfe.ai/browser": "^0.3.0",
     "@alfe.ai/config": "0.4.1",
-    "@alfe.ai/remote": "^0.1.1",
-    "@alfe.ai/terminal": "^0.1.3"
+    "@alfe.ai/remote": "^0.2.0",
+    "@alfe.ai/terminal": "^0.1.4"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.0"