@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { ReticleCommand } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { asNumber, asString } from '@reticlehq/core';
+import { idleMsSchema } from '../../surface/tools/args/numeric-bounds.js';
+/**
+ * Session lifecycle controls. The presenter session begins on the agent's first action and ends
+ * either when the agent ends it (reticle_end_session) or after an idle window — and the human keeps the
+ * panel (with Copy/Export of the run) afterwards. reticle_session lets the AGENT tune that idle window
+ * for the app: raise it for a slow app, lower it for a quick check.
+ */
+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 }.',
+        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.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+        },
+        outputSchema: {
+            applied: z.boolean(),
+            idleEndMs: z.number().optional(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const idleEndMs = asNumber(args['idleEndMs']);
+            // Tune BOTH sides: the browser's foreground idle timer AND the server reaper (the throttle-proof
+            // 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 } : {});
+            if (!res.ok)
+                throw new Error(res.error ?? 'session config failed');
+            return res.result ?? { applied: true };
+        },
+    },
+];

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

@@ -0,0 +1,279 @@
+import type { WebSocket } from 'ws';
+import { type ChannelId, type ImpactSnapshot, type ProjectId } from '@reticlehq/core';
+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';
+export type { SessionHealth };
+import { 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';
+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';
+type Clock = () => number;
+/**
+ * One connected browser tab. Owns its socket, a ring buffer of observations, and the
+ * in-flight command map. `clock` is injected so elapsed-time logic stays testable.
+ */
+export declare class Session implements HandshakeFacts {
+    #private;
+    readonly id: string;
+    /**
+     * Stable build-stamped project identity; undefined for SDKs old enough to omit it.
+     *
+     * MINTED HERE. This is one of the two places a projectId enters the daemon with its provenance
+     * intact: the field is `projectId` on a zod-parsed HELLO, so the page said what it is. Every
+     * downstream reader takes the brand from this property rather than re-blessing a string.
+     */
+    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.
+     */
+    artifactRoot: string | undefined;
+    url: string;
+    title: string;
+    adapters: string[];
+    hasCapabilities: boolean;
+    versionSkew?: string;
+    sdkVersion?: string | undefined;
+    captureBodies?: boolean | undefined;
+    channels?: readonly ChannelId[] | undefined;
+    commands?: readonly string[] | undefined;
+    sourceMapping?: boolean | undefined;
+    readonly redactKeys: readonly string[];
+    constructor(hello: HelloMessage, socket: WebSocket, clock: Clock);
+    /** Milliseconds since this session connected — the authoritative buffer clock. */
+    elapsed(): number;
+    /** 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). */
+    lastSeenMs(): number;
+    /**
+     * Record the latest page visibility/focus state from a PAGE_HEALTH event.
+     *
+     * `runtime` is optional so an older SDK (which does not report it) still works — it simply loses
+     * the desktop-specific timeout diagnosis rather than breaking.
+     */
+    applyHealth(hidden: boolean, focused: boolean, runtime?: string, engine?: string, brand?: BrowserBrand): void;
+    /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
+    get runtime(): PageRuntime | undefined;
+    get engine(): string | undefined;
+    /** The browser brand the SDK reported. Absent (never guessed) when the page did not say. */
+    get brand(): BrowserBrand | undefined;
+    /** Throttled if the tab is hidden OR we have not heard from it recently. */
+    throttled(): boolean;
+    /** The attachable health block — single source of truth for the tools. */
+    health(): SessionHealth;
+    info(): SessionInfo;
+    /**
+     * Attached but not answering. A tab can be `connected` with a fresh `lastSeenMs` and still answer
+     * nothing: `lastSeenMs` measures the events the SDK streams, not the commands it replies to. Reuse
+     * and auto-selection read that as health, so `reticle open` handed a wedged tab back forever and
+     * `reticle_session{action:"end"}` — a flag on the record, not on the page — could not help.
+     */
+    unresponsive(): boolean;
+    /** Wall-clock age of the session in milliseconds. */
+    staleMs(): number;
+    /** The document the most recent stamped event was observed under. See `#documentId`. */
+    get currentDocumentId(): string | undefined;
+    /** The edit epoch the most recent stamped event was observed under. See `#editEpoch`. */
+    get currentEditEpoch(): number | undefined;
+    /** Seed/auth precondition failure reason, if any. */
+    setPreconditionFailure(reason: string): void;
+    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;
+    /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
+    pushEvent(event: ReticleEvent, byteSize?: number): void;
+    recordActedRef(ref: string): void;
+    actedLabels(): ReadonlySet<string>;
+    /**
+     * Derive the snapshot-shaped label (`button "Deploy"`) from an act reply and remember it.
+     *
+     * Same shape the interactive snapshot emits, so coverage can match a control the agent drove
+     * against the same control after a re-render gave it a different ref.
+     */
+    private recordActedLabelFrom;
+    actedRefs(): ReadonlySet<string>;
+    noteRateLimited(dropped: number): void;
+    blindSpots(): 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. */
+    ownAmbientCounts(): AmbientCounts;
+    /** Seed the ambient map from the persisted per-app `.reticle/ambient.json` (sharpens across sessions). */
+    seedAmbient(counts: AmbientCounts): void;
+    /**
+     * Attach the durable causal-journal recorder (off by default; wired at session creation). The optional
+     * reader is the query fall-through source — pass it to make `queryEvents` survive buffer eviction.
+     */
+    setJournal(recorder: JournalRecorder, reader?: JournalReader): void;
+    /**
+     * Journal-backed event query — the rule itself lives in `readQueryEvents`, beside the merge and
+     * filter it is made of. This is how "what did action N cause" is answered after the buffer has
+     * dropped the evidence. The sync `eventsSince`/`window` stay for the hot path.
+     */
+    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.
+     */
+    beginAction(tool: string, args: Record<string, unknown>): string;
+    /**
+     * Record one action WITHOUT opening an attribution window — for a tool that returns a verdict but
+     * drives nothing, so no event it observes was caused by it. See `JournalRecorder.recordAction`.
+     */
+    recordAction(tool: string, args: Record<string, unknown>, effect?: unknown): string;
+    /**
+     * How many actions this session has dispatched.
+     *
+     * The counter that mints journal action ids, not a second one — so it equals the journal's own
+     * length, and `reticle_context`'s `step`, whenever this session journals at all.
+     */
+    get actionCount(): number;
+    /** Close the active action window, persisting its action record with the settle outcome. */
+    finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /**
+     * The durable action ledger for this session — the ledger the run context is folded out of.
+     *
+     * `[]` when nothing journals this session (journaling disabled, or an id that is not a safe path
+     * segment). An absent ledger reads as an empty run, never as a missing one: the fold simply has
+     * nothing to say, which is the honest answer.
+     */
+    readJournalActions(): Promise<JournalAction[]>;
+    /** Flush any buffered journal events to disk (call on session end). */
+    flushJournal(): Promise<void>;
+    eventsSince(cursor: number): ReticleEvent[];
+    /**
+     * What the most recent act was: its cursor, its source, and what it changed inside its target.
+     *
+     * Exposed as the object rather than six pass-through methods — act writes to it and observe reads
+     * from it, and the split between those two tool calls is the whole reason it exists.
+     */
+    readonly lastAct: LastAct;
+    /**
+     * What this app still cannot tell Reticle, as of the most recent verdict.
+     *
+     * Lives on the session because that is the scope the question belongs to: "am I done with this
+     * app" is a session question, and a gap closed halfway through must not follow the agent to the
+     * 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
+     * session is REVIVED to ACTIVE. An EXPLICIT end (human/agent reticle_end_session) is terminal and is
+     * never revived here.
+     */
+    markAgentActivity(): void;
+    /** ms since the agent last issued a command against this session (the reaper's idle signal). */
+    agentIdleMs(): number;
+    /** The agent-idle window after which the reaper ends this session. */
+    idleEndMs(): number;
+    /** Tune the idle window (reticle_session). Floored so an agent can't disable the safety net. */
+    setIdleEndMs(ms: number): void;
+    /**
+     * Reaper/disconnect end: terminal like a normal end (pushes PRESENTER ended to the browser, which a
+     * throttled tab still receives) but flagged auto-ended so a returning agent revives it. No-op if
+     * already ended.
+     */
+    autoEnd(text?: string, tone?: PresenterTone): void;
+    eventsInWindow(windowMs: number): ReticleEvent[];
+    /** Buffer honesty: events currently held + cumulative evictions since connect (for false-negative detection). */
+    bufferHealth(): {
+        total: number;
+        dropped: number;
+    };
+    /**
+     * Did the EVENT STORE lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+     * moves for the age and churn evictions that every live page produces continuously. The journal is
+     * the other half of that store, so a durable read that could not reach back to `cursor` lost
+     * exactly what an eviction would have. Both boundaries are INCLUSIVE (`t` is a millisecond many
+     * records share) and an absent `lostThroughT` impeaches every window rather than none — the
+     * conservative direction, both times.
+     */
+    lostSince(cursor: number): boolean;
+    onEvent(listener: (event: ReticleEvent) => void): () => void;
+    onDisconnect(listener: () => void): () => void;
+    /** Send a command to the browser and await its reply (or time out). */
+    command(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<CommandResult>;
+    handleResult(result: CommandResult): void;
+    /** Reject everything still in flight — used on disconnect. */
+    rejectAll(reason: string, replaced?: boolean): void;
+    succeededBy(next: Session): void;
+    /** End this transport without letting a stale socket remove its replacement session. */
+    disconnect(reason: string, replaced?: boolean): void;
+    getState(): SessionState;
+    isPaused(): boolean;
+    isEnded(): boolean;
+    /**
+     * Set the lifecycle state and echo it to the panel in ONE PRESENTER push. The SOLE pusher of
+     * PRESENTER for a transition. Optional `text` rides the same push (e.g. an end-of-session
+     * 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). */
+    pushMessage(text: string): void;
+    /** Queued human notes, cleared as they are read (delivered-once). */
+    drainInbox(): InboxMessage[];
+    /** Diagnostic read of the inbox depth (does not clear). */
+    inboxSize(): number;
+    /** Everything the human has said this session, delivered or not. Never clears. */
+    inboxHistory(): readonly InboxMessage[];
+    /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark does. */
+    pendingMarks(): ReviewMark[];
+    /** Full mark history (pending + resolved), oldest first. */
+    allMarks(): ReviewMark[];
+    /** Count of pending marks — surfaced as the panel badge / a session-health hint. */
+    pendingMarkCount(): number;
+    /** Retire a mark the agent fixed. True on a real pending → resolved transition; false otherwise. */
+    resolveMark(id: string): boolean;
+    /**
+     * Apply a narrowed human control. LiveControl decides the transition; this applies it, so a real
+     * change pushes exactly one PRESENTER command and a no-op pushes none.
+     */
+    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.
+     */
+    pushImpact(read: () => ImpactSnapshot | undefined, immediate?: boolean): void;
+    pushPresenter(state: SessionState, text?: string, tone?: PresenterTone): void;
+    pushNarration(text: string): void;
+    /** The one-time lease block on the first agent command, then undefined forever after. */
+    takeSessionLease(): SessionLease | undefined;
+    /**
+     * Returns a human-readable age warning after SESSION_LEASE.WARN_AFTER_MS (10 min), else undefined.
+     * Spliced onto every session-bound tool result so the agent is passively reminded to clean up
+     * without needing an explicit polling loop.
+     */
+    ageWarning(): string | undefined;
+    /** Wired by SessionManager.add, the one place every session registers. */
+    setViewers(read: () => Session[]): void;
+}