@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,147 +0,0 @@
-/**
- * Which of the usual dev-server ports have something listening on them.
- *
- * The one fact that separates "the app is not running" from "the app is running and never dialled
- * us" — the difference between two completely different next actions for the agent, which the
- * no-session message could not tell apart before. See no-session-diagnosis.ts.
- *
- * Kept out of the hot path: `SessionManager.resolve` is synchronous and runs on every tool call, so
- * 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.
- */
-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, 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.
- *
- * 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 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?
- *
- * A bare TCP connect reported macOS ControlCenter (AirPlay Receiver, on by default on every Mac,
- * 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 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 ? PortState.SERVES_DOCUMENT : PortState.CLOSED);
-        });
-        req.once('socket', (socket) => {
-            socket.once('connect', () => {
-                connected = true;
-            });
-        });
-        req.once('timeout', () => {
-            req.destroy();
-            resolve(connected ? PortState.CONNECTED_NO_ANSWER : PortState.CLOSED);
-        });
-        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.
- */
-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) => 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/live-control-tools.d.ts

@@ -1,15 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-/**
- * Live-control agent tools: the agent's side of the human-in-the-loop control surface.
- *
- * - reticle_end_session: terminal stop. Sets state `ended` and syncs the panel (PRESENTER) with an
- * optional summary. Idempotent — ending an already-ended session is a safe no-op.
- * - reticle_resume: clears a human pause. Sets state `active` and syncs the panel.
- * - reticle_messages: explicit poll — drains and returns the queued human notes.
- *
- * State changes go through `setState`, which echoes the state to the panel in a SINGLE PRESENTER
- * push (optionally carrying human-facing text, e.g. the end summary) — a transition never emits two
- * PRESENTER commands. No clock is read here — inbox stamps were assigned by the session's injected
- * elapsed clock at enqueue time.
- */
-export declare const LIVE_CONTROL_TOOLS: ToolDef[];

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

