@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,50 @@
+/**
+ * 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. A leased session is driven far harder than an unleased
+ * one and is where most of the bugs anybody finds are actually found, so a lease that does not
+ * dial in costs more than any other kind of failed start.
+ *
+ * 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. In every
+ * field report we looked at, the port was correct, 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.
+ */
+/** What the daemon can say for certain at the moment a lease comes back unconnected. */
+export interface LeaseEvidence {
+    /** A dial WAS made and turned away, with the reason. The only certain cause there is. */
+    refusal?: string;
+    /** An app for this project has connected on this port before (durable, survives a restart). */
+    previouslyConnected?: boolean;
+    /** The project has been through `init` — so recommending it again cannot help. */
+    initialized?: boolean;
+    /** The framework `.reticle.json` declares, used to rank rather than to decorate. */
+    framework?: string;
+    /**
+     * Whether any Reticle marker was found in the page the lease loaded.
+     *
+     * The single bit that separates the two commonest cases — "this app ships no SDK" and "the SDK
+     * loaded but could not reach the daemon" — which today produce identical messages. Absent means
+     * NOT CHECKED, and an absent bit prints nothing: a marker check that could not run must not be
+     * reported as a marker that was not found.
+     */
+    sdkMarker?: boolean;
+    /**
+     * The websocket URL the leased page actually tried, read from its own console.
+     *
+     * The only per-page proof there is about where the dial WENT. `refusal` proves a dial arrived
+     * HERE; this proves where one was aimed, which is the strictly more useful fact when it was aimed
+     * somewhere else — the case in which no refusal exists to be recorded, because nothing arrived.
+     *
+     * Absent means the page said nothing, never that it dialled correctly.
+     */
+    dialledUrl?: string;
+}
+export declare function leaseNotConnectedHint(url: string, port: number, evidence?: LeaseEvidence): string;

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

@@ -0,0 +1,125 @@
+/**
+ * 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. A leased session is driven far harder than an unleased
+ * one and is where most of the bugs anybody finds are actually found, so a lease that does not
+ * dial in costs more than any other kind of failed start.
+ *
+ * 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. In every
+ * field report we looked at, the port was correct, 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/surface/tools/lease-tools.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 { 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 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?
+ *
+ * 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>;
+/**
+ * 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[];
+/**
+ * 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>;
+export {};