@reticlehq/server 3.7.0 → 3.8.1

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

@@ -9,28 +9,16 @@
  * 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.
  */
-import { unreachableUrlIn } from '@reticlehq/core';
+import { LEASE_CLOSE_TIMEOUT_MS, unreachableUrlIn } from '@reticlehq/core';
+import { log } from '../../log.js';
+import { closeLeaseTab, LEASE_CLOSE_TIMED_OUT, settledWithin } from './bounded-close.js';
 import { seedStorageInto, targetOriginOf } from './storage-seed.js';
 import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
-import { grantLeasePermissions, NOTIFICATION_PERMISSION_READ, NOTIFICATION_READ_TIMEOUT_MS, } from './context-permissions.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;
-/** 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';
-/**
- * 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 { grantLeasePermissions, readNotificationPermission } from './context-permissions.js';
+import { readViewport } from './lease-emulation.js';
+import { NotHtmlDocumentError, READER_NOT_HTML } from './zero-install.js';
+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.
@@ -74,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;
@@ -116,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;
@@ -128,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;
         }
@@ -161,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);
     }
     /**
@@ -202,8 +197,35 @@ 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)
-            lease.touchedAt = this.#now();
+        if (lease === undefined) {
+            return;
+        }
+        lease.touchedAt = this.#now();
+        delete lease.detachedAt;
+    }
+    /**
+     * The MCP connection `owner` closed. Its leases go after {@link ORPHANED_LEASE_GRACE_MS} unless it
+     * touches them again: a reconnect is a new owner, so nothing else would ever hand them back, and
+     * each one held a browser window open for the full TTL.
+     */
+    detachOwner(owner) {
+        const now = this.#now();
+        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
+     * their grace, because the owner they wait for is here again.
+     */
+    reattachOwner(owner) {
+        for (const lease of this.#active.values()) {
+            if (lease.owner === owner) {
+                delete lease.detachedAt;
+            }
+        }
     }
     /**
      * Reclaim leases untouched for longer than the TTL — a hung/crashed agent never holds a slot
@@ -221,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);
@@ -244,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 });
@@ -264,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);
@@ -275,6 +300,46 @@ export class BrowserPool {
             return false;
         }
     }
+    /** 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) {
+            return false;
+        }
+        this.touch(sessionId);
+        try {
+            await lease.page.emulateMedia(media);
+            return true;
+        }
+        catch {
+            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;
+    }
+    /**
+     * Press a key with the leased page's real keyboard, or undefined when this session is not a lease
+     * or its page has no keyboard. A throw is the caller's to read: a key that went down and did not
+     * come up must not be answered with a second, synthetic press.
+     */
+    async pressLease(sessionId, args) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease?.page.press === undefined) {
+            return undefined;
+        }
+        this.touch(sessionId);
+        return lease.page.press(args);
+    }
     /**
      * 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
@@ -291,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);
@@ -302,19 +368,40 @@ export class BrowserPool {
             return false;
         }
     }
+    /** The size a leased page reports for itself, or undefined when it cannot be read. */
+    async viewportOfLease(sessionId) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        return lease === undefined ? undefined : readViewport(lease.page);
+    }
     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) {
+                await lease.page.guardRequests?.(lease.guard);
+            }
             return true;
         }
         catch {
             return false;
         }
     }
