@reticlehq/server 2.8.0 → 2.10.0

package/dist/events/declared.js

@@ -0,0 +1,73 @@
+/**
+ * What the caller DECLARED before acting — the oracle, read back.
+ *
+ * `act_and_wait` asks the agent to name the expected consequence BEFORE the action, and that
+ * declaration was then thrown away: everything downstream judged the window as if nobody had said
+ * what they were expecting. Two measured consequences, one bug:
+ *
+ *  - An error path can be declared exactly — `{ net, POST, /api/login, status: 500 }` — and the
+ *    contradiction hunter still reported `ui-advanced-request-failed`, because a failed request plus
+ *    a moved DOM is all it can see. The failure was EXPECTED and said so in the predicate, so a
+ *    verdict of "channels disagree" is a statement about a disagreement nobody had.
+ *  - A destination whose content was asserted and FOUND was still reported as
+ *    `route-rendered-nothing`, a clause the element evidence beside it disproves.
+ *
+ * Deliberately conservative about what counts as declared. Only what the caller REQUIRED is read:
+ * the top level and `allOf` chains. An `anyOf` branch may never have held, and a `not` declares the
+ * opposite of a consequence — honouring either would suppress a real finding on the strength of
+ * something that never happened. Pure: a predicate in, a description out.
+ */
+import { PredicateKind } from '@reticlehq/core';
+/** Below this, a status is a success or a redirect: not a declared failure. */
+const FAILURE_STATUS_MIN = 400;
+export function declaredExpectations(predicate) {
+    const netFailures = [];
+    let rendersContent = false;
+    const walk = (p) => {
+        switch (p.kind) {
+            case PredicateKind.ALL_OF:
+                for (const child of p.predicates)
+                    walk(child);
+                return;
+            case PredicateKind.NET: {
+                const declaredFailure = false === p.ok || (p.status !== undefined && p.status >= FAILURE_STATUS_MIN);
+                if (!declaredFailure)
+                    return;
+                netFailures.push({
+                    ...(p.method === undefined ? {} : { method: p.method }),
+                    ...(p.urlContains === undefined ? {} : { urlContains: p.urlContains }),
+                    ...(p.status === undefined ? {} : { status: p.status }),
+                });
+                return;
+            }
+            case PredicateKind.ELEMENT:
+            case PredicateKind.TEXT:
+                if (true !== p.absent)
+                    rendersContent = true;
+                return;
+            default:
+                return;
+        }
+    };
+    if (predicate !== undefined)
+        walk(predicate);
+    return { netFailures, rendersContent };
+}
+/**
+ * Does a call the window recorded match a failure the caller declared?
+ *
+ * Every field the caller named must agree — a declaration about `POST /api/login → 500` says nothing
+ * about `POST /api/orders`, and treating it as a blanket amnesty for failed requests would remove
+ * the check rather than inform it. Fields the caller left out are not constraints.
+ */
+export function matchesDeclaredFailure(call, declared) {
+    return declared.some((d) => {
+        if (d.method !== undefined && d.method.toUpperCase() !== call.method.toUpperCase())
+            return false;
+        if (d.urlContains !== undefined && !call.url.includes(d.urlContains))
+            return false;
+        if (d.status !== undefined && d.status !== call.status)
+            return false;
+        return true;
+    });
+}

package/dist/events/echo-mismatch.d.ts

@@ -1,4 +1,10 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
-/** Contradictions for writes whose response echoes a different value than the request asked for. */
-export declare function findEchoMismatches(events: readonly ReticleEvent[]): Contradiction[];
+import type { OwnContradiction } from './contradictions.js';
+/**
+ * Contradictions for writes whose response echoes a different value than the request asked for.
+ *
+ * `actionSince` is the attribution floor `findContradictions` already keeps — the event time the
+ * action that opened this window was dispatched. A finding about a request that had already settled
+ * before the agent acted otherwise reads as a verdict on the change it just made.
+ */
+export declare function findEchoMismatches(events: readonly ReticleEvent[], actionSince?: number): OwnContradiction[];

package/dist/events/echo-mismatch.js

