@alfe.ai/browser 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -33,6 +33,14 @@ puppeteer_core = __toESM(puppeteer_core);
 * new tabs are what gets screencast, not a stale main window.
 */
 const DEFAULT_IDLE_MS = 300 * 1e3;
+/**
+* A page target is worth streaming only once it has a real, navigable http(s)
+* URL. Transient `about:blank` (and `chrome://`, `data:`, blank string) targets
+* are throwaways we must not flip the screencast to.
+*/
+function isNavigablePageUrl(url) {
+	return url.startsWith("http://") || url.startsWith("https://");
+}
 const noopLogger$2 = {
 	info: () => {},
 	warn: () => {},
@@ -76,11 +84,13 @@ var BrowserSession = class {
 		});
 		this.activePage = (await this.browser.pages())[0] ?? await this.browser.newPage();
 		this.browser.on("targetcreated", (target) => {
+			if (target.type() !== puppeteer_core.TargetType.PAGE) return;
 			target.page().then((page) => {
-				if (page) {
-					this.activePage = page;
-					this.log.debug("Active page switched to new target");
-				}
+				if (!page) return;
+				if (this.adoptIfNavigable(page)) return;
+				page.on("framenavigated", (frame) => {
+					if (frame === page.mainFrame()) this.adoptIfNavigable(page);
+				});
 			}).catch(() => {});
 		});
 		this.browser.on("disconnected", () => {
@@ -88,6 +98,18 @@ var BrowserSession = class {
 			this.activePage = null;
 		});
 	}
