@reticlehq/server 2.14.0 → 3.2.0

package/dist/tools/lease-hint.js

@@ -1,124 +0,0 @@
-/**
- * Why a leased tab did not dial in.
- *
- * The lease pool opens the app itself, which is what makes it the highest-value path in the product
- * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
- * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
- *
- * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
- * cannot be in doubt: the pool just navigated a real browser to it. Its replacement then swung to
- * the other confident-but-unevidenced claim — "the usual cause is a PORT MISMATCH" — and the daemon
- * ended up contradicting ITSELF inside one response, saying in `reticle_sessions` that a session had
- * connected earlier "so the wiring is correct" and here that the port was probably wrong. Across a
- * batch of field reports on four apps the port was correct every single time, and `reticle init`
- * would have been the wrong action every single time.
- *
- * So: rank by what the daemon actually knows, and fall back to the differential only when it knows
- * nothing. A cause we hold positive evidence against is not printed at all.
- */
-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 " +
-    "daemon on a different port never hears from it — check the app's reticle port (`.reticle.json`, " +
-    "RETICLE_PORT, or the build plugin's `port`), or start the daemon on the port the app expects.";
-/**
- * The causes that actually occur on a wired app, in the order they occur. Mirrors the no-session
- * diagnosis deliberately: two surfaces answering the same question must not rank it differently.
- */
-const REAL_CAUSES = 'Causes that produce exactly this and are NOT a port problem: (a) the SDK is in the bundle but ' +
-    '`connect()` is never reached — a dev-mode guard or a missing runtime-config value returning ' +
-    'early, which emits nothing at all; (b) the dev server was started BEFORE the Reticle plugin was ' +
-    'added, so it is not in the bundle — restart it, HMR is not enough; (c) a peer dependency is ' +
-    'missing (typically `@reticlehq/react` in a non-React app) so the dynamic import fails silently; ' +
-    '(d) the page is not on localhost, where the SDK needs BOTH `allowNonLocalhost: true` and a ' +
-    'pairing token — the flag alone is not sufficient.';
-const NUXT_FIRST = 'This project is Nuxt: the most likely cause by a distance is a dev server that predates the ' +
-    'Reticle plugin, because Nuxt does NOT register a newly added plugin on HMR. Restart `nuxt dev` ' +
-    'and re-acquire before investigating anything else.';
-const RELEASE = 'The tab stays leased either way — release it with reticle_lease{action:"release"}.';
-function markerClause(sdkMarker) {
-    if (sdkMarker === undefined)
-        return '';
-    return sdkMarker
-        ? ' A Reticle SDK marker WAS found in the page that loaded, so the app does ship the SDK — the ' +
-            'question is only why it did not reach this daemon.'
-        : ' No Reticle SDK marker was found in the page that loaded. That is a check of the SERVED ' +
-            'document, so a lazily-imported SDK can still be missed — but combined with the rest it ' +
-            'points at a bundle that carries no Reticle at all, i.e. wiring that never took effect.';
-}
-/**
- * The port a websocket URL names, or undefined when it names none we can read.
- *
- * `ws://host/path` with no explicit port is deliberately undefined rather than defaulted to 80: a
- * guessed port compared against the daemon's would manufacture a mismatch out of nothing, and this
- * branch outranks every other cause. No answer is correct here; a plausible one is not.
- */
-function dialledPort(url) {
-    if (url === undefined)
-        return undefined;
-    try {
-        const port = new URL(url).port;
-        return '' === port ? undefined : Number(port);
-    }
-    catch {
-        return undefined;
-    }
-}
-export function leaseNotConnectedHint(url, port, evidence = {}) {
-    const opening = `the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}).`;
-    const marker = markerClause(evidence.sdkMarker);
-    // 0. The page told us where it dialled, and it was not here. Proof, and it outranks the refusal
-    //    branch below: a refusal proves a dial reached THIS daemon, which is a fact about some page;
-    //    this is a fact about the page in hand. When they disagree, the specific one wins.
-    //
-    //    Neither side can reach this conclusion alone, which is why it went unsaid for so long. The
-    //    page's own warning deliberately refuses to diagnose the daemon — from inside a browser a
-    //    daemon that is absent and one that is unreachable are the same observation. The daemon cannot
-    //    see a dial that never arrived. Put the address the page names beside the port the daemon is
-    //    bound to and the ambiguity disappears.
-    const dialled = dialledPort(evidence.dialledUrl);
-    if (dialled !== undefined && dialled !== port) {
-        return (`${opening} The page dialled ${String(evidence.dialledUrl)} (port ${String(dialled)}) and ` +
-            `this daemon is on ${String(port)}, so the dial never reached it. Nothing about the app's ` +
-            `wiring is in question. Either start the daemon on ${String(dialled)}, or point the app at ` +
-            `${String(port)} — the app's port comes from its build config (\`.reticle.json\`, ` +
-            `RETICLE_PORT, or the build plugin's \`port\`), and \`VITE_RETICLE_WS_URL\` overrides it ` +
-            `outright.${marker} ${RELEASE}`);
-    }
-    // 1. A recorded refusal. The only cause with proof behind it, so nothing outranks it.
-    if (evidence.refusal !== undefined) {
-        return `${opening} A dial DID arrive and was refused: ${evidence.refusal}${marker} ${RELEASE}`;
-    }
-    // 2. Nuxt, whose most likely cause differs from every other framework's and which `init` warns
-    //    about at install time — while this hint never mentioned it.
-    const nuxt = evidence.framework?.toLowerCase() === NUXT ? ` ${NUXT_FIRST}` : '';
-    // 3. Proven PORT. Blaming the port here is the self-contradiction this rewrite exists to end —
-    //    but "the wiring is correct" was a second claim, and it was not proven at all.
-    //
-    //    `previouslyConnected` is scoped to project + port, never to the app. In a monorepo, or for
-    //    anyone adding a second app, the thing that connected yesterday is a DIFFERENT app. Measured:
-    //    an uninstrumented app driven in exactly that situation was told its wiring was correct, and
-    //    handed four causes — a dev-mode guard, a stale dev server, a missing peer dependency, a
-    //    non-localhost page — every one of which presupposes the SDK is already installed. It was
-    //    not. That is the commonest failure there is, and `reticle init` appeared nowhere in the
-    //    answer, because the only branch that mentions it is the one reached when nothing is known.
-    if (true === evidence.previouslyConnected) {
-        const notThisApp = true === evidence.sdkMarker
-            ? ''
-            : ' That may have been a DIFFERENT app, though: this one may carry no Reticle SDK at all, ' +
-                'in which case run `reticle init` in ITS directory first — every cause below assumes the ' +
-                'SDK is already installed.';
-        return (`${opening} An app for this project HAS connected on this port before, so the port is ` +
-            `proven.${notThisApp}${nuxt}${marker} ${REAL_CAUSES} ${RELEASE}`);
-    }
-    // 4. Wired, but never seen connect. Rank the real causes; keep the port differential last, where
-    //    the evidence for it actually sits.
-    if (true === evidence.initialized) {
-        return `${opening}${nuxt}${marker} ${REAL_CAUSES} If none of those, it may be dialling a different daemon than this one: check the app's reticle port matches ${String(port)}. ${RELEASE}`;
-    }
-    // 5. Nothing known. The differential, plus the possibility this app carries no SDK at all —
-    //    except when the marker check already ruled that out, which is the whole reason for the bit.
-    const noSdk = true === evidence.sdkMarker
-        ? ''
-        : ' If the app carries no Reticle SDK at all, run `reticle init` in it first.';
-    return `${opening}${nuxt}${marker} ${PORT_DIFFERENTIAL}${noSdk} ${REAL_CAUSES} ${RELEASE}`;
-}

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

