@reticlehq/server 2.11.0 → 2.13.0

package/dist/session/session.js

@@ -1,8 +1,10 @@
 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';
+import { MIRRORED_COMMANDS, mirroredNarration } from './session-mirror.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
 const IMPACT_PUSH_DEBOUNCE_MS = 700;
 import { PendingCommands, CommandTimeoutError } from './pending-commands.js';
@@ -51,6 +53,12 @@ const REBINDABLE_COMMANDS = new Set([
 ]);
 /** Prefix on minted action ids (a1, a2, …) — the journal's action identity, independent of commands. */
 const ACTION_ID_PREFIX = 'a';
+/**
+ * How many consecutive unanswered commands make a tab unresponsive. One is a page that was merely
+ * busy for its budget; two in a row with no reply between them is a wedge, and the cost of being
+ * wrong about that is one extra browser tab.
+ */
+const UNRESPONSIVE_AFTER_TIMEOUTS = 2;
 /** ws readyState for an OPEN socket — guard fire-and-forget pushes against a closing tab. */
 const WS_OPEN = 1;
 /**
@@ -61,6 +69,17 @@ export class Session {
     id;
     /** Stable build-stamped project identity; undefined for v1.0 SDKs that omit it. */
     projectId;
+    /**
+     * 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;
     url;
     title;
     adapters;
@@ -81,6 +100,8 @@ export class Session {
     #listeners = new Set();
     #disconnectListeners = new Set();
     #actionSeq = 0;
+    /** Consecutive missed command budgets — free liveness evidence. Any reply resets it. */
+    #unansweredCommands = 0;
     #lastSeenAt;
     #hidden = false;
     /** Which shell the page reported (PAGE_HEALTH). Undefined until the first report lands. */
@@ -107,6 +128,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;
@@ -179,6 +224,9 @@ export class Session {
             hidden: this.#hidden,
             throttled: base.throttled,
             focused: base.focused,
+            // Without this the desktop branch is unreachable in production: every unit test would pass and
+            // every real Electron window would still be told to open a browser.
+            runtime: this.#runtime,
         });
         return recommendation === undefined ? base : { ...base, recommendation };
     }
@@ -190,19 +238,42 @@ export class Session {
             title: this.title,
             adapters: this.adapters,
             hasCapabilities: this.hasCapabilities,
+            runtime: this.#runtime,
             versionSkew: this.versionSkew,
             hidden: this.#hidden,
             health: () => this.health(),
             staleMs: () => this.staleMs(),
             pendingMarkCount: () => this.#review.pendingCount(),
+            unresponsive: () => this.unresponsive(),
         });
     }
+    /**
+     * 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() {
+        return this.#unansweredCommands >= UNRESPONSIVE_AFTER_TIMEOUTS;
+    }
     /** Wall-clock age of the session in milliseconds. */
     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);
