@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,17 +0,0 @@
-/**
- * One readable sentence when a predicate does not parse — never the zod array.
- *
- * 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
- * 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';
-export declare function parsePredicate(input: unknown): z.infer<typeof PredicateSchema>;

package/dist/events/predicate-parse.js

@@ -1,175 +0,0 @@
-/**
- * One readable sentence when a predicate does not parse — never the zod array.
- *
- * 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
- * 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 { PredicateKind } from '@reticlehq/core';
-import { PredicateSchema, predicateFieldsFor, predicateNestedFieldsFor } from './predicate-eval.js';
-/**
- * One valid call PER KIND, because an example of another kind answers a question nobody asked.
- *
- * This was a single `signal` example shown for every rejection. Watched on a real drive: an agent got
- * the `element` shape wrong, was shown a `signal` example, got `element` wrong again, and was shown
- * the same `signal` example. A rejected predicate produces no verdict at all, so each of those was a
- * round trip that ended with nothing — and the one field an agent most needs (`element`'s nested
- * `query`) is exactly what a flat example cannot convey.
- *
- * Short by design: an example that grows past a line stops being read.
- */
-const EXAMPLES = {
-    [PredicateKind.ELEMENT]: '{ kind: "element", query: { role: "button", name: "Save" } }',
-    [PredicateKind.TEXT]: '{ kind: "text", contains: "Saved" }',
-    [PredicateKind.NET]: '{ kind: "net", method: "POST", urlContains: "/api/save", status: 200 }',
-    [PredicateKind.ROUTE]: '{ kind: "route", pathname: "/dashboard" }',
-    [PredicateKind.CONSOLE]: '{ kind: "console", level: "error", absent: true }',
-    [PredicateKind.ANIMATION]: '{ kind: "animation", name: "slide-in", completed: true }',
-    [PredicateKind.SIGNAL]: '{ kind: "signal", name: "todos:loaded" }',
-    [PredicateKind.STATE]: '{ kind: "state", path: "cart.total", equals: 0 }',
-    [PredicateKind.SETTLED]: '{ kind: "settled" }',
-    [PredicateKind.ALL_OF]: '{ kind: "allOf", predicates: [{ kind: "text", contains: "Saved" }, { kind: "console", level: "error", absent: true }] }',
-    [PredicateKind.ANY_OF]: '{ kind: "anyOf", predicates: [{ kind: "text", contains: "Saved" }, { kind: "text", contains: "Updated" }] }',
-    [PredicateKind.NOT]: '{ kind: "not", predicate: { kind: "text", contains: "Error" } }',
-};
-/** The fallback, for when the KIND itself is the mistake and there is no shape to demonstrate. */
-const GENERIC_EXAMPLE = '{ kind: "text", contains: "Saved" }';
-function exampleFor(kind) {
-    return EXAMPLES[kind] ?? GENERIC_EXAMPLE;
-}
-/** `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.
- */
-/**
- * The placeholder `verify_next` puts in the `until` it suggests, sent back unchanged.
- *
- * The nudge hands the agent a ready-made `act_and_wait` call with `ref` and `action` filled in from
- * the act that dispatched, and leaves the consequence blank on purpose: naming it is the one part
- * only the agent can know, and guessing would be Reticle inventing the assertion.
- *
- * Sent verbatim it parses as a perfectly valid text predicate that simply never matches, so the
- * verdict came back `verified:"no"` / "the declared consequence did not hold" — blaming the app for
- * a placeholder the agent forgot to replace, and sending it to hunt a defect that does not exist.
- * Measured on a live app before this guard: a confident, wrong, actionable-looking answer, which is
- * the exact failure the rest of this file exists to avoid.
- */
-const UNFILLED_PLACEHOLDER = /^<name the consequence/i;
-function placeholderValue(input) {
-    if ('object' !== typeof input || null === input)
-        return undefined;
-    const value = input['value'];
-    return 'string' === typeof value && UNFILLED_PLACEHOLDER.test(value) ? value : undefined;
-}
-export function parsePredicate(input) {
-    const unfilled = placeholderValue(input);
-    if (unfilled !== undefined) {
-        throw new Error(`that predicate still carries the placeholder from verify_next ("${unfilled}"). Nothing ran, ` +
-            'and no verdict was produced — which is deliberate: as written it would have failed and ' +
-            'blamed the app for a value you had not filled in yet. Replace it with the consequence ' +
-            'this action actually causes, and prefer one the action CHANGES: a signal, a request, a ' +
-            'route, or store state. Text on screen that was already there proves nothing.');
-    }
-    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. ${accepted(kind, parsed.error.issues)}` +
-        `${misplacedCallFields(input)} ` +
-        `A valid ${kind} predicate looks like: ${exampleFor(kind)}`);
-}
-/**
- * Arguments of the CALL that agents write inside the predicate instead.
- *
- * Reported from the field on `timeout_ms`, nested in `until` on an `act_and_wait` that had already
- * timed out once at the default budget. The rejection said "unknown field", which reads as "there is
- * no such thing" — so the obvious retry is to delete it and silently give up the longer budget that
- * was the point of writing it. It is not an unknown field; it is a real argument one level too deep.
- */
-const CALL_LEVEL_FIELDS = [
-    'timeout_ms',
-    'sessionId',
-    'ref',
-    'action',
-    'args',
-    'target',
-    'intent',
-];
-/** The clause naming where a misplaced call argument goes, or '' when nothing was misplaced. */
-function misplacedCallFields(input) {
-    if ('object' !== typeof input || null === input)
-        return '';
-    const written = Object.keys(input);
-    const misplaced = CALL_LEVEL_FIELDS.filter((field) => written.includes(field));
-    if (0 === misplaced.length)
-        return '';
-    const list = misplaced.join(', ');
-    // Named as a MOVE, not as a removal. Deleting the field is the reading of "unknown field" that
-    // costs the caller the thing it asked for.
-    return (` ${list} ${1 === misplaced.length ? 'is an argument' : 'are arguments'} of the CALL, not of ` +
-        `the predicate: ${1 === misplaced.length ? 'move it' : 'move them'} up beside \`until\` rather ` +
-        'than dropping it — nesting is why the predicate did not parse.');
-}
-/**
- * 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, issues) {
-    const fields = predicateFieldsFor(kind);
-    if (0 < fields.length) {
-        // A field whose value is an object is the one an agent cannot guess from its name alone, so
-        // expand it in the same breath rather than making the shape a second round trip.
-        //
-        // Only the field the rejection actually points at, though. Expanding every object-valued field
-        // of the kind makes the sentence longer the more the schema grows, and buries the one clause
-        // that answers the question asked — the same argument this file already makes for showing one
-        // example per kind instead of a generic one. `element` is the only kind with an object-valued
-        // field today, so the two agree except when the mistake is somewhere else entirely, which is
-        // the case pinned in the tests.
-        const all = predicateNestedFieldsFor(kind);
-        const blamed = new Set(issues
-            .map((issue) => issue.path[0])
-            .filter((field) => 'string' === typeof field));
-        const nested = Object.entries(all)
-            .filter(([field]) => blamed.has(field))
-            .map(([field, keys]) => ` ${field} accepts: ${keys.join(', ')}.`)
-            .join('');
-        return `${kind} accepts: ${fields.join(', ')}.${nested}`;
-    }
-    return `"${kind}" is not a predicate kind — use one of: ${Object.values(PredicateKind).join(', ')}.`;
-}

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

@@ -1,8 +0,0 @@
-/**
- * The reason this predicate cannot be evaluated, or undefined when it can.
- *
- * Only checks what is knowable WITHOUT the page — a locator that names fields the resolver drops is
- * wrong whatever the DOM contains, which is what makes it safe to refuse before acting. Anything
- * that depends on what is actually rendered is still decided after the action, where it belongs.
- */
-export declare function unevaluablePredicateReason(predicate: unknown): string | undefined;

