@reticlehq/server 3.5.0 → 3.7.0

package/dist/portal/session/session-manager.js

@@ -3,8 +3,9 @@ import { notePendingNoSessionReason } from '../../telemetry/tool-refused.js';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
 import { AttachmentHistory } from './presence/attachment-history.js';
-import { openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
-import { SESSION_DISCONNECTED_REASON } from './facts/session-replaced.js';
+import { claimedSessionOf, openedBeforeDeparture, pickDocumentSuccessor, } from './session-successor.js';
+import { SESSION_DISCONNECTED_REASON, SESSION_PARKED_REASON } from './facts/session-replaced.js';
+import { isErrorDocument } from './session-info.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
     if (url === undefined)
@@ -43,19 +44,31 @@ function scopeSessions(sessions, scope) {
  * reader goes looking at their app instead of at the scope. Name what IS connected and how to
  * target it: both facts are already in hand here.
  */
-function scopeMissError(connected, scope) {
+export function scopeMissError(connected, scope) {
     const who = scope?.projectId !== undefined
         ? `project '${scope.projectId}'`
         : scope?.url !== undefined
             ? `your app at ${scope.url}`
             : 'the active project';
+    const anyUntagged = connected.some((s) => s.projectId === undefined);
+    const anyTagged = connected.some((s) => s.projectId !== undefined);
+    const how = anyUntagged && !anyTagged
+        ? 'with no projectId'
+        : anyUntagged && anyTagged
+            ? 'under a different project or with no projectId'
+            : 'under a different project';
     const listed = connected
-        .map((s) => `'${s.projectId ?? 'untagged'}' (${s.url}, sessionId '${s.id}')`)
+        .map((s) => s.projectId !== undefined
+        ? `'${s.projectId}' (${s.url}, sessionId '${s.id}')`
+        : `(no projectId: the page's connect() carries none) (${s.url}, sessionId '${s.id}')`)
         .join(', ');
-    return (`no browser session for ${who}, but ${String(connected.length)} session(s) ARE connected under a ` +
-        `different project: ${listed}. The daemon scopes to the .reticle.json of the directory it was ` +
-        `started in, so this is a scope mismatch, not a dead app. Pass the sessionId above to target one, ` +
-        `or restart the daemon from that app's directory.`);
+    const advice = anyUntagged
+        ? `Pass the sessionId above to target one, add a projectId to the app's connect() call or ` +
+            `.reticle.json, or restart the daemon from that app's directory.`
+        : `Pass the sessionId above to target one, or restart the daemon from that app's directory.`;
+    return (`no browser session for ${who}, but ${String(connected.length)} session(s) ARE connected ${how}: ` +
+        `${listed}. The daemon scopes to the .reticle.json of the directory it was started in, so ` +
+        `this is a scope mismatch, not a dead app. ${advice}`);
 }
 /**
  * Owns the set of connected browser sessions and the smart auto-selection that resolves which one a
@@ -72,6 +85,8 @@ const MAX_REMEMBERED_CLOSURES = 5;
  * Bounded so a long-lived daemon cannot accumulate one record per tab forever.
  */
 const MAX_TOMBSTONES = 32;
+/** How a leased tab's id begins (`lease-tools.ts` mints them). */
+const LEASE_ID_PREFIX = 'lease-';
 export class SessionManager {
     #sessions = new Map();
     /**
@@ -112,6 +127,8 @@ export class SessionManager {
     }
     add(session) {
         this.#everConnected = true;
+        if (session.projectId !== undefined)
+            this.#connectedProjects.add(session.projectId);
         // Ordering, not lifetime: this is what makes a remembered refusal distinguishable from a live
         // one. Here for the same reason `#everConnected` is — `add` is the one method every path that
         // registers a session goes through.
@@ -144,6 +161,24 @@ export class SessionManager {
         const scope = driven.projectId === undefined ? { url: driven.url } : { projectId: driven.projectId };
         return scopeSessions([...this.#sessions.values()], scope).filter((s) => s !== driven);
     }
+    /**
+     * Close a window's connection and refuse its id until the daemon restarts.
+     *
+     * Reported from a Tauri app whose hidden windows kept reconnecting: ending the session only ended
+     * the presenter, so the window came straight back. A reload keeps its id (sessionStorage), so the
+     * id is what stays parked; the 1008 close tells the SDK not to retry. Its tombstone goes too, so a
+     * call naming it is refused rather than handed a sibling window.
+     */
+    park(session) {
+        this.#parked.add(session.id);
+        session.disconnect(SESSION_PARKED_REASON);
+        this.remove(session);
+        this.#tombstones.delete(session.id);
+    }
+    isParked(sessionId) {
+        return this.#parked.has(sessionId);
+    }
+    #parked = new Set();
     remove(session) {
         if (this.#sessions.get(session.id) !== session)
             return false;
@@ -164,10 +199,13 @@ export class SessionManager {
         this.#siblingsAtDeparture.set(session.id, new Set([...this.#sessions.values()]
             .filter((s) => s !== session && openedBeforeDeparture(s, session))
             .map((s) => s.id)));
+        const departedTo = session.departedTo();
         this.#tombstones.set(session.id, {
             id: session.id,
             url: session.url,
             ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+            // Where the tab was seen heading, kept off `url`: successor matching needs the old origin.
+            ...(departedTo === undefined ? {} : { departedTo }),
         });
         while (this.#tombstones.size > MAX_TOMBSTONES) {
             const oldest = this.#tombstones.keys().next().value;
@@ -222,6 +260,15 @@ export class SessionManager {
     all() {
         return [...this.#sessions.values()];
     }
+    /**
+     * The connected sessions an id-less call may consider: the active project's, when one is set.
+     *
+     * The same set `resolve()` chooses from, so a caller that falls back from a refused resolution
+     * (an id-less yield) never reaches a tab the project scope would never have handed it.
+     */
+    inScope() {
+        return scopeSessions(this.all(), this.#defaultScope);
+    }
     count() {
         return this.#sessions.size;
     }
@@ -322,9 +369,20 @@ export class SessionManager {
     }
     /** Whether any session has connected since this daemon booted — half the diagnosis. */
     #everConnected = false;
+    /**
+     * Which projects have registered a session in this process.
+     *
+     * `#everConnected` is one bit for the whole daemon. A second project asking "has anything
+     * connected" was answered about the first. The set is the same fact, per project.
+     */
+    #connectedProjects = new Set();
     everConnected() {
         return this.#everConnected;
     }
+    /** Whether a session for this project has registered since boot. An unknown id has not. */
+    everConnectedTo(projectId) {
+        return this.#connectedProjects.has(projectId);
+    }
     /**
      * Record a bridge-initiated close so `resolve` can explain a session that vanished.
      *
@@ -385,6 +443,24 @@ export class SessionManager {
             last = record;
         return last;
     }
+    /**
+     * The most recent departed session for one project.
+     *
+     * `lastKnown` is the newest tombstone of any project. A shared daemon that quoted it to every
+     * caller told the second project to reopen the first project's tab.
+     */
+    lastKnownFor(projectId) {
+        let last;
+        for (const record of this.#tombstones.values()) {
+            if (record.projectId === projectId)
+                last = record;
+        }
+        return last;
+    }
+    /** Every departed session's URL, oldest first. The port scan has to see all of them, not only the newest. */
+    tombstoneUrls() {
+        return [...this.#tombstones.values()].map((record) => record.url);
+    }
     /**
      * A dead `sessionId`, answered with what the caller needs to recover — not with an errand.
      *
@@ -410,8 +486,17 @@ export class SessionManager {
                 ' The app is not dialling this daemon; call ' +
                 'reticle_sessions for the diagnosis rather than retrying this call.');
         }
-        const named = live.map((s) => `'${s.id}' (${s.url})`).join(', ');
-        return (`no connected session with id '${sessionId}'. Connected right now: ${named}. ` +
+        // A leased tab belongs to whoever holds the lease: naming it, and the page it is on, told one
+        // agent what every other agent on this daemon was doing. Only the app's own tabs are offered.
+        const own = live.filter((s) => claimedSessionOf(s.url) === undefined);
+        const ended = sessionId.startsWith(LEASE_ID_PREFIX)
+            ? ` Lease '${sessionId}' has ended (it expired or was released); lease a new tab to go on.`
+            : '';
+        if (0 === own.length)
+            return (`no connected session with id '${sessionId}'.${ended} ` +
+                'Omit sessionId to let Reticle scope to your project, or lease a tab of your own.');
+        const named = own.map((s) => `'${s.id}' (${s.url})`).join(', ');
+        return (`no connected session with id '${sessionId}'.${ended} Your app's tabs: ${named}. ` +
             'Retry with one of those, or omit sessionId entirely and let Reticle scope to your project.');
     }
     resolve(sessionId, scope) {
@@ -495,7 +580,9 @@ export class SessionManager {
         // every call auto-targeted the one tab guaranteed to time out.
         const scored = all.map((s) => ({
             s,
-            score: s.unresponsive() ? 2 : s.throttled() ? 1 : 0,
+            // An error document (a dev server's 404 that still mounted the SDK) ranks below any working
+            // page, hidden or not: it is never the app the agent was asked about.
+            score: s.unresponsive() ? 3 : isErrorDocument(s.page) ? 2 : s.throttled() ? 1 : 0,
             ms: s.lastSeenMs(),
         }));
         const bestScore = Math.min(...scored.map((x) => x.score));

package/dist/portal/session/session-reaper.js

@@ -101,7 +101,10 @@ export function endAllSessions(sessions, reason) {
     for (const session of sessions.all()) {
         if (session.isEnded())
             continue;
-        endWithUndelivered(session, reason, PresenterTone.WARN);
+        // WAITING, not WARN: a dropped MCP connection is far more often an agent that finished its turn
+        // than one that crashed, and the daemon cannot tell them apart. Red at the end of every
+        // completed Harness or agent run read as an error the run never had.
+        endWithUndelivered(session, reason, PresenterTone.WAITING);
         ended.push(session.id);
     }
     if (ended.length > 0)

package/dist/portal/session/session-successor.d.ts

@@ -14,11 +14,24 @@ export interface SessionIdentity {
     id: string;
     url: string;
     projectId?: string;
+    /**
+     * Where the tab was seen heading just before it went away (#1256). Separate from `url` — the
+     * old origin — because successor matching must match on where the tab WAS.
+     */
+    departedTo?: string;
 }
 export interface SuccessorClock {
     now: () => number;
     sleep: (ms: number) => Promise<void>;
 }
+/**
+ * The session a URL explicitly CLAIMS to be, via `__reticle_session`.
+ *
+ * A leased tab carries this marker so the pool can find the context it opened, and an app can set it
+ * deliberately so a battery addresses a known id. Either way it is a claim of identity, not a
+ * coincidence of origin — which is what makes it the right thing to gate succession on.
+ */
+export declare function claimedSessionOf(url: string): string | undefined;
 /**
  * The one live session that can honestly take over from `departed`, or undefined when none or more
  * than one could.

package/dist/portal/session/session-successor.js

@@ -30,7 +30,7 @@ function originOf(url) {
  * deliberately so a battery addresses a known id. Either way it is a claim of identity, not a
  * coincidence of origin — which is what makes it the right thing to gate succession on.
  */
-function claimedSessionOf(url) {
+export function claimedSessionOf(url) {
     try {
         return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
     }

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ReticleCommand } from '@reticlehq/core';
+import { HudCorner, HudVisibility, ReticleCommand } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { idleMsSchema } from '../../surface/tools/args/numeric-bounds.js';
@@ -12,11 +12,17 @@ import { idleMsSchema } from '../../surface/tools/args/numeric-bounds.js';
 export const SESSION_TOOLS = [
     {
         name: ReticleTool.SESSION_TUNE,
-        description: 'Tune the presenter session for this app. { idleEndMs } sets how long the session stays open after you go quiet before the panel shows the human you are WAITING (your turn). Default 5min — the SLOW backstop; signal handback IMMEDIATELY with reticle_session{action:"yield"} instead of waiting for this. Lower it for snappier auto-handback, raise it for a slow app where long gaps between your tool calls are normal. Enforced SERVER-SIDE (immune to background-tab throttling); it also fires if you (the MCP client) disconnect — so a forgotten or crashed session never leaves the HUD reading "live". Going quiet then acting again revives the session automatically. Returns { applied, idleEndMs }.',
+        description: 'Tune the presenter session for this app. { idleEndMs } sets how long the session stays open after you go quiet before the panel shows the human you are WAITING (your turn). Default 5min — the SLOW backstop; signal handback IMMEDIATELY with reticle_session{action:"yield"} instead of waiting for this. Lower it for snappier auto-handback, raise it for a slow app where long gaps between your tool calls are normal. Enforced SERVER-SIDE (immune to background-tab throttling); it also fires if you (the MCP client) disconnect — so a forgotten or crashed session never leaves the HUD reading "live". Going quiet then acting again revives the session automatically. Also moves the HUD out of your way: { hud: "hidden" | "shown" | "removed" } (removed lasts until the page reloads), or a corner to move it to: { hud: "top-left" }. Use it when the HUD covers a control you must test; say so in your report. Returns { applied, idleEndMs, hud }.',
         inputSchema: {
             idleEndMs: idleMsSchema
                 .optional()
                 .describe('Idle window in milliseconds after which the panel shows WAITING (your turn). Default: 300000 (5 min) — the slow backstop; prefer reticle_session{action:"yield"}. Raise for slow apps.'),
+            hud: z
+                .enum([
+                ...Object.values(HudVisibility),
+                ...Object.values(HudCorner),
+            ])
+                .optional(),
             sessionId: z
                 .string()
                 .optional()
@@ -25,6 +31,7 @@ export const SESSION_TOOLS = [
         outputSchema: {
             applied: z.boolean(),
             idleEndMs: z.number().optional(),
+            hud: z.array(z.string()).optional(),
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
@@ -33,9 +40,25 @@ export const SESSION_TOOLS = [
             // authority), so the agent-set window is honored even when the tab is backgrounded.
             if (idleEndMs !== undefined)
                 session.setIdleEndMs(idleEndMs);
-            const res = await session.command(ReticleCommand.SESSION_CONFIG, idleEndMs !== undefined ? { idleEndMs } : {});
+            // One parameter on the wire to the agent, two to the page: a corner moves it, anything else
+            // shows, hides or removes it.
+            const asked = asString(args['hud']);
+            const isCorner = Object.values(HudCorner).includes(asked);
+            const hud = isCorner ? undefined : asked;
+            const corner = isCorner ? asked : undefined;
+            const res = await session.command(ReticleCommand.SESSION_CONFIG, {
+                ...(idleEndMs === undefined ? {} : { idleEndMs }),
+                ...(hud === undefined ? {} : { hud }),
+                ...(corner === undefined ? {} : { corner }),
+            });
             if (!res.ok)
                 throw new Error(res.error ?? 'session config failed');
+            // Asked to move the HUD and the page says nothing about it: an SDK older than this daemon, or
+            // no HUD mounted. Reported, never `applied: true`: an agent told the HUD moved would test a
+            // control it is still covering.
+            const applied = res.result?.hud;
+            if ((hud !== undefined || corner !== undefined) && !Array.isArray(applied))
+                throw new Error('the page did not apply `hud`: its Reticle SDK predates it, or no HUD is mounted. Update the SDK (npx @reticlehq/server update) or test with the HUD where it is.');
             return res.result ?? { applied: true };
         },
     },

package/dist/portal/session/session.d.ts

@@ -1,13 +1,13 @@
 import type { WebSocket } from 'ws';
 import { type ChannelId, type ImpactSnapshot, type ProjectId } from '@reticlehq/core';
+import { type NarrationBy } from './narration-args.js';
 import type { HandshakeFacts } from './facts/handshake-facts.js';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '@reticlehq/engine/evidence/gap-ledger.js';
-import { CaptureLedger } from '../../surface/tools/feature-capture.js';
 import { type PageRuntime } from './timing/command-timeout.js';
-import { type SessionHealth } from './session-health.js';
+import { readHealthEvent, type SessionHealth } from './session-health.js';
 export type { SessionHealth };
-import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type JournalWriteLoss, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+import { ReticleCommand, PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type JournalWriteLoss, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
 import type { JournalReader, JournalRecorder } from '../../memory/journal/journal-recorder.js';
 import { type EventQueryOptions } from '../../memory/journal/journal-query.js';
 import { type AmbientCounts } from '@reticlehq/engine/window/ambient.js';
@@ -15,8 +15,8 @@ import { type InboxMessage } from './human/live-control.js';
 export type { InboxMessage } from './human/live-control.js';
 import { type ReviewMark } from './human/review-store.js';
 import { type SessionLease } from './presence/session-lease.js';
-import type { SessionInfo } from './session-info.js';
 export type { SessionInfo } from './session-info.js';
+import { type SessionInfo } from './session-info.js';
 type Clock = () => number;
 /**
  * One connected browser tab. Owns its socket, a ring buffer of observations, and the
@@ -35,13 +35,8 @@ export declare class Session implements HandshakeFacts {
     readonly projectId: ProjectId | undefined;
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
-     *
-     * Stamped once when the session is created, from the project it declared in HELLO, rather than
-     * resolved per call: the answer cannot change while the tab is connected, and resolving it once
-     * means every counter that fires for this session agrees about where it goes.
-     *
-     * Undefined when nothing could name a project — the caller then falls back to the daemon's own
-     * root, which is what every counter did unconditionally before this existed.
+     * Stamped once, from the project it declared in HELLO, so every counter agrees where it goes.
+     * Undefined when nothing could name a project: callers fall back to the daemon's own root.
      */
     artifactRoot: string | undefined;
     /**
@@ -60,9 +55,14 @@ export declare class Session implements HandshakeFacts {
     commands?: readonly string[] | undefined;
     sourceMapping?: boolean | undefined;
     readonly redactKeys: readonly string[];
+    /** The desktop window this is and its document's HTTP status, merged from every PAGE_HEALTH. */
+    readonly page: ReturnType<typeof readHealthEvent>['page'];
+    /** The newest journal action: a verdict's screenshot names it, so the run pairs it with its check. */
+    lastActionId: string | undefined;
     constructor(hello: HelloMessage, socket: WebSocket, clock: Clock);
     /** Milliseconds since this session connected — the authoritative buffer clock. */
     elapsed(): number;
+    departedTo(): string | undefined;
     /** Mark that the SDK was just heard from. Called on every inbound message. */
     touch(): void;
     /** ms since the SDK last reported anything (distinct from elapsed-since-connect). */
@@ -104,7 +104,7 @@ export declare class Session implements HandshakeFacts {
     preconditionFailure(): string | undefined;
     /** What the rules that decide a verdict need from the daemon. See daemon-answers.ts. */
     readonly note: typeof import("../../log.js").log;
-    readonly keepCallerContext: typeof import("../../trace.js").bindSpanContext;
+    readonly keepCallerContext: <A extends unknown[]>(fn: (...args: A) => void) => ((...args: A) => void);
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
@@ -121,7 +121,7 @@ export declare class Session implements HandshakeFacts {
     provedLabels(): ReadonlySet<string>;
     actedRefs(): ReadonlySet<string>;
     noteRateLimited(dropped: number): void;
-    blindSpots(): Readonly<Record<string, number>>;
+    blindSpots(since?: number): Readonly<Record<string, number>>;
     /** Learned ambient-churn counts (PredicateSession hook the settle oracle reads). */
     ambientCounts(): AmbientCounts;
     /** Only what THIS session observed — what teardown accumulates onto the persisted map. */
@@ -141,10 +141,7 @@ export declare class Session implements HandshakeFacts {
     queryEvents(options: EventQueryOptions): Promise<ReticleEvent[]>;
     /** What the durable ledger could not WRITE — see `readJournalWriteLoss` for the rule and why. */
     journalWriteLoss(): Promise<JournalWriteLoss | undefined>;
-    /**
-     * Open an action-attribution window: events observed until finishAction attribute to the returned
-     * action id. Ids are minted independently of command correlation ids so the journal is self-contained.
-     */
+    /** Open an attribution window: events until finishAction carry the returned (journal-own) id. */
     beginAction(tool: string, args: Record<string, unknown>): string;
     /**
      * Record one action WITHOUT opening an attribution window — for a tool that returns a verdict but
@@ -186,11 +183,6 @@ export declare class Session implements HandshakeFacts {
      * end of it.
      */
     readonly gaps: GapLedger;
-    /**
-     * The read-only calls the journal does not keep, so "was `reticle_context` ever called" has
-     * something to fold. See surface/tools/feature-capture.ts — it is the only state that instrument adds.
-     */
-    readonly capture: CaptureLedger;
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
      * If the reaper had auto-ended the session, a fresh command means the agent is alive again, so the
@@ -242,9 +234,9 @@ export declare class Session implements HandshakeFacts {
      * summary) so a transition never emits two PRESENTER commands.
      */
     setState(next: SessionState, text?: string, tone?: PresenterTone): void;
-    /** Push a human note onto the inbox (see LiveControl). */
+    /** Push a human note onto the inbox (see LiveControl); the HUD shows it as sent. */
     pushMessage(text: string): void;
-    /** Queued human notes, cleared as they are read (delivered-once). */
+    /** Queued human notes, cleared as they are read (delivered-once); the HUD shows them as seen. */
     drainInbox(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */
     inboxSize(): number;
@@ -264,15 +256,15 @@ export declare class Session implements HandshakeFacts {
      */
     applyHumanControl(data: HumanControlData): void;
     /**
-     * Push the impact record to this tab's HUD.
-     *
-     * Debounced: the record changes on every tool call, and the panel does not need 200 frames to
-     * show a counter going up. The LAST state always lands, because the timer re-reads the store
-     * when it fires rather than capturing a snapshot when it was scheduled.
+     * Push the impact record to this tab's HUD. Debounced (a counter needs no 200 frames); the LAST
+     * state always lands, because the timer re-reads the store when it fires.
      */
     pushImpact(read: () => ImpactSnapshot | undefined, immediate?: boolean): void;
     pushPresenter(state: SessionState, text?: string, tone?: PresenterTone): void;
-    pushNarration(text: string): void;
+    /** `mirror: false` for a notice about THIS page (its SDK is behind), which every tab says itself. */
+    pushNarration(text: string, mirror?: boolean, by?: NarrationBy): void;
+    /** A HUD replay's progress, or the Harness's drive plan: pictures the HUD redraws as they change. */
+    pushView(name: typeof ReticleCommand.FLOW_PROGRESS | typeof ReticleCommand.PLAN, args: object): void;
     /** The one-time lease block on the first agent command, then undefined forever after. */
     takeSessionLease(): SessionLease | undefined;
     /**