@reticlehq/server 2.14.0 → 3.2.0

package/dist/tools/real-input-attempt.js

@@ -1,360 +0,0 @@
-/**
- * The native-input attempt — everything that decides whether a pointer action is driven through a
- * real input provider or falls back to the occlusion-honest synthetic path, and WHY.
- *
- * Split out of act-tools.ts along its natural seam: the act tools care only about the outcome
- * (`result` defined = it went native), never about provider availability, box resolution,
- * drag-target inspection or the reason taxonomy.
- *
- * Also hosts `rewriteUploadArgs` — the daemon-side path that lets an agent name a file on disk
- * and have its REAL bytes reach the browser's `<input type="file">`. The browser SDK cannot read
- * the filesystem; the daemon can. The rewrite happens here, before the ACT command crosses the
- * bridge, so the browser side sees a normal `{ content, name, type }` call and `assertUploadArgs`
- * keeps its invariant (no fabricated bytes, no silently-dropped keys).
- *
- * Trust boundary: scoped to the project root (one level above `deps.reticleRoot`) plus any
- * opt-in `uploadRoots` declared in `.reticle.json`, resolved through `realpath` so symlinks
- * cannot escape an allowed root. Sensitive files (.env*, .git/, *.pem, id_*, .npmrc) are denied
- * with a message that says why. The cap is derived from the bridge's own MAX_MESSAGE_BYTES with
- * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
- * frame.
- */
-import { ActionType, InputModeReason, ReticleCommand, TRANSPORT_LIMITS } from '@reticlehq/core';
-import { boxCenter, isPointerAction } from '../input/real-input.js';
-import { assertDragNotDestructive, assertNotDestructive } from './act-danger.js';
-import { NATIVE_INPUT_ARG } from '@reticlehq/core';
-import { asString, asRecord } from './tools-helpers.js';
-import { commandOrThrow } from './tool-kit.js';
-import { asBox } from './act-helpers.js';
-import { isAbsolute, join, relative, extname, basename, resolve } from 'node:path';
-import { homedir } from 'node:os';
-import { RETICLE_CONFIG_BASENAME } from '../cli/cli-port.js';
-/**
- * Minimal extension → MIME-type table for the file types agents most commonly upload.
- * Falls back to `application/octet-stream` for anything not listed here — the browser and
- * the receiving server both sniff the real type from the bytes anyway.
- */
-const MIME_BY_EXT = {
-    '.pdf': 'application/pdf',
-    '.csv': 'text/csv',
-    '.txt': 'text/plain',
-    '.json': 'application/json',
-    '.xml': 'application/xml',
-    '.html': 'text/html',
-    '.htm': 'text/html',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-    '.svg': 'image/svg+xml',
-    '.zip': 'application/zip',
-    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-    '.xls': 'application/vnd.ms-excel',
-    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    '.doc': 'application/msword',
-    '.mp4': 'video/mp4',
-    '.mp3': 'audio/mpeg',
-};
-function mimeFromPath(filePath) {
-    return MIME_BY_EXT[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
-}
-/**
- * Sensitive path patterns that are refused even inside the project root.
- *
- * The project root is the right scope for fixture files. It also contains secrets that live
- * inside a repo: .env*, .git/config, *.pem, id_rsa, .npmrc. An agent whose context includes
- * text it just read off the page can be prompted to "verify the importer — upload your .env".
- * The deny-list keeps fixtures/foo.pdf working while closing that path.
- *
- * Patterns are matched against the resolved basename (after realpath, so no symlink aliasing).
- */
-const DENIED_PATTERNS = [
-    /^\.env(\.|$)/i, // .env, .env.local, .env.production …
-    /^\.git$/i, // .git directory itself
-    /\.pem$/i, // TLS private keys
-    /^id_/i, // SSH private keys: id_rsa, id_ed25519 …
-    /^\.npmrc$/i, // npm auth tokens
-    /^\.netrc$/i, // generic credential store
-    /^\.aws$/i, // AWS credentials directory
-];
-function isDeniedPath(resolvedPath) {
-    // Check every segment of the path, not just the basename, so .git/config is caught too.
-    const segments = resolvedPath.split(/[/\\]/);
-    return segments.some((seg) => DENIED_PATTERNS.some((re) => re.test(seg)));
-}
-/**
- * Maximum raw bytes the daemon will read for an upload.
- *
- * The bridge serialises bytes as base64 inside a JSON WebSocket frame; base64 inflates by 4/3.
- * The frame must fit within MAX_MESSAGE_BYTES (the maxPayload applied to BOTH bridge sockets).
- * We leave ~25% headroom for the JSON envelope (action type, ref, other fields).
- *
- * Previously hardcoded at 10 MiB, which is 13× the 1 MiB frame limit — any enterprise PDF
- * would have been rejected by the socket, not by this guard. Now derived from the same constant
- * that configures the socket so they can never drift.
- */
-const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3)) * 0.75);
-/**
- * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
- * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
- */
-export function expandUserPath(rawPath, home) {
-    if ('~' === rawPath)
-        return home;
-    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))
-        return join(home, rawPath.slice(2));
-    return rawPath;
-}
-/** True when `real` is inside `root` after both have been realpath'd / resolved. */
-function isInsideRoot(real, root) {
-    const rel = relative(root, real);
-    return !rel.startsWith('..') && !isAbsolute(rel);
-}
-/**
- * Opt-in extra upload directories from `.reticle.json` (`uploadRoots`). Absent, empty, or unreadable
- * config means project-root only — the previous default, kept on purpose.
- */
-async function readUploadRoots(projectRoot, fs, home) {
-    const configPath = join(projectRoot, RETICLE_CONFIG_BASENAME);
-    let raw;
-    try {
-        raw = await fs.readFile(configPath);
-    }
-    catch {
-        return [];
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return [];
-    }
-    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
-        return [];
-    const listed = parsed['uploadRoots'];
-    if (!Array.isArray(listed))
-        return [];
-    const roots = [];
-    for (const entry of listed) {
-        if ('string' !== typeof entry || 0 === entry.trim().length)
-            continue;
-        roots.push(resolve(expandUserPath(entry.trim(), home)));
-    }
-    return roots;
-}
-/**
- * Resolve and validate a caller-supplied upload path.
- *
- * 1. Expand a leading `~`, then resolve to absolute (join against project root for relative paths).
- * 2. Call `realpath` to follow symlinks — `relative()` is lexical and a symlink inside the tree
- *    can point outside it; realpath is the only reliable check.
- * 3. Confirm the real path is within the project root or an opt-in `uploadRoots` entry.
- * 4. Confirm the path does not match the sensitive-file deny-list.
- *
- * Returns the resolved real path on success. Throws with a user-readable message on any violation.
- */
-async function resolveUploadPath(rawPath, projectRoot, fs, uploadRoots, home) {
-    const expanded = expandUserPath(rawPath, home);
-    const abs = isAbsolute(expanded) ? expanded : join(projectRoot, expanded);
-    // realpath resolves symlinks; it also rejects ENOENT, so we get a clear missing-file error.
-    const real = await fs.realpath(abs).catch(() => {
-        throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
-    });
-    const allowed = [projectRoot, ...uploadRoots];
-    if (!allowed.some((root) => isInsideRoot(real, root))) {
-        const listed = allowed.map((r) => `'${r}'`).join(', ');
-        throw new Error(`upload path '${rawPath}' resolves to '${real}', which is outside every allowed upload root ` +
-            `(${listed}). Paths must sit under the project directory or an entry in ` +
-            `\`.reticle.json\`'s \`uploadRoots\` (e.g. ["~/Downloads"]).`);
-    }
-    if (isDeniedPath(real)) {
-        throw new Error(`upload path '${rawPath}' matches a sensitive-file pattern and cannot be read by the daemon. ` +
-            'Fixture files for upload tests should live in a dedicated directory (e.g. fixtures/).');
-    }
-    return real;
-}
-/**
- * If the action is `upload` AND the inner args carry `path`, read the file from disk and rewrite
- * the args to `{ content, name, type, __base64: true }` before the ACT command reaches the browser.
- *
- * Returns the (possibly rewritten) args object. All other actions are returned unchanged.
- *
- * This is the SINGLE interception point — called from session.command() so flow replay, crawl,
- * and every other ACT dispatch site are covered without per-site wiring.
- */
-export async function rewriteUploadArgs(deps, action, innerArgs, 
-/** Injected for tests; production uses the process home directory. */
-home = homedir()) {
-    if (action !== ActionType.UPLOAD)
-        return innerArgs;
-    const rawPath = asString(innerArgs['path']);
-    if (rawPath === undefined)
-        return innerArgs; // no path → browser handles as inline upload
-    // Project root is one level above .reticle/
-    const projectRoot = resolve(join(deps.reticleRoot, '..'));
-    const uploadRoots = await readUploadRoots(projectRoot, deps.fs, home);
-    // Blocker 4 fix: stat FIRST, before allocating read buffer, so a huge file fails fast.
-    const realPath = await resolveUploadPath(rawPath, projectRoot, deps.fs, uploadRoots, home);
-    const fileStat = await deps.fs.stat(realPath).catch(() => {
-        throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
-    });
-    // Blocker 2 fix: cap is now derived from TRANSPORT_LIMITS so it can never exceed the socket limit.
-    if (fileStat.size > UPLOAD_MAX_BYTES) {
-        throw new Error(`upload path '${rawPath}' is ${fileStat.size} bytes, which exceeds the ` +
-            `${UPLOAD_MAX_BYTES} byte upload limit (bridge frame cap). ` +
-            'Split the file or pass its bytes as args.content directly.');
-    }
-    const bytes = await deps.fs.readFileBytes(realPath).catch(() => {
-        throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
-    });
-    // Encode as base-64 so the bytes survive JSON serialisation across the bridge.
-    const content = Buffer.from(bytes).toString('base64');
-    // Infer MIME type from the file extension; fall back to octet-stream if unknown.
-    const callerType = asString(innerArgs['type']);
-    const type = callerType ?? mimeFromPath(realPath);
-    // Default filename to the basename of the REAL path (post-symlink-resolution).
-    const callerName = asString(innerArgs['name']);
-    const name = callerName ?? basename(realPath);
-    // Strip 'path' — the browser does not know it; assertUploadArgs would refuse it.
-    // __base64: true tells the browser-side dispatch to decode content before File construction.
-    const { path: _dropped, name: _n, type: _t, ...rest } = innerArgs;
-    return { ...rest, content, name, type, __base64: true };
-}
-/** Synthetic outcome with a diagnostic reason (provider configured but native input skipped). */
-function synthetic(reason) {
-    return reason === undefined
-        ? { result: undefined, settled: false }
-        : { result: undefined, settled: false, reason };
-}
-/**
- * Hover without a native pointer is a false success: synthetic mouseover reports dispatched and
- * settled while CSS `:hover` never applies. Same refusal shape as contenteditable — name the gap
- * rather than pretend the action ran.
- */
-export const HOVER_NEEDS_POINTER_MSG = 'cannot hover without a real pointer — CSS :hover only applies to a native mouse move, never to a synthetic mouseover';
-function hoverSucceeded(center) {
-    return { result: { performed: true, center, action: ActionType.HOVER }, settled: true };
-}
-/**
- * Drive hover through a real pointer (CDP provider, then a leased Playwright page), or refuse.
- *
- * A leased tab already owns Chromium — the pool can move the mouse even when `reticle drive` /
- * `RETICLE_CDP_URL` never configured a provider. Falling through to synthetic dispatch is the
- * bug: the tool reports done and the styles never ran.
- */
-async function hoverForReal(deps, session, ref, inner, provider) {
-    const providerReady = provider !== undefined && (await provider.isAvailableFor(session.url));
-    if (!providerReady && deps.pool === undefined) {
-        throw new Error(HOVER_NEEDS_POINTER_MSG);
-    }
-    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
-    assertNotDestructive(ActionType.HOVER, inner, inspected);
-    const box = asBox(inspected);
-    if (box === undefined) {
-        throw new Error(HOVER_NEEDS_POINTER_MSG);
-    }
-    if (providerReady && provider !== undefined) {
-        try {
-            const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
-            if (performed.performed)
-                return hoverSucceeded(performed.center);
-        }
-        catch {
-            // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
-        }
-    }
-    const { cx, cy } = boxCenter(box);
-    if (true === (await deps.pool?.hoverLease(session.id, cx, cy))) {
-        return hoverSucceeded({ cx, cy });
-    }
-    throw new Error(HOVER_NEEDS_POINTER_MSG);
-}
-/**
- * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
- * `reason` when a provider is configured) whenever the synthetic path should run — no matching
- * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
- * flagged with `fellBack`. `result` is defined only on a real success.
- *
- * Hover is the exception: it never returns synthetic. CSS `:hover` is not applied by
- * `dispatchEvent`, so a synthetic success is the defect. The call either drives a real pointer
- * or throws.
- */
-export async function tryRealInput(deps, session, ref, action, args) {
-    const provider = deps.realInput;
-    const inner = asRecord(args['args']);
-    const askedForNative = true === inner[NATIVE_INPUT_ARG];
-    if (action === ActionType.HOVER) {
-        return hoverForReal(deps, session, ref, inner, provider);
-    }
-    if (provider === undefined) {
-        // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
-        // noise on the most-used tool in the product. But an agent that passed native:true asked a
-        // question and got the opposite answer — reported from the field as a silent downgrade that cost
-        // real debugging time, because the tool description promises a reason is "never silent".
-        return askedForNative ? synthetic(InputModeReason.NOT_CONFIGURED) : synthetic();
-    }
-    if (!isPointerAction(action))
-        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
-    // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
-    // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
-    // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
-    // isTrusted-gated handlers). hover/drag genuinely need native pointer state, so they stay real.
-    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !askedForNative) {
-        return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
-    }
-    // Under version skew CDP is unusable while DOM tools still work (#688). Surface the skew sentence
-    // rather than "page not correlated" / a silent provider-error fallback — those send the agent
-    // hunting a dead context that is not dead.
-    if (session.versionSkew !== undefined) {
-        throw new Error(session.versionSkew);
-    }
-    if (!(await provider.isAvailableFor(session.url)))
-        return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
-    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
-    assertNotDestructive(action, inner, inspected);
-    const box = asBox(inspected);
-    if (box === undefined)
-        return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
-    let toBox;
-    if (action === ActionType.DRAG) {
-        const toRef = asString(inner['toRef']);
-        if (toRef === undefined)
-            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
-        const targetInspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
-            ref: toRef,
-        });
-        // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
-        // thing being dragged looks.
-        assertDragNotDestructive(inner, inspected, targetInspected);
-        toBox = asBox(targetInspected);
-        if (toBox === undefined)
-            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
-    }
-    const performArgs = {};
-    const value = asString(inner['value']);
-    if (value !== undefined)
-        performArgs.value = value;
-    const text = asString(inner['text']);
-    if (text !== undefined)
-        performArgs.text = text;
-    if (toBox !== undefined)
-        performArgs.toBox = toBox;
-    try {
-        const performed = await provider.perform(session.url, action, box, performArgs);
-        if (!performed.performed)
-            return synthetic(InputModeReason.PROVIDER_DECLINED);
-        return { result: { performed: true, center: performed.center, action }, settled: true };
-    }
-    catch {
-        if (session.versionSkew !== undefined)
-            throw new Error(session.versionSkew);
-        return {
-            result: undefined,
-            settled: false,
-            fellBack: true,
-            reason: InputModeReason.PROVIDER_ERROR,
-        };
-    }
-}

