@reticlehq/server 3.2.0 → 3.4.0

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

@@ -9,22 +9,25 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { planAgentConfigs } from './agent-configs.js';
-import { AppShape, readShape } from './desktop-shape.js';
+import { AppShape, describeShape, readShape } from './desktop-shape.js';
 import { stopOnInterrupt } from './terminal/interrupt.js';
 import { stopOnCrash, crashSentence } from './terminal/crash.js';
 import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
 import { ApprovalOutcome, grantAutoApproval } from './auto-approve.js';
 import { agentIo } from './agent-io.js';
-import { EnsureDaemon, ensureDaemon, nodeEnsureDaemonDeps } from './bringup/ensure-daemon.js';
+import { EnsureDaemon, ensureDaemon, holdDaemon, nodeEnsureDaemonDeps, nodeRetireDeps, retireMovedDaemons, } from './bringup/ensure-daemon.js';
 import { openInBrowser } from '../cli/launch/cli-launch.js';
+import { openLeaseFor } from './bringup/connect-lease.js';
 import { readProjectId } from '../cli/ports/resolve/cli-port.js';
-import { reticleStateHome } from '../daemon/daemon.js';
+import { spawnSync } from 'node:child_process';
+import { isAlive, reticleStateHome } from '../daemon/daemon.js';
 import { readDevServers } from '../daemon/dev-servers.js';
 import { urlOfExistingApp } from './probe/existing-app.js';
+import { handedOverUrl, stopHandedOver } from './bringup/dev-server-files.js';
 import { listSessions, OwnedDevServer, probePage } from './node-effects.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
-import { summarizeStatus } from '../cli/launch/cli-launch.js';
-import { runSetupPhases, } from './run-setup.js';
+import { daemonSkew, summarizeStatus } from '../cli/launch/cli-launch.js';
+import { runSetupPhases, SetupPhase, } from './run-setup.js';
 import { noticeKey, readSaid, rememberSaid, unsaidNotices } from './agent-notice-memory.js';
 /**
  * The dev server a crash should take with it, if one is running right now.
@@ -84,13 +87,15 @@ function hasElectronDependency(dir) {
  * 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.
  */
