@alfe.ai/browser 0.0.0

package/dist/index.cjs

@@ -0,0 +1,600 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let _alfe_ai_remote = require("@alfe.ai/remote");
+let puppeteer_core = require("puppeteer-core");
+puppeteer_core = __toESM(puppeteer_core);
+//#region src/browser-session.ts
+/**
+* BrowserSession — owns the single headless Chrome instance the agent
+* automates and the human takes over. Lazy-launched on first use, idle-shut
+* down when nothing holds it open (cookies/login persist on disk in
+* `userDataDir` across restarts). Tracks the *active* target so OAuth popups /
+* new tabs are what gets screencast, not a stale main window.
+*/
+const DEFAULT_IDLE_MS = 300 * 1e3;
+const noopLogger$2 = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {}
+};
+var BrowserSession = class {
+	browser = null;
+	activePage = null;
+	launching = null;
+	holds = 0;
+	idleTimer = null;
+	log;
+	idleMs;
+	constructor(options) {
+		this.options = options;
+		this.log = options.logger ?? noopLogger$2;
+		this.idleMs = options.idleShutdownMs ?? DEFAULT_IDLE_MS;
+	}
+	/** Launch Chrome if not already running (idempotent, concurrent-safe). */
+	async ensureLaunched() {
+		if (this.browser) return;
+		if (this.launching) return this.launching;
+		this.launching = this.doLaunch().finally(() => {
+			this.launching = null;
+		});
+		return this.launching;
+	}
+	async doLaunch() {
+		const args = [
+			"--disable-blink-features=AutomationControlled",
+			...this.options.noSandbox ? ["--no-sandbox", "--disable-setuid-sandbox"] : [],
+			...this.options.extraArgs ?? []
+		];
+		this.log.info(`Launching Chrome (${this.options.executablePath})`);
+		this.browser = await puppeteer_core.default.launch({
+			executablePath: this.options.executablePath,
+			headless: this.options.headless ?? true,
+			userDataDir: this.options.userDataDir,
+			args
+		});
+		this.activePage = (await this.browser.pages())[0] ?? await this.browser.newPage();
+		this.browser.on("targetcreated", (target) => {
+			target.page().then((page) => {
+				if (page) {
+					this.activePage = page;
+					this.log.debug("Active page switched to new target");
+				}
+			}).catch(() => {});
+		});
+		this.browser.on("disconnected", () => {
+			this.browser = null;
+			this.activePage = null;
+		});
+	}
+	/** The current active page, launching Chrome first if needed. */
+	async getActivePage() {
+		await this.ensureLaunched();
+		if (!this.activePage || this.activePage.isClosed()) {
+			if (!this.browser) throw new Error("Browser not available");
+			this.activePage = (await this.browser.pages()).find((p) => !p.isClosed()) ?? await this.browser.newPage();
+		}
+		return this.activePage;
+	}
+	/** Prevent idle shutdown while a viewer or op is active. */
+	addHold() {
+		this.holds += 1;
+		this.clearIdleTimer();
+	}
+	/** Release a hold; arm idle shutdown when the last one is released. */
+	removeHold() {
+		this.holds = Math.max(0, this.holds - 1);
+		if (this.holds === 0) this.armIdleTimer();
+	}
+	/** Reset the idle timer on any activity (only relevant when unheld). */
+	touch() {
+		if (this.holds === 0) this.armIdleTimer();
+	}
+	armIdleTimer() {
+		this.clearIdleTimer();
+		const timer = setTimeout(() => {
+			if (this.holds === 0) {
+				this.log.info("Chrome idle — shutting down (cookies persist on disk)");
+				this.shutdown();
+			}
+		}, this.idleMs);
+		timer.unref();
+		this.idleTimer = timer;
+	}
+	clearIdleTimer() {
+		if (this.idleTimer) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = null;
+		}
+	}
+	async shutdown() {
+		this.clearIdleTimer();
+		const browser = this.browser;
+		this.browser = null;
+		this.activePage = null;
+		if (browser) try {
+			await browser.close();
+		} catch {}
+	}
+};
+//#endregion
+//#region src/screencast-pump.ts
+const noopLogger$1 = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {}
+};
+var ScreencastPump = class {
+	cdp = null;
+	running = false;
+	frameSeq = 0;
+	outstanding = null;
+	log;
+	quality;
+	ackTimeoutMs;
+	constructor(options) {
+		this.options = options;
+		this.log = options.logger ?? noopLogger$1;
+		this.quality = options.quality ?? 70;
+		this.ackTimeoutMs = options.ackTimeoutMs ?? 2e3;
+	}
+	get isRunning() {
+		return this.running;
+	}
+	/** Start (or restart) the screencast on the given page. */
+	async start(page, viewport) {
+		await this.stop();
+		const cdp = await page.createCDPSession();
+		this.cdp = cdp;
+		await cdp.send("Emulation.setDeviceMetricsOverride", {
+			width: viewport.width,
+			height: viewport.height,
+			deviceScaleFactor: viewport.dpr,
+			mobile: false
+		});
+		cdp.on("Page.screencastFrame", (event) => {
+			this.onCdpFrame(event.data, event.sessionId, event.metadata);
+		});
+		await cdp.send("Page.startScreencast", {
+			format: "jpeg",
+			quality: this.quality,
+			maxWidth: Math.round(viewport.width * viewport.dpr),
+			maxHeight: Math.round(viewport.height * viewport.dpr),
+			everyNthFrame: 1
+		});
+		this.running = true;
+		this.log.debug("Screencast started");
+	}
+	onCdpFrame(dataBase64, cdpSessionId, metadata) {
+		if (this.outstanding) this.ackCdp(this.outstanding);
+		const frameSeq = ++this.frameSeq;
+		const meta = {
+			deviceWidth: metadata.deviceWidth ?? 0,
+			deviceHeight: metadata.deviceHeight ?? 0,
+			frameSeq,
+			offsetTop: metadata.offsetTop,
+			pageScaleFactor: metadata.pageScaleFactor,
+			scrollOffsetX: metadata.scrollOffsetX,
+			scrollOffsetY: metadata.scrollOffsetY
+		};
+		const timer = setTimeout(() => {
+			if (this.outstanding?.frameSeq === frameSeq) this.ackCdp(this.outstanding);
+		}, this.ackTimeoutMs);
+		timer.unref();
+		this.outstanding = {
+			cdpSessionId,
+			frameSeq,
+			timer
+		};
+		this.options.onFrame(Buffer.from(dataBase64, "base64"), meta);
+	}
+	/** Viewer acked frame `frameSeq` — release Chrome to send the next frame. */
+	ackFromViewer(frameSeq) {
+		if (this.outstanding?.frameSeq === frameSeq) this.ackCdp(this.outstanding);
+	}
+	ackCdp(outstanding) {
+		clearTimeout(outstanding.timer);
+		this.outstanding = null;
+		if (this.cdp && this.running) this.cdp.send("Page.screencastFrameAck", { sessionId: outstanding.cdpSessionId }).catch(() => {});
+	}
+	async stop() {
+		this.running = false;
+		if (this.outstanding) {
+			clearTimeout(this.outstanding.timer);
+			this.outstanding = null;
+		}
+		const cdp = this.cdp;
+		this.cdp = null;
+		if (cdp) {
+			try {
+				await cdp.send("Page.stopScreencast");
+			} catch {}
+			try {
+				await cdp.detach();
+			} catch {}
+		}
+	}
+};
+//#endregion
+//#region src/input-injector.ts
+const MOUSE_TYPE = {
+	mousemoved: "mouseMoved",
+	mousepressed: "mousePressed",
+	mousereleased: "mouseReleased"
+};
+var InputInjector = class {
+	cdp = null;
+	viewport;
+	constructor(viewport) {
+		this.viewport = viewport;
+	}
+	async attach(page) {
+		await this.detach();
+		this.cdp = await page.createCDPSession();
+	}
+	async detach() {
+		const cdp = this.cdp;
+		this.cdp = null;
+		if (cdp) try {
+			await cdp.detach();
+		} catch {}
+	}
+	updateViewport(viewport) {
+		this.viewport = viewport;
+	}
+	toCssPx(nx, ny) {
+		return {
+			x: Math.round(clamp01(nx) * this.viewport.width),
+			y: Math.round(clamp01(ny) * this.viewport.height)
+		};
+	}
+	mouse(p) {
+		if (!this.cdp) return;
+		const { x, y } = this.toCssPx(p.nx, p.ny);
+		this.cdp.send("Input.dispatchMouseEvent", {
+			type: MOUSE_TYPE[p.type],
+			x,
+			y,
+			button: p.button ?? "none",
+			buttons: p.buttons ?? 0,
+			clickCount: p.clickCount ?? (p.type === "mousepressed" ? 1 : 0),
+			modifiers: p.modifiers ?? 0
+		}).catch(() => {});
+	}
+	wheel(p) {
+		if (!this.cdp) return;
+		const { x, y } = this.toCssPx(p.nx, p.ny);
+		this.cdp.send("Input.dispatchMouseEvent", {
+			type: "mouseWheel",
+			x,
+			y,
+			deltaX: p.deltaX,
+			deltaY: p.deltaY,
+			modifiers: p.modifiers ?? 0
+		}).catch(() => {});
+	}
+	key(p) {
+		if (!this.cdp) return;
+		if (p.type === "char") {
+			this.cdp.send("Input.dispatchKeyEvent", {
+				type: "char",
+				text: p.text ?? "",
+				modifiers: p.modifiers ?? 0
+			}).catch(() => {});
+			return;
+		}
+		this.cdp.send("Input.dispatchKeyEvent", {
+			type: p.type === "keydown" ? "keyDown" : "keyUp",
+			key: p.key,
+			code: p.code,
+			text: p.type === "keydown" ? p.text : void 0,
+			modifiers: p.modifiers ?? 0
+		}).catch(() => {});
+	}
+};
+function clamp01(n) {
+	if (Number.isNaN(n)) return 0;
+	return Math.max(0, Math.min(1, n));
+}
+//#endregion
+//#region src/automation.ts
+var BrowserAutomation = class {
+	constructor(session, turn, isNavigationAllowed) {
+		this.session = session;
+		this.turn = turn;
+		this.isNavigationAllowed = isNavigationAllowed;
+	}
+	async navigate(url) {
+		await this.turn.acquireAgent();
+		if (!this.isNavigationAllowed(url)) throw new Error(`Navigation to ${url} blocked by SSRF policy`);
+		const page = await this.session.getActivePage();
+		await page.goto(url, { waitUntil: "domcontentloaded" });
+		return {
+			url: page.url(),
+			title: await page.title()
+		};
+	}
+	async click(selector) {
+		await this.turn.acquireAgent();
+		await (await this.session.getActivePage()).click(selector);
+	}
+	async type(selector, text) {
+		await this.turn.acquireAgent();
+		await (await this.session.getActivePage()).type(selector, text);
+	}
+	async waitFor(opts) {
+		await this.turn.acquireAgent();
+		const page = await this.session.getActivePage();
+		if (opts.selector) await page.waitForSelector(opts.selector);
+		else if (opts.urlPattern) {
+			const pattern = opts.urlPattern;
+			await page.waitForFunction((p) => window.location.href.includes(p), {}, pattern);
+		} else if (typeof opts.ms === "number") await new Promise((resolve) => setTimeout(resolve, opts.ms));
+	}
+	/** One-shot JPEG screenshot (base64) for the agent's own reasoning — distinct
+	* from the continuous screencast stream to viewers. */
+	async screenshot() {
+		await this.turn.acquireAgent();
+		return (await this.session.getActivePage()).screenshot({
+			type: "jpeg",
+			quality: 70,
+			encoding: "base64"
+		});
+	}
+	/** Evaluate an expression in the page context via CDP (no eval on our side). */
+	async evaluate(expression) {
+		await this.turn.acquireAgent();
+		const cdp = await (await this.session.getActivePage()).createCDPSession();
+		try {
+			return (await cdp.send("Runtime.evaluate", {
+				expression,
+				returnByValue: true,
+				awaitPromise: true
+			})).result.value;
+		} finally {
+			try {
+				await cdp.detach();
+			} catch {}
+		}
+	}
+};
+//#endregion
+//#region src/browser-surface.ts
+/**
+* BrowserSurface — the `SurfaceHandler` for browser co-browsing. Ties together
+* the shared Chrome (BrowserSession), the screencast pump, the input injector,
+* the agent/human turn-mutex, and the agent automation tools. Viewers watch the
+* live page; the turn token gates who can write.
+*
+* Multiple viewers can attach to one browser; screencast frames broadcast to
+* all, and the pump's ack-gating advances on the first viewer ack (a slow
+* second viewer may drop frames — acceptable for v1).
+*/
+const noopLogger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {}
+};
+var BrowserSurface = class {
+	surface = "browser";
+	session;
+	turn;
+	pump;
+	injector;
+	automation;
+	viewers = /* @__PURE__ */ new Set();
+	viewport = {
+		width: 1280,
+		height: 720,
+		dpr: 1
+	};
+	handoff = null;
+	log;
+	constructor(options, sendFrame) {
+		this.options = options;
+		this.sendFrame = sendFrame;
+		this.log = options.logger ?? noopLogger;
+		this.session = new BrowserSession(options);
+		this.turn = new _alfe_ai_remote.TurnController({ onOwnerChange: () => {
+			this.broadcastState();
+		} });
+		this.pump = new ScreencastPump({
+			onFrame: (jpeg, meta) => {
+				this.broadcastFrame(jpeg, meta);
+			},
+			logger: this.log
+		});
+		this.injector = new InputInjector(this.viewport);
+		this.automation = new BrowserAutomation(this.session, this.turn, options.isNavigationAllowed ?? (() => true));
+	}
+	async openSession(sessionId, open) {
+		this.viewers.add(sessionId);
+		this.session.addHold();
+		if (open.width && open.height) this.viewport = {
+			width: open.width,
+			height: open.height,
+			dpr: open.dpr ?? 1
+		};
+		await this.ensureStreaming();
+		this.sendState(sessionId);
+	}
+	handleFrame(frame) {
+		switch (frame.type) {
+			case _alfe_ai_remote.RemoteFrameType.SCREENCAST_ACK: {
+				const ack = (0, _alfe_ai_remote.decodeJson)(frame.payload);
+				if (ack) this.pump.ackFromViewer(ack.frameSeq);
+				this.session.touch();
+				break;
+			}
+			case _alfe_ai_remote.RemoteFrameType.RESIZE: {
+				const r = (0, _alfe_ai_remote.decodeJson)(frame.payload);
+				if (r) this.applyResize(r.width, r.height, r.dpr ?? 1);
+				break;
+			}
+			case _alfe_ai_remote.RemoteFrameType.INPUT_MOUSE:
+				if (this.turn.humanInControl) {
+					const p = (0, _alfe_ai_remote.decodeJson)(frame.payload);
+					if (p) this.injector.mouse(p);
+				}
+				break;
+			case _alfe_ai_remote.RemoteFrameType.INPUT_WHEEL:
+				if (this.turn.humanInControl) {
+					const p = (0, _alfe_ai_remote.decodeJson)(frame.payload);
+					if (p) this.injector.wheel(p);
+				}
+				break;
+			case _alfe_ai_remote.RemoteFrameType.INPUT_KEY:
+				if (this.turn.humanInControl) {
+					const p = (0, _alfe_ai_remote.decodeJson)(frame.payload);
+					if (p) this.injector.key(p);
+				}
+				break;
+			case _alfe_ai_remote.RemoteFrameType.TAKEOVER_REQUEST:
+				if (this.turn.grantHuman()) this.broadcast(_alfe_ai_remote.RemoteFrameType.TAKEOVER_GRANTED);
+				else this.sendFrame((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
+				break;
+			case _alfe_ai_remote.RemoteFrameType.RELEASE_CONTROL:
+				this.releaseToAgent();
+				break;
+			default: break;
+		}
+	}
+	closeSession(sessionId) {
+		if (!this.viewers.delete(sessionId)) return;
+		this.session.removeHold();
+		if (this.viewers.size === 0) {
+			this.pump.stop();
+			if (this.turn.humanInControl) this.releaseToAgent();
+		}
+	}
+	/**
+	* Agent tool entry point: hand control to the human and block until they
+	* release it (RELEASE_CONTROL) or `timeoutMs` elapses. Resolves with the
+	* final page URL/title so the agent resumes on the same live page.
+	*/
+	async requestHandoff(timeoutMs) {
+		this.turn.grantHuman();
+		this.broadcast(_alfe_ai_remote.RemoteFrameType.TAKEOVER_GRANTED);
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				this.handoff = null;
+				this.turn.releaseHuman();
+				this.broadcast(_alfe_ai_remote.RemoteFrameType.CONTROL_REVOKED);
+				this.currentPageInfo().then(({ url, title }) => {
+					resolve({
+						released: false,
+						timedOut: true,
+						url,
+						title
+					});
+				});
+			}, timeoutMs);
+			timer.unref();
+			this.handoff = {
+				resolve,
+				timer
+			};
+		});
+	}
+	async shutdown() {
+		await this.pump.stop();
+		await this.injector.detach();
+		await this.session.shutdown();
+	}
+	releaseToAgent() {
+		this.turn.releaseHuman();
+		const waiter = this.handoff;
+		this.handoff = null;
+		if (waiter) {
+			clearTimeout(waiter.timer);
+			this.currentPageInfo().then(({ url, title }) => {
+				waiter.resolve({
+					released: true,
+					timedOut: false,
+					url,
+					title
+				});
+			});
+		}
+	}
+	async ensureStreaming() {
+		if (this.pump.isRunning || this.viewers.size === 0) return;
+		const page = await this.session.getActivePage();
+		await this.injector.attach(page);
+		this.injector.updateViewport(this.viewport);
+		await this.pump.start(page, this.viewport);
+	}
+	async applyResize(width, height, dpr) {
+		this.viewport = {
+			width,
+			height,
+			dpr
+		};
+		this.injector.updateViewport(this.viewport);
+		if (this.pump.isRunning) {
+			const page = await this.session.getActivePage();
+			await this.pump.start(page, this.viewport);
+		}
+	}
+	broadcastFrame(jpeg, meta) {
+		for (const sessionId of this.viewers) this.sendFrame((0, _alfe_ai_remote.encodeScreencastFrame)(sessionId, meta, jpeg));
+	}
+	broadcast(type) {
+		for (const sessionId of this.viewers) this.sendFrame((0, _alfe_ai_remote.encodeFrame)(type, sessionId));
+	}
+	broadcastState() {
+		for (const sessionId of this.viewers) this.sendState(sessionId);
+	}
+	sendState(sessionId) {
+		this.currentPageInfo().then(({ url, title }) => {
+			const state = {
+				surface: "browser",
+				url,
+				title,
+				controller: this.turn.currentOwner
+			};
+			this.sendFrame((0, _alfe_ai_remote.encodeJsonFrame)(_alfe_ai_remote.RemoteFrameType.SESSION_STATE, sessionId, state));
+		});
+	}
+	async currentPageInfo() {
+		try {
+			const page = await this.session.getActivePage();
+			return {
+				url: page.url(),
+				title: await page.title()
+			};
+		} catch {
+			return {
+				url: "",
+				title: ""
+			};
+		}
+	}
+};
+//#endregion
+exports.BrowserAutomation = BrowserAutomation;
+exports.BrowserSession = BrowserSession;
+exports.BrowserSurface = BrowserSurface;