@reticlehq/server 3.7.0 → 3.8.1

package/dist/portal/input/viewport-tools.js

@@ -4,6 +4,59 @@ import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
 import { MAX_VIEWPORT_PX, MIN_VIEWPORT_PX, viewportPxSchema, } from '../../surface/tools/args/numeric-bounds.js';
 import { asString } from '@reticlehq/core';
+import { ColorScheme, ReducedMotion, } from '../pool/lease-emulation.js';
+// ── Media and width, as a tool call names them (reticle_viewport here, reticle_lease acquire) ──
+/** Playwright's own default page size, used for the side a caller did not name. */
+const DEFAULT_WIDTH = 1280;
+const DEFAULT_HEIGHT = 720;
+export const COLOR_SCHEME_ARG = z
+    .enum([ColorScheme.LIGHT, ColorScheme.DARK, ColorScheme.NO_PREFERENCE])
+    .optional()
+    .describe('prefers-color-scheme for this page: light, dark or no-preference.');
+export const REDUCED_MOTION_ARG = z
+    .enum([ReducedMotion.REDUCE, ReducedMotion.NO_PREFERENCE])
+    .optional()
+    .describe('prefers-reduced-motion for this page: reduce or no-preference.');
+const EmulateSchema = z
+    .object({
+    colorScheme: COLOR_SCHEME_ARG,
+    reducedMotion: REDUCED_MOTION_ARG,
+    width: viewportPxSchema.optional(),
+    height: viewportPxSchema.optional(),
+})
+    .strict();
+export const LEASE_EMULATE_ARG = EmulateSchema.optional().describe('Open the lease with these set before the first paint: { colorScheme, reducedMotion, width, height }. ' +
+    'A side you leave out keeps its default (1280 by 720). Change them later with reticle_viewport.');
+/** The media part of what a caller asked for, or undefined when it asked for none. */
+export function mediaOf(raw) {
+    const parsed = EmulateSchema.pick({ colorScheme: true, reducedMotion: true }).parse({
+        colorScheme: raw.colorScheme,
+        reducedMotion: raw.reducedMotion,
+    });
+    const media = {
+        ...(parsed.colorScheme === undefined ? {} : { colorScheme: parsed.colorScheme }),
+        ...(parsed.reducedMotion === undefined ? {} : { reducedMotion: parsed.reducedMotion }),
+    };
+    return 0 === Object.keys(media).length ? undefined : media;
+}
+/** A lease's `emulate` argument, read; a value it does not know is refused by name. */
+export function leaseEmulationOf(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = EmulateSchema.safeParse(raw);
+    if (!parsed.success) {
+        const field = parsed.error.issues[0]?.path.join('.') ?? 'emulate';
+        throw new Error(`emulate.${field}: ${parsed.error.issues[0]?.message ?? 'not valid'}`);
+    }
+    const { width, height } = parsed.data;
+    const media = mediaOf(parsed.data);
+    const viewport = width === undefined && height === undefined
+        ? undefined
+        : { width: width ?? DEFAULT_WIDTH, height: height ?? DEFAULT_HEIGHT };
+    if (media === undefined && viewport === undefined)
+        return undefined;
+    return { ...media, ...(viewport === undefined ? {} : { viewport }) };
+}
 /** Bounds so a viewport request stays sane (and a typo can't ask for a 1px or 100k-px window). */
 const MIN_DIM = MIN_VIEWPORT_PX;
 const MAX_DIM = MAX_VIEWPORT_PX;
