@reticlehq/server 3.9.0 → 3.10.0

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

@@ -18,6 +18,7 @@
  * nothing. A cause we hold positive evidence against is not printed at all.
  */
 import { isLoopbackHostname, LeaseNotReadyReason } from '@reticlehq/core';
+import { HeldLeaseReload } from './lease-readiness.js';
 import { INIT_COMMAND } from '../../portal/session/no-session-next-action.js';
 const NUXT = 'nuxt';
 const PORT_DIFFERENTIAL = "The usual cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a " +
@@ -180,3 +181,44 @@ export function leaseReaderFailedHint(url, failure) {
         : `The zero-install reader failed on ${url}: ${failure.cause}. ${LEASE_RELEASED_SENTENCE} ` +
             'If the tab closed during setup, acquire again.';
 }
+/**
+ * The answer for a held lease that is kept although its page did not connect (#1924). The tab is
+ * kept, because its context holds the cookies: a new context starts signed out. `reload` says
+ * whether its page loaded again; `cause` is why it did not connect, or why it did not load.
+ */
+export function keptLeaseAnswer(lease, pool, cause) {
+    const reloaded = lease.reload === HeldLeaseReload.RELOADED;
+    const what = reloaded
+        ? 'Acquire loaded its page again, but the page did not connect.'
+        : `Acquire could not load ${lease.url} in it again: ${cause}`;
+    return {
+        sessionId: lease.sessionId,
+        url: lease.url,
+        ready: false,
+        notReadyReason: LeaseNotReadyReason.SDK_NEVER_DIALLED,
+        reused: true,
+        expiresInMs: pool.leaseTtlMs(),
+        leased: pool.activeCount(),
+        queued: pool.queuedCount(),
+        hint: `You already hold a lease on ${lease.origin}: ${lease.sessionId}. ${what} The tab and its ` +
+            'context are kept, so its cookies and sign-in are kept. A new context has no cookies: ' +
+            'release this lease first only if you want one, and pass seedStorage to start it signed in.' +
+            (reloaded ? ` ${cause}` : ' Acquire again when the app answers.'),
+    };
+}
+/**
+ * Why a held lease's page did not load again, said from what the daemon can check: whether
+ * anything accepts a connection on the page's port. Only asked of a loopback URL, where the probe
+ * reaches the same server the browser does.
+ */
+export async function notLoadedCause(url, portAccepts) {
+    const target = URL.canParse(url) ? new URL(url) : undefined;
+    if (portAccepts === undefined || target === undefined || !isLoopbackHostname(target.hostname)) {
+        return 'the page did not load. The app may be restarting.';
+    }
+    const defaultPort = 'https:' === target.protocol ? '443' : '80';
+    const port = '' === target.port ? defaultPort : target.port;
+    return (await portAccepts(Number(port)).catch(() => false))
+        ? `the server on port ${port} accepted the connection, but the page did not finish loading. It may still be compiling.`
+        : `nothing accepts connections on port ${port}. The app may be restarting.`;
+}

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

@@ -111,4 +111,30 @@ export declare function moveReusedLease(tabUrl: () => string | undefined, reques
     url: string;
     arrived: boolean;
 } | undefined>;
+/** What loading a held lease's tab again found. */
+export declare const HeldLeaseReload: {
+    /** Its tab had already registered, so nothing was loaded again. */
+    readonly REGISTERED: "registered";
+    /** The page loaded again. Its SDK may or may not have dialled in since. */
+    readonly RELOADED: "reloaded";
+    /** The page is still open, but it did not load: the server did not answer, or it timed out. */
+    readonly NOT_LOADED: "not-loaded";
+    /** The page is closed, or its context is gone. Nothing is left to keep. */
+    readonly GONE: "gone";
+};
+export type HeldLeaseReload = (typeof HeldLeaseReload)[keyof typeof HeldLeaseReload];
+/**
+ * Load a held lease's tab again in its own context, and wait for its SDK to dial in (#1924).
+ *
+ * A held lease whose tab never registered used to be released, and a new context minted. That
+ * context has no cookies, so a tab the agent had signed in to was closed and replaced by a
+ * signed-out one, and the retry could not get the sign-in back. The context is the sign-in, so the
+ * retry keeps it and only loads the page again. The reader the first acquire injected is an init
+ * script of that page, so it runs again on the new document by itself.
+ *
+ * A navigation that fails is not a closed tab: a dev server that restarts refuses the connection
+ * for a moment, and the context with its cookies is still there. `isOpen` asks the page something,
+ * which tells the two apart. A tab that has registered already is left alone.
+ */
+export declare function reconnectHeldLease(goto: (timeoutMs: number) => Promise<boolean>, isOpen: () => Promise<boolean>, isLoading: () => Promise<boolean>, isRegistered: () => boolean, deadline: number, now: () => number): Promise<HeldLeaseReload>;
 export {};

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

@@ -250,3 +250,82 @@ export async function moveReusedLease(tabUrl, requested, goto, now) {
     }
     return { navigated: true, url: requested, arrived: pageOf(tabUrl()) === target };
 }
