@alfe.ai/openclaw-remote 0.0.15 → 0.0.16

package/dist/runtime.js

@@ -0,0 +1,789 @@
+import { createRequire } from "node:module";
+import { isAbsolute, join } from "node:path";
+import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
+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 { TerminalSurface } from "@alfe.ai/terminal";
+//#region src/ssrf.ts
+/** Hostnames blocked outright (case-insensitive, exact match). */
+const BLOCKED_HOSTNAMES = new Set(["localhost"]);
+/** Hostname suffixes blocked outright (internal service discovery names). */
+const BLOCKED_HOST_SUFFIXES = [".internal", ".local"];
+/** Parse a dotted-quad IPv4 literal into its four octets, or null. */
+function parseIpv4(host) {
+	const parts = host.split(".");
+	if (parts.length !== 4) return null;
+	const octets = [];
+	for (const part of parts) {
+		if (!/^\d{1,3}$/.test(part)) return null;
+		const n = Number(part);
+		if (n > 255) return null;
+		octets.push(n);
+	}
+	return octets;
+}
+/** Is this IPv4 literal private, loopback, link-local, or otherwise reserved? */
+function isPrivateOrReservedIpv4(host) {
+	const octets = parseIpv4(host);
+	if (!octets) return false;
+	const [a, b] = octets;
+	if (a === 0) return true;
+	if (a === 10) return true;
+	if (a === 127) return true;
+	if (a === 169 && b === 254) return true;
+	if (a === 172 && b >= 16 && b <= 31) return true;
+	if (a === 192 && b === 0 && octets[2] === 0) return true;
+	if (a === 192 && b === 0 && octets[2] === 2) return true;
+	if (a === 192 && b === 168) return true;
+	if (a === 192 && b === 88 && octets[2] === 99) return true;
+	if (a === 100 && b >= 64 && b <= 127) return true;
+	if (a === 198 && (b === 18 || b === 19)) return true;
+	if (a === 198 && b === 51 && octets[2] === 100) return true;
+	if (a === 203 && b === 0 && octets[2] === 113) return true;
+	if (a >= 224) return true;
+	return false;
+}
+/** Is this IPv6 literal (brackets already stripped) loopback/private/link-local? */
+function isPrivateOrReservedIpv6(host) {
+	const h = host.toLowerCase();
+	if (h === "::1" || h === "::") return true;
+	const mapped = /^::ffff:(.+)$/.exec(h);
+	if (mapped) {
+		const rest = mapped[1];
+		if (rest.includes(".")) return isPrivateOrReservedIpv4(rest);
+		const groups = rest.split(":");
+		if (groups.length === 2 && groups.every((g) => /^[0-9a-f]{1,4}$/.test(g))) {
+			const g1 = parseInt(groups[0], 16);
+			const g2 = parseInt(groups[1], 16);
+			return isPrivateOrReservedIpv4([
+				g1 >> 8 & 255,
+				g1 & 255,
+				g2 >> 8 & 255,
+				g2 & 255
+			].join("."));
+		}
+	}
+	if (/^f[cd][0-9a-f]*:/.test(h)) return true;
+	if (/^fe[89ab][0-9a-f]*:/.test(h)) return true;
+	if (/^ff[0-9a-f]{2}:/u.test(h)) return true;
+	if (h.startsWith("100::") || h.startsWith("100:0:0:0:")) return true;
+	if (h === "2001:db8::" || h.startsWith("2001:db8:")) return true;
+	return false;
+}
+/**
+* Build the navigation predicate for a given SSRF policy. When
+* `dangerouslyAllowPrivateNetwork` is true the predicate is allow-all
+* otherwise it blocks the reserved ranges above and any non-http(s) scheme.
+*/
+function buildIsNavigationAllowed(policy, log) {
+	const allowPrivate = policy?.dangerouslyAllowPrivateNetwork === true;
+	const block = () => {
+		log?.warn("SSRF policy blocked browser navigation");
+		return false;
+	};
+	return (rawUrl) => {
+		let url;
+		try {
+			url = new URL(rawUrl);
+		} catch {
+			return block();
+		}
+		if (url.protocol !== "http:" && url.protocol !== "https:") return block();
+		if (url.username !== "" || url.password !== "") return block();
+		if (allowPrivate) return true;
+		const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+		if (BLOCKED_HOSTNAMES.has(host)) return block();
+		if (BLOCKED_HOST_SUFFIXES.some((s) => host.endsWith(s))) return block();
+		if (parseIpv4(host)) {
+			if (isPrivateOrReservedIpv4(host)) return block();
+		} else if (host.includes(":")) {
+			if (isPrivateOrReservedIpv6(host)) return block();
+		}
+		return true;
+	};
+}
+//#endregion
+//#region src/runtime.ts
+/**
+* @alfe.ai/openclaw-remote — testable runtime for the interactive remote-control
+* relay. Owns one outbound WS to the relay and routes per-session frames to the
+* browser co-browse surface (@alfe.ai/browser) or the web terminal surface
+* (@alfe.ai/terminal). Registers the agent-callable browser tools, including
+* `request_browser_takeover` ("help me complete these").
+*
+* Follows the established Alfe plugin shape (see @alfe.ai/openclaw-webhooks):
+* tools register on every activate(); the long-lived connection is guarded and
+* created inside registerService.start.
+*/
+const pkg = createRequire(import.meta.url)("../package.json");
+const REMOTE_ACTIVATION_KEY = getActivationKey("remote");
+const DEFAULT_HANDOFF_TIMEOUT_MS = 600 * 1e3;
+const DEFAULT_CHROME_PATH = "/usr/bin/google-chrome-stable";
+const RUNTIME_STATE_KEY = "__alfeOpenClawRemoteRuntimeState";
+const MAX_REMOTE_URL_CHARS = 2048;
+const MAX_PATH_CHARS = 4096;
+const MAX_AGENT_ID_CHARS = 256;
+const MAX_SESSION_ID_CHARS = 256;
+const MAX_SELECTOR_CHARS = 4096;
+const MAX_TYPE_TEXT_CHARS = 32 * 1024;
+const MAX_EXPRESSION_CHARS = 128 * 1024;
+const MAX_NAVIGATION_URL_CHARS = 8192;
+const MAX_INSTRUCTIONS_CHARS = 2e3;
+const MAX_CONVERSATION_ID_CHARS = 200;
+const MAX_SCREENSHOT_BYTES = 10 * 1024 * 1024;
+const MAX_TERMINAL_RELAY_BUFFER_BYTES = 4 * 1024 * 1024;
+const GENERIC_TOOL_ERROR = "Tool execution failed. Retry, and inspect agent diagnostics if the failure persists.";
+const PLUGIN_VERSION = validatePackageVersion(pkg.version);
+function createRemotePluginRuntimeState() {
+	return {
+		generation: 0,
+		remoteClient: null,
+		browserSurface: null,
+		terminalSurface: null,
+		apiClient: null,
+		handoffTimeoutMs: DEFAULT_HANDOFF_TIMEOUT_MS,
+		sessionSurfaces: /* @__PURE__ */ new Map(),
+		stopPromise: null
+	};
+}
+/**
+* Derive the relay WebSocket URL from the agent's cloud apiUrl when the
+* manifest doesn't provide one — mirrors @alfe.ai/console-client's
+* `deriveConsoleWsUrl` so the URL is per-stage automatically:
+*   https://api.dev.alfe.ai → wss://remote.dev.alfe.ai/ws
+* (matches config.flyDomains.remote per stage). This is why the
+* headless-browser integration manifest carries no hardcoded, prod-pinned
+* `remoteWsUrl`: the plugin resolves it from the agent's own endpoint.
+*/
+function deriveRemoteWsUrl(apiUrl) {
+	try {
+		const url = new URL(apiUrl);
+		if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || !url.hostname.startsWith("api.")) return void 0;
+		return `wss://remote.${url.hostname.slice(4)}/ws`;
+	} catch {
+		return;
+	}
+}
+/**
+* Derive the dashboard (control-plane) base URL from the agent's cloud apiUrl,
+* mirroring `deriveRemoteWsUrl` so it's per-stage automatically:
+*   https://api.dev.alfe.ai → https://app.dev.alfe.ai
+*   https://api.alfe.ai     → https://app.alfe.ai   (prod)
+* The `api.` → `app.` swap matches config.*.ts `dashboardDomain` for every
+* stage. Returns undefined for a non-`api.` host (e.g. localhost/dev override)
+* so the caller can fall back to a session-only link.
+*/
+function deriveDashboardBaseUrl(apiUrl) {
+	try {
+		const url = new URL(apiUrl);
+		if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || !url.hostname.startsWith("api.")) return void 0;
+		return `https://app.${url.hostname.slice(4)}`;
+	} catch {
+		return;
+	}
+}
+/**
+* Build the dashboard deep-link ("control URL") the human opens to take over.
+* Prefers the full agent-scoped path; if the dashboard host or agentId is
+* unavailable, degrades gracefully (session-only path, then null).
+*/
+function buildControlUrl(dashboardBaseUrl, agentId, sessionId) {
+	if (!isDashboardBaseUrl(dashboardBaseUrl) || !isBoundedString(sessionId, MAX_SESSION_ID_CHARS)) return void 0;
+	const session = encodeURIComponent(sessionId);
+	if (agentId && isBoundedString(agentId, MAX_AGENT_ID_CHARS)) return `${dashboardBaseUrl}/agents/${encodeURIComponent(agentId)}?tab=browser&session=${session}`;
+	return `${dashboardBaseUrl}/agents?tab=browser&session=${session}`;
+}
+/** Route an inbound relay frame to the owning surface by session. */
+function dispatchFrame(state, frame, log) {
+	if (frame.type === RemoteFrameType.SESSION_OPEN) {
+		const open = decodeSessionOpenPayload(frame.payload);
+		if (!open) return;
+		const existingSurface = state.sessionSurfaces.get(frame.sessionId);
+		if (existingSurface !== void 0 && existingSurface !== open.surface) {
+			log.warn("Remote session attempted to change surface type");
+			return;
+		}
+		const handler = open.surface === "terminal" ? state.terminalSurface : state.browserSurface;
+		if (!handler) {
+			log.warn("Remote session surface is unavailable");
+			return;
+		}
+		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 {}
+			log.warn("Remote session could not be opened");
+		});
+		return;
+	}
+	const surface = state.sessionSurfaces.get(frame.sessionId);
+	const handler = surface === "terminal" ? state.terminalSurface : surface === "browser" ? state.browserSurface : null;
+	if (!handler) return;
+	if (frame.type === RemoteFrameType.SESSION_CLOSE) {
+		state.sessionSurfaces.delete(frame.sessionId);
+		try {
+			handler.closeSession(frame.sessionId);
+		} catch {
+			log.warn("Remote session close failed");
+		}
+		return;
+	}
+	try {
+		handler.handleFrame(frame);
+	} catch {
+		log.warn("Remote session frame handling failed");
+	}
+}
+function startService(pluginConfig, ssrfPolicy, workspaceDir, log, dependencies, state) {
+	guardedStart(REMOTE_ACTIVATION_KEY, log, () => {
+		if (pluginConfig === null) {
+			log.error("Remote plugin configuration is invalid");
+			resetActivation(REMOTE_ACTIVATION_KEY);
+			return;
+		}
+		return startServiceInner(pluginConfig, ssrfPolicy, workspaceDir, log, dependencies, state);
+	});
+}
+async function startServiceInner(pluginConfig, ssrfPolicy, workspaceDir, log, dependencies, state) {
+	if (state.remoteClient !== null || state.browserSurface !== null || state.terminalSurface !== null || state.apiClient !== null) {
+		log.warn("Remote runtime already owns active resources");
+		return;
+	}
+	let alfeConfig = null;
+	try {
+		alfeConfig = dependencies.resolveRuntimeConfig();
+	} catch {
+		log.info("Could not resolve Alfe config — remote plugin idle");
+	}
+	const apiKey = alfeConfig?.apiKey;
+	const apiUrl = alfeConfig?.apiUrl;
+	const wsUrl = pluginConfig.remoteWsUrl ?? (apiUrl ? deriveRemoteWsUrl(apiUrl) : void 0);
+	if (!wsUrl || !apiKey || !apiUrl) {
+		log.info("Remote relay URL or credentials not configured — plugin running without relay");
+		resetActivation(REMOTE_ACTIVATION_KEY);
+		return;
+	}
+	const generation = state.generation + 1;
+	const nextApiClient = dependencies.createApiClient({
+		apiKey,
+		apiUrl
+	});
+	const resolvedWorkspace = selectWorkspacePath(workspaceDir, alfeConfig?.workspacePath);
+	let nextBrowserSurface = null;
+	let nextTerminalSurface = null;
+	let nextRemoteClient = null;
+	const sendFrame = (frame) => {
+		if (state.generation === generation && state.remoteClient === nextRemoteClient) nextRemoteClient?.sendFrame(frame);
+	};
+	const sendTerminalFrame = (frame) => {
+		if (state.generation !== generation || state.remoteClient !== nextRemoteClient || nextRemoteClient === null) return;
+		if ((nextRemoteClient.bufferedAmount ?? 0) >= MAX_TERMINAL_RELAY_BUFFER_BYTES) throw new Error("Remote terminal relay buffer limit reached");
+		nextRemoteClient.sendFrame(frame);
+	};
+	try {
+		nextBrowserSurface = dependencies.createBrowserSurface({
+			executablePath: pluginConfig.browserExecutablePath ?? DEFAULT_CHROME_PATH,
+			headless: pluginConfig.browserHeadless ?? true,
+			noSandbox: pluginConfig.browserNoSandbox ?? true,
+			userDataDir: join(resolvedWorkspace, ".alfe-browser-profile"),
+			isNavigationAllowed: buildIsNavigationAllowed(ssrfPolicy, log),
+			logger: log
+		}, sendFrame);
+		nextTerminalSurface = dependencies.createTerminalSurface({
+			cwd: resolvedWorkspace,
+			logger: log
+		}, sendTerminalFrame);
+		nextRemoteClient = dependencies.createRemoteClient({
+			wsUrl,
+			apiKey,
+			onFrame: (frame) => {
+				if (state.generation === generation && state.remoteClient === nextRemoteClient) dispatchFrame(state, frame, log);
+			},
+			onConnectionChange: (connected) => {
+				if (state.generation !== generation || state.remoteClient !== nextRemoteClient) return;
+				log.info(`Remote relay connection: ${connected ? "connected" : "disconnected"}`);
+				if (!connected) closeAllSessions(state, log);
+			},
+			logger: log
+		});
+	} catch (error) {
+		nextRemoteClient?.stop();
+		nextTerminalSurface?.shutdown();
+		await nextBrowserSurface?.shutdown().catch(() => void 0);
+		throw error;
+	}
+	state.generation = generation;
+	state.handoffTimeoutMs = pluginConfig.handoffTimeoutMs ?? DEFAULT_HANDOFF_TIMEOUT_MS;
+	state.apiClient = nextApiClient;
+	state.browserSurface = nextBrowserSurface;
+	state.terminalSurface = nextTerminalSurface;
+	state.remoteClient = nextRemoteClient;
+	state.dashboardBaseUrl = deriveDashboardBaseUrl(apiUrl);
+	state.selfAgentId = void 0;
+	try {
+		nextRemoteClient.start();
+	} catch (error) {
+		await stopService(state, log);
+		throw error;
+	}
+	nextApiClient.whoami().then(({ agentId }) => {
+		if (state.generation === generation && state.apiClient === nextApiClient && isBoundedString(agentId, MAX_AGENT_ID_CHARS)) state.selfAgentId = agentId;
+	}).catch(() => {
+		log.debug("whoami failed; takeover links will omit agentId");
+	});
+	log.info("Remote plugin started");
+}
+function stopService(state, log) {
+	if (state.stopPromise !== null) return state.stopPromise;
+	const generation = state.generation + 1;
+	state.generation = generation;
+	const remoteClient = state.remoteClient;
+	const browserSurface = state.browserSurface;
+	const terminalSurface = state.terminalSurface;
+	const stopping = (async () => {
+		remoteClient?.stop();
+		closeAllSessions(state, log);
+		terminalSurface?.shutdown();
+		await browserSurface?.shutdown().catch(() => void 0);
+		if (state.generation === generation) {
+			state.remoteClient = null;
+			state.browserSurface = null;
+			state.terminalSurface = null;
+			state.apiClient = null;
+			state.dashboardBaseUrl = void 0;
+			state.selfAgentId = void 0;
+			state.handoffTimeoutMs = DEFAULT_HANDOFF_TIMEOUT_MS;
+			state.sessionSurfaces.clear();
+		}
+	})().finally(() => {
+		if (state.stopPromise === stopping) state.stopPromise = null;
+		resetActivation(REMOTE_ACTIVATION_KEY);
+		log.info("Remote plugin stopped");
+	});
+	state.stopPromise = stopping;
+	return stopping;
+}
+function closeAllSessions(state, log) {
+	for (const [sessionId, surface] of state.sessionSurfaces) {
+		const handler = surface === "terminal" ? state.terminalSurface : state.browserSurface;
+		try {
+			handler?.closeSession(sessionId);
+		} catch {
+			log.warn("Remote session cleanup failed");
+		}
+	}
+	state.sessionSurfaces.clear();
+}
+function registerTools(api, state) {
+	const needBrowser = () => {
+		if (!state.browserSurface) throw publicToolError("Browser surface is unavailable; retry after the remote service connects.");
+		return state.browserSurface;
+	};
+	api.registerTool(remoteTool({
+		name: "browser_navigate",
+		description: "Navigate the shared browser to a URL. Returns the final URL and page title.",
+		parameters: {
+			type: "object",
+			properties: { url: {
+				type: "string",
+				minLength: 1,
+				maxLength: MAX_NAVIGATION_URL_CHARS,
+				description: "Absolute credential-free HTTP(S) URL to open"
+			} },
+			required: ["url"],
+			additionalProperties: false
+		},
+		handler: async (params) => {
+			const url = requireHttpUrl(params.url, "url", MAX_NAVIGATION_URL_CHARS);
+			try {
+				return await needBrowser().automation.navigate(url);
+			} catch (error) {
+				if (error instanceof Error && error.message === "Navigation blocked by browser policy") throw publicToolError(error.message);
+				throw error;
+			}
+		}
+	}));
+	api.registerTool(remoteTool({
+		name: "browser_click",
+		description: "Click an element in the shared browser by CSS selector.",
+		parameters: {
+			type: "object",
+			properties: { selector: {
+				type: "string",
+				minLength: 1,
+				maxLength: MAX_SELECTOR_CHARS
+			} },
+			required: ["selector"],
+			additionalProperties: false
+		},
+		handler: async (params) => {
+			await needBrowser().automation.click(requireString(params.selector, "selector", MAX_SELECTOR_CHARS));
+			return { ok: true };
+		}
+	}));
+	api.registerTool(remoteTool({
+		name: "browser_type",
+		description: "Type text into an element in the shared browser by CSS selector.",
+		parameters: {
+			type: "object",
+			properties: {
+				selector: {
+					type: "string",
+					minLength: 1,
+					maxLength: MAX_SELECTOR_CHARS
+				},
+				text: {
+					type: "string",
+					maxLength: MAX_TYPE_TEXT_CHARS
+				}
+			},
+			required: ["selector", "text"],
+			additionalProperties: false
+		},
+		handler: async (params) => {
+			await needBrowser().automation.type(requireString(params.selector, "selector", MAX_SELECTOR_CHARS), requireString(params.text, "text", MAX_TYPE_TEXT_CHARS, true));
+			return { ok: true };
+		}
+	}));
+	api.registerTool(remoteTool({
+		name: "browser_wait_for",
+		description: "Wait for exactly one selector, URL substring, or fixed delay.",
+		parameters: {
+			type: "object",
+			properties: {
+				selector: {
+					type: "string",
+					minLength: 1,
+					maxLength: MAX_SELECTOR_CHARS
+				},
+				urlPattern: {
+					type: "string",
+					minLength: 1,
+					maxLength: MAX_NAVIGATION_URL_CHARS
+				},
+				ms: {
+					type: "integer",
+					minimum: 0,
+					maximum: 12e4
+				}
+			},
+			additionalProperties: false
+		},
+		handler: async (params) => {
+			const options = parseWaitOptions(params);
+			await needBrowser().automation.waitFor(options);
+			return { ok: true };
+		}
+	}));
+	api.registerTool({
+		name: "browser_screenshot",
+		label: "browser_screenshot",
+		description: "Capture a JPEG screenshot of the shared browser's current page.",
+		parameters: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		},
+		execute: async (_toolCallId, params) => {
+			try {
+				if (!isRecord(params) || Object.keys(params).length > 0) throw publicToolError("browser_screenshot accepts no parameters");
+				const data = await needBrowser().automation.screenshot();
+				const bytes = decodedBase64Bytes(data);
+				if (bytes < 1 || bytes > MAX_SCREENSHOT_BYTES) throw new Error("Browser screenshot exceeded its media boundary");
+				return {
+					content: [{
+						type: "image",
+						data,
+						mimeType: "image/jpeg"
+					}],
+					details: {
+						mimeType: "image/jpeg",
+						bytes
+					}
+				};
+			} catch (error) {
+				return errResult(error instanceof PublicToolError ? error.message : GENERIC_TOOL_ERROR);
+			}
+		}
+	});
+	api.registerTool(remoteTool({
+		name: "browser_evaluate",
+		description: "Evaluate a JavaScript expression in the shared browser page and return bounded JSON.",
+		parameters: {
+			type: "object",
+			properties: { expression: {
+				type: "string",
+				minLength: 1,
+				maxLength: MAX_EXPRESSION_CHARS
+			} },
+			required: ["expression"],
+			additionalProperties: false
+		},
+		handler: async (params) => ({ result: await needBrowser().automation.evaluate(requireString(params.expression, "expression", MAX_EXPRESSION_CHARS)) })
+	}));
+	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.",
+		parameters: {
+			type: "object",
+			properties: {
+				instructions: {
+					type: "string",
+					minLength: 1,
+					maxLength: MAX_INSTRUCTIONS_CHARS,
+					description: "Exact task for the human to complete"
+				},
+				url: {
+					type: "string",
+					minLength: 1,
+					maxLength: 2048,
+					description: "Optional credential-free HTTP(S) page shown for context"
+				},
+				conversationId: {
+					type: "string",
+					minLength: 1,
+					maxLength: MAX_CONVERSATION_ID_CHARS
+				}
+			},
+			required: ["instructions"],
+			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);
+			}
+		}
+	}));
+}
+function createRemotePlugin(dependencies = {}) {
+	const state = dependencies.runtimeState ?? getGlobalRuntimeState();
+	const runtimeDependencies = {
+		resolveRuntimeConfig: dependencies.resolveConfig ?? resolveConfig,
+		createApiClient: dependencies.createApiClient ?? ((config) => new AgentApiClient(config)),
+		createRemoteClient: dependencies.createRemoteClient ?? ((options) => new RemoteServiceClient(options)),
+		createBrowserSurface: dependencies.createBrowserSurface ?? ((options, sendFrame) => new BrowserSurface(options, sendFrame)),
+		createTerminalSurface: dependencies.createTerminalSurface ?? ((options, sendFrame) => new TerminalSurface(options, sendFrame))
+	};
+	const installErrorCapture = dependencies.installErrorCapture ?? installToolErrorCapture;
+	return {
+		id: "@alfe.ai/openclaw-remote",
+		name: "Remote",
+		description: "Interactive remote control — browser co-browse takeover and web terminal",
+		version: PLUGIN_VERSION,
+		activate(api) {
+			installErrorCapture(api, { plugin: "openclaw-remote" });
+			const log = api.logger;
+			let pluginConfig = null;
+			let ssrfPolicy;
+			try {
+				const parsedPluginConfig = parseRemotePluginConfig(api.config?.plugins?.entries?.["@alfe.ai/openclaw-remote"]?.config, api.config?.browser);
+				const parsedSsrfPolicy = parseSsrfPolicy(api.config?.browser?.ssrfPolicy);
+				pluginConfig = parsedPluginConfig;
+				ssrfPolicy = parsedSsrfPolicy;
+			} catch {
+				log.error("Remote plugin configuration is invalid");
+			}
+			registerTools(api, state);
+			api.registerService({
+				id: "alfe-remote",
+				start: (context) => {
+					startService(pluginConfig, ssrfPolicy, context.workspaceDir, log, runtimeDependencies, state);
+				},
+				stop: () => stopService(state, log)
+			});
+			log.info("Alfe Remote plugin activated");
+		},
+		async deactivate(api) {
+			await stopService(state, api.logger);
+			api.logger.info("Alfe Remote plugin deactivated");
+		}
+	};
+}
+function parseRemotePluginConfig(value, browserFallback) {
+	const config = value === void 0 ? {} : requireRecord(value, "remote plugin config");
+	const allowedKeys = new Set([
+		"remoteWsUrl",
+		"browserExecutablePath",
+		"browserHeadless",
+		"browserNoSandbox",
+		"handoffTimeoutMs"
+	]);
+	if (Object.keys(config).some((key) => !allowedKeys.has(key))) throw new Error("Remote plugin config contains unsupported fields");
+	const browser = isRecord(browserFallback) ? browserFallback : {};
+	return {
+		remoteWsUrl: optionalRelayUrl(config.remoteWsUrl),
+		browserExecutablePath: optionalAbsolutePath(config.browserExecutablePath ?? browser.executablePath),
+		browserHeadless: optionalBoolean(config.browserHeadless ?? browser.headless, "browserHeadless"),
+		browserNoSandbox: optionalBoolean(config.browserNoSandbox ?? browser.noSandbox, "browserNoSandbox"),
+		handoffTimeoutMs: optionalInteger(config.handoffTimeoutMs, "handoffTimeoutMs", 1e3, 1800 * 1e3)
+	};
+}
+function parseSsrfPolicy(value) {
+	if (value === void 0) return void 0;
+	const policy = requireRecord(value, "browser SSRF policy");
+	if (Object.keys(policy).some((key) => key !== "dangerouslyAllowPrivateNetwork")) throw new Error("Browser SSRF policy contains unsupported fields");
+	return { dangerouslyAllowPrivateNetwork: optionalBoolean(policy.dangerouslyAllowPrivateNetwork, "dangerouslyAllowPrivateNetwork") };
+}
+function remoteTool(definition) {
+	return defineTool({
+		...definition,
+		handler: (params) => Promise.resolve(definition.handler(params))
+	});
+}
+function requireString(value, label, maxChars, allowEmpty = false) {
+	if (typeof value !== "string" || !allowEmpty && value.length < 1 || value.length > maxChars || hasControlCharacter(value)) throw publicToolError(`${label} must contain ${allowEmpty ? "at most" : "1 to"} ${String(maxChars)} non-control characters`);
+	return value;
+}
+function optionalString(value, label, maxChars) {
+	return value === void 0 ? void 0 : requireString(value, label, maxChars);
+}
+function requireHttpUrl(value, label, maxChars) {
+	const raw = requireString(value, label, maxChars);
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw publicToolError(`${label} must be an absolute HTTP(S) URL`);
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:" || url.username !== "" || url.password !== "") throw publicToolError(`${label} must be an absolute HTTP(S) URL without credentials`);
+	return url.href;
+}
+function parseWaitOptions(params) {
+	if ([
+		params.selector,
+		params.urlPattern,
+		params.ms
+	].filter((value) => value !== void 0).length !== 1) throw publicToolError("Provide exactly one of selector, urlPattern, or ms");
+	if (params.selector !== void 0) return { selector: requireString(params.selector, "selector", MAX_SELECTOR_CHARS) };
+	if (params.urlPattern !== void 0) return { urlPattern: requireString(params.urlPattern, "urlPattern", MAX_NAVIGATION_URL_CHARS) };
+	if (!Number.isInteger(params.ms) || params.ms < 0 || params.ms > 12e4) throw publicToolError("ms must be an integer from 0 to 120000");
+	return { ms: params.ms };
+}
+function requireTrustedString(value, label, maxChars) {
+	if (!isBoundedString(value, maxChars)) throw new Error(`${label} is invalid`);
+	return value;
+}
+function decodedBase64Bytes(value) {
+	if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value)) throw new Error("Browser screenshot was not valid base64");
+	return Buffer.from(value, "base64").byteLength;
+}
+function selectWorkspacePath(contextPath, configuredPath) {
+	for (const candidate of [contextPath, configuredPath]) if (typeof candidate === "string" && candidate.length > 0 && candidate.length <= MAX_PATH_CHARS && !hasControlCharacter(candidate) && isAbsolute(candidate)) return candidate;
+	throw new Error("Remote workspace path is invalid");
+}
+function optionalRelayUrl(value) {
+	if (value === void 0) return void 0;
+	if (!isBoundedString(value, MAX_REMOTE_URL_CHARS)) throw new Error("remoteWsUrl is invalid");
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error("remoteWsUrl is invalid");
+	}
+	const host = url.hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+	const loopback = host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/u.test(host);
+	if (url.protocol !== "wss:" && !(url.protocol === "ws:" && loopback) || url.username !== "" || url.password !== "" || url.hash !== "") throw new Error("remoteWsUrl is invalid");
+	return url.href;
+}
+function isDashboardBaseUrl(value) {
+	if (!isBoundedString(value, MAX_REMOTE_URL_CHARS)) return false;
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" && url.username === "" && url.password === "" && url.hostname.startsWith("app.") && url.pathname === "/" && url.search === "" && url.hash === "";
+	} catch {
+		return false;
+	}
+}
+function optionalAbsolutePath(value) {
+	if (value === void 0) return void 0;
+	if (!isBoundedString(value, MAX_PATH_CHARS) || !isAbsolute(value)) throw new Error("browserExecutablePath is invalid");
+	return value;
+}
+function optionalBoolean(value, label) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "boolean") throw new Error(`${label} must be a boolean`);
+	return value;
+}
+function optionalInteger(value, label, minimum, maximum) {
+	if (value === void 0) return void 0;
+	if (!Number.isInteger(value) || value < minimum || value > maximum) throw new Error(`${label} must be an integer from ${String(minimum)} to ${String(maximum)}`);
+	return value;
+}
+function getGlobalRuntimeState() {
+	const root = globalThis;
+	const existing = root[RUNTIME_STATE_KEY];
+	if (isRuntimeState(existing)) return existing;
+	const state = createRemotePluginRuntimeState();
+	root[RUNTIME_STATE_KEY] = state;
+	return state;
+}
+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));
+}
+function isRemoteClient(value) {
+	return isRecord(value) && typeof value.start === "function" && typeof value.stop === "function" && typeof value.sendFrame === "function";
+}
+function isBrowserSurface(value) {
+	return isRecord(value) && isRecord(value.automation) && typeof value.automation.navigate === "function" && typeof value.automation.click === "function" && typeof value.automation.type === "function" && typeof value.automation.waitFor === "function" && typeof value.automation.screenshot === "function" && typeof value.automation.evaluate === "function" && typeof value.openSession === "function" && typeof value.closeSession === "function" && typeof value.handleFrame === "function" && typeof value.requestHandoff === "function" && typeof value.addHold === "function" && typeof value.removeHold === "function" && typeof value.shutdown === "function";
+}
+function isTerminalSurface(value) {
+	return isRecord(value) && typeof value.openSession === "function" && typeof value.closeSession === "function" && typeof value.handleFrame === "function" && typeof value.shutdown === "function";
+}
+function isRemoteApiClient(value) {
+	return isRecord(value) && typeof value.whoami === "function" && typeof value.requestBrowserTakeover === "function" && typeof value.completeRemoteSession === "function";
+}
+function requireRecord(value, label) {
+	if (!isRecord(value)) throw new Error(`${label} must be an object`);
+	return value;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isBoundedString(value, maxChars) {
+	return typeof value === "string" && value.length > 0 && value.length <= maxChars && !hasControlCharacter(value);
+}
+function hasControlCharacter(value) {
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code < 32 || code === 127) return true;
+	}
+	return false;
+}
+function validatePackageVersion(value) {
+	if (typeof value !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(value)) throw new Error("openclaw-remote package version is invalid");
+	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 };