@alfe.ai/browser 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -96,9 +96,10 @@ declare class TurnController {
   /**
    * Resolve once the agent is (again) allowed to drive. Resolves immediately if
    * the agent already holds the token; otherwise parks until `releaseHuman()`.
-   * Every automation op awaits this before touching the page.
+   * Every automation op awaits this before touching the page. Cancellation
+   * removes only this waiter and never changes the current human owner.
    */
-  acquireAgent(): Promise<void>;
+  acquireAgent(signal?: AbortSignal): Promise<void>;
   /**
    * Grant control to a human. Succeeds unless a human already holds it (single
    * controller). "Human request always wins over the agent" — the agent parks
@@ -112,6 +113,18 @@ declare class TurnController {
 //#endregion
 //#endregion
 //#region src/types.d.ts
+/** Private local capability for a trusted adapter, never a tool result. */
+interface BrowserOperationContext {
+  /** Loopback Chrome endpoint. Do not log, persist, or expose to a viewer/model. */
+  browserWSEndpoint: string;
+  /** The exact active page's CDP target; never choose the first context/page. */
+  targetId: string;
+  /** On abort, stop and await all external work before returning. */
+  signal: AbortSignal;
+}
+interface BrowserOperationOptions {
+  signal?: AbortSignal;
+}
 interface BrowserSessionOptions {
   /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
   executablePath: string;
@@ -125,16 +138,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,6 +152,9 @@ 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);
@@ -156,8 +167,16 @@ declare class BrowserSession {
    * screencast to a transient `about:blank` throwaway target.
    */
   private adoptIfNavigable;
+  /** A login popup can close while the agent is parked for human control.
+   * Recover here, without waiting for another automation call to discover
+   * that the active page is closed, and rebind the viewer to its opener. */
+  private restoreAfterClose;
   /** The current active page, launching Chrome first if needed. */
   getActivePage(): Promise<Page>;
+  onActivePageChange(listener: (page: Page) => void | Promise<void>): () => void;
+  /** Internal to the serialized automation turn. The caller holds Chrome until
+   * the adapter has disconnected its client/awaited its child process exit. */
+  withCdpTarget<T>(operation: (context: BrowserOperationContext) => Promise<T>, signal: AbortSignal): Promise<T>;
   /** Prevent idle shutdown while a viewer or op is active. */
   addHold(): void;
   /** Release a hold; arm idle shutdown when the last one is released. */
@@ -167,6 +186,9 @@ declare class BrowserSession {
   private armIdleTimer;
   private clearIdleTimer;
   shutdown(): Promise<void>;
+  private setActivePage;
+  private preparePage;
+  private isLaunchCurrent;
 }
 //#endregion
 //#region src/automation.d.ts
@@ -178,6 +200,8 @@ declare class BrowserAutomation {
   private readonly session;
   private readonly turn;
   private readonly isNavigationAllowed;
+  private operationTail;
+  private readonly stopping;
   constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
   navigate(url: string): Promise<NavigateResult>;
   click(selector: string): Promise<void>;
@@ -192,6 +216,17 @@ 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>;
+  /** Trusted local adapters share the built-in automation queue and exact page.
+   * The callback must disconnect/await children in finally, including on abort.
+   * Do not invoke another automation operation or handoff from the callback. */
+  withCdpOperation<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
+  /** Insert the claim at a precise queue position; later automation parks. */
+  yieldToHuman(grant: () => void): Promise<void>;
+  /** Abort first, then await callback cleanup before the owner closes Chrome. */
+  shutdown(): Promise<void>;
+  private run;
 }
 //#endregion
 //#region src/browser-surface.d.ts
@@ -202,7 +237,6 @@ interface HandoffResult {
   title: string;
 }
 declare class BrowserSurface implements SurfaceHandler {
-  private readonly options;
   private readonly sendFrame;
   readonly surface: "browser";
   private readonly session;
@@ -213,6 +247,13 @@ declare class BrowserSurface implements SurfaceHandler {
   private readonly viewers;
   private viewport;
   private handoff;
+  private controllerSessionId;
+  private pendingControllerSessionId;
+  private claimGeneration;
+  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>;
@@ -233,7 +274,7 @@ declare class BrowserSurface implements SurfaceHandler {
    * under the user (mislabeled 409 on the real claim; agent only resuming when
    * the tab closed).
    */
-  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  requestHandoff(timeoutMs: number, signal?: AbortSignal): 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
@@ -244,13 +285,16 @@ declare class BrowserSurface implements SurfaceHandler {
   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 };
+export { BrowserAutomation, type BrowserOperationContext, type BrowserOperationOptions, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };

package/dist/index.d.ts

@@ -96,9 +96,10 @@ declare class TurnController {
   /**
    * Resolve once the agent is (again) allowed to drive. Resolves immediately if
    * the agent already holds the token; otherwise parks until `releaseHuman()`.
-   * Every automation op awaits this before touching the page.
+   * Every automation op awaits this before touching the page. Cancellation
+   * removes only this waiter and never changes the current human owner.
    */
-  acquireAgent(): Promise<void>;
+  acquireAgent(signal?: AbortSignal): Promise<void>;
   /**
    * Grant control to a human. Succeeds unless a human already holds it (single
    * controller). "Human request always wins over the agent" — the agent parks
@@ -112,6 +113,18 @@ declare class TurnController {
 //#endregion
 //#endregion
 //#region src/types.d.ts
+/** Private local capability for a trusted adapter, never a tool result. */
+interface BrowserOperationContext {
+  /** Loopback Chrome endpoint. Do not log, persist, or expose to a viewer/model. */
+  browserWSEndpoint: string;
+  /** The exact active page's CDP target; never choose the first context/page. */
+  targetId: string;
+  /** On abort, stop and await all external work before returning. */
+  signal: AbortSignal;
+}
+interface BrowserOperationOptions {
+  signal?: AbortSignal;
+}
 interface BrowserSessionOptions {
   /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
   executablePath: string;
@@ -125,16 +138,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,6 +152,9 @@ 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);
@@ -156,8 +167,16 @@ declare class BrowserSession {
    * screencast to a transient `about:blank` throwaway target.
    */
   private adoptIfNavigable;
+  /** A login popup can close while the agent is parked for human control.
+   * Recover here, without waiting for another automation call to discover
+   * that the active page is closed, and rebind the viewer to its opener. */
+  private restoreAfterClose;
   /** The current active page, launching Chrome first if needed. */
   getActivePage(): Promise<Page>;
+  onActivePageChange(listener: (page: Page) => void | Promise<void>): () => void;
+  /** Internal to the serialized automation turn. The caller holds Chrome until
+   * the adapter has disconnected its client/awaited its child process exit. */
+  withCdpTarget<T>(operation: (context: BrowserOperationContext) => Promise<T>, signal: AbortSignal): Promise<T>;
   /** Prevent idle shutdown while a viewer or op is active. */
   addHold(): void;
   /** Release a hold; arm idle shutdown when the last one is released. */
@@ -167,6 +186,9 @@ declare class BrowserSession {
   private armIdleTimer;
   private clearIdleTimer;
   shutdown(): Promise<void>;
+  private setActivePage;
+  private preparePage;
+  private isLaunchCurrent;
 }
 //#endregion
 //#region src/automation.d.ts
@@ -178,6 +200,8 @@ declare class BrowserAutomation {
   private readonly session;
   private readonly turn;
   private readonly isNavigationAllowed;
+  private operationTail;
+  private readonly stopping;
   constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
   navigate(url: string): Promise<NavigateResult>;
   click(selector: string): Promise<void>;
@@ -192,6 +216,17 @@ 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>;
+  /** Trusted local adapters share the built-in automation queue and exact page.
+   * The callback must disconnect/await children in finally, including on abort.
+   * Do not invoke another automation operation or handoff from the callback. */
+  withCdpOperation<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
+  /** Insert the claim at a precise queue position; later automation parks. */
+  yieldToHuman(grant: () => void): Promise<void>;
+  /** Abort first, then await callback cleanup before the owner closes Chrome. */
+  shutdown(): Promise<void>;
+  private run;
 }
 //#endregion
 //#region src/browser-surface.d.ts
@@ -202,7 +237,6 @@ interface HandoffResult {
   title: string;
 }
 declare class BrowserSurface implements SurfaceHandler {
-  private readonly options;
   private readonly sendFrame;
   readonly surface: "browser";
   private readonly session;
@@ -213,6 +247,13 @@ declare class BrowserSurface implements SurfaceHandler {
   private readonly viewers;
   private viewport;
   private handoff;
+  private controllerSessionId;
+  private pendingControllerSessionId;
+  private claimGeneration;
+  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>;
@@ -233,7 +274,7 @@ declare class BrowserSurface implements SurfaceHandler {
    * under the user (mislabeled 409 on the real claim; agent only resuming when
    * the tab closed).
    */
-  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  requestHandoff(timeoutMs: number, signal?: AbortSignal): 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
@@ -244,13 +285,16 @@ declare class BrowserSurface implements SurfaceHandler {
   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 };
+export { BrowserAutomation, type BrowserOperationContext, type BrowserOperationOptions, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };