@reticlehq/server 3.7.0 → 3.8.1

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

@@ -8,7 +8,7 @@
  */
 import { z } from 'zod';
 import type { BrowserPool } from '../../portal/pool/browser-pool.js';
-export declare const LEASE_PERMISSIONS_ARG: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+export declare const LEASE_PERMISSIONS_ARG: z.ZodOptional<z.ZodArray<z.ZodString>>;
 type PermissionPool = Pick<BrowserPool, 'notificationPermission'>;
 /** The validated list, undefined when the caller passed none, or a refusal naming the right shape. */
 export declare function parseLeasePermissions(raw: unknown): readonly string[] | undefined;

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

@@ -1,7 +1,10 @@
 /**
  * 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 wait for the tab to connect is here too, with the zero-install reader for a page that stays silent,
+ * and the move that takes a reused lease to the page it was asked for.
  */
+import { LeaseNotReadyReason } from '@reticlehq/core';
 /** 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>;
@@ -14,6 +17,11 @@ interface ProbeableSession {
  * default `false`. The pool foregrounding the page is what covers the gap; this catches the rest.
  */
 export declare function tabHidden(session: unknown): boolean;
+/**
+ * Why a lease that connected is not ready: `failed` when it did not answer, `tab_hidden` when it
+ * answers from a hidden tab, nothing when it is ready.
+ */
+export declare function notReadyReason(answered: boolean, session: unknown, failed?: LeaseNotReadyReason): LeaseNotReadyReason | undefined;
 /**
  * Does this tab still answer?
  *
@@ -35,4 +43,51 @@ export declare function tabHidden(session: unknown): boolean;
  * failure than the one being fixed.
  */
 export declare function probeLeaseAlive(session: ProbeableSession | undefined, timeoutMs?: number): Promise<boolean>;
+/**
+ * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
+ * is immediately usable (the page navigates first, then connects a moment later — without this wait
+ * an agent's very next call could race and hit "no connected session"). Returns whether it connected
+ * in time. `isConnected`, `sleeper`, and `attempts` are injected so this is fast to unit-test.
+ */
+export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
+/**
+ * Wait for the leased tab to connect; if its app never does, hand it the zero-install reader.
+ *
+ * The decision is taken HERE, by the daemon, on the one fact that settles it: no HELLO arrived. A
+ * timer inside the page cannot know that — an app can connect from a dynamic import that resolves
+ * after `load` — and a reader injected into a page whose app was about to connect would take its
+ * place and drop the app's own options. So an app that connected itself is never touched, and a page
+ * that stayed silent through the whole readiness wait is the one that gets a reader.
+ */
+export declare function connectOrInject(lease: {
+    injectReader?: () => Promise<boolean>;
+    isLoading?: () => Promise<boolean>;
+    release?: () => Promise<void>;
+}, isConnected: () => boolean, wait?: (isConnected: () => boolean) => Promise<boolean>, graceRounds?: number): Promise<{
+    ready: boolean;
+    zeroInstall: boolean;
+    stillLoading?: true;
+    readerFailure?: LeaseReaderFailure;
+}>;
+/** Why the zero-install reader did not run, and the short cause that the hint shows. */
+export interface LeaseReaderFailure {
+    reason: LeaseNotReadyReason;
+    cause: string;
+}
+/**
+ * Move a reused lease to the page it was asked for (#1667).
+ *
+ * Reuse hands back the tab wherever the last caller left it. Answering with the requested url
+ * while the tab stayed elsewhere sent the next read to another page. So the tab goes there, and
+ * the answer waits for its SDK to come back on that page, as a minted lease's does.
+ *
+ * `undefined` when there is nothing to move: the tab is already there, or its url is unknown.
+ * Otherwise `navigated` says whether the tab got there, `url` is the page it is on, and `arrived`
+ * whether its SDK connected there within the wait.
+ */
+export declare function moveReusedLease(tabUrl: () => string | undefined, requested: string, goto: () => Promise<boolean>, now: () => number): Promise<{
+    navigated: boolean;
+    url: string;
+    arrived: boolean;
+} | undefined>;
 export {};

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

