@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/input/storage-fixture.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Turning a driven browser into somewhere a suite can start from.
+ *
+ * A realm offers `applyFixture` only when something can honour it, and on the web that is not a
+ * property of the realm — it is a property of the CONNECTION. The wire settles it: there is a
+ * `storage_read` command and no storage write, and a page cannot write an httpOnly cookie from
+ * inside itself, which is the entire point of httpOnly. So an ATTACHED session can never restore
+ * auth however much is added to the SDK; a DRIVEN page can, because a browser context sits behind
+ * it and that context owns the cookie jar.
+ *
+ * This is therefore the one place that decides whether a web fixture exists at all, and the answer
+ * is "no" far more often than "yes" — which is correct, and merely slower: every flow runs from cold.
+ */
+import type { SeedStorage } from '@reticlehq/core';
+import type { RealInputProvider } from './real-input.js';
+/**
+ * What this hands back: save and restore, and nothing else.
+ *
+ * Declared here rather than imported from the realm that consumes it, deliberately. The realm owns
+ * the interface it DEPENDS on and this file owns the thing that provides one; neither needs to know
+ * the other exists, and they meet at the composition root where TypeScript checks the shapes agree.
+ * Importing the realm's port here would make a provider depend on its consumer, which is the
+ * inversion backwards — and the reach guard says so before anybody has to argue about it.
+ */
+export interface StorageFixturePort {
+    capture(): Promise<unknown>;
+    apply(payload: unknown): Promise<void>;
+}
+/**
+ * A port for this session, or nothing.
+ *
+ * Nothing when the provider cannot do storage at all, and nothing when it is not driving THIS page.
+ * The second case matters as much as the first: a provider that answered for a page it does not
+ * drive would restore state into whatever page it happened to find, which is worse than refusing.
+ */
+export declare function fixturePortFor(provider: RealInputProvider, sessionUrl: string): Promise<StorageFixturePort | undefined>;
+/**
+ * Turn state a browser saved into something a lease can be BOOTED with.
+ *
+ * `SeedStorage` is applied to an isolated context before the first navigation, which is exactly and
+ * only when a fixture can work: restoring a cookie jar into a page that has already decided it is
+ * signed out is a fixture that appears to work and does nothing.
+ *
+ * The two shapes do not line up, and the mismatch is the reason this function exists rather than a
+ * spread:
+ *
+ *   - a context state is per-ORIGIN and a lease is booted at one URL, so another origin's
+ *     localStorage is dropped. Seeding it would write keys belonging to a site this run never
+ *     visits, under the name of a fixture somebody trusts.
+ *   - a context state carries no sessionStorage at all, so `session` is left ABSENT rather than set
+ *     to an empty object. A suite relying on a flag it was never given should find nothing, not
+ *     something that looks restored and is empty.
+ *
+ * Returns nothing when there is nothing to seed — an empty fixture is not a fixture, and a lease
+ * asked to boot with one would pay the isolation cost for no state.
+ */
+export declare function seedFromStorageState(state: unknown, pageUrl: string): SeedStorage | undefined;

package/dist/portal/input/storage-fixture.js

@@ -0,0 +1,92 @@
+/**
+ * Turning a driven browser into somewhere a suite can start from.
+ *
+ * A realm offers `applyFixture` only when something can honour it, and on the web that is not a
+ * property of the realm — it is a property of the CONNECTION. The wire settles it: there is a
+ * `storage_read` command and no storage write, and a page cannot write an httpOnly cookie from
+ * inside itself, which is the entire point of httpOnly. So an ATTACHED session can never restore
+ * auth however much is added to the SDK; a DRIVEN page can, because a browser context sits behind
+ * it and that context owns the cookie jar.
+ *
+ * This is therefore the one place that decides whether a web fixture exists at all, and the answer
+ * is "no" far more often than "yes" — which is correct, and merely slower: every flow runs from cold.
+ */
+/**
+ * A port for this session, or nothing.
+ *
+ * Nothing when the provider cannot do storage at all, and nothing when it is not driving THIS page.
+ * The second case matters as much as the first: a provider that answered for a page it does not
+ * drive would restore state into whatever page it happened to find, which is worse than refusing.
+ */
+export async function fixturePortFor(provider, sessionUrl) {
+    // Not destructured: a method pulled off its object loses `this`, and these are real methods on a
+    // provider that holds a browser.
+    if (provider.storageState === undefined || provider.applyStorageState === undefined) {
+        return undefined;
+    }
+    if (!(await provider.isAvailableFor(sessionUrl)))
+        return undefined;
+    return {
+        /** Verbatim, and opaque: only the browser that wrote this can read it back. */
+        capture: () => provider.storageState?.(sessionUrl) ?? Promise.resolve(undefined),
+        apply: async (payload) => {
+            const restored = await provider.applyStorageState?.(sessionUrl, payload);
+            /*
+             * A refusal is thrown, never swallowed.
+             *
+             * Silence is the whole failure mode here: a suite that believes it is signed in and is not
+             * produces fifty flows failing for a reason none of them names, and the first one anybody
+             * reads blames the feature it was testing.
+             */
+            // `undefined` cannot happen — the method was checked above — but it is the same answer as
+            // false either way: nothing confirmed the state went back.
+            if (true !== restored) {
+                throw new Error(`could not restore state into ${sessionUrl}: no driven page matched this session when ` +
+                    'the fixture was applied. A fixture needs a driven browser (`reticle drive` / ' +
+                    'RETICLE_CDP_URL); an attached tab cannot have a cookie jar written into it from ' +
+                    'inside the page.');
+            }
+        },
+    };
+}
+/**
+ * Turn state a browser saved into something a lease can be BOOTED with.
+ *
+ * `SeedStorage` is applied to an isolated context before the first navigation, which is exactly and
+ * only when a fixture can work: restoring a cookie jar into a page that has already decided it is
+ * signed out is a fixture that appears to work and does nothing.
+ *
+ * The two shapes do not line up, and the mismatch is the reason this function exists rather than a
+ * spread:
+ *
+ *   - a context state is per-ORIGIN and a lease is booted at one URL, so another origin's
+ *     localStorage is dropped. Seeding it would write keys belonging to a site this run never
+ *     visits, under the name of a fixture somebody trusts.
+ *   - a context state carries no sessionStorage at all, so `session` is left ABSENT rather than set
+ *     to an empty object. A suite relying on a flag it was never given should find nothing, not
+ *     something that looks restored and is empty.
+ *
+ * Returns nothing when there is nothing to seed — an empty fixture is not a fixture, and a lease
+ * asked to boot with one would pay the isolation cost for no state.
+ */
+export function seedFromStorageState(state, pageUrl) {
+    if ('object' !== typeof state || null === state)
+        return undefined;
+    const saved = state;
+    const local = {};
+    for (const origin of saved.origins ?? []) {
+        if (!pageUrl.startsWith(origin.origin))
+            continue;
+        for (const entry of origin.localStorage ?? [])
+            local[entry.name] = entry.value;
+    }
+    const cookies = saved.cookies ?? [];
+    const hasCookies = Array.isArray(cookies) ? cookies.length > 0 : Object.keys(cookies).length > 0;
+    const hasLocal = Object.keys(local).length > 0;
+    if (!hasCookies && !hasLocal)
+        return undefined;
+    return {
+        ...(hasCookies ? { cookies } : {}),
+        ...(hasLocal ? { local } : {}),
+    };
+}

package/dist/portal/input/viewport-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+export declare const VIEWPORT_TOOLS: ToolDef[];

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

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
+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';
+/** 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;
+function viewportProvider(deps) {
+    const p = deps.realInput;
+    return p !== undefined && 'function' === typeof p.setViewport
+        ? p
+        : undefined;
+}
+export const VIEWPORT_TOOLS = [
+    {
+        name: ReticleTool.VIEWPORT,
+        description: 'Pin the DRIVEN page (needs `reticle drive`) 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.',
+        inputSchema: {
+            width: viewportPxSchema.describe('Viewport width in CSS px (e.g. 1280).'),
+            height: viewportPxSchema.describe('Viewport height in CSS px (e.g. 800).'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            applied: z.boolean(),
+            width: z.number(),
+            height: z.number(),
+            ok: z.boolean().optional(),
+            reason: z.string().optional(),
+            recommendation: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const width = clampDim(args['width']);
+            const height = clampDim(args['height']);
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const provider = viewportProvider(deps);
+            if (provider !== undefined) {
+                const applied = await provider.setViewport(session.url, { width, height });
+                if (applied)
+                    return { applied: true, width, height };
+            }
+            // 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
+            // follows: when both exist, drive is the page the caller means and a lease is the fallback.
+            //
+            // Without this, `reticle_viewport` refused on every SDK-only install, which is the DEFAULT
+            // install. Reported from the field: mobile-only UI — a `lg:hidden` hamburger, a drawer that
+            // 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: CDP_NO_PROVIDER_RECOMMENDATION,
+            };
+        },
+    },
+];
+/** Clamp a requested dimension into [MIN_DIM, MAX_DIM]; a missing/NaN value falls back to MIN_DIM. */
+function clampDim(value) {
+    const n = 'number' === typeof value && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
+    return Math.max(MIN_DIM, Math.min(n, MAX_DIM));
+}

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

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+import { type SeedStorage } from '@reticlehq/core';
+import type { Launcher, PooledMockRule } from './pool-contract.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>;
+}
+/** 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>;
+}