@alfe.ai/browser 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -125,16 +125,11 @@ interface BrowserSessionOptions {
   idleShutdownMs?: number;
   /** Extra Chrome args. */
   extraArgs?: string[];
-  logger?: Logger;
-}
-interface BrowserSurfaceOptions extends BrowserSessionOptions {
-  /**
-   * Guard consulted before agent-driven or human navigation. Return false to
-   * block (SSRF policy). Defaults to allow-all; Phase 11 wires the integration
-   * SSRF allowlist here.
-   */
+  /** Guard applied to every intercepted HTTP(S) page request. */
   isNavigationAllowed?: (url: string) => boolean;
+  logger?: Logger;
 }
+type BrowserSurfaceOptions = BrowserSessionOptions;
 //#endregion
 //#region src/browser-session.d.ts
 declare class BrowserSession {
@@ -144,14 +139,24 @@ declare class BrowserSession {
   private launching;
   private holds;
   private idleTimer;
+  private generation;
+  private readonly preparedPages;
+  private readonly activePageListeners;
   private readonly log;
   private readonly idleMs;
   constructor(options: BrowserSessionOptions);
   /** 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>;
+  onActivePageChange(listener: (page: Page) => void | Promise<void>): () => void;
   /** Prevent idle shutdown while a viewer or op is active. */
   addHold(): void;
   /** Release a hold; arm idle shutdown when the last one is released. */
@@ -161,6 +166,9 @@ declare class BrowserSession {
   private armIdleTimer;
   private clearIdleTimer;
   shutdown(): Promise<void>;
+  private setActivePage;
+  private preparePage;
+  private isLaunchCurrent;
 }
 //#endregion
 //#region src/automation.d.ts
@@ -172,6 +180,7 @@ declare class BrowserAutomation {
   private readonly session;
   private readonly turn;
   private readonly isNavigationAllowed;
+  private operationTail;
   constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
   navigate(url: string): Promise<NavigateResult>;
   click(selector: string): Promise<void>;
@@ -186,6 +195,9 @@ declare class BrowserAutomation {
   screenshot(): Promise<string>;
   /** Evaluate an expression in the page context via CDP (no eval on our side). */
   evaluate(expression: string): Promise<unknown>;
+  /** Wait until all agent operations that were already queued have settled. */
+  waitUntilIdle(): Promise<void>;
+  private run;
 }
 //#endregion
 //#region src/browser-surface.d.ts
@@ -207,26 +219,53 @@ declare class BrowserSurface implements SurfaceHandler {
   private readonly viewers;
   private viewport;
   private handoff;
+  private controllerSessionId;
+  private pendingControllerSessionId;
+  private streamGeneration;
+  private streamQueue;
+  private closed;
+  private readonly removePageListener;
   private readonly log;
   constructor(options: BrowserSurfaceOptions, sendFrame: (buf: Buffer) => void);
   openSession(sessionId: number, open: SessionOpenPayload): Promise<void>;
   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;
+  private restartStreaming;
+  private enqueueStreamCleanup;
+  private shouldStream;
   private applyResize;
   private broadcastFrame;
   private broadcast;
   private broadcastState;
   private sendState;
   private currentPageInfo;
+  private sendFrameSafe;
 }
 //#endregion
 export { BrowserAutomation, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };

package/dist/index.d.ts

@@ -125,16 +125,11 @@ interface BrowserSessionOptions {
   idleShutdownMs?: number;
   /** Extra Chrome args. */
   extraArgs?: string[];
-  logger?: Logger;
-}
-interface BrowserSurfaceOptions extends BrowserSessionOptions {
-  /**
-   * Guard consulted before agent-driven or human navigation. Return false to
-   * block (SSRF policy). Defaults to allow-all; Phase 11 wires the integration
-   * SSRF allowlist here.
-   */
+  /** Guard applied to every intercepted HTTP(S) page request. */
   isNavigationAllowed?: (url: string) => boolean;
+  logger?: Logger;
 }
+type BrowserSurfaceOptions = BrowserSessionOptions;
 //#endregion
 //#region src/browser-session.d.ts
 declare class BrowserSession {
@@ -144,14 +139,24 @@ declare class BrowserSession {
   private launching;
   private holds;
   private idleTimer;
+  private generation;
+  private readonly preparedPages;
+  private readonly activePageListeners;
   private readonly log;
   private readonly idleMs;
   constructor(options: BrowserSessionOptions);
   /** 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>;
+  onActivePageChange(listener: (page: Page) => void | Promise<void>): () => void;
   /** Prevent idle shutdown while a viewer or op is active. */
   addHold(): void;
   /** Release a hold; arm idle shutdown when the last one is released. */
@@ -161,6 +166,9 @@ declare class BrowserSession {
   private armIdleTimer;
   private clearIdleTimer;
   shutdown(): Promise<void>;
+  private setActivePage;
+  private preparePage;
+  private isLaunchCurrent;
 }
 //#endregion
 //#region src/automation.d.ts
@@ -172,6 +180,7 @@ declare class BrowserAutomation {
   private readonly session;
   private readonly turn;
   private readonly isNavigationAllowed;
+  private operationTail;
   constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
   navigate(url: string): Promise<NavigateResult>;
   click(selector: string): Promise<void>;
@@ -186,6 +195,9 @@ declare class BrowserAutomation {
   screenshot(): Promise<string>;
   /** Evaluate an expression in the page context via CDP (no eval on our side). */
   evaluate(expression: string): Promise<unknown>;
+  /** Wait until all agent operations that were already queued have settled. */
+  waitUntilIdle(): Promise<void>;
+  private run;
 }
 //#endregion
 //#region src/browser-surface.d.ts
@@ -207,26 +219,53 @@ declare class BrowserSurface implements SurfaceHandler {
   private readonly viewers;
   private viewport;
   private handoff;
+  private controllerSessionId;
+  private pendingControllerSessionId;
+  private streamGeneration;
+  private streamQueue;
+  private closed;
+  private readonly removePageListener;
   private readonly log;
   constructor(options: BrowserSurfaceOptions, sendFrame: (buf: Buffer) => void);
   openSession(sessionId: number, open: SessionOpenPayload): Promise<void>;
   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;
+  private restartStreaming;
+  private enqueueStreamCleanup;
+  private shouldStream;
   private applyResize;
   private broadcastFrame;
   private broadcast;
   private broadcastState;
   private sendState;
   private currentPageInfo;
+  private sendFrameSafe;
 }
 //#endregion
 export { BrowserAutomation, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };