@reticlehq/server 2.11.0 → 2.12.0

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

@@ -0,0 +1,37 @@
+/**
+ * The session that took over after a full-document navigation.
+ *
+ * Reload keeps the id (sessionStorage). A click that loads a new document often does not: the SDK
+ * is torn down with the page and HELLO's back under a new id, while the agent still holds the old
+ * one. `navigate` already waits for that HELLO (`awaitArrival`) and returns the new id.
+ * `act_and_wait` and `assert` did not, so an MPA drive ended at the first link.
+ *
+ * Unique at the departed origin (and project, when known). Two live tabs at that origin is still a
+ * guess, and a guess here would drive the wrong app.
+ */
+import type { Session } from './session.js';
+export interface SessionIdentity {
+    id: string;
+    url: string;
+    projectId?: string;
+}
+export interface SuccessorClock {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * The one live session that can honestly take over from `departed`, or undefined when none or more
+ * than one could.
+ *
+ * A same-id reconnect is a successor: the id survived in sessionStorage, the document did not.
+ */
+export declare function pickDocumentSuccessor(live: readonly SessionIdentity[], departed: SessionIdentity): SessionIdentity | undefined;
+export interface SuccessorRegistry {
+    get(id: string): Session | undefined;
+    all(): readonly Session[];
+}
+/**
+ * Poll until a successor of `departed` is live, or the budget runs out. Null on timeout — never
+ * throws, because failing to follow is a legitimate `observation_lost`, not an error.
+ */
+export declare function awaitDocumentSuccessor(sessions: SuccessorRegistry, departed: Session, timeoutMs: number, clock?: SuccessorClock): Promise<Session | null>;

package/dist/session/session-successor.js

@@ -0,0 +1,78 @@
+/**
+ * The session that took over after a full-document navigation.
+ *
+ * Reload keeps the id (sessionStorage). A click that loads a new document often does not: the SDK
+ * is torn down with the page and HELLO's back under a new id, while the agent still holds the old
+ * one. `navigate` already waits for that HELLO (`awaitArrival`) and returns the new id.
+ * `act_and_wait` and `assert` did not, so an MPA drive ended at the first link.
+ *
+ * Unique at the departed origin (and project, when known). Two live tabs at that origin is still a
+ * guess, and a guess here would drive the wrong app.
+ */
+const POLL_MS = 25;
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function identityOf(session) {
+    return {
+        id: session.id,
+        url: session.url,
+        ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
+    };
+}
+/**
+ * The one live session that can honestly take over from `departed`, or undefined when none or more
+ * than one could.
+ *
+ * A same-id reconnect is a successor: the id survived in sessionStorage, the document did not.
+ */
+export function pickDocumentSuccessor(live, departed) {
+    const origin = originOf(departed.url);
+    if (origin === undefined)
+        return undefined;
+    const atOrigin = live.filter((s) => originOf(s.url) === origin);
+    const sameId = atOrigin.find((s) => s.id === departed.id);
+    if (sameId !== undefined)
+        return sameId;
+    const others = atOrigin.filter((s) => s.id !== departed.id &&
+        (departed.projectId === undefined || s.projectId === departed.projectId));
+    if (1 !== others.length)
+        return undefined;
+    return others[0];
+}
+/**
+ * Poll until a successor of `departed` is live, or the budget runs out. Null on timeout — never
+ * throws, because failing to follow is a legitimate `observation_lost`, not an error.
+ */
+export async function awaitDocumentSuccessor(sessions, departed, timeoutMs, clock = REAL_CLOCK) {
+    const deadline = clock.now() + timeoutMs;
+    const departedIdentity = identityOf(departed);
+    for (;;) {
+        const sameId = sessions.get(departed.id);
+        if (sameId !== undefined && sameId !== departed)
+            return sameId;
+        // The departed session often still sits in the registry until the socket close lands. Leave it
+        // out of the pick, or same-id-first would keep returning the page that just unloaded.
+        const picked = pickDocumentSuccessor(sessions
+            .all()
+            .filter((s) => s !== departed)
+            .map(identityOf), departedIdentity);
+        if (picked !== undefined) {
+            const live = sessions.get(picked.id);
+            if (live !== undefined && live !== departed)
+                return live;
+        }
+        if (clock.now() >= deadline)
+            return null;
+        await clock.sleep(POLL_MS);
+    }
+}

package/dist/session/session.d.ts

@@ -2,10 +2,11 @@ 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 HelloMessage, type HumanControlData, type ReticleEvent } from '@reticlehq/core';
+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';
@@ -63,6 +64,10 @@ export declare class Session {
     info(): SessionInfo;
     /** 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;
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event: ReticleEvent, byteSize?: number): void;
     recordActedRef(ref: string): void;
@@ -100,8 +105,28 @@ export declare class Session {
      * 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[];
@@ -120,6 +145,11 @@ export declare class Session {
      * 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

package/dist/session/session.js

@@ -1,6 +1,7 @@
 import { recordImpact } from '../impact/impact-recorder.js';
 import { LastAct } from './last-act.js';
 import { GapLedger } from '../honesty/gap-ledger.js';
+import { CaptureLedger } from '../honesty/feature-capture.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
@@ -107,6 +108,30 @@ export class Session {
     #journalReader;
     /** What this session has learned by watching its own stream: ambient churn + blind-spot levels. */
     #observed = new ObservedState();
+    /**
+     * Which document is on screen right now — the one the most recent stamped event was observed under.
+     *
+     * DERIVED, never announced. The SDK mints a document id once per real document and stamps it on
+     * every event, so the stream already carries the answer; asking the page for it separately would be
+     * a second source of truth that can disagree with the evidence it is supposed to scope. A full
+     * navigation or a reload builds a new document, mints a new id, and the first event carrying it
+     * moves this forward — which is exactly the moment the previous document's evidence stops being
+     * about the world. An SPA route change keeps the same document and so keeps the same id, which is
+     * correct rather than a limitation: same JavaScript context, same in-flight requests, same evidence.
+     *
+     * An UNSTAMPED event never clears this. An SDK older than the field stamps nothing, and letting one
+     * such event blank the current document would make every later comparison vacuous.
+     */
+    #documentId;
+    /**
+     * The edit epoch of the most recent stamped event. DERIVED for the same reason `#documentId` is:
+     * the stream already carries it, and asking the page separately would be a second source of truth.
+     *
+     * A hot update advances it INSIDE the same document, which is the case `#documentId` structurally
+     * cannot see — no navigation, same page, replaced code. An unstamped event never clears it: most
+     * pages have no hot-update channel at all, so absence is "unknown", never "back to no edits".
+     */
+    #editEpoch;
     constructor(hello, socket, clock) {
         this.id = hello.sessionId;
         this.projectId = hello.projectId;
@@ -201,8 +226,20 @@ export class Session {
     staleMs() {
         return this.#clock() - this.#startedAt;
     }
+    /** The document the most recent stamped event was observed under. See `#documentId`. */
+    get currentDocumentId() {
+        return this.#documentId;
+    }
+    /** The edit epoch the most recent stamped event was observed under. See `#editEpoch`. */
+    get currentEditEpoch() {
+        return this.#editEpoch;
+    }
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event, byteSize) {
+        if (event.documentId !== undefined)
+            this.#documentId = event.documentId;
+        if (event.editEpoch !== undefined)
+            this.#editEpoch = event.editEpoch;
         if (event.type === EventType.PAGE_HEALTH) {
             const r = readHealthEvent(event.data);
             this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine, r.brand);
@@ -344,19 +381,50 @@ export class Session {
      * action id. Ids are minted independently of command correlation ids so the journal is self-contained.
      */
     beginAction(tool, args) {
-        this.#actionSeq += 1;
-        const actionId = `${ACTION_ID_PREFIX}${String(this.#actionSeq)}`;
+        const actionId = this.#mintActionId();
         // Held here, not only in the journal: with the journal off every event was unattributed, and
         // pushEvent reads that as ambient churn the settle oracle then ignores. See action-attribution test.
         this.#activeActionId = actionId;
         this.#journal?.beginAction(actionId, tool, args);
         return actionId;
     }
+    /**
+     * 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, args, effect) {
+        const actionId = this.#mintActionId();
+        this.#journal?.recordAction(actionId, tool, args, effect);
+        return actionId;
+    }
+    #mintActionId() {
+        this.#actionSeq += 1;
+        return `${ACTION_ID_PREFIX}${String(this.#actionSeq)}`;
+    }
+    /**
+     * 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() {
+        return this.#actionSeq;
+    }
     /** Close the active action window, persisting its action record with the settle outcome. */
     finishAction(effect, settled, settledInMs) {
         this.#activeActionId = undefined;
         this.#journal?.finishAction(effect, settled, settledInMs);
     }
+    /**
+     * 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.
+     */
+    async readJournalActions() {
+        return (await this.#journalReader?.readActions?.()) ?? [];
+    }
     /** Flush any buffered journal events to disk (call on session end). */
     async flushJournal() {
         await this.#journal?.flush();
@@ -379,6 +447,11 @@ export class Session {
      * end of it.
      */
     gaps = new 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.
+     */
+    capture = new CaptureLedger();
     // ── Server-authoritative liveness (immune to browser-tab throttling) ──────────────
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).

package/dist/telemetry/automation-hint.d.ts

@@ -1,5 +1,5 @@
 import { AutomationHint } from '@reticlehq/core';
-export interface AutomationInput {
+interface AutomationInput {
     env: NodeJS.ProcessEnv;
     fileExists: (path: string) => boolean;
     hasTty: boolean;
@@ -15,3 +15,4 @@ export interface AutomationInput {
 export declare function resolveAutomationHint(input: AutomationInput): AutomationHint | undefined;
 /** The real reading, taken once per process. */
 export declare function currentAutomationHint(env: NodeJS.ProcessEnv): AutomationHint | undefined;
+export {};

package/dist/telemetry/feedback-outbox.d.ts

@@ -1,5 +1,5 @@
 /** One queued report: the payload, plus what is needed to find and remove it again. */
-export interface OutboxEntry {
+interface OutboxEntry {
     id: string;
     t: string;
     payload: unknown;
@@ -20,3 +20,4 @@ export declare function readOutbox(home?: string): OutboxEntry[];
  * Volume is a handful of lines a week, so the cost is irrelevant.
  */
 export declare function markDelivered(id: string | null, home?: string): void;
+export {};

package/dist/telemetry/project-profile.d.ts

@@ -13,9 +13,6 @@ export declare const FeatureFamily: {
     readonly BUG_CAPSULES: "bug_capsules";
     readonly CROSS_RUN_HISTORY: "cross_run_history";
 };
-export type FeatureFamily = (typeof FeatureFamily)[keyof typeof FeatureFamily];
-/** Count source files, stopping at the cap (the cap itself lands in the largest bucket, correctly). */
-export declare function countSourceFiles(root: string, readDir?: DirReader): number;
 export declare function sizeBucket(sourceFiles: number): ProjectSize;
 /**
  * Project age in whole WEEKS, from the repo's first commit.
@@ -30,11 +27,6 @@ export declare function sizeBucket(sourceFiles: number): ProjectSize;
 export declare function projectAgeWeeks(root: string, now: number, read?: FileReader): number | undefined;
 /** True when package.json declares workspaces — monorepos exercise very different code paths. */
 export declare function isMonorepo(root: string, read?: FileReader): boolean;
-interface DirEntry {
-    name: string;
-    isDirectory: boolean;
-}
-type DirReader = (dir: string) => DirEntry[];
 type FileReader = (path: string) => string;
 /**
  * Build the full profile. Best-effort throughout: an unreadable project yields a profile of zeroes

package/dist/telemetry/project-profile.js

@@ -45,7 +45,7 @@ const MAX_FILES_SCANNED = 6000;
 const MAX_WALK_DEPTH = 8;
 const MS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
 /** Count source files, stopping at the cap (the cap itself lands in the largest bucket, correctly). */
-export function countSourceFiles(root, readDir = defaultReadDir) {
+function countSourceFiles(root, readDir = defaultReadDir) {
     let count = 0;
     const walk = (dir, depth) => {
         if (depth > MAX_WALK_DEPTH || count >= MAX_FILES_SCANNED)

package/dist/telemetry/run-telemetry.d.ts

@@ -11,8 +11,6 @@
  * how a replay works.
  */
 import { type ReticleVerificationRun } from '@reticlehq/core';
-/** The tool name reported for this path, so CI runs are distinguishable from agent-driven ones. */
-export declare const VERIFY_SURFACE = "reticle_verify";
 /**
  * Report one completed verification run: the verdict, and one bug per failing flow.
  *

package/dist/telemetry/run-telemetry.js

@@ -14,7 +14,7 @@ import { BugAttribution, BugSource, RunFlowStatus, TelemetryActor, TelemetryEven
 import { getSessionMetrics } from './session-metrics.js';
 import { getTelemetry } from './telemetry.js';
 /** The tool name reported for this path, so CI runs are distinguishable from agent-driven ones. */
-export const VERIFY_SURFACE = 'reticle_verify';
+const VERIFY_SURFACE = 'reticle_verify';
 /**
  * Report one completed verification run: the verdict, and one bug per failing flow.
  *

package/dist/telemetry/verification-of.js

@@ -13,7 +13,7 @@
  * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
  */
 import { CaptureLoss, VerifiedReason } from '@reticlehq/core';
-import { VERIFICATION_TOOLS } from '../tools/feedback-tools.js';
+import { VERDICT_TOOLS } from '../tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
 /**
  * The deciding clause, read off the result `decideVerified` wrote it onto.
@@ -92,7 +92,7 @@ function passedOf(result, status) {
  * it verified. That is the product's thesis reduced to a boolean.
  */
 export function verificationOf(toolName, result, durationMs, brand) {
-    if (!VERIFICATION_TOOLS.has(toolName))
+    if (!VERDICT_TOOLS.has(toolName))
         return undefined;
     // A paused session REFUSES the call — nothing driven, nothing asserted. The refusal carries a
     // verdict field so the agent never reads undefined off it, and that field must not be mistaken