@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/lease-permissions.js

@@ -0,0 +1,73 @@
+/**
+ * The `permissions` argument of `reticle_lease { action: "acquire" }` (#1370).
+ *
+ * Granted before the first navigation of a fresh lease. On an origin that already has a live lease,
+ * acquire hands back THAT lease rather than opening a second tab, and it may be another agent's tab
+ * mid-flow — nothing at this layer knows whose it is. So its grants never change there: the same list
+ * is a plain reuse, a different one is refused with the way out (release, then acquire again).
+ */
+import { z } from 'zod';
+import { ReticleTool } from '@reticlehq/core';
+import { LeasePermissionError, NOTIFICATIONS_PERMISSION, } from '../../portal/pool/context-permissions.js';
+export const LEASE_PERMISSIONS_ARG = z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Browser permissions to grant on the app origin before the first navigation, e.g. ["geolocation", "clipboard-read"]. A fresh lease starts with none granted. An origin that already has a lease keeps its grants: a different list there is refused, so release it and acquire again to change them. Names are Playwright\'s, and one it does not know is refused.');
+/** The family member these refusals come from, named the way `open-note.ts` names it. */
+const LeaseAction = { ACQUIRE: 'acquire' };
+/** How this tool's refusals name the call: built from `ReticleTool.LEASE`, not spelled out. */
+const ACQUIRE = `${ReticleTool.LEASE}{action:"${LeaseAction.ACQUIRE}"}`;
+const INVALID_PERMISSIONS = `${ACQUIRE} permissions must be a list of permission names, e.g. ["geolocation"]`;
+/** The one `Notification.permission` value that means the page can see a notifications grant. */
+const GRANTED = 'granted';
+/** The validated list, undefined when the caller passed none, or a refusal naming the right shape. */
+export function parseLeasePermissions(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = LEASE_PERMISSIONS_ARG.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(INVALID_PERMISSIONS);
+    return parsed.data;
+}
+/** A permission failure, reworded for the agent; undefined for every other error. */
+export function permissionRefusal(err) {
+    return err instanceof LeasePermissionError ? new Error(`${ACQUIRE} ${err.message}`) : undefined;
+}
+/**
+ * What to tell the agent when the page cannot see a notifications grant, else undefined.
+ *
+ * Undefined too when the page could not be asked: the grant was made, and a reading nobody took is
+ * not evidence that it failed.
+ */
+export async function notificationReadBack(pool, sessionId, permissions) {
+    if (true !== permissions?.includes(NOTIFICATIONS_PERMISSION))
+        return undefined;
+    const reading = await pool.notificationPermission(sessionId);
+    if (reading === undefined || GRANTED === reading)
+        return undefined;
+    return (`notifications was granted, but this page's Notification.permission still reads "${reading}": ` +
+        'the pooled headless browser does not support notifications, so UI gated on ' +
+        'Notification.permission will not see the grant. navigator.permissions.query({ name: "notifications" }) does report it.');
+}
+const sameSet = (a, b) => a.length === b.length &&
+    a.every((name) => b.includes(name)) &&
+    b.every((name) => a.includes(name));
+/**
+ * Refuse to reuse a held lease under a different set of grants. Nothing to refuse when the caller
+ * named no list, or the same one in any order.
+ */
+export function refuseRegrant(pool, sessionId, permissions) {
+    if (permissions === undefined)
+        return;
+    const held = pool.permissionsOf(sessionId);
+    if (held === undefined || sameSet(permissions, held))
+        return;
+    throw new Error(`${ACQUIRE} this origin's lease ${sessionId} already holds [${held.join(', ')}], and it may be ` +
+        "another agent's live tab, so its grants are not changed in place. If it is yours, release it " +
+        'and acquire again with the new list.');
+}
+/** `{ hint }` joining whichever parts are present, or nothing at all. */
+export function hintOf(...parts) {
+    const present = parts.filter((part) => part !== undefined);
+    return 0 === present.length ? {} : { hint: present.join(' ') };
+}

package/dist/surface/tools/lease-readiness.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Is a leased tab usable right now? The checks `reticle_lease` runs before it may say `ready: true`.
+ * Presence in the sessions map is not enough: the tab has to answer, and it has to be visible.
+ */
+/** The narrow slice of a session the probe needs. Anything that quacks like this works. */
+interface ProbeableSession {
+    command?: (name: string, args: Record<string, unknown>, timeoutMs: number) => Promise<unknown>;
+}
+/**
+ * Did the SDK report its tab hidden? A hidden tab answers commands while its timers and rAF are
+ * throttled, so a lease on it is `ready` by every other test and verifies nothing (#1351).
+ *
+ * Known gap: this reads the last PAGE_HEALTH, which lands just after HELLO — a check in that gap sees the
+ * default `false`. The pool foregrounding the page is what covers the gap; this catches the rest.
+ */
+export declare function tabHidden(session: unknown): boolean;
+/**
+ * Does this tab still answer?
+ *
+ * PRESENCE IS NOT LIVENESS. The sessions map still holds a tab that is attached, streaming events,
+ * and answering nothing, so `ready` read off a row in that map hands back a lease that `snapshot`,
+ * `state` and `console` then reject (#692). It has to mean the tab replied.
+ *
+ * ANY reply counts, including one that reports the command failed. The question is whether the SDK
+ * answers at all, not what it says — so an SDK too old to know the command replies
+ * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
+ * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
+ * answer, so the two cases are already separated for us.
+ *
+ * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
+ * wire command is introduced: this rides an existing round trip.
+ *
+ * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
+ * turning a lease that works into a refusal over a probe that could not run would be a worse
+ * failure than the one being fixed.
+ */
+export declare function probeLeaseAlive(session: ProbeableSession | undefined, timeoutMs?: number): Promise<boolean>;
+export {};

package/dist/surface/tools/lease-readiness.js

