@reticlehq/server 2.4.0 → 2.5.0

package/dist/tools/merge-tools.js

@@ -33,17 +33,23 @@ export function applyMerges(tools, plans, retired = []) {
             actions[action] = member;
             consumed.add(memberName);
         }
-        merged.push(mergeTools({ name: plan.name, description: plan.description, actions }));
+        merged.push(mergeTools({
+            name: plan.name,
+            description: plan.description,
+            actions,
+            ...(plan.example === undefined ? {} : { example: plan.example }),
+        }));
     }
     return [...tools.filter((t) => !consumed.has(t.name)), ...merged];
 }
 export function mergeTools(spec) {
     const actionNames = Object.keys(spec.actions);
-    if (actionNames.length === 0)
+    if (0 === actionNames.length)
         throw new Error(`mergeTools(${spec.name}): no actions`);
     return {
         name: spec.name,
         description: spec.description,
+        ...(spec.example === undefined ? {} : { example: spec.example }),
         inputSchema: {
             action: z
                 .enum(actionNames)
@@ -52,7 +58,7 @@ export function mergeTools(spec) {
         },
         handler: (deps, args) => {
             const action = args['action'];
-            const chosen = typeof action === 'string' ? spec.actions[action] : undefined;
+            const chosen = 'string' === typeof action ? spec.actions[action] : undefined;
             if (chosen === undefined) {
                 return Promise.resolve({
                     error: `unknown action '${String(action)}' for ${spec.name}`,

package/dist/tools/merged-name-redirect.d.ts

@@ -0,0 +1,13 @@
+interface MergedNameRedirect {
+    /** The tool to call instead. */
+    tool: string;
+    /** The action that selects the old behaviour, when the name was merged rather than retired. */
+    action?: string;
+    /** Why there is no direct replacement, for a retired name. */
+    note?: string;
+}
+/** Where `name` went, or undefined when it is a live tool or not ours. */
+export declare function mergedNameRedirect(name: string): MergedNameRedirect | undefined;
+/** The sentence handed to an agent that called `name`. */
+export declare function mergedNameMessage(name: string, redirect: MergedNameRedirect): string;
+export {};

package/dist/tools/merged-name-redirect.js

@@ -0,0 +1,55 @@
+/**
+ * Where a merged or retired tool's old name went.
+ *
+ * Twenty-two names exported from `ReticleTool` are no longer tools: `reticle_record_start` became
+ * `reticle_record { action: "start" }`, `reticle_diff` became `reticle_baseline { action: "diff" }`,
+ * and three were retired outright. Confirmed live in a field sweep, they all answered `unknown tool`
+ * — which is the wrong answer, because the capability exists and only moved. An agent trained on an
+ * earlier release, or reading the merged tool's own description (which names every action), reaches
+ * for exactly these.
+ *
+ * DERIVED from `MERGE_PLANS` and `RETIRED_FROM_SURFACE` rather than written out, so the next merge is
+ * covered the day it lands instead of the day someone notices.
+ */
+import { MERGE_PLANS, RETIRED_FROM_SURFACE } from './tools.js';
+import { ReticleTool } from './tool-names.js';
+/** Retired names, and where the capability actually lives now. */
+const RETIRED_NOTE = {
+    [ReticleTool.REFRESH]: {
+        tool: ReticleTool.NAVIGATE,
+        note: 'reloading was absorbed into reticle_navigate { reload: true }',
+    },
+    [ReticleTool.RUN_RECORD]: {
+        tool: ReticleTool.PROJECT,
+        note: 'run outcomes are persisted automatically by reticle_flow_replay; read them with reticle_project',
+    },
+    [ReticleTool.WAIT_READY]: {
+        tool: ReticleTool.SESSIONS,
+        note: 'waiting is implicit — the first live call already blocks until the session is ready',
+    },
+};
+const BY_OLD_NAME = (() => {
+    const map = new Map();
+    for (const plan of MERGE_PLANS) {
+        for (const [action, oldName] of Object.entries(plan.members)) {
+            map.set(oldName, { tool: plan.name, action });
+        }
+    }
+    for (const name of RETIRED_FROM_SURFACE) {
+        const known = RETIRED_NOTE[name];
+        if (known !== undefined)
+            map.set(name, known);
+    }
+    return map;
+})();
+/** Where `name` went, or undefined when it is a live tool or not ours. */
+export function mergedNameRedirect(name) {
+    return BY_OLD_NAME.get(name);
+}
+/** The sentence handed to an agent that called `name`. */
+export function mergedNameMessage(name, redirect) {
+    return redirect.action === undefined
+        ? `${name} no longer exists — ${redirect.note ?? `use ${redirect.tool}`}.`
+        : `${name} was merged into ${redirect.tool}. Call ${redirect.tool} { action: "${redirect.action}", ... } — ` +
+            `through reticle_run if it is not advertised under this profile.`;
+}

package/dist/tools/navigate-result.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The honest envelope for a navigation nobody can confirm.
+ *
+ * `window.location.assign(url)` returns before the page moves, and the SDK that would report on the
+ * new document is destroyed by the navigation itself. So a successful NAVIGATE means the browser
+ * accepted the instruction — not that anything arrived. Driven against a dead URL it returned
+ * `{"ok":true}` while the session died, which is the worst combination available: the agent believes
+ * it navigated, is looking at nothing, and has lost Reticle.
+ *
+ * `reticle_act` already draws this line — `dispatched` (sent) versus `settled` (a frame flushed).
+ * This gives navigate the same honesty without changing what it does.
+ */
+export declare function navigateResult(result: {
+    ok?: unknown;
+    url?: unknown;
+    reason?: unknown;
+}): Record<string, unknown>;

package/dist/tools/navigate-result.js

@@ -0,0 +1,31 @@
+/**
+ * The honest envelope for a navigation nobody can confirm.
+ *
+ * `window.location.assign(url)` returns before the page moves, and the SDK that would report on the
+ * new document is destroyed by the navigation itself. So a successful NAVIGATE means the browser
+ * accepted the instruction — not that anything arrived. Driven against a dead URL it returned
+ * `{"ok":true}` while the session died, which is the worst combination available: the agent believes
+ * it navigated, is looking at nothing, and has lost Reticle.
+ *
+ * `reticle_act` already draws this line — `dispatched` (sent) versus `settled` (a frame flushed).
+ * This gives navigate the same honesty without changing what it does.
+ */
+export function navigateResult(result) {
+    const ok = true === result.ok;
+    const base = {
+        ok,
+        ...('string' === typeof result.url ? { url: result.url } : {}),
+        ...('string' === typeof result.reason ? { reason: result.reason } : {}),
+    };
+    // A refusal is conclusive: the page never moved, so there is nothing unconfirmed to report.
+    if (!ok)
+        return base;
+    return {
+        ...base,
+        confirmed: false,
+        note: 'ok means the navigation was DISPATCHED, not that the page arrived — the SDK is torn down by ' +
+            'the navigation itself, so nothing here can see the new document. Call reticle_sessions to ' +
+            'confirm a session reconnected at the new URL before acting; if none appears, the page did ' +
+            'not load or is not instrumented.',
+    };
+}

package/dist/tools/observe-tools.js

@@ -2,8 +2,10 @@
  * Observe / wait / assert tools — reticle_observe, reticle_wait_for, reticle_assert, reticle_network,
  * reticle_console, reticle_animations. Split out of tools.ts; assembled back via...OBSERVE_TOOLS.
  */
+import { noteEmptyRead } from './observed-nothing.js';
 import { z } from 'zod';
-import { ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS } from '@reticlehq/core';
+import { aliasParam } from './alias-args.js';
+import { CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport } from '../events/reaction.js';
 import { findContradictions } from '../events/contradictions.js';
@@ -54,11 +56,21 @@ function lastActSourceOnFailure(session, pass) {
  * really do interleave; it is only redundant at this boundary.
  */
 function withoutConstantSessionId(event) {
-    if (typeof event !== 'object' || event === null)
+    if (typeof event !== 'object' || null === event)
         return event;
     const { sessionId: _sessionId, ...rest } = event;
     return rest;
 }
+/**
+ * The console levels, derived from core's console EventTypes — see CONSOLE_LEVELS.
+ *
+ * A free string here filtered by building `console.${level}`, so `level:'ERROR'` or `level:'fatal'`
+ * matched nothing and returned an empty log list. On a page that HAS logs the zero-match hint saves
+ * it (it reports which levels are present), but on a quiet page the answer is identical to a genuine
+ * all-clear. Refusing the value outright is the only reading with no ambiguity.
+ */
+const CONSOLE_LEVEL_LIST = CONSOLE_LEVELS.join(' | ');
+const consoleLevelEnum = z.enum(CONSOLE_LEVELS);
 export const OBSERVE_TOOLS = [
     {
         name: ReticleTool.OBSERVE,
@@ -180,10 +192,12 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.WAIT_FOR,
-        example: { predicate: { kind: 'state', path: 'todos.length', equals: 3 } },
+        example: { predicate: { kind: PredicateKind.STATE, path: 'todos.length', equals: 3 } },
         description: 'Block until a predicate is satisfied (or already true in the recent buffer), else time out. Returns matching evidence or a near-miss diagnosis. By default it only counts events since your last act, so a signal buffered BEFORE the action can never fake a pass; pass `since` (an observe/act cursor) to widen or narrow that window explicitly.',
         inputSchema: {
-            predicate: PredicateSchema.describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "net", ok: false } (assert on the OUTCOME — the honest field for IPC, which has no status code), { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
+            predicate: PredicateSchema.optional().describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "net", ok: false } (assert on the OUTCOME — the honest field for IPC, which has no status code), { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
+            // Same concept, the neighbouring tool's name. See alias-args.ts.
+            until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: z.number().optional().describe('Maximum wait in milliseconds. Default: 4000.'),
             since: z
                 .number()
@@ -218,7 +232,8 @@ export const OBSERVE_TOOLS = [
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const predicate = PredicateSchema.parse(args['predicate']);
+            // `until` is act_and_wait's name for this — see alias-args.ts.
+            const predicate = PredicateSchema.parse(aliasParam(args, 'predicate', ['until'])['predicate']);
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
             const verdict = await waitForPredicate(session, predicate, asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS, since);
@@ -234,10 +249,11 @@ export const OBSERVE_TOOLS = [
     },
     {
         name: ReticleTool.ASSERT,
-        example: { predicate: { kind: 'signal', name: 'todos:loaded' } },
+        example: { predicate: { kind: PredicateKind.SIGNAL, name: 'todos:loaded' } },
         description: 'Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. Prefer a { signal } or { net } consequence over { element }/{ text } presence — a passing presence-only assertion returns `advice` because a wrong/healed element can fake it. By default it only counts events since your last act, so a stale buffered signal can never fake a pass; pass `since` (an observe/act cursor) to set the window explicitly.',
         inputSchema: {
-            predicate: PredicateSchema.describe('Predicate to evaluate: { signal }, { net }, { element } or a combination.'),
+            predicate: PredicateSchema.optional().describe('Predicate to evaluate: { signal }, { net }, { element } or a combination.'),
+            until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: z
                 .number()
                 .optional()
@@ -287,7 +303,8 @@ export const OBSERVE_TOOLS = [
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            const predicate = PredicateSchema.parse(args['predicate']);
+            // `until` is act_and_wait's name for this — see alias-args.ts.
+            const predicate = PredicateSchema.parse(aliasParam(args, 'predicate', ['until'])['predicate']);
             const timeout = asNumber(args['timeout_ms']) ?? 0;
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
@@ -306,7 +323,7 @@ export const OBSERVE_TOOLS = [
                     : assertsDerivedIpcStatus(predicate)
                         ? { advice: DERIVED_IPC_STATUS_ADVICE }
                         : {};
-            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since);
+            const { decision, contradictions, coverage } = await assertVerdict(session, predicate, verdict.pass, since, verdict.inconclusive);
             return withControl(session, {
                 ...decision,
                 ...verdict,
@@ -374,7 +391,7 @@ export const OBSERVE_TOOLS = [
             const method = asString(args['method']);
             const urlContains = asString(args['urlContains']);
             const status = asNumber(args['status']);
-            const ok = typeof args['ok'] === 'boolean' ? args['ok'] : undefined;
+            const ok = 'boolean' === typeof args['ok'] ? args['ok'] : undefined;
             const limit = asNumber(args['limit']);
             const buffer = bufferEnvelope(session);
             // Completed calls + unresolved in-flight requests (a hung request shows as pending).
@@ -385,18 +402,21 @@ export const OBSERVE_TOOLS = [
             }));
             const matched = allNet.filter((e) => matchNet(e, method, urlContains, status, ok));
             // zero-match filter returns what DID fire, not a bare [].
-            if (matched.length === 0 && allNet.length > 0) {
+            if (0 === matched.length && allNet.length > 0) {
                 return withSizeCost({ calls: matched, hint: netEmptyHint(allNet), ...buffer });
             }
             // Default the cap so an omitted `limit` can't dump a whole flooded session (since defaults to 0).
             const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit ?? DEFAULT_QUERY_LIMIT);
             const calls = budgeted.map(projectNetCall);
-            return withSizeCost({
+            // A zero-match FILTER already reports what did fire (netEmptyHint above). Zero calls at all
+            // fell through as a bare `[]`, which is indistinguishable from an observer that is not
+            // recording — and those need opposite responses. Say the look happened.
+            return withSizeCost(noteEmptyRead({
                 calls,
                 ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
                 ...bodiesNotCaptured(calls),
                 ...buffer,
-            });
+            }, 'calls', { noun: 'network calls' }));
         },
     },
     {
@@ -404,10 +424,9 @@ export const OBSERVE_TOOLS = [
         example: { level: 'error' },
         description: 'Console/error log. Fast path for "were there any errors during this flow?". When a level filter matches nothing, returns a `hint` { totalInWindow, byLevel } so 0 errors is distinguishable from a silent page.',
         inputSchema: {
-            level: z
-                .string()
+            level: consoleLevelEnum
                 .optional()
-                .describe('Log level filter: error | warn | info | log. Omit to return all levels.'),
+                .describe(`Log level filter: ${CONSOLE_LEVEL_LIST}. Omit to return all levels.`),
             since: z
                 .number()
                 .optional()
@@ -451,15 +470,19 @@ export const OBSERVE_TOOLS = [
             })).filter(isConsoleEvent);
             const matched = allConsole.filter((e) => matchConsole(e, level));
             // zero matches at this level → report what levels ARE present (not a bare []).
-            if (matched.length === 0 && allConsole.length > 0) {
+            if (0 === matched.length && allConsole.length > 0) {
                 return withSizeCost({ logs: matched, hint: consoleEmptyHint(allConsole), ...buffer });
             }
             // Default the cap so an omitted `limit` can't dump a whole flooded session (since defaults to 0).
             const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit ?? DEFAULT_QUERY_LIMIT);
             const logs = budgeted.map(projectConsoleLog);
-            return withSizeCost(droppedOldest > 0
+            // Say the look HAPPENED when it found nothing. A quiet page and a dead console observer both
+            // produced `{ logs: [] }`, and "no console errors" is the claim agents lean on most — see
+            // observed-nothing.ts, whose own header names this exact case and which every other array-
+            // returning read here was already wired to.
+            return withSizeCost(noteEmptyRead(droppedOldest > 0
                 ? { logs, total: matched.length, droppedOldest, ...buffer }
-                : { logs, ...buffer });
+                : { logs, ...buffer }, 'logs', { noun: 'console lines' }));
         },
     },
     {
@@ -469,6 +492,17 @@ export const OBSERVE_TOOLS = [
         outputSchema: {
             animations: z.array(z.unknown()),
         },
-        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.ANIMATIONS, {}),
+        handler: async (deps, args) => {
+            const result = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.ANIMATIONS, {});
+            // A page with nothing animating and an observer that is not watching both return `[]`, and the
+            // second means the run should not be trusted. Say the look happened.
+            return isPlainRecord(result)
+                ? noteEmptyRead(result, 'animations', { noun: 'animations running or completed' })
+                : result;
+        },
     },
 ];
+/** Narrow a command result to something noteEmptyRead can annotate. */
+function isPlainRecord(value) {
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
+}

package/dist/tools/observed-nothing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Say that the look HAPPENED, when the look found nothing.
+ *
+ * A quiet page and a dead observer produce the same JSON: `[]`. Reported across seven tools in a
+ * field sweep — network with 0 calls, console with 0 logs, reconcile comparing 0, crawl with 0 steps,
+ * an empty message inbox — none of which could be told apart from the observer not working. Those
+ * need opposite responses: one means "the app did nothing", the other means "stop trusting this run".
+ *
+ * One shared shape rather than a field per tool: an empty read states the window it watched. "I
+ * watched 2000ms and saw nothing" is a finding. `[]` is an absence of information wearing the same
+ * clothes as one.
+ */
+interface EmptyReadContext {
+    /** The observation window, when the read has one. */
+    windowMs?: number;
+    /** What was being counted, in the agent's words: "console lines", "network calls". */
+    noun: string;
+}
+/**
+ * Add `observed: true` and a note when `key` holds an EMPTY array. Returns the result untouched
+ * otherwise — including when it is a refusal, where "I observed nothing" would be actively
+ * misleading on top of an error that already explains itself.
+ */
+export declare function noteEmptyRead(result: Record<string, unknown>, key: string, context: EmptyReadContext): Record<string, unknown>;
+export {};

package/dist/tools/observed-nothing.js

@@ -0,0 +1,33 @@
+/**
+ * Say that the look HAPPENED, when the look found nothing.
+ *
+ * A quiet page and a dead observer produce the same JSON: `[]`. Reported across seven tools in a
+ * field sweep — network with 0 calls, console with 0 logs, reconcile comparing 0, crawl with 0 steps,
+ * an empty message inbox — none of which could be told apart from the observer not working. Those
+ * need opposite responses: one means "the app did nothing", the other means "stop trusting this run".
+ *
+ * One shared shape rather than a field per tool: an empty read states the window it watched. "I
+ * watched 2000ms and saw nothing" is a finding. `[]` is an absence of information wearing the same
+ * clothes as one.
+ */
+/**
+ * Add `observed: true` and a note when `key` holds an EMPTY array. Returns the result untouched
+ * otherwise — including when it is a refusal, where "I observed nothing" would be actively
+ * misleading on top of an error that already explains itself.
+ */
+export function noteEmptyRead(result, key, context) {
+    if ('string' === typeof result['error'])
+        return result;
+    const value = result[key];
+    if (!Array.isArray(value) || value.length > 0)
+        return result;
+    if (result['note'] !== undefined)
+        return result;
+    const window = context.windowMs === undefined ? '' : ` over the last ${String(context.windowMs)}ms`;
+    return {
+        ...result,
+        // The distinction the field sweep could not make: this is a RESULT, not a failure to look.
+        observed: true,
+        note: `no ${context.noun}${window} — the observation ran and found none, which is a result, not a missing reading`,
+    };
+}

package/dist/tools/query-paginate.js

@@ -19,7 +19,7 @@
  * number that is silently wrong. `count` survives because it is a scalar. Trust it over the array.
  */
 export function paginateQueryResult(result, limit, countOnly) {
-    if (typeof result !== 'object' || result === null)
+    if (typeof result !== 'object' || null === result)
         return result;
     const record = result;
     const elements = record['elements'];
@@ -28,7 +28,7 @@ export function paginateQueryResult(result, limit, countOnly) {
     const counted = record['count'];
     // Older browser SDKs (and the zero-match hint path) may not carry `count`; fall back rather than
     // report nothing, but never prefer the array when the browser told us the real number.
-    const total = typeof counted === 'number' ? counted : elements.length;
+    const total = 'number' === typeof counted ? counted : elements.length;
     const truncatedOnWire = total > elements.length;
     if (countOnly) {
         const { elements: _dropped, ...rest } = record;

package/dist/tools/query-shape.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Accepting the element-query shape the rest of the surface teaches.
+ *
+ * `reticle_query` asks for a strategy and a value — `{ by: 'text', value: 'Deploy' }`. Every
+ * predicate asks for named fields — `{ text: 'Deploy' }`, `{ testid: 'submit' }` — and that is where
+ * an agent meets element queries most often (`act_and_wait { until: { kind:'element', query } }`,
+ * `reticle_assert`, `wait_for`). Carrying the predicate's spelling to `reticle_query` earns
+ * `-32602: Unknown parameter for reticle_query: text`.
+ *
+ * It is a small thing that lands in an expensive place: of the sessions that called any tool in a
+ * day, HALF made exactly one call and stopped. A rejected first call is a bounced session, and the
+ * agent has no way to know the rejection was about spelling rather than the page.
+ *
+ * Translation only — `by`/`value` remain the tool's contract, an explicit pair always wins, and a
+ * call carrying neither shape is left alone so the schema error still explains itself rather than
+ * being replaced by a confident wrong query.
+ */
+export declare function normalizeQueryArgs(args: Record<string, unknown>): Record<string, unknown>;

package/dist/tools/query-shape.js

@@ -0,0 +1,39 @@
+/**
+ * Accepting the element-query shape the rest of the surface teaches.
+ *
+ * `reticle_query` asks for a strategy and a value — `{ by: 'text', value: 'Deploy' }`. Every
+ * predicate asks for named fields — `{ text: 'Deploy' }`, `{ testid: 'submit' }` — and that is where
+ * an agent meets element queries most often (`act_and_wait { until: { kind:'element', query } }`,
+ * `reticle_assert`, `wait_for`). Carrying the predicate's spelling to `reticle_query` earns
+ * `-32602: Unknown parameter for reticle_query: text`.
+ *
+ * It is a small thing that lands in an expensive place: of the sessions that called any tool in a
+ * day, HALF made exactly one call and stopped. A rejected first call is a bounced session, and the
+ * agent has no way to know the rejection was about spelling rather than the page.
+ *
+ * Translation only — `by`/`value` remain the tool's contract, an explicit pair always wins, and a
+ * call carrying neither shape is left alone so the schema error still explains itself rather than
+ * being replaced by a confident wrong query.
+ */
+/** Most specific first: the order Reticle prefers anchors everywhere else (testid is gold). */
+const FIELD_TO_STRATEGY = [
+    ['testid', 'testid'],
+    ['label', 'label'],
+    ['placeholder', 'placeholder'],
+    ['alt', 'alt'],
+    ['text', 'text'],
+    ['role', 'role'],
+];
+export function normalizeQueryArgs(args) {
+    // An explicit pair is the contract; never second-guess it.
+    if ('string' === typeof args['by'] && 'string' === typeof args['value'])
+        return args;
+    for (const [field, strategy] of FIELD_TO_STRATEGY) {
+        const value = args[field];
+        if ('string' === typeof value && value.length > 0) {
+            // `name` stays as-is: with role it is the accessible-name filter the predicate also uses.
+            return { ...args, by: strategy, value };
+        }
+    }
+    return args;
+}