@@ -19,29 +72,49 @@ export const VIEWPORT_TOOLS = [
         description: 'Pin the DRIVEN or LEASED page (needs `reticle drive`, or `reticle_lease` acquire when there is no CDP provider) to a fixed viewport size so a screenshot baseline is ' +
             'reproducible across machines — the missing piece of CI-stable visual regression, alongside ' +
             'reticle_visual_diff `masks` and a frozen clock (reticle_clock). Set it once before reticle_screenshot / ' +
-            'reticle_visual_diff. Returns { applied, width, height } or the no-provider recommendation.',
+            'reticle_visual_diff. On a lease it also sets prefers-color-scheme and prefers-reduced-motion; ' +
+            'give only those to change the media and keep the size. Returns { applied, width, height, observed } or the no-provider recommendation; `observed` is the size the leased page reports after the resize.',
         inputSchema: {
-            width: viewportPxSchema.describe('Viewport width in CSS px (e.g. 1280).'),
-            height: viewportPxSchema.describe('Viewport height in CSS px (e.g. 800).'),
+            width: viewportPxSchema.optional().describe('Viewport width in CSS px (e.g. 1280).'),
+            height: viewportPxSchema.optional().describe('Viewport height in CSS px (e.g. 800).'),
+            colorScheme: COLOR_SCHEME_ARG,
+            reducedMotion: REDUCED_MOTION_ARG,
             ...sessionIdShape,
         },
         outputSchema: {
             applied: z.boolean(),
             width: z.number(),
             height: z.number(),
+            observed: z.object({ width: z.number(), height: z.number() }).optional(),
+            colorScheme: z.string().optional(),
+            reducedMotion: z.string().optional(),
             ok: z.boolean().optional(),
             reason: z.string().optional(),
             recommendation: z.string().optional(),
         },
         handler: async (deps, args) => {
+            const media = mediaOf(args);
+            if (media !== undefined && args['width'] === undefined && args['height'] === undefined) {
+                const session = deps.sessions.resolve(asString(args['sessionId']));
+                if (true === (await deps.pool?.emulateLease(session.id, media))) {
+                    return { applied: true, width: 0, height: 0, ...media };
+                }
+                return { ...refused(), recommendation: MEDIA_NEEDS_A_LEASE };
+            }
             const width = clampDim('width', args['width']);
             const height = clampDim('height', args['height']);
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const provider = viewportProvider(deps);
+            // A lease is resized as the lease. The driven provider resizes its own page, whatever
+            // session was named, so taking it first resized the wrong tab and said `applied: true`.
+            const driven = viewportProvider(deps);
+            const provider = driven !== undefined && deps.pool?.leaseUrl(session.id) === undefined ? driven : undefined;
             if (provider !== undefined) {
                 const applied = await provider.setViewport(session.url, { width, height });
-                if (applied)
+                // The driven page takes the size; its media stay as the person's browser has them.
+                if (applied && media === undefined)
                     return { applied: true, width, height };
+                if (applied)
+                    return { applied: true, width, height, recommendation: MEDIA_NEEDS_A_LEASE };
             }
             // A lease is a Playwright-owned page, so the resize was always possible — this tool just had
             // no route to it. Tried after the driven provider, on the same rule reticle_network_mock
@@ -52,19 +125,37 @@ export const VIEWPORT_TOOLS = [
             // only mounts under a breakpoint — could not be driven at a desktop viewport at all, and the
             // recommendation printed alongside the refusal asked the reader to install a second browser.
             const leased = await deps.pool?.setViewportLease(session.id, { width, height });
-            if (true === leased)
-                return { applied: true, width, height };
-            return {
-                applied: false,
-                width: 0,
-                height: 0,
-                ok: false,
-                reason: CDP_NO_PROVIDER_REASON,
-                recommendation: VIEWPORT_NO_PROVIDER_RECOMMENDATION,
-            };
+            if (true !== leased)
+                return refused();
+            // What the page reports after the resize, so `applied` is a reading and not a hope.
+            const observed = await deps.pool?.viewportOfLease(session.id);
+            if (observed !== undefined && (observed.width !== width || observed.height !== height)) {
+                return { applied: false, width, height, observed, ok: false, reason: VIEWPORT_NOT_TAKEN };
+            }
+            const seen = observed === undefined ? {} : { observed };
+            if (media === undefined)
+                return { applied: true, width, height, ...seen };
+            if (true === (await deps.pool?.emulateLease(session.id, media))) {
+                return { applied: true, width, height, ...seen, ...media };
+            }
+            return { ...refused(), width, height, recommendation: MEDIA_NEEDS_A_LEASE };
         },
     },
 ];
+/** The resize went through, but the page still reports another size. */
+const VIEWPORT_NOT_TAKEN = 'the page still reports the size in `observed` after the resize, so the size was not applied';
+/** prefers-color-scheme and prefers-reduced-motion are set on a leased page only. */
+const MEDIA_NEEDS_A_LEASE = 'Media features are set on a leased tab: open one with reticle_lease { action: "acquire", emulate }, then call this again with its sessionId.';
+function refused() {
+    return {
+        applied: false,
+        width: 0,
+        height: 0,
+        ok: false,
+        reason: CDP_NO_PROVIDER_REASON,
+        recommendation: VIEWPORT_NO_PROVIDER_RECOMMENDATION,
+    };
+}
 /**
  * Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing value falls back to MIN_DIM.
  *

package/dist/portal/pool/bounded-close.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A close that has a time limit.
+ *
+ * Playwright's `context.close()` and `browser.close()` can wait forever on a browser that stopped
+ * answering. The pool awaited them with no limit, so one such close held a lease slot and kept the
+ * tab open after the agent was gone.
+ */
+/** Logged when a leased tab did not close within LEASE_CLOSE_TIMEOUT_MS. */
+export declare const LEASE_CLOSE_TIMED_OUT = "lease_close_timed_out";
+/**
+ * Dispose the lease's init script, then close its context. False when that took longer than `ms`.
+ * The disposal is best-effort: a context that is already gone (a crash) makes it moot.
+ */
+export declare function closeLeaseTab(tab: {
+    hostStub?: {
+        dispose(): Promise<void>;
+    };
+    context: {
+        close(): Promise<void>;
+    };
+}, ms: number): Promise<boolean>;
+/** Whether `work` settled within `ms`. A rejection counts as settled: the close is over. */
+export declare function settledWithin(work: Promise<unknown>, ms: number): Promise<boolean>;

