@reticlehq/server 2.8.0 → 2.10.0

package/dist/session/dev-server-probe.d.ts

@@ -9,5 +9,73 @@
  * the probe refreshes in the background and the resolve path reads a cached answer. A stale answer
  * is fine here — it is a hint in an error message, not a decision.
  */
+/**
+ * What the probe actually learned about a port. Three states, because two cannot express this.
+ *
+ * A bare TCP connect is not enough (macOS AirPlay Receiver holds 5000 on every Mac and would read as
+ * the user's dev server), and a document check alone is not enough either (a compiling SSR server
+ * reads as absent). The thing in between — accepted the connection, said nothing in time — is a
+ * listener we cannot classify, and reporting that honestly is the point.
+ */
+export declare const PortState: {
+    /** Nothing accepted a connection on either loopback family. */
+    readonly CLOSED: "closed";
+    /** Accepted a connection, then answered nothing within the budget. Something IS there. */
+    readonly CONNECTED_NO_ANSWER: "connected-no-answer";
+    /** Answered with a document: a dev server serving an app. */
+    readonly SERVES_DOCUMENT: "serves-document";
+};
+export type PortState = (typeof PortState)[keyof typeof PortState];
+/** The probe's answer for one port, however it was obtained. */
+export declare function classifyPort(port: number, probe: (port: number) => Promise<PortState>): Promise<PortState>;
+/**
+ * `localhost`, not `127.0.0.1` — so BOTH address families are tried.
+ *
+ * Measured: a plain `vite --port 4311` on this machine listens on `[::1]` only, and a probe pinned to
+ * the IPv4 loopback cannot see it. The old TCP probe had the same blind spot, which meant the
+ * diagnostic could miss the very dev server it exists to find while still reporting an unrelated
+ * service that happens to bind both stacks (macOS AirPlay does).
+ */
+/**
+ * Both loopback addresses, BY ADDRESS — never by the name `localhost`.
+ *
+ * A dev server started with `--host` binds the wildcards `0.0.0.0` and `[::]` rather than the
+ * loopbacks, and a wildcard bind serves only the family it belongs to. Asking for `localhost` hands
+ * the choice of family to the resolver: on Windows it prefers `::1`, so a `0.0.0.0` listener is
+ * invisible and the scan reports "nothing is listening" about a dev server that is plainly running.
+ * Reported from the field on exactly that setup.
+ *
+ * `[::1]` is also how a `[::]` bind is reached, and on most stacks a `[::]` bind additionally
+ * accepts v4-mapped connections — so between the two, every ordinary bind is covered.
+ */
+export declare const PROBE_HOSTS: readonly string[];
+/**
+ * Is anything serving a document on this port, on EITHER loopback family?
+ *
+ * "Either" and not "both": one answer is enough, and requiring both would make the wildcard binds
+ * this exists to see fail the check again. A family that errors (no IPv6 stack at all) is an
+ * absence, never a rejection — a diagnostic must not throw at the tool it is diagnosing.
+ */
+export declare function anyFamilyServes(port: number, probe?: (port: number, host: string) => Promise<boolean>): Promise<boolean>;
+/**
+ * Every candidate port, split by what the probe could actually establish.
+ *
+ * `slow` is the set that accepted a connection and then said nothing inside the budget. Those ports
+ * are NOT dev servers as far as this check knows, and they are emphatically not absent — an SSR
+ * framework compiling its first route lands here every time. Reported separately so the diagnosis
+ * can stop telling people to start a server that is already running.
+ */
+export declare function probeDevServerStates(ports?: readonly number[], probe?: (port: number) => Promise<PortState>): Promise<{
+    serving: number[];
+    slow: number[];
+}>;
+/**
+ * The strongest state either loopback family reports.
+ *
+ * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
+ * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
+ * three states.
+ */
+export declare function anyFamilyState(port: number, probe?: (port: number, host: string) => Promise<PortState>): Promise<PortState>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;

package/dist/session/dev-server-probe.js

@@ -12,8 +12,37 @@
 import { request } from 'node:http';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
 import { looksLikeDevServer } from './looks-like-dev-server.js';
