@reticlehq/server 2.6.0 → 2.8.0

package/dist/events/predicate-eval.js

@@ -1,4 +1,4 @@
-import { ElementQuerySchema, ElementState, EventType, PredicateKind, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
+import { ElementQuerySchema, ElementState, EventType, PredicateKind, QueryBy, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
 import { z } from 'zod';
 import { describeObserved } from './observed-in-window.js';
 /**
@@ -9,6 +9,11 @@ import { describeObserved } from './observed-in-window.js';
  * the only key supplied left a predicate that asserts nothing and passes on anything.
  */
 const PREDICATE_ALIASES = {
+    // `text`/`value` on a `text` predicate: the kind is called "text", so `text:` is the first thing
+    // anyone writes for it, and `value` follows from the element query's own `value` field. Both were
+    // hard rejections, and a rejected predicate produces NO verdict at all — the drive ends with
+    // nothing rather than with a failure, which is the worst outcome of the three.
+    [PredicateKind.TEXT]: { text: 'contains', value: 'contains' },
     // `urlContains`/`url` reported from the field: an agent that had just written
     // `net { urlContains }` applied the same word to `route`, which spells it `contains`, and got
     // `unrecognized_keys` with no list of what would have worked. The parallel it assumed is a fair
@@ -19,111 +24,265 @@ const PREDICATE_ALIASES = {
     [PredicateKind.NET]: { url: 'urlContains' },
     [PredicateKind.SIGNAL]: { data: 'dataMatches' },
 };
+/**
+ * Element-query fields an agent writes FLAT on an `element` predicate instead of nested under
+ * `query`. `reticle_query` takes exactly these at the top level, so an agent that has just located
+ * something writes the same words again when it asserts on it — and got `query: Required` plus an
+ * `unknown field` list for its trouble. Lifting them is unambiguous: they have no other meaning on
+ * this kind.
+ */
+const ELEMENT_QUERY_FIELDS = [
+    'by',
+    'value',
+    'role',
+    'name',
+    'text',
+    'label',
+    'placeholder',
+    'testid',
+    'alt',
+    'component',
+];
+/**
+ * The locator fields the browser actually CONSUMES for a given query — mirrors the precedence in
+ * `findIn` (packages/browser/src/dom/query.ts).
+ *
+ * An element query is not a conjunction. It is a first-match dispatch: `by`+`value` wins, then the
+ * component/source anchor, then `role` (which alone also consumes `name`), then the first of
+ * text/label/placeholder/testid/alt that is present. Every OTHER field the caller wrote is dropped on
+ * the floor, silently, and the match reported as if the whole query had been honoured.
+ *
+ * Duplicated here on purpose. The alternative is to send the question to the browser, and the browser
+ * cannot answer it: by the time a match comes back, the fields it ignored are indistinguishable from
+ * the fields it used.
+ */
+function usedQueryFields(query) {
+    const used = new Set();
+    if (query.by !== undefined && query.value !== undefined) {
+        used.add('by').add('value');
+        if (QueryBy.ROLE === query.by)
+            used.add('name');
+        if (QueryBy.COMPONENT === query.by)
+            used.add('component');
+        return used;
+    }
+    if (query.component !== undefined || query.source !== undefined)
+        return used.add('component');
+    if (query.role !== undefined)
+        return used.add('role').add('name');
+    for (const field of ['text', 'label', 'placeholder', 'testid', 'alt']) {
+        if (query[field] !== undefined)
+            return used.add(field);
+    }
+    return used;
+}
+/**
+ * How a dropped field is checked back on the server, against the descriptor the match returned.
+ *
+ * `value` is the field this exists for: `{ role: "textbox", name: "GST amount", value: "274.58" }`
+ * read as a locator has no `by`, so the value half was discarded and the predicate collapsed to "a
+ * textbox named GST amount exists" — trivially true against an EMPTY field. Comparison is TRIMMED and
+ * exact: an input's value is a value, not prose, and a trailing space in either the app or the
+ * predicate is not a finding anybody wants. `""` asserts the field is empty, which describe() reports
+ * by omitting the field entirely.
+ *
+ * `role`/`name`/`value` compare against exactly what `reticle_query` REPORTS, so the words an agent
+ * copies out of a query result are the words that match here. `text` is a substring match, matching
+ * Testing Library's `exact: false`, and falls back to the name because describe() omits `text` when it
+ * equals the accessible name.
+ */
+const RESIDUAL_CHECKS = {
+    value: (element, want) => (element.value ?? '').trim() === want.trim(),
+    role: (element, want) => element.role === want,
+    name: (element, want) => element.name.trim() === want.trim(),
+    text: (element, want) => (element.text ?? element.name).includes(want),
+};
+/**
+ * Split a query's dropped fields into the ones the server can still enforce and the ones it cannot.
+ *
+ * The alternative — refuse every dropped field — breaks calls that work today and that our own
+ * cheatsheet advertises (`{ role: "button", text: "Save" }`), and breaks them into no verdict at all.
+ * Enforcing what we can and refusing only the rest keeps those calls working AS WRITTEN, which is the
+ * outcome the caller was already assuming.
+ */
+export function residualQueryChecks(query) {
+    const used = usedQueryFields(query);
+    const checks = [];
+    const unusable = [];
+    for (const field of ELEMENT_QUERY_FIELDS) {
+        const want = query[field];
+        if (want === undefined || used.has(field))
+            continue;
+        if ('string' === typeof want && RESIDUAL_CHECKS[field] !== undefined)
+            checks.push([field, want]);
+        else
+            unusable.push(field);
+    }
+    return { checks, unusable };
+}
+/** Does this element satisfy every field the locator dropped? */
+export function satisfiesResiduals(element, checks) {
+    return checks.every(([field, want]) => true === RESIDUAL_CHECKS[field]?.(element, want));
+}
+/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
+export function describeResidual(element, field) {
+    const reading = 'value' === field
+        ? (element.value ?? '')
+        : 'text' === field
+            ? (element.text ?? element.name)
+            : 'role' === field
+                ? element.role
+                : element.name;
+    return `${element.role} "${element.name}" ${field}=${JSON.stringify(reading)}`;
+}
 /** Rename known aliases before parse; an explicit canonical key always wins. */
 function applyPredicateAliases(input) {
     if (typeof input !== 'object' || null === input || Array.isArray(input))
         return input;
     const obj = input;
-    const aliases = PREDICATE_ALIASES['string' === typeof obj['kind'] ? obj['kind'] : ''];
-    if (aliases === undefined)
-        return input;
+    const kind = 'string' === typeof obj['kind'] ? obj['kind'] : '';
+    const aliases = PREDICATE_ALIASES[kind];
+    let out = obj;
+    if (aliases !== undefined) {
+        out = { ...obj };
+        for (const [from, to] of Object.entries(aliases)) {
+            if (out[from] === undefined)
+                continue;
+            if (out[to] === undefined)
+                out[to] = out[from];
+            delete out[from];
+        }
+    }
+    return PredicateKind.ELEMENT === kind ? liftElementQuery(out) : out;
+}
+/**
+ * Fold flat query fields into `query`. An explicit `query` wins outright — a caller that supplied
+ * both told us which one it meant, and merging the two would invent a locator neither side wrote.
+ */
+function liftElementQuery(obj) {
+    const loose = ELEMENT_QUERY_FIELDS.filter((field) => obj[field] !== undefined);
+    if (0 === loose.length)
+        return obj;
     const out = { ...obj };
-    for (const [from, to] of Object.entries(aliases)) {
-        if (out[from] === undefined)
-            continue;
-        if (out[to] === undefined)
-            out[to] = out[from];
-        delete out[from];
+    const query = {};
+    for (const field of loose) {
+        query[field] = out[field];
+        delete out[field];
     }
+    if (out['query'] === undefined)
+        out['query'] = query;
     return out;
 }
 /**
  * Strict on every branch. A key that is nobody's spelling is now a schema error naming it, instead of
  * a stripped field and a green — see predicate-strict.test.ts for the MCP session that found this.
+ *
+ * Built on demand rather than at module scope: the `allOf`/`anyOf`/`not` branches reference
+ * `PredicateSchema` itself, which does not exist yet while this module is initialising. Calling it
+ * after init is what makes the union introspectable — see `predicateFieldsFor`.
  */
-export const PredicateSchema = z.lazy(() => z.preprocess(applyPredicateAliases, z.discriminatedUnion('kind', [
-    z
-        .object({
-        kind: z.literal(PredicateKind.ELEMENT),
-        query: ElementQuerySchema,
-        state: z.nativeEnum(ElementState).optional(),
-        absent: z.boolean().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.TEXT),
-        contains: z.string(),
-        visible: z.boolean().optional(),
-        absent: z.boolean().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.NET),
-        method: z.string().optional(),
-        urlContains: z.string().optional(),
-        status: z.number().optional(),
-        ok: z.boolean().optional(),
-        since: z.number().optional(),
-        count: z.number().int().nonnegative().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.ROUTE),
-        pathname: z.string().optional(),
-        contains: z.string().optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.CONSOLE),
-        level: z.string().optional(),
-        absent: z.boolean().optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.ANIMATION),
-        name: z.string().optional(),
-        target: z.string().optional(),
-        completed: z.boolean().optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.SIGNAL),
-        name: z.string().optional(),
-        dataMatches: z.record(z.unknown()).optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.STATE),
-        store: z.string().optional(),
-        path: z.string(),
-        equals: z.unknown().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.SETTLED),
-        quietMs: z.number().positive().optional(),
-    })
-        .strict(),
-    z
-        .object({ kind: z.literal(PredicateKind.ALL_OF), predicates: z.array(PredicateSchema) })
-        .strict(),
-    z
-        .object({ kind: z.literal(PredicateKind.ANY_OF), predicates: z.array(PredicateSchema) })
-        .strict(),
-    z.object({ kind: z.literal(PredicateKind.NOT), predicate: PredicateSchema }).strict(),
-])));
+function predicateUnion() {
+    return z.discriminatedUnion('kind', [
+        z
+            .object({
+            kind: z.literal(PredicateKind.ELEMENT),
+            query: ElementQuerySchema,
+            state: z.nativeEnum(ElementState).optional(),
+            absent: z.boolean().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.TEXT),
+            contains: z.string(),
+            visible: z.boolean().optional(),
+            absent: z.boolean().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.NET),
+            method: z.string().optional(),
+            urlContains: z.string().optional(),
+            status: z.number().optional(),
+            ok: z.boolean().optional(),
+            since: z.number().optional(),
+            count: z.number().int().nonnegative().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.ROUTE),
+            pathname: z.string().optional(),
+            contains: z.string().optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.CONSOLE),
+            level: z.string().optional(),
+            absent: z.boolean().optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.ANIMATION),
+            name: z.string().optional(),
+            target: z.string().optional(),
+            completed: z.boolean().optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.SIGNAL),
+            name: z.string().optional(),
+            dataMatches: z.record(z.unknown()).optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.STATE),
+            store: z.string().optional(),
+            path: z.string(),
+            equals: z.unknown().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.SETTLED),
+            quietMs: z.number().positive().optional(),
+        })
+            .strict(),
+        z
+            .object({ kind: z.literal(PredicateKind.ALL_OF), predicates: z.array(PredicateSchema) })
+            .strict(),
+        z
+            .object({ kind: z.literal(PredicateKind.ANY_OF), predicates: z.array(PredicateSchema) })
+            .strict(),
+        z.object({ kind: z.literal(PredicateKind.NOT), predicate: PredicateSchema }).strict(),
+    ]);
+}
+export const PredicateSchema = z.lazy(() => z.preprocess(applyPredicateAliases, predicateUnion()));
+/**
+ * The fields a given predicate kind accepts, read off the schema itself.
+ *
+ * Derived rather than listed so the two can never disagree: a rejection message that names a stale
+ * field set is worse than one that names none, because the agent trusts it and retries into the same
+ * wall. Empty for a kind that is not in the union.
+ */
+export function predicateFieldsFor(kind) {
+    for (const option of predicateUnion().options) {
+        const literal = option.shape['kind'];
+        if (literal instanceof z.ZodLiteral && literal.value === kind) {
+            return Object.keys(option.shape).filter((field) => 'kind' !== field);
+        }
+    }
+    return [];
+}
 function str(value) {
     return 'string' === typeof value ? value : undefined;
 }
