@reticlehq/server 2.14.0 → 3.2.0

package/dist/pool/browser-pool.d.ts

@@ -1,282 +0,0 @@
-/**
- * BrowserPool — one headless browser, many cheap isolated contexts.
- *
- * The "10 agents test 10 flows" scenario does NOT mean 10 Chromiums (each ~hundreds of MB). It means
- * ONE launched browser and N `newContext` calls (each ~a few MB, fully isolated cookies/storage).
- * The pool owns that single browser, hands out per-flow leases, caps concurrency so a machine is
- * never overwhelmed (over-cap acquires queue FIFO), and transparently relaunches if the browser dies.
- *
- * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
- * the thin Playwright adapter that satisfies these interfaces lives separately.
- */
-/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
-import { type SeedStorage } from '@reticlehq/core';
-export interface PooledPage {
-    goto(url: string, opts?: {
-        timeoutMs?: number;
-    }): Promise<unknown>;
-    close(): Promise<void>;
-    /** Fires when THIS page's renderer crashes — lets the pool reclaim just this lease, not the fleet. */
-    onCrash(handler: () => void): void;
-    /**
-     * Fires for each console message the page logs. OPTIONAL: a fake that does not implement it makes
-     * the pool record nothing, which is the correct degradation — an absent dial address must read as
-     * "the page said nothing", never as "the page dialled correctly".
-     */
-    onConsole?(handler: (text: string) => void): void;
-    /**
-     * Capture the page as a PNG. OPTIONAL, like `onConsole`: a fake that does not implement it makes
-     * the pool report "no provider", which is the correct degradation — an absent screenshotter must
-     * read as "this context cannot be captured", never as a blank image that a visual diff would then
-     * compare against and pass.
-     */
-    screenshot?(opts?: {
-        fullPage?: boolean;
-    }): Promise<Uint8Array>;
-    /**
-     * Move the real pointer to (x, y) so CSS `:hover` applies. OPTIONAL, like `screenshot`: a fake
-     * that does not implement it makes hover refuse rather than dispatch a synthetic mouseover that
-     * reports dispatched/settled while the styles never ran.
-     */
-    hover?(x: number, y: number): Promise<void>;
-    /** Add an init script to run after document creation but before any page scripts run. */
-    addInitScript?<Arg>(script: ((arg: Arg) => void) | string, arg?: Arg): Promise<InitScriptHandle | void>;
-    /**
-     * Install (or clear) network mocks on this page. OPTIONAL: a fake that does not implement it
-     * makes `reticle_network_mock` refuse rather than claiming it stubbed a request it cannot intercept.
-     */
-    installMocks?(rules: readonly PooledMockRule[]): Promise<void>;
-    /**
-     * Resize this page's viewport. OPTIONAL, like `installMocks`: a fake that does not implement it
-     * makes `reticle_viewport` refuse rather than claim a resize the page never took.
-     *
-     * A lease IS a real browser page, so the resize was always possible — the tool simply had no route
-     * to it and consulted only the driven-provider path. On an SDK-only install there is no such
-     * provider, so mobile-only UI (a `lg:hidden` hamburger, a drawer that only mounts under a
-     * breakpoint) could not be driven at all without installing Playwright separately.
-     */
-    setViewport?(size: {
-        width: number;
-        height: number;
-    }): Promise<void>;
-    /**
-     * Fires when the page opens a native `window.confirm`/`alert`/`prompt`. OPTIONAL, like `onConsole`:
-     * a fake that does not implement it means the pool cannot see or arbitrate the dialog, and the
-     * page is left to whatever the underlying engine does with no listener attached.
-     *
-     * The pool always dismisses on this handler (see `acquire`) — a page blocked on a native dialog
-     * previously wedged the whole session (every subsequent tool call timed out and no recovery
-     * existed short of restarting the daemon), because nothing in the stack ever answered it.
-     */
-    onDialog?(handler: (dialog: PooledDialog) => void): void;
-}
-/** A native dialog the page opened, handed to the pool so it can be dismissed instead of left blocking. */
-export interface PooledDialog {
-    /** The dialog's message text — kept for diagnostics (`BrowserPool#lastDialogMessage`). */
-    readonly message: string;
-    dismiss(): Promise<void>;
-}
-export interface InitScriptHandle {
-    dispose(): Promise<void>;
-}
-export interface PooledCookie {
-    name: string;
-    value: string;
-    url?: string;
-    domain?: string;
-    path?: string;
-    expires?: number;
-    httpOnly?: boolean;
-    secure?: boolean;
-    sameSite?: 'Strict' | 'Lax' | 'None';
-}
-/**
- * One interception rule the pool can install. Same fields as the drive-path mock rule, kept here so
- * the pool does not import Playwright.
- */
-export interface PooledMockRule {
-    urlContains: string;
-    method?: string;
-    status?: number;
-    body?: string;
-    contentType?: string;
-    delayMs?: number;
-    abort?: boolean;
-}
-/** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
-export interface PooledContext {
-    newPage(): Promise<PooledPage>;
-    close(): Promise<void>;
-    addCookies?(cookies: PooledCookie[]): Promise<void>;
-}
-/** The launched browser. Real Playwright `Browser` satisfies this. */
-export interface PooledBrowser {
-    isConnected(): boolean;
-    newContext(): Promise<PooledContext>;
-    close(): Promise<void>;
-    /** Fires when the browser process dies/crashes so the pool can relaunch on the next acquire. */
-    onDisconnected(handler: () => void): void;
-}
-/** Produces a freshly launched browser. Injected so tests can supply a fake. */
-export type Launcher = () => Promise<PooledBrowser>;
-/** A leased context+page for one flow. `release` frees the slot and closes the context. */
-export interface Lease {
-    readonly sessionId: string;
-    readonly url: string;
-    readonly navStatus?: number;
-    release(): Promise<void>;
-}
-/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
-export declare const DEFAULT_LEASE_TTL_MS: number;
-interface BrowserPoolOptions {
-    /** Max simultaneous leased contexts. Over-cap acquires queue. */
-    maxContexts: number;
-    /** Stable id generator for lease sessionIds (injected to stay clock-/random-free in logic). */
-    genSessionId: () => string;
-    /** Injected clock (ms). Defaults to Date.now; tests pass a controllable one. */
-    now?: () => number;
-    /** A lease untouched for longer than this is reclaimed by sweepExpired. */
-    leaseTtlMs?: number;
-    /** Per-lease navigation timeout — a page that won't load fails its own lease, never blocks a slot. */
-    navTimeoutMs?: number;
-}
-/**
- * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.
- * Not exported as a singleton — the daemon owns one instance.
- */
-export declare class BrowserPool {
-    #private;
-    constructor(launch: Launcher, opts: BrowserPoolOptions);
-    /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
-    leaseTtlMs(): number;
-    /** Max simultaneous leases — the ceiling the parallel suite sizes its concurrency to. */
-    capacity(): number;
-    activeCount(): number;
-    /** Acquires waiting for a free slot. */
-    queuedCount(): number;
-    /** The sessionIds of every currently leased context — used to report/group leased sessions. */
-    leasedSessionIds(): string[];
-    /**
-     * The public session id of an active lease on this origin, if we already hold one.
-     *
-     * The lease TOOL reuses that id instead of minting a second context: a second acquire on the same
-     * origin used to leave both tabs connected and poison default session resolution (#600). The pool's
-     * own `acquire` still mints — the parallel suite needs isolation on purpose.
-     *
-     * Prefers the alias the agent was given, when the app registered under its own name.
-     */
-    leaseIdOnOrigin(origin: string): string | undefined;
-    /**
-     * Release a lease by its sessionId (closes the context, frees the slot). No-op if unknown.
-     *
-     * Resolves an alias first, because the agent releases with the id it was GIVEN, which for an app
-     * that named its own session is not the id the pool navigated with. Releasing by that name used to
-     * be a silent no-op that left the slot held until the reaper took it.
-     */
-    release(sessionId: string): Promise<void>;
-    /**
-     * Record that a lease is also known by the name the APP registered.
-     *
-     * Leases are keyed by the id the pool navigated with, and the SDK normally adopts that id off the
-     * URL so the two agree. An app that passes an explicit `session` to `connect()` keeps its own name
-     * instead, which is legitimate, and the lease tool then hands the agent THAT name because it is the
-     * one it has to drive with. Every later touch and release arrives under it.
-     *
-     * Without this the touches hit nothing, the lease ages out despite continuous activity, and the
-     * reaper closes the context mid-flow — the failure in #157, where a session died on the very call
-     * that would have read a computed value.
-     */
-    alias(registeredId: string, leaseId: string): void;
-    /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
-    touch(sessionId: string): void;
-    /**
-     * Reclaim leases untouched for longer than the TTL — a hung/crashed agent never holds a slot
-     * forever. Returns the released sessionIds. This is the fault-tolerance backstop for the pool.
-     */
-    /**
-     * Capture a leased page, or undefined when this session is not a lease or cannot be captured.
-     *
-     * A lease IS a real browser page, so the pixels were always available — the visual tools simply had
-     * no route to them and answered "no provider" for every context an agent can actually get. That
-     * made visual regression impossible on exactly the isolated contexts the pool exists to hand out.
-     *
-     * Touches the lease like any other tool call, so capturing keeps it alive rather than letting the
-     * reaper take it out from under a diff.
-     */
-    screenshotLease(sessionId: string, opts?: {
-        fullPage?: boolean;
-    }): Promise<Uint8Array | undefined>;
-    /**
-     * Move the real pointer on a leased page, or false when this session is not a lease or cannot
-     * hover. Same optional-capability contract as screenshotLease: absence must read as "could not
-     * hover", never as a successful dispatch of a synthetic mouseover.
-     *
-     * Touches the lease like any other tool call, so hovering keeps it alive.
-     */
-    hoverLease(sessionId: string, x: number, y: number): Promise<boolean>;
-    /**
-     * Install network mocks on a leased page, or false when this session is not a lease or cannot
-     * intercept. Same optional-capability contract as screenshotLease: absence must read as "could not
-     * mock", never as a stub that applied to nothing.
-     *
-     * Touches the lease like any other tool call, so mocking keeps it alive.
-     */
-    /**
-     * Resize a leased page's viewport, or report that this page cannot be resized.
-     *
-     * Alias-resolved like every other agent-facing capability — see `#leaseIdOf`.
-     *
-     * Touches the lease like any other tool call, so resizing keeps it alive.
-     */
-    setViewportLease(sessionId: string, size: {
-        width: number;
-        height: number;
-    }): Promise<boolean>;
-    setMocksLease(sessionId: string, rules: readonly PooledMockRule[]): Promise<boolean>;
-    sweepExpired(): Promise<string[]>;
-    /**
-     * How many leases this pool has reclaimed for going stale.
-     *
-     * Kept for reporting. NOT a basis for diagnosis: it is a lifetime total that never resets, so
-     * `count > 0` latches true forever after the first reap. Ask `wasReapedLease` instead, which
-     * answers about a specific session.
-     */
-    reapedLeaseCount(): number;
-    /**
-     * Did THIS session id belong to a lease this pool aged out?
-     *
-     * The question the no-session diagnosis actually has. It used to ask `reapedLeaseCount() > 0`,
-     * which meant that once any lease had ever aged out, every closed human tab for the rest of the
-     * daemon's life was reported as an expired lease — and the recovery that followed
-     * (`reticle_lease {acquire}`) would open an unauthenticated headless context and lose the app
-     * session (#611).
-     *
-     * Only the last {@link MAX_REMEMBERED_REAPED_LEASES} are remembered, so this answers `false` for
-     * a lease reaped long enough ago that thousands have followed. That direction is the safe one:
-     * it falls back to the generic "the tab was closed" wording rather than inventing a lease.
-     */
-    wasReapedLease(sessionId: string): boolean;
-    /**
-     * Lease an isolated context, navigate it to `url`, and return a handle. If the pool is at capacity,
-     * waits FIFO until a slot frees (or until `signal` aborts, if provided).
-     */
-    acquire(url: string, opts?: {
-        signal?: AbortSignal;
-        sessionId?: string;
-        seedStorage?: SeedStorage;
-    }): Promise<Lease>;
-    /**
-     * The websocket address this lease's page reported it could not reach, if it reported one.
-     *
-     * Undefined means the page said nothing — never that it dialled the right place.
-     */
-    dialFailureUrl(sessionId: string): string | undefined;
-    /**
-     * The message of the most recent native dialog (`confirm`/`alert`/`prompt`) auto-dismissed on this
-     * lease, if any. Diagnostic only — the dialog itself is already gone by the time this is readable.
-     */
-    lastDialogMessage(sessionId: string): string | undefined;
-    /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
-    shutdown(): Promise<void>;
-}
-export {};