@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/session/stall-clock.js

@@ -0,0 +1,48 @@
+/**
+ * How long this daemon has waited with no app connected.
+ *
+ * This is what survived `instrumentation_stalled`. The EVENT was removed: it claimed to separate
+ * "never wired" from "died before reporting" and did not, because it only fired on a flush tick or a
+ * graceful shutdown, so a killed daemon was invisible to it exactly as before. Everything it carried
+ * is derivable from `daemon_started` minus `app_instrumented`, joined on `sessionId` — and that set
+ * difference is strictly MORE complete, because it does catch the killed daemons. A second way to
+ * compute the same number that disagrees with the first is worse than not having it.
+ *
+ * The CLOCK is a different thing and stays. Two live features read it, neither of them a metric: the
+ * no-session diagnosis tells an agent how long this daemon has been waiting, and the daemon warns on
+ * stderr when a run passes the threshold with nothing connected. Both are help for somebody stuck
+ * mid-install, which is the moment they are least able to work it out themselves.
+ *
+ * It lives under `session/` rather than `telemetry/` now, beside the two files that read it. The old
+ * home is why the removal looked like it would take the diagnosis with it.
+ */
+import { appEverConnected } from '../../telemetry/app-instrumented.js';
+/**
+ * When a run with nothing connected is worth mentioning to a human.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and short enough that the warning still arrives while somebody is at the keyboard.
+ */
+export const STALL_AFTER_MS = 10 * 60 * 1000;
+let daemonStartedAt;
+/** Start the clock, from the same place the instrumentation clock is marked. */
+export function markStallClock(now) {
+    daemonStartedAt = now;
+}
+/**
+ * How long this daemon has waited with no app, or undefined if the question is moot.
+ *
+ * Moot means the clock was never started, or an app already connected. A run that starts slowly and
+ * then works has nothing to report, which is why this returns undefined rather than a duration.
+ */
+export function stallUptime(now) {
+    if (daemonStartedAt === undefined)
+        return undefined;
+    if (appEverConnected())
+        return undefined;
+    return now - daemonStartedAt;
+}
+/** Tests only. */
+export function resetStallClock() {
+    daemonStartedAt = undefined;
+}

package/dist/portal/session/timing/command-timeout.d.ts

@@ -0,0 +1,40 @@
+import { AppRuntime } from '@reticlehq/core';
+/**
+ * Turn a bare command timeout into something the reader can act on.
+ *
+ * The default message — `command 'snapshot' timed out after 8000ms` — is eight seconds of silence
+ * followed by a fact with no cause. For a Tauri app the cause is usually not a bug in the app: its
+ * window was hidden before the webview had ever been PRESENTED, and a webview that has never been
+ * presented never loads its page. The session stays connected, so nothing looks wrong, and the
+ * developer goes hunting through their own code for a fault that is not there.
+ *
+ * Occlusion is NOT the cause: a loaded Tauri webview keeps answering while minimized, occluded and
+ * on another Space. `hide()` after load is the only remaining quiet path, and it is not
+ * reproducible on every machine — so it is named as a candidate, never as a fact.
+ *
+ * The only thing observed here is `hidden === true`; the hidden-before-load ORDERING is never
+ * observed. So this ranks the causes and asserts none of them: a diagnostic that names the wrong
+ * cause is worse than a bare timeout, because the bare timeout at least sends the reader looking.
+ *
+ * The advice is ADDED, never substituted — the original fact still leads — and only for a runtime
+ * that can actually suffer it.
+ */
+/**
+ * What the page told us about its shell, via PAGE_HEALTH. Undefined before the first report.
+ *
+ * An alias of core's AppRuntime rather than a second list of the same three strings: the SDK reports
+ * this value, so it is a wire value, and two independent spellings of it is how one side gains a
+ * runtime the other silently refuses to recognise.
+ */
+export type PageRuntime = AppRuntime;
+interface TimeoutContext {
+    url: string;
+    /** The page's own last visibility report. */
+    hidden: boolean;
+    /** Reported by the SDK. A URL cannot distinguish a Tauri dev server from a plain localhost app. */
+    runtime?: PageRuntime;
+    /** ms since ANY inbound message from the SDK. Small = the page is demonstrably still running. */
+    lastSeenMs?: number;
+}
+export declare function commandTimeoutMessage(name: string, timeoutMs: number, context: TimeoutContext): string;
+export {};