@@ -0,0 +1,57 @@
+/**
+ * Is a leased tab usable right now? The checks `reticle_lease` runs before it may say `ready: true`.
+ * Presence in the sessions map is not enough: the tab has to answer, and it has to be visible.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+/**
+ * How long a liveness probe waits for the tab to say anything at all.
+ *
+ * Short on purpose. This is not "finish the work", it is "are you there" — a page executing
+ * JavaScript answers a no-argument command in single-digit milliseconds, and a wedged one is not
+ * going to answer in two seconds either.
+ */
+const LEASE_PROBE_TIMEOUT_MS = 1_500;
+/**
+ * Did the SDK report its tab hidden? A hidden tab answers commands while its timers and rAF are
+ * throttled, so a lease on it is `ready` by every other test and verifies nothing (#1351).
+ *
+ * Known gap: this reads the last PAGE_HEALTH, which lands just after HELLO — a check in that gap sees the
+ * default `false`. The pool foregrounding the page is what covers the gap; this catches the rest.
+ */
+export function tabHidden(session) {
+    return (null !== session &&
+        'object' === typeof session &&
+        true === session.info?.().hidden);
+}
+/**
+ * Does this tab still answer?
+ *
+ * PRESENCE IS NOT LIVENESS. The sessions map still holds a tab that is attached, streaming events,
+ * and answering nothing, so `ready` read off a row in that map hands back a lease that `snapshot`,
+ * `state` and `console` then reject (#692). It has to mean the tab replied.
+ *
+ * ANY reply counts, including one that reports the command failed. The question is whether the SDK
+ * answers at all, not what it says — so an SDK too old to know the command replies
+ * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
+ * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
+ * answer, so the two cases are already separated for us.
+ *
+ * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
+ * wire command is introduced: this rides an existing round trip.
+ *
+ * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
+ * turning a lease that works into a refusal over a probe that could not run would be a worse
+ * failure than the one being fixed.
+ */
+export async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
+    const send = session?.command;
+    if (send === undefined)
+        return true;
+    try {
+        await send.call(session, ReticleCommand.CAPABILITIES, {}, timeoutMs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/surface/tools/lease-seed.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Seeded storage for a lease, and the errors a lease's navigation throws: what a caller may see of
+ * them without seeing the secrets it seeded. Split from lease-tools.ts, which crossed the line cap.
+ */
+import { type SeedStorage } from '@reticlehq/core';
+/**
+ * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
+ * from an error string before it reaches daemon logs, metrics, or MCP error responses.
+ */
+export declare function scrubSeedFromError(text: string, seed?: unknown): string;
+/** True for a Playwright `storageState()` export (`{ origins: [...] }`), not our seed shape. */
+export declare function looksLikeStorageStateExport(seed: unknown): boolean;
+/**
+ * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
+ * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
+ * of an internals-leaking wall of text.
+ */
+/** What {@link cleanNavError} answers for a navigation that ran out of time. */
+export declare const NAV_TIMED_OUT = "navigation timed out";
+export declare function cleanNavError(err: unknown, seed?: SeedStorage): string;
+/** What a lease whose navigation hit a certificate error tells the caller. */
+export declare const NAV_CERT_REFUSED: string;
+/** The question a failed lease navigation asks, when nothing says the app is up. */
+export declare const NAV_FAILED_QUESTION = "is the app running there?";
+/** What a lease navigation that ran out of time tells the caller to do. */
+export declare const NAV_TIMEOUT_ADVICE: string;
+/**
+ * The sentence for a lease whose first navigation failed.
+ *
+ * A timeout and a refusal are different stories and get different sentences. A refusal
+ * (`net::ERR_CONNECTION_REFUSED` and the like) means nothing is serving there, so asking whether the
+ * app is running is the right question. A timeout proves less — only that the page was not ready in
+ * time — and its most common cause is a dev server compiling a route for the first time, which
+ * routinely outlasts the navigation budget. Asking "is the app running?" there sends the agent
+ * hunting for a dev server that is up instead of retrying, so the timeout sentence names both
+ * cases and leads with the retry.
+ */
+export declare function navFailureMessage(url: string, err: unknown, seed?: SeedStorage): string;
+/**
+ * Determine if a required seedStorage application precondition failed.
+ *
+ * Checks strong signals:
+ * 1. HTTP 401/403 status on the initial navigation.
+ * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
+ * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
+ *
+ * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
+ */
+export declare function evaluateSeedPrecondition(requestedUrl: string, actualUrl: string | undefined, seed: SeedStorage, navStatus?: number): string | undefined;

package/dist/surface/tools/lease-seed.js

@@ -0,0 +1,167 @@
+/**
+ * Seeded storage for a lease, and the errors a lease's navigation throws: what a caller may see of
+ * them without seeing the secrets it seeded. Split from lease-tools.ts, which crossed the line cap.
+ */
+import { REDACTED_VALUE, scrubKnownSecrets } from '@reticlehq/core';
+function redactExactValue(text, value) {
+    if (0 === value.length)
+        return text;
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return text.replace(new RegExp(`(^|[^a-zA-Z0-9])${escaped}(?=$|[^a-zA-Z0-9])`, 'g'), `$1${REDACTED_VALUE}`);
+}
+/**
+ * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
+ * from an error string before it reaches daemon logs, metrics, or MCP error responses.
+ */
+export function scrubSeedFromError(text, seed) {
+    let out = scrubKnownSecrets(text);
+    if (undefined !== seed && null !== seed && 'object' === typeof seed) {
+        const s = seed;
+        const cookies = s['cookies'];
+        if (undefined !== cookies && null !== cookies) {
+            if (Array.isArray(cookies)) {
+                for (const c of cookies) {
+                    if (undefined !== c && null !== c && 'object' === typeof c) {
+                        const val = c['value'];
+                        if (undefined !== val && 'string' === typeof val) {
+                            out = redactExactValue(out, val);
+                        }
+                    }
+                }
+            }
+            else if ('object' === typeof cookies) {
+                for (const v of Object.values(cookies)) {
+                    if ('string' === typeof v) {
+                        out = redactExactValue(out, v);
+                    }
+                }
+            }
+        }
+        const local = s['local'];
+        if (undefined !== local && null !== local && 'object' === typeof local) {
+            for (const v of Object.values(local)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+        const session = s['session'];
+        if (undefined !== session && null !== session && 'object' === typeof session) {
+            for (const v of Object.values(session)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+    }
+    return out;
+}
+/** True for a Playwright `storageState()` export (`{ origins: [...] }`), not our seed shape. */
+export function looksLikeStorageStateExport(seed) {
+    return Array.isArray(seed?.origins);
+}
+/**
+ * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
+ * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
+ * of an internals-leaking wall of text.
+ */
+/** What {@link cleanNavError} answers for a navigation that ran out of time. */
+export const NAV_TIMED_OUT = 'navigation timed out';
+export function cleanNavError(err, seed) {
+    const rawMsg = err instanceof Error ? err.message : String(err);
+    const msg = scrubSeedFromError(rawMsg, seed);
+    // Strip ANSI color codes (ESC[…m) Playwright emits — built via fromCharCode to keep the
+    // control character out of a regex literal (no-control-regex).
+    const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+    const firstLine = (msg.split('\n')[0] ?? msg).replace(ansi, '');
+    const netCode = /net::[A-Z_]+/.exec(firstLine);
+    if (netCode !== null)
+        return netCode[0];
+    if (/timeout/i.test(firstLine))
+        return NAV_TIMED_OUT;
+    return firstLine
+        .replace(/^page\.goto:\s*/, '')
+        .replace(/\s+at\s+https?:\/\/\S+.*$/, '')
+        .trim()
+        .slice(0, 100);
+}
+/** Chromium's certificate failures: `net::ERR_CERT_AUTHORITY_INVALID`, `ERR_CERT_DATE_INVALID`, … */
+const CERT_ERROR = /^net::ERR_CERT_/;
+/** What a lease whose navigation hit a certificate error tells the caller. */
+export const NAV_CERT_REFUSED = 'the browser refused its TLS certificate, which a self-signed or mkcert dev certificate gets. ' +
+    'If it is your dev server, acquire again with ignoreHTTPSErrors: true to accept it for this lease';
+/** The question a failed lease navigation asks, when nothing says the app is up. */
+export const NAV_FAILED_QUESTION = 'is the app running there?';
+/** What a lease navigation that ran out of time tells the caller to do. */
+export const NAV_TIMEOUT_ADVICE = 'If the app is running, a dev server compiling a route for the first time can take longer than ' +
+    'that: retry the acquire. If it is not running, start it first.';
+/** Lead of the timeout sentence, before the budget ("within 30 s", or "in time" when unknown). */
+const NAV_TIMEOUT_LEAD = 'the page did not finish loading';
+const NAV_TIMEOUT_UNKNOWN_BUDGET = 'in time';
+/** Playwright's own wording for a navigation that ran out of time, with the budget it used. */
+const PLAYWRIGHT_TIMEOUT = /Timeout (\d+)ms exceeded/;
+/**
+ * The sentence for a lease whose first navigation failed.
+ *
+ * A timeout and a refusal are different stories and get different sentences. A refusal
+ * (`net::ERR_CONNECTION_REFUSED` and the like) means nothing is serving there, so asking whether the
+ * app is running is the right question. A timeout proves less — only that the page was not ready in
+ * time — and its most common cause is a dev server compiling a route for the first time, which
+ * routinely outlasts the navigation budget. Asking "is the app running?" there sends the agent
+ * hunting for a dev server that is up instead of retrying, so the timeout sentence names both
+ * cases and leads with the retry.
+ */
+export function navFailureMessage(url, err, seed) {
+    const reason = cleanNavError(err, seed);
+    // A certificate the browser refused is not an app that is down: the server answered, with a cert
+    // no CA here vouches for (a self-signed or mkcert dev certificate). Asking "is the app running?"
+    // sent the caller to restart a dev server that was fine (#1255).
+    if (CERT_ERROR.test(reason))
+        return `could not open ${url} — ${NAV_CERT_REFUSED} (${reason})`;
+    if (NAV_TIMED_OUT !== reason)
+        return `could not open ${url} — ${NAV_FAILED_QUESTION} (${reason})`;
+    const rawMsg = err instanceof Error ? err.message : String(err);
+    const budgetMs = PLAYWRIGHT_TIMEOUT.exec(rawMsg)?.[1];
+    const within = budgetMs === undefined
+        ? NAV_TIMEOUT_UNKNOWN_BUDGET
+        : `within ${String(Number(budgetMs) / 1000)} s`;
+    return `could not open ${url} — ${NAV_TIMEOUT_LEAD} ${within} (${reason}). ${NAV_TIMEOUT_ADVICE}`;
+}
+/**
+ * Determine if a required seedStorage application precondition failed.
+ *
+ * Checks strong signals:
+ * 1. HTTP 401/403 status on the initial navigation.
+ * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
+ * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
+ *
+ * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
+ */
+export function evaluateSeedPrecondition(requestedUrl, actualUrl, seed, navStatus) {
+    if (401 === navStatus || 403 === navStatus) {
+        return `HTTP ${navStatus} returned on initial seeded navigation to ${requestedUrl}`;
+    }
+    if (actualUrl === undefined || '' === actualUrl.trim())
+        return undefined;
+    let reqParsed;
+    let actParsed;
+    try {
+        reqParsed = new URL(requestedUrl);
+        actParsed = new URL(actualUrl);
+    }
+    catch {
+        return undefined;
+    }
+    // Cross-origin redirect when local or session storage was requested
+    const hasStorage = (undefined !== seed.local && 0 < Object.keys(seed.local).length) ||
+        (undefined !== seed.session && 0 < Object.keys(seed.session).length);
+    if (hasStorage && reqParsed.origin !== actParsed.origin) {
+        return `seeded storage precondition not established: cross-origin redirect from ${reqParsed.origin} to ${actParsed.origin} skipped origin-scoped storage injection`;
+    }
+    // Clear redirect to an authentication/login endpoint when the requested URL was not a login page
+    const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);
+    if (!isAuthPath(reqParsed.pathname) && isAuthPath(actParsed.pathname)) {
+        return `seeded authentication precondition not established: redirected from ${reqParsed.pathname} to login page (${actParsed.pathname})`;
+    }
+    return undefined;
+}

package/dist/surface/tools/lease-tools.d.ts

@@ -14,34 +14,15 @@ import { type StorageFixturePort } from '../../portal/input/storage-fixture.js';
 import { type NetworkMutationPort } from '../../portal/input/network-mutation.js';
 import type { Perturbation } from '@reticlehq/core';
 import { type SeedStorage } from '@reticlehq/core';
-import type { ToolDef } from './tool-kit.js';
+import { HudVisibility } from '@reticlehq/core';
+import { type ToolDef, type ToolDeps } from './tool-kit.js';
+import type { BrowserPool } from '../../portal/pool/browser-pool.js';
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
  */
-export declare function appendReticleParams(url: string, session: string, projectId?: string): string;
-/**
- * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
- * from an error string before it reaches daemon logs, metrics, or MCP error responses.
- */
-export declare function scrubSeedFromError(text: string, seed?: unknown): string;
-/**
- * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
- * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
- * of an internals-leaking wall of text.
- */
-export declare function cleanNavError(err: unknown, seed?: SeedStorage): string;
-/**
- * Determine if a required seedStorage application precondition failed.
- *
- * Checks strong signals:
- * 1. HTTP 401/403 status on the initial navigation.
- * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
- * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
- *
- * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
- */
-export declare function evaluateSeedPrecondition(requestedUrl: string, actualUrl: string | undefined, seed: SeedStorage, navStatus?: number): string | undefined;
+export declare function appendReticleParams(url: string, session: string, projectId?: string, hud?: HudVisibility): string;
+export { cleanNavError, evaluateSeedPrecondition, scrubSeedFromError } from './lease-seed.js';
 /**
  * The session a lease's tab actually registered as, or undefined while nothing has.
  *
@@ -132,6 +113,14 @@ export declare function connectOrInject(lease: {
 }>;
 export declare function hasOriginLock(origin: string): boolean;
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
+/**
+ * Release one lease and everything that hangs off it. Returns how many leases are still held.
+ *
+ * Shared with `reticle_session { action: "end" }`: an ended session that kept its lease stayed
+ * connected until the reaper took it, and every id-less call from the next agent was refused as
+ * ambiguous in the meantime.
+ */
+export declare function releaseLease(deps: ToolDeps, pool: BrowserPool, sessionId: string): Promise<number>;
 export declare const LEASE_TOOLS: ToolDef[];
 /**
  * The state a suite should boot its flows from: whatever the agent is already sitting in.