@alfe.ai/browser 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,232 @@
+import { Page } from "puppeteer-core";
+
+//#region ../remote/dist/index.d.ts
+
+declare const RemoteFrameType: {
+  /** viewer→plugin: a viewer attached. Payload: SessionOpenPayload. */
+  readonly SESSION_OPEN: 1;
+  /** either direction: a viewer detached / session torn down. */
+  readonly SESSION_CLOSE: 2;
+  /** plugin→viewer: current surface state. Payload: SessionStatePayload. */
+  readonly SESSION_STATE: 3;
+  /** plugin→viewer (browser): the page navigated. Payload: { url }. */
+  readonly NAVIGATION: 4;
+  /** plugin→viewer: [metaLen:u16BE][meta JSON][raw JPEG]. */
+  readonly SCREENCAST_FRAME: 16;
+  /** viewer→plugin: { frameSeq } — drives ack-gated backpressure. */
+  readonly SCREENCAST_ACK: 17;
+  readonly INPUT_MOUSE: 32;
+  readonly INPUT_WHEEL: 33;
+  readonly INPUT_KEY: 34;
+  /** viewer→plugin: { width, height, dpr }. */
+  readonly RESIZE: 35;
+  readonly TAKEOVER_REQUEST: 48;
+  readonly TAKEOVER_GRANTED: 49;
+  readonly TAKEOVER_DENIED: 50;
+  readonly RELEASE_CONTROL: 51;
+  readonly CONTROL_REVOKED: 52;
+  /** plugin→viewer: raw PTY output bytes. */
+  readonly TERMINAL_DATA: 64;
+  /** viewer→plugin: raw keystroke bytes. */
+  readonly TERMINAL_INPUT: 65;
+  /** viewer→plugin: { cols, rows }. */
+  readonly TERMINAL_RESIZE: 66;
+};
+type RemoteFrameType = (typeof RemoteFrameType)[keyof typeof RemoteFrameType];
+type RemoteSurface = "browser" | "terminal";
+interface RemoteFrame {
+  type: RemoteFrameType;
+  sessionId: number;
+  payload: Buffer;
+}
+interface SessionOpenPayload {
+  surface: RemoteSurface;
+  /** Browser: initial viewport in device pixels. */
+  width?: number;
+  height?: number;
+  dpr?: number;
+  /** Terminal: initial PTY dimensions. */
+  cols?: number;
+  rows?: number;
+}
+//#endregion
+//#region src/surface.d.ts
+interface SurfaceHandler {
+  /** Which surface this handler serves. */
+  readonly surface: RemoteSurface;
+  /** A viewer attached — open the surface for this session. */
+  openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
+  /** A subsequent frame for one of this handler's sessions (not SESSION_OPEN). */
+  handleFrame(frame: RemoteFrame): void;
+  /** The viewer detached — tear down this session's resources. */
+  closeSession(sessionId: number): void;
+}
+//#endregion
+//#region src/types.d.ts
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+//#endregion
+//#region src/turn-controller.d.ts
+/**
+ * TurnController — the write-mutex between agent automation and a human during
+ * a browser co-browse handoff. The plugin owns the single CDP session, so this
+ * lives plugin-side; the relay only forwards the control frames.
+ *
+ * Only *writes* are gated — screencast reads always flow so the human sees the
+ * live page regardless of who holds the token. Agent automation ops call
+ * `acquireAgent()` and park while the human is in control; the human's input is
+ * injected only while `owner === 'human'`.
+ */
+type TurnOwner = "agent" | "human";
+interface TurnControllerOptions {
+  /** Fired whenever ownership changes, so the plugin can emit SESSION_STATE. */
+  onOwnerChange?: (owner: TurnOwner) => void;
+}
+declare class TurnController {
+  private owner;
+  private waiters;
+  private readonly onOwnerChange?;
+  constructor(options?: TurnControllerOptions);
+  get currentOwner(): TurnOwner;
+  get humanInControl(): boolean;
+  /**
+   * 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.
+   */
+  acquireAgent(): 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
+   * at its next `acquireAgent()`.
+   */
+  grantHuman(): boolean;
+  /** Return control to the agent and drain any parked automation ops. */
+  releaseHuman(): void;
+  private setOwner;
+}
+//#endregion
+//#endregion
+//#region src/types.d.ts
+interface BrowserSessionOptions {
+  /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
+  executablePath: string;
+  /** Persistent profile dir so cookies/login survive process restarts. */
+  userDataDir: string;
+  /** Headless mode (default true). */
+  headless?: boolean;
+  /** Pass --no-sandbox (needed on most managed Linux VMs). */
+  noSandbox?: boolean;
+  /** Shut Chrome down after this many ms with no holds/activity (default 5 min). */
+  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.
+   */
+  isNavigationAllowed?: (url: string) => boolean;
+}
+//#endregion
+//#region src/browser-session.d.ts
+declare class BrowserSession {
+  private readonly options;
+  private browser;
+  private activePage;
+  private launching;
+  private holds;
+  private idleTimer;
+  private readonly log;
+  private readonly idleMs;
+  constructor(options: BrowserSessionOptions);
+  /** Launch Chrome if not already running (idempotent, concurrent-safe). */
+  ensureLaunched(): Promise<void>;
+  private doLaunch;
+  /** The current active page, launching Chrome first if needed. */
+  getActivePage(): Promise<Page>;
+  /** Prevent idle shutdown while a viewer or op is active. */
+  addHold(): void;
+  /** Release a hold; arm idle shutdown when the last one is released. */
+  removeHold(): void;
+  /** Reset the idle timer on any activity (only relevant when unheld). */
+  touch(): void;
+  private armIdleTimer;
+  private clearIdleTimer;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/automation.d.ts
+interface NavigateResult {
+  url: string;
+  title: string;
+}
+declare class BrowserAutomation {
+  private readonly session;
+  private readonly turn;
+  private readonly isNavigationAllowed;
+  constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
+  navigate(url: string): Promise<NavigateResult>;
+  click(selector: string): Promise<void>;
+  type(selector: string, text: string): Promise<void>;
+  waitFor(opts: {
+    selector?: string;
+    ms?: number;
+    urlPattern?: string;
+  }): Promise<void>;
+  /** One-shot JPEG screenshot (base64) for the agent's own reasoning — distinct
+   * from the continuous screencast stream to viewers. */
+  screenshot(): Promise<string>;
+  /** Evaluate an expression in the page context via CDP (no eval on our side). */
+  evaluate(expression: string): Promise<unknown>;
+}
+//#endregion
+//#region src/browser-surface.d.ts
+interface HandoffResult {
+  released: boolean;
+  timedOut: boolean;
+  url: string;
+  title: string;
+}
+declare class BrowserSurface implements SurfaceHandler {
+  private readonly options;
+  private readonly sendFrame;
+  readonly surface: "browser";
+  private readonly session;
+  private readonly turn;
+  private readonly pump;
+  private readonly injector;
+  readonly automation: BrowserAutomation;
+  private readonly viewers;
+  private viewport;
+  private handoff;
+  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.
+   */
+  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  shutdown(): Promise<void>;
+  private releaseToAgent;
+  private ensureStreaming;
+  private applyResize;
+  private broadcastFrame;
+  private broadcast;
+  private broadcastState;
+  private sendState;
+  private currentPageInfo;
+}
+//#endregion
+export { BrowserAutomation, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { Page } from "puppeteer-core";
+
+//#region ../remote/dist/index.d.ts
+
+declare const RemoteFrameType: {
+  /** viewer→plugin: a viewer attached. Payload: SessionOpenPayload. */
+  readonly SESSION_OPEN: 1;
+  /** either direction: a viewer detached / session torn down. */
+  readonly SESSION_CLOSE: 2;
+  /** plugin→viewer: current surface state. Payload: SessionStatePayload. */
+  readonly SESSION_STATE: 3;
+  /** plugin→viewer (browser): the page navigated. Payload: { url }. */
+  readonly NAVIGATION: 4;
+  /** plugin→viewer: [metaLen:u16BE][meta JSON][raw JPEG]. */
+  readonly SCREENCAST_FRAME: 16;
+  /** viewer→plugin: { frameSeq } — drives ack-gated backpressure. */
+  readonly SCREENCAST_ACK: 17;
+  readonly INPUT_MOUSE: 32;
+  readonly INPUT_WHEEL: 33;
+  readonly INPUT_KEY: 34;
+  /** viewer→plugin: { width, height, dpr }. */
+  readonly RESIZE: 35;
+  readonly TAKEOVER_REQUEST: 48;
+  readonly TAKEOVER_GRANTED: 49;
+  readonly TAKEOVER_DENIED: 50;
+  readonly RELEASE_CONTROL: 51;
+  readonly CONTROL_REVOKED: 52;
+  /** plugin→viewer: raw PTY output bytes. */
+  readonly TERMINAL_DATA: 64;
+  /** viewer→plugin: raw keystroke bytes. */
+  readonly TERMINAL_INPUT: 65;
+  /** viewer→plugin: { cols, rows }. */
+  readonly TERMINAL_RESIZE: 66;
+};
+type RemoteFrameType = (typeof RemoteFrameType)[keyof typeof RemoteFrameType];
+type RemoteSurface = "browser" | "terminal";
+interface RemoteFrame {
+  type: RemoteFrameType;
+  sessionId: number;
+  payload: Buffer;
+}
+interface SessionOpenPayload {
+  surface: RemoteSurface;
+  /** Browser: initial viewport in device pixels. */
+  width?: number;
+  height?: number;
+  dpr?: number;
+  /** Terminal: initial PTY dimensions. */
+  cols?: number;
+  rows?: number;
+}
+//#endregion
+//#region src/surface.d.ts
+interface SurfaceHandler {
+  /** Which surface this handler serves. */
+  readonly surface: RemoteSurface;
+  /** A viewer attached — open the surface for this session. */
+  openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
+  /** A subsequent frame for one of this handler's sessions (not SESSION_OPEN). */
+  handleFrame(frame: RemoteFrame): void;
+  /** The viewer detached — tear down this session's resources. */
+  closeSession(sessionId: number): void;
+}
+//#endregion
+//#region src/types.d.ts
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+//#endregion
+//#region src/turn-controller.d.ts
+/**
+ * TurnController — the write-mutex between agent automation and a human during
+ * a browser co-browse handoff. The plugin owns the single CDP session, so this
+ * lives plugin-side; the relay only forwards the control frames.
+ *
+ * Only *writes* are gated — screencast reads always flow so the human sees the
+ * live page regardless of who holds the token. Agent automation ops call
+ * `acquireAgent()` and park while the human is in control; the human's input is
+ * injected only while `owner === 'human'`.
+ */
+type TurnOwner = "agent" | "human";
+interface TurnControllerOptions {
+  /** Fired whenever ownership changes, so the plugin can emit SESSION_STATE. */
+  onOwnerChange?: (owner: TurnOwner) => void;
+}
+declare class TurnController {
+  private owner;
+  private waiters;
+  private readonly onOwnerChange?;
+  constructor(options?: TurnControllerOptions);
+  get currentOwner(): TurnOwner;
+  get humanInControl(): boolean;
+  /**
+   * 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.
+   */
+  acquireAgent(): 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
+   * at its next `acquireAgent()`.
+   */
+  grantHuman(): boolean;
+  /** Return control to the agent and drain any parked automation ops. */
+  releaseHuman(): void;
+  private setOwner;
+}
+//#endregion
+//#endregion
+//#region src/types.d.ts
+interface BrowserSessionOptions {
+  /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
+  executablePath: string;
+  /** Persistent profile dir so cookies/login survive process restarts. */
+  userDataDir: string;
+  /** Headless mode (default true). */
+  headless?: boolean;
+  /** Pass --no-sandbox (needed on most managed Linux VMs). */
+  noSandbox?: boolean;
+  /** Shut Chrome down after this many ms with no holds/activity (default 5 min). */
+  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.
+   */
+  isNavigationAllowed?: (url: string) => boolean;
+}
+//#endregion
+//#region src/browser-session.d.ts
+declare class BrowserSession {
+  private readonly options;
+  private browser;
+  private activePage;
+  private launching;
+  private holds;
+  private idleTimer;
+  private readonly log;
+  private readonly idleMs;
+  constructor(options: BrowserSessionOptions);
+  /** Launch Chrome if not already running (idempotent, concurrent-safe). */
+  ensureLaunched(): Promise<void>;
+  private doLaunch;
+  /** The current active page, launching Chrome first if needed. */
+  getActivePage(): Promise<Page>;
+  /** Prevent idle shutdown while a viewer or op is active. */
+  addHold(): void;
+  /** Release a hold; arm idle shutdown when the last one is released. */
+  removeHold(): void;
+  /** Reset the idle timer on any activity (only relevant when unheld). */
+  touch(): void;
+  private armIdleTimer;
+  private clearIdleTimer;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/automation.d.ts
+interface NavigateResult {
+  url: string;
+  title: string;
+}
+declare class BrowserAutomation {
+  private readonly session;
+  private readonly turn;
+  private readonly isNavigationAllowed;
+  constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
+  navigate(url: string): Promise<NavigateResult>;
+  click(selector: string): Promise<void>;
+  type(selector: string, text: string): Promise<void>;
+  waitFor(opts: {
+    selector?: string;
+    ms?: number;
+    urlPattern?: string;
+  }): Promise<void>;
+  /** One-shot JPEG screenshot (base64) for the agent's own reasoning — distinct
+   * from the continuous screencast stream to viewers. */
+  screenshot(): Promise<string>;
+  /** Evaluate an expression in the page context via CDP (no eval on our side). */
+  evaluate(expression: string): Promise<unknown>;
+}
+//#endregion
+//#region src/browser-surface.d.ts
+interface HandoffResult {
+  released: boolean;
+  timedOut: boolean;
+  url: string;
+  title: string;
+}
+declare class BrowserSurface implements SurfaceHandler {
+  private readonly options;
+  private readonly sendFrame;
+  readonly surface: "browser";
+  private readonly session;
+  private readonly turn;
+  private readonly pump;
+  private readonly injector;
+  readonly automation: BrowserAutomation;
+  private readonly viewers;
+  private viewport;
+  private handoff;
+  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.
+   */
+  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  shutdown(): Promise<void>;
+  private releaseToAgent;
+  private ensureStreaming;
+  private applyResize;
+  private broadcastFrame;
+  private broadcast;
+  private broadcastState;
+  private sendState;
+  private currentPageInfo;
+}
+//#endregion
+export { BrowserAutomation, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };