@reticlehq/server 3.7.0 → 3.8.1

package/dist/surface/tools/run-report.js

@@ -0,0 +1,141 @@
+/**
+ * The end-of-run report: the run ledger as the agent shows it to the user.
+ *
+ * Added to the answer of the call that ends an agent's run: a session end, a yield, or a released
+ * tab. A run that ended by releasing its tab got no word about the run before this, and its agent
+ * wrote its own summary. The report is a schema'd object, the markdown built from it, and one
+ * instruction. The cloud line is said only when the project is not linked, and it says what it is.
+ */
+import { CLOUD_VALUE_LINE, ReticleTool, RUN_REPORT_FIELD, RUN_REPORT_INSTRUCTION, UPGRADE_HINT_SILENCE_ENV, Verified, asString, } from '@reticlehq/core';
+import { ResultWord, linkedToPlatform, seconds } from './reticle-result.js';
+const HEAD = '**Reticle run report: ';
+const SEP = ' · ';
+/** Claims listed before the rest are counted: enough to read, not enough to flood a reply. */
+const CLAIMS_SHOWN = 20;
+const Said = {
+    NOTHING_CHECKED: 'nothing was checked',
+    CAUGHT: 'Caught, expected to hold and did not',
+    FLOWS_SAVED: 'Flows saved',
+    FLOWS_REPLAYED: 'Flows replayed',
+    NO_FLOWS: 'Flows: none saved, none replayed',
+    MEMORY: 'Memory',
+    TIME: 'Time',
+    FIRST_VERDICT: 'first verdict after',
+};
+const WORD = {
+    [Verified.YES]: ResultWord.PROVED,
+    [Verified.NO]: ResultWord.FAILED,
+    [Verified.UNKNOWN]: ResultWord.NOT_PROVED,
+    [Verified.NO_FAULT]: ResultWord.NOT_PROVED,
+};
+const plural = (n, word) => `${String(n)} ${word}${1 === n ? '' : 's'}`;
+function headline(report) {
+    const all = [...report.claims, ...report.flows.replayed].map((c) => c.verified);
+    const count = (v) => all.filter((each) => v === each).length;
+    const total = all.length;
+    const word = `${HEAD}${WORD[report.verified]}**${SEP}`;
+    if (0 === total)
+        return `${word}${Said.NOTHING_CHECKED}`;
+    if (Verified.NO === report.verified)
+        return `${word}${String(count(Verified.NO))} of ${plural(total, 'check')} did not hold`;
+    if (Verified.YES === report.verified)
+        return `${word}${String(total)} of ${plural(total, 'check')} held`;
+    return `${word}${String(total - count(Verified.YES) - count(Verified.NO))} of ${plural(total, 'check')} undecided`;
+}
+/** The report as markdown: the verdict, each claim with its evidence, then what the run left. */
+export function renderRunReport(report) {
+    const claims = report.claims
+        .slice(0, CLAIMS_SHOWN)
+        .map((c) => `- ${c.verified}: ${c.claim}${c.evidence === undefined ? '' : ` (${c.evidence})`}`);
+    const more = report.claims.length - CLAIMS_SHOWN;
+    const { saved, replayed } = report.flows;
+    const flows = 0 === saved.length && 0 === replayed.length
+        ? [`- ${Said.NO_FLOWS}`]
+        : [
+            ...(0 === saved.length ? [] : [`- ${Said.FLOWS_SAVED}: ${saved.join(', ')}`]),
+            ...(0 === replayed.length
+                ? []
+                : [
+                    `- ${Said.FLOWS_REPLAYED}: ${replayed.map((r) => `${r.name} (${r.verified})`).join(', ')}`,
+                ]),
+        ];
+    const time = report.firstVerdictMs === undefined
+        ? seconds(report.wallMs)
+        : `${seconds(report.wallMs)}, ${Said.FIRST_VERDICT} ${seconds(report.firstVerdictMs)}`;
+    return [
+        headline(report),
+        ...claims,
+        ...(0 < more ? [`- (+${String(more)} more claims)`] : []),
+        ...(0 === report.caught.length ? [] : [`- ${Said.CAUGHT}: ${report.caught.join('; ')}`]),
+        ...flows,
+        `- ${Said.MEMORY}: ${plural(report.memory.written, 'note')} written, ${String(report.memory.read)} read`,
+        `- ${Said.TIME}: ${time}`,
+        ...(report.cloud === undefined ? [] : [`- ${report.cloud}`]),
+    ].join('\n');
+}
+/** The calls that end an agent's run, by their own name or as an action of a merged tool. */
+export function endsRun(tool, args) {
+    const action = asString(args['action']);
+    switch (tool) {
+        case ReticleTool.END_SESSION:
+        case ReticleTool.YIELD:
+        case ReticleTool.LEASE_RELEASE:
+            return true;
+        case ReticleTool.SESSION:
+            return 'end' === action || 'yield' === action;
+        case ReticleTool.LEASE:
+            return 'release' === action;
+        default:
+            return false;
+    }
+}
+/** `reticle_intent` actions that write a statement, and the ones that read them back. */
+const IntentWrite = { RECORD: 'record', DECLARE: 'declare' };
+const INTENT_READS = new Set(['list', 'index', 'subject', 'get']);
+const isRecord = (value) => null !== value && 'object' === typeof value && !Array.isArray(value);
+/** What an answer says the run saved or read. An answer that refused counts for nothing. */
+export function noteToolResult(ledger, tool, args, result) {
+    if (!isRecord(result) || result['error'] !== undefined)
+        return;
+    if (ReticleTool.FLOW_SAVE === tool || ReticleTool.FLOW_SAVE_RECORDED === tool) {
+        const name = result['name'];
+        if ('string' === typeof name)
+            ledger.flowSaved(name);
+        return;
+    }
+    const action = asString(args['action']);
+    if (ReticleTool.INTENT === tool) {
+        // The intent ledger in `.reticle/intent/` is the memory an unlinked project has.
+        if (IntentWrite.RECORD === action)
+            ledger.memoryWritten();
+        const declared = args['intents'];
+        if (IntentWrite.DECLARE === action && Array.isArray(declared))
+            ledger.memoryWritten(declared.length);
+        if (action !== undefined && INTENT_READS.has(action))
+            ledger.memoryRead([JSON.stringify(result)]);
+        return;
+    }
+    if (ReticleTool.MEMORY !== tool)
+        return;
+    if ('add' === action && result['added'] !== undefined)
+        ledger.memoryWritten();
+    const known = result['known'];
+    if (Array.isArray(known))
+        ledger.memoryRead(known.map((entry) => JSON.stringify(entry)));
+}
+/** The report as an answer field, or no field when the ledger holds no run. Empties the ledger. */
+export function runReportField(ledger, root, env, now) {
+    if (ledger.isEmpty())
+        return {};
+    const taken = ledger.take(now);
+    const silenced = env[UPGRADE_HINT_SILENCE_ENV] !== undefined;
+    const linked = root === undefined || linkedToPlatform(root, env);
+    const report = silenced || linked ? taken : { ...taken, cloud: CLOUD_VALUE_LINE };
+    return {
+        [RUN_REPORT_FIELD]: {
+            report,
+            markdown: renderRunReport(report),
+            instruction: RUN_REPORT_INSTRUCTION,
+        },
+    };
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Provider capabilities handed to features as ports: a suite fixture to seed from, save/restore,
+ * slowing the page and breaking it. Each is `undefined` when the provider cannot do it. They sit on
+ * the tool side because a feature reaching into the input layer directly would depend on a driver.
+ */
+import type { RealInputProvider } from '../../portal/input/real-input.js';
+import { type StorageFixturePort } from '../../portal/input/storage-fixture.js';
+import { type NetworkMutationPort } from '../../portal/input/network-mutation.js';
+import type { Perturbation, SeedStorage } from '@reticlehq/core';
+/**
+ * The state a suite should boot its flows from: whatever the agent is already sitting in.
+ *
+ * This is the join the fixture work was building toward. A suite's flows each start from cold, so
+ * fifty of them prove the login works fifty times — and the flow that LOGS OUT leaves every flow
+ * after it signed out, which no navigation repairs, because the problem is not where the subject is
+ * but what it holds. A seed is applied to an isolated context BEFORE the first navigation, which is
+ * exactly and only when a fixture can work.
+ *
+ * Best-effort, deliberately. A fixture is an OPTIMISATION over running from cold, and running from
+ * cold is correct: a suite that refused to start because a cookie jar could not be read would have
+ * traded a slow answer for no answer. Every "no" here — no provider, no storage support, nothing
+ * driven, a browser that threw, nothing worth seeding — produces the same honest `undefined`, and
+ * the suite runs exactly as it did before any of this existed.
+ */
+export declare function suiteFixtureSeed(realInput: RealInputProvider | undefined, appUrl: string): Promise<SeedStorage | undefined>;
+/**
+ * A way to make this session's page SLOW on purpose, or nothing.
+ *
+ * The third of these seams, for the same reason as the other two: a feature reaching into the input
+ * layer directly is a feature depending on a driver, and the boundary guard asks about it.
+ *
+ * Installs delays and NOTHING else. A rule that carried a status or a body would substitute a
+ * response the server never sent, and an app raced against invented data produces invented races —
+ * a fabricated defect handed to somebody at 3am, which is worse than finding nothing.
+ */
+export declare function sessionPerturbationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<{
+    slow(rules: readonly Perturbation[]): Promise<void>;
+    clear(): Promise<void>;
+} | undefined>;
+/**
+ * Save/restore for this session's page, or nothing.
+ *
+ * The same job as `suiteFixtureSeed` next door, stopping one step earlier: that one captures and
+ * converts, this hands back the PORT so a caller can re-apply what it captured later. It lives here
+ * for the reason written above — a feature reaching into the input layer directly is a feature
+ * depending on a driver, and the boundary guard asks about it. It asked.
+ */
+export declare function suiteFixturePort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<StorageFixturePort | undefined>;
+/**
+ * A way to break this session's page, or nothing.
+ *
+ * Sits beside `suiteFixtureSeed` because it is the same shape of job: turning a provider capability
+ * into something a feature can use, on the one side of the graph that is allowed to know about both.
+ * A flow tool reaching into the input layer directly would be a feature depending on a driver, which
+ * is the reach the boundary guard exists to ask about.
+ */
+export declare function sessionMutationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<NetworkMutationPort | undefined>;

package/dist/surface/tools/session-ports.js

@@ -0,0 +1,102 @@
+import { fixturePortFor, seedFromStorageState, } from '../../portal/input/storage-fixture.js';
+import { mutationPortFor } from '../../portal/input/network-mutation.js';
+/**
+ * The state a suite should boot its flows from: whatever the agent is already sitting in.
+ *
+ * This is the join the fixture work was building toward. A suite's flows each start from cold, so
+ * fifty of them prove the login works fifty times — and the flow that LOGS OUT leaves every flow
+ * after it signed out, which no navigation repairs, because the problem is not where the subject is
+ * but what it holds. A seed is applied to an isolated context BEFORE the first navigation, which is
+ * exactly and only when a fixture can work.
+ *
+ * Best-effort, deliberately. A fixture is an OPTIMISATION over running from cold, and running from
+ * cold is correct: a suite that refused to start because a cookie jar could not be read would have
+ * traded a slow answer for no answer. Every "no" here — no provider, no storage support, nothing
+ * driven, a browser that threw, nothing worth seeding — produces the same honest `undefined`, and
+ * the suite runs exactly as it did before any of this existed.
+ */
+export async function suiteFixtureSeed(realInput, appUrl) {
+    if (realInput === undefined) {
+        return undefined;
+    }
+    try {
+        const port = await fixturePortFor(realInput, appUrl);
+        if (port === undefined) {
+            return undefined;
+        }
+        return seedFromStorageState(await port.capture(), appUrl);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A way to make this session's page SLOW on purpose, or nothing.
+ *
+ * The third of these seams, for the same reason as the other two: a feature reaching into the input
+ * layer directly is a feature depending on a driver, and the boundary guard asks about it.
+ *
+ * Installs delays and NOTHING else. A rule that carried a status or a body would substitute a
+ * response the server never sent, and an app raced against invented data produces invented races —
+ * a fabricated defect handed to somebody at 3am, which is worse than finding nothing.
+ */
+export async function sessionPerturbationPort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    const setMocks = realInput.setMocks?.bind(realInput);
+    if (setMocks === undefined) {
+        return undefined;
+    }
+    if (!(await realInput.isAvailableFor(appUrl))) {
+        return undefined;
+    }
+    return {
+        slow: async (rules) => {
+            await setMocks(appUrl, [...rules]);
+        },
+        /** Clearing is the undo. A page left slowed is damage the next run inherits. */
+        clear: async () => {
+            await setMocks(appUrl, []);
+        },
+    };
+}
+/**
+ * Save/restore for this session's page, or nothing.
+ *
+ * The same job as `suiteFixtureSeed` next door, stopping one step earlier: that one captures and
+ * converts, this hands back the PORT so a caller can re-apply what it captured later. It lives here
+ * for the reason written above — a feature reaching into the input layer directly is a feature
+ * depending on a driver, and the boundary guard asks about it. It asked.
+ */
+export async function suiteFixturePort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    try {
+        return await fixturePortFor(realInput, appUrl);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A way to break this session's page, or nothing.
+ *
+ * Sits beside `suiteFixtureSeed` because it is the same shape of job: turning a provider capability
+ * into something a feature can use, on the one side of the graph that is allowed to know about both.
+ * A flow tool reaching into the input layer directly would be a feature depending on a driver, which
+ * is the reach the boundary guard exists to ask about.
+ */
+export async function sessionMutationPort(realInput, appUrl) {
+    if (realInput === undefined || appUrl === undefined) {
+        return undefined;
+    }
+    try {
+        return await mutationPortFor(realInput, appUrl);
+    }
+    catch {
+        // A provider that cannot answer is the same answer as a provider that cannot break anything.
+        return undefined;
+    }
+}

package/dist/surface/tools/tool-kit.d.ts

@@ -13,6 +13,7 @@ import type { BaselineStore } from '../../memory/project/baselines.js';
 import type { RecordingStore } from '../../language/flows/recording/tape/recordings.js';
 import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
 import type { ArtifactRoot } from '../../memory/project/artifact-root.js';
+import type { NonceMinter } from '../../portal/production/production-activation.js';
 import type { FlowStore } from '../../language/flows/flows.js';
 import type { ProjectStore } from '../../memory/project/project-store.js';
 import type { AnnotationStore } from '../../language/flows/stores/annotation-store.js';
@@ -76,6 +77,11 @@ export interface ToolDeps<Ext = unknown> {
      * it, so two agents on one origin never share a tab (#1226). Absent ⇒ every acquire gets its own.
      */
     attachId?: string;
+    /**
+     * The coding agent's own session id, as its MCP server announced it on connect. Joins this
+     * connection's episode to the agent hooks' records. Absent: the agent announced none.
+     */
+    agentSession?: string;
     /** Run one sync cycle with the platform now, for `reticle_project { push }`. Absent: not linked here. */
     syncNow?: () => Promise<unknown>;
     /** Wires the app on the agent's first use, instead of at installation. Absent: tell, do not wire. */
@@ -88,6 +94,8 @@ export interface ToolDeps<Ext = unknown> {
         url: string;
         notice: string;
     } | undefined>;
+    /** The one dev server running in the caller's project folder, for a lease that names no url. */
+    projectAppUrl?: () => Promise<string | undefined>;
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */
@@ -140,6 +148,11 @@ export interface ToolDeps<Ext = unknown> {
      * ToolDeps keeps working; absent falls back to the default port.
      */
     bridgePort?: number;
+    /**
+     * The bridge's session-nonce registry. Local callers only: a production lease mints its nonce
+     * here. Absent where no bridge runs in this process, and a production lease then refuses.
+     */
+    nonces?: NonceMinter;
     /**
      * A consumer's OWN dependencies, carried through untouched.
      *
@@ -159,13 +172,13 @@ export interface ToolDeps<Ext = unknown> {
 export interface ToolDef<Ext = unknown> {
     name: string;
     description: string;
-    inputSchema: z.ZodRawShape;
+    inputSchema: Record<string, z.ZodType>;
     /**
      * JSON Schema-compatible output schema for this tool. When present, the MCP server advertises it
      * in the tools/list response so schema-aware clients (like @reticlehq/cli) can validate outputs and
      * compose tool calls safely. Also drives TOON encoding for snapshot/query results.
      */
-    outputSchema?: z.ZodRawShape;
+    outputSchema?: Record<string, z.ZodType>;
     /**
      * One concrete, valid call — the shape, not the prose.
      *
@@ -268,6 +281,8 @@ export declare const EnvelopeKey: {
     readonly TALK_TO_US: "talk_to_us";
     /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
     readonly VERSION_SKEW: "version_skew";
+    /** On each verdict from a page whose SDK is behind the daemon. See session-info.ts. */
+    readonly SDK_BEHIND: "sdk_behind";
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
     readonly FEEDBACK_UNDELIVERED: "feedback_undelivered";
     /** Once per project: verified runs exist only on this machine. See platform-moment.ts. */
@@ -290,6 +305,8 @@ export declare const EnvelopeKey: {
     readonly ZERO_INSTALL: "zero_install";
     /** Once-per-session advisory lines an agent's own call carries. See agent/notices.ts. */
     readonly NOTICES: "notices";
+    /** The end-of-run report, on the call that ends an agent's run. See run-report.ts. */
+    readonly RUN_REPORT: "runReport";
 };
 export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
 /**
@@ -305,10 +322,47 @@ export declare const HOST_STUB_NOTE: string;
  * `steps`) takes one per step, inside the sequence, rather than one for the whole call.
  */
 export declare const STEP_SHOT_TOOLS: ReadonlySet<string>;
+/**
+ * Tools that DRIVE the page. An action with no verdict after it is the signature of the loop
+ * breaking mid-task — see `abandonedActions`. `act_and_wait` is one of these AND a verification, so
+ * it settles its own action, which is exactly right: it is the tool that does both.
+ */
+export declare const ACTION_TOOLS: ReadonlySet<string>;
+/**
+ * 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 in `runTool` never runs for them — resolve again there so we can refuse with
+ * the skew sentence before Playwright lies about a closed page.
+ */
+export declare const CDP_TOOLS: ReadonlySet<string>;
+/**
+ * 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.
+ *
+ * Over-inclusion is the safe direction here and under-inclusion is not dangerous either: both ends
+ * produce a REFUSAL naming the two tabs, never a silent drive against the wrong one.
+ */
+export declare const REF_MINTING_TOOLS: ReadonlySet<string>;
+/**
+ * The live-session tools whose result MUST carry the
+ * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
+ * can never return a healthy-looking result from any of these. `runTool` is the single choke point
+ * (mcp.ts + tool-invoker.ts) that splices health on (`invoke-tool.ts`); the guard test asserts the set is exhaustive.
+ */
+export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
+/**
+ * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
+ * disk (capabilities/contract/flow/project), drain a buffer, or steer session lifecycle. They are
+ * exempt from the health splice ON PURPOSE. Kept explicit so the guard test can force every new
+ * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
+ */
+export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
 /** A step-screenshot tool, with the one sentence about its screenshot on the end of its description. */
 export declare function withScreenshotDoc(tool: ToolDef): ToolDef;
 /** The one sentence every tool that takes a step screenshot says about it. */
-export declare const SCREENSHOT_DOC = " `screenshot.path` is a picture of the page at the outcome: open it when the look of the page matters; reading it is your choice.";
+export declare const SCREENSHOT_DOC = " `screenshot.path` is a picture of the page at the outcome: open it when the look of the page matters; reading it is your choice. When `pending: true`, the file may still be in write; wait before you read it.";
 /**
  * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
  * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
@@ -317,7 +371,7 @@ export declare const SCREENSHOT_DOC = " `screenshot.path` is a picture of the pa
  * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
  * whole release, and every key that went missing was a channel nobody could see was missing.
  */
-export declare const sessionEnvelopeShape: z.ZodRawShape;
+export declare const sessionEnvelopeShape: Record<string, z.ZodType>;
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
 export declare function commandOrThrow(deps: ToolDeps, sessionId: string | undefined, name: ReticleCommand, args: Record<string, unknown>): Promise<unknown>;
 /** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */

package/dist/surface/tools/tool-kit.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { asRecord, asString, ReticleCommand, ReticleTool, SnapshotMode, } from '@reticlehq/core';
+import { asRecord, asString, ReticleCommand, ReticleTool, SnapshotMode, RUN_REPORT_FIELD, } from '@reticlehq/core';
 import { normalizeLines } from '../../memory/project/baselines.js';
 import { SnapshotCache } from './read/snapshot-delta.js';
 /**
@@ -77,6 +77,8 @@ export const EnvelopeKey = {
     TALK_TO_US: 'talk_to_us',
     /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
     VERSION_SKEW: 'version_skew',
+    /** On each verdict from a page whose SDK is behind the daemon. See session-info.ts. */
+    SDK_BEHIND: 'sdk_behind',
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
     FEEDBACK_UNDELIVERED: 'feedback_undelivered',
     /** Once per project: verified runs exist only on this machine. See platform-moment.ts. */
@@ -99,6 +101,8 @@ export const EnvelopeKey = {
     ZERO_INSTALL: 'zero_install',
     /** Once-per-session advisory lines an agent's own call carries. See agent/notices.ts. */
     NOTICES: 'notices',
+    /** The end-of-run report, on the call that ends an agent's run. See run-report.ts. */
+    RUN_REPORT: RUN_REPORT_FIELD,
 };
 /**
  * The sentence every session-bound result carries while its leased tab runs on a stubbed shell.
@@ -119,6 +123,132 @@ export const STEP_SHOT_TOOLS = new Set([
     ReticleTool.NAVIGATE,
     ReticleTool.ASSERT,
 ]);
+/**
+ * Tools that DRIVE the page. An action with no verdict after it is the signature of the loop
+ * breaking mid-task — see `abandonedActions`. `act_and_wait` is one of these AND a verification, so
+ * it settles its own action, which is exactly right: it is the tool that does both.
+ */
+export const ACTION_TOOLS = new Set([
+    ReticleTool.ACT,
+    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 in `runTool` never runs for them — resolve again there so we can refuse with
+ * the skew sentence before Playwright lies about a closed page.
+ */
+export const CDP_TOOLS = new Set([
+    ReticleTool.SCREENSHOT,
+    ReticleTool.VISUAL_DIFF,
+    ReticleTool.NETWORK_MOCK,
+    ReticleTool.VIEWPORT,
+    // Breaks a request through the same Playwright route `reticle_network_mock` uses, so it fails the
+    // same way under version skew and must be refused with the same sentence.
+    ReticleTool.FLOW_MUTATE,
+]);
+/**
+ * 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.
+ *
+ * Over-inclusion is the safe direction here and under-inclusion is not dangerous either: both ends
+ * produce a REFUSAL naming the two tabs, never a silent drive against the wrong one.
+ */
+export const REF_MINTING_TOOLS = new Set([
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    // The same three merged, on the `merged` surface. Its `state` action mints nothing, and
+    // over-inclusion is the safe direction here: the worst case is a refusal naming two tabs.
+    ReticleTool.LOOK,
+    ReticleTool.EXPLORE,
+    // `crawl` mints refs for the controls it drives and `coverage` for the ones it reports untouched.
+    // Both are actions on the merged verify tool now.
+    ReticleTool.VERIFY,
+]);
+/**
+ * The live-session tools whose result MUST carry the
+ * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
+ * can never return a healthy-looking result from any of these. `runTool` is the single choke point
+ * (mcp.ts + tool-invoker.ts) that splices health on (`invoke-tool.ts`); the guard test asserts the set is exhaustive.
+ */
+export const SESSION_BOUND_TOOLS = new Set([
+    // Resolves a session and reads its event window (`session.eventsSince`), exactly as OBSERVE and
+    // NETWORK do. Without this it runs with no session and answers from nothing.
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    // All four merged. Every member here is session-bound, so unlike `verify` there is no split to
+    // adjudicate — the merged tool inherits the only answer its members ever gave.
+    ReticleTool.LOOK,
+    // Merged change/flows/affected/coverage/crawl. Its members were SPLIT across bound and exempt —
+    // coverage/change/crawl bound, flow_verify exempt because it returns its own suite contract — and
+    // a merged tool has to be one or the other. Bound is the right side: `crawl` drives the app
+    // itself, so a throttled or event-dropping tab is exactly the condition its verdict depends on,
+    // and dropping the health disclosure there to protect a sibling's output shape would trade an
+    // honesty signal for a formatting preference.
+    ReticleTool.VERIFY,
+    ReticleTool.ACT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.OBSERVE,
+    ReticleTool.WAIT_FOR,
+    ReticleTool.ASSERT,
+    // Reads the live page as well as the event window, so a throttled tab can make it compare a stale
+    // render against fresh data — exactly the case the health envelope exists to disclose.
+    ReticleTool.RECONCILE,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.ANIMATIONS,
+    ReticleTool.BASELINE, // merged save/list/diff — save+diff are live reads
+    ReticleTool.RECORD, // merged start/stop — both live
+    ReticleTool.REPLAY,
+    ReticleTool.CLOCK,
+    ReticleTool.STATE,
+    ReticleTool.STORAGE,
+    ReticleTool.EXPLORE,
+    ReticleTool.SCROLL_TO,
+    ReticleTool.NAVIGATE,
+]);
+/**
+ * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
+ * disk (capabilities/contract/flow/project), drain a buffer, or steer session lifecycle. They are
+ * exempt from the health splice ON PURPOSE. Kept explicit so the guard test can force every new
+ * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
+ */
+export const SESSION_EXEMPT_TOOLS = new Set([
+    ReticleTool.CAPABILITIES, // has a fromDisk mode with no live session
+    ReticleTool.CONTRACT_SAVE, // persists the registry to disk
+    ReticleTool.FLOW_SAVE, // sessionId only scopes the write to the app's flow subdir; disk-side
+    ReticleTool.FLOW, // merged list/load/delete — sessionId only scopes the project; all disk-side
+    ReticleTool.FLOW_REPLAY, // returns its own FlowReplayResult contract (+ auto-records a run)
+    ReticleTool.FLOW_SAVE_RECORDED, // reads the recording buffer, writes disk
+    // FLOW_HEAL is no longer a name runTool ever sees: it became `reticle_verify {action:"heal"}`,
+    // and VERIFY is already listed here, so the exemption is inherited from the parent. Left as a
+    // dangling name it would be a lie this file's own test 6 is written to catch.
+    ReticleTool.INTENT, // reads/writes .reticle/intent/; sessionId only picks the project
+    ReticleTool.CONTEXT, // folds the journal + intent ledger; must still answer when nothing is connected
+    ReticleTool.MAP, // folds the journals on disk into the App Graph; answers with no tab 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
+    ReticleTool.VISUAL_DIFF, // own contract (matched/ratio/region)
+    ReticleTool.NETWORK_MOCK, // own contract (applied/count); provider-driven, not a live-DOM read
+    ReticleTool.VIEWPORT, // own contract (applied/width/height); provider-driven, not a live-DOM read
+    ReticleTool.ANNOTATE, // annotates a recording's steps; pure disk-side metadata, no live DOM read
+    ReticleTool.LEASE, // merged acquire/release — its sessionId is a pool lease id, not a live session
+    // Its sessionId only enriches the report with the tab's runtime/engine, and it must stay callable
+    // when NO session exists — "nothing ever connected" is feedback we especially want.
+    ReticleTool.FEEDBACK,
+]);
 /** A step-screenshot tool, with the one sentence about its screenshot on the end of its description. */
 export function withScreenshotDoc(tool) {
     return STEP_SHOT_TOOLS.has(tool.name)
@@ -126,7 +256,7 @@ export function withScreenshotDoc(tool) {
         : tool;
 }
 /** The one sentence every tool that takes a step screenshot says about it. */
-export const SCREENSHOT_DOC = ' `screenshot.path` is a picture of the page at the outcome: open it when the look of the page matters; reading it is your choice.';
+export const SCREENSHOT_DOC = ' `screenshot.path` is a picture of the page at the outcome: open it when the look of the page matters; reading it is your choice. When `pending: true`, the file may still be in write; wait before you read it.';
 /**
  * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
  * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
@@ -147,16 +277,18 @@ export async function commandOrThrow(deps, sessionId,
 name, args) {
     const session = deps.sessions.resolve(sessionId);
     const result = await session.command(name, args);
-    if (!result.ok)
+    if (!result.ok) {
         throw new Error(result.error ?? `command '${name}' failed`);
+    }
     return result.result;
 }
 /** Full DOM snapshot → normalized tree lines + route, for tools that diff or scan the page. */
 export async function snapshotTree(deps, sessionId) {
     const session = deps.sessions.resolve(sessionId);
     const result = await session.command(ReticleCommand.SNAPSHOT, { mode: SnapshotMode.FULL });
-    if (!result.ok)
+    if (!result.ok) {
         throw new Error(result.error ?? 'snapshot failed');
+    }
     const snap = (result.result ?? {});
     return { lines: normalizeLines(snap.tree ?? ''), route: snap.status?.route ?? '' };
 }
@@ -181,14 +313,16 @@ export function callSecrets() {
  * telemetry — ever sees them.
  */
 export function takeCallSecrets(args) {
-    if (!(CALL_SECRETS_ARG in args))
+    if (!(CALL_SECRETS_ARG in args)) {
         return { secrets: undefined, rest: args };
+    }
     const { [CALL_SECRETS_ARG]: raw, ...rest } = args;
     const secrets = {};
     for (const [key, value] of Object.entries(asRecord(raw))) {
         const text = asString(value);
-        if (text !== undefined && 0 < text.length)
+        if (text !== undefined && 0 < text.length) {
             secrets[key] = text;
+        }
     }
     return { secrets, rest };
 }

package/dist/surface/tools/tool-surface.d.ts

@@ -1,3 +1,4 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolDef } from './tool-kit.js';
 /**
  * There is ONE tool surface. This is not a menu.
@@ -193,3 +194,4 @@ export declare function describeToolSurface(active: ToolSurface, requested?: str
  */
 export declare function defaultAdvertisedNames(): readonly string[];
 export declare function filterTools(tools: ToolDef[], surface: ToolSurface): ToolDef[];
+export declare function toolAnnotations(name: string): ToolAnnotations;