-/** Give up fast: an HTTP answer from localhost either lands quickly or nothing is there. */
+/**
+ * Give up fast, but do not call giving up an absence.
+ *
+ * This budget suits Vite handing back a static index.html. It does NOT suit an SSR framework
+ * compiling a route on the first request: Nuxt and Next routinely take seconds cold, and treating
+ * that as "nothing is there" told a reporter to start a dev server that was already serving 57KB of
+ * HTML — advice that would have hit their dev lock with a second `nuxt dev`.
+ *
+ * So the budget stays short and the TIMEOUT changed meaning instead. See PortState.
+ */
 const HTTP_PROBE_TIMEOUT_MS = 400;
+/**
+ * What the probe actually learned about a port. Three states, because two cannot express this.
+ *
+ * A bare TCP connect is not enough (macOS AirPlay Receiver holds 5000 on every Mac and would read as
+ * the user's dev server), and a document check alone is not enough either (a compiling SSR server
+ * reads as absent). The thing in between — accepted the connection, said nothing in time — is a
+ * listener we cannot classify, and reporting that honestly is the point.
+ */
+export const PortState = {
+    /** Nothing accepted a connection on either loopback family. */
+    CLOSED: 'closed',
+    /** Accepted a connection, then answered nothing within the budget. Something IS there. */
+    CONNECTED_NO_ANSWER: 'connected-no-answer',
+    /** Answered with a document: a dev server serving an app. */
+    SERVES_DOCUMENT: 'serves-document',
+};
+/** The probe's answer for one port, however it was obtained. */
+export function classifyPort(port, probe) {
+    return probe(port).catch(() => PortState.CLOSED);
+}
 /**
  * `localhost`, not `127.0.0.1` — so BOTH address families are tried.
  *
@@ -22,7 +51,19 @@ const HTTP_PROBE_TIMEOUT_MS = 400;
  * diagnostic could miss the very dev server it exists to find while still reporting an unrelated
  * service that happens to bind both stacks (macOS AirPlay does).
  */
-const PROBE_HOST = 'localhost';
+/**
+ * Both loopback addresses, BY ADDRESS — never by the name `localhost`.
+ *
+ * A dev server started with `--host` binds the wildcards `0.0.0.0` and `[::]` rather than the
+ * loopbacks, and a wildcard bind serves only the family it belongs to. Asking for `localhost` hands
+ * the choice of family to the resolver: on Windows it prefers `::1`, so a `0.0.0.0` listener is
+ * invisible and the scan reports "nothing is listening" about a dev server that is plainly running.
+ * Reported from the field on exactly that setup.
+ *
+ * `[::1]` is also how a `[::]` bind is reached, and on most stacks a `[::]` bind additionally
+ * accepts v4-mapped connections — so between the two, every ordinary bind is covered.
+ */
+export const PROBE_HOSTS = ['127.0.0.1', '::1'];
 /**
  * Does this port serve a DOCUMENT — i.e. is it a dev server rather than merely something listening?
  *
@@ -30,23 +71,77 @@ const PROBE_HOST = 'localhost';
  * port 5000) as the user's dev server. See looks-like-dev-server for what it actually answers and
  * why "a socket accepted" is the wrong question.
  */