@@ -1,143 +0,0 @@
-/**
- * Lease tools — the agent-facing surface of the BrowserPool.
- *
- * `reticle_lease_acquire` opens an isolated headless context navigated to the app URL and returns
- * the sessionId the app's SDK will register. A second acquire on the same origin reuses the live
- * lease rather than minting another tab — that second tab used to poison default session resolution
- * for the rest of the run. The parallel suite still mints via `acquireLeasedSession`, because ten
- * flows on one origin need isolation on purpose.
- *
- * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
- */
-import { type SeedStorage } from '@reticlehq/core';
-import type { ToolDef } from './tool-kit.js';
-/** The origin of a URL, or undefined when it does not parse. */
-export declare function originOf(url: string): string | undefined;
-/**
- * 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;
-/**
- * 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;
-/** 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>;
-}
-/**
- * Does this tab still answer?
- *
- * `ready: true` used to mean "a row is in the sessions map", which is how a lease came back ready
- * and was then rejected by `snapshot`, `state` and `console`. Presence is not liveness: the map
- * still holds a tab that is attached, streaming events, and answering nothing (#692).
- *
- * 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>;
-/**
- * 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
- * leaks a pool slot and starves the rest of the suite.
- */
-export declare function acquireLeasedSession(pool: {
-    acquire: (url: string, opts: {
-        sessionId: string;
-        seedStorage?: SeedStorage;
-    }) => Promise<{
-        sessionId: string;
-        release: () => Promise<void>;
-        navStatus?: number;
-    }>;
-    /**
-     * The address this lease's page said it could not reach. Optional so a test double need not
-     * implement it; the real pool always does.
-     */
-    dialFailureUrl?: (sessionId: string) => string | undefined;
-    /** Optional so a test double need not implement it; the real pool always does. */
-    alias?: (registeredId: string, leaseId: string) => void;
-}, sessions: {
-    get: (id: string) => unknown;
-    all: () => {
-        id: string;
-        url?: string;
-    }[];
-}, url: string, projectId?: string, seedStorage?: SeedStorage): Promise<{
-    sessionId: string;
-    release: () => Promise<void>;
-}>;
-export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
-export declare function hasOriginLock(origin: string): boolean;
-export declare const LEASE_ACQUIRE_TOOL: ToolDef;
-export declare const LEASE_TOOLS: ToolDef[];
-export {};