@reticlehq/server 3.3.0 → 3.4.0

package/dist/command/setup/probe/loopback-probe-urls.js

@@ -50,3 +50,43 @@ export function loopbackProbeUrls(url) {
         push(host);
     return out;
 }
+/**
+ * Errors that mean "nothing is listening at THIS address", so another loopback family may be.
+ *
+ * Anything else, a timeout above all, means the address was right and the server is slow. A cold
+ * Next 16 first compile takes long enough to time a probe out, and treating that as a family miss
+ * walked on to `127.0.0.1`/`[::1]`, which answered first, became the app url, and is an origin Next
+ * refuses its dev resources to: no hydration, so the SDK never ran and init blamed the page.
+ */
+const ADDRESS_MISS_CODES = new Set([
+    'ECONNREFUSED',
+    'EADDRNOTAVAIL',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EAFNOSUPPORT',
+]);
+function field(value, key) {
+    return 'object' === typeof value && null !== value ? Reflect.get(value, key) : undefined;
+}
+const codeOf = (value) => {
+    const code = field(value, 'code');
+    return 'string' === typeof code ? code : undefined;
+};
+/**
+ * Whether a failed fetch was refused at the connection level on this address.
+ *
+ * `fetch` wraps the socket error as `cause`; with happy-eyeballs that cause is an AggregateError of
+ * one error per address tried, and it is a miss only when every one of them was.
+ */
+export function isAddressMiss(err) {
+    const cause = field(err, 'cause');
+    const direct = codeOf(cause);
+    if (undefined !== direct)
+        return ADDRESS_MISS_CODES.has(direct);
+    const errors = field(cause, 'errors');
+    if (!Array.isArray(errors) || 0 === errors.length)
+        return false;
+    return errors.every((e) => ADDRESS_MISS_CODES.has(codeOf(e) ?? ''));
+}

package/dist/command/setup/probe/page-probe.d.ts

@@ -40,8 +40,13 @@ export declare function readPage(probe: PageProbe): PageFinding;
 /**
  * What the page adds to the daemon's account. Deliberately a sentence to APPEND, not a replacement:
  * the daemon's diagnosis names the fix, and this says what the page looked like when we checked.
+ *
+ * `daemonSpoke`: the daemon already gave its account. Whether the page dialled is ITS fact (it
+ * sees every hello, including one it refused), so the SDK_PRESENT sentence then states only the
+ * page fact. Saying "never dialled the bridge" under "this daemon REFUSED the last page" contradicted
+ * the one piece of positive evidence in the run.
  */
-export declare function describePage(finding: PageFinding, url: string): string;
+export declare function describePage(finding: PageFinding, url: string, daemonSpoke?: boolean): string;
 /**
  * What the page looks like once it has had its short chance to come up.
  *
@@ -68,4 +73,10 @@ export declare function describePage(finding: PageFinding, url: string): string;
 export declare function findingBeforeOpen(probe: () => Promise<PageProbe>, clock: {
     readonly now: () => number;
     readonly sleep: (ms: number) => Promise<void>;
-}, windowMs: number, pollMs: number): Promise<PageFinding>;
+}, windowMs: number, pollMs: number, 
+/**
+ * The served HTML carries the SDK marker on this shape. When it does not (the connect is in the
+ * JS bundle), SDK_MISSING is the permanent state of a healthy page, and waiting for it to change
+ * only delays the window that would load the bundle.
+ */
+htmlCarriesSdk?: boolean): Promise<PageFinding>;

package/dist/command/setup/probe/page-probe.js

