@reticlehq/server 2.4.0 → 2.6.0

package/dist/events/predicate-eval.js

@@ -1,84 +1,153 @@
-import { ElementQuerySchema, ElementState, EventType, } from '@reticlehq/core';
+import { ElementQuerySchema, ElementState, EventType, PredicateKind, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
 import { z } from 'zod';
-export const PredicateSchema = z.lazy(() => z.discriminatedUnion('kind', [
-    z.object({
-        kind: z.literal('element'),
+import { describeObserved } from './observed-in-window.js';
+/**
+ * Spellings an agent plausibly reaches for, mapped to the real field.
+ *
+ * `route` spells its field `pathname` while `state`, in the same union, spells its `path`. Every one
+ * of these was silently DROPPED before, and because these kinds have all-optional fields, dropping
+ * the only key supplied left a predicate that asserts nothing and passes on anything.
+ */
+const PREDICATE_ALIASES = {
+    // `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
+    // one — route's `contains` matches the WHOLE route (path + query + fragment), so "the URL
+    // contains this" is precisely what it does — and asserting a redirect after login is the single
+    // most common thing an agent reaches for here.
+    [PredicateKind.ROUTE]: { path: 'pathname', urlContains: 'contains', url: 'contains' },
+    [PredicateKind.NET]: { url: 'urlContains' },
+    [PredicateKind.SIGNAL]: { data: 'dataMatches' },
+};
+/** 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 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 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.
+ */
+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(),
-    }),
-    z.object({
-        kind: z.literal('text'),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.TEXT),
         contains: z.string(),
         visible: z.boolean().optional(),
         absent: z.boolean().optional(),
-    }),
-    z.object({
-        kind: z.literal('net'),
+    })
+        .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(),
-    }),
-    z.object({
-        kind: z.literal('route'),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.ROUTE),
         pathname: z.string().optional(),
         contains: z.string().optional(),
-    }),
-    z.object({
-        kind: z.literal('console'),
+        since: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.CONSOLE),
         level: z.string().optional(),
         absent: z.boolean().optional(),
         since: z.number().optional(),
-    }),
-    z.object({
-        kind: z.literal('animation'),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.ANIMATION),
         name: z.string().optional(),
         target: z.string().optional(),
         completed: z.boolean().optional(),
-    }),
-    z.object({
-        kind: z.literal('signal'),
+        since: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.SIGNAL),
         name: z.string().optional(),
         dataMatches: z.record(z.unknown()).optional(),
-    }),
-    z.object({
-        kind: z.literal('state'),
+        since: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.STATE),
         store: z.string().optional(),
         path: z.string(),
         equals: z.unknown().optional(),
-    }),
-    z.object({ kind: z.literal('settled'), quietMs: z.number().positive().optional() }),
-    z.object({ kind: z.literal('allOf'), predicates: z.array(PredicateSchema) }),
-    z.object({ kind: z.literal('anyOf'), predicates: z.array(PredicateSchema) }),
-    z.object({ kind: z.literal('not'), predicate: PredicateSchema }),
-]));
+    })
+        .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 str(value) {
-    return typeof value === 'string' ? value : undefined;
+    return 'string' === typeof value ? value : undefined;
 }
 function num(value) {
-    return typeof value === 'number' ? value : undefined;
+    return 'number' === typeof value ? value : undefined;
 }
 /**
  * Match one value against a pattern. Supports `*` (present), strict equality, and operators:
  * `{$gte,$lte,$gt,$lt}` (numbers), `{$contains}` (array membership or substring), `{$length}`.
  */
 export function matchValue(got, want) {
-    if (want === '*')
+    if ('*' === want)
         return got !== undefined;
     // An object is an OPERATOR container only if it actually carries a `$`-prefixed operator. An empty
     // `{}` (or an object with no `$` key) used to enter this branch, iterate zero recognized operators,
     // and `return true` — so `equals: {}` / `dataMatches: {status: {}}` was a green assertion that
     // passed against ANYTHING, undefined included: the exact false green the oracle exists to catch.
     // Without an operator it is a literal to compare, and falls through to strict equality below.
-    const ops = typeof want === 'object' && want !== null && !Array.isArray(want)
+    const ops = 'object' === typeof want && want !== null && !Array.isArray(want)
         ? Object.entries(want)
         : undefined;
     if (ops !== undefined && ops.some(([op]) => op.startsWith('$'))) {
         for (const [op, val] of ops) {
-            const n = typeof got === 'number' ? got : NaN;
+            const n = 'number' === typeof got ? got : NaN;
             switch (op) {
                 case '$gte':
                     if (!(n >= val))
@@ -101,7 +170,7 @@ export function matchValue(got, want) {
                         if (!got.includes(val))
                             return false;
                     }
-                    else if (typeof got === 'string') {
+                    else if ('string' === typeof got) {
                         if (!got.includes(String(val)))
                             return false;
                     }
@@ -110,7 +179,7 @@ export function matchValue(got, want) {
                     }
                     break;
                 case '$length':
-                    if (!((Array.isArray(got) || typeof got === 'string') && got.length === val)) {
+                    if (!((Array.isArray(got) || 'string' === typeof got) && got.length === val)) {
                         return false;
                     }
                     break;
@@ -140,11 +209,27 @@ function dataMatches(actual, pattern) {
  * This exists so an agent can assert on the OUTCOME rather than on a number Reticle invented.
  */
 function callSucceeded(data) {
-    if (typeof data['ok'] === 'boolean')
+    if ('boolean' === typeof data['ok'])
         return data['ok'];
     const status = num(data['status']);
     return status === undefined || status < 400;
 }
+/**
+ * One call, as the failure report should name it: `POST /api/generate-script → 500`.
+ *
+ * The status used to be dropped here, which made the most common net failure unreadable. Asserting
+ * `{status: 200}` against a call that returned 500 reported only `POST /api/generate-script` — the
+ * very field the predicate filtered on was missing from the account of what was seen, so the agent
+ * is told the call happened and left to guess why it did not match.
+ *
+ * The arrow is OMITTED when there is no status. An in-flight or aborted request genuinely has none,
+ * and `→ undefined` would be a fabricated fact about the wire.
+ */
+function describeCall(e) {
+    const head = `${str(e.data['method']) ?? 'GET'} ${str(e.data['url']) ?? ''}`;
+    const status = num(e.data['status']);
+    return status === undefined ? head : `${head} → ${String(status)}`;
+}
 export function evalNet(events, p) {
     const since = p.since ?? 0;
     const matches = events.filter((e) => {
@@ -183,7 +268,9 @@ export function evalNet(events, p) {
         : {
             pass: false,
             failureReason: `no network call matched ${JSON.stringify(p)}`,
-            observed: 'no matching network call in the window',
+            // Same reasoning as the signal miss: "no matching call" cannot be told apart from "the app
+            // made no calls at all", and those need different fixes.
+            observed: describeObserved('calls', events.filter((e) => e.type === EventType.NET_REQUEST).map(describeCall)),
             expected: `at least one call matching ${JSON.stringify(p)}`,
             assertion: 'net.present',
         };
@@ -257,17 +344,17 @@ export function evalConsole(events, p) {
                 e.type === EventType.CONSOLE_ERROR ||
                 e.type === EventType.ERROR_UNCAUGHT);
         }
-        if (p.level === 'error')
+        if ('error' === p.level)
             return isErr;
         return e.type === CONSOLE_LEVEL_TYPE[p.level];
     });
-    if (p.absent === true) {
-        return matches.length === 0
+    if (true === p.absent) {
+        return 0 === matches.length
             ? { pass: true, evidence: { absent: true } }
             : {
                 pass: false,
                 failureReason: `expected no ${p.level ?? 'console'} entries but found ${String(matches.length)}`,
-                observed: `${String(matches.length)} ${p.level ?? 'console'} entr${matches.length === 1 ? 'y' : 'ies'}`,
+                observed: `${String(matches.length)} ${p.level ?? 'console'} entr${1 === matches.length ? 'y' : 'ies'}`,
                 expected: `no ${p.level ?? 'console'} entries`,
                 assertion: 'console.absent',
                 evidence: matches.map((e) => e.data),
@@ -284,7 +371,7 @@ export function evalConsole(events, p) {
         };
 }
 export function evalAnimation(events, p) {
-    const wantType = p.completed === true ? EventType.ANIM_END : EventType.ANIM_START;
+    const wantType = true === p.completed ? EventType.ANIM_END : EventType.ANIM_START;
     const hit = events.find((e) => {
         if (e.type !== wantType)
             return false;
@@ -330,7 +417,9 @@ export function evalSignal(events, p) {
             : `no signal matched ${JSON.stringify(p)}`,
         observed: sameName.length > 0
             ? `signal '${p.name ?? '(any)'}' fired ${String(sameName.length)}x, payload: ${JSON.stringify(sameName[0])}`
-            : `signal '${p.name ?? '(any)'}' never fired in the window`,
+            : // 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']) ?? ''))}`,
         expected: p.dataMatches === undefined
             ? `signal '${p.name ?? '(any)'}' to fire`
             : `signal '${p.name ?? '(any)'}' with payload matching ${JSON.stringify(p.dataMatches)}`,
@@ -364,6 +453,12 @@ const SETTLE_ACTIVITY = new Set([
     EventType.DOM_REMOVED,
     EventType.DOM_ATTR,
 ]);
+/** The three net-shaped event types a URL can be read off — the only ones dev tooling can produce. */
+const NET_TYPES = new Set([
+    EventType.NET_PENDING,
+    EventType.NET_REQUEST,
+    EventType.NET_STREAM,
+]);
 /** Default quiet window — enough to absorb a render+xhr settle without waiting on slow polls. */
 const DEFAULT_QUIET_MS = 500;
 /**
@@ -372,8 +467,24 @@ const DEFAULT_QUIET_MS = 500;
  * now, not to any buffered event — so `now` is injected (CLAUDE.md rule 7), and the wait loop's
  * poll interval is what eventually flips this to pass once activity stops.
  */
-export function evalSettled(events, p, now) {
+export function evalSettled(allEvents, p, now) {
     const quietMs = p.quietMs ?? DEFAULT_QUIET_MS;
+    // Dev-tooling traffic is the framework talking about ITSELF (see DevToolingChannel) and says
+    // nothing about whether the app finished its work — but it was holding settle open. Dropped from
+    // both halves of the calculation below (in-flight AND the quiet timer) and DISCLOSED on the
+    // evidence, never silently swallowed.
+    const ignoredDevTooling = [];
+    const events = allEvents.filter((e) => {
+        if (!NET_TYPES.has(e.type))
+            return true;
+        const url = str(e.data['url']);
+        if (!isDevToolingUrl(url))
+            return true;
+        if (url !== undefined && !ignoredDevTooling.includes(url))
+            ignoredDevTooling.push(url);
+        return false;
+    });
+    const disclosure = 0 === ignoredDevTooling.length ? {} : { ignoredDevTooling };
     // A request that STARTED (NET_PENDING) but never completed (NET_REQUEST with the same id) is
     // still in flight — the page is NOT settled no matter how quiet the DOM has gone. Without this,
     // a slow save reads as "settled" the instant its spinner stops mutating the DOM: the exact
@@ -417,16 +528,16 @@ export function evalSettled(events, p, now) {
         if (id === undefined)
             continue;
         const direction = str(e.data['direction']);
-        if (direction === 'open')
+        if (StreamDirection.OPEN === direction)
             openStreams.add(id);
-        else if (direction === 'close')
+        else if (StreamDirection.CLOSE === direction)
             openStreams.delete(id);
     }
     const streaming = openStreams.size;
     if (inFlight + streaming > 0) {
-        const what = streaming === 0
+        const what = 0 === streaming
             ? `${String(inFlight)} request(s) still in flight`
-            : inFlight === 0
+            : 0 === inFlight
                 ? `${String(streaming)} response body(ies) still streaming`
                 : `${String(inFlight)} request(s) in flight and ${String(streaming)} response body(ies) still streaming`;
         return {
@@ -435,7 +546,12 @@ export function evalSettled(events, p, now) {
             observed: what,
             expected: 'no requests in flight and no response bodies still streaming',
             assertion: 'settled.in-flight',
-            evidence: { settled: false, inFlight, ...(streaming > 0 ? { streaming } : {}) },
+            evidence: {
+                settled: false,
+                inFlight,
+                ...(streaming > 0 ? { streaming } : {}),
+                ...disclosure,
+            },
         };
     }
     let lastT = -1;
@@ -449,12 +565,15 @@ export function evalSettled(events, p, now) {
     if (lastT < 0) {
         return {
             pass: true,
-            evidence: { settled: true, quietForMs: null, note: 'no activity to settle' },
+            evidence: { settled: true, quietForMs: null, note: 'no activity to settle', ...disclosure },
         };
     }
     const quietForMs = now - lastT;
     if (quietForMs >= quietMs) {
-        return { pass: true, evidence: { settled: true, quietForMs, lastActivity: lastType } };
+        return {
+            pass: true,
+            evidence: { settled: true, quietForMs, lastActivity: lastType, ...disclosure },
+        };
     }
     return {
         pass: false,
@@ -462,6 +581,11 @@ export function evalSettled(events, p, now) {
         observed: `last activity was ${String(lastType)}, ${String(quietForMs)}ms ago`,
         expected: `${String(quietMs)}ms of quiet`,
         assertion: 'settled.quiet',
-        evidence: { quietForMs, lastActivity: lastType },
+        evidence: { quietForMs, lastActivity: lastType, ...disclosure },
+        // The one failure in this file that knows exactly when it could stop being one: if nothing else
+        // happens, the window closes in this many ms. A waiter that re-checks THEN instead of on its next
+        // blind tick stops paying up to a full poll interval on the hottest call in the product. Only a
+        // hint — the predicate is still evaluated at that moment, and can still fail.
+        retryAfterMs: quietMs - quietForMs,
     };
 }

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

@@ -0,0 +1,23 @@
+/**
+ * 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
+ * `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
+ * wrong.
+ *
+ * `PredicateSchema.parse()` throws a `ZodError` whose `.message` IS that array, and three handlers
+ * call it directly. This wraps it once, so every caller gets the same shape rather than each
+ * growing its own catch — the pattern #108 asks for: name the parameter, say whether anything ran,
+ * show a valid call.
+ */
+import { z } from 'zod';
+import { PredicateSchema } from './predicate-eval.js';
+/**
+ * Parse a predicate, or throw an Error whose message is a sentence.
+ *
+ * Deliberately still THROWS: every call site already handles a throw, and turning this into a
+ * result type would mean touching three handlers to gain nothing the message does not already say.
+ */
+export declare function parsePredicate(input: unknown): z.infer<typeof PredicateSchema>;

package/dist/events/predicate-parse.js

@@ -0,0 +1,54 @@
+/**
+ * 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
+ * `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
+ * wrong.
+ *
+ * `PredicateSchema.parse()` throws a `ZodError` whose `.message` IS that array, and three handlers
+ * call it directly. This wraps it once, so every caller gets the same shape rather than each
+ * growing its own catch — the pattern #108 asks for: name the parameter, say whether anything ran,
+ * show a valid call.
+ */
+import { z } from 'zod';
+import { PredicateSchema } 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. */
+function pathOf(issue) {
+    return 0 === issue.path.length ? 'the predicate' : issue.path.map(String).join('.');
+}
+/**
+ * One issue, as a clause a human or an agent can act on.
+ *
+ * `unrecognized_keys` is the common case by far and the one worth spelling out — it is what a
+ * plausible-but-wrong field name produces, and the key itself is the whole answer.
+ */
+function describeIssue(issue) {
+    if (z.ZodIssueCode.unrecognized_keys === issue.code) {
+        return `unknown field ${issue.keys.join(', ')}`;
+    }
+    return `${pathOf(issue)}: ${issue.message}`;
+}
+/**
+ * Parse a predicate, or throw an Error whose message is a sentence.
+ *
+ * Deliberately still THROWS: every call site already handles a throw, and turning this into a
+ * result type would mean touching three handlers to gain nothing the message does not already say.
+ */
+export function parsePredicate(input) {
+    const parsed = PredicateSchema.safeParse(input);
+    if (parsed.success)
+        return parsed.data;
+    const kind = 'object' === typeof input && null !== input && 'kind' in input
+        ? String(input['kind'])
+        : 'unknown';
+    // Bounded on purpose: a union rejection can produce one issue per member, and pasting all of them
+    // 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}`);
+}

package/dist/events/predicate.d.ts

@@ -1,8 +1,8 @@
-import { type CommandResult, type ReticleEvent } from '@reticlehq/core';
+import { PredicateKind, type CommandResult, type ReticleEvent } from '@reticlehq/core';
 import type { ExpectedLink } from '../capsule/divergence.js';
 import { type AmbientCounts } from '../journal/ambient.js';
 import { PredicateSchema, type Predicate, type EvalResult } from './predicate-eval.js';
-export { PredicateSchema };
+export { PredicateSchema, PredicateKind };
 export type { Predicate, EvalResult };
 /** The subset of Session the predicate engine needs — keeps it testable with a fake. */
 export interface PredicateSession {
@@ -17,6 +17,11 @@ export interface PredicateSession {
      * Optional: a session without ambient learning simply omits it and settle behaves as before.
      */
     ambientCounts?(): AmbientCounts;
+    /**
+     * Subscribe to session disconnect. Returns an unsubscribe function. Optional: a session without
+     * this hook (e.g. tests that never disconnect) simply leaves in-flight predicates until timeout.
+     */
+    onDisconnect?(listener: () => void): () => void;
 }
 export declare function evaluatePredicate(session: PredicateSession, predicate: Predicate, since?: number, diagnose?: boolean): Promise<EvalResult>;
 /**