+	/**
+	* Adopt `page` as the streamed active page iff it has a real navigable
+	* http(s) URL. Returns whether it was adopted. Guards against flipping the
+	* screencast to a transient `about:blank` throwaway target.
+	*/
+	adoptIfNavigable(page) {
+		if (page.isClosed() || !isNavigablePageUrl(page.url())) return false;
+		if (this.activePage === page) return true;
+		this.activePage = page;
+		this.log.debug("Active page switched to new target");
+		return true;
+	}
 	/** The current active page, launching Chrome first if needed. */
 	async getActivePage() {
 		await this.ensureLaunched();
@@ -491,18 +513,29 @@ var BrowserSurface = class {
 		}
 	}
 	/**
-	* 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.
+	* Agent tool entry point: PARK the agent and wait for a human to take over
+	* and hand back (RELEASE_CONTROL / viewer teardown after a claim) or for
+	* `timeoutMs` to elapse. Resolves with the final page URL/title so the agent
+	* resumes on the same live page.
+	*
+	* Crucially this does NOT grant the human turn up front. The turn is granted
+	* only when a human ACTUALLY takes control — i.e. when the controlling
+	* (`canControl:true`) viewer sends a `TAKEOVER_REQUEST` frame (see
+	* `handleFrame` → `grantHuman()`). Granting at tool-call time made the session
+	* "human in control" before anyone had claimed, so a read-only viewer's
+	* teardown would fire `releaseToAgent()` and complete the session out from
+	* under the user (mislabeled 409 on the real claim; agent only resuming when
+	* the tab closed).
 	*/
 	async requestHandoff(timeoutMs) {
-		this.turn.grantHuman();
-		this.broadcast(_alfe_ai_remote.RemoteFrameType.TAKEOVER_GRANTED);
+		if (this.handoff) this.releaseToAgent();
 		return new Promise((resolve) => {
 			const timer = setTimeout(() => {
 				this.handoff = null;
-				this.turn.releaseHuman();
-				this.broadcast(_alfe_ai_remote.RemoteFrameType.CONTROL_REVOKED);
+				if (this.turn.humanInControl) {
+					this.turn.releaseHuman();
+					this.broadcast(_alfe_ai_remote.RemoteFrameType.CONTROL_REVOKED);
+				}
 				this.currentPageInfo().then(({ url, title }) => {
 					resolve({
 						released: false,
@@ -519,6 +552,18 @@ var BrowserSurface = class {
 			};
 		});
 	}
+	/**
+	* Keep the shared Chrome alive across an awaiting-human window. Delegates to
+	* the session's hold counter (which also backs per-viewer holds). Idempotent
+	* and leak-safe when paired with {@link removeHold} in a `finally`.
+	*/
+	addHold() {
+		this.session.addHold();
+	}
+	/** Release a hold taken by {@link addHold}. */
+	removeHold() {
+		this.session.removeHold();
+	}
 	async shutdown() {
 		await this.pump.stop();
 		await this.injector.detach();

package/dist/index.d.cts

@@ -150,6 +150,12 @@ declare class BrowserSession {
   /** Launch Chrome if not already running (idempotent, concurrent-safe). */
   ensureLaunched(): Promise<void>;
   private doLaunch;
+  /**
+   * Adopt `page` as the streamed active page iff it has a real navigable
+   * http(s) URL. Returns whether it was adopted. Guards against flipping the
+   * screencast to a transient `about:blank` throwaway target.
+   */
+  private adoptIfNavigable;
   /** The current active page, launching Chrome first if needed. */
   getActivePage(): Promise<Page>;
   /** Prevent idle shutdown while a viewer or op is active. */
@@ -213,11 +219,29 @@ declare class BrowserSurface implements SurfaceHandler {
   handleFrame(frame: RemoteFrame): void;
   closeSession(sessionId: number): void;
   /**
-   * 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.
+   * Agent tool entry point: PARK the agent and wait for a human to take over
+   * and hand back (RELEASE_CONTROL / viewer teardown after a claim) or for
+   * `timeoutMs` to elapse. Resolves with the final page URL/title so the agent
+   * resumes on the same live page.
+   *
+   * Crucially this does NOT grant the human turn up front. The turn is granted
+   * only when a human ACTUALLY takes control — i.e. when the controlling
+   * (`canControl:true`) viewer sends a `TAKEOVER_REQUEST` frame (see
+   * `handleFrame` → `grantHuman()`). Granting at tool-call time made the session
+   * "human in control" before anyone had claimed, so a read-only viewer's
+   * teardown would fire `releaseToAgent()` and complete the session out from
+   * under the user (mislabeled 409 on the real claim; agent only resuming when
+   * the tab closed).
    */
   requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  /**
+   * Keep the shared Chrome alive across an awaiting-human window. Delegates to
+   * the session's hold counter (which also backs per-viewer holds). Idempotent
+   * and leak-safe when paired with {@link removeHold} in a `finally`.
+   */
+  addHold(): void;
+  /** Release a hold taken by {@link addHold}. */
+  removeHold(): void;
   shutdown(): Promise<void>;
   private releaseToAgent;
   private ensureStreaming;

package/dist/index.d.ts

@@ -150,6 +150,12 @@ declare class BrowserSession {
   /** Launch Chrome if not already running (idempotent, concurrent-safe). */
   ensureLaunched(): Promise<void>;
   private doLaunch;
+  /**
+   * Adopt `page` as the streamed active page iff it has a real navigable
+   * http(s) URL. Returns whether it was adopted. Guards against flipping the
+   * screencast to a transient `about:blank` throwaway target.
+   */
+  private adoptIfNavigable;
   /** The current active page, launching Chrome first if needed. */
   getActivePage(): Promise<Page>;
   /** Prevent idle shutdown while a viewer or op is active. */
@@ -213,11 +219,29 @@ declare class BrowserSurface implements SurfaceHandler {
   handleFrame(frame: RemoteFrame): void;
   closeSession(sessionId: number): void;
   /**
-   * 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.
+   * Agent tool entry point: PARK the agent and wait for a human to take over
+   * and hand back (RELEASE_CONTROL / viewer teardown after a claim) or for
+   * `timeoutMs` to elapse. Resolves with the final page URL/title so the agent
+   * resumes on the same live page.
+   *
+   * Crucially this does NOT grant the human turn up front. The turn is granted
+   * only when a human ACTUALLY takes control — i.e. when the controlling
+   * (`canControl:true`) viewer sends a `TAKEOVER_REQUEST` frame (see
+   * `handleFrame` → `grantHuman()`). Granting at tool-call time made the session
+   * "human in control" before anyone had claimed, so a read-only viewer's
+   * teardown would fire `releaseToAgent()` and complete the session out from
+   * under the user (mislabeled 409 on the real claim; agent only resuming when
+   * the tab closed).
    */
   requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  /**
+   * Keep the shared Chrome alive across an awaiting-human window. Delegates to
+   * the session's hold counter (which also backs per-viewer holds). Idempotent
+   * and leak-safe when paired with {@link removeHold} in a `finally`.
+   */
+  addHold(): void;
+  /** Release a hold taken by {@link addHold}. */
+  removeHold(): void;
   shutdown(): Promise<void>;
   private releaseToAgent;
   private ensureStreaming;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { RemoteFrameType, TurnController, decodeJson, encodeFrame, encodeJsonFrame, encodeScreencastFrame } from "@alfe.ai/remote";
-import puppeteer from "puppeteer-core";
+import puppeteer, { TargetType } from "puppeteer-core";
 //#region src/browser-session.ts
 /**
 * BrowserSession — owns the single headless Chrome instance the agent
@@ -9,6 +9,14 @@ import puppeteer from "puppeteer-core";
 * new tabs are what gets screencast, not a stale main window.
 */
 const DEFAULT_IDLE_MS = 300 * 1e3;
+/**
+* A page target is worth streaming only once it has a real, navigable http(s)
+* URL. Transient `about:blank` (and `chrome://`, `data:`, blank string) targets
+* are throwaways we must not flip the screencast to.
+*/
+function isNavigablePageUrl(url) {
+	return url.startsWith("http://") || url.startsWith("https://");
+}
 const noopLogger$2 = {
 	info: () => {},
 	warn: () => {},
@@ -52,11 +60,13 @@ var BrowserSession = class {
 		});
 		this.activePage = (await this.browser.pages())[0] ?? await this.browser.newPage();
 		this.browser.on("targetcreated", (target) => {
+			if (target.type() !== TargetType.PAGE) return;
 			target.page().then((page) => {
-				if (page) {
-					this.activePage = page;
-					this.log.debug("Active page switched to new target");
-				}
+				if (!page) return;
+				if (this.adoptIfNavigable(page)) return;
+				page.on("framenavigated", (frame) => {
+					if (frame === page.mainFrame()) this.adoptIfNavigable(page);
+				});
 			}).catch(() => {});
 		});
 		this.browser.on("disconnected", () => {
@@ -64,6 +74,18 @@ var BrowserSession = class {
 			this.activePage = null;
 		});
 	}
+	/**
+	* Adopt `page` as the streamed active page iff it has a real navigable
+	* http(s) URL. Returns whether it was adopted. Guards against flipping the
+	* screencast to a transient `about:blank` throwaway target.
+	*/
+	adoptIfNavigable(page) {
+		if (page.isClosed() || !isNavigablePageUrl(page.url())) return false;
+		if (this.activePage === page) return true;
+		this.activePage = page;
+		this.log.debug("Active page switched to new target");
+		return true;
+	}
 	/** The current active page, launching Chrome first if needed. */
 	async getActivePage() {
 		await this.ensureLaunched();
@@ -467,18 +489,29 @@ var BrowserSurface = class {
 		}
 	}
 	/**
-	* 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.
+	* Agent tool entry point: PARK the agent and wait for a human to take over
+	* and hand back (RELEASE_CONTROL / viewer teardown after a claim) or for
+	* `timeoutMs` to elapse. Resolves with the final page URL/title so the agent
+	* resumes on the same live page.
+	*
+	* Crucially this does NOT grant the human turn up front. The turn is granted
+	* only when a human ACTUALLY takes control — i.e. when the controlling
+	* (`canControl:true`) viewer sends a `TAKEOVER_REQUEST` frame (see
+	* `handleFrame` → `grantHuman()`). Granting at tool-call time made the session
+	* "human in control" before anyone had claimed, so a read-only viewer's
+	* teardown would fire `releaseToAgent()` and complete the session out from
+	* under the user (mislabeled 409 on the real claim; agent only resuming when
+	* the tab closed).
 	*/
 	async requestHandoff(timeoutMs) {
-		this.turn.grantHuman();
-		this.broadcast(RemoteFrameType.TAKEOVER_GRANTED);
+		if (this.handoff) this.releaseToAgent();
 		return new Promise((resolve) => {
 			const timer = setTimeout(() => {
 				this.handoff = null;
-				this.turn.releaseHuman();
-				this.broadcast(RemoteFrameType.CONTROL_REVOKED);
+				if (this.turn.humanInControl) {
+					this.turn.releaseHuman();
+					this.broadcast(RemoteFrameType.CONTROL_REVOKED);
+				}
 				this.currentPageInfo().then(({ url, title }) => {
 					resolve({
 						released: false,
@@ -495,6 +528,18 @@ var BrowserSurface = class {
 			};
 		});
 	}
+	/**
+	* Keep the shared Chrome alive across an awaiting-human window. Delegates to
+	* the session's hold counter (which also backs per-viewer holds). Idempotent
+	* and leak-safe when paired with {@link removeHold} in a `finally`.
+	*/
+	addHold() {
+		this.session.addHold();
+	}
+	/** Release a hold taken by {@link addHold}. */
+	removeHold() {
+		this.session.removeHold();
+	}
 	async shutdown() {
 		await this.pump.stop();
 		await this.injector.detach();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/browser",
-  "version": "0.1.0",
+  "version": "0.2.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",