@reticlehq/server 2.14.0 → 3.2.0

package/dist/version/version-skew.js

@@ -1,147 +0,0 @@
-/**
- * Does this peer speak our contract? The daemon is the only thing that asks.
- *
- * Reticle is three separately-installed pieces — the SDK in the page, this daemon, and the MCP
- * server the agent spawns — upgraded independently and therefore drifting constantly. Each pair
- * fails the same silent way: `protocolVersion` still matches, the connection succeeds, and only
- * BEHAVIOUR disagrees. A user hit exactly that with a 2.2.1 SDK against a 2.3.0 daemon and saw a
- * bare `-32000` with nothing on either side naming a version.
- *
- * Two decisions shape this file.
- *
- * The daemon is the SINGLE judge. Every piece announces itself at a connect it already makes — the
- * SDK in HELLO, the CLI and the MCP server over /status — and comparing happens here, once. Three
- * independent pairwise checks would be three copies to keep in step and three separate complaints
- * about one upgrade; a table in one place can say what is actually true: which pieces disagree, and
- * which one is behind.
- *
- * The signal is the CONTRACT FINGERPRINT, not the version. Version equality is wrong in both
- * directions: it fires on 2.4.0-vs-2.4.1 where nothing changed — so every patch release makes every
- * un-upgraded app cry wolf, and the warning becomes noise — and it cannot fire at all for two
- * different BUILDS of one version number, which is exactly what a stale daemon and a cached npx
- * install are. The fingerprint is derived from core's wire vocabulary, so it moves when a name on
- * the wire changes and stays put when internals do. Versions still ride along, because they are what
- * a human acts on.
- */
-import { resolveSdkFix } from './sdk-fix.js';
-/** Which pair disagreed. Named so the nudge can report each independently. */
-export const SkewPair = {
-    /** The SDK in the page vs this daemon. */
-    SDK: 'sdk',
-    /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
-    DAEMON: 'daemon',
-};
-function versionPhrase(peer, self) {
-    return peer.version === undefined
-        ? `${peer.what} is on an unknown version; this daemon is ${self.version}`
-        : `${peer.what} is ${peer.version}; this daemon is ${self.version}`;
-}
-/**
- * The one sentence to tell the agent, or undefined when the pair agrees.
- *
- * Silent when the fingerprints MATCH, whatever the versions say — that is the point: a patch bump
- * that changed no wire name is not skew, and warning about it is how a real warning gets ignored.
- *
- * A peer with no fingerprint is treated as skewed ONLY when its version also differs from ours: the
- * field is absent exactly on builds that predate it, so "no fingerprint AND a different version" is
- * a build provably older than this daemon. With neither signal there is nothing to go on, and
- * inventing a warning would be as dishonest as staying silent about a real one.
- */
-export function describeSkew(peer, self) {
-    if (peer.contract !== undefined && peer.contract === self.contract)
-        return undefined;
-    if (peer.contract === undefined) {
-        if (peer.version === undefined || peer.version === self.version)
-            return undefined;
-        return (`version skew: ${versionPhrase(peer, self)}, and it is too old to report which wire contract ` +
-            `it speaks. They connect anyway and then disagree about behaviour, which usually surfaces as ` +
-            `a bare -32000 with nothing naming a version. ${peer.fix}`);
-    }
-    return (`version skew: ${versionPhrase(peer, self)}, and they speak DIFFERENT wire contracts ` +
-        `(${peer.contract} vs ${self.contract}) — so this is a real mismatch, not a harmless patch ` +
-        `difference. Tools will behave in ways neither side reports. ${peer.fix}`);
-}
-/**
- * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
- *
- * Names the framework-neutral sensor and plain npm, because those are the answers that are never
- * actively wrong. When a project directory IS available, `resolveSdkFix` / `sdkFixForDirectory`
- * in sdk-fix.ts read the real packages and package manager — this used to hardcode
- * `@reticlehq/react` and told Vue projects to install a React package (#618).
- */
-export function sdkFix(daemonVersion) {
-    return resolveSdkFix(daemonVersion);
-}
-/**
- * Compare two of our own version strings. Numeric dotted compare, prerelease tags ignored: both
- * sides are Reticle package versions, so this never sees a range or build metadata. Undefined when
- * either side does not parse, so the caller can decline to guess a direction.
- */
-function compareVersions(a, b) {
-    const parts = (v) => {
-        const head = v.split('-')[0];
-        if (head === undefined)
-            return undefined;
-        const nums = head.split('.').map((n) => parseInt(n, 10));
-        return nums.some(isNaN) ? undefined : nums;
-    };
-    if (a === undefined)
-        return undefined;
-    const left = parts(a);
-    const right = parts(b);
-    if (left === undefined || right === undefined)
-        return undefined;
-    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
-        const diff = (left[i] ?? 0) - (right[i] ?? 0);
-        if (0 !== diff)
-            return diff;
-    }
-    return 0;
-}
-/**
- * The fix line for another Reticle process that disagrees with the daemon it attached to.
- *
- * Branches on DIRECTION, which the old unconditional `reticle stop` did not (#618). Restarting the
- * daemon converges the pair only when the daemon is the OLDER half. When the daemon is newer — the
- * common case, because the MCP registration is deliberately unpinned and so resolves fresh while a
- * long-lived daemon does not — `reticle stop` starts another newer daemon and leaves the same two
- * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
- * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
- *
- * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
- * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
- * and the advice depends on which piece is behind, not on who noticed.
- */
-export function daemonFix(daemonVersion, agentVersion) {
-    const order = agentVersion === undefined ? undefined : compareVersions(daemonVersion, agentVersion);
-    if (order !== undefined && order > 0) {
-        return ('The daemon is NEWER than this process, so `reticle stop` will not converge them — it would ' +
-            'replace it with another newer daemon and leave the same mismatch. Tell the human to restart ' +
-            'the agent so it spawns a current MCP server (or update the package it spawns), then retry.');
-    }
-    return ('A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
-        '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
-        'it (other agents on that daemon will need to reconnect).');
-}
-/**
- * Playwright wording when a CDP call cannot bind to the page.
- *
- * Under SDK/daemon version skew this text is a LIE: the page is still connected (DOM tools work),
- * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
- * (#688). Matched only so we can replace it with the skew sentence already on the session.
- */
-const PLAYWRIGHT_CLOSED_ERROR = /target (?:page|context|browser) has been closed|browser has been closed|browser has disconnected/i;
-/** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
-export function isPlaywrightClosedError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return PLAYWRIGHT_CLOSED_ERROR.test(message);
-}
-/**
- * Replace a closed-target throw with the session's skew sentence when we already know the pair is
- * mismatched. Undefined when there is no skew to name, or the throw is something else.
- */
-export function rewriteClosedAsSkew(error, skew) {
-    if (skew === undefined || !isPlaywrightClosedError(error))
-        return undefined;
-    return new Error(skew);
-}