@@ -1,8 +1,11 @@
 /**
  * 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 wait for the tab to connect is here too, with the zero-install reader for a page that stays silent,
+ * and the move that takes a reused lease to the page it was asked for.
  */
-import { ReticleCommand } from '@reticlehq/core';
+import { LeaseNotReadyReason, ReticleCommand, RETICLE_URL_PARAM } from '@reticlehq/core';
+import { NotHtmlDocumentError } from '../../portal/pool/zero-install.js';
 /**
  * How long a liveness probe waits for the tab to say anything at all.
  *
@@ -23,6 +26,16 @@ export function tabHidden(session) {
         'object' === typeof session &&
         true === session.info?.().hidden);
 }
+/**
+ * Why a lease that connected is not ready: `failed` when it did not answer, `tab_hidden` when it
+ * answers from a hidden tab, nothing when it is ready.
+ */
+export function notReadyReason(answered, session, failed = LeaseNotReadyReason.SDK_STOPPED_ANSWERING) {
+    if (!answered) {
+        return failed;
+    }
+    return tabHidden(session) ? LeaseNotReadyReason.TAB_HIDDEN : undefined;
+}
 /**
  * Does this tab still answer?
  *
@@ -45,8 +58,9 @@ export function tabHidden(session) {
  */
 export async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
     const send = session?.command;
-    if (send === undefined)
+    if (send === undefined) {
         return true;
+    }
     try {
         await send.call(session, ReticleCommand.CAPABILITIES, {}, timeoutMs);
         return true;
@@ -55,3 +69,137 @@ export async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_M
         return false;
     }
 }
