@reticlehq/server 3.8.2 → 3.10.0

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

@@ -8,6 +8,7 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { mcpLauncher } from './mcp-launcher.js';
 import { planAgentConfigs, platformKey } from './agent-configs.js';
 import { AppShape, describeShape, readShape } from './desktop-shape.js';
 import { devConfigText, expectedDevPort, loneLoopbackOnDevPort, pinnedDevPort, } from './probe/dev-port.js';
@@ -25,7 +26,7 @@ import { spawnSync } from 'node:child_process';
 import { isAlive, reticleStateHome } from '../daemon/daemon.js';
 import { readDevServers } from '../daemon/dev-servers.js';
 import { connectedAppUrl, urlOfExistingApp } from './probe/existing-app.js';
-import { handedOverUrl, stopHandedOver } from './bringup/dev-server-files.js';
+import { handedOverToOtherPort, 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 { daemonSkew, summarizeStatus } from '../cli/launch/cli-launch.js';
@@ -73,8 +74,9 @@ export function installCrashGuard() {
 function hasElectronDependency(dir) {
     try {
         const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-        if ('object' !== typeof pkg || null === pkg)
+        if ('object' !== typeof pkg || null === pkg) {
             return false;
+        }
         const p = pkg;
         return undefined !== { ...p.dependencies, ...p.devDependencies }['electron'];
     }
@@ -95,7 +97,13 @@ const agentWord = (n) => (1 === n ? 'agent' : 'agents');
 export function registerOtherAgents(print) {
     const platform = platformKey(process.platform);
     const home = homedir();
-    const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
+    const results = applyAgentPlan(planAgentConfigs({
+        home,
+        platform,
+        exists: agentIo.exists,
+        readFile: agentIo.readFile,
+        launcher: mcpLauncher(),
+    }), agentIo);
     const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
     if (0 < wrote.length) {
         print(`  ✓ ${String(wrote.length)} more ${agentWord(wrote.length)}: ${wrote.map((r) => r.name).join(', ')}`);
@@ -115,8 +123,9 @@ export function registerOtherAgents(print) {
     }
     rememberSaid(stateHome, fresh.map((n) => noticeKey(n)));
     const skills = applyAgentSkills(agentIo, { home, platform });
-    if (0 < skills.length)
+    if (0 < skills.length) {
         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 });
@@ -173,8 +182,9 @@ async function restartHandedOverServer(appDir) {
  */
 async function afterConnect(input, url, sessionId, outcome, print) {
     const notes = [...outcome.notes];
-    if (input.firstFlow === undefined)
+    if (input.firstFlow === undefined) {
         return { flowSaved: false, notes };
+    }
     const { flowSaved } = await input.firstFlow({
         appDir: input.appDir,
         bridgePort: input.bridgePort,
@@ -192,8 +202,9 @@ async function afterConnect(input, url, sessionId, outcome, print) {
     return { flowSaved, notes };
 }
 export async function runSetupCommand(input, print) {
-    if (input.registerAgents)
+    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());
@@ -203,14 +214,18 @@ export async function runSetupCommand(input, print) {
     }
     // 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))) {
+    // Its record names the port it was started for, so this works when the old daemon is gone too.
+    const movedUnderServer = 0 < retired.length ||
+        handedOverToOtherPort(reticleStateHome(), input.appDir, input.bridgePort, { alive: isAlive });
+    if (movedUnderServer && (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((status) => undefined !== daemonSkew(status)));
-    if (undefined !== daemon.message)
+    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.
@@ -235,8 +250,9 @@ export async function runSetupCommand(input, print) {
         hasTauriConf: existsSync(join(input.appDir, 'src-tauri', 'tauri.conf.json')),
         hasElectronDep: hasElectronDependency(input.appDir),
     });
-    if (AppShape.WEB !== shape)
+    if (AppShape.WEB !== shape) {
         print(`detected ${describeShape(shape)}`);
+    }
     const server = new OwnedDevServer();
     const effects = {
         startDevServer: (command, cwd) => {
@@ -261,8 +277,9 @@ export async function runSetupCommand(input, print) {
                     },
                 })
                 : {};
-            if (SigningEnv.IDENTITY in signing)
+            if (SigningEnv.IDENTITY in signing) {
                 print(`signing the dev build as ${String(signing[SigningEnv.IDENTITY])}, so macOS does not ask for the keychain password`);
+            }
             server.start(command, cwd, { ...input.env, ...signing });
             return Promise.resolve();
         },
@@ -288,8 +305,9 @@ export async function runSetupCommand(input, print) {
         probePage,
         openBrowser: async (url) => {
             const failure = await openInBrowser(url);
-            if (null === failure)
+            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.
@@ -310,8 +328,9 @@ export async function runSetupCommand(input, print) {
             // A daemon too old to report the short one falls back to the long one, because saying the
             // right thing at length beats saying nothing.
             const lead = status.whyLead ?? full;
-            if (undefined === lead)
+            if (undefined === lead) {
                 return undefined;
+            }
             return undefined === full ? { lead } : { lead, full };
         },
         now: () => Date.now(),
@@ -348,15 +367,17 @@ export async function runSetupCommand(input, print) {
         }, effects);
         // The app stays up only when there is something worth watching.
         if (outcome.ok) {
-            server.handOver(outcome.url);
+            server.handOver(outcome.url, input.bridgePort);
             // 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)
+            if (undefined !== log) {
                 print(`The dev server keeps running; its output goes to ${log}`);
+            }
         }
-        if (!outcome.ok || undefined === outcome.url || undefined === outcome.sessionId)
+        if (!outcome.ok || undefined === outcome.url || undefined === outcome.sessionId) {
             return outcome;
+        }
         return {
             ...outcome,
             ...(await afterConnect(input, outcome.url, outcome.sessionId, outcome, print)),

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

@@ -17,6 +17,8 @@ export interface SetupMcpIo {
     writeFile(path: string, contents: string): void;
     homeDir(): string;
     print(line: string): void;
+    /** The installed bin to register (`InitHost.mcpLauncher`). Absent: the pinned npx command. */
+    readonly launcher?: string | undefined;
     /** Register with a client that owns its own registration (Claude Code). Returns whether it took. */
     runCli(command: string, args: readonly string[]): boolean;
     /**
@@ -46,6 +48,12 @@ export interface SetupMcpResult {
      * and a pre-seeded `~/.codex/config.toml`; the file came back byte-identical both times.
      */
     readonly manual: readonly ManualClient[];
+    /** Clients whose Reticle plugin brings the server, so nothing was registered for them. */
+    readonly pluginActive: readonly string[];
+    /** Clients with the plugin AND a user-scope `reticle` entry: two servers. Named, never removed. */
+    readonly duplicates: readonly string[];
+    /** Clients whose `reticle` entry is the floating npx form. Named with the fix, never replaced. */
+    readonly stale: readonly string[];
 }
 /** A client the caller has to tell somebody about, with the two facts they need to act. */
 export interface ManualClient {

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

@@ -1,5 +1,5 @@
-import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, codexAddCommand, codexAvailableProbe, codexNamesOurServer, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
-import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
+import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, claudePluginInstalled, claudeUserEntryIsFloating, codexAddCommand, codexAvailableProbe, codexNamesOurServer, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
+import { OnboardingPhase, OnboardingStepStatus, OnboardingStop, } from '@reticlehq/core/telemetry';
 /**
  * Codex registers through `codex mcp add`, which does the TOML editing we refuse to do (#1238).
  * `undefined` when that does not apply, and the caller reports a hand edit exactly as before: not
@@ -12,9 +12,10 @@ function registerWithCodexCli(io, client, serversKey) {
         return undefined;
     }
     const probe = codexAvailableProbe();
-    if (!io.runCli(probe.command, probe.args))
+    if (!io.runCli(probe.command, probe.args)) {
         return undefined;
-    const cmd = codexAddCommand();
+    }
+    const cmd = codexAddCommand(io.launcher);
     return io.runCli(cmd.command, cmd.args);
 }
 export function setupMcp(io) {
@@ -23,6 +24,9 @@ export function setupMcp(io) {
     const alreadyThere = [];
     const failed = [];
     const manual = [];
+    const pluginActive = [];
+    const duplicates = [];
+    const stale = [];
     /*
      * Claude Code first, because nothing else can find it.
      *
@@ -41,21 +45,34 @@ export function setupMcp(io) {
     if (io.runCli(available.command, available.args)) {
         detected.push(McpClient.CLAUDE_CODE);
         // Read from Claude's config: `claude mcp get` health-checks by launching the server.
-        if (claudeHasReticle(io, undefined)) {
+        const hasEntry = claudeHasReticle(io, undefined);
+        if (claudePluginInstalled(io)) {
+            // The plugin brings its own server. A user-scope entry next to it is a second one.
+            pluginActive.push(McpClient.CLAUDE_CODE);
+            if (hasEntry) {
+                duplicates.push(McpClient.CLAUDE_CODE);
+            }
+        }
+        else if (hasEntry) {
             alreadyThere.push(McpClient.CLAUDE_CODE);
+            if (claudeUserEntryIsFloating(io)) {
+                stale.push(McpClient.CLAUDE_CODE);
+            }
         }
         else {
-            const cmd = claudeAddCommand();
-            if (io.runCli(cmd.command, cmd.args))
+            const cmd = claudeAddCommand(io.launcher);
+            if (io.runCli(cmd.command, cmd.args)) {
                 registered.push(McpClient.CLAUDE_CODE);
-            else
+            }
+            else {
                 failed.push(McpClient.CLAUDE_CODE);
+            }
         }
     }
     for (const client of detectMcpClients(io)) {
         detected.push(client.id);
         const spec = clientSpec(client.id);
-        const merged = mergeClientConfig(spec, client.existing);
+        const merged = mergeClientConfig(spec, client.existing, io.launcher);
         if (ClientMergeStatus.ALREADY === merged.status) {
             alreadyThere.push(client.id);
             continue;
@@ -65,12 +82,15 @@ export function setupMcp(io) {
         // sends somebody to an agent that has no Reticle tools in it.
         if (ClientMergeStatus.MANUAL === merged.status) {
             const viaCli = registerWithCodexCli(io, client, spec.serversKey);
-            if (true === viaCli)
+            if (true === viaCli) {
                 registered.push(client.id);
-            else if (false === viaCli)
+            }
+            else if (false === viaCli) {
                 failed.push(client.id);
-            else
+            }
+            else {
                 manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
+            }
             continue;
         }
         try {
@@ -93,6 +113,7 @@ export function setupMcp(io) {
         step: 'agents_detected',
         status: OnboardingStepStatus.COMPLETED,
     });
+    const mcpStatus = mcpRegisteredStatus(detected.length, registered.length, alreadyThere.length + pluginActive.length);
     io.reportStep({
         phase: OnboardingPhase.INSTALL,
         step: 'mcp_registered',
@@ -107,15 +128,21 @@ export function setupMcp(io) {
          * for. Registering some and not others is still COMPLETED: the agent they are using may well be
          * one that worked, and a partial win is not a failed step.
          */
-        status: 0 === detected.length
-            ? OnboardingStepStatus.SKIPPED
-            : 0 === registered.length && alreadyThere.length > 0
-                ? OnboardingStepStatus.SKIPPED
-                : 0 === registered.length && 0 === alreadyThere.length
-                    ? OnboardingStepStatus.FAILED
-                    : OnboardingStepStatus.COMPLETED,
+        status: mcpStatus,
+        ...(OnboardingStepStatus.FAILED === mcpStatus
+            ? { stop: OnboardingStop.MCP_NOT_REGISTERED }
+            : {}),
     });
-    return { detected, registered, alreadyThere, failed, manual };
+    return { detected, registered, alreadyThere, failed, manual, pluginActive, duplicates, stale };
+}
+function mcpRegisteredStatus(detected, registered, alreadyThere) {
+    if (0 === detected || (0 === registered && 0 < alreadyThere)) {
+        return OnboardingStepStatus.SKIPPED;
+    }
+    if (0 === registered) {
+        return OnboardingStepStatus.FAILED;
+    }
+    return OnboardingStepStatus.COMPLETED;
 }
 /** Everything this machine could be asked about, for the report when nothing was found. */
 export function knownClientLabels() {

package/dist/command/setup/start-dev-server.d.ts

@@ -0,0 +1,8 @@
+/** The url it serves and how to stop it, or why it did not serve. */
+export type StartedDevServer = {
+    url: string;
+    stop: () => void;
+} | {
+    failed: string;
+};
+export declare function startDevServerAndWait(command: string, dir: string, budgetMs: number): Promise<StartedDevServer>;

package/dist/command/setup/start-dev-server.js

@@ -0,0 +1,43 @@
+/**
+ * Start a project's dev script and wait until it serves a page, for a command that is not `init`.
+ *
+ * The same pieces `init` uses: the supervised `OwnedDevServer`, the URL it announces or the port its
+ * process tree binds, and `judgeWait` for ready, dead or hung. `init` keeps its own loop because it
+ * also reports progress and hands the server over; this one stops the server when the caller is done.
+ */
+import { OwnedDevServer, probePage } from './node-effects.js';
+import { WaitVerdict, devServerDiedMessage, judgeWait, portBusyMessage, urlToWatch, } from './bringup/dev-server-wait.js';
+const POLL_MS = 500;
+const MS_PER_S = 1000;
+export async function startDevServerAndWait(command, dir, budgetMs) {
+    const server = new OwnedDevServer();
+    server.start(command, dir, {});
+    const startedAt = Date.now();
+    for (;;) {
+        const watching = urlToWatch(server.output(), server.listeningPorts());
+        const probe = watching === undefined ? undefined : await probePage(watching);
+        const verdict = judgeWait({
+            output: server.output(),
+            launcherExited: server.exited(),
+            serving: true === probe?.served,
+            quietForMs: server.quietForMs(),
+            elapsedMs: Date.now() - startedAt,
+            budgetMs,
+        });
+        if (WaitVerdict.READY === verdict && watching !== undefined) {
+            return { url: probe?.reachedUrl ?? watching, stop: () => server.stop() };
+        }
+        if (WaitVerdict.DEAD === verdict) {
+            const failed = portBusyMessage(server.output()) ?? devServerDiedMessage(server.output());
+            server.stop();
+            return { failed };
+        }
+        if (WaitVerdict.HUNG === verdict) {
+            server.stop();
+            return {
+                failed: `The dev server did not serve a page in ${String(budgetMs / MS_PER_S)}s.`,
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+}

package/dist/command/update/updater.js

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import { NodePlatform } from '../../machine/platform.js';
+import { PLUGIN_SERVER_DIR } from '../../telemetry/agent-client.js';
 import { existsSync } from 'node:fs';
 import { platform } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -63,6 +64,11 @@ function detectExecutionKind() {
 export function classifyExecutionKind(script) {
     if (script.includes('/_npx/') || script.includes('\\_npx\\'))
         return ExecutionKind.NPX;
+    // The Claude Code plugin's copy sits in a `node_modules`, but it is not the project's. It is pinned
+    // to the plugin version, so treat it as npx: a restart picks the version, and nothing is installed.
+    if (script.includes(`/${PLUGIN_SERVER_DIR}/`) || script.includes(`\\${PLUGIN_SERVER_DIR}\\`)) {
+        return ExecutionKind.NPX;
+    }
     const globalSignals = [
         '/lib/node_modules/',
         '\\npm\\node_modules\\',

package/dist/command/version/identity/server-version.d.ts

@@ -5,3 +5,5 @@ export declare const SERVER_VERSION: string;
  * drift. Self-update installs THIS (never `@reticlehq/core`, which is schema-only and has no bin).
  */
 export declare const RETICLE_NPM_PACKAGE: string;
+/** The Node.js range this package declares in `engines`, such as `>=20.11`. */
+export declare const SERVER_NODE_RANGE: string | undefined;

package/dist/command/version/identity/server-version.js

@@ -48,3 +48,5 @@ export const SERVER_VERSION = _pkg.version;
  * drift. Self-update installs THIS (never `@reticlehq/core`, which is schema-only and has no bin).
  */
 export const RETICLE_NPM_PACKAGE = _pkg.name;
+/** The Node.js range this package declares in `engines`, such as `>=20.11`. */
+export const SERVER_NODE_RANGE = _pkg.engines?.node;

package/dist/command/version/version-skew.d.ts

@@ -106,6 +106,13 @@ export declare function compareVersions(a: string | undefined, b: string): numbe
 export declare function sdkIsBehind(sdk: string | undefined, daemon: string): boolean;
 /** The same fact for the person looking at the page, on its overlay. */
 export declare const SDK_BEHIND_NARRATION: (sdk: string, daemon: string) => string;
+/**
+ * The sentence for a screenshot the page cannot draw because its SDK is behind this daemon.
+ *
+ * `render` is one of the things a behind page does not have. The refusal from the page names the
+ * missing command and nothing else; this is the same update the overlay already shows.
+ */
+export declare function sdkBehindNote(sdk: string | undefined): string | undefined;
 /**
  * A page whose SDK is a minor release or more behind this daemon.
  *

package/dist/command/version/version-skew.js

@@ -23,6 +23,7 @@
  * a human acts on.
  */
 import { RETIRED_WIRE_NAMES } from '@reticlehq/core';
+import { SERVER_VERSION } from './identity/server-version.js';
 import { resolveSdkFix } from './sdk-fix.js';
 /** Which pair disagreed. Named so the nudge can report each independently. */
 export const SkewPair = {
@@ -60,7 +61,7 @@ function namesWeDoNotKnow(peer, self) {
 export const SKEW_CONVERGE = "To put every piece on one version, update the CLI and the app SDK (`reticle update` in the app's " +
     'folder does both), then restart the MCP host.';
 /** The fix for two builds of one version. */
-const SAME_VERSION_FIX = 'Both say the same version, so one of them is an older build of it: run `reticle restart`, then ' +
+const SAME_VERSION_FIX = 'Both say the same version, so one of them is an older build of it: run `reticle serve --restart`, then ' +
     'reload the page so it loads the SDK the dev server serves now.';
 function versionPhrase(peer, self) {
     return peer.version === undefined
@@ -177,9 +178,19 @@ export function sdkIsBehind(sdk, daemon) {
     const order = compareVersions(minorOf(sdk), minorOf(daemon));
     return order !== undefined && order < 0;
 }
+/** What to run so the page picks up the daemon's SDK. */
+const UPDATE_THE_SDK = "Run `reticle update` in the app's folder, then restart its dev server.";
 /** The same fact for the person looking at the page, on its overlay. */
-export const SDK_BEHIND_NARRATION = (sdk, daemon) => `This app runs Reticle SDK ${sdk}, older than Reticle ${daemon}. Run \`reticle update\` in the ` +
-    "app's folder, then restart its dev server.";
+export const SDK_BEHIND_NARRATION = (sdk, daemon) => `This app runs Reticle SDK ${sdk}, older than Reticle ${daemon}. ${UPDATE_THE_SDK}`;
+/**
+ * The sentence for a screenshot the page cannot draw because its SDK is behind this daemon.
+ *
+ * `render` is one of the things a behind page does not have. The refusal from the page names the
+ * missing command and nothing else; this is the same update the overlay already shows.
+ */
+export function sdkBehindNote(sdk) {
+    return describeSdkBehind(sdk, SERVER_VERSION, () => UPDATE_THE_SDK);
+}
 /**
  * A page whose SDK is a minor release or more behind this daemon.
  *