+/** `agent`, `agents`. */
+const agentWord = (n) => (1 === n ? 'agent' : 'agents');
 export function registerOtherAgents(print) {
     const platform = process.platform;
     const home = homedir();
     const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
     const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
     if (0 < wrote.length) {
-        print(`registered the MCP server with ${wrote.length} more agent(s): ${wrote.map((r) => r.name).join(', ')}`);
+        print(`  ✓ ${String(wrote.length)} more ${agentWord(wrote.length)}: ${wrote.map((r) => r.name).join(', ')}`);
     }
     // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped --
     // but said ONCE. Two commands call this function by design, so a `curl | sh` followed by
@@ -103,21 +108,21 @@ export function registerOtherAgents(print) {
         .map((r) => ({ name: r.name, file: r.file, why: r.why }));
     const fresh = unsaidNotices(readSaid(stateHome), manual);
     for (const notice of fresh) {
-        print(`${notice.name}: ${notice.why} — add the reticle entry to ${notice.file} by hand.`);
+        print(`  ⚠ ${notice.name}: ${notice.why} — add the reticle entry to ${notice.file} by hand.`);
     }
     rememberSaid(stateHome, fresh.map((n) => noticeKey(n)));
     const skills = applyAgentSkills(agentIo, { home, platform });
     if (0 < skills.length)
-        print(`wrote the /reticle skill for ${skills.length} agent(s)`);
+        print(`  ✓ the /reticle skill, for ${String(skills.length)} ${agentWord(skills.length)}`);
     // Registration alone still leaves an Accept dialog in front of every call, and a verification run
     // makes dozens of them: the loop is only autonomous once the tools are pre-approved.
     const approvals = grantAutoApproval(agentIo, { home, platform });
     const granted = approvals.filter((a) => ApprovalOutcome.GRANTED === a.outcome);
     if (0 < granted.length) {
-        print(`pre-approved the reticle tools in ${granted.map((a) => a.name).join(', ')} — no Accept prompt per call`);
+        print(`  ✓ tools pre-approved in ${granted.map((a) => a.name).join(', ')}, so no Accept prompt per call`);
     }
     for (const noted of approvals.filter((a) => undefined !== a.warn)) {
-        print(`${noted.name}: ${String(noted.warn)}`);
+        print(`  ⚠ ${noted.name}: ${String(noted.warn)}`);
     }
 }
 /**
@@ -127,13 +132,70 @@ export function registerOtherAgents(print) {
  * instrumented app they can watch is the deliverable, and killing it would leave them with config
  * files and a dead tab.
  */
+/** How long a stopped dev server gets to let go of its port before the new one is started. */
+const HANDED_OVER_EXIT_MS = 10_000;
+const HANDED_OVER_EXIT_POLL_MS = 100;
+/** Stop the server a previous init handed over for `appDir`, and wait (bounded) for it to exit. */
+async function restartHandedOverServer(appDir) {
+    let stoppedPid;
+    const stopped = stopHandedOver(reticleStateHome(), appDir, {
+        alive: isAlive,
+        kill: (pid) => {
+            stoppedPid = pid;
+            try {
+                // Its own process group (it was spawned detached), so what it started goes with it.
+                if ('win32' === process.platform) {
+                    spawnSync('taskkill', ['/PID', String(pid), '/T', '/F']);
+                }
+                else {
+                    process.kill(-pid, 'SIGTERM');
+                }
+            }
+            catch {
+                /* already gone */
+            }
+        },
+    });
+    const deadline = Date.now() + HANDED_OVER_EXIT_MS;
+    while (undefined !== stoppedPid && isAlive(stoppedPid) && Date.now() < deadline) {
+        await new Promise((done) => setTimeout(done, HANDED_OVER_EXIT_POLL_MS));
+    }
+    return stopped;
+}
 export async function runSetupCommand(input, print) {
     if (input.registerAgents)
         registerOtherAgents(print);
+    // A moved port first: this project's daemon on the OLD port would otherwise be the one the page
+    // finds and dials, while everything below waits on the new one.
+    const retired = await retireMovedDaemons(readProjectId(input.appDir), input.bridgePort, nodeRetireDeps());
+    for (const port of retired) {
+        print(`stopped this project's Reticle daemon on port ${String(port)}: the project now uses ` +
+            `${String(input.bridgePort)}, and the page would have kept dialling the old one.`);
+    }
+    // And the dev server a previous init left running, which may have read the old port once at
+    // startup (Next does) — so the attach below would keep a page dialling the daemon just stopped.
+    if (0 < retired.length && (await restartHandedOverServer(input.appDir))) {
+        print(`stopped the dev server a previous init started, so it restarts on port ${String(input.bridgePort)}.`);
+    }
     // Before the app is booted, because the app's whole job from here is to dial this port. Without
     // it the phases wait out their budget and then report the SDK as the thing that failed.
-    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps());
-    if (EnsureDaemon.UNAVAILABLE === daemon) {
+    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps((status) => undefined !== daemonSkew(status)));
+    if (undefined !== daemon.message)
+        print(daemon.message);
+    if (EnsureDaemon.SKEWED_IN_USE === daemon.state) {
+        // Stop here: every hello from the page would be refused, and waiting out the connect budget
+        // only to blame the page is the run this exists to prevent.
+        return {
+            ok: false,
+            reachedPhase: SetupPhase.DEV_SERVER,
+            flowSaved: false,
+            notes: undefined === daemon.message ? [] : [daemon.message],
+            fallback: [
+                `Once those sessions are done, free the port with \`npx @reticlehq/server kill --port ${String(input.bridgePort)}\` and re-run init.`,
+            ],
+        };
+    }
+    if (EnsureDaemon.UNAVAILABLE === daemon.state) {
         print(`could not start the Reticle daemon on port ${String(input.bridgePort)}, so nothing is listening for the app to connect to. Run \`npx @reticlehq/server serve --port ${String(input.bridgePort)}\` and try again.`);
     }
     // Which shell this is decides three things the phases would otherwise get wrong: opening a
@@ -145,7 +207,7 @@ export async function runSetupCommand(input, print) {
         hasElectronDep: hasElectronDependency(input.appDir),
     });
     if (AppShape.WEB !== shape)