package/dist/portal/session/timing/command-timeout.js

@@ -0,0 +1,42 @@
+import { realmOf, AppRuntime, isOpaqueOrigin } from '@reticlehq/core';
+/**
+ * Inbound silence beyond this means the page may genuinely be wedged; inside it, the SDK has spoken
+ * recently enough that "the page is hung" is provably the wrong story. A page that is streaming
+ * events is executing JavaScript by definition.
+ */
+const RECENTLY_HEARD_MS = 2000;
+const ONE_WAY_ADVICE = 'The page is ALIVE — the SDK last reported to the bridge %MS%ms ago — but it is not answering ' +
+    'commands. A page that is still sending is executing JavaScript, so it is not hung, hidden or ' +
+    'suspended: messages are getting OUT and not back IN. Look at the bridge→page direction (a socket ' +
+    'replaced mid-session, a proxy buffering one way) rather than at your app.';
+const HIDDEN_ADVICE = 'The page last reported itself hidden, and this is a WKWebView (Tauri) window, so the webview is ' +
+    'most likely not running the page at all. Two known causes, commonest first: (1) the window was ' +
+    'hidden BEFORE its first page load — a webview that has never been presented never loads, so park ' +
+    'it from `on_page_load` instead of `setup` (see `reticle_tauri::on_page_load`, which does this for ' +
+    'RETICLE_HEADLESS=1). (2) the window was hidden after load and then went quiet — that has been ' +
+    'observed on a hidden macOS WKWebView after a pause, even though capture still works; park it ' +
+    'off-screen rather than calling hide. If neither fits, the page is reachable but not executing, ' +
+    'which is worth reporting.';
+/** True when this session is a WebKit desktop shell — the only runtime that suffers this. */
+function isWebKitDesktop(context) {
+    if (realmOf(context.runtime).usesWebKit)
+        return true;
+    // A `tauri://` origin is unambiguous even before the first health report lands.
+    if (context.runtime !== undefined)
+        return false;
+    return isOpaqueOrigin(context.url) && context.url.startsWith('tauri:');
+}
+export function commandTimeoutMessage(name, timeoutMs, context) {
+    const base = `command '${name}' timed out after ${String(timeoutMs)}ms`;
+    // Checked FIRST, and it overrides the visibility story: a page that was heard from moments ago is
+    // executing JavaScript, so "hidden, hung or never presented" cannot be the explanation whatever
+    // `hidden` says. Deduced from the invariant, not from a measured incident — the Tauri case that
+    // prompted it turned out to go fully silent instead, which this branch correctly does not claim.
+    const heard = context.lastSeenMs;
+    if (heard !== undefined && heard <= RECENTLY_HEARD_MS) {
+        return `${base}. ${ONE_WAY_ADVICE.replace('%MS%', String(heard))}`;
+    }
+    if (!context.hidden || !isWebKitDesktop(context))
+        return base;
+    return `${base}. ${HIDDEN_ADVICE}`;
+}

