@alfe.ai/openclaw-remote 0.0.0 → 0.0.1

package/dist/plugin2.cjs

@@ -0,0 +1,423 @@
+let _alfe_ai_config = require("@alfe.ai/config");
+let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
+let _alfe_ai_remote = require("@alfe.ai/remote");
+let _alfe_ai_browser = require("@alfe.ai/browser");
+let _alfe_ai_terminal = require("@alfe.ai/terminal");
+let node_module = require("node:module");
+//#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 === 168) return true;
+	if (a === 100 && b >= 64 && b <= 127) 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;
+	return false;
+}
+/**
+* Build the navigation predicate for a given SSRF policy. When
+* `dangerouslyAllowPrivateNetwork` is true the predicate is allow-all
+* (matching the `alfe` integration's current default); otherwise it blocks
+* the reserved ranges above and any non-http(s) scheme.
+*/
+function buildIsNavigationAllowed(policy, log) {
+	const allowPrivate = policy?.dangerouslyAllowPrivateNetwork === true;
+	const block = (rawUrl) => {
+		log?.warn(`SSRF policy blocked navigation to ${rawUrl}`);
+		return false;
+	};
+	return (rawUrl) => {
+		let url;
+		try {
+			url = new URL(rawUrl);
+		} catch {
+			return block(rawUrl);
+		}
+		if (url.protocol !== "http:" && url.protocol !== "https:") return block(rawUrl);
+		if (allowPrivate) return true;
+		const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+		if (BLOCKED_HOSTNAMES.has(host)) return block(rawUrl);
+		if (BLOCKED_HOST_SUFFIXES.some((s) => host.endsWith(s))) return block(rawUrl);
+		if (parseIpv4(host)) {
+			if (isPrivateOrReservedIpv4(host)) return block(rawUrl);
+		} else if (host.includes(":")) {
+			if (isPrivateOrReservedIpv6(host)) return block(rawUrl);
+		}
+		return true;
+	};
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* @alfe.ai/openclaw-remote — OpenClaw plugin 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 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json");
+const ACTIVATED_KEY = "__alfeRemotePluginActivated";
+const DEFAULT_HANDOFF_TIMEOUT_MS = 600 * 1e3;
+const DEFAULT_CHROME_PATH = "/usr/bin/google-chrome-stable";
+/**
+* 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 {
+		return `wss://${new URL(apiUrl).hostname.replace("api.", "remote.")}/ws`;
+	} catch {
+		return;
+	}
+}
+let remoteClient = null;
+let browserSurface = null;
+let terminalSurface = null;
+let apiClient = null;
+let handoffTimeoutMs = DEFAULT_HANDOFF_TIMEOUT_MS;
+const sessionSurfaces = /* @__PURE__ */ new Map();
+function g() {
+	return globalThis;
+}
+/** Coerce an unknown tool param to a string (empty if not a string). */
+function asStr(v) {
+	return typeof v === "string" ? v : "";
+}
+/** Coerce an unknown tool param to a string or undefined. */
+function optStr(v) {
+	return typeof v === "string" ? v : void 0;
+}
+/** Route an inbound relay frame to the owning surface by session. */
+function dispatchFrame(frame, log) {
+	if (frame.type === _alfe_ai_remote.RemoteFrameType.SESSION_OPEN) {
+		const open = (0, _alfe_ai_remote.decodeJson)(frame.payload);
+		if (!open) return;
+		const handler = open.surface === "terminal" ? terminalSurface : browserSurface;
+		if (!handler) {
+			log.warn(`No handler for surface ${open.surface}`);
+			return;
+		}
+		sessionSurfaces.set(frame.sessionId, open.surface);
+		Promise.resolve(handler.openSession(frame.sessionId, open)).catch((err) => {
+			log.warn(`openSession failed: ${err.message}`);
+		});
+		return;
+	}
+	const surface = sessionSurfaces.get(frame.sessionId);
+	const handler = surface === "terminal" ? terminalSurface : surface === "browser" ? browserSurface : null;
+	if (!handler) return;
+	if (frame.type === _alfe_ai_remote.RemoteFrameType.SESSION_CLOSE) {
+		handler.closeSession(frame.sessionId);
+		sessionSurfaces.delete(frame.sessionId);
+		return;
+	}
+	handler.handleFrame(frame);
+}
+function startService(pluginConfig, ssrfPolicy, workspaceDir, log) {
+	if (g()[ACTIVATED_KEY] === true) {
+		log.debug("Alfe Remote plugin already activated — skipping duplicate");
+		return;
+	}
+	g()[ACTIVATED_KEY] = true;
+	let alfeConfig = null;
+	try {
+		alfeConfig = (0, _alfe_ai_config.resolveConfig)();
+	} 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");
+		g()[ACTIVATED_KEY] = false;
+		return;
+	}
+	handoffTimeoutMs = pluginConfig.handoffTimeoutMs ?? DEFAULT_HANDOFF_TIMEOUT_MS;
+	apiClient = new _alfe_ai_agent_api_client.AgentApiClient({
+		apiKey,
+		apiUrl
+	});
+	const sendFrame = (buf) => {
+		remoteClient?.sendFrame(buf);
+	};
+	browserSurface = new _alfe_ai_browser.BrowserSurface({
+		executablePath: pluginConfig.browserExecutablePath ?? DEFAULT_CHROME_PATH,
+		headless: pluginConfig.browserHeadless ?? true,
+		noSandbox: pluginConfig.browserNoSandbox ?? true,
+		userDataDir: `${workspaceDir ?? alfeConfig?.workspacePath ?? "."}/.alfe-browser-profile`,
+		isNavigationAllowed: buildIsNavigationAllowed(ssrfPolicy, log),
+		logger: log
+	}, sendFrame);
+	terminalSurface = new _alfe_ai_terminal.TerminalSurface({
+		cwd: workspaceDir ?? alfeConfig?.workspacePath,
+		logger: log
+	}, sendFrame);
+	remoteClient = new _alfe_ai_remote.RemoteServiceClient({
+		wsUrl,
+		apiKey,
+		onFrame: (frame) => {
+			dispatchFrame(frame, log);
+		},
+		onConnectionChange: (connected) => {
+			log.info(`Remote relay connection: ${connected ? "connected" : "disconnected"}`);
+		},
+		logger: log
+	});
+	remoteClient.start();
+	log.info(`Remote plugin started — relay ${wsUrl}`);
+}
+function stopService(log) {
+	g()[ACTIVATED_KEY] = false;
+	remoteClient?.stop();
+	remoteClient = null;
+	browserSurface?.shutdown();
+	browserSurface = null;
+	terminalSurface?.shutdown();
+	terminalSurface = null;
+	apiClient = null;
+	sessionSurfaces.clear();
+	log.info("Remote plugin stopped");
+}
+function registerTools(api) {
+	const needBrowser = () => {
+		if (!browserSurface) throw new Error("Browser surface not available (remote relay not connected)");
+		return browserSurface;
+	};
+	api.registerTool({
+		name: "browser_navigate",
+		label: "browser_navigate",
+		description: "Navigate the shared browser to a URL. Returns the final URL and page title.",
+		parameters: {
+			type: "object",
+			properties: { url: {
+				type: "string",
+				description: "The URL to open"
+			} },
+			required: ["url"]
+		},
+		execute: async (_id, params) => needBrowser().automation.navigate(asStr(params.url))
+	});
+	api.registerTool({
+		name: "browser_click",
+		label: "browser_click",
+		description: "Click an element in the shared browser by CSS selector.",
+		parameters: {
+			type: "object",
+			properties: { selector: {
+				type: "string",
+				description: "CSS selector to click"
+			} },
+			required: ["selector"]
+		},
+		execute: async (_id, params) => {
+			await needBrowser().automation.click(asStr(params.selector));
+			return { ok: true };
+		}
+	});
+	api.registerTool({
+		name: "browser_type",
+		label: "browser_type",
+		description: "Type text into an element in the shared browser by CSS selector.",
+		parameters: {
+			type: "object",
+			properties: {
+				selector: {
+					type: "string",
+					description: "CSS selector of the input"
+				},
+				text: {
+					type: "string",
+					description: "Text to type"
+				}
+			},
+			required: ["selector", "text"]
+		},
+		execute: async (_id, params) => {
+			await needBrowser().automation.type(asStr(params.selector), asStr(params.text));
+			return { ok: true };
+		}
+	});
+	api.registerTool({
+		name: "browser_wait_for",
+		label: "browser_wait_for",
+		description: "Wait for a selector to appear, a URL substring to match, or a fixed delay.",
+		parameters: {
+			type: "object",
+			properties: {
+				selector: { type: "string" },
+				urlPattern: { type: "string" },
+				ms: { type: "number" }
+			}
+		},
+		execute: async (_id, params) => {
+			await needBrowser().automation.waitFor({
+				selector: optStr(params.selector),
+				urlPattern: optStr(params.urlPattern),
+				ms: typeof params.ms === "number" ? params.ms : void 0
+			});
+			return { ok: true };
+		}
+	});
+	api.registerTool({
+		name: "browser_screenshot",
+		label: "browser_screenshot",
+		description: "Capture a JPEG screenshot of the shared browser's current page (base64).",
+		parameters: {
+			type: "object",
+			properties: {}
+		},
+		execute: async () => ({ imageBase64: await needBrowser().automation.screenshot() })
+	});
+	api.registerTool({
+		name: "browser_evaluate",
+		label: "browser_evaluate",
+		description: "Evaluate a JavaScript expression in the shared browser page and return the result.",
+		parameters: {
+			type: "object",
+			properties: { expression: {
+				type: "string",
+				description: "JS expression to evaluate"
+			} },
+			required: ["expression"]
+		},
+		execute: async (_id, params) => ({ result: await needBrowser().automation.evaluate(asStr(params.expression)) })
+	});
+	api.registerTool({
+		name: "request_browser_takeover",
+		label: "request_browser_takeover",
+		description: "Ask a human to take over the browser you're currently looking at and complete a step you can't do yourself — logging in, solving a captcha, or clicking through a manual flow. The human sees your current live page, completes the instructions, and hands control back; you then resume on the same authenticated page. Blocks until the human is done or the request times out.",
+		parameters: {
+			type: "object",
+			properties: {
+				instructions: {
+					type: "string",
+					description: "What you need the human to do, e.g. 'Log in with the saved credentials and complete the 2FA prompt, then click Continue.'"
+				},
+				url: {
+					type: "string",
+					description: "Optional: the page you're stuck on (display only — the human sees your live page)."
+				},
+				conversationId: {
+					type: "string",
+					description: "Optional: the chat conversation to surface the request in."
+				}
+			},
+			required: ["instructions"]
+		},
+		execute: async (_id, params) => {
+			const surface = needBrowser();
+			if (!apiClient) throw new Error("Remote plugin not connected");
+			const { sessionId } = await apiClient.requestBrowserTakeover({
+				instructions: asStr(params.instructions),
+				url: optStr(params.url),
+				conversationId: optStr(params.conversationId)
+			});
+			try {
+				return {
+					sessionId,
+					...await surface.requestHandoff(handoffTimeoutMs)
+				};
+			} finally {
+				await apiClient.completeRemoteSession(sessionId).catch(() => {});
+			}
+		}
+	});
+}
+const plugin = {
+	id: "@alfe.ai/openclaw-remote",
+	name: "Remote",
+	description: "Interactive remote control — browser co-browse takeover and web terminal",
+	version: pkg.version,
+	activate(api) {
+		const log = api.logger;
+		const pluginConfig = api.config?.plugins?.entries?.["@alfe.ai/openclaw-remote"]?.config ?? {};
+		pluginConfig.browserExecutablePath ??= api.config?.browser?.executablePath;
+		pluginConfig.browserHeadless ??= api.config?.browser?.headless;
+		pluginConfig.browserNoSandbox ??= api.config?.browser?.noSandbox;
+		const ssrfPolicy = api.config?.browser?.ssrfPolicy;
+		registerTools(api);
+		api.registerService({
+			id: "alfe-remote",
+			start: (ctx) => {
+				startService(pluginConfig, ssrfPolicy, ctx.workspaceDir, log);
+			},
+			stop: () => {
+				stopService(log);
+			}
+		});
+		log.info("Alfe Remote plugin activated");
+	},
+	deactivate(api) {
+		stopService(api.logger);
+		api.logger.info("Alfe Remote plugin deactivated");
+	}
+};
+//#endregion
+Object.defineProperty(exports, "buildIsNavigationAllowed", {
+	enumerable: true,
+	get: function() {
+		return buildIsNavigationAllowed;
+	}
+});
+Object.defineProperty(exports, "plugin", {
+	enumerable: true,
+	get: function() {
+		return plugin;
+	}
+});