+const LEASE_READY_ATTEMPTS = 100;
+const LEASE_READY_POLL_MS = 100;
+/** Extra readiness waits allowed while the leased page is still loading (each one is ~10 s). */
+const LEASE_LOADING_GRACE_ROUNDS = 3;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
+ * is immediately usable (the page navigates first, then connects a moment later — without this wait
+ * an agent's very next call could race and hit "no connected session"). Returns whether it connected
+ * in time. `isConnected`, `sleeper`, and `attempts` are injected so this is fast to unit-test.
+ */
+export async function waitForLeasedSession(isConnected, sleeper = sleep, attempts = LEASE_READY_ATTEMPTS, pollMs = LEASE_READY_POLL_MS) {
+    for (let i = 0; i < attempts; i++) {
+        if (isConnected()) {
+            return true;
+        }
+        await sleeper(pollMs);
+    }
+    return isConnected();
+}
+/**
+ * Wait for the leased tab to connect; if its app never does, hand it the zero-install reader.
+ *
+ * The decision is taken HERE, by the daemon, on the one fact that settles it: no HELLO arrived. A
+ * timer inside the page cannot know that — an app can connect from a dynamic import that resolves
+ * after `load` — and a reader injected into a page whose app was about to connect would take its
+ * place and drop the app's own options. So an app that connected itself is never touched, and a page
+ * that stayed silent through the whole readiness wait is the one that gets a reader.
+ */
+export async function connectOrInject(lease, isConnected, wait = waitForLeasedSession, graceRounds = LEASE_LOADING_GRACE_ROUNDS) {
+    if (await wait(isConnected)) {
+        return { ready: true, zeroInstall: false };
+    }
+    let injected;
+    try {
+        injected = true === (await lease.injectReader?.());
+    }
+    catch (err) {
+        // No SDK can connect to this tab now (#1701). Release the lease, so that its slot is free.
+        await lease.release?.().catch(() => undefined);
+        return { ready: false, zeroInstall: false, readerFailure: readerFailureOf(err) };
+    }
+    if (injected && (await wait(isConnected))) {
+        return { ready: true, zeroInstall: true };
+    }
+    // A slow first dev compile can hold the document past both waits, and its app connects a moment
+    // later (#1555). Keep waiting while the page itself says it is still loading, bounded so a page
+    // that never finishes cannot hold the acquire forever.
+    for (let round = 0; round < graceRounds; round++) {
+        if (!(await pageStillLoading(lease))) {
+            break;
+        }
+        if (await wait(isConnected)) {
+            return { ready: true, zeroInstall: injected };
+        }
+    }
+    // Re-check right before answering: a connect that landed during the last loading probe counts.
+    if (isConnected()) {
+        return { ready: true, zeroInstall: injected };
+    }
+    return (await pageStillLoading(lease))
+        ? { ready: false, zeroInstall: false, stillLoading: true }
+        : { ready: false, zeroInstall: false };
+}
+/** Whether the leased page reports it has not finished loading. Unknown counts as loaded. */
+async function pageStillLoading(lease) {
+    try {
+        return true === (await lease.isLoading?.());
+    }
+    catch {
+        return false;
+    }
+}
+/** The longest cause that a reader failure keeps. A Playwright error can carry a long call log. */
+const READER_CAUSE_MAX_CHARS = 200;
+function readerFailureOf(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Only the first line: the lines after it are the Playwright call log, not the cause.
+    const cause = (message.split('\n')[0] ?? '').slice(0, READER_CAUSE_MAX_CHARS);
+    return {
+        reason: err instanceof NotHtmlDocumentError
+            ? LeaseNotReadyReason.NOT_HTML_DOCUMENT
+            : LeaseNotReadyReason.READER_FAILED,
+        cause,
+    };
+}
+/** How long a moved lease's SDK gets to come back on the new page: the mint path's wait. */
+const REUSED_ARRIVAL_MS = LEASE_READY_ATTEMPTS * LEASE_READY_POLL_MS;
+/** A URL as a page: without Reticle's own params or the fragment. Undefined when it is not a URL. */
+function pageOf(url) {
+    if (url === undefined) {
+        return undefined;
+    }
+    try {
+        const u = new URL(url);
+        for (const param of Object.values(RETICLE_URL_PARAM)) {
+            u.searchParams.delete(param);
+        }
+        u.hash = '';
+        return u.href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Move a reused lease to the page it was asked for (#1667).
+ *
+ * Reuse hands back the tab wherever the last caller left it. Answering with the requested url
+ * while the tab stayed elsewhere sent the next read to another page. So the tab goes there, and
+ * the answer waits for its SDK to come back on that page, as a minted lease's does.
+ *
+ * `undefined` when there is nothing to move: the tab is already there, or its url is unknown.
+ * Otherwise `navigated` says whether the tab got there, `url` is the page it is on, and `arrived`
+ * whether its SDK connected there within the wait.
+ */
+export async function moveReusedLease(tabUrl, requested, goto, now) {
+    const from = tabUrl();
+    const target = pageOf(requested);
+    if (pageOf(from) === undefined || target === undefined || pageOf(from) === target) {
+        return undefined;
+    }
+    const went = await Promise.resolve()
+        .then(goto)
+        .catch(() => false);
+    if (!went) {
+        return { navigated: false, url: from ?? requested, arrived: true };
+    }
+    const start = now();
+    while (pageOf(tabUrl()) !== target && now() - start < REUSED_ARRIVAL_MS) {
+        await sleep(LEASE_READY_POLL_MS);
+    }
+    return { navigated: true, url: requested, arrived: pageOf(tabUrl()) === target };
+}

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

@@ -9,14 +9,11 @@
  *
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
-import type { RealInputProvider } from '../../portal/input/real-input.js';
-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 { HudVisibility } from '@reticlehq/core';
 import { type ToolDef, type ToolDeps } from './tool-kit.js';
-import type { BrowserPool } from '../../portal/pool/browser-pool.js';
+import { type BrowserPool } from '../../portal/pool/browser-pool.js';
+export { sessionMutationPort, sessionPerturbationPort, suiteFixturePort, suiteFixtureSeed, } from './session-ports.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.
@@ -57,12 +54,6 @@ export declare function resolveLeasedSessionId(sessions: {
  * a human's own URL.
  */
 export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl: string): string;
-/**
- * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
- * is immediately usable (the page navigates first, then connects a moment later — without this wait
- * an agent's very next call could race and hit "no connected session"). Returns whether it connected
- * in time. `isConnected`, `sleeper`, and `attempts` are injected so this is fast to unit-test.
- */
 /**
  * Acquire a leased, SDK-connected context for a caller that is not the lease TOOL (the parallel suite).
  * Returns the session id plus its release; the caller must release in a finally so a crashed flow never
@@ -77,6 +68,7 @@ export declare function acquireLeasedSession(pool: {
         release: () => Promise<void>;
         navStatus?: number;
         injectReader?: () => Promise<boolean>;
+        isLoading?: () => Promise<boolean>;
     }>;
     /**
      * The address this lease's page said it could not reach. Optional so a test double need not
@@ -95,22 +87,6 @@ export declare function acquireLeasedSession(pool: {
     sessionId: string;
     release: () => Promise<void>;
 }>;
-export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
-/**
- * Wait for the leased tab to connect; if its app never does, hand it the zero-install reader.
- *
- * The decision is taken HERE, by the daemon, on the one fact that settles it: no HELLO arrived. A
- * timer inside the page cannot know that — an app can connect from a dynamic import that resolves
- * after `load` — and a reader injected into a page whose app was about to connect would take its
- * place and drop the app's own options. So an app that connected itself is never touched, and a page
- * that stayed silent through the whole readiness wait is the one that gets a reader.
- */
-export declare function connectOrInject(lease: {
-    injectReader?: () => Promise<boolean>;
-}, isConnected: () => boolean, wait?: (isConnected: () => boolean) => Promise<boolean>): Promise<{
-    ready: boolean;
-    zeroInstall: boolean;
-}>;
 export declare function hasOriginLock(origin: string): boolean;
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
 /**
@@ -122,51 +98,3 @@ export declare const LEASE_ACQUIRE_TOOL: ToolDef;
  */
 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.
- *
- * This is the join the fixture work was building toward. A suite's flows each start from cold, so
- * fifty of them prove the login works fifty times — and the flow that LOGS OUT leaves every flow
- * after it signed out, which no navigation repairs, because the problem is not where the subject is
- * but what it holds. A seed is applied to an isolated context BEFORE the first navigation, which is
- * exactly and only when a fixture can work.
- *
- * Best-effort, deliberately. A fixture is an OPTIMISATION over running from cold, and running from
- * cold is correct: a suite that refused to start because a cookie jar could not be read would have
- * traded a slow answer for no answer. Every "no" here — no provider, no storage support, nothing
- * driven, a browser that threw, nothing worth seeding — produces the same honest `undefined`, and
- * the suite runs exactly as it did before any of this existed.
- */
-export declare function suiteFixtureSeed(realInput: RealInputProvider | undefined, appUrl: string): Promise<SeedStorage | undefined>;
-/**
- * A way to make this session's page SLOW on purpose, or nothing.
- *
- * The third of these seams, for the same reason as the other two: a feature reaching into the input
- * layer directly is a feature depending on a driver, and the boundary guard asks about it.
- *
- * Installs delays and NOTHING else. A rule that carried a status or a body would substitute a
- * response the server never sent, and an app raced against invented data produces invented races —
- * a fabricated defect handed to somebody at 3am, which is worse than finding nothing.
- */
-export declare function sessionPerturbationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<{
-    slow(rules: readonly Perturbation[]): Promise<void>;
-    clear(): Promise<void>;
-} | undefined>;
-/**
- * Save/restore for this session's page, or nothing.
- *
- * The same job as `suiteFixtureSeed` next door, stopping one step earlier: that one captures and
- * converts, this hands back the PORT so a caller can re-apply what it captured later. It lives here
- * for the reason written above — a feature reaching into the input layer directly is a feature
- * depending on a driver, and the boundary guard asks about it. It asked.
- */
-export declare function suiteFixturePort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<StorageFixturePort | undefined>;
-/**
- * A way to break this session's page, or nothing.
- *
- * Sits beside `suiteFixtureSeed` because it is the same shape of job: turning a provider capability
- * into something a feature can use, on the one side of the graph that is allowed to know about both.
- * A flow tool reaching into the input layer directly would be a feature depending on a driver, which
- * is the reach the boundary guard exists to ask about.
- */
-export declare function sessionMutationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<NetworkMutationPort | undefined>;