@alfe.ai/browser 0.0.0

package/dist/index.js

@@ -0,0 +1,574 @@
+import { RemoteFrameType, TurnController, decodeJson, encodeFrame, encodeJsonFrame, encodeScreencastFrame } from "@alfe.ai/remote";
+import puppeteer from "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.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 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 RemoteFrameType.SCREENCAST_ACK: {
+				const ack = decodeJson(frame.payload);
+				if (ack) this.pump.ackFromViewer(ack.frameSeq);
+				this.session.touch();
+				break;
+			}
+			case RemoteFrameType.RESIZE: {
+				const r = decodeJson(frame.payload);
+				if (r) this.applyResize(r.width, r.height, r.dpr ?? 1);
+				break;
+			}
+			case RemoteFrameType.INPUT_MOUSE:
+				if (this.turn.humanInControl) {
+					const p = decodeJson(frame.payload);
+					if (p) this.injector.mouse(p);
+				}
+				break;
+			case RemoteFrameType.INPUT_WHEEL:
+				if (this.turn.humanInControl) {
+					const p = decodeJson(frame.payload);
+					if (p) this.injector.wheel(p);
+				}
+				break;
+			case RemoteFrameType.INPUT_KEY:
+				if (this.turn.humanInControl) {
+					const p = decodeJson(frame.payload);
+					if (p) this.injector.key(p);
+				}
+				break;
+			case RemoteFrameType.TAKEOVER_REQUEST:
+				if (this.turn.grantHuman()) this.broadcast(RemoteFrameType.TAKEOVER_GRANTED);
+				else this.sendFrame(encodeFrame(RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
+				break;
+			case 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(RemoteFrameType.TAKEOVER_GRANTED);
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				this.handoff = null;
+				this.turn.releaseHuman();
+				this.broadcast(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(encodeScreencastFrame(sessionId, meta, jpeg));
+	}
+	broadcast(type) {
+		for (const sessionId of this.viewers) this.sendFrame(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(encodeJsonFrame(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
+export { BrowserAutomation, BrowserSession, BrowserSurface };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@alfe.ai/browser",
+  "version": "0.0.0",
+  "description": "CDP-driven browser surface for the Alfe interactive remote-control relay — one shared headless Chrome for agent automation + human co-browse takeover",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "puppeteer-core": "^24.0.0",
+    "@alfe.ai/remote": "^0.0.0"
+  },
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}