@reticlehq/server 2.11.0 → 2.13.0

package/dist/tools/invoke-tool.js

@@ -1,23 +1,26 @@
 import { healthEnvelope } from '../session/session-health.js';
+import { verifyNextBaton, SUPPRESS_VERIFY_NEXT_ENV } from './verify-next-baton.js';
 import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
 import { takeUpdateNudge } from '../update/update-nudge.js';
 import { takeVersionSkew } from '../version/version-nudge.js';
+import { rewriteClosedAsSkew } from '../version/version-skew.js';
 import { noteToolCall } from '../daemon/daemon-usefulness.js';
 import { bugsInResult, routeOf } from '../telemetry/bug-found.js';
 import { noteToolServed, reportToolRefused } from '../telemetry/tool-refused.js';
 import { buildErrorPayload, refusalReasonFor } from './error-recovery.js';
 import { resultIsError } from '../mcp/mcp-is-error.js';
 import { verificationOf } from '../telemetry/verification-of.js';
-import { asString } from './tools-helpers.js';
+import { asString, sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
 import { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
 import { noteRefsMinted, wrongTabRefusal } from '../session/ref-provenance.js';
+import { CAPTURED_TOOLS, noteCapturedCall, noteToolDispatched, } from '../honesty/feature-capture.js';
 import { span } from '../trace.js';
-import { deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
+import { defectForToolResult, deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
 import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
  * The live-session tools whose result MUST carry the
@@ -35,6 +38,20 @@ const ACTION_TOOLS = new Set([
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
 ]);
+/**
+ * Tools that go through Playwright CDP rather than the page SDK.
+ *
+ * Under version skew these fail with "Target page, context or browser has been closed" while every
+ * DOM tool against the same tab still works (#688). They are session-EXEMPT (own result contracts),
+ * so the bound-tool resolve above never runs for them — resolve again here so we can refuse with
+ * the skew sentence before Playwright lies about a closed page.
+ */
+const CDP_TOOLS = new Set([
+    ReticleTool.SCREENSHOT,
+    ReticleTool.VISUAL_DIFF,
+    ReticleTool.NETWORK_MOCK,
+    ReticleTool.VIEWPORT,
+]);
 /**
  * Tools whose result hands the agent refs. The tab they were minted in is remembered, so the call
  * that spends one cannot be routed to a different tab without saying so — see ref-provenance.ts.
@@ -98,7 +115,13 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.FLOW_REPLAY, // returns its own FlowReplayResult contract (+ auto-records a run)
     ReticleTool.FLOW_SAVE_RECORDED, // reads the recording buffer, writes disk
     ReticleTool.FLOW_HEAL, // returns its own FlowHealResult contract
+    ReticleTool.INTENT, // reads/writes .reticle/intent.json; sessionId only picks the project
+    ReticleTool.CONTEXT, // folds the journal + intent ledger; must still answer when nothing is connected
     ReticleTool.PROJECT, // reads .reticle/project.json
+    // Reads the team's shared memory over HTTP; sessionId only resolves WHICH project's link file to
+    // use. It must answer with no tab connected — "what does this project know?" is a question an
+    // agent asks before it has opened anything.
+    ReticleTool.MEMORY,
     ReticleTool.RUN_EXPORT, // reads .reticle/runs/<id>.json (verification-run artifact)
     ReticleTool.SESSION, // merged lifecycle/human-channel family (tune/yield/end/resume/messages/review/narrate)
     ReticleTool.SCREENSHOT, // own contract; provider-driven, not a live-DOM-health read
@@ -283,7 +306,7 @@ export async function runTool(tool, deps, args) {
         getSessionMetrics().recordAction();
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
-    const rawSessionId = asString(args['sessionId']);
+    const rawSessionId = sessionIdFromArgs(args);
     const bound = SESSION_BOUND_TOOLS.has(tool.name);
     // Resolve the session identity ONCE, up front, for a live-session tool. The lease heartbeat must
     // target the session the handler will ACTUALLY drive — which, when the agent omits sessionId, is the
@@ -292,7 +315,7 @@ export async function runTool(tool, deps, args) {
     // before the handler so a long ACT_AND_WAIT is protected for its whole duration; on failure leave it
     // to the handler to throw the canonical no-session error.
     let session;
-    if (bound) {
+    if (bound || CDP_TOOLS.has(tool.name)) {
         try {
             session = deps.sessions.resolve(rawSessionId);
         }
@@ -300,6 +323,50 @@ export async function runTool(tool, deps, args) {
             session = undefined;
         }
     }
+    // CDP tools against a skewed session: refuse with the sentence reticle_sessions already knows,
+    // before Playwright invents a closed page. ready:true leases still hit this path.
+    if (session?.versionSkew !== undefined && CDP_TOOLS.has(tool.name)) {
+        const message = session.versionSkew;
+        reportRefusal(tool.name, message);
+        throw new Error(message);
+    }
+    // The read-only calls the journal never keeps, recorded HERE because this is the one dispatch
+    // point every call routes through — a second recording site is a second thing to forget, and this
+    // instrument exists precisely because nothing was recorded before. Recorded before the handler
+    // runs: a read dispatches no action, so the counter reads the same either side.
+    //
+    // `reticle_context` is session-EXEMPT, so `session` above is undefined for it and it needs its own
+    // lenient resolve. Failing that resolve is silent by design: a call made with nothing connected
+    // has no per-session ledger to land in, and an instrument must never be why a tool call fails.
+    //
+    // EVERY tool is counted here, not just the read set: which of the 70-odd names in the table an
+    // agent actually reaches for is the question a decision about cutting or consolidating the surface
+    // turns on, and it had no answer. `reticle_run` is the one exclusion, for the same reason
+    // `reportRefusal` and `bugsInResult` exclude it — its handler calls `runTool` on the real tool, so
+    // the inner call is already counted under the name that RAN, and counting the wrapper too would
+    // both double the total and hide the run-only tier behind a single wrapper name. That tier is
+    // precisely the one the decision hinges on. See honesty/tool-hit-rate.ts.
+    if (ReticleTool.RUN !== tool.name) {
+        let target = session;
+        if (target === undefined) {
+            try {
+                target = deps.sessions.resolve(rawSessionId);
+            }
+            catch {
+                target = undefined;
+            }
+        }
+        if (target !== undefined) {
+            noteToolDispatched(target, tool.name);
+            if (CAPTURED_TOOLS.has(tool.name)) {
+                const subject = asString(args['ref']) ?? asString(args['target']);
+                noteCapturedCall(target, {
+                    tool: tool.name,
+                    ...(subject === undefined ? {} : { subject }),
+                });
+            }
+        }
+    }
     // A ref that was handed out by a DIFFERENT tab, on a call that named no session. Refused here, at
     // the one point that knows both the ref and the tab resolution picked — the handler only learns
     // that the ref missed, and answers that with "the DOM re-rendered", which is a confident diagnosis
@@ -307,7 +374,7 @@ export async function runTool(tool, deps, args) {
     // the guessed tab and return a green about a page nobody asked about.
     if (session !== undefined) {
         const wrongTab = wrongTabRefusal({
-            ref: asString(args['ref']),
+            ref: spentRefFromArgs(args),
             explicitSessionId: rawSessionId,
             chosenSessionId: session.id,
             connected: () => deps.sessions.list(),
@@ -334,7 +401,22 @@ export async function runTool(tool, deps, args) {
         // to the agent by the MCP boundary, and discarded. Reported here rather than at that boundary
         // because there are two of them (mcp.ts and the reticle_run hatch) and this is the one place both
         // go through — a third would otherwise be invisible from the day it was added.
-        const message = error instanceof Error ? error.message : String(error);
+        //
+        // Under version skew, Playwright's "Target page has been closed" is the wrong cause (#688): the
+        // page is still dialled in. Prefer the session's skew sentence when we already know the pair is
+        // mismatched — including for tools that are not in CDP_TOOLS (real-input fallbacks that throw).
+        let skewText = session?.versionSkew;
+        if (skewText === undefined) {
+            try {
+                skewText = deps.sessions.resolve(rawSessionId).versionSkew;
+            }
+            catch {
+                skewText = undefined;
+            }
+        }
+        const rewritten = rewriteClosedAsSkew(error, skewText);
+        const toThrow = rewritten ?? error;
+        const message = toThrow instanceof Error ? toThrow.message : String(toThrow);
         reportRefusal(tool.name, message);
         // The invitation on THIS path is the one `buildErrorPayload` attaches when it does not recognise
         // the error, and it was never counted — so the denominator excluded the commonest friction there
@@ -343,7 +425,7 @@ export async function runTool(tool, deps, args) {
         if (tool.name !== ReticleTool.RUN && buildErrorPayload(message).feedback !== undefined) {
             getSessionMetrics().recordFeedbackPrompt();
         }
-        throw error;
+        throw toThrow;
     }
     finally {
         // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
@@ -369,11 +451,20 @@ export async function runTool(tool, deps, args) {
     // The user's own record of what Reticle did for them. Same chokepoint as everything else that
     // counts, for the same reason: a second recording site is a second thing to forget. Separate
     // store from telemetry - this one never leaves the machine.
-    recordImpact(deltaForToolResult(raw, Date.now() - startedAt, resultIsError(raw)));
+    const finishedAt = Date.now();
+    const defect = defectForToolResult(raw, finishedAt);
+    // Which project's ledger this call belongs to. Resolved from the SESSION being driven, not from
+    // wherever the daemon happens to stand: one daemon serves many projects, and recording every
+    // call against its own cwd is how one app's verdicts ended up on another account's dashboard.
+    // Falls back to the daemon root when no session can be named, which is the old behaviour.
+    const artifactRoot = session?.artifactRoot ?? deps.reticleRoot;
+    recordImpact(deltaForToolResult(raw, finishedAt - startedAt, resultIsError(raw)), { ...(defect === undefined ? {} : { defect }) }, artifactRoot);
     // ...and the tab being driven is told, so the report is live rather than a thing you reload.
     // Optional-call, not optional-chain-on-the-object: a test double is a partial Session, and a
     // courtesy push must never be the reason a tool call throws.
-    session?.pushImpact?.(impactSnapshot);
+    // Bound to THIS session's root: a tab must be shown its own project's numbers, not whichever
+    // project the daemon was started in.
+    session?.pushImpact?.(() => impactSnapshot(artifactRoot));
     if (resultIsError(raw))
         reportRefusal(tool.name, raw.error);
     else {
@@ -450,8 +541,27 @@ export async function runTool(tool, deps, args) {
     // verdict-less session in the field never called a verdict-producing tool ONCE;
     // the counter behind this already existed and was reported only to us. One-shot per abandoned
     // run, same discipline as the pool lease — a hint on every call is noise that gets tuned out.
+    // The A/B control, and the reason it exists as an env flag rather than a code edit.
+    //
+    // `verify_next` is described in this repo's own changelog as "the largest known lever on whether a
+    // session produces a verdict at all", and it has never been measured — it was once built, fired
+    // and silently dropped by schema-strict clients for a whole release, which is exactly what an
+    // unmeasured lever looks like from the inside. "The payload now arrives" and "the agent acts on
+    // it" are different claims and only the first was ever verified.
+    //
+    // Suppressing it for a control arm has to leave the ONLY difference being the baton: same build,
+    // same surface, same counters. So the nudge is still TAKEN (the counter still resets, so the
+    // one-shot cadence is identical) and only the envelope key is withheld.
+    const suppressBaton = '1' === process.env[SUPPRESS_VERIFY_NEXT_ENV];
     const unverified = getSessionMetrics().takeUnverifiedNudge();
-    if (unverified !== undefined)
-        envelope[EnvelopeKey.VERIFY_NEXT] = unverified;
+    // Carry the CALL, not just the sentence. The prose has to be translated back into arguments, and
+    // that translation is where agents were already going wrong — `until` omitted, action arguments
+    // flat instead of nested under `args`. `ref` and `action` come from the act that actually
+    // dispatched, so the suggestion is about the element the agent touched. See verify-next-baton.
+    if (unverified !== undefined && !suppressBaton)
+        // `lastAct` read defensively: this envelope is built on EVERY tool call, so a session shape
+        // without it would turn a missing field into a crash on the whole surface rather than a missing
+        // suggestion. The baton degrades to prose, which is what it carried before.
+        envelope[EnvelopeKey.VERIFY_NEXT] = verifyNextBaton(unverified, resolved.lastAct?.effect() ?? {});
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }

package/dist/tools/lease-hint.d.ts

@@ -35,5 +35,15 @@ export interface LeaseEvidence {
      * reported as a marker that was not found.
      */
     sdkMarker?: boolean;
+    /**
+     * The websocket URL the leased page actually tried, read from its own console.
+     *
+     * The only per-page proof there is about where the dial WENT. `refusal` proves a dial arrived
+     * HERE; this proves where one was aimed, which is the strictly more useful fact when it was aimed
+     * somewhere else — the case in which no refusal exists to be recorded, because nothing arrived.
+     *
+     * Absent means the page said nothing, never that it dialled correctly.
+     */
+    dialledUrl?: string;
 }
 export declare function leaseNotConnectedHint(url: string, port: number, evidence?: LeaseEvidence): string;

package/dist/tools/lease-hint.js

@@ -45,9 +45,45 @@ function markerClause(sdkMarker) {
             'document, so a lazily-imported SDK can still be missed — but combined with the rest it ' +
             'points at a bundle that carries no Reticle at all, i.e. wiring that never took effect.';
 }
+/**
+ * The port a websocket URL names, or undefined when it names none we can read.
+ *
+ * `ws://host/path` with no explicit port is deliberately undefined rather than defaulted to 80: a
+ * guessed port compared against the daemon's would manufacture a mismatch out of nothing, and this
+ * branch outranks every other cause. No answer is correct here; a plausible one is not.
+ */
+function dialledPort(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        const port = new URL(url).port;
+        return '' === port ? undefined : Number(port);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function leaseNotConnectedHint(url, port, evidence = {}) {
     const opening = `the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}).`;
     const marker = markerClause(evidence.sdkMarker);
+    // 0. The page told us where it dialled, and it was not here. Proof, and it outranks the refusal
+    //    branch below: a refusal proves a dial reached THIS daemon, which is a fact about some page;
+    //    this is a fact about the page in hand. When they disagree, the specific one wins.
+    //
+    //    Neither side can reach this conclusion alone, which is why it went unsaid for so long. The
+    //    page's own warning deliberately refuses to diagnose the daemon — from inside a browser a
+    //    daemon that is absent and one that is unreachable are the same observation. The daemon cannot
+    //    see a dial that never arrived. Put the address the page names beside the port the daemon is
+    //    bound to and the ambiguity disappears.
+    const dialled = dialledPort(evidence.dialledUrl);
+    if (dialled !== undefined && dialled !== port) {
+        return (`${opening} The page dialled ${String(evidence.dialledUrl)} (port ${String(dialled)}) and ` +
+            `this daemon is on ${String(port)}, so the dial never reached it. Nothing about the app's ` +
+            `wiring is in question. Either start the daemon on ${String(dialled)}, or point the app at ` +
+            `${String(port)} — the app's port comes from its build config (\`.reticle.json\`, ` +
+            `RETICLE_PORT, or the build plugin's \`port\`), and \`VITE_RETICLE_WS_URL\` overrides it ` +
+            `outright.${marker} ${RELEASE}`);
+    }
     // 1. A recorded refusal. The only cause with proof behind it, so nothing outranks it.
     if (evidence.refusal !== undefined) {
         return `${opening} A dial DID arrive and was refused: ${evidence.refusal}${marker} ${RELEASE}`;
@@ -55,11 +91,24 @@ export function leaseNotConnectedHint(url, port, evidence = {}) {
     // 2. Nuxt, whose most likely cause differs from every other framework's and which `init` warns
     //    about at install time — while this hint never mentioned it.
     const nuxt = evidence.framework?.toLowerCase() === NUXT ? ` ${NUXT_FIRST}` : '';
-    // 3. Proven wiring. Blaming the port here is the self-contradiction this rewrite exists to end.
+    // 3. Proven PORT. Blaming the port here is the self-contradiction this rewrite exists to end —
+    //    but "the wiring is correct" was a second claim, and it was not proven at all.
+    //
+    //    `previouslyConnected` is scoped to project + port, never to the app. In a monorepo, or for
+    //    anyone adding a second app, the thing that connected yesterday is a DIFFERENT app. Measured:
+    //    an uninstrumented app driven in exactly that situation was told its wiring was correct, and
+    //    handed four causes — a dev-mode guard, a stale dev server, a missing peer dependency, a
+    //    non-localhost page — every one of which presupposes the SDK is already installed. It was
+    //    not. That is the commonest failure there is, and `reticle init` appeared nowhere in the
+    //    answer, because the only branch that mentions it is the one reached when nothing is known.
     if (true === evidence.previouslyConnected) {
-        return (`${opening} An app for this project HAS connected on this port before, so the port and the ` +
-            `wiring are both correct — what is failing is the SDK reaching initialise on the page.${nuxt}` +
-            `${marker} ${REAL_CAUSES} ${RELEASE}`);
+        const notThisApp = true === evidence.sdkMarker
+            ? ''
+            : ' That may have been a DIFFERENT app, though: this one may carry no Reticle SDK at all, ' +
+                'in which case run `reticle init` in ITS directory first — every cause below assumes the ' +
+                'SDK is already installed.';
+        return (`${opening} An app for this project HAS connected on this port before, so the port is ` +
+            `proven.${notThisApp}${nuxt}${marker} ${REAL_CAUSES} ${RELEASE}`);
     }
     // 4. Wired, but never seen connect. Rank the real causes; keep the port differential last, where
     //    the evidence for it actually sits.

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

@@ -1,14 +1,17 @@
 /**
  * Lease tools — the agent-facing surface of the BrowserPool.
  *
- * `reticle_lease_acquire` opens a fresh isolated headless context navigated to the app URL and returns
- * the sessionId the app's SDK will register (stamped via __reticle_session so the lease and the session
- * correlate 1:1). This is the "one of 10 flows" entry point: 10 agents acquire 10 leases, the pool
- * keeps them in ONE browser, capped and queued. `reticle_lease_release` frees the slot.
+ * `reticle_lease_acquire` opens an isolated headless context navigated to the app URL and returns
+ * the sessionId the app's SDK will register. A second acquire on the same origin reuses the live
+ * lease rather than minting another tab — that second tab used to poison default session resolution
+ * for the rest of the run. The parallel suite still mints via `acquireLeasedSession`, because ten
+ * flows on one origin need isolation on purpose.
  *
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
 import type { ToolDef } from './tool-kit.js';
+/** The origin of a URL, or undefined when it does not parse. */
+export declare function originOf(url: string): string | undefined;
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
@@ -40,6 +43,20 @@ export declare function resolveLeasedSessionId(sessions: {
         url?: string;
     }[];
 }, leaseId: string): string | undefined;
+/**
+ * Carry a claimed identity across a navigation.
+ *
+ * A LEASED tab is addressed by `__reticle_session` in its URL: that param is how the pool finds the
+ * context it opened, and — since succession was tightened — it is also the ONLY thing that lets the
+ * reconnecting document inherit the lease. `reticle_navigate` sent the caller's raw URL, so the very
+ * first navigation stripped the marker, the tab re-announced as an ordinary anonymous session, and
+ * the lease was orphaned: "no sessions are connected at all", with a browser window still open on
+ * screen. A leased browser that cannot survive being navigated is not a usable one.
+ *
+ * A tab that claims nothing is left exactly as it was — this must never bolt Reticle's params onto
+ * a human's own URL.
+ */
+export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl: string): string;
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
  * is immediately usable (the page navigates first, then connects a moment later — without this wait
@@ -58,6 +75,11 @@ export declare function acquireLeasedSession(pool: {
         sessionId: string;
         release: () => Promise<void>;
     }>;
+    /**
+     * The address this lease's page said it could not reach. Optional so a test double need not
+     * implement it; the real pool always does.
+     */
+    dialFailureUrl?: (sessionId: string) => string | undefined;
     /** Optional so a test double need not implement it; the real pool always does. */
     alias?: (registeredId: string, leaseId: string) => void;
 }, sessions: {
@@ -81,5 +103,13 @@ export declare function waitForLeasedSession(isConnected: () => boolean, sleeper
  * any other call instead of being a second, invisible dispatch path.
  */
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
-export declare const LEASE_RELEASE_TOOL: ToolDef;
+/**
+ * What to say when a lease was taken while a real tab was already open.
+ *
+ * Not a refusal. Leases are the highest-value path for autonomous work and an agent that genuinely
+ * needs isolation must still get one — but a human watching their own tab cannot see a lease, so
+ * when both exist the visible one is the better default and the agent should hear that here, where
+ * it is choosing, rather than discover it when somebody asks why nothing is happening.
+ */
+export declare const PREFER_EXISTING_NOTE = "a non-leased tab for this app was already connected \u2014 that is the one a human can see, and this lease is not. Unless you need an isolated context (a second identity, a clean profile, parallel flows), release this lease and drive that sessionId instead.";
 export declare const LEASE_TOOLS: ToolDef[];