@@ -27,8 +27,16 @@ export function readPage(probe) {
 /**
  * What the page adds to the daemon's account. Deliberately a sentence to APPEND, not a replacement:
  * the daemon's diagnosis names the fix, and this says what the page looked like when we checked.
+ *
+ * `daemonSpoke`: the daemon already gave its account. Whether the page dialled is ITS fact (it
+ * sees every hello, including one it refused), so the SDK_PRESENT sentence then states only the
+ * page fact. Saying "never dialled the bridge" under "this daemon REFUSED the last page" contradicted
+ * the one piece of positive evidence in the run.
  */
-export function describePage(finding, url) {
+export function describePage(finding, url, daemonSpoke = false) {
+    if (PageFinding.SDK_PRESENT === finding && daemonSpoke) {
+        return `The SDK IS in the page at ${url}; the daemon's account above says what became of it.`;
+    }
     switch (finding) {
         case PageFinding.NOT_SERVED:
             // Leads with the cause. The break-matrix asserts this phrasing because it is what a reader
@@ -77,10 +85,17 @@ export function describePage(finding, url) {
  * `probePage` 1,500 times before reaching this point and a test of the decision cannot get near
  * it through that. Here it takes a probe and a clock and answers in three lines of setup.
  */
-export async function findingBeforeOpen(probe, clock, windowMs, pollMs) {
+export async function findingBeforeOpen(probe, clock, windowMs, pollMs, 
+/**
+ * The served HTML carries the SDK marker on this shape. When it does not (the connect is in the
+ * JS bundle), SDK_MISSING is the permanent state of a healthy page, and waiting for it to change
+ * only delays the window that would load the bundle.
+ */
+htmlCarriesSdk = true) {
     const readyBy = clock.now() + windowMs;
     let finding = readPage(await probe());
-    while ((PageFinding.SDK_MISSING === finding || PageFinding.NOT_SERVED === finding) &&
+    while (((htmlCarriesSdk && PageFinding.SDK_MISSING === finding) ||
+        PageFinding.NOT_SERVED === finding) &&
         clock.now() < readyBy) {
         await clock.sleep(pollMs);
         finding = readPage(await probe());

package/dist/command/setup/run-setup.d.ts

@@ -51,6 +51,11 @@ export interface DaemonReason {
     /** The whole differential, recorded for the agent reading `--json`. Defaults to the lead. */
     readonly full?: string;
 }
+/** A lease this run opened for its connect proof, and the way to hand it back. */
+export interface OwnedBrowser {
+    readonly sessionId: string;
+    readonly release: () => Promise<void>;
+}
 export interface SetupEffects {
     /** Start the dev server. Resolves once started; the caller owns stopping it. */
     readonly startDevServer: (command: string, cwd: string) => Promise<void>;
@@ -79,8 +84,19 @@ export interface SetupEffects {
      * short (`vite-react`, `vite-vue`, `next-app-router`, `monorepo-subdir`, run 35242186243 against
      * 35232727716). A non-zero launcher exit means UNKNOWN, not "no browser": it reports whether the
      * COMMAND succeeded, never whether a window opened. Do not shorten a wait on it.
+     *
+     * It may resolve with the launcher's own failure, and that is used for exactly one thing: to ALSO
+     * open a Reticle-owned browser, so the proof does not depend on a window that may never appear.
+     * Adding a second source of a session is safe on a false alarm; cutting the wait was not.
+     */
+    readonly openBrowser: (url: string) => Promise<string | void>;
+    /**
+     * Open the url in a browser Reticle owns (a pooled lease), for a run with no system browser to
+     * lean on: `--no-open`, CI, a container, an agent. Optional: absent means no lease is attempted.
      */
-    readonly openBrowser: (url: string) => Promise<void>;
+    readonly openLease?: (url: string) => Promise<OwnedBrowser | {
+        readonly failed: string;
+    }>;
     readonly listSessions: () => Promise<CandidateSession[]>;
     /**
      * The daemon's own account of why nothing connected, if it can be asked.
@@ -101,6 +117,8 @@ export interface SetupEffects {
 }
 export interface SetupInput {
     readonly appDir: string;
+    /** This project's id, so a live tab of it can be told from another app's on the same url. */
+    readonly projectId?: string | undefined;
     readonly devCommand?: string | undefined;
     /** The app is already served here, so nothing is started. */
     readonly suppliedUrl?: string | undefined;
@@ -117,6 +135,13 @@ export interface SetupInput {
     readonly openBrowser: boolean;
     /** Web, Electron or Tauri. Desktop changes three things; see desktop-shape.ts. */
     readonly shape: AppShape;
+    /**
+     * The served HTML carries the SDK marker on this shape: Vite's index.html injection, or a plain
+     * HTML page with the snippet pasted in. Every other framework delivers the connect in the JS
+     * bundle, so "the SDK is NOT in the page" is the permanent state of a healthy page there, and
+     * saying it sent people to restart a dev server that was fine.
+     */
+    readonly htmlCarriesSdk: boolean;
     readonly phaseTimeoutMs: number;
     readonly pollMs: number;
 }

package/dist/command/setup/run-setup.js

@@ -14,7 +14,7 @@
  * and a real browser to find out what happens when neither works.
  */
 import { judgeWait, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
-import { waitProgressLine } from './terminal/wait-progress.js';
+import { connectProgressLine, waitProgressLine } from './terminal/wait-progress.js';
 /**
  * Windows gets longer to say something before silence counts as a wedge.
  *
@@ -28,7 +28,7 @@ import { waitProgressLine } from './terminal/wait-progress.js';
  */
 const WINDOWS_QUIET_MEANS_HUNG_MS = 3 * 60_000;
 const WINDOWS_QUIET_MEANS_HUNG_MS_APPLIES = 'win32' === process.platform;
-import { pickSession } from './session-pick.js';
+import { liveSessionOfProject, pickSession } from './session-pick.js';
 import { readPage, describePage, findingBeforeOpen, PageFinding, } from './probe/page-probe.js';
 import { remainingSteps } from './remaining-steps.js';
 import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
@@ -40,11 +40,27 @@ import { AppShape, isDesktop, policyFor } from './desktop-shape.js';
 const SDK_READY_WINDOW_MS = 15_000;
 /** The wait left when no browser was opened: only a tab that is ALREADY loaded can still appear. */
 const NO_BROWSER_GRACE_MS = 3_000;
+/**
+ * How long a system browser that SAID it opened gets to produce a session before init proves the
+ * connect in a Reticle-owned browser instead. A launcher's exit is not a window: macOS `open` against
+ * a default browser that does not answer exits 1 only after the launch check has already counted it
+ * as opened, and init then waited out its whole connect budget over a correct install.
+ */
+const SYSTEM_BROWSER_GRACE_MS = 15_000;
 export const SetupPhase = {
     DEV_SERVER: 'dev-server',
     CONNECT: 'connect',
     DONE: 'done',
 };
+/** Hand a lease back. Best-effort: a lease that already expired is already gone. */
+async function releaseLease(lease) {
+    try {
+        await lease?.release();
+    }
+    catch {
+        /* nothing to undo */
+    }
+}
 const asProgress = (input, o) => ({
     initDone: true,
     devServerUp: undefined !== o.url,
@@ -89,6 +105,10 @@ async function daemonWhy(fx) {
 export async function runSetupPhases(input, fx) {
     const notes = [];
     const note = (line) => {
+        // The page is probed before the browser opens and again after the wait, and an unchanged page
+        // gave the reader the same paragraph twice in a row.
+        if (notes.at(-1) === line)
+            return;
         notes.push(line);
         fx.note(line);
     };
@@ -181,9 +201,13 @@ export async function runSetupPhases(input, fx) {
     const requiredRuntime = isDesktop(input.shape) ? input.shape : undefined;
     // A tab already on this URL is the answer. Opening another is how three sessions appear.
     // `before` is empty so pickSession will take that tab rather than waiting for a new one.
+    //
+    // Not only when attached: a server init started itself (Next, Angular — nothing announces) has a
+    // url too, and a live tab of this project already on it is just as much the answer. Without this
+    // every re-run opened one more tab.
     const alreadyConnected = attachedToExisting
         ? pickSession(listed, url, new Set(), requiredRuntime)
-        : null;
+        : liveSessionOfProject(listed, url, input.projectId, requiredRuntime);
     const before = new Set(listed.map((s) => s.sessionId));
     // Do not put a window in front of somebody until the page behind it can actually do something.
     //
@@ -198,7 +222,12 @@ export async function runSetupPhases(input, fx) {
     // proof that nothing can ever dial in.
     const budgetMs = input.connectBudgetMs ?? Math.max(input.phaseTimeoutMs, policy.connectBudgetMs);
     let openedBrowser = false;
-    if (null === alreadyConnected && input.openBrowser && policy.openBrowser) {
+    let lease;
+    // `--no-open` used to skip this whole block, so nothing was opened and the run ended on "never
+    // dialled the bridge" over a correct install. With a lease to fall back on it is entered too, and
+    // only the system browser is skipped.
+    const canLease = undefined !== fx.openLease;
+    if (null === alreadyConnected && policy.openBrowser && (input.openBrowser || canLease)) {
         // SERVED is the precondition, not SDK_PRESENT: a url that answers nothing is the only state
         // where a window is certainly useless. Whether the SDK is in the served HTML is a DIFFERENT
         // question — Vite injects a marker, while Nuxt, React Router, Astro, SvelteKit and CRA deliver
@@ -209,7 +238,7 @@ export async function runSetupPhases(input, fx) {
         //
         // So presence decides only WHEN: open the moment it appears (the fast path for the frameworks
         // that inline it), otherwise once the short readiness window is out.
-        const finding = await findingBeforeOpen(() => fx.probePage(url), { now: () => fx.now(), sleep: (ms) => fx.sleep(ms) }, Math.min(SDK_READY_WINDOW_MS, budgetMs), input.pollMs);
+        const finding = await findingBeforeOpen(() => fx.probePage(url), { now: () => fx.now(), sleep: (ms) => fx.sleep(ms) }, Math.min(SDK_READY_WINDOW_MS, budgetMs), input.pollMs, input.htmlCarriesSdk);
         if (PageFinding.NOT_SERVED === finding || PageFinding.TLS_REFUSED === finding) {
             note(describePage(finding, url));
             note('Not opening a browser: nothing answered that url, so the window could only show an error ' +
@@ -218,12 +247,23 @@ export async function runSetupPhases(input, fx) {
         else {
             // Said BEFORE the window appears, so somebody watching a page that stays inert has already
             // been told which of the two it is.
-            if (PageFinding.SDK_MISSING === finding)
+            if (PageFinding.SDK_MISSING === finding && input.htmlCarriesSdk) {
                 note(describePage(finding, url));
+            }
             // `= true` means ATTEMPTED, which is the most that is knowable — see openBrowser above for
             // why the launcher's own exit code must not be read as "no window appeared".
-            await fx.openBrowser(url);
-            openedBrowser = true;
+            const launcherFailed = input.openBrowser ? await fx.openBrowser(url) : undefined;
+            openedBrowser = input.openBrowser;
+            if (undefined !== fx.openLease && (!input.openBrowser || undefined !== launcherFailed)) {
+                const owned = await fx.openLease(url);
+                if ('failed' in owned) {
+                    note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
+                }
+                else {
+                    lease = owned;
+                    openedBrowser = true;
+                }
+            }
         }
     }
     // Waiting the full budget for a session when nothing was opened to create one is dead time, and
@@ -237,6 +277,9 @@ export async function runSetupPhases(input, fx) {
             ? budgetMs
             : Math.min(NO_BROWSER_GRACE_MS, budgetMs));
     let session = alreadyConnected;
+    const waitStartedAt = fx.now();
+    let connectSpokeAtMs;
+    let leaseFallbackTried = false;
     while (null === session) {
         // On a desktop app, only the desktop window counts. AppShape and the runtime a page reports use
         // the same three names, so the shape IS the requirement — see session-pick.
@@ -245,6 +288,32 @@ export async function runSetupPhases(input, fx) {
             break;
         if (deadline <= fx.now())
             break;
+        if (!leaseFallbackTried &&
+            undefined === lease &&
+            undefined !== fx.openLease &&
+            openedBrowser &&
+            input.openBrowser &&
+            !isDesktop(input.shape) &&
+            fx.now() - waitStartedAt >= SYSTEM_BROWSER_GRACE_MS) {
+            leaseFallbackTried = true;
+            const owned = await fx.openLease(url);
+            if ('failed' in owned) {
+                note(`Could not open ${url} in a Reticle-owned browser either: ${owned.failed}`);
+            }
+            else {
+                lease = owned;
+            }
+            continue;
+        }
+        // Not in silence: a desktop run used to print one line and then nothing for ten minutes.
+        const waitedMs = fx.now() - waitStartedAt;
+        const progress = connectProgressLine(waitedMs, connectSpokeAtMs, deadline - waitStartedAt, policy.awaiting);
+        if (undefined !== progress) {
+            // To the person only: it is progress, not a finding, and in `notes` it would split the
+            // page description printed before and after this wait into two copies.
+            fx.note(progress);
+            connectSpokeAtMs = waitedMs;
+        }
         await fx.sleep(input.pollMs);
     }
     if (null === session) {
@@ -275,8 +344,13 @@ export async function runSetupPhases(input, fx) {
                 fx.note(why.lead);
                 notes.push(why.full ?? why.lead);
             }
-            note(describePage(readPage(await fx.probePage(url)), url));
+            const finding = readPage(await fx.probePage(url));
+            // Silent on a bundle-connect shape: its HTML never carries the SDK, so the absence says nothing.
+            if (PageFinding.SDK_MISSING !== finding || input.htmlCarriesSdk) {
+                note(describePage(finding, url, undefined !== why));
+            }
         }
+        await releaseLease(lease);
         return stop(input, SetupPhase.CONNECT, { url }, notes);
     }
     // ── connected, which is where ONBOARDING ends ────────────────────────────────────────────────
@@ -292,16 +366,25 @@ export async function runSetupPhases(input, fx) {
     // Both routes, because `explore` needs a model: without ANTHROPIC_API_KEY it answers "No model
     // configured to drive the app". Naming only that one hands the reader a dead end on any machine
     // without a key, which is the same defect this release spent its time removing everywhere else.
-    // Three short lines rather than one paragraph, and each says who it is for.
+    // A heading and a numbered list rather than one paragraph: a reader scans for what to do next.
     //
     // This was a single 524-character note, measured on a real first run: eighty-three words, no
     // break, naming `reticle_*` tools at a reader who had just typed `reticle init` in a terminal and
     // has no such tools to call. The facts were right and the shape made them unreadable, which on
     // the last line of onboarding is the same as not saying them.
-    note(`Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
-    note('Agent: drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
+    note(`✓ Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
+    // Said, because "connected" otherwise reads as "your browser connected": the page that dialled
+    // was a headless one Reticle launched and has now closed, and nothing is open on this screen.
+    if (undefined !== lease && session.sessionId === lease.sessionId) {
+        note('The proof came from a Reticle-owned headless browser (now closed), not a window of yours — ' +
+            `open ${url} in your own browser to use the app.`);
+    }
+    await releaseLease(lease);
+    note('');
+    note('Next, prove one flow. Your agent does this:');
+    note('  1. Drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
         'produce a verdict; nothing else does.');
-    note('Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
+    note('  2. Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
         'what>" }` records what it drove, so later runs replay with no model in the loop. Needs ' +
         'ANTHROPIC_API_KEY.');
     return {

package/dist/command/setup/session-pick.d.ts

@@ -21,7 +21,20 @@ export interface CandidateSession {
     readonly hasCapabilities?: boolean;
     /** Which shell answered. Absent on an SDK too old to report one — see requiredRuntime below. */
     readonly runtime?: string;
+    /** The project the page reported. Absent on an SDK too old to report one. */
+    readonly projectId?: string;
 }
+/**
+ * A tab of THIS project on `url` that is demonstrably alive right now, or null.
+ *
+ * Stricter than `pickSession`, because it decides whether to open a window at all: every init run
+ * opened another tab even when this project already had a live one on the url, and the pile-up then
+ * made every tool called without a sessionId fail with "multiple sessions connected". Reused only on
+ * positive evidence — the page names this project, is visible, and was heard from inside the
+ * daemon's staleness threshold — because reusing a dead tab is the worse mistake: nothing opens and
+ * nothing connects.
+ */
+export declare function liveSessionOfProject(sessions: readonly CandidateSession[], url: string, projectId: string | undefined, requiredRuntime?: string): CandidateSession | null;
 /**
  * The session to drive, or null when nothing on this url qualifies.
  *

package/dist/command/setup/session-pick.js

@@ -10,9 +10,29 @@
  *   the oldest: a tab whose dev server died yesterday. The HUD then plays to a window nobody is
  *   watching, and the verdict describes a page the user cannot see.
  */
+import { SESSION_HEALTH } from '@reticlehq/core';
 /** Sorts a hidden tab after a visible one; among equals, the least stale first. */
 const isLive = (s) => true !== s.hidden && true !== s.throttled;
 const staleness = (s) => s.lastSeenMs ?? Number.POSITIVE_INFINITY;
+/**
+ * A tab of THIS project on `url` that is demonstrably alive right now, or null.
+ *
+ * Stricter than `pickSession`, because it decides whether to open a window at all: every init run
+ * opened another tab even when this project already had a live one on the url, and the pile-up then
+ * made every tool called without a sessionId fail with "multiple sessions connected". Reused only on
+ * positive evidence — the page names this project, is visible, and was heard from inside the
+ * daemon's staleness threshold — because reusing a dead tab is the worse mistake: nothing opens and
+ * nothing connects.
+ */
+export function liveSessionOfProject(sessions, url, projectId, requiredRuntime) {
+    if (undefined === projectId || 0 === projectId.length)
+        return null;
+    const mine = sessions.filter((s) => projectId === s.projectId &&
+        true !== s.hidden &&
+        undefined !== s.lastSeenMs &&
+        s.lastSeenMs <= SESSION_HEALTH.STALE_THRESHOLD_MS);
+    return pickSession(mine, url, new Set(), requiredRuntime);
+}
 /**
  * The session to drive, or null when nothing on this url qualifies.
  *

package/dist/command/setup/setup-command.d.ts

@@ -27,22 +27,10 @@ interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
     readonly env: Readonly<Record<string, string>>;
     /** Register the MCP server with the coding agents init does not itself reach. */
     readonly registerAgents: boolean;
+    /** The bridge's pairing token, for the MCP transport a connect-proof lease is opened over. */
+    readonly pairingToken?: string | undefined;
 }
-/**
- * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
- *
- * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
- * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
- * so a VS Code user has no tools outside the directory they ran init in.
- */
 export declare function registerOtherAgents(print: (line: string) => void): void;
 type SetupCommandResult = SetupOutcome;
-/**
- * Run the phases against the real world.
- *
- * The dev server is stopped on every ending except success, where it is handed to the user: an
- * instrumented app they can watch is the deliverable, and killing it would leave them with config
- * files and a dead tab.
- */
 export declare function runSetupCommand(input: SetupCommandInput, print: (line: string) => void): Promise<SetupCommandResult>;
 export {};