package/dist/tools/reconcile-tools.js

@@ -1,126 +0,0 @@
-import { bodyCaptureRemedy } from '../honesty/body-capture-remedy.js';
-import { z } from 'zod';
-import { EventType, ReticleCommand, SnapshotMode, urlForMatch } from '@reticlehq/core';
-import { ReticleTool } from './tool-names.js';
-import { cursorSchema } from './numeric-bounds.js';
-import { reconcile } from '../events/reconcile.js';
-import { salvageJson } from '../events/json-salvage.js';
-import { withControl } from '../session/control-envelope.js';
-import { asNumber, asString } from './tools-helpers.js';
-import { sessionIdShape, commandOrThrow } from './tool-kit.js';
-import { readCompleteTree } from './complete-snapshot.js';
-/**
- * Does the screen agree with the data the app was given?
- *
- * A separate tool rather than a passive contradiction rule, because it needs the rendered page as
- * well as the events — a comparison, not an observation. Passive rules stay pure and run on every
- * window; this one costs a snapshot, so the agent asks for it.
- *
- * It exists because the misses that mattered on a real payments dashboard were all this shape: a USD
- * amount rendered with a rupee sign, a settlement the API calls `on_hold` rendered as "pending". No
- * request fails, no assertion fails, and the numbers on screen match the numbers in the payload. The
- * only thing that disagrees is the meaning.
- */
-/** Response bodies captured in the window, newest last. Only JSON is worth comparing. */
-async function capturedBodies(session, since, urlContains) {
-    const events = (await session.queryEvents({ since }));
-    const bodies = [];
-    let withBody = 0;
-    let total = 0;
-    let truncated = 0;
-    for (const event of events) {
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const url = urlForMatch(event.data);
-        if (urlContains !== undefined && !url.includes(urlContains))
-            continue;
-        total += 1;
-        const raw = event.data['responseBody'];
-        if (typeof raw !== 'string' || 0 === raw.length)
-            continue;
-        // A capped body is not an absent one. Recover the records that closed before the cut rather than
-        // reporting nothing about the page with the most data on it.
-        const salvaged = salvageJson(raw);
-        if (0 === salvaged.values.length)
-            continue;
-        bodies.push(...salvaged.values);
-        withBody += 1;
-        if (salvaged.partial)
-            truncated += 1;
-    }
-    return { bodies, withBody, total, truncated };
-}
-export const RECONCILE_TOOLS = [
-    {
-        name: ReticleTool.RECONCILE,
-        example: { urlContains: '/api/v1/settlements' },
-        description: 'Compare what the API returned against what the page RENDERS. Catches the class no status code and no assertion can: a USD amount shown with a ₹ sign, a record the API calls `on_hold` displayed as "pending". Needs response bodies — enable `captureNetworkBodies` — and says so when they are missing rather than reporting a clean result over data it never read.',
-        inputSchema: {
-            ...sessionIdShape,
-            since: cursorSchema
-                .optional()
-                .describe('Cursor from a prior act — scopes to responses received after it. Default: 0.'),
-            urlContains: z
-                .string()
-                .optional()
-                .describe('Only compare responses from URLs containing this, e.g. "/api/v1/settlements".'),
-        },
-        outputSchema: {
-            mismatches: z
-                .array(z.object({ entity: z.string(), field: z.string(), api: z.string() }).passthrough())
-                .describe('Fields whose rendering disagrees with the data the app was given.'),
-            compared: z.number().describe('How many responses carried a body that could be compared.'),
-            note: z
-                .string()
-                .optional()
-                .describe('Present when nothing could be compared — never silent about an empty check.'),
-        },
-        handler: async (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
-            const since = asNumber(args['since']) ?? 0;
-            const { bodies, withBody, total, truncated } = await capturedBodies(session, since, asString(args['urlContains']));
-            // An empty result over data that was never read is the exact false green this tool exists to
-            // prevent, so the two cases are reported differently and neither is silent.
-            if (0 === bodies.length) {
-                return withControl(session, {
-                    mismatches: [],
-                    compared: 0,
-                    note: 0 === total
-                        ? 'no responses in this window matched — nothing was compared'
-                        : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. ${bodyCaptureRemedy(session.sdkVersion)}`,
-                });
-            }
-            // The whole page, INCLUDING whatever the snapshot's node cap cut off. A comparison against a
-            // prefix of the page can miss the row that disagrees and can invent one that does not — the
-            // value it was looking for may simply sit past the cut.
-            const page = await readCompleteTree((scope) => commandOrThrow(deps, session.id, ReticleCommand.SNAPSHOT, {
-                mode: SnapshotMode.FULL,
-                ...(scope === undefined ? {} : { scope, includeRoot: true }),
-            }));
-            const mismatches = reconcile(bodies, page.tree);
-            // ASYMMETRIC on purpose. A mismatch FOUND in a partial page is still found — one witness proves
-            // presence, and withholding it because the rest of the page was unread helps nobody. An EMPTY
-            // result is the universal claim "nothing anywhere disagrees", and a partial page cannot support
-            // it. So the positive keeps working and only the negative is refused.
-            if (0 === mismatches.length && !page.complete) {
-                throw new Error(`the page could not be read completely — ${page.incompleteBecause ?? 'the snapshot was cut'}. ` +
-                    'Nothing was found to disagree with the API, but that is not the same as nothing disagreeing: ' +
-                    'the record that does could be in the part that was never read. Narrow the page (close overlays, ' +
-                    'navigate to the view holding these records) and re-run.');
-            }
-            // A truncated body is declared whether or not anything was found in it: "no mismatches" over a
-            // partially-read payload is a weaker statement than over a whole one, and the difference is
-            // exactly the kind of omission this layer exists to refuse.
-            const partial = truncated > 0
-                ? {
-                    note: `${String(truncated)} of ${String(withBody)} response(s) exceeded the body cap and were read only up to the cut — records after it were not compared`,
-                }
-                : 0 === mismatches.length
-                    ? {
-                        note: `compared ${String(withBody)} response(s); nothing on screen contradicts them`,
-                    }
-                    : {};
-            return withControl(session, { mismatches, compared: withBody, ...partial });
-        },
-    },
-];

package/dist/tools/resolve-target.js

@@ -1,116 +0,0 @@
-import { ElementState } from '@reticlehq/core';
-import { asRecord } from './tools-helpers.js';
-/**
- * Roles that usually name the control an agent meant, ahead of a wrapping `generic` that
- * happened to inherit the same accessible name (header CTA vs empty-state CTA).
- */
-const ROLE_RANK = {
-    button: 0,
-    link: 1,
-    menuitem: 2,
-    tab: 3,
-    checkbox: 4,
-    radio: 5,
-    switch: 6,
-    option: 7,
-    combobox: 8,
-    textbox: 9,
-    searchbox: 10,
-};
-function roleRank(role) {
-    if ('string' !== typeof role)
-        return 100;
-    return ROLE_RANK[role] ?? 50;
-}
-function statesOf(c) {
-    return Array.isArray(c.states) ? c.states.filter((s) => 'string' === typeof s) : [];
-}
-function inViewport(c) {
-    return statesOf(c).includes(ElementState.IN_VIEWPORT);
-}
-/**
- * Stable ranking for the refusal message only. Never used to pick — an action must not guess.
- *
- * Order: in-viewport over off-screen, then more-specific roles over `generic`. Visibility is
- * already applied before this runs (hidden duplicates are filtered), so it is not a sort key here.
- */
-function compareCandidates(a, b) {
-    const viewport = Number(inViewport(b)) - Number(inViewport(a));
-    if (0 !== viewport)
-        return viewport;
-    return roleRank(a.role) - roleRank(b.role);
-}
-/**
- * Annotate where the candidate sits. `anyInViewport` is true when at least one sibling carried
- * `inViewport` — only then is absence meaningful as off-screen. Without that signal, saying
- * "off-screen" would invent a fact the descriptor never reported.
- */
-function formatCandidate(c, anyInViewport) {
-    const role = 'string' === typeof c.role ? c.role : '?';
-    const name = 'string' === typeof c.name ? c.name : '';
-    const ref = 'string' === typeof c.ref ? c.ref : '?';
-    const visible = false !== c.visible;
-    let where;
-    if (!visible)
-        where = 'hidden';
-    else if (inViewport(c))
-        where = 'in-viewport';
-    else if (anyInViewport)
-        where = 'off-screen';
-    else
-        where = 'visible';
-    const head = name.length > 0 ? `${ref} (${role} "${name}"` : `${ref} (${role}`;
-    return `${head}; ${where})`;
-}
-/**
- * Turn a target QUERY into the single ref an action can be performed on.
- *
- * `act_and_wait` took only a `ref`, so every verification cost a `reticle_query` turn first just to
- * learn one string. The advertised tool surface is re-sent on every turn, so that extra turn was not
- * a small cost: measured on the wire, a two-turn verification spent 10,756 of its 11,235 tokens on
- * schema and 479 on the actual answers. Removing the turn removes half the schema bill.
- *
- * Ambiguity is an ERROR, never a pick. Choosing "the first match" would let a verification act on a
- * different element than the author meant and still report success, which is the false green this
- * product exists to prevent — and the failure is invisible, because the verdict describes the
- * element it DID act on. The message names the candidates so the caller can narrow rather than guess.
- *
- * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
- * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
- * the two-turn path for no gain.
- *
- * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
- * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
- */
-export function resolveTargetRef(candidates) {
-    const all = candidates.map((c) => asRecord(c));
-    const visible = all.filter((c) => c.visible !== false);
-    const usable = visible.length > 0 ? visible : all;
-    if (0 === usable.length) {
-        return {
-            kind: 'error',
-            message: 'target matched no element. Nothing was acted on and no verdict is possible — widen the ' +
-                'query, or take a reticle_snapshot to see what is actually on the page.',
-        };
-    }
-    if (usable.length > 1) {
-        const ranked = [...usable].sort(compareCandidates);
-        const anyInViewport = ranked.some(inViewport);
-        const named = ranked
-            .slice(0, 5)
-            .map((c) => formatCandidate(c, anyInViewport))
-            .join(', ');
-        return {
-            kind: 'error',
-            message: `target matched ${String(usable.length)} elements and an action must not guess between ` +
-                `them (ranked: in-viewport, then role): ${named}. Narrow the query (add role/name/testid ` +
-                'or a scope), or pass an explicit `ref` from reticle_query.',
-        };
-    }
-    const only = usable[0];
-    const ref = only === undefined ? undefined : only.ref;
-    if ('string' !== typeof ref || 0 === ref.length) {
-        return { kind: 'error', message: 'target matched an element with no usable ref.' };
-    }
-    return { kind: 'ref', ref };
-}