@@ -1,4 +1,4 @@
-import { ContradictionKind, EventType } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core';
 /**
  * A write that returned OK and quietly did not apply part of what it was asked to.
  *
@@ -18,6 +18,11 @@ import { ContradictionKind, EventType } from '@reticlehq/core';
  * would fire on healthy APIs constantly, and a contradiction kind that cries wolf gets filtered out
  * by the agents reading it, taking the true positives with it. So:
  *
+ *  - only requests that are WRITES are considered. Reported from the field: a lookup that sends its
+ *    key in the body (`POST /get-branding` with `{workspace_id}`) and gets a record back was graded
+ *    as a half-applied write. The gate was on the RESPONSE being a success and never on the REQUEST
+ *    being a write, so every successful call carrying a body read as a save — and the same key name
+ *    legitimately means different things on the two sides of a request/response pair;
  *  - only keys the request actually SENT are considered;
  *  - only scalars, since deep structural diffing is where the false positives live;
  *  - values are compared NORMALISED (trimmed, case-folded, numbers as numbers), so `FR` vs `fr` and
@@ -89,12 +94,33 @@ function scalarsByKey(body, into = new Map(), depth = 0) {
 }
 const OK_MIN = 200;
 const OK_MAX = 300;
-/** Contradictions for writes whose response echoes a different value than the request asked for. */
-export function findEchoMismatches(events) {
+/**
+ * Contradictions for writes whose response echoes a different value than the request asked for.
+ *
+ * `actionSince` is the attribution floor `findContradictions` already keeps — the event time the
+ * action that opened this window was dispatched. A finding about a request that had already settled
+ * before the agent acted otherwise reads as a verdict on the change it just made.
+ */
+export function findEchoMismatches(events, actionSince) {
     const found = [];
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
+        // `MUTATING_METHODS` is the one definition of "is this a write" in the codebase — the same list
+        // `contradictions.ts`'s `isMutating` reads. A read has no fields to half-apply.
+        //
+        // KNOWN LIMIT, stated because it is easy to read this fix as bigger than it is: POST is in that
+        // list, so a lookup that POSTs its key and gets a record back — the shape actually reported —
+        // still reaches the comparison below. Method is the only signal available here, and a read-shaped
+        // POST is genuinely indistinguishable from a write by method alone.
+        //
+        // The tempting next step is to skip a pair whose JSON types disagree (a string key sent, a number
+        // echoed). Deliberately not taken: that also silences `{"qty":"5"}` answered with `3`, which is a
+        // real dropped write. A false negative here is a missed bug in someone's app, and that is not a
+        // trade this file makes to quieten a false positive.
+        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
+        if (!MUTATING_METHODS.includes(method.toUpperCase()))
+            continue;
         // 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'];
@@ -126,12 +152,14 @@ export function findEchoMismatches(events) {
         if (0 === dropped.length)
             continue;
         const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
-        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
+        const attribution = actionSince !== undefined && event.t < actionSince
+            ? ' — this request completed before the action being verified, so the finding is not about that change'
+            : '';
         found.push({
             kind: ContradictionKind.WRITE_FIELD_IGNORED,
             claim: 'the write returned success and the page treated it as saved',
             counter: `its own echo shows ${String(dropped.length)} field(s) NOT applied — ${dropped.join('; ')}`,
-            detail: `${method} ${url} — the server answered OK and returned a different value than it was asked to set, so the write half-applied; the UI has no way to know and will show the value the user typed`,
+            detail: `${method} ${url} — the server answered OK and returned a different value than it was asked to set, so the write half-applied; the UI has no way to know and will show the value the user typed${attribution}`,
         });
     }
     return found;

package/dist/events/event-filters.d.ts

@@ -57,7 +57,7 @@ interface NetCallView {
      */
     oneWay?: boolean;
 }
-export declare function projectNetCall(e: ReticleEvent): NetCallView;
+export declare function projectNetCall(e: ReticleEvent, includeBodies?: boolean): NetCallView;
 /**
  * Compact console-log summary for reticle_console output.
  *

package/dist/events/event-filters.js

@@ -86,7 +86,7 @@ export function reconcileNet(events) {
         .map((e) => ({ ...e, data: { ...e.data, status: 'pending', pending: true } }));
     return [...completed, ...unresolved].sort((a, b) => a.t - b.t);
 }
-export function projectNetCall(e) {
+export function projectNetCall(e, includeBodies = true) {
     const status = e.data['status'];
     const ms = asNumber(e.data['durationMs']);
     const statusText = asString(e.data['statusText']);
@@ -106,11 +106,14 @@ export function projectNetCall(e) {
         view.contentType = contentType;
     if (responseSize !== undefined)
         view.responseSize = responseSize;
-    if (requestBody !== undefined)
+    // Bodies dominate the payload of the most-called read tool, and are only occasionally the part
+    // anyone wanted — `bodies: false` on reticle_network drops them for a body-free listing (#401).
+    if (includeBodies && requestBody !== undefined)
         view.requestBody = requestBody;
-    if (responseBody !== undefined)
+    if (includeBodies && responseBody !== undefined)
         view.responseBody = responseBody;
-    if (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated']) {
+    if (includeBodies &&
+        (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated'])) {
         view.bodyTruncated = true;
     }
     if (ms !== undefined)

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

@@ -1,91 +1,6 @@
-import { ElementState, PredicateKind, type ElementDescriptor, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
-import { z } from 'zod';
-export type Predicate = {
-    kind: typeof PredicateKind.ELEMENT;
-    query: ElementQuery;
-    state?: ElementState;
-    absent?: boolean;
-} | {
-    kind: typeof PredicateKind.TEXT;
-    contains: string;
-    visible?: boolean;
-    absent?: boolean;
-} | {
-    kind: typeof PredicateKind.NET;
-    method?: string;
-    urlContains?: string;
-    status?: number;
-    /** Did the call succeed? The honest field for IPC, which has no status code. */
-    ok?: boolean;
-    since?: number;
-    count?: number;
-} | {
-    kind: typeof PredicateKind.ROUTE;
-    pathname?: string;
-    contains?: string;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.CONSOLE;
-    level?: string;
-    absent?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.ANIMATION;
-    name?: string;
-    target?: string;
-    completed?: boolean;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.SIGNAL;
-    name?: string;
-    dataMatches?: Record<string, unknown>;
-    since?: number;
-} | {
-    kind: typeof PredicateKind.STATE;
-    store?: string;
-    path: string;
-    equals?: unknown;
-} | {
-    kind: typeof PredicateKind.SETTLED;
-    quietMs?: number;
-} | {
-    kind: typeof PredicateKind.ALL_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.ANY_OF;
-    predicates: Predicate[];
-} | {
-    kind: typeof PredicateKind.NOT;
-    predicate: Predicate;
-};
-export interface ResidualQueryChecks {
-    /** Dropped fields this side CAN check, as [field, wanted value] pairs. */
-    checks: [string, string][];
-    /** Dropped fields with no descriptor to check them against — refuse rather than ignore. */
-    unusable: string[];
-}
-/**
- * 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 declare function residualQueryChecks(query: ElementQuery): ResidualQueryChecks;
-/** Does this element satisfy every field the locator dropped? */
-export declare function satisfiesResiduals(element: ElementDescriptor, checks: readonly [string, string][]): boolean;
-/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
-export declare function describeResidual(element: ElementDescriptor, field: string): string;
-export declare const PredicateSchema: z.ZodType<Predicate>;
-/**
- * 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 declare function predicateFieldsFor(kind: string): readonly string[];
+import { PredicateKind, type ReticleEvent } from '@reticlehq/core';
+import type { Predicate } from './predicate-schema.js';
+export * from './predicate-schema.js';
 export interface EvalResult {
     pass: boolean;
     /**
@@ -104,6 +19,19 @@ export interface EvalResult {
      * not a defect in the user's app, and reporting it as one puts agent mistakes into the bug count.
      */
     inconclusive?: string;
+    /**
+     * No later event in this window can change this answer, so waiting out the rest of the budget
+     * buys nothing.
+     *
+     * Set ONLY where that is provable, which is rarer than it looks. "The toast never appeared" is not
+     * decided — it is only knowable when the budget ends, and ending early there would manufacture the
+     * false negative the budget exists to prevent. Exact cardinality IS decided once exceeded, because
+     * a window only accumulates matches and a count cannot come back down.
+     *
+     * A scheduling fact, never a verdict: `pass` already says what the answer is, and this only says
+     * that it is final.
+     */
+    decided?: boolean;
     evidence?: unknown;
     failureReason?: string;
     /**
@@ -132,6 +60,7 @@ export interface EvalResult {
     expected?: string;
     assertion?: string;
 }
+export declare function str(value: unknown): string | undefined;
 /**
  * Match one value against a pattern. Supports `*` (present), strict equality, and operators:
  * `{$gte,$lte,$gt,$lt}` (numbers), `{$contains}` (array membership or substring), `{$length}`.
@@ -140,9 +69,6 @@ export declare function matchValue(got: unknown, want: unknown): boolean;
 export declare function evalNet(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.NET;
 }>): EvalResult;
-export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: typeof PredicateKind.ROUTE;
-}>): EvalResult;
 export declare function evalConsole(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.CONSOLE;
 }>): EvalResult;