@@ -189,7 +348,37 @@ export function matchValue(got, want) {
         }
         return true;
     }
-    return got === want;
+    return structurallyEqual(got, want);
+}
+/**
+ * Value equality for the leaf comparison, because `===` could never match a literal.
+ *
+ * The expected side of a predicate is parsed out of the agent's JSON, so it is a fresh object every
+ * time — reference equality made `equals: ["a", "b"]` false against a store holding exactly
+ * `["a", "b"]`, and there was no value of the app's state that could have made it true. The mirror of
+ * a false green: an assertion nobody could satisfy, on the commonest thing there is to assert about.
+ *
+ * Deliberately strict about shape. An array is not an object, an extra key is a difference, and order
+ * is part of a list's value — `equals` means equals; `dataMatches` is the field-by-field one.
+ */
+function structurallyEqual(got, want) {
+    if (got === want)
+        return true;
+    if (null === got || null === want)
+        return false;
+    if ('object' !== typeof got || 'object' !== typeof want)
+        return false;
+    if (Array.isArray(got) !== Array.isArray(want))
+        return false;
+    if (Array.isArray(got) && Array.isArray(want)) {
+        return got.length === want.length && got.every((v, i) => structurallyEqual(v, want[i]));
+    }
+    const a = got;
+    const b = want;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((k) => k in b && structurallyEqual(a[k], b[k]));
 }
 /** Shallow JSON pattern match: each key in `pattern` must match (see matchValue). */
 function dataMatches(actual, pattern) {
@@ -419,7 +608,7 @@ export function evalSignal(events, p) {
             ? `signal '${p.name ?? '(any)'}' fired ${String(sameName.length)}x, payload: ${JSON.stringify(sameName[0])}`
             : // Name what DID fire: a typo'd signal name and a genuinely dead action produce the same
                 // sentence otherwise, and the agent cannot tell them apart. See observed-in-window.ts.
-                `signal '${p.name ?? '(any)'}' never fired — ${describeObserved('signals', events.filter((e) => e.type === EventType.SIGNAL).map((e) => str(e.data['name']) ?? ''))}`,
+                `signal '${p.name ?? '(any)'}' never fired; ${describeObserved('signals', events.filter((e) => e.type === EventType.SIGNAL).map((e) => str(e.data['name']) ?? ''))}`,
         expected: p.dataMatches === undefined
             ? `signal '${p.name ?? '(any)'}' to fire`
             : `signal '${p.name ?? '(any)'}' with payload matching ${JSON.stringify(p.dataMatches)}`,

package/dist/events/predicate-parse.d.ts

@@ -1,7 +1,7 @@
 /**
  * One readable sentence when a predicate does not parse — never the zod array.
  *
- * Measured 2026-08-10: **9 of 58 tool errors that day were a serialized zod issue array**, all on
+ * In the field a meaningful share of all tool errors were **a serialized zod issue array**, all on
  * `reticle_act_and_wait`, `reticle_wait_for` and `reticle_assert` — the three tools that produced
  * every action-derived finding in the dataset. The least readable error we emit was landing on the
  * highest-value path, and an agent had to `JSON.parse` an error string to learn which field it got

package/dist/events/predicate-parse.js

@@ -1,7 +1,7 @@
 /**
  * One readable sentence when a predicate does not parse — never the zod array.
  *
- * Measured 2026-08-10: **9 of 58 tool errors that day were a serialized zod issue array**, all on
+ * In the field a meaningful share of all tool errors were **a serialized zod issue array**, all on
  * `reticle_act_and_wait`, `reticle_wait_for` and `reticle_assert` — the three tools that produced
  * every action-derived finding in the dataset. The least readable error we emit was landing on the
  * highest-value path, and an agent had to `JSON.parse` an error string to learn which field it got
@@ -13,7 +13,8 @@
  * show a valid call.
  */
 import { z } from 'zod';
-import { PredicateSchema } from './predicate-eval.js';
+import { PredicateKind } from '@reticlehq/core';
+import { PredicateSchema, predicateFieldsFor } from './predicate-eval.js';
 /** A valid call, short enough to sit inside an error without becoming the error. */
 const EXAMPLE = '{ kind: "signal", name: "todos:loaded" }';
 /** `path: ["net","urlContains"]` → `net.urlContains`; an empty path means the object itself. */
@@ -49,6 +50,19 @@ export function parsePredicate(input) {
     // back is how the zod array became unreadable in the first place.
     const issues = parsed.error.issues.slice(0, 3).map(describeIssue).join('; ');
     throw new Error(`that predicate did not parse (kind "${kind}"): ${issues}. Nothing ran — the predicate was ` +
-        `not evaluated, so no verdict was produced. Call reticle_tools for the fields this kind ` +
-        `accepts. A valid call looks like: ${EXAMPLE}`);
+        `not evaluated, so no verdict was produced. ${accepted(kind)} ` +
+        `A valid call looks like: ${EXAMPLE}`);
+}
+/**
+ * What WOULD have worked, in the same breath as what did not.
+ *
+ * Telling an agent only which field is wrong leaves it guessing again, and each guess costs another
+ * round trip on the one call path that produces verdicts. Naming the accepted fields — or, when the
+ * kind itself is the mistake, the accepted kinds — makes the retry informed instead.
+ */
+function accepted(kind) {
+    const fields = predicateFieldsFor(kind);
+    if (0 < fields.length)
+        return `${kind} accepts: ${fields.join(', ')}.`;
+    return `"${kind}" is not a predicate kind — use one of: ${Object.values(PredicateKind).join(', ')}.`;
 }