@reticlehq/server 3.8.0 → 3.8.2

package/dist/portal/pool/browser-pool.js

@@ -17,43 +17,8 @@ import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
 import { grantLeasePermissions, readNotificationPermission } from './context-permissions.js';
 import { readViewport } from './lease-emulation.js';
 import { NotHtmlDocumentError, READER_NOT_HTML } from './zero-install.js';
-/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
-export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
-/**
- * How long a lease outlives the MCP connection that took it. Long enough for an agent whose
- * connection only blipped to touch it again; short enough that a gone agent's window closes soon.
- */
-export const ORPHANED_LEASE_GRACE_MS = 30_000;
-/** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
-const DEFAULT_NAV_TIMEOUT_MS = 30_000;
-/**
- * How many reaped lease ids to remember. Only the most recent departure is ever asked about, so
- * this is slack for a burst sweep, not a history.
- */
-const MAX_REMEMBERED_REAPED_LEASES = 64;
-/** What a headed lease is refused with where no window can be opened. */
-export const NO_HEADED_BROWSER = 'no headed browser can be opened here';
-/**
- * An acquire that asked to be refused rather than queued found every slot taken (#1535). Queued,
- * it waited behind the cap with no deadline and no status, and `reticle drive` reported the 60 s
- * timeout as a daemon shutting down. The message names the cap and the one override for it.
- */
-export class PoolAtCapacityError extends Error {
-    max;
-    constructor(max) {
-        super(`all ${String(max)} lease slots are in use. Release one (reticle_lease{action:"release"}, or ` +
-            'stop a `reticle drive`), or raise RETICLE_MAX_CONTEXTS.');
-        this.max = max;
-        this.name = 'PoolAtCapacityError';
-    }
-}
-/**
- * What an acquire that asked for an init script is refused with when the page cannot run one.
- *
- * A refusal rather than a lease: the caller asked for a stub of the bindings a desktop shell
- * injects, and a tab opened without it would throw in the app's view and read as a broken app.
- */
-const INIT_SCRIPT_UNSUPPORTED = 'Init script failed: this page does not support init scripts, so the requested stub would not be there';
+import { DEFAULT_LEASE_TTL_MS, DEFAULT_NAV_TIMEOUT_MS, INIT_SCRIPT_UNSUPPORTED, MAX_REMEMBERED_REAPED_LEASES, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, pageLoading, PoolAtCapacityError, } from './pool-lease.js';
+export { DEFAULT_LEASE_TTL_MS, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, PoolAtCapacityError, } from './pool-lease.js';
 /**
  * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
  * capped at `maxContexts` across both.
@@ -97,8 +62,9 @@ export class BrowserPool {
     /** FIFO of acquires waiting for a slot; each resolves when one frees. */
     #waiters = [];
     constructor(launch, opts) {
-        if (opts.maxContexts < 1)
+        if (opts.maxContexts < 1) {
             throw new Error('maxContexts must be >= 1');
+        }
         this.#headless = { launch, headed: false };
         this.#headed = { launch: opts.launchHeaded, headed: true };
         this.#max = opts.maxContexts;
@@ -139,11 +105,13 @@ export class BrowserPool {
      * Prefers the alias the agent was given, when the app registered under its own name.
      */
     leaseIdOnOrigin(origin, owner) {
-        if (owner === undefined)
+        if (owner === undefined) {
             return undefined;
+        }
         for (const [leaseId, lease] of this.#active) {
-            if (lease.owner !== owner)
+            if (lease.owner !== owner) {
                 continue;
+            }
             let leaseOrigin;
             try {
                 leaseOrigin = new URL(lease.url).origin;
@@ -151,11 +119,13 @@ export class BrowserPool {
             catch {
                 continue;
             }
-            if (leaseOrigin !== origin)
+            if (leaseOrigin !== origin) {
                 continue;
+            }
             for (const [alias, id] of this.#aliases) {
-                if (id === leaseId)
+                if (id === leaseId) {
                     return alias;
+                }
             }
             return leaseId;
         }
@@ -184,10 +154,12 @@ export class BrowserPool {
      * that would have read a computed value.
      */
     alias(registeredId, leaseId) {
-        if (registeredId === leaseId)
+        if (registeredId === leaseId) {
             return;
-        if (!this.#active.has(leaseId))
+        }
+        if (!this.#active.has(leaseId)) {
             return;
+        }
         this.#aliases.set(registeredId, leaseId);
     }
     /**
@@ -225,8 +197,9 @@ export class BrowserPool {
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined)
+        if (lease === undefined) {
             return;
+        }
         lease.touchedAt = this.#now();
         delete lease.detachedAt;
     }
@@ -237,9 +210,11 @@ export class BrowserPool {
      */
     detachOwner(owner) {
         const now = this.#now();
-        for (const lease of this.#active.values())
-            if (lease.owner === owner)
+        for (const lease of this.#active.values()) {
+            if (lease.owner === owner) {
                 lease.detachedAt = now;
+            }
+        }
     }
     /**
      * The MCP connection `owner` came back: a proxy that reconnects keeps its id. Its leases stop
@@ -268,8 +243,9 @@ export class BrowserPool {
      */
     async screenshotLease(sessionId, opts = {}) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined || lease.page.screenshot === undefined)
+        if (lease === undefined || lease.page.screenshot === undefined) {
             return undefined;
+        }
         this.touch(sessionId);
         try {
             return await lease.page.screenshot(opts);
@@ -291,8 +267,9 @@ export class BrowserPool {
      */
     async gotoLease(sessionId, url, timeoutMs) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined)
+        if (lease === undefined) {
             return false;
+        }
         this.touch(sessionId);
         try {
             await lease.page.goto(url, timeoutMs === undefined ? {} : { timeoutMs });
@@ -311,8 +288,9 @@ export class BrowserPool {
      */
     async hoverLease(sessionId, x, y) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined || lease.page.hover === undefined)
+        if (lease === undefined || lease.page.hover === undefined) {
             return false;
+        }
         this.touch(sessionId);
         try {
             await lease.page.hover(x, y);
@@ -325,8 +303,9 @@ export class BrowserPool {
     /** Set a live lease's media features, or false when this is not a lease or its page cannot. */
     async emulateLease(sessionId, media) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease?.page.emulateMedia === undefined)
+        if (lease?.page.emulateMedia === undefined) {
             return false;
+        }
         this.touch(sessionId);
         try {
             await lease.page.emulateMedia(media);
@@ -336,6 +315,14 @@ export class BrowserPool {
             return false;
         }
     }
+    /** Whether this lease's page is still loading. False for a non-lease, or a page that cannot say. */
+    async leaseLoading(sessionId) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease === undefined) {
+            return false;
+        }
+        return pageLoading(lease.page).catch(() => false);
+    }
     /** Whether this session is a lease whose page has a real keyboard. */
     hasKeyboard(sessionId) {
         return this.#active.get(this.#leaseIdOf(sessionId))?.page.press !== undefined;
@@ -347,8 +334,9 @@ export class BrowserPool {
      */
     async pressLease(sessionId, args) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease?.page.press === undefined)
+        if (lease?.page.press === undefined) {
             return undefined;
+        }
         this.touch(sessionId);
         return lease.page.press(args);
     }
@@ -368,8 +356,9 @@ export class BrowserPool {
      */
     async setViewportLease(sessionId, size) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined || lease.page.setViewport === undefined)
+        if (lease === undefined || lease.page.setViewport === undefined) {
             return false;
+        }
         this.touch(sessionId);
         try {
             await lease.page.setViewport(size);
@@ -386,15 +375,17 @@ export class BrowserPool {
     }
     async setMocksLease(sessionId, rules) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined || lease.page.installMocks === undefined)
+        if (lease === undefined || lease.page.installMocks === undefined) {
             return false;
+        }
         this.touch(sessionId);
         try {
             await lease.page.installMocks(rules);
             // Mocks registered later are asked first, and one that lets a request through would skip
             // the production guard. Re-asserting the guard puts it back in front.
-            if (lease.guard !== undefined)
+            if (lease.guard !== undefined) {
                 await lease.page.guardRequests?.(lease.guard);
+            }
             return true;
         }
         catch {
@@ -404,8 +395,9 @@ export class BrowserPool {
     /** Guard a leased page's requests, or false when this is not a lease or its page cannot. */
     async guardLease(sessionId, decide) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined || lease.page.guardRequests === undefined)
+        if (lease === undefined || lease.page.guardRequests === undefined) {
             return false;
+        }
         await lease.page.guardRequests(decide);
         lease.guard = decide;
         return true;
@@ -447,13 +439,15 @@ export class BrowserPool {
             .filter(([, lease]) => now - lease.touchedAt > this.#ttl ||
             (lease.detachedAt !== undefined && now - lease.detachedAt >= ORPHANED_LEASE_GRACE_MS))
             .map(([sessionId]) => sessionId);
-        for (const sessionId of expired)
+        for (const sessionId of expired) {
             await this.#release(sessionId);
+        }
         this.#reapedLeases += expired.length;
         for (const sessionId of expired) {
             this.#reapedLeaseIds.push(sessionId);
-            if (this.#reapedLeaseIds.length > MAX_REMEMBERED_REAPED_LEASES)
+            if (this.#reapedLeaseIds.length > MAX_REMEMBERED_REAPED_LEASES) {
                 this.#reapedLeaseIds.shift();
+            }
         }
         return expired;
     }
@@ -489,18 +483,21 @@ export class BrowserPool {
      * `'refuse'`: then it throws {@link PoolAtCapacityError} at once and claims nothing.
      */
     async acquire(url, opts = {}) {
-        if (this.#closed)
+        if (this.#closed) {
             throw new Error('browser pool is shut down');
+        }
         const slot = true === opts.headed ? this.#headed : this.#headless;
         // Refused before a slot is claimed, so a refusal never holds one.
-        if (slot.launch === undefined)
+        if (slot.launch === undefined) {
             throw new Error(NO_HEADED_BROWSER);
+        }
         // #waitForSlot claims the slot synchronously (bumps #occupied) before returning, so the cap holds
         // even when many acquires race through the gate in the same tick. A refusing acquire claims the
         // same way, or claims nothing and says so.
         if ('refuse' === opts.whenFull) {
-            if (!this.#tryClaim())
+            if (!this.#tryClaim()) {
                 throw new PoolAtCapacityError(this.#max);
+            }
         }
         else {
             await this.#waitForSlot(opts.signal);
@@ -516,8 +513,9 @@ export class BrowserPool {
                 ...opts.emulate,
             };
             context = await browser.newContext(0 < Object.keys(contextOpts).length ? contextOpts : undefined);
-            if (opts.permissions !== undefined)
+            if (opts.permissions !== undefined) {
                 await grantLeasePermissions(context, opts.permissions, url);
+            }
             const page = await context.newPage();
             // A caller-supplied init script is a stub of the bindings a desktop shell injects, and it has
             // to exist before the app's first module runs. Installed here — before goto — so the very
@@ -540,23 +538,28 @@ export class BrowserPool {
             // retry backoff stretches out.
             page.onConsole?.((text) => {
                 const dialled = unreachableUrlIn(text);
-                if (dialled === undefined)
+                if (dialled === undefined) {
                     return;
+                }
                 const active = this.#active.get(sessionId);
-                if (active !== undefined)
+                if (active !== undefined) {
                     active.dialFailureUrl = dialled;
-                else
-                    pending = dialled; // logged during goto, before the lease is registered below
+                }
+                else {
+                    pending = dialled;
+                } // logged during goto, before the lease is registered below
             });
             // Same "listen before goto" reasoning as onConsole above: a dialog opened during the initial
             // navigation (an app that confirms something in an onload handler) must still be dismissed, not
             // just ones opened after the lease is registered.
             page.onDialog?.((dialog) => {
                 const active = this.#active.get(sessionId);
-                if (active !== undefined)
+                if (active !== undefined) {
                     active.lastDialogMessage = dialog.message;
-                else
+                }
+                else {
                     pendingDialogMessage = dialog.message;
+                }
                 void dialog.dismiss();
             });
             const marker = leaseMarkerOf(url);
@@ -584,8 +587,9 @@ export class BrowserPool {
             // #occupied. Registering the lease now would resurrect a dead entry against a crashed browser with
             // the slot count out of sync (drifting below #active.size, eventually exceeding the cap). If we're
             // no longer the live browser, bail — the catch below closes the context and returns the slot.
-            if (slot.browser !== browser)
+            if (slot.browser !== browser) {
                 throw new Error('browser crashed during navigation');
+            }
             // Foreground it: a page opened beside other tabs can start hidden (#1351). Best-effort — a tab
             // that stays hidden is reported by name at the lease, which failing here would lose.
             await page.bringToFront?.().catch(() => undefined);
@@ -595,8 +599,9 @@ export class BrowserPool {
                 if ('function' === typeof s) {
                     try {
                         const code = s.call(navRes);
-                        if ('number' === typeof code)
+                        if ('number' === typeof code) {
                             navStatus = code;
+                        }
                     }
                     catch {
                         // ignore
@@ -628,26 +633,24 @@ export class BrowserPool {
                 release: () => this.#release(sessionId),
                 injectReader: async () => {
                     const script = this.#zeroInstall?.();
-                    if (script === undefined || page.evaluate === undefined)
+                    if (script === undefined || page.evaluate === undefined) {
                         return false;
+                    }
                     await page.addInitScript?.(script);
-                    if (READER_NOT_HTML === (await page.evaluate(script)))
+                    if (READER_NOT_HTML === (await page.evaluate(script))) {
                         throw new NotHtmlDocumentError();
+                    }
                     return true;
                 },
-                isLoading: async () => {
-                    if (page.evaluate === undefined)
-                        return false;
-                    const state = await page.evaluate('document.readyState');
-                    return 'string' === typeof state && state !== 'complete';
-                },
+                isLoading: () => pageLoading(page),
             };
         }
         catch (err) {
             // Setup failed after we claimed the slot — give it back so a queued acquire isn't stuck, and
             // close the half-open context.
-            if (context !== undefined)
+            if (context !== undefined) {
                 await settledWithin(context.close(), LEASE_CLOSE_TIMEOUT_MS);
+            }
             this.#releaseSlot();
             throw err;
         }
@@ -686,22 +689,26 @@ export class BrowserPool {
             }
             const browser = slot.browser;
             slot.browser = undefined;
-            if (browser !== undefined)
+            if (browser !== undefined) {
                 await browser.close().catch(() => undefined);
+            }
         }
-        for (const waiter of this.#waiters.splice(0))
+        for (const waiter of this.#waiters.splice(0)) {
             waiter();
+        }
     }
     async #release(sessionId) {
         const lease = this.#active.get(sessionId);
-        if (lease === undefined)
-            return; // already released or lost to a crash
+        if (lease === undefined) {
+            return;
+        } // already released or lost to a crash
         this.#active.delete(sessionId);
         // Drop any alias pointing here, or the map grows for the life of the daemon and a later lease
         // reusing that registered name would resolve to a context that is already closed.
         for (const [registered, leaseId] of this.#aliases) {
-            if (leaseId === sessionId)
+            if (leaseId === sessionId) {
                 this.#aliases.delete(registered);
+            }
         }
         // Bounded: a close that never returned held the slot and kept the tab open after the agent left.
         const closed = await closeLeaseTab(lease, LEASE_CLOSE_TIMEOUT_MS);
@@ -730,12 +737,14 @@ export class BrowserPool {
      * nothing occupied means no acquire is between launching a browser and using it.
      */
     async #closeIfIdle() {
-        if (this.#active.size > 0 || this.#occupied > 0 || this.#waiters.length > 0)
+        if (this.#active.size > 0 || this.#occupied > 0 || this.#waiters.length > 0) {
             return;
+        }
         for (const slot of [this.#headless, this.#headed]) {
             const browser = slot.browser;
-            if (browser === undefined || slot.launching !== undefined)
+            if (browser === undefined || slot.launching !== undefined) {
                 continue;
+            }
             slot.browser = undefined;
             await settledWithin(browser.close(), LEASE_CLOSE_TIMEOUT_MS);
         }
@@ -749,21 +758,24 @@ export class BrowserPool {
         return false;
     }
     #waitForSlot(signal) {
-        if (this.#tryClaim())
+        if (this.#tryClaim()) {
             return Promise.resolve();
+        }
         return new Promise((resolve, reject) => {
             const onFree = () => {
                 // The pool shut down while we waited → reject rather than relaunch a browser.
                 if (this.#closed) {
-                    if (signal !== undefined)
+                    if (signal !== undefined) {
                         signal.removeEventListener('abort', onAbort);
+                    }
                     reject(new Error('browser pool is shut down'));
                     return;
                 }
                 // Claim the freed slot; if another woken waiter beat us to it, re-queue.
                 if (this.#tryClaim()) {
-                    if (signal !== undefined)
+                    if (signal !== undefined) {
                         signal.removeEventListener('abort', onAbort);
+                    }
                     resolve();
                 }
                 else {
@@ -772,8 +784,9 @@ export class BrowserPool {
             };
             const onAbort = () => {
                 const i = this.#waiters.indexOf(onFree);
-                if (i >= 0)
+                if (i >= 0) {
                     this.#waiters.splice(i, 1);
+                }
                 reject(new Error('acquire aborted'));
             };
             if (signal !== undefined) {
@@ -788,20 +801,25 @@ export class BrowserPool {
     }
     /** Give back one occupied slot and hand it to the next waiter (which re-claims it synchronously). */
     #releaseSlot() {
-        if (this.#occupied > 0)
+        if (this.#occupied > 0) {
             this.#occupied -= 1;
+        }
         const next = this.#waiters.shift();
-        if (next !== undefined)
+        if (next !== undefined) {
             next();
+        }
     }
     async #ensureBrowser(slot) {
-        if (this.#closed)
+        if (this.#closed) {
             throw new Error('browser pool is shut down');
-        if (slot.browser !== undefined && slot.browser.isConnected())
+        }
+        if (slot.browser !== undefined && slot.browser.isConnected()) {
             return slot.browser;
+        }
         const launch = slot.launch;
-        if (launch === undefined)
+        if (launch === undefined) {
             throw new Error(NO_HEADED_BROWSER);
+        }
         // De-dupe concurrent launches: the first acquire to find no browser starts one; the rest await it.
         if (slot.launching === undefined) {
             // The in-flight promise MUST be cleared on failure as well as success. It used to be cleared only
@@ -826,21 +844,24 @@ export class BrowserPool {
      * acquire of that kind relaunches it. The other browser's leases live on.
      */
     #onCrash(slot, crashed) {
-        if (slot.browser !== crashed)
-            return; // a stale handler from a prior browser
+        if (slot.browser !== crashed) {
+            return;
+        } // a stale handler from a prior browser
         slot.browser = undefined;
         let freed = 0;
         for (const [id, lease] of this.#active) {
-            if (lease.headed !== slot.headed)
+            if (lease.headed !== slot.headed) {
                 continue;
+            }
             this.#active.delete(id);
             freed += 1;
         }
         // A lease mid-acquire on the dead browser holds a slot too; it frees it in its own catch. When
         // every lease belonged to this browser, nothing else can be holding one.
         this.#occupied = 0 === this.#active.size ? 0 : Math.max(0, this.#occupied - freed);
-        for (const waiter of this.#waiters.splice(0))
-            waiter(); // let them re-claim + relaunch
+        for (const waiter of this.#waiters.splice(0)) {
+            waiter();
+        } // let them re-claim + relaunch
     }
     /** Whether this lease's context skips certificate checks. A context cannot change it later. */
     ignoresHTTPSErrors(sessionId) {

package/dist/portal/pool/pool-lease.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The pool's lease handle and lease record, its options, and its limits: the types and constants
+ * `BrowserPool` is built from.
+ */
+import type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledPage } from './pool-contract.js';
+/** 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>;
+    /**
+     * Hand the page the zero-install reader: evaluated in the live document, and added ahead of every
+     * document this lease loads next. False when there is no reader, or the page cannot run one.
+     * Rejects with `NotHtmlDocumentError` when the page is not an HTML document.
+     */
+    injectReader?(): Promise<boolean>;
+    /** Whether the page's document has not reached `complete` yet. False when it cannot be read. */
+    isLoading?(): Promise<boolean>;
+}
+/** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
+export declare const DEFAULT_LEASE_TTL_MS: number;
+/**
+ * How long a lease outlives the MCP connection that took it. Long enough for an agent whose
+ * connection only blipped to touch it again; short enough that a gone agent's window closes soon.
+ */
+export declare const ORPHANED_LEASE_GRACE_MS = 30000;
+/** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
+export declare const DEFAULT_NAV_TIMEOUT_MS = 30000;
+/**
+ * How many reaped lease ids to remember. Only the most recent departure is ever asked about, so
+ * this is slack for a burst sweep, not a history.
+ */
+export declare const MAX_REMEMBERED_REAPED_LEASES = 64;
+export 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;
+    /**
+     * The zero-install reader, built where the daemon knows its own port and pairing token. A thunk so
+     * the ~450KB build is only read if some page ever needs it; undefined when there is none to give.
+     */
+    zeroInstallScript?: () => string | undefined;
+    /**
+     * Launches a browser with a window, for a lease somebody wants to watch. Launched only when the
+     * first headed lease is asked for. Absent: a headed lease is refused.
+     */
+    launchHeaded?: Launcher;
+}
+/** One browser the pool may hold, and the launch in flight for it. */
+export interface BrowserSlot {
+    readonly launch: Launcher | undefined;
+    readonly headed: boolean;
+    browser?: PooledBrowser | undefined;
+    launching?: Promise<PooledBrowser> | undefined;
+}
+/** What a headed lease is refused with where no window can be opened. */
+export declare const NO_HEADED_BROWSER = "no headed browser can be opened here";
+/**
+ * An acquire that asked to be refused rather than queued found every slot taken (#1535). Queued,
+ * it waited behind the cap with no deadline and no status, and `reticle drive` reported the 60 s
+ * timeout as a daemon shutting down. The message names the cap and the one override for it.
+ */
+export declare class PoolAtCapacityError extends Error {
+    readonly max: number;
+    constructor(max: number);
+}
+/**
+ * What an acquire that asked for an init script is refused with when the page cannot run one.
+ *
+ * A refusal rather than a lease: the caller asked for a stub of the bindings a desktop shell
+ * injects, and a tab opened without it would throw in the app's view and read as a broken app.
+ */
+export declare const INIT_SCRIPT_UNSUPPORTED = "Init script failed: this page does not support init scripts, so the requested stub would not be there";
+export interface ActiveLease {
+    /** Whether it lives in the headed browser: that browser's death is this lease's death. */
+    headed: boolean;
+    context: PooledContext;
+    page: PooledPage;
+    url: string;
+    /** Who took it (one id per MCP attach). Only that caller is handed it again. */
+    owner?: string;
+    /** Last time an agent touched this lease (acquire or any tool call); drives orphan reclaim. */
+    touchedAt: number;
+    /** When the connection that took it closed, until it is touched again. */
+    detachedAt?: number;
+    /**
+     * The websocket address the page's SDK reported it could not reach, if it said so.
+     *
+     * One string, overwritten — not a buffer. The SDK retries and logs each failure, so accumulating
+     * them would grow without bound for exactly the app that is already misconfigured, and every entry
+     * after the first says the same thing.
+     */
+    dialFailureUrl?: string;
+    /**
+     * The message of the most recent native dialog dismissed on this lease, if any.
+     *
+     * One string, overwritten — not a buffer, same reasoning as `dialFailureUrl`: this is diagnostic
+     * context for "why did the page look frozen for a moment", not a log an agent needs to replay.
+     */
+    lastDialogMessage?: string;
+    /**
+     * The disposable handle of the caller's init script, when the lease was opened with one — a stub
+     * of the bindings a desktop shell injects. Disposed with the lease, so a reload or a later
+     * navigation inside the lease keeps the stub.
+     */
+    hostStub?: InitScriptHandle;
+    /** The production guard on this page's requests, re-asserted after mocks so it is asked first. */
+    guard?: (method: string, url: string) => string | undefined;
+    /**
+     * The text of that init script, kept so a lease that asks for the SAME stub again is recognised and
+     * reused instead of being torn down and remade — see `hostStubScript` and the lease tool's reuse.
+     */
+    hostStubScript?: string;
+    /** What this lease was granted when it opened. It never changes on an open lease. */
+    permissions: readonly string[];
+    /** Whether its context accepts any TLS certificate (#1255). Fixed when the context is made. */
+    ignoresHTTPSErrors: boolean;
+}
+/** Whether the page's document has not finished loading. A page that cannot be asked counts as loaded. */
+export declare function pageLoading(page: PooledPage): Promise<boolean>;