-function servesDocument(port, host = PROBE_HOST) {
+function probeState(port, host) {
     return new Promise((resolve) => {
+        // Whether the SOCKET came up is tracked separately from whether a response did, because that is
+        // the whole difference between "nothing is there" and "something is there and still compiling".
+        let connected = false;
         const req = request({ host, port, path: '/', method: 'GET', timeout: HTTP_PROBE_TIMEOUT_MS }, (res) => {
             const answer = looksLikeDevServer(res.statusCode ?? 0, res.headers['content-type']);
             res.resume(); // drain, so the socket closes rather than lingering
-            resolve(answer);
+            resolve(answer ? PortState.SERVES_DOCUMENT : PortState.CLOSED);
+        });
+        req.once('socket', (socket) => {
+            socket.once('connect', () => {
+                connected = true;
+            });
         });
         req.once('timeout', () => {
             req.destroy();
-            resolve(false);
+            resolve(connected ? PortState.CONNECTED_NO_ANSWER : PortState.CLOSED);
         });
-        req.once('error', () => resolve(false));
+        req.once('error', () => resolve(PortState.CLOSED));
         req.end();
     });
 }
+/** Kept for callers that only need the yes/no. A slow listener is NOT a dev server, but it is not absent. */
+function servesDocument(port, host) {
+    return probeState(port, host).then((state) => state === PortState.SERVES_DOCUMENT);
+}
+/**
+ * Is anything serving a document on this port, on EITHER loopback family?
+ *
+ * "Either" and not "both": one answer is enough, and requiring both would make the wildcard binds
+ * this exists to see fail the check again. A family that errors (no IPv6 stack at all) is an
+ * absence, never a rejection — a diagnostic must not throw at the tool it is diagnosing.
+ */
+export async function anyFamilyServes(port, probe = servesDocument) {
+    const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => false)));
+    return answers.some((up) => up);
+}
+/**
+ * Every candidate port, split by what the probe could actually establish.
+ *
+ * `slow` is the set that accepted a connection and then said nothing inside the budget. Those ports
+ * are NOT dev servers as far as this check knows, and they are emphatically not absent — an SSR
+ * framework compiling its first route lands here every time. Reported separately so the diagnosis
+ * can stop telling people to start a server that is already running.
+ */
+export async function probeDevServerStates(ports = [...DEV_SERVER_PORTS], probe = (p) => anyFamilyState(p)) {
+    const states = await Promise.all(ports.map((p) => classifyPort(p, probe).then((state) => ({ port: p, state }))));
+    const pick = (want) => states
+        .filter((s) => s.state === want)
+        .map((s) => s.port)
+        .sort((a, b) => a - b);
+    return { serving: pick(PortState.SERVES_DOCUMENT), slow: pick(PortState.CONNECTED_NO_ANSWER) };
+}
+/**
+ * The strongest state either loopback family reports.
+ *
+ * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
+ * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
+ * three states.
+ */
+export async function anyFamilyState(port, probe = probeState) {
+    const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => PortState.CLOSED)));
+    if (answers.includes(PortState.SERVES_DOCUMENT))
+        return PortState.SERVES_DOCUMENT;
+    if (answers.includes(PortState.CONNECTED_NO_ANSWER))
+        return PortState.CONNECTED_NO_ANSWER;
+    return PortState.CLOSED;
+}
 /** Every candidate port serving a document, in ascending order. Never rejects. */