@@ -1,242 +0,0 @@
-import { z } from 'zod';
-import { noteEmptyRead } from '../tools/observed-nothing.js';
-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 { asString } from '../tools/tools-helpers.js';
-/**
- * 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.
- *
- * - reticle_end_session: terminal stop. Sets state `ended` and syncs the panel (PRESENTER) with an
- * optional summary. Idempotent — ending an already-ended session is a safe no-op.
- * - reticle_resume: clears a human pause. Sets state `active` and syncs the panel.
- * - reticle_messages: explicit poll — drains and returns the queued human notes.
- *
- * State changes go through `setState`, which echoes the state to the panel in a SINGLE PRESENTER
- * push (optionally carrying human-facing text, e.g. the end summary) — a transition never emits two
- * PRESENTER commands. No clock is read here — inbox stamps were assigned by the session's injected
- * elapsed clock at enqueue time.
- */
-export const LIVE_CONTROL_TOOLS = [
-    {
-        name: ReticleTool.END_SESSION,
-        description: 'End this session for good — use ONLY when the whole task is complete. Sets state "ended" ' +
-            '(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 },
-        // `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 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 });
-        },
-    },
-    {
-        name: ReticleTool.YIELD,
-        description: 'MANDATORY before you stop driving and hand control back to the human — call this whenever you ' +
-            'finish a turn or need to wait on them, so the panel never falsely shows the agent as live. ' +
-            'mode:"waiting" = you are done responding and will continue on their next message. ' +
-            'mode:"ask" = you are blocked and need an answer first; put the question in `note` so it shows ' +
-            'on the panel. The session is REVIVED automatically on your next tool call, so you never need to ' +
-            'reopen it. Use reticle_session{action:"end"} instead only when the whole task is truly complete.',
-        inputSchema: {
-            mode: z
-                .enum([PresenterTone.WAITING, PresenterTone.ASK])
-                .describe('"waiting" = turn done, will resume; "ask" = blocked, need the human to answer.'),
-            note: z
-                .string()
-                .optional()
-                .describe('For mode:"ask", the question to show the human on the panel.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            yielded: z.boolean(),
-            mode: z.string(),
-            sessionId: z.string().optional(),
-            note: z.string().optional(),
-        },
-        handler: (deps, args) => {
-            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
-                ? `${AGENT_ASK_NOTICE}: ${note.trim()}`
-                : ask
-                    ? AGENT_ASK_NOTICE
-                    : AGENT_WAITING_NOTICE;
-            // autoEnd = revivable end: the panel reflects the handoff now, the agent's next call revives it.
-            session.autoEnd(text, tone);
-            return Promise.resolve({
-                yielded: true,
-                mode: ask ? PresenterTone.ASK : PresenterTone.WAITING,
-                sessionId: session.id,
-            });
-        },
-    },
-    {
-        name: ReticleTool.RESUME,
-        description: 'Clear a human pause and resume driving the page. Sets state "active" and syncs the panel ' +
-            '(PRESENTER). Call after you have addressed the human guidance returned by a paused reticle_act.',
-        inputSchema: { ...sessionIdShape },
-        outputSchema: { ok: z.boolean() },
-        handler: (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
-            // setState echoes ACTIVE to the panel in a single PRESENTER push.
-            session.setState(SessionState.ACTIVE);
-            return Promise.resolve({ ok: true });
-        },
-    },
-    {
-        name: ReticleTool.MESSAGES,
-        description: 'Drain and return any messages the human queued from the panel since the last poll. Use to ' +
-            'explicitly check for human guidance without acting.',
-        inputSchema: { ...sessionIdShape },
-        outputSchema: {
-            messages: z.array(z.unknown()),
-            delivered: z
-                .array(z.unknown())
-                .optional()
-                .describe('Present ONLY when this poll found nothing new but the human HAS spoken this session: everything they said, including what was already handed to you inline on an earlier tool result. An empty `messages` never means silence.'),
-        },
-        handler: (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
-            const messages = session.drainInbox();
-            if (messages.length > 0)
-                return Promise.resolve({ messages });
-            // Nothing NEW is not the same as nothing said. The inbox has two consumers — this poll and the
-            // control envelope spliced onto every tool result — and delivery is destructive, so a message
-            // handed over inline moments ago left this call reporting an empty queue with a note that read
-            // as "the human has said nothing". Reported from the field, from both ends: the agent believed
-            // it, and the person who typed the message got silence with no sign it had been seen.
-            const history = session.inboxHistory();
-            if (history.length > 0) {
-                return Promise.resolve({
-                    messages,
-                    delivered: [...history],
-                    note: `nothing NEW since your last poll — but the human has sent ` +
-                        `${String(history.length)} message(s) this session, listed in \`delivered\`. They were ` +
-                        `handed to you inline on an earlier tool result, which is why this queue is empty. An ` +
-                        `empty \`messages\` never means the human has said nothing.`,
-                });
-            }
-            // An empty inbox and a panel that is not wired both return `[]`. The first means the human has
-            // said nothing; the second means an agent is waiting on a channel that does not exist.
-            return Promise.resolve(noteEmptyRead({ messages }, 'messages', {
-                noun: 'messages from the human since the last poll',
-                // The HUD no longer carries a text input — two boxes on one screen, and nothing said which
-                // was which. Nothing in the shipped product produces one of these today, so an empty queue
-                // here is structural rather than a quiet human, and a caller polling it deserves to know
-                // that rather than infer silence.
-                caveat: 'the HUD has no message box, so nothing currently sends on this channel — an empty ' +
-                    'queue here is not evidence about what the human thinks',
-            }));
-        },
-    },
-    {
-        name: ReticleTool.REVIEW,
-        description: 'List the mistakes the human pinned to elements on the running page (the "annotate the bug ' +
-            'where you see it" loop), then resolve each once you have fixed it. Each pending mark carries ' +
-            'the human note, the element label, and — when the framework stamped it — the source file:line ' +
-            'to open, plus a ready-to-act `fix` hint. After applying a fix, call again with ' +
-            '`{ resolve: "<id>" }` to retire that mark. Reading does NOT consume a mark, so you can list, ' +
-            'fix, verify, then resolve.',
-        inputSchema: {
-            resolve: z
-                .string()
-                .optional()
-                .describe('A mark id (e.g. "m1") to retire after you have fixed it. Omit to just list.'),
-            all: z
-                .boolean()
-                .optional()
-                .describe('Include already-resolved marks in the listing (default: pending only).'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            marks: z.array(z.unknown()),
-            pendingCount: z.number(),
-            resolved: z.boolean().optional(),
-            resolvedNote: z
-                .string()
-                .optional()
-                .describe('The note on the mark that was actually retired. CHECK IT against the mark you meant to resolve: a bare `resolved:true` cannot tell you it closed the right one, and ids are only meaningful while the session that issued them lives.'),
-        },
-        handler: (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
-            const resolveId = asString(args['resolve']);
-            let resolved;
-            let resolvedNote;
-            if (resolveId !== undefined) {
-                // Grab the note BEFORE retiring it so we can close the loop visually for the human.
-                const mark = session.allMarks().find((m) => m.id === resolveId);
-                resolved = session.resolveMark(resolveId);
-                if (resolved && mark !== undefined) {
-                    // Echoed back to the CALLER too, not only to the panel. A bare `resolved:true` is equally
-                    // consistent with "I retired the bug you fixed" and "I retired somebody else's", and an
-                    // agent hit exactly that — it closed a mark the human had recorded minutes later while
-                    // the two it had actually fixed vanished with no record.
-                    resolvedNote = mark.note;
-                    // The human watching the panel sees their flagged bug get marked fixed (fire-and-forget).
-                    session.pushNarration(`✓ fixed: ${mark.note}`);
-                }
-            }
-            const source = true === args['all'] ? session.allMarks() : session.pendingMarks();
-            const marks = source.map((m) => ({ ...m, fix: buildFixHint(m) }));
-            const out = {
-                marks,
-                pendingCount: session.pendingMarkCount(),
-            };
-            if (resolved !== undefined)
-                out.resolved = resolved;
-            if (resolvedNote !== undefined)
-                out.resolvedNote = resolvedNote;
-            return Promise.resolve(out);
-        },
-    },
-];
-/**
- * The single actionable next-move for a pending mark: point the agent at the source (or the element
- * label when no file:line was stamped), echo the human's note, and name the resolve call. Keeping
- * the recovery hint here means the agent is never left guessing what to do with a mark.
- */
-function buildFixHint(m) {
-    const where = m.source !== undefined
-        ? `Open ${m.source.file}:${String(m.source.line)}`
-        : m.label !== undefined
-            ? `Find the "${m.label}" element`
-            : 'Find the flagged element';
-    return `${where} and fix: ${m.note}. Then call reticle_session { action: "review", resolve: "${m.id}" }.`;
-}

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

@@ -1,176 +0,0 @@
-/**
- * Turning "no browser session connected" from a dead end into a next action.
- *
- * This is the most consequential sentence in the product. Most sessions never call a Reticle tool at
- * all, and of the ones that do, a large share make exactly ONE call — usually `reticle_sessions` —
- * and stop. Almost none of those ever touched a browser, and this is the session error they hit. The
- * agent asks whether anything is connected, is told no, and leaves.
- *
- * The old message asked the agent to check two things it cannot see from where it stands ("is your
- * app running with the SDK enabled?", "does it point at this port?"). The daemon can actually tell
- * the three cases apart, and each has a different, concrete fix:
- *
- *   - a session was here and went away    -> the tab closed or reloaded; reopen it
- *   - something is listening, never dialled, project not wired -> run `reticle init` in THAT app
- *   - something is listening, project wired -> port mismatch or a stale build; restart the dev server
- *   - nothing is listening anywhere       -> there is no app running; start it
- *
- * 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.
- */
-import { NoSessionReason } from '@reticlehq/core/telemetry';
-import { type LeaseBrowserState } from './lease-availability.js';
-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;
-    /**
-     * What the caller knows about the Chromium a lease would drive.
-     *
-     * Every branch below offers `reticle_lease` as the way not to wait for a human. When that browser
-     * is missing or at a revision this Playwright will not use, the offer is the one thing that cannot
-     * help — and it was being made by the same output that had just diagnosed exactly that. Optional:
-     * absent means the caller did not probe, which is not evidence the browser is missing.
-     */
-    leaseBrowser?: LeaseBrowserState | undefined;
-    /**
-     * The directory `initialized` was decided in, named in the message when it is known.
-     *
-     * "There is no `.reticle.json`" is only ever true OF A DIRECTORY, and a reader who cannot see
-     * which one has to guess whether the claim is about their app at all — reported by someone whose
-     * app lives in `src/admin` while the daemon stands at the repo root.
-     */
-    directory?: string;
-    /**
-     * This daemon has reaped at least one EXPIRED pooled lease.
-     *
-     * Deliberately not "the session that just vanished was that lease" — nothing knows that. It is
-     * evidence, not proof, and the message below is worded accordingly.
-     */
-    leaseExpired?: boolean;
-    /**
-     * The port `.reticle.json` configures for this project, when there is one.
-     *
-     * Half of a mismatch the daemon can settle rather than hint at: it knows the port it bound, and
-     * this is the number the app's SDK was built to dial. `doctor` already compares them and prints a
-     * precise line; the agent reading `why` was getting "check that the port matches" instead.
-     *
-     * Absent means no config, or one without a port, which is NOT a mismatch: a plugin-wired app has
-     * 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;
-    /**
-     * Well-known Reticle ports other than `port` that currently accept a connection.
-     *
-     * Remaining half of #261. We cannot see an SDK dialling a port we are not on, but we can see that
-     * a well-known Reticle port has a listener. That is an observation: somebody else's daemon, another
-     * project, and an unrelated process all look the same from here. The sentence that reports it
-     * names the ports and refuses the conclusion. Absent or empty means nothing else was listening,
-     * which is the common case and must not gain a paragraph.
-     */
-    siblingListeners?: readonly number[];
-    /**
-     * The URL of the session that most recently disappeared, when the tombstone still holds it.
-     *
-     * A route that 500s tears the page down and the SDK never reconnects. `everConnected` already
-     * knew a tab HAD been here; without this the diagnosis could not say WHERE, so a server error
-     * and a closed tab read as the same empty list (#808). Absent when nothing was ever connected,
-     * or the ring has forgotten — inventing a URL is worse than the silence this exists to end.
-     */
-    lastKnownUrl?: string;
-}
-/**
- * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session
- * recovery: a message that already carries its own next action must not be handed a second, more
- * generic one that contradicts it.
- */
-export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again \u2014 it will appear within a second of the page loading.";
-/**
- * The last URL a connected session was on when it disappeared without a successor HELLO.
- *
- * Shared with the observation-lost verdict so the two surfaces cannot drift into naming different
- * routes for the same teardown (#808).
- */
-export declare function pageTornDownWhileOn(url: string): string;
-/**
- * The diagnosis, and the CODE for the branch that produced it.
- *
- * The prose has always been well-ranked and it was the only output, so the population that installs
- * Reticle and never gets an app connected arrived as one undifferentiated silence. "Restarted the
- * dev server and it still did not connect" and "never started the app" need opposite fixes and were
- * the same absence (#615).
- *
- * One function returning both, rather than a classifier beside the writer. A reason computed
- * separately would drift from the sentence the user is actually shown, and then the metric would
- * describe a diagnosis nobody received.
- */
-export declare function explainNoSession(facts: NoSessionFacts): {
-    reason: NoSessionReason;
-    message: string;
-};
-/**
- * The message alone, for the callers that render it.
- *
- * Kept as the narrow surface it always was: most callers want the sentence, and handing them the
- * pair would spread a telemetry concern across every error path that shows a user this text.
- */
-export declare function diagnoseNoSession(facts: NoSessionFacts): string;