@reticlehq/server 2.14.0 → 3.2.0

package/dist/session/session-replaced.js

@@ -1,29 +0,0 @@
-/**
- * "The page reconnected under the same id" — one sentence, and one way to recognise it.
- *
- * A server-rendered app reconnects its SDK on EVERY full page load, so on an MPA this is the normal
- * consequence of following a link, not a fault. The bridge rejects any command that was in flight
- * when it happens, and a caller that reads that rejection as fatal cannot walk past the first link:
- * reported against `reticle_verify action=crawl`, which died on link one of every Django, Rails and
- * plain-HTML app.
- *
- * The prefix lives here so the producer and the predicate cannot drift apart. This repo has already
- * shipped that exact bug twice — a remedy string restated in a second place, and a redaction name
- * derived two different ways — and both times the halves disagreed silently.
- */
-/** The start of the reason the bridge hands to commands displaced by a reconnect. */
-export const SESSION_REPLACED_PREFIX = 'session replaced by a newer connection';
-/** Build the full reason. The only place this sentence is written. */
-export function sessionReplacedReason(id, url) {
-    return `${SESSION_REPLACED_PREFIX} claiming the same id (${id}) from ${url}`;
-}
-/**
- * Was this failure a reconnect rather than a fault?
- *
- * Accepts the thrown value rather than a string so every call site can hand over whatever it caught
- * without each one re-deriving a message — an `Error`, a bare string, or something else entirely.
- */
-export function isSessionReplacedError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return message.includes(SESSION_REPLACED_PREFIX);
-}

package/dist/session/session-tools.d.ts

@@ -1,8 +0,0 @@
-import type { ToolDef } from '../tools/tools.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 declare const SESSION_TOOLS: ToolDef[];

package/dist/session/session-tools.js

@@ -1,42 +0,0 @@
-import { z } from 'zod';
-import { ReticleCommand } from '@reticlehq/core';
-import { ReticleTool } from '../tools/tool-names.js';
-import { asNumber, asString } from '../tools/tools-helpers.js';
-import { idleMsSchema } from '../tools/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/session/session.d.ts

@@ -1,280 +0,0 @@
-import type { WebSocket } from 'ws';
-import type { ImpactSnapshot } from '@reticlehq/core';
-import { LastAct } from './last-act.js';
-import { GapLedger } from '../honesty/gap-ledger.js';
-import { CaptureLedger } from '../honesty/feature-capture.js';
-import { type PageRuntime } from './command-timeout.js';
-import { type SessionHealth } from './session-health.js';
-export type { SessionHealth };
-import { PresenterTone, SessionState, type BrowserBrand, type CommandResult, type JournalAction, type HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
-import type { JournalReader, JournalRecorder } from '../journal/journal-recorder.js';
-import { type EventQueryOptions } from '../journal/journal-query.js';
-import { type AmbientCounts } from '../journal/ambient.js';
-import { type InboxMessage } from './live-control.js';
-export type { InboxMessage } from './live-control.js';
-import { type ReviewMark } from './review-store.js';
-import { type SessionLease } from './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 {
-    #private;
-    readonly id: string;
-    /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
-    readonly projectId: string | 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;
-    /** Set when the page's SDK version differs from the daemon's (see version-skew.ts). */
-    versionSkew?: string;
-    /** SDK version from HELLO; kept so a remedy can check it applies — see body-capture-remedy.ts. */
-    sdkVersion?: string | undefined;
-    /** Whether the page records network bodies; undefined on an SDK too old to say. See HELLO. */
-    captureBodies?: boolean | undefined;
-    /**
-     * Whether this build stamps `data-reticle-source`, when the build plugin said. See HELLO.
-     * `false` separates "the project turned it off" from "nothing provides one"; undefined is unknown.
-     */
-    sourceMapping?: boolean | undefined;
-    /**
-     * Extra key names this app declared sensitive via `connect({ redact: { keys } })`. Held so the
-     * DRIVEN path can redact them too — a request body the daemon captures from the network stack
-     * never passes through the SDK, so nothing else would.
-     */
-    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;
-    /** 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 ring buffer's events, merged with the durable journal **only when
-     * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by since/until/
-     * actionId. This is how "what did action N cause" is answered after the buffer has dropped the
-     * evidence — the substrate's whole point. The sync `eventsSince`/`window` stay for the hot path.
-     */
-    queryEvents(options: EventQueryOptions): Promise<ReticleEvent[]>;
-    /**
-     * 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 honesty/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 buffer 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.
-     */
-    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 a lifecycle state to the panel with optional human-facing `text`. State changes still flow
-     * through `setState`; an auto-ended session rides a `warn` tone so the panel can shout "agent stopped".
-     */
-    /**
-     * 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;
-}
-/** Re-exported so the public import path (`./session.js`) is unchanged. */
-export { SessionManager } from './session-manager.js';