-export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => servesDocument(p)) {
+export async function probeDevServers(ports = [...DEV_SERVER_PORTS], probe = (p) => anyFamilyServes(p)) {
     const results = await Promise.all(ports.map((p) => probe(p).then((up) => (up ? p : null))));
     return results.filter((p) => p !== null).sort((a, b) => a - b);
 }

package/dist/session/last-act.d.ts

@@ -36,6 +36,32 @@ export declare class LastAct {
      * cannot forget to clean up state that was never written.
      */
     markActed(cursor: number, action: string | undefined, mutatedWithin: number | undefined): void;
+    /**
+     * A navigation — by URL or by reload — moves the floor without being an act.
+     *
+     * Reported from the field: an agent reloaded the page, restarted its API, then asserted four
+     * strings that were on the screen. Every clause passed and the verdict came back `contradicted`,
+     * citing hundreds of failed requests, every one against a resource that no longer existed. The
+     * failures were real once; they belonged to the document the reload destroyed.
+     *
+     * The floor was set only by act, act_sequence and act_and_wait, so navigating left it where it was
+     * — or unset, which the caller reads as "judge the whole session". `queryEvents` is journal-backed,
+     * so the whole session is durable history that outlives the page. A navigation has to move this or
+     * every rule reading the window inherits evidence from a page that is gone.
+     *
+     * Deliberately NOT `markActed`: a navigation records no act effect. The "this click did nothing"
+     * check reads an action with no measured mutation, and a reload written there would be accused of
+     * being a dead click.
+     */
+    markNavigated(cursor: number): void;
+    /**
+     * The evaluation floor: the most recent thing that changed the page, whichever kind it was.
+     *
+     * `Math.max` rather than last-writer-wins, because the two are recorded by different tools and
+     * their order is the agent's, not ours: an act then a reload must floor at the reload, and a reload
+     * then an act must floor at the act. Either one going backwards would re-admit the evidence this
+     * exists to exclude.
+     */
     cursor(): number | undefined;
     markSource(source: string | undefined): void;
     source(): string | undefined;

package/dist/session/last-act.js

@@ -1,5 +1,7 @@
 export class LastAct {
     #cursor;
+    /** The cursor of the most recent navigation, kept apart from an act's so neither overwrites it. */
+    #navigated;
     #source;
     #effect;
     /**
@@ -20,8 +22,40 @@ export class LastAct {
         this.#cursor = cursor;
         this.#effect = { action, mutatedWithin };
     }
+    /**
+     * A navigation — by URL or by reload — moves the floor without being an act.
+     *
+     * Reported from the field: an agent reloaded the page, restarted its API, then asserted four
+     * strings that were on the screen. Every clause passed and the verdict came back `contradicted`,
+     * citing hundreds of failed requests, every one against a resource that no longer existed. The
+     * failures were real once; they belonged to the document the reload destroyed.
+     *
+     * The floor was set only by act, act_sequence and act_and_wait, so navigating left it where it was
+     * — or unset, which the caller reads as "judge the whole session". `queryEvents` is journal-backed,
+     * so the whole session is durable history that outlives the page. A navigation has to move this or
+     * every rule reading the window inherits evidence from a page that is gone.
+     *
+     * Deliberately NOT `markActed`: a navigation records no act effect. The "this click did nothing"
+     * check reads an action with no measured mutation, and a reload written there would be accused of
+     * being a dead click.
+     */
+    markNavigated(cursor) {
+        this.#navigated = cursor;
+    }
+    /**
+     * The evaluation floor: the most recent thing that changed the page, whichever kind it was.
+     *
+     * `Math.max` rather than last-writer-wins, because the two are recorded by different tools and
+     * their order is the agent's, not ours: an act then a reload must floor at the reload, and a reload
+     * then an act must floor at the act. Either one going backwards would re-admit the evidence this
+     * exists to exclude.
+     */
     cursor() {
-        return this.#cursor;
+        if (this.#cursor === undefined)
+            return this.#navigated;
+        if (this.#navigated === undefined)
+            return this.#cursor;
+        return Math.max(this.#cursor, this.#navigated);
     }
     markSource(source) {
         this.#source = source;

package/dist/session/live-control-tools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { noteEmptyRead } from '../tools/observed-nothing.js';
-import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, } from '@reticlehq/core';
+import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YIELD_WITHOUT_SESSION_NOTE, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
@@ -9,6 +9,20 @@ import { recoveryFor } from '../tools/error-recovery.js';
 /** Default + ceiling for the readiness wait — keep it short so a truly-missing app fails fast. */
 const WAIT_READY_DEFAULT_MS = 5000;
 const WAIT_READY_MAX_MS = 30000;
+/**
+ * Is this a turn ending with nothing attached, rather than a call about a specific tab?
+ *
+ * Only true when the caller named NO session and none is connected. Ending a turn is a statement
+ * about the agent, not about a tab, so it must not fail merely because no app was ever wired — that
+ * made a call documented as MANDATORY fail in the most common state a daemon is in, and the agents
+ * that hit it stopped calling it and wrote the gap into prose instead.
+ *
+ * Naming a session that does not exist stays an error. That is a mistake about WHICH tab you are
+ * talking to, and swallowing it would hide a real one.
+ */
+function endingTurnWithNothingAttached(deps, id) {
+    return id === undefined && 0 === deps.sessions.count();
+}
 /**
  * Live-control agent tools: the agent's side of the human-in-the-loop control surface.
  *
@@ -29,9 +43,19 @@ export const LIVE_CONTROL_TOOLS = [
             '(calm, terminal) and shows the optional `summary` on the panel. If you are just finishing a ' +
             'turn or waiting on the human, call reticle_session{action:"yield"} instead (revivable). Idempotent.',
         inputSchema: { summary: z.string().optional(), ...sessionIdShape },
-        outputSchema: { ended: z.boolean(), sessionId: z.string() },
+        // `sessionId` is optional because there may genuinely not be one — see the no-op below. An
+        // empty string would read as a real id in a log, which is worse than its absence.
+        outputSchema: {
+            ended: z.boolean(),
+            sessionId: z.string().optional(),
+            note: z.string().optional(),
+        },
         handler: (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const requested = asString(args['sessionId']);
+            if (endingTurnWithNothingAttached(deps, requested)) {
+                return Promise.resolve({ ended: true, note: YIELD_WITHOUT_SESSION_NOTE });
+            }
+            const session = deps.sessions.resolve(requested);
             // One PRESENTER push for the transition; the optional summary rides the same push.
             session.setState(SessionState.ENDED, asString(args['summary']));
             return Promise.resolve({ ended: true, sessionId: session.id });
@@ -55,10 +79,23 @@ export const LIVE_CONTROL_TOOLS = [
                 .describe('For mode:"ask", the question to show the human on the panel.'),
             ...sessionIdShape,
         },
-        outputSchema: { yielded: z.boolean(), mode: z.string(), sessionId: z.string() },
+        outputSchema: {
+            yielded: z.boolean(),
+            mode: z.string(),
+            sessionId: z.string().optional(),
+            note: z.string().optional(),
+        },
         handler: (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const requested = asString(args['sessionId']);
             const ask = asString(args['mode']) === PresenterTone.ASK;
+            if (endingTurnWithNothingAttached(deps, requested)) {
+                return Promise.resolve({
+                    yielded: true,
+                    mode: ask ? PresenterTone.ASK : PresenterTone.WAITING,
+                    note: YIELD_WITHOUT_SESSION_NOTE,
+                });
+            }
+            const session = deps.sessions.resolve(requested);
             const note = asString(args['note']);
             const tone = ask ? PresenterTone.ASK : PresenterTone.WAITING;
             const text = ask && note !== undefined && note.trim().length > 0

package/dist/session/no-session-diagnosis.d.ts

@@ -18,13 +18,22 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
-interface NoSessionFacts {
+export interface NoSessionFacts {
     /** Whether ANY session has connected to this daemon since it booted. */
     everConnected: boolean;
     /** Whether this project has been through `reticle init` (a .reticle.json / projectId is present). */
     initialized: boolean;
     /** Localhost ports with something listening that looks like a dev server. */
     listening: readonly number[];
+    /**
+     * Ports that ACCEPTED a connection and then answered nothing inside the probe budget.
+     *
+     * Not dev servers as far as the probe knows, and absolutely not absent. An SSR framework
+     * compiling its first route lands here every time, and calling that "nothing is listening" told a
+     * reporter to start a Nuxt server that was already serving — advice that would have hit their dev
+     * lock. Named in the message so the reader can tell the two apart.
+     */
+    slowListeners?: readonly number[];
     /** The port this daemon is on — half of the mismatch the old message asked about. */
     port: number;
     /**
@@ -53,6 +62,51 @@ interface NoSessionFacts {
      * no `.reticle.json` at all and is working perfectly.
      */
     projectPort?: number;
+    /**
+     * An app HAS connected on this port for this project before — read from durable state, not from
+     * this process.
+     *
+     * `everConnected` is a per-process boolean, and daemons are short-lived by design: they idle out
+     * and respawn. So a fresh daemon said it had "never seen one" seconds after its predecessor served
+     * a session, and the reader was sent hunting a `.reticle.json` that was never missing. The two
+     * claims mean opposite things — one is evidence about an install, the other is a fact about a
+     * process that booted four seconds ago — and only this one can tell them apart.
+     */
+    previouslyConnected?: boolean;
+    /**
+     * The framework `.reticle.json` declares, when there is one.
+     *
+     * Used to RANK the causes rather than to print a static differential. Nuxt is the case that made
+     * the difference: it does not register a new plugin on HMR, so a dev server older than the wiring
+     * is the single most likely cause there — and `reticle init` says so at install time while the
+     * hint the agent reads hours later never mentioned it.
+     */
+    framework?: string;
+    /**
+     * `.reticle.json` files found OUTSIDE this daemon's directory — a workspace app, a repo root.
+     *
+     * Editors launch MCP servers from wherever they like, and the config then sits under the app
+     * package while the daemon stands in the user's home. The old message read that as "this project
+     * has no SDK" and sent a working install back through `reticle init`.
+     */
+    configsElsewhere?: readonly {
+        directory: string;
+        projectId?: string;
+    }[];
+    /**
+     * Every directory the config search actually checked.
+     *
+     * "There is no `.reticle.json`" is unfalsifiable without it, and the claim was wrong often enough
+     * that a reader deserves to check it.
+     */
+    searchedDirectories?: readonly string[];
+    /**
+     * How long this daemon has been running with no app connected, in milliseconds.
+     *
+     * Present only when the stall clock is active and no app has arrived. Used to surface "the
+     * install never finished" to the user-facing diagnosis rather than only to telemetry.
+     */
+    daemonUpMs?: number;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
@@ -61,4 +115,3 @@ interface NoSessionFacts {
  */
 export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again \u2014 it will appear within a second of the page loading.";
 export declare function diagnoseNoSession(facts: NoSessionFacts): string;
-export {};