package/dist/start-options.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What `start()` accepts.
+ *
+ * A leaf: `bridge-security.ts` names this type and had to import it out of the package barrel,
+ * which imports bridge-security. A shape is not a barrel's to own.
+ */
+import type { OwnedRealInputProvider } from './portal/input/real-input.js';
+import type { InjectConnectOptions } from './portal/input/real-input.js';
+export interface StartOptions {
+    port?: number;
+    /** Bind address. Non-loopback hosts require a token. Defaults to RETICLE_HOST or localhost. */
+    host?: string;
+    /** Browser/bridge pairing token. Defaults to RETICLE_TOKEN. */
+    token?: string;
+    /** Browser origins allowed in addition to localhost. Defaults to RETICLE_ALLOWED_ORIGINS. */
+    allowedOrigins?: string[];
+    /** When false, skip the MCP stdio transport (used in tests). */
+    mcp?: boolean;
+    /** CDP endpoint for native real-input mode. Defaults to env RETICLE_CDP_URL. No-op if unset. */
+    cdpUrl?: string;
+    /** launch+own a Playwright Chromium at this url and route pointer actions through it. */
+    driveUrl?: string;
+    /** launch headless (default true; CLI `--headed` sets false). */
+    headless?: boolean;
+    /** injected so tests swap in a fake launched provider instead of real Playwright. */
+    realInputFactory?: (opts: {
+        driveUrl: string;
+        headless: boolean;
+    }) => OwnedRealInputProvider;
+    /** When driving, force the page's SDK to (re)connect to our bridge with this token — verify a hosted preview. */
+    injectConnect?: InjectConnectOptions;
+    /** Path to a Playwright storageState JSON so the driven browser starts authenticated (past a login wall). */
+    storageState?: string;
+    /** absolute .reticle root. Defaults to process.cwd()/.reticle. Injectable for tests. */
+    reticleRoot?: string;
+    /** Directory holding the auto-provisioned pairing token. Defaults to ~/.reticle. Injectable for tests. */
+    pairingTokenDir?: string;
+    /** injectable clock for contract.json's generatedAt stamp. Defaults to Date.now. */
+    now?: () => number;
+    /**
+     * Retired profile name (`core`/`full`/…). Old values still map. The live switch is
+     * RETICLE_ADVERTISE_ALL_TOOLS=1; the default is the lean surface.
+     */
+    toolProfile?: string;
+    /** Start the OEM/CI verify HTTP endpoint alongside the daemon (`reticle serve --http`). */
+    httpVerify?: boolean;
+    /** Port for the verify endpoint. Defaults to RETICLE_VERIFY_DEFAULT_PORT. */
+    httpVerifyPort?: number;
+    /** Shared token for the verify endpoint. Defaults to env RETICLE_VERIFY_TOKEN, else open (localhost). */
+    httpVerifyToken?: string;
+}

package/dist/start-options.js

@@ -0,0 +1,7 @@
+/**
+ * What `start()` accepts.
+ *
+ * A leaf: `bridge-security.ts` names this type and had to import it out of the package barrel,
+ * which imports bridge-security. A shape is not a barrel's to own.
+ */
+export {};

package/dist/status-payload.d.ts

@@ -4,9 +4,9 @@
  * Carries the daemon's OWN version, because a daemon outlives every agent attached to it: after an
  * upgrade the new CLI attaches to the old daemon and serves its code, and until this field existed
  * there was no surface anywhere — not /status, not `reticle status` — naming the version actually
- * answering requests. See describeDaemonSkew.
+ * answering requests. See takeVersionSkewOnto in command/version/version-nudge.ts.
  */
-import type { SessionInfo } from './session/session-info.js';
+import type { SessionInfo } from './portal/session/session-info.js';
 interface StatusPayload {
     running: true;
     version: string;
@@ -15,21 +15,27 @@ interface StatusPayload {
     sessionCount: number;
     sessions: SessionInfo[];
     /**
-     * Why nothing is connected — present ONLY when `sessionCount` is 0.
-     *
-     * `reticle status` is the most-run command in the field, and with no sessions it answered
-     * `sessionCount: 0` and stopped. That is the same dead end `reticle_sessions` used to be for
-     * agents, at the same point in the funnel — the daemon is up, the agent is attached, and the app
-     * never arrived — and it is where most installs stop. Agents got the diagnosis in 2.7.0; a human
-     * running the command we tell them to run in `init`'s closing line deserves the same sentence.
+     * Why nothing is connected — present ONLY when `sessionCount` is 0, so a diagnosis never prints
+     * beside a live session.
      */
     why?: string;
+    /**
+     * The same diagnosis with the differential left off: the lead and the next action.
+     *
+     * Two fields because there are two readers. `why` is for an agent about to spend a drive on a
+     * guess, and carries the ranked causes, the port-scan caveat and the lease offer. `whyLead` is
+     * for a surface a PERSON reads: `reticle init` prints the daemon's account of a failed connect,
+     * and was printing roughly five hundred words of it in one paragraph.
+     */
+    whyLead?: string;
     /** Port of the verify HTTP endpoint this daemon serves — present only when started with `--http`. */
     verifyPort?: number;
 }
 export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why?: string, verifyPort?: number): StatusPayload;