package/dist/portal/pool/bounded-close.js

@@ -0,0 +1,38 @@
+/**
+ * A close that has a time limit.
+ *
+ * Playwright's `context.close()` and `browser.close()` can wait forever on a browser that stopped
+ * answering. The pool awaited them with no limit, so one such close held a lease slot and kept the
+ * tab open after the agent was gone.
+ */
+/** Logged when a leased tab did not close within LEASE_CLOSE_TIMEOUT_MS. */
+export const LEASE_CLOSE_TIMED_OUT = 'lease_close_timed_out';
+/**
+ * Dispose the lease's init script, then close its context. False when that took longer than `ms`.
+ * The disposal is best-effort: a context that is already gone (a crash) makes it moot.
+ */
+export function closeLeaseTab(tab, ms) {
+    const closing = (async () => {
+        await tab.hostStub?.dispose().catch(() => undefined);
+        await tab.context.close();
+    })();
+    return settledWithin(closing, ms);
+}
+/** Whether `work` settled within `ms`. A rejection counts as settled: the close is over. */
+export async function settledWithin(work, ms) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    try {
+        return await Promise.race([
+            work.then(() => true, () => true),
+            late,
+        ]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}

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

@@ -11,45 +11,12 @@
  */
 import { type SeedStorage } from '@reticlehq/core';
 import type { Launcher, PooledMockRule, ScreenshotOptions } from './pool-contract.js';
+import type { RealInputArgs, RealInputResult } from '../input/real-input.js';
+import { type LeaseEmulation, type LeaseMedia } from './lease-emulation.js';
 export type { InitScriptHandle, Launcher, PooledBrowser, PooledContext, PooledCookie, PooledDialog, PooledMockRule, 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.
-     */
-    injectReader?(): 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;
-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;
-}
-/** 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";
+import { type BrowserPoolOptions, type Lease } from './pool-lease.js';
+export { DEFAULT_LEASE_TTL_MS, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, PoolAtCapacityError, } from './pool-lease.js';
+export type { Lease } 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.
@@ -108,6 +75,17 @@ export declare class BrowserPool {
     heldBy(sessionId: string, owner: string | undefined): boolean;
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: 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.
@@ -139,6 +117,18 @@ export declare class BrowserPool {
      * Touches the lease like any other tool call, so hovering keeps it alive.
      */
     hoverLease(sessionId: string, x: number, y: number): Promise<boolean>;
+    /** Set a live lease's media features, or false when this is not a lease or its page cannot. */
+    emulateLease(sessionId: string, media: LeaseMedia): Promise<boolean>;
+    /** Whether this lease's page is still loading. False for a non-lease, or a page that cannot say. */
+    leaseLoading(sessionId: string): Promise<boolean>;
+    /** Whether this session is a lease whose page has a real keyboard. */
+    hasKeyboard(sessionId: string): boolean;
+    /**
+     * 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.
+     */
+    pressLease(sessionId: string, args: RealInputArgs): Promise<RealInputResult | undefined>;
     /**
      * 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
@@ -157,7 +147,14 @@ export declare class BrowserPool {
         width: number;
         height: number;
     }): Promise<boolean>;
+    /** The size a leased page reports for itself, or undefined when it cannot be read. */
+    viewportOfLease(sessionId: string): Promise<{
+        width: number;
+        height: number;
+    } | undefined>;
     setMocksLease(sessionId: string, rules: readonly PooledMockRule[]): Promise<boolean>;
+    /** Guard a leased page's requests, or false when this is not a lease or its page cannot. */
+    guardLease(sessionId: string, decide: (method: string, url: string) => string | undefined): Promise<boolean>;
     /** What a lease was granted when it opened, or undefined for a session that is not a lease. */
     permissionsOf(sessionId: string): readonly string[] | undefined;
     /**
@@ -205,10 +202,16 @@ export declare class BrowserPool {
     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).
+     * 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.
      */
     acquire(url: string, opts?: {
         signal?: AbortSignal;
+        /**
+         * `'wait'` (the default) queues behind the cap. `'refuse'` is for a caller that has a person
+         * or an agent waiting on the answer and no way to see a queue: it is told the pool is full.
+         */
+        whenFull?: 'wait' | 'refuse';
         sessionId?: string;
         seedStorage?: SeedStorage;
         owner?: string;
@@ -224,6 +227,8 @@ export declare class BrowserPool {
         permissions?: readonly string[];
         /** Accept a self-signed or local-CA dev certificate for this lease's context only (#1255). */
         ignoreHTTPSErrors?: boolean;
+        /** Media and viewport set on the context, so the first paint already has them. */
+        emulate?: LeaseEmulation;
     }): Promise<Lease>;
     /**
      * The websocket address this lease's page reported it could not reach, if it reported one.