+/** What loading a held lease's tab again found. */
+export const HeldLeaseReload = {
+    /** Its tab had already registered, so nothing was loaded again. */
+    REGISTERED: 'registered',
+    /** The page loaded again. Its SDK may or may not have dialled in since. */
+    RELOADED: 'reloaded',
+    /** The page is still open, but it did not load: the server did not answer, or it timed out. */
+    NOT_LOADED: 'not-loaded',
+    /** The page is closed, or its context is gone. Nothing is left to keep. */
+    GONE: 'gone',
+};
+/**
+ * Load a held lease's tab again in its own context, and wait for its SDK to dial in (#1924).
+ *
+ * A held lease whose tab never registered used to be released, and a new context minted. That
+ * context has no cookies, so a tab the agent had signed in to was closed and replaced by a
+ * signed-out one, and the retry could not get the sign-in back. The context is the sign-in, so the
+ * retry keeps it and only loads the page again. The reader the first acquire injected is an init
+ * script of that page, so it runs again on the new document by itself.
+ *
+ * A navigation that fails is not a closed tab: a dev server that restarts refuses the connection
+ * for a moment, and the context with its cookies is still there. `isOpen` asks the page something,
+ * which tells the two apart. A tab that has registered already is left alone.
+ */
+export async function reconnectHeldLease(goto, isOpen, isLoading, isRegistered, deadline, now) {
+    if (isRegistered()) {
+        return HeldLeaseReload.REGISTERED;
+    }
+    // Bounded by the acquire's own deadline. Playwright reads a timeout of 0 as "none", so at least
+    // 1 ms; and raced too, because a frozen page can hold the navigation past its own timeout.
+    const budget = Math.max(1, deadline - now());
+    const went = await answerWithin(Promise.resolve(budget).then(goto), budget + HELD_PAGE_ANSWER_MS, false);
+    if (!went) {
+        return (await pageStillOpen(isOpen)) ? HeldLeaseReload.NOT_LOADED : HeldLeaseReload.GONE;
+    }
+    const loading = () => answerWithin(isLoading(), HELD_PAGE_ANSWER_MS, false);
+    await connectOrInject({ isLoading: loading }, isRegistered, connectWaitUntil(deadline, now));
+    return HeldLeaseReload.RELOADED;
+}
+/**
+ * How long one question to a held page may take. A page that answers does so in milliseconds; a
+ * frozen one (a script in an endless loop) never does, and must not hold the acquire with it.
+ */
+const HELD_PAGE_ANSWER_MS = 250;
+/** `work`'s answer, or `fallback` when it rejects or has not answered within `ms`. */
+async function answerWithin(work, ms, fallback) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve(fallback);
+        }, ms);
+    });
+    try {
+        return await Promise.race([work.catch(() => fallback), late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** How many times a page whose navigation failed is asked whether it is still there. */
+const OPEN_PROBE_ATTEMPTS = 3;
+/**
+ * Whether a page still answers, after a navigation on it failed.
+ *
+ * Asked more than once, because the first question right after a failed navigation is often lost
+ * ("Execution context was destroyed") on a page that is still open, and the next one is answered.
+ * A closed page, or a page whose context is closed, refuses every time. A frozen page never answers,
+ * so each question is bounded, and it reads as gone.
+ */
+async function pageStillOpen(isOpen) {
+    for (let attempt = 0; attempt < OPEN_PROBE_ATTEMPTS; attempt++) {
+        const asked = Promise.resolve().then(isOpen);
+        if (await answerWithin(asked, HELD_PAGE_ANSWER_MS, false)) {
+            return true;
+        }
+        await sleep(LEASE_READY_POLL_MS);
+    }
+    return false;
+}

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

@@ -24,6 +24,11 @@ export declare const NAV_CERT_REFUSED: string;
 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;
+/**
+ * What a lease navigation that ran out of time tells the caller when the server accepted the
+ * connection: it is running and most likely compiling the route, so starting it again is wrong (#2005).
+ */
+export declare const NAV_COMPILING_ADVICE: string;
 /**
  * The sentence for a lease whose first navigation failed.
  *
@@ -35,7 +40,15 @@ export declare const NAV_TIMEOUT_ADVICE: string;
  * 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;
+export declare function navFailureMessage(url: string, err: unknown, seed?: SeedStorage, serverAccepted?: boolean): string;
+/**
+ * Whether the server behind a timed-out lease navigation accepted a connection.
+ *
+ * Only asked after a timeout and only of a loopback URL: the port probe reaches `localhost`, so a
+ * remote host would be answered by whatever listens locally on the same port. Never rejects; any
+ * doubt is `false`, which keeps the generic timeout advice.
+ */
+export declare function serverAcceptedAfterTimeout(url: string, err: unknown, seed: SeedStorage | undefined, portAccepts: ((port: number) => Promise<boolean>) | undefined): Promise<boolean>;
 /** Whether a path is a sign-in page, by its name: `/login`, `/signin`, `/auth/login` and similar. */
 export declare const isAuthPath: (pathname: string) => boolean;
 /**

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

@@ -2,7 +2,7 @@
  * 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';
+import { isLoopbackHostname, REDACTED_VALUE, scrubKnownSecrets, } from '@reticlehq/core';
 function redactExactValue(text, value) {
     if (0 === value.length)
         return text;
@@ -95,6 +95,12 @@ 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.';
+/**
+ * What a lease navigation that ran out of time tells the caller when the server accepted the
+ * connection: it is running and most likely compiling the route, so starting it again is wrong (#2005).
+ */
+export const NAV_COMPILING_ADVICE = 'The server accepted the connection, so it is running and is probably still compiling this ' +
+    'route: wait a few seconds, then acquire the lease again. Do not start another dev server.';
 /** 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';
@@ -111,7 +117,7 @@ const PLAYWRIGHT_TIMEOUT = /Timeout (\d+)ms exceeded/;
  * 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) {
+export function navFailureMessage(url, err, seed, serverAccepted = false) {
     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?"
@@ -125,7 +131,33 @@ export function navFailureMessage(url, err, seed) {
     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}`;
+    const advice = serverAccepted ? NAV_COMPILING_ADVICE : NAV_TIMEOUT_ADVICE;
+    return `could not open ${url} — ${NAV_TIMEOUT_LEAD} ${within} (${reason}). ${advice}`;
+}
+/**
+ * Whether the server behind a timed-out lease navigation accepted a connection.
+ *
+ * Only asked after a timeout and only of a loopback URL: the port probe reaches `localhost`, so a
+ * remote host would be answered by whatever listens locally on the same port. Never rejects; any
+ * doubt is `false`, which keeps the generic timeout advice.
+ */
+export async function serverAcceptedAfterTimeout(url, err, seed, portAccepts) {
+    if (portAccepts === undefined || NAV_TIMED_OUT !== cleanNavError(err, seed)) {
+        return false;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (!isLoopbackHostname(parsed.hostname)) {
+        return false;
+    }
+    const defaultPort = 'https:' === parsed.protocol ? 443 : 80;
+    const port = '' === parsed.port ? defaultPort : Number(parsed.port);
+    return portAccepts(port).catch(() => false);
 }
 /** Whether a path is a sign-in page, by its name: `/login`, `/signin`, `/auth/login` and similar. */
 export const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);

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

@@ -10,50 +10,11 @@
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
 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';
 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.
- */
-export declare function appendReticleParams(url: string, session: string, projectId?: string, hud?: HudVisibility): string;
+export { appendReticleParams, carryReticleIdentity, resolveLeasedSessionId, } from './lease-url-identity.js';
 export { cleanNavError, evaluateSeedPrecondition, scrubSeedFromError } from './lease-seed.js';
-/**
- * The session a lease's tab actually registered as, or undefined while nothing has.
- *
- * Normally that is the lease id: `appendReticleParams` stamps `__reticle_session` on the URL and the
- * SDK adopts it. An app that passes an explicit `session` to `connect()` keeps its own name instead,
- * which is legitimate — a single-app fixture does it deliberately so a battery can address it by a
- * known id. Matching on the lease id alone could never see those tabs, so the lease reported
- * `ready: false` and a hint blaming a port mismatch while the session was connected and driveable.
- *
- * The URL marker is the evidence, and it is what makes this safe: two concurrent leases on one origin
- * carry different markers, so neither can adopt the other's tab. Parsed rather than substring-matched,
- * so `lease-abc` cannot claim `lease-abcdef`.
- */
-export declare function resolveLeasedSessionId(sessions: {
-    get: (id: string) => unknown;
-    all: () => {
-        id: string;
-        url?: string;
-    }[];
-}, leaseId: string): string | undefined;
-/**
- * Carry a claimed identity across a navigation.
- *
- * A LEASED tab is addressed by `__reticle_session` in its URL: that param is how the pool finds the
- * context it opened, and — since succession was tightened — it is also the ONLY thing that lets the
- * reconnecting document inherit the lease. `reticle_navigate` sent the caller's raw URL, so the very
- * first navigation stripped the marker, the tab re-announced as an ordinary anonymous session, and
- * the lease was orphaned: "no sessions are connected at all", with a browser window still open on
- * screen. A leased browser that cannot survive being navigated is not a usable one.
- *
- * A tab that claims nothing is left exactly as it was — this must never bolt Reticle's params onto
- * a human's own URL.
- */
-export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl: string): string;
 /**
  * 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
@@ -63,6 +24,7 @@ export declare function acquireLeasedSession(pool: {
     acquire: (url: string, opts: {
         sessionId: string;
         seedStorage?: SeedStorage;
+        ignoreHTTPSErrors?: boolean;
     }) => Promise<{
         sessionId: string;
         release: () => Promise<void>;
@@ -83,7 +45,7 @@ export declare function acquireLeasedSession(pool: {
         id: string;
         url?: string;
     }[];
-}, url: string, projectId?: string, seedStorage?: SeedStorage): Promise<{
+}, url: string, projectId?: string, seedStorage?: SeedStorage, ignoreHTTPSErrors?: boolean): Promise<{
     sessionId: string;
     release: () => Promise<void>;
 }>;