@reticlehq/server 2.4.0 → 2.5.0

package/dist/events/echo-mismatch.js

@@ -31,7 +31,7 @@ import { ContradictionKind, EventType } from '@reticlehq/core';
 /** Bodies larger than this are skipped — a diff over a huge payload is neither cheap nor legible. */
 const MAX_ECHO_KEYS = 200;
 function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
 /**
  * Any JSON value, not just an object. An HTTP write sends an object; an IPC call sends its ARGUMENT
@@ -39,7 +39,7 @@ function isRecord(value) {
  * silently excluded every desktop write from this check — the exact platform the finding came from.
  */
 function parse(raw) {
-    if (typeof raw !== 'string' || raw.length === 0)
+    if (typeof raw !== 'string' || 0 === raw.length)
         return undefined;
     try {
         return JSON.parse(raw);
@@ -50,11 +50,11 @@ function parse(raw) {
 }
 /** Comparable form of a scalar. Non-scalars return undefined and are never compared. */
 function normalize(value) {
-    if (typeof value === 'string')
+    if ('string' === typeof value)
         return value.trim().toLowerCase();
-    if (typeof value === 'number')
+    if ('number' === typeof value)
         return Number.isFinite(value) ? String(value) : undefined;
-    if (typeof value === 'boolean')
+    if ('boolean' === typeof value)
         return String(value);
     return undefined;
 }
@@ -98,7 +98,7 @@ export function findEchoMismatches(events) {
         // IPC reports `ok` rather than a status; HTTP reports a status. Either must say success — a write
         // that already failed is a different (and louder) finding than one that half-applied.
         const status = event.data['status'];
-        const httpOk = typeof status === 'number' && status >= OK_MIN && status < OK_MAX;
+        const httpOk = 'number' === typeof status && status >= OK_MIN && status < OK_MAX;
         if (!httpOk && event.data['ok'] !== true)
             continue;
         const request = parse(event.data['requestBody']);
@@ -117,16 +117,16 @@ export function findEchoMismatches(events) {
             const values = echoed.get(key);
             // Not echoed at all = no evidence either way. Only a key the server chose to report back can
             // contradict the request, and silence is not a contradiction.
-            if (values === undefined || values.size === 0)
+            if (values === undefined || 0 === values.size)
                 continue;
             const [want] = [...wanted];
             if (want !== undefined && !values.has(want))
                 dropped.push(`${key}: asked ${want}, got ${[...values].join('/')}`);
         }
-        if (dropped.length === 0)
+        if (0 === dropped.length)
             continue;
-        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
-        const method = typeof event.data['method'] === 'string' ? event.data['method'] : '';
+        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
+        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
         found.push({
             kind: ContradictionKind.WRITE_FIELD_IGNORED,
             claim: 'the write returned success and the page treated it as saved',

package/dist/events/event-filters.js

@@ -98,7 +98,7 @@ export function projectNetCall(e) {
         method: asString(e.data['method']) ?? '',
         url: asString(e.data['url']) ?? '',
     };
-    if (typeof status === 'number' || typeof status === 'string')
+    if ('number' === typeof status || 'string' === typeof status)
         view.status = status;
     if (statusText !== undefined)
         view.statusText = statusText;
@@ -110,15 +110,15 @@ export function projectNetCall(e) {
         view.requestBody = requestBody;
     if (responseBody !== undefined)
         view.responseBody = responseBody;
-    if (e.data['requestBodyTruncated'] === true || e.data['responseBodyTruncated'] === true) {
+    if (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated']) {
         view.bodyTruncated = true;
     }
     if (ms !== undefined)
         view.ms = ms;
-    if (e.data['oneWay'] === true)
+    if (true === e.data['oneWay'])
         view.oneWay = true;
     const headers = e.data['headers'];
-    if (headers !== null && typeof headers === 'object') {
+    if (headers !== null && 'object' === typeof headers) {
         view.headers = headers;
     }
     return view;
@@ -146,7 +146,7 @@ export function projectConsoleLog(e) {
     const source = asString(e.data['source']);
     const line = e.data['line'];
     if (source !== undefined && source.length > 0) {
-        view.source = typeof line === 'number' ? `${source}:${String(line)}` : source;
+        view.source = 'number' === typeof line ? `${source}:${String(line)}` : source;
     }
     return view;
 }
@@ -165,7 +165,7 @@ export function matchConsole(e, level) {
         return false;
     if (level === undefined)
         return true;
-    return (e.type === `console.${level}` || (level === 'error' && e.type === EventType.ERROR_UNCAUGHT));
+    return (e.type === `console.${level}` || ('error' === level && e.type === EventType.ERROR_UNCAUGHT));
 }
 /** How many present calls/levels a zero-match hint samples before truncating. */
 const HINT_SAMPLE_MAX = 5;

package/dist/events/json-salvage.d.ts

@@ -15,7 +15,7 @@
  * before the cut and reports how many it had to drop, so a partial answer is delivered AS partial
  * rather than as a clean one.
  */
-export interface Salvaged {
+interface Salvaged {
     /** Parsed values — one whole body, or the records recovered from a truncated one. */
     values: unknown[];
     /** True when the payload was incomplete and only part of it could be read. */
@@ -30,3 +30,4 @@ export interface Salvaged {
  * costs nothing, because each record still carries its own id and its own fields.
  */
 export declare function salvageJson(raw: string): Salvaged;
+export {};

package/dist/events/json-salvage.js

@@ -38,22 +38,22 @@ function completeObjects(text) {
         if (inString) {
             if (escaped)
                 escaped = false;
-            else if (ch === '\\')
+            else if ('\\' === ch)
                 escaped = true;
-            else if (ch === '"')
+            else if ('"' === ch)
                 inString = false;
             continue;
         }
-        if (ch === '"') {
+        if ('"' === ch) {
             inString = true;
             continue;
         }
-        if (ch === '{') {
+        if ('{' === ch) {
             starts.push(i);
             depth += 1;
             continue;
         }
-        if (ch === '}') {
+        if ('}' === ch) {
             depth -= 1;
             // A negative depth means the cut removed an opening brace; nothing further is trustworthy.
             if (depth < 0)
@@ -63,7 +63,7 @@ function completeObjects(text) {
                 found.push({ depth: depth + 1, text: text.slice(start, i + 1) });
         }
     }
-    if (found.length === 0)
+    if (0 === found.length)
         return [];
     const shallowest = Math.min(...found.map((f) => f.depth));
     return found.filter((f) => f.depth === shallowest).map((f) => f.text);

package/dist/events/observed-in-window.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What DID happen, when the thing you asserted did not.
+ *
+ * "signal 'x' never fired" and "no matching network call" are true and useless: a typo'd name and a
+ * genuinely broken app produce the same sentence, and the agent cannot tell them apart without a
+ * round trip it does not know to make. `{ kind:'state' }` already answers a bad path by naming the
+ * stores that exist; this gives `signal` and `net` the same courtesy.
+ *
+ * It also distinguishes the two failures that matter: NOTHING happened in the window (the action did
+ * not do what you thought) versus things happened but not that one (you named it wrong).
+ */
+export declare function describeObserved(noun: string, seen: readonly string[]): string;

package/dist/events/observed-in-window.js

@@ -0,0 +1,21 @@
+/**
+ * What DID happen, when the thing you asserted did not.
+ *
+ * "signal 'x' never fired" and "no matching network call" are true and useless: a typo'd name and a
+ * genuinely broken app produce the same sentence, and the agent cannot tell them apart without a
+ * round trip it does not know to make. `{ kind:'state' }` already answers a bad path by naming the
+ * stores that exist; this gives `signal` and `net` the same courtesy.
+ *
+ * It also distinguishes the two failures that matter: NOTHING happened in the window (the action did
+ * not do what you thought) versus things happened but not that one (you named it wrong).
+ */
+/** Enough to recognise the one you meant; not so many that a chatty window floods the message. */
+const MAX_LISTED = 8;
+export function describeObserved(noun, seen) {
+    const unique = [...new Set(seen.filter((s) => s.length > 0))];
+    if (0 === unique.length)
+        return `no ${noun} at all in this window`;
+    const shown = unique.slice(0, MAX_LISTED);
+    const rest = unique.length - shown.length;
+    return `${noun} seen in this window: ${shown.join(', ')}${rest > 0 ? `, and ${String(rest)} more` : ''}`;
+}

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

@@ -1,17 +1,17 @@
-import { ElementState, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
+import { ElementState, PredicateKind, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
 import { z } from 'zod';
 export type Predicate = {
-    kind: 'element';
+    kind: typeof PredicateKind.ELEMENT;
     query: ElementQuery;
     state?: ElementState;
     absent?: boolean;
 } | {
-    kind: 'text';
+    kind: typeof PredicateKind.TEXT;
     contains: string;
     visible?: boolean;
     absent?: boolean;
 } | {
-    kind: 'net';
+    kind: typeof PredicateKind.NET;
     method?: string;
     urlContains?: string;
     status?: number;
@@ -20,44 +20,67 @@ export type Predicate = {
     since?: number;
     count?: number;
 } | {
-    kind: 'route';
+    kind: typeof PredicateKind.ROUTE;
     pathname?: string;
     contains?: string;
+    since?: number;
 } | {
-    kind: 'console';
+    kind: typeof PredicateKind.CONSOLE;
     level?: string;
     absent?: boolean;
     since?: number;
 } | {
-    kind: 'animation';
+    kind: typeof PredicateKind.ANIMATION;
     name?: string;
     target?: string;
     completed?: boolean;
+    since?: number;
 } | {
-    kind: 'signal';
+    kind: typeof PredicateKind.SIGNAL;
     name?: string;
     dataMatches?: Record<string, unknown>;
+    since?: number;
 } | {
-    kind: 'state';
+    kind: typeof PredicateKind.STATE;
     store?: string;
     path: string;
     equals?: unknown;
 } | {
-    kind: 'settled';
+    kind: typeof PredicateKind.SETTLED;
     quietMs?: number;
 } | {
-    kind: 'allOf';
+    kind: typeof PredicateKind.ALL_OF;
     predicates: Predicate[];
 } | {
-    kind: 'anyOf';
+    kind: typeof PredicateKind.ANY_OF;
     predicates: Predicate[];
 } | {
-    kind: 'not';
+    kind: typeof PredicateKind.NOT;
     predicate: Predicate;
 };
+/**
+ * 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 declare const PredicateSchema: z.ZodType<Predicate>;
 export interface EvalResult {
     pass: boolean;
+    /**
+     * For a TIME-based failure: how long until this predicate could first become true, if nothing else
+     * changes. Purely a scheduling hint for `waitForPredicate` — it replaces a blind poll tick with one
+     * timed to the moment that matters, and never decides anything. Absent when the wait is on an
+     * external event (a request in flight settles when the server answers, not on a clock).
+     */
+    retryAfterMs?: number;
+    /**
+     * Set when the assertion could not be EVALUATED — the call was under-specified or there was
+     * nothing instrumented to read — rather than evaluated and found false. Carries the sentence that
+     * names what is missing.
+     *
+     * `pass` stays false because nothing was proven, but a false that nobody could have made true is
+     * not a defect in the user's app, and reporting it as one puts agent mistakes into the bug count.
+     */
+    inconclusive?: string;
     evidence?: unknown;
     failureReason?: string;
     /**
@@ -82,19 +105,19 @@ export interface EvalResult {
  */
 export declare function matchValue(got: unknown, want: unknown): boolean;
 export declare function evalNet(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'net';
+    kind: typeof PredicateKind.NET;
 }>): EvalResult;
 export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'route';
+    kind: typeof PredicateKind.ROUTE;
 }>): EvalResult;
 export declare function evalConsole(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'console';
+    kind: typeof PredicateKind.CONSOLE;
 }>): EvalResult;
 export declare function evalAnimation(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'animation';
+    kind: typeof PredicateKind.ANIMATION;
 }>): EvalResult;
 export declare function evalSignal(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'signal';
+    kind: typeof PredicateKind.SIGNAL;
 }>): EvalResult;
 /**
  * "The page has gone quiet": no network/DOM/animation activity for at least `quietMs`. Needs the
@@ -102,6 +125,6 @@ export declare function evalSignal(events: ReticleEvent[], p: Extract<Predicate,
  * 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 declare function evalSettled(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: 'settled';
+export declare function evalSettled(allEvents: ReticleEvent[], p: Extract<Predicate, {
+    kind: typeof PredicateKind.SETTLED;
 }>, now: number): EvalResult;