package/dist/events/predicate-precheck.js

@@ -1,41 +0,0 @@
-import { residualQueryChecks } from './predicate-schema.js';
-/** Composite predicates nest; the unusable one can be at any depth. */
-const NESTED_KEYS = ['predicates', 'predicate'];
-const isRecord = (v) => 'object' === typeof v && null !== v;
-/** Every element query in a predicate tree, in the order a reader would meet them. */
-function elementQueries(predicate, found = []) {
-    if (!isRecord(predicate))
-        return found;
-    if (isRecord(predicate['query']))
-        found.push(predicate['query']);
-    for (const key of NESTED_KEYS) {
-        const nested = predicate[key];
-        if (Array.isArray(nested))
-            for (const child of nested)
-                elementQueries(child, found);
-        else if (isRecord(nested))
-            elementQueries(nested, found);
-    }
-    return found;
-}
-/**
- * The reason this predicate cannot be evaluated, or undefined when it can.
- *
- * Only checks what is knowable WITHOUT the page — a locator that names fields the resolver drops is
- * wrong whatever the DOM contains, which is what makes it safe to refuse before acting. Anything
- * that depends on what is actually rendered is still decided after the action, where it belongs.
- */
-export function unevaluablePredicateReason(predicate) {
-    for (const query of elementQueries(predicate)) {
-        const residual = residualQueryChecks(query);
-        if (0 === residual.unusable.length)
-            continue;
-        return (`the element locator ignores ${residual.unusable.map((f) => `\`${f}\``).join(', ')} ` +
-            `in ${JSON.stringify(query)} — it resolves by the first of by+value, component/source, role, ` +
-            'text, label, placeholder, testid, alt that is present, and nothing here can check the rest. ' +
-            'Assert them one locator at a time, or move the extra field into the locator. ' +
-            'Nothing was acted on: this predicate could never have been evaluated, so refusing it costs ' +
-            'you nothing and spending the action on it would have cost you the verdict.');
-    }
-    return undefined;
-}

package/dist/events/predicate-request-body.d.ts

@@ -1,50 +0,0 @@
-import { type EvalResult } from './predicate-eval.js';
-import type { PredicateKind } from '@reticlehq/core';
-import type { Predicate } from './predicate-schema.js';
-/** The net predicate as `describeNetFilter` types it. */
-type NetPredicate = Extract<Predicate, {
-    kind: typeof PredicateKind.NET;
-}>;
-/** A net predicate, narrowed to the fields this module reads. */
-interface RequestBodyPredicate {
-    requestBodyContains?: string;
-    requestBodyMatches?: Record<string, unknown>;
-}
-/**
- * What the filtering pass learned about calls that matched everything else.
- *
- * Accumulated during the single pass over events rather than recomputed after it, the way the
- * response-side trackers already are.
- */
-export interface RequestBodyState {
-    /** A call matched everything else but carried no recorded request body. */
-    unrecorded: boolean;
-    /** The request body a clause was checked against and did not match. */
-    mismatch?: string;
-    /** The prefix of a TRUNCATED request body the clause did not hold over — undecidable, not absent. */
-    truncated?: string;
-    /**
-     * A key whose CAPTURED value is `[REDACTED]`, so the clause cannot be judged at all.
-     *
-     * Request bodies go through the same redaction path as responses before they are ever recorded,
-     * so a clause on a sensitive key is unsatisfiable whatever the app sent. Grading that a mismatch
-     * would blame the application for the SDK's own redaction and send someone to fix a correct
-     * payload.
-     */
-    redactedField?: string;
-}
-export declare function newRequestBodyState(): RequestBodyState;
-/**
- * Does this event satisfy the predicate's request-body clauses? Records why not in `state`.
- *
- * Returns true when there is nothing to check, so callers can apply it unconditionally.
- */
-export declare function checkRequestBody(data: Record<string, unknown>, predicate: RequestBodyPredicate, state: RequestBodyState): boolean;
-/**
- * The verdict for a request-body clause nothing satisfied, or `undefined` to fall through.
- *
- * Ranked the way the response side ranks its own: the two nobody could have answered (redacted,
- * unrecorded, truncated) come before the one that WAS answered and came out false.
- */
-export declare function requestBodyVerdict(state: RequestBodyState, predicate: NetPredicate, matchCount: number): EvalResult | undefined;
-export {};

package/dist/events/predicate-request-body.js

@@ -1,120 +0,0 @@
-/**
- * Asserting on what the UI SENT, not on what came back (#798).
- *
- * `net.bodyContains` searches the response only, and the comment on it says why: searching the
- * request too would let it pass on the very defect it exists to catch (the app sent `1187.01`, so
- * that string is in the request whatever the server then did with it). That reasoning is right, and
- * it leaves a real gap. For a filter, a search box or a form, the thing under test IS the outgoing
- * payload — "applying this filter actually sends it" had no verdict at all, only
- * `reticle_network { bodies: true }` and a person reading `requestBody` by eye.
- *
- * So these are separate fields rather than a mode on `bodyContains`: neither assertion can then be
- * satisfied by the wrong half of the exchange.
- *
- * Extracted from `predicate-eval.ts`, which was at the 1000-line cap.
- */
-import { REDACTED_VALUE } from '@reticlehq/core';
-import { clipBody, dataMatches, describeNetFilter, str, } from './predicate-eval.js';
-export function newRequestBodyState() {
-    return { unrecorded: false };
-}
-/**
- * Does this event satisfy the predicate's request-body clauses? Records why not in `state`.
- *
- * Returns true when there is nothing to check, so callers can apply it unconditionally.
- */
-export function checkRequestBody(data, predicate, state) {
-    const { requestBodyContains, requestBodyMatches } = predicate;
-    if (undefined === requestBodyContains && undefined === requestBodyMatches)
-        return true;
-    const sent = str(data['requestBody']);
-    if (sent === undefined) {
-        state.unrecorded = true;
-        return false;
-    }
-    const wasTruncated = true === data['requestBodyTruncated'];
-    const note = () => {
-        // The same rule the response side keeps: a needle missing from a body we hold only the first N
-        // bytes of is undecidable, not absent.
-        if (wasTruncated)
-            state.truncated ??= sent;
-        else
-            state.mismatch ??= sent;
-        return false;
-    };
-    if (requestBodyContains !== undefined && !sent.includes(requestBodyContains))
-        return note();
-    if (requestBodyMatches === undefined)
-        return true;
-    let payload;
-    try {
-        payload = JSON.parse(sent);
-    }
-    catch {
-        // Not JSON (a form post, plain text). A shallow key match cannot be applied, and guessing at
-        // form encoding here would answer a different question than the one asked. Use
-        // `requestBodyContains` for those.
-        return note();
-    }
-    if (null === payload || typeof payload !== 'object' || Array.isArray(payload))
-        return note();
-    const actual = payload;
-    const redacted = Object.keys(requestBodyMatches).find((key) => REDACTED_VALUE === actual[key]);
-    if (redacted !== undefined) {
-        state.redactedField ??= redacted;
-        return false;
-    }
-    return dataMatches(actual, requestBodyMatches) ? true : note();
-}
-/**
- * The verdict for a request-body clause nothing satisfied, or `undefined` to fall through.
- *
- * Ranked the way the response side ranks its own: the two nobody could have answered (redacted,
- * unrecorded, truncated) come before the one that WAS answered and came out false.
- */
-export function requestBodyVerdict(state, predicate, matchCount) {
-    if (matchCount > 0)
-        return undefined;
-    const wanted = JSON.stringify(predicate.requestBodyContains ?? predicate.requestBodyMatches);
-    if (state.redactedField !== undefined) {
-        const field = JSON.stringify(state.redactedField);
-        return {
-            pass: false,
-            inconclusive: `a call matching ${describeNetFilter(predicate)} was made, but its ${field} was REDACTED before the body was recorded, so this clause cannot be judged — a redacted field is unknown, not different. Assert on a non-sensitive key, or on the effect the value had`,
-            observed: `a matching request whose ${field} is ${REDACTED_VALUE}`,
-            expected: `a request body matching ${wanted}`,
-            assertion: 'net.requestBodyMatches',
-        };
-    }
-    if (state.unrecorded) {
-        return {
-            pass: false,
-            failureReason: `a call matched but its REQUEST body was not recorded, so the request-body clause could not be checked — enable it where the app calls connect(): reticle({ captureNetworkBodies: true })`,
-            observed: 'a matching call with no recorded request body',
-            expected: `a request body matching ${wanted}`,
-            assertion: 'net.requestBody',
-        };
-    }
-    if (state.truncated !== undefined) {
-        return {
-            pass: false,
-            inconclusive: `a call matching ${describeNetFilter(predicate)} was sent with a request body that was TRUNCATED before it was recorded, and the clause did not hold over the part that was kept — so this is undecidable, not a failure`,
-            observed: `the first ${String(state.truncated.length)} characters of a truncated request body ${JSON.stringify(clipBody(state.truncated))}`,
-            expected: `a request body matching ${wanted}`,
-            assertion: 'net.requestBody',
-        };
-    }
-    if (state.mismatch !== undefined) {
-        // Named separately from "no call matched", for the reason the response side already learned: the
-        // request DID fire, and reporting zero matches sends the caller to check the url and the method,
-        // which are both fine, instead of to the value the UI actually sent.
-        return {
-            pass: false,
-            failureReason: `a call matching ${describeNetFilter(predicate)} was sent with ${JSON.stringify(clipBody(state.mismatch))}, which does not match the request-body clause — the request fired, the payload is what differed`,
-            observed: `request body ${JSON.stringify(clipBody(state.mismatch))}`,
-            expected: `a request body matching ${wanted}`,
-            assertion: 'net.requestBody',
-        };
-    }
-    return undefined;
-}

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

@@ -1,66 +0,0 @@
-/**
- * The `route` oracle. Split out of predicate-eval.ts, which was at the file-size backstop.
- *
- * Route is the one predicate with TWO sources of truth — a navigation inside the window and where the
- * app is right now — and keeping that reconciliation in one place is what makes it readable.
- */
-import { PredicateKind, type ReticleEvent } from '@reticlehq/core';
-import { type EvalResult, type Predicate } from './predicate-eval.js';
-/**
- * Which fact answered a `route` predicate: a navigation inside the window, or where the app is now.
- *
- * Reported on every route result because the two are different claims. "It changed to /login" proves
- * a redirect; "it was already /login" does not, and an agent asserting a post-login redirect has to
- * be able to tell them apart. Silently conflating them would trade one wrong verdict for another.
- */
-export declare const RouteDecidedBy: {
-    readonly CHANGE: "route-change";
-    readonly CURRENT: "current-route";
-};
-/**
- * The path the router is actually on.
- *
- * Under a hash router the document pathname is `/` on every page and the whole route lives in the
- * fragment — which is why `contains` below matches the full route. `pathname` was left comparing the
- * document path, so `{ pathname: '/posts/12/show' }` could never pass on a HashRouter app, the
- * standard router for a packaged Electron/Tauri renderer. That is a guaranteed false red: Reticle
- * telling a user their working app is broken.
- *
- * The fragment WINS rather than being accepted alongside the document path. Honouring both would
- * make `{ pathname: '/' }` trivially true on every hash-routed page — a green that says nothing
- * about where the app is, which is the failure this predicate exists to prevent.
- */
-export declare function routePathOf(pathname: string, hash: string): string;
-/**
- * The resolved parts of a route, from a `ROUTE_CHANGE` event or a session URL.
- *
- * `routePath` is where the ROUTER is (the fragment path under a hash router). `docPath` + `hash`
- * is the NAVIGABLE value a `reticle_navigate` can be pointed at. Call sites pick; collapsing
- * them into one string is how a hash-router miss lands as "every page is `/`".
- */
-export interface RouteParts {
-    routePath: string;
-    docPath: string;
-    hash: string;
-    search: string;
-    full: string;
-}
-/** A `ROUTE_CHANGE` event, or its `data` — one reading, so the sixth copy cannot drift. */
-export declare function routeOfEvent(eventOrData: ReticleEvent | Record<string, unknown>): RouteParts | undefined;
-/** Same shape from a session URL (the fallback when the tab hard-loaded and emitted no route event). */
-export declare function routeOfUrl(url: string): RouteParts | undefined;
-export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
-    kind: typeof PredicateKind.ROUTE;
-}>, 
-/**
- * Where the app is RIGHT NOW, if the caller can say.
- *
- * Without it a route predicate could only ever be answered by a navigation inside the window, so
- * "did the session survive a reload?" — which by definition produces no route change — and "we
- * landed on /login" after a completed navigate were both a guaranteed false red, contradicted by
- * `reticle_snapshot({ mode: 'status' }).route` one call later. Optional so a caller with no session
- * (a replayed window) keeps the old answer instead of inventing a route.
- */
-currentUrl?: string, 
-/** Event-time floor for the window, so a request already in flight before it is not counted. */
-since?: number): EvalResult;