package/dist/visual/visual-store.d.ts

@@ -1,22 +0,0 @@
-import type { FileSystemPort } from '../project/fs-port.js';
-/**
- * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
- * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
- */
-export declare class VisualStore {
-    #private;
-    constructor(fs: FileSystemPort, root: string);
-    /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
-     *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
-    baselinePath(name: string, runtime?: string): string;
-    /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
-    diffPath(name: string, runtime?: string): string;
-    /** True iff a valid name and a baseline PNG exists on disk. */
-    hasBaseline(name: string, runtime?: string): Promise<boolean>;
-    /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
-    saveBaseline(name: string, png: Uint8Array, runtime?: string): Promise<string>;
-    /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
-    readBaseline(name: string, runtime?: string): Promise<Uint8Array | undefined>;
-    /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
-    saveDiff(name: string, png: Uint8Array, runtime?: string): Promise<string>;
-}

package/dist/visual/visual-store.js

@@ -1,66 +0,0 @@
-import { isValidFlowName, visualDiffPath, visualDir, visualPath } from '../project/reticle-dir.js';
-/**
- * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
- * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
- */
-export class VisualStore {
-    #fs;
-    #root;
-    constructor(fs, root) {
-        this.#fs = fs;
-        this.#root = root;
-    }
-    /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
-     *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
-    baselinePath(name, runtime) {
-        if (!isValidFlowName(name))
-            throw new Error(`invalid visual baseline name: ${name}`);
-        return visualPath(this.#root, name, runtime);
-    }
-    /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
-    diffPath(name, runtime) {
-        if (!isValidFlowName(name))
-            throw new Error(`invalid visual diff name: ${name}`);
-        return visualDiffPath(this.#root, name, runtime);
-    }
-    /** True iff a valid name and a baseline PNG exists on disk. */
-    async hasBaseline(name, runtime) {
-        if (!isValidFlowName(name))
-            return false;
-        return this.#fs.exists(visualPath(this.#root, name, runtime));
-    }
-    /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
-    async saveBaseline(name, png, runtime) {
-        if (!isValidFlowName(name))
-            throw new Error(`invalid visual baseline name: ${name}`);
-        // The runtime's own directory, not the shared one — see visualDir.
-        await this.#fs.mkdir(visualDir(this.#root, runtime));
-        const path = visualPath(this.#root, name, runtime);
-        await this.#fs.writeFileBytes(path, png);
-        return path;
-    }
-    /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
-    async readBaseline(name, runtime) {
-        if (!isValidFlowName(name) || !(await this.#fs.exists(visualPath(this.#root, name, runtime)))) {
-            return undefined;
-        }
-        try {
-            return await this.#fs.readFileBytes(visualPath(this.#root, name, runtime));
-        }
-        catch (error) {
-            if (this.#fs.isNotFound(error))
-                return undefined; // exists/read TOCTOU race
-            throw error;
-        }
-    }
-    /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
-    async saveDiff(name, png, runtime) {
-        if (!isValidFlowName(name))
-            throw new Error(`invalid visual baseline name: ${name}`);
-        // Beside its baseline, or a diff lands in a directory the baseline is not in.
-        await this.#fs.mkdir(visualDir(this.#root, runtime));
-        const path = visualDiffPath(this.#root, name, runtime);
-        await this.#fs.writeFileBytes(path, png);
-        return path;
-    }
-}

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

@@ -1,26 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-/**
- * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
- * become a file-read oracle for whatever a compromised renderer names.
- *
- * Two layouts are accepted, and the pair is the whole subtlety:
- *
- * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
- *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
- * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
- *   SEPARATE package on the user's own upgrade schedule: an app still on the older
- *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
- *   start returning no image. It grants the daemon nothing it did not already have.
- *
- * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
- * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
- * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
- */
-export declare function isCapturePath(path: string): boolean;
-/**
- * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
- * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER
- * envelope (with a recommendation) instead of throwing when none is attached. Behavioral checks
- * stay the default; this is the complementary "does it look right" surface, never bundled in.
- */
-export declare const VISUAL_TOOLS: ToolDef[];

package/dist/visual/visual-tools.js

@@ -1,328 +0,0 @@
-import { z } from 'zod';
-import { AppRuntime, ReticleCommand, RETICLE_CAPTURE_FILE_PREFIX, VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason, } from '@reticlehq/core';
-import { ReticleTool } from '../tools/tool-names.js';
-import { sessionIdShape } from '../tools/tool-kit.js';
-import { ratioSchema } from '../tools/numeric-bounds.js';
-import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
-import { diffPng } from './visual-diff.js';
-import { VisualStore } from './visual-store.js';
-import { trackCaptureDirectory } from './capture-cleanup.js';
-import { readFile, unlink } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { basename, dirname } from 'node:path';
-const rectShape = z.object({
-    x: z.number(),
-    y: z.number(),
-    width: z.number(),
-    height: z.number(),
-});
-function screenshotProvider(deps) {
-    const p = deps.realInput;
-    return p !== undefined && 'function' === typeof p.screenshot
-        ? p
-        : undefined;
-}
-/** The "you need a driven browser" envelope, shared by both visual tools. */
-const noProvider = {
-    ok: false,
-    reason: VisualReason.NO_PROVIDER,
-    recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION,
-};
-function asBox(value) {
-    const b = asRecord(asRecord(value)['box']);
-    const x = asNumber(b['x']);
-    const y = asNumber(b['y']);
-    const w = asNumber(b['width']);
-    const h = asNumber(b['height']);
-    if (x === undefined || y === undefined || w === undefined || h === undefined)
-        return undefined;
-    if (w <= 0 || h <= 0)
-        return undefined;
-    return { x, y, width: w, height: h };
-}
-/** Build capture options from args: explicit clip > ref (resolved via INSPECT) > fullPage. */
-async function buildOpts(deps, sessionId, args) {
-    const clipArg = args['clip'];
-    if (clipArg !== undefined) {
-        const c = asRecord(clipArg);
-        const box = asBox({ box: c });
-        if (box !== undefined)
-            return { clip: box };
-    }
-    const ref = asString(args['ref']);
-    if (ref !== undefined) {
-        const session = deps.sessions.resolve(sessionId);
-        const res = await session.command(ReticleCommand.INSPECT, { ref });
-        const box = res.ok ? asBox(res.result) : undefined;
-        if (box !== undefined)
-            return { clip: box };
-    }
-    return true === args['fullPage'] ? { fullPage: true } : {};
-}
-/**
- * Ask the desktop shell to photograph its own window.
- *
- * Returns undefined for a plain web page (no capture helper) and for a desktop app that did not
- * install `@reticlehq/electron/main`. Deliberately NOT a screen-region capture: photographing
- * the glass returns whatever window is on top, which would save a picture of the user's editor as a
- * visual baseline — the exact false green Reticle exists to eliminate.
- */
-async function desktopCapture(deps, sessionId, fullPage) {
-    const session = deps.sessions.resolve(sessionId);
-    // A session that cannot take commands (no live browser behind it) simply has no pixels to give.
-    if (typeof session.command !== 'function')
-        return {};
-    const res = await session.command(ReticleCommand.CAPTURE, { fullPage });
-    if (!res.ok)
-        return {};
-    const r = asRecord(res.result);
-    if (r['ok'] !== true) {
-        // The shell refused a full-page capture it cannot do. That is a different answer from "capture
-        // broke", and the caller has to hear it — otherwise they read `fullPage` as honoured.
-        return r['reason'] === VisualReason.FULL_PAGE_UNSUPPORTED
-            ? { reason: VisualReason.FULL_PAGE_UNSUPPORTED }
-            : {};
-    }
-    const path = asString(r['path']);
-    if (path === undefined || !isCapturePath(path))
-        return {};
-    try {
-        const bytes = await readFile(path);
-        await unlink(path).catch(() => undefined);
-        trackCaptureDirectory(path);
-        return isCompletePng(bytes) ? { png: new Uint8Array(bytes) } : {};
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
- * become a file-read oracle for whatever a compromised renderer names.
- *
- * Two layouts are accepted, and the pair is the whole subtlety:
- *
- * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
- *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
- * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
- *   SEPARATE package on the user's own upgrade schedule: an app still on the older
- *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
- *   start returning no image. It grants the daemon nothing it did not already have.
- *
- * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
- * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
- * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
- */
-export function isCapturePath(path) {
-    if (!basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX))
-        return false;
-    const parent = dirname(path);
-    if (parent === tmpdir())
-        return true;
-    return dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
-}
-/**
- * A PNG is complete only if it ends with IEND. This check exists because a truncated image once
- * sailed through as a saved baseline: the tool answered `saved: true` with a path, and the file was
- * undecodable. A screenshot that cannot be read must fail loudly, never bank a corrupt baseline that
- * a later visual_diff will compare against.
- */
-function isCompletePng(bytes) {
-    if (bytes.byteLength < 12)
-        return false;
-    return 'IEND' === bytes.subarray(bytes.byteLength - 8, bytes.byteLength - 4).toString('ascii');
-}
-/**
- * Get pixels for a session, by whichever route exists.
- *
- * A driven/attached browser is captured through CDP — exact, and the only route that can do
- * `fullPage`. A desktop app has no CDP endpoint, so its own shell is asked instead. CDP is tried
- * FIRST and the desktop path is a genuine fallback, not an either/or: with a CDP endpoint attached
- * to one app and the screenshot aimed at a different (desktop) session, CDP fails and the shell
- * capture is still correct.
- *
- * `clip`/`ref` are honoured only on the CDP path — the shell photographs the whole window. Scoping is
- * left to the caller rather than cropped here, so a clip never silently becomes a full-window image.
- *
- * `fullPage` is different, because it cannot be emulated by cropping: only WebKitGTK (Tauri on Linux)
- * can render a full document offscreen. Where the shell cannot, it REFUSES and this reports
- * `full-page-unsupported` — a viewport image returned as though it were the whole scroll height is a
- * baseline that says nothing about the content below the fold, and a later diff would call it green.
- */
-/**
- * Which runtime this session is, for scoping a visual artifact.
- *
- * Undefined when the session cannot be resolved or its SDK never reported one — and undefined means
- * the flat legacy path, so a baseline captured before any of this keeps matching.
- */
-function runtimeOf(deps, sessionId) {
-    try {
-        return deps.sessions.resolve(sessionId).runtime;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function capture(deps, sessionId, args) {
-    const provider = screenshotProvider(deps);
-    if (provider !== undefined) {
-        const session = deps.sessions.resolve(sessionId);
-        const png = await provider.screenshot(session.url, await buildOpts(deps, sessionId, args));
-        // A driven browser renders the session's URL in a BROWSER — so the pixels are web even when the
-        // session named is a desktop window. Scoping those under the desktop runtime would corrupt that
-        // runtime's baseline with a picture of a different renderer.
-        if (png !== undefined)
-            return { png, runtime: AppRuntime.WEB };
-    }
-    // The window's own backing store, via the Electron/Tauri adapter — the only route whose pixels
-    // really are the desktop app.
-    const desktop = await desktopCapture(deps, sessionId, true === args['fullPage']);
-    if (desktop.png !== undefined)
-        return { png: desktop.png, runtime: runtimeOf(deps, sessionId) };
-    if (desktop.reason !== undefined)
-        return { reason: desktop.reason };
-    /*
-     * A LEASED page is a real browser page, so the pixels were always there — the visual tools simply
-     * had no route to them. Without this, `reticle_screenshot` answered "no provider" for every context
-     * an agent can actually acquire, which made visual regression impossible on exactly the isolated
-     * contexts the pool exists to hand out. Tried last: a CDP provider, when there is one, is driving
-     * the page the caller means, and a lease is the fallback rather than a competitor.
-     */
-    const leased = sessionId === undefined
-        ? undefined
-        : await deps.pool?.screenshotLease(sessionId, { fullPage: true === args['fullPage'] });
-    // A leased page is a real browser page, whatever the session is.
-    if (leased !== undefined)
-        return { png: leased, runtime: AppRuntime.WEB };
-    return {
-        reason: provider === undefined ? VisualReason.NO_PROVIDER : VisualReason.CAPTURE_FAILED,
-    };
-}
-function rectsFrom(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const rects = [];
-    for (const r of value) {
-        const box = asBox({ box: r });
-        if (box !== undefined)
-            rects.push(box);
-    }
-    return rects.length > 0 ? rects : undefined;
-}
-/**
- * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
- * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER
- * envelope (with a recommendation) instead of throwing when none is attached. Behavioral checks
- * stay the default; this is the complementary "does it look right" surface, never bundled in.
- */
-export const VISUAL_TOOLS = [
-    {
-        name: ReticleTool.SCREENSHOT,
-        example: { name: 'home' },
-        description: 'Capture a pixel screenshot of the DRIVEN page (needs `reticle drive`/RETICLE_CDP_URL — the SDK has no screenshotter) and save it as a visual baseline at .reticle/visual/<name>.png. { fullPage } for the whole scroll height, { ref } or { clip:{x,y,width,height} } for one element/region. Returns { saved:true, name, path, bytes } or { ok:false, reason } when no driven browser is attached.',
-        inputSchema: {
-            name: z
-                .string()
-                .describe('Baseline name — saved as .reticle/visual/<name>.png. Use the same name in reticle_visual_diff to compare.'),
-            fullPage: z
-                .boolean()
-                .optional()
-                .describe('Capture the full scroll height. Default: viewport only.'),
-            ref: z
-                .string()
-                .optional()
-                .describe('Element ref to screenshot (scopes to element bounding box). Omit for full page.'),
-            clip: rectShape
-                .optional()
-                .describe('Explicit { x, y, width, height } clip rectangle in page coordinates.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            ok: z.boolean(),
-            saved: z.boolean().optional(),
-            name: z.string().optional(),
-            path: z.string().optional(),
-            bytes: z.number().optional(),
-            reason: z.string().optional(),
-            recommendation: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const sessionId = asString(args['sessionId']);
-            const { png, reason, runtime } = await capture(deps, sessionId, args);
-            if (png === undefined) {
-                return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
-            }
-            const name = asString(args['name']) ?? 'default';
-            const store = new VisualStore(deps.fs, deps.reticleRoot);
-            // Scoped to the runtime that produced it: an Electron window, a Tauri webview and a browser
-            // tab do not render the same url the same way, and one shared baseline makes every
-            // cross-runtime diff wrong. See visualDir.
-            const path = await store.saveBaseline(name, png, runtime);
-            return { ok: true, saved: true, name, path, bytes: png.length };
-        },
-    },
-    {
-        name: ReticleTool.VISUAL_DIFF,
-        example: { baseline: 'home' },
-        description: 'Perceptually diff the DRIVEN page against a saved visual baseline (see reticle_screenshot). { masks:[{x,y,width,height}] } neutralizes volatile regions; { maxRatio } sets the pass tolerance (default 0). Returns { matched, changedPixels, totalPixels, ratio, region?, diffPath, dimensionMismatch } — the overlay diff is written to .reticle/visual/<baseline>.diff.png — or { ok:false, reason } (no-provider / baseline-missing).',
-        inputSchema: {
-            baseline: z
-                .string()
-                .describe('Baseline screenshot name (from reticle_screenshot). Used to compare with the current screenshot.'),
-            fullPage: z.boolean().optional(),
-            ref: z.string().optional(),
-            clip: rectShape.optional(),
-            masks: z.array(rectShape).optional(),
-            maxRatio: ratioSchema.optional(),
-            threshold: ratioSchema
-                .optional()
-                .describe('Pixel difference threshold (0–1). Default: 0.01.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            ok: z.boolean(),
-            matched: z.boolean().optional(),
-            changedPixels: z.number().optional(),
-            totalPixels: z.number().optional(),
-            ratio: z.number().optional(),
-            region: rectShape.optional(),
-            dimensionMismatch: z.boolean().optional(),
-            diffPath: z.string().optional(),
-            reason: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            const baseline = asString(args['baseline']) ?? '';
-            const store = new VisualStore(deps.fs, deps.reticleRoot);
-            // Capture FIRST, then fetch the baseline for the runtime that produced these pixels. Reading it
-            // by the session's runtime looked equivalent and is not: the route decides the renderer, so a
-            // desktop session captured through a driven browser must be compared against the WEB baseline,
-            // not the desktop one. Comparing across renderers is a confident wrong diff in one direction
-            // and a silently overwritten baseline in the other.
-            const sessionId = asString(args['sessionId']);
-            const { png: current, reason, runtime } = await capture(deps, sessionId, args);
-            if (current === undefined) {
-                return reason === VisualReason.NO_PROVIDER ? noProvider : { ok: false, reason };
-            }
-            // A baseline from another runtime is not missing by accident — it is a different rendering, and
-            // "no baseline for this one" is the honest answer.
-            const baselineBytes = await store.readBaseline(baseline, runtime);
-            if (baselineBytes === undefined)
-                return { ok: false, reason: VisualReason.BASELINE_MISSING };
-            const masks = rectsFrom(args['masks']);
-            const threshold = asNumber(args['threshold']);
-            const maxRatio = asNumber(args['maxRatio']);
-            const result = await diffPng(baselineBytes, current, {
-                ...(threshold !== undefined ? { threshold } : {}),
-                ...(maxRatio !== undefined ? { maxRatio } : {}),
-                ...(masks !== undefined ? { masks } : {}),
-            });
-            // Omit the raw diff bytes from the JSON result; persist them and return the path instead.
-            const { diffPng: diffBytes, ...verdict } = result;
-            if (diffBytes === undefined) {
-                return { ok: false, ...verdict, reason: VisualReason.DIMENSION_MISMATCH };
-            }
-            const diffPath = await store.saveDiff(baseline, diffBytes, runtime);
-            return { ok: true, ...verdict, diffPath };
-        },
-    },
-];