@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,242 @@
+import { z } from 'zod';
+import { noteEmptyRead } from '../../surface/tools/gaps/observed-nothing.js';
+import { AGENT_ASK_NOTICE, AGENT_WAITING_NOTICE, PresenterTone, SessionState, YIELD_WITHOUT_SESSION_NOTE, } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { asString } from '@reticlehq/core';
+/**
+ * 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/portal/session/no-session-diagnosis.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Turning "no browser session connected" from a dead end into a next action.
+ *
+ * The daemon can tell these 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 './presence/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 bridge refused the last hello on its token.
+     *
+     * The only POSITIVE evidence in this whole structure. Every other fact here is an absence being
+     * interpreted — nothing listening, no config, nobody connected — but only an SDK dials the
+     * bridge, so a refused hello proves the app is running, instrumented, and pointed at this daemon.
+     *
+     * It outranks everything, including `everConnected`. Without it the daemon answered "one WAS
+     * connected to this daemon earlier … the tab was closed, navigated away, or hard-reloaded" about
+     * a page that was being turned away on every attempt, and the reader goes looking at browsers.
+     * `noteClosure(WS_CLOSE_REASON.AUTH_FAILED)` has recorded this for a while and the NEXT ACTION
+     * already read it; the message did not.
+     */
+    authRefused?: 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 diagnosis, and the CODE for the branch that produced it.
+ *
+ * The prose alone is not enough to tell the branches apart afterwards: "restarted the dev server
+ * and it still did not connect" and "never started the app" need opposite fixes and read as 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;
+    detail?: 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;