+why?: string, verifyPort?: number, 
+/** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
+whyLead?: string): StatusPayload;
 /**
  * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
  * that daemon already serves the verify HTTP endpoint on the wanted port.

package/dist/status-payload.js

@@ -1,8 +1,10 @@
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
-import { SERVER_VERSION } from './version/server-version.js';
+import { SERVER_VERSION } from './command/version/identity/server-version.js';
 export function statusPayload(sessionCount, sessions, 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why, verifyPort) {
+why, verifyPort, 
+/** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
+whyLead) {
     return {
         running: true,
         version: SERVER_VERSION,
@@ -12,6 +14,7 @@ why, verifyPort) {
         // Only when there is nothing to explain away: a diagnosis printed beside a live session would
         // contradict it.
         ...(0 === sessionCount && why !== undefined ? { why } : {}),
+        ...(0 === sessionCount && whyLead !== undefined ? { whyLead } : {}),
         ...(verifyPort === undefined ? {} : { verifyPort }),
     };
 }

package/dist/surface/http-server.d.ts

@@ -0,0 +1,52 @@
+import * as http from 'node:http';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface SharedServer {
+    readonly httpServer: http.Server;
+    /**
+     * Register a factory that creates a fresh McpServer per SSE connection.
+     * The MCP SDK's Protocol layer only supports one transport per Server instance,
+     * so each concurrent Claude Code client needs its own McpServer.
+     * Must be called before listen.
+     */
+    attachMcp(factory: () => McpServer): void;
+    /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
+    attachStatus(provider: () => unknown): void;
+    /**
+     * Register the handler behind POST /drive: open a driveable browser at `url` and answer with the
+     * session it registered.
+     *
+     * This is how `reticle drive` stops fighting the daemon for the bridge port. The daemon already
+     * owns the browser plane, so driving is a request to it — see cli/drive/drive-attach.ts. Left
+     * unattached, the route 404s, which is exactly what a newer CLI needs to hear from an older daemon.
+     */
+    attachDrive(provider: (url: string) => Promise<unknown>): void;
+    /**
+     * Register a callback fired when the AGENT presence changes — true when the first MCP client (any
+     * agent: Codex/OpenCode/Claude/Hermes) connects, false when the last one disconnects. Agent-
+     * independent: the MCP connection lives exactly as long as the agent session, so its presence IS
+     * "is an agent attached?". The daemon uses this to tell the panel "agent live" vs "agent stopped".
+     */
+    attachAgentPresence(cb: (connected: boolean) => void): void;
+    /**
+     * Tell every attached MCP proxy that this daemon is retiring, BEFORE the sockets go.
+     *
+     * The proxy sees a clean stream end whether the daemon shut down on schedule or died under it, so
+     * without this the two are one row and the transport-stability metric is dominated by the designed
+     * case. Separate from `close()` because it must run before the shutdown work rather than during it:
+     * `close()` is also the cleanup path of a start that failed, where there is nobody to tell.
+     */
+    announceShutdown(): void;
+    close(): Promise<void>;
+}
+/**
+ * Creates a shared HTTP server that handles both the WebSocket bridge (browser SDK) and the
+ * SSE MCP transport (Claude/agent). Does NOT call listen — caller controls that.
+ *
+ * Routes:
+ * GET /mcp/sse → establishes SSE MCP session
+ * POST /mcp/message → routes MCP messages to an active SSE session
+ * WS /reticle → browser SDK connections (via WebSocketServer)
+ */
+export declare function createSharedServer(options?: {
+    token?: string;
+}): SharedServer;