-        print(`detected a ${shape} app`);
+        print(`detected ${describeShape(shape)}`);
     const server = new OwnedDevServer();
     const effects = {
         startDevServer: (command, cwd) => {
@@ -153,10 +215,16 @@ export async function runSetupCommand(input, print) {
             server.start(command, cwd, input.env);
             return Promise.resolve();
         },
-        existingAppUrl: () => Promise.resolve(urlOfExistingApp(readDevServers(reticleStateHome()), {
+        // The server the plugin announced (Vite), or failing that the one a previous init handed over
+        // and recorded — the only way to know a Next or Angular server on the port is this project's own.
+        existingAppUrl: async () => urlOfExistingApp(readDevServers(reticleStateHome()), {
             projectId: readProjectId(input.appDir),
             root: input.appDir,
-        })),
+        }) ??
+            (await handedOverUrl(reticleStateHome(), input.appDir, {
+                alive: isAlive,
+                answers: async (url) => (await probePage(url)).served,
+            })),
         devServerOutput: () => server.output(),
         devServerExited: () => server.exited(),
         devServerQuietForMs: () => server.quietForMs(),
@@ -164,20 +232,16 @@ export async function runSetupCommand(input, print) {
         probePage,
         openBrowser: async (url) => {
             const failure = await openInBrowser(url);
-            if (null !== failure) {
-                print(`could not open a browser (${failure}). Nothing was opened, and nothing else here will ` +
-                    // Three wordings have been wrong in a row, each naming a way out that does not exist on
-                    // the machine being spoken to. It said `reticle_run({ tool: "reticle_lease", ... })`:
-                    // the default surface advertises neither name and ships no hatch to reach the second.
-                    // It then said `reticle open <url>`, which asks the OS to launch the default browser --
-                    // the very thing that just failed -- so it returned the reader to the same wall.
-                    // This one names no command: the missing piece is a browser, and the honest sentence
-                    // says which url needs one rather than inventing a Reticle that can conjure it.
-                    `open one: this asks the OS for your default browser, and it is a machine with none — ` +
-                    `CI, a container, an SSH session, WSL with no host browser. Point any browser that can ` +
-                    `reach it at ${url}; the session appears within a second of the page loading.`);
-            }
+            if (null === failure)
+                return undefined;
+            // It used to end "nothing else here will open one", which stopped being true once a
+            // Reticle-owned browser could always launch: run-setup opens a lease on this failure, so the
+            // reader is told what happens next rather than sent to find a browser by hand.
+            print(`could not open a browser (${failure}), so the connect proof will come from a ` +
+                `Reticle-owned headless browser instead. To use the app yourself, point any browser at ${url}.`);
+            return failure;
         },
+        openLease: (url) => openLeaseFor(input.bridgePort, url, input.pairingToken),
         listSessions: () => listSessions(input.bridgePort),
         // `summarizeStatus` already narrows this payload for `reticle status`; reusing it here keeps one
         // reader of the wire shape rather than two that can disagree about which key carries the reason.
@@ -207,16 +271,26 @@ export async function runSetupCommand(input, print) {
     activeDevServerStop = () => {
         server.stop();
     };
+    // Hold the daemon for as long as this run waits on it. Its idle rule counted none of this as
+    // activity, and on a slow desktop build the daemon init had just started idled out mid-wait.
+    const releaseDaemon = holdDaemon(input.bridgePort);
     try {
-        const outcome = await runSetupPhases({ ...input, shape }, effects);
+        const outcome = await runSetupPhases({ ...input, shape, projectId: readProjectId(input.appDir) }, effects);
         // The app stays up only when there is something worth watching.
-        if (outcome.ok)
-            server.handOver();
+        if (outcome.ok) {
+            server.handOver(outcome.url);
+            // Its output is on a file now, not this terminal, so say where: a compile error that used to
+            // scroll past here is the first thing somebody will look for.
+            const log = server.logPath();
+            if (undefined !== log)
+                print(`The dev server keeps running; its output goes to ${log}`);
+        }
         return {
             ...outcome,
         };
     }
     finally {
+        releaseDaemon();
         releaseSignals();
         activeDevServerStop = null;
         server.stop();

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

@@ -1,4 +1,4 @@
-import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeExistsProbe, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
+import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
 export function setupMcp(io) {
     const detected = [];
@@ -22,8 +22,8 @@ export function setupMcp(io) {
     const available = claudeAvailableProbe();
     if (io.runCli(available.command, available.args)) {
         detected.push(McpClient.CLAUDE_CODE);
-        const already = claudeExistsProbe();
-        if (io.runCli(already.command, already.args)) {
+        // Read from Claude's config: `claude mcp get` health-checks by launching the server.
+        if (claudeHasReticle(io, undefined)) {
             alreadyThere.push(McpClient.CLAUDE_CODE);
         }
         else {

package/dist/command/setup/terminal/wait-progress.d.ts

@@ -26,3 +26,11 @@ export declare const WAIT_PROGRESS_EVERY_MS = 15000;
  * without a line per poll burying the output it exists to explain.
  */
 export declare function waitProgressLine(elapsedMs: number, watching: string | undefined, lastSpokeAtMs: number | undefined): string | undefined;
+/**
+ * The same, for the wait on a session after the app is up.
+ *
+ * That wait was silent as well: a desktop init printed "Waiting for the app to launch and dial in."
+ * and then nothing for the whole of its budget. Naming what is awaited and how long remains is what
+ * lets somebody tell a slow start from a wedged one — and when to stop waiting themselves.
+ */
+export declare function connectProgressLine(elapsedMs: number, lastSpokeAtMs: number | undefined, budgetMs: number, awaiting: string): string | undefined;

package/dist/command/setup/terminal/wait-progress.js

@@ -41,3 +41,20 @@ export function waitProgressLine(elapsedMs, watching, lastSpokeAtMs) {
     return (`Waiting ${seconds} for the dev server — watching ${watching}. If the app is already up ` +
         `somewhere else, that url is the thing to check first.`);
 }
+/**
+ * The same, for the wait on a session after the app is up.
+ *
+ * That wait was silent as well: a desktop init printed "Waiting for the app to launch and dial in."
+ * and then nothing for the whole of its budget. Naming what is awaited and how long remains is what
+ * lets somebody tell a slow start from a wedged one — and when to stop waiting themselves.
+ */
+export function connectProgressLine(elapsedMs, lastSpokeAtMs, budgetMs, awaiting) {
+    if (elapsedMs < WAIT_PROGRESS_EVERY_MS)
+        return undefined;
+    if (lastSpokeAtMs !== undefined && elapsedMs - lastSpokeAtMs < WAIT_PROGRESS_EVERY_MS) {
+        return undefined;
+    }
+    const seconds = (ms) => `${String(Math.max(0, Math.floor(ms / 1000)))}s`;
+    return (`Still waiting for ${awaiting} to connect: ${seconds(elapsedMs)} so far, giving up in ` +
+        `${seconds(budgetMs - elapsedMs)}.`);
+}

package/dist/features/crawl/crawl-empty.js

@@ -19,6 +19,6 @@ export function crawlEmptyNote(outcome) {
         return `no interactive controls were found on this page, so nothing was clicked — the crawl ran and found none, which is a result rather than a failure.${capped}`;
     }
     return (`${String(outcome.interactiveFound)} interactive controls were found and none of them were clicked. ` +
-        `That is not an empty page, so something stopped the loop — report it with reticle_feedback, ` +
+        `That is not an empty page, so something stopped the loop — report it with reticle_session { action: "feedback" }, ` +
         `including this page's URL and one control's ref.`);
 }

package/dist/features/crawl/crawl-tools.d.ts

@@ -1,4 +1,10 @@
 import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * The configured secret for a field, only on the origin the crawl started on. The field name comes
+ * from whatever page is on screen, so without the check a page on another origin could name an
+ * empty textbox after a secret and have the crawl type it in.
+ */
+export declare function crawlSecret(startUrl: string, env: Readonly<Record<string, string | undefined>>): (name: string, pageUrl: string) => string | undefined;
 /**
  * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
  * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —

package/dist/features/crawl/crawl-tools.js

@@ -5,8 +5,29 @@ import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { stepCountSchema, timeoutMsSchema } from '../../surface/tools/args/numeric-bounds.js';
 import { crawl } from './crawl.js';
+import { EXHAUST_DEFAULT_ACTIONS, runExhaustive } from '../exhaust/exhaust-run.js';
+import { heuristicFillValue } from '../harness/fill-values.js';
+import { secretEnvKey } from '../../language/flows/flows.js';
+import { CRAWL_DEFAULTS } from '@reticlehq/core';
 import { routeFromUrl, routesFromEvents } from '../../memory/project/learned-routes.js';
 const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * The configured secret for a field, only on the origin the crawl started on. The field name comes
+ * from whatever page is on screen, so without the check a page on another origin could name an
+ * empty textbox after a secret and have the crawl type it in.
+ */
+export function crawlSecret(startUrl, env) {
+    const originOf = (url) => {
+        try {
+            return new URL(url).origin;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const home = originOf(startUrl);
+    return (name, pageUrl) => home !== undefined && home === originOf(pageUrl) ? env[secretEnvKey(name)] : undefined;
+}
 /**
  * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
  * actually clicking each reachable control and classifying the reaction. DESTRUCTIVE by nature —
@@ -27,6 +48,10 @@ export const CRAWL_TOOLS = [
                 .string()
                 .optional()
                 .describe('CSS selector or element ref to restrict crawling to a subtree.'),
+            exhaustive: z
+                .boolean()
+                .optional()
+                .describe("Walk every state it can tell apart, drive each write's failure path, fold into the coverage ledger."),
             confirmDangerous: z
                 .boolean()
                 .optional()
@@ -62,6 +87,8 @@ export const CRAWL_TOOLS = [
                 .optional()
                 .describe('Present only when the page exceeded one snapshot, so controls past the cap were never listed. When present, a zero-anomaly result does NOT mean the app is clean.'),
             truncated: z.boolean(),
+            // Only on `exhaustive` — see features/exhaust/exhaust-run.ts. Loose: it carries the levels.
+            exhaustive: z.record(z.unknown()).optional(),
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
@@ -76,6 +103,36 @@ export const CRAWL_TOOLS = [
                 ...(scope !== undefined ? { scope } : {}),
                 ...(true === args['confirmDangerous'] ? { confirmDangerous: true } : {}),
             };
+            if (true === args['exhaustive']) {
+                // Starts code-coverage collection, so the drive below is measured. See takeCodeCoverage.
+                await deps.realInput?.takeCodeCoverage?.(session.url);
+                const secret = crawlSecret(session.url, process.env);
+                return runExhaustive({
+                    sessions: deps.sessions,
+                    session,
+                    startUrl: session.url,
+                    maxActions: maxSteps ?? EXHAUST_DEFAULT_ACTIONS,
+                    settleMs: settleMs ?? CRAWL_DEFAULTS.SETTLE_MS,
+                    fillValue: (label, pageUrl) => {
+                        const name = /"([^"]*)"/.exec(label)?.[1] ?? label;
+                        return secret(name, pageUrl) ?? heuristicFillValue(name);
+                    },
+                    now: deps.now,
+                    sleep: nodeSleep,
+                    ...(deps.realInput?.setMocks === undefined
+                        ? {}
+                        : {
+                            setMocks: (url, rules) => deps.realInput?.setMocks?.(url, rules) ?? Promise.resolve(false),
+                        }),
+                    ...(deps.realInput?.takeCodeCoverage === undefined
+                        ? {}
+                        : {
+                            takeCode: (url) => deps.realInput?.takeCodeCoverage?.(url) ?? Promise.resolve(undefined),
+                        }),
+                    fs: deps.fs,
+                    reticleRoot: sessionRoot(deps, session.id),
+                });
+            }
             const report = await crawl(session, opts, nodeSleep);
             const routes = [
                 ...(initialRoute === undefined ? [] : [initialRoute]),

package/dist/features/crawl/crawl.d.ts

@@ -16,6 +16,8 @@ export interface CrawlSession {
     /** The page under test, so a third-party beacon cannot be reported against a control. Optional
      *  for the same reason `currentDocumentId` is. */
     readonly url?: string | undefined;
+    /** Same-origin endpoints the project declared as background. Optional like `url`. */
+    readonly background?: readonly string[] | undefined;
     /**
      * Is the page BACKGROUNDED? A hidden tab has its rAF clamped and the DOM observer flushes on rAF,
      * so real renders emit nothing and every absence-derived contradiction reads that silence as a