@@ -227,7 +298,7 @@ export class Session {
                 this.#review.add(parsed.data, this.elapsed());
                 // The impact record's `marks` field existed and nothing ever wrote it: the report would
                 // have shown a permanent zero next to a page covered in pins.
-                recordImpact({ marks: 1 });
+                recordImpact({ marks: 1 }, {}, this.artifactRoot);
             }
         }
         if (event.type === EventType.ROUTE_CHANGE) {
@@ -344,19 +415,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 +481,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).
@@ -478,6 +585,8 @@ export class Session {
         // the app taking its time — the split telemetry reports in aggregate, made visible per call.
         return span('browser.command', { command: name, sessionId: this.id }, () => awaited)
             .then((result) => {
+            // Answered — whatever the reply said, the command channel is alive.
+            this.#unansweredCommands = 0;
             // The label is only knowable from the REPLY — the request carries a ref, and a ref dies with
             // the next re-render. Recorded here so coverage survives frameworks that replace nodes.
             if (name === ReticleCommand.ACT)
@@ -493,6 +602,8 @@ export class Session {
             // simply not been answered in budget was read as "you were replaced, ask again" — and
             // against a page re-dialling in a loop that turned one read into hundreds of commands on the
             // wire, minutes of wall clock, and an answer still quoting the budget it had blown.
+            if (error instanceof CommandTimeoutError)
+                this.#unansweredCommands += 1;
             const next = error instanceof CommandTimeoutError ? undefined : this.#liveSuccessor();
             if (next === undefined || !REBINDABLE_COMMANDS.has(name))
                 throw error;
@@ -507,11 +618,14 @@ export class Session {
         });
     }
     handleResult(result) {
+        // Any reply at all clears the wedge, including one for a command that already timed out: it is
+        // still proof that bridge→page→bridge works right now, which is the only thing being claimed.
+        this.#unansweredCommands = 0;
         this.#pending.settle(result);
     }
     /** Reject everything still in flight — used on disconnect. */
-    rejectAll(reason) {
-        this.#pending.rejectAll(reason);
+    rejectAll(reason, replaced = false) {
+        this.#pending.rejectAll(reason, replaced);
         for (const listener of this.#disconnectListeners)
             listener();
         this.#disconnectListeners.clear();
@@ -558,11 +672,11 @@ export class Session {
         return undefined;
     }
     /** End this transport without letting a stale socket remove its replacement session. */
-    disconnect(reason) {
+    disconnect(reason, replaced = false) {
         // "Longest run" means the longest SESSION, and it used to be fed a single tool call's duration
         // - so the report's superlative was a number in milliseconds that never grew past a click.
-        recordImpact({}, { runMs: this.elapsed() });
-        this.rejectAll(reason);
+        recordImpact({}, { runMs: this.elapsed() }, this.artifactRoot);
+        this.rejectAll(reason, replaced);
         try {
             this.#socket.close(1008, reason);
         }
@@ -691,8 +805,47 @@ export class Session {
         const minutes = Math.floor(ageMs / 60_000);
         return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_session{action:"end"} now.`;
     }
-    /** Fire-and-forget command send — NOT registered in #pending (no correlated result expected). */
+    /**
+     * The tabs that should SEE what this session is told, supplied by the SessionManager.
+     *
+     * `reticle drive` attaches to the running daemon and is handed a pooled HEADLESS context, so the
+     * whole HUD feed — the narration, the counters, the bug that was just raised — went to a browser
+     * with nobody in front of it, while the developer's own tab showed nothing. The feed is now a
+     * per-project broadcast: the driven tab is still the only one DRIVEN, and any other tab of the
+     * same app is a viewer.
+     */
+    #viewers;
+    /** Wired by SessionManager.add, the one place every session registers. */
+    setViewers(read) {
+        this.#viewers = read;
+    }
+    /**
+     * Fire-and-forget command send — NOT registered in #pending (no correlated result expected).
+     *
+     * Mirrored to this project's other tabs, for the two commands that are a REPORT of what happened
+     * (narration, impact). PRESENTER is deliberately not among them: it is the glow and the lifecycle
+     * that say "the agent is driving THIS tab", and a viewer that showed it would be claiming
+     * something untrue about itself.
+     */
     #post(name, args) {
+        this.#send(name, args);
+        if (!MIRRORED_COMMANDS.has(name))
+            return;
+        for (const viewer of this.#viewers?.() ?? []) {
+            if (viewer === this)
+                continue;
+            // Straight to the raw send, so a mirrored row is never mirrored again.
+            viewer.#send(name, name === ReticleCommand.NARRATE ? this.#labelled(args) : args);
+        }
+    }
+    /** A narration row re-addressed to a tab that is watching rather than being driven. */
+    #labelled(args) {
+        const text = args['text'];
+        if ('string' !== typeof text)
+            return args;
+        return { ...args, text: mirroredNarration(this.id, text) };
+    }
+    #send(name, args) {
         if (this.#socket.readyState !== WS_OPEN)
             return;
         // Shares the same counter as tracked commands, so a fire-and-forget id can never collide with

package/dist/session/wall-clock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The real clock, named once.
+ *
+ * The logic that needs a clock takes one as an argument so a test can drive it without waiting
+ * (CLAUDE.md rule 7). That leaves the production callers each constructing the same pair of
+ * closures, which is how two of them end up with different sleep implementations. One export, one
+ * place to look.
+ */
+export declare const WALL_CLOCK: {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+};

package/dist/session/wall-clock.js

@@ -0,0 +1,14 @@
+/**
+ * The real clock, named once.
+ *
+ * The logic that needs a clock takes one as an argument so a test can drive it without waiting
+ * (CLAUDE.md rule 7). That leaves the production callers each constructing the same pair of
+ * closures, which is how two of them end up with different sleep implementations. One export, one
+ * place to look.
+ */
+export const WALL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => {
+        setTimeout(resolve, ms).unref?.();
+    }),
+};

package/dist/setup/agent-configs.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The coding agents `init`'s own MCP registration does not reach, and where their config lives.
+ *
+ * `init` covers eight clients and only where it already finds them. That leaves real holes: VS
+ * Code's USER-scope mcp.json exists on machines today and init only ever writes the project-scope
+ * one, so a VS Code user has no tools outside the directory they ran init in. Zed, Warp, Kiro, Amp,
+ * Copilot CLI, Amazon Q, Factory Droid, Cline and Roo are not covered at all.
+ *
+ * Three rules, and the second is what keeps this honest:
+ *
+ * 1. A path with OFFICIAL documentation is written even when the agent is absent, so a later
+ *    install finds itself already wired.
+ * 2. A path we cannot evidence is REFUSED. Cline's and Roo's live under VS Code globalStorage,
+ *    which moves under Insiders, portable installs and a custom --user-data-dir; they are written
+ *    only where the host's standard layout is present. A config file at a guessed location is one
+ *    nobody reads, which is indistinguishable from success.
+ * 3. A format we cannot merge safely is never rewritten. TOML, an existing YAML, JSONC carrying
+ *    comments: we print the snippet instead. Reformatting somebody's config to add one entry is
+ *    not ours to do.
+ */
+export declare const AgentConfidence: {
+    /** Documented by the vendor. Safe to create before the agent exists. */
+    readonly OFFICIAL: "official";
+    /** Community-sourced. Only written where the host's own layout proves the path. */
+    readonly COMMUNITY: "community";
+};
+export type AgentConfidence = (typeof AgentConfidence)[keyof typeof AgentConfidence];
+export declare const AgentAction: {
+    readonly CREATE: "create";
+    readonly CREATE_YAML: "create-yaml";
+    readonly MERGE: "merge";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+    readonly SKIP: "skip";
+};
+export type AgentAction = (typeof AgentAction)[keyof typeof AgentAction];
+/** Per-platform relative paths, from the user's home directory. */
+export interface PlatformPaths {
+    readonly darwin: string;
+    readonly linux: string;
+    readonly win32: string;
+}
+export interface AgentClient {
+    readonly id: string;
+    readonly name: string;
+    readonly confidence: AgentConfidence;
+    /** `json` merges; `yaml-manual` is only ever created fresh, never edited. */
+    readonly format: 'json' | 'yaml-manual';
+    /** Where the server map lives. Getting this wrong writes a file the client silently ignores. */
+    readonly key: string;
+    readonly entry?: Readonly<Record<string, unknown>> | undefined;
+    readonly paths: PlatformPaths;
+    /** Existence proves the agent is installed. */
+    readonly marker: PlatformPaths;
+    /** The HOST's directory, when the marker belongs to an extension rather than the app. */
+    readonly parentMarker?: PlatformPaths | undefined;
+    /** Where this agent loads reusable skills from, when it has such a place. */
+    readonly skillDir?: string | undefined;
+}
+export declare const AGENT_CLIENTS: readonly AgentClient[];
+/** What to do for one client, decided without touching the disk. */
+export interface AgentPlanStep {
+    readonly id: string;
+    readonly name: string;
+    readonly file: string;
+    readonly action: AgentAction;
+    readonly key?: string | undefined;
+    readonly entry?: Readonly<Record<string, unknown>> | undefined;
+    readonly why: string;
+}
+export interface AgentPlanInput {
+    readonly home: string;
+    readonly platform: keyof PlatformPaths;
+    readonly exists: (path: string) => boolean;
+    readonly readFile: (path: string) => string;
+}
+/**
+ * Join for the platform the CALLER named, never the one this process happens to run on.
+ *
+ * Every planner here takes `platform` as an argument and claims to be pure over it — the doc below
+ * says the Windows rows are "testable from any machine". `node:path`'s bare `join` broke that claim
+ * silently in both directions: a mac planning win32 rows emitted `/` separators into paths Windows
+ * cannot use, and a Windows host planning linux rows emitted `\`. The second half is what turned
+ * the whole Windows CI job red — the pure planners returned `\home\u\.claude\settings.json`,
+ * every injected filesystem is keyed by the POSIX path the caller asked for, so every lookup missed
+ * and every row came back `absent`/`skip`. Twenty-eight tests failed for a reason that had nothing
+ * to do with what they were testing, which left the platform with the most users unwatched.
+ *
+ * A separator is part of the answer, so it belongs to the platform being planned for.
+ */
+export declare const joinFor: (os: keyof PlatformPaths) => ((...parts: string[]) => string);
+/**
+ * Decide what to do for every client. Pure: the filesystem arrives as two functions, which is what
+ * makes the Windows rows testable from any machine.
+ */
+export declare function planAgentConfigs(input: AgentPlanInput): AgentPlanStep[];