+    /** 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) {
+            return false;
+        }
+        await lease.page.guardRequests(decide);
+        lease.guard = decide;
+        return true;
+    }
     /** What a lease was granted when it opened, or undefined for a session that is not a lease. */
     permissionsOf(sessionId) {
         return this.#active.get(this.#leaseIdOf(sessionId))?.permissions;
@@ -344,35 +431,23 @@ export class BrowserPool {
      */
     async notificationPermission(sessionId) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
-        if (lease === undefined || lease.page.evaluate === undefined)
-            return undefined;
-        let timer;
-        const gaveUp = new Promise((resolve) => {
-            timer = setTimeout(() => resolve(undefined), NOTIFICATION_READ_TIMEOUT_MS);
-        });
-        try {
-            const value = await Promise.race([lease.page.evaluate(NOTIFICATION_PERMISSION_READ), gaveUp]);
-            return 'string' === typeof value ? value : undefined;
-        }
-        catch {
-            return undefined;
-        }
-        finally {
-            clearTimeout(timer);
-        }
+        return lease === undefined ? undefined : readNotificationPermission(lease.page);
     }
     async sweepExpired() {
         const now = this.#now();
         const expired = [...this.#active.entries()]
-            .filter(([, lease]) => now - lease.touchedAt > this.#ttl)
+            .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;
     }
@@ -404,27 +479,43 @@ export class BrowserPool {
     }
     /**
      * 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).
+     * waits FIFO until a slot frees (or until `signal` aborts, if provided), unless `whenFull` is
+     * `'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.
-        await this.#waitForSlot(opts.signal);
+        // 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()) {
+                throw new PoolAtCapacityError(this.#max);
+            }
+        }
+        else {
+            await this.#waitForSlot(opts.signal);
+        }
         const sessionId = opts.sessionId ?? this.#genId();
         let context;
         let pending;
         let pendingDialogMessage;
         try {
             const browser = await this.#ensureBrowser(slot);
-            context = await browser.newContext(true === opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : undefined);
-            if (opts.permissions !== undefined)
+            const contextOpts = {
+                ...(true === opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
+                ...opts.emulate,
+            };
+            context = await browser.newContext(0 < Object.keys(contextOpts).length ? contextOpts : 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
@@ -447,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);
@@ -491,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);
@@ -502,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
@@ -535,19 +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);
-                    await page.evaluate(script);
+                    if (READER_NOT_HTML === (await page.evaluate(script))) {
+                        throw new NotHtmlDocumentError();
+                    }
                     return true;
                 },
+                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)
-                await context.close().catch(() => undefined);
+            if (context !== undefined) {
+                await settledWithin(context.close(), LEASE_CLOSE_TIMEOUT_MS);
+            }
             this.#releaseSlot();
             throw err;
         }
@@ -586,28 +689,65 @@ 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);
+            }
         }
-        // Disposed with the lease, which is what "for that lease only" means. Best-effort: a context
-        // that is already gone (a crash) makes the disposal moot, not a reason to fail the release.
-        await lease.hostStub?.dispose().catch(() => undefined);
-        await lease.context.close().catch(() => undefined);
+        // 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);
         this.#releaseSlot();
+        if (!closed) {
+            await this.#dropWedgedBrowser(sessionId, lease.headed);
+        }
+        await this.#closeIfIdle();
+    }
+    /** Close the browser of a tab that did not close in time, unless another lease still uses it. */
+    async #dropWedgedBrowser(sessionId, headed) {
+        const slot = headed ? this.#headed : this.#headless;
+        const shared = [...this.#active.values()].some((other) => other.headed === headed);
+        const browser = slot.browser;
+        const drop = !shared && browser !== undefined && slot.launching === undefined;
+        log(LEASE_CLOSE_TIMED_OUT, { lease: sessionId, browserClosed: drop });
+        if (!drop) {
+            return;
+        }
+        slot.browser = undefined;
+        await settledWithin(browser.close(), LEASE_CLOSE_TIMEOUT_MS);
+    }
+    /**
+     * Close the browsers once nothing holds or waits for a lease. An idle Chromium kept its memory
+     * until the daemon itself went idle. Every acquire claims a slot before it touches a browser, so
+     * 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) {
+            return;
+        }
+        for (const slot of [this.#headless, this.#headed]) {
+            const browser = slot.browser;
+            if (browser === undefined || slot.launching !== undefined) {
+                continue;
+            }
+            slot.browser = undefined;
+            await settledWithin(browser.close(), LEASE_CLOSE_TIMEOUT_MS);
+        }
     }
     /** Synchronously claim a slot if under the cap. Returns true on success (caller proceeds). */
     #tryClaim() {
@@ -618,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 {
@@ -641,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) {
@@ -657,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
@@ -695,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/context-permissions.d.ts

@@ -15,7 +15,7 @@
  * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
  * "granted" there would be reporting something the page cannot see.
  */
-import type { PooledContext } from './pool-contract.js';
+import type { PooledContext, PooledPage } from './pool-contract.js';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export declare const NOTIFICATIONS_PERMISSION = "notifications";
 /** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
@@ -31,3 +31,11 @@ export declare class LeasePermissionError extends Error {
 }
 /** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
 export declare function grantLeasePermissions(context: PooledContext, permissions: readonly string[], url: string): Promise<void>;
+/**
+ * What the page's `Notification.permission` says, or undefined when it cannot be asked.
+ *
+ * Read back rather than inferred from the grant, because the headless shell answers `denied`
+ * after a notifications grant. Bounded, so a page that never answers reads as "could not ask"
+ * instead of holding the caller.
+ */
+export declare function readNotificationPermission(page: PooledPage): Promise<string | undefined>;

package/dist/portal/pool/context-permissions.js

@@ -31,3 +31,29 @@ export async function grantLeasePermissions(context, permissions, url) {
         throw new LeasePermissionError(`could not grant ${permissions.join(', ')}: ${reasonOf(err)}`);
     }
 }
+/**
+ * What the page's `Notification.permission` says, or undefined when it cannot be asked.
+ *
+ * Read back rather than inferred from the grant, because the headless shell answers `denied`
+ * after a notifications grant. Bounded, so a page that never answers reads as "could not ask"
+ * instead of holding the caller.
+ */
+export async function readNotificationPermission(page) {
+    if (page.evaluate === undefined) {
+        return undefined;
+    }
+    let timer;
+    const gaveUp = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), NOTIFICATION_READ_TIMEOUT_MS);
+    });
+    try {
+        const value = await Promise.race([page.evaluate(NOTIFICATION_PERMISSION_READ), gaveUp]);
+        return 'string' === typeof value ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}