@reticlehq/server 2.12.0 → 2.13.0

package/dist/events/predicate-precheck.js

@@ -0,0 +1,41 @@
+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-route.d.ts

@@ -17,6 +17,20 @@ 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;
 export declare function evalRoute(events: ReticleEvent[], p: Extract<Predicate, {
     kind: typeof PredicateKind.ROUTE;
 }>, 

package/dist/events/predicate-route.js

@@ -17,6 +17,26 @@ export const RouteDecidedBy = {
     CHANGE: 'route-change',
     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 function routePathOf(pathname, hash) {
+    if (!hash.startsWith('#/'))
+        return pathname;
+    const withoutHash = hash.slice(1);
+    const query = withoutHash.indexOf('?');
+    return -1 === query ? withoutHash : withoutHash.slice(0, query);
+}
 /**
  * The session's live URL, split the way a route-change event already carries it.
  *
@@ -30,6 +50,7 @@ function readCurrentRoute(url) {
     const hash = parsed?.hash ?? '';
     return {
         pathname,
+        routePath: routePathOf(pathname, hash),
         full: `${pathname}${search}${hash}`,
         decidedBy: RouteDecidedBy.CURRENT,
         data: { pathname, search, hash, url, decidedBy: RouteDecidedBy.CURRENT },
@@ -55,12 +76,17 @@ currentUrl) {
     const routes = events.filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
     const reading = last !== undefined
-        ? {
-            pathname: str(last.data['pathname']) ?? str(last.data['to']) ?? '',
-            full: `${str(last.data['pathname']) ?? str(last.data['to']) ?? ''}${str(last.data['search']) ?? ''}${str(last.data['hash']) ?? ''}`,
-            decidedBy: RouteDecidedBy.CHANGE,
-            data: { ...last.data, decidedBy: RouteDecidedBy.CHANGE },
-        }
+        ? (() => {
+            const changedPath = str(last.data['pathname']) ?? str(last.data['to']) ?? '';
+            const changedHash = str(last.data['hash']) ?? '';
+            return {
+                pathname: changedPath,
+                routePath: routePathOf(changedPath, changedHash),
+                full: `${changedPath}${str(last.data['search']) ?? ''}${changedHash}`,
+                decidedBy: RouteDecidedBy.CHANGE,
+                data: { ...last.data, decidedBy: RouteDecidedBy.CHANGE },
+            };
+        })()
         : currentUrl === undefined || 0 === currentUrl.length
             ? undefined
             : readCurrentRoute(currentUrl);
@@ -73,11 +99,13 @@ currentUrl) {
             assertion: 'route.changed',
         };
     }
-    const pathname = reading.pathname;
+    // The ROUTER's path, not the document's — see routePathOf.
+    const pathname = reading.routePath;
     if (p.pathname !== undefined && pathname !== p.pathname) {
         return {
             pass: false,
-            failureReason: `${describeRouteSource(reading)} is '${pathname}', expected '${p.pathname}'`,
+            // No ` is` after the clause: it read "route changed to is '/'".
+            failureReason: `${describeRouteSource(reading)} '${pathname}', expected '${p.pathname}'`,
             observed: `${describeRouteSource(reading)} '${pathname}'`,
             expected: `route '${p.pathname}'`,
             assertion: 'route.pathname',

package/dist/events/predicate.d.ts

@@ -45,6 +45,11 @@ export interface PredicateSession {
      * this hook (e.g. tests that never disconnect) simply leaves in-flight predicates until timeout.
      */
     onDisconnect?(listener: () => void): () => void;
+    /**
+     * True when the tab is hidden or stale enough that the browser is throttling it.
+     * Optional: a fake that never throttles simply omits it.
+     */
+    throttled?(): boolean;
 }
 export declare function evaluatePredicate(session: PredicateSession, predicate: Predicate, since?: number, diagnose?: boolean): Promise<EvalResult>;
 /**

package/dist/events/predicate.js

@@ -1,8 +1,9 @@
-import { ElementState, PredicateKind, ReticleCommand, isSameDocument, } from '@reticlehq/core';
+import { ElementState, PredicateKind, ReticleCommand, THROTTLED_STARVED_NOTE, isSameDocument, } from '@reticlehq/core';
 import { log } from '../log.js';
 import { bindSpanContext } from '../trace.js';
 import { selectPath, capDepth } from '../session/state-select.js';
 import { describeTestidMiss } from './testid-near-miss.js';
+import { describeSplitTextMiss } from './split-text-miss.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { isAmbient, ambientKeyOf } from '../journal/ambient.js';
 import { evalRoute } from './predicate-route.js';
@@ -154,7 +155,12 @@ async function evalElement(session, query, state, absent, diagnose) {
     // testid-near-miss.ts.
     const present = match.hint?.presentTestids ?? [];
     const alsoHere = query.testid === undefined ? undefined : describeTestidMiss(query.testid, present);
-    const suffix = alsoHere === undefined || '' === alsoHere ? '' : ` — ${alsoHere}`;
+    // A text miss where the string is on the page but split across children reads exactly like an
+    // element that never rendered. Naming the container is the difference between a retry and a bug
+    // report against working code. See split-text-miss.ts.
+    const splitText = describeSplitTextMiss(match.hint?.splitText);
+    const clause = splitText ?? (alsoHere === undefined || '' === alsoHere ? undefined : alsoHere);
+    const suffix = clause === undefined ? '' : ` — ${clause}`;
     return {
         pass: false,
         failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}${suffix}`,
@@ -419,7 +425,33 @@ const SUPERSEDED_ASSERTION = 'window.evidence-superseded';
 function predicateSince(predicate) {
     return 'since' in predicate && 'number' === typeof predicate.since ? predicate.since : 0;
 }
-export async function evaluatePredicate(session, predicate, since = 0, 
+/**
+ * A miss on a throttled tab is not a missing render. The browser has starved the tab, so a timeout
+ * there may mean it never ran — which must not look like "the text is absent".
+ *
+ * Sets `inconclusive` only. The PROSE is already handled one layer up by
+ * `annotateStarvedFailure` (session-health.ts), which suffixes the same fact onto the
+ * failureReason so the concrete diagnosis still leads; writing it here as well would put the
+ * sentence in every throttled failure twice. What was missing was never the sentence — it was the
+ * FIELD an agent gates on, so a starved wait graded `assertion-failed` and sent somebody to fix
+ * working code.
+ *
+ * Idempotent, and a more specific `inconclusive` (unreadable locator, superseded window) is never
+ * overwritten.
+ */
+function annotateThrottledMiss(session, result) {
+    if (result.pass)
+        return result;
+    if (true !== session.throttled?.())
+        return result;
+    if (result.inconclusive !== undefined)
+        return result;
+    return { ...result, inconclusive: THROTTLED_STARVED_NOTE };
+}
+export async function evaluatePredicate(session, predicate, since = 0, diagnose = true) {
+    return annotateThrottledMiss(session, await evaluatePredicateRaw(session, predicate, since, diagnose));
+}
+async function evaluatePredicateRaw(session, predicate, since = 0, 
 // Compute the (extra-round-trip) near-miss diagnostics on element failures. Default true so a
 // one-shot assert is fully diagnostic; the wait loop passes false on its interim polls (which read
 // only `pass`) and true on the final timeout eval, so a flood no longer pays for a diagnostic nobody
@@ -760,11 +792,11 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
                 // `{ pass, evidence, failureReason }` construction DISCARDED them on every timed-out wait and
                 // assert. So the highest-value localization signal was computed and then thrown away exactly
                 // on the failure path where it matters, no matter what the schema declared.
-                finish({
+                finish(annotateThrottledMiss(session, {
                     ...r,
                     pass: false,
                     failureReason: r.failureReason ?? 'timed out waiting for predicate',
-                });
+                }));
             })
                 .catch((error) => {
                 finish(failed(error));

package/dist/events/split-text-miss.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Turning "no element matched {text: …}" into something an agent can act on, when the string IS here.
+ *
+ * `by: text` matches an element's own text nodes. A label rendered across several children —
+ * `v-html`, one `<span>` per word, a highlighted substring — is on the page and matches nothing, and
+ * the verdict is byte-identical to the one for an element that never rendered.
+ *
+ * That equivalence is the expensive part. Reported from the field: `act_and_wait` returned
+ * `effect.appeared` containing `"Move to Reticle Repro Folder"`, the `until` predicate in the SAME
+ * call searched for that string and failed, and the drive ended in a bug report against an app that
+ * had rendered correctly. `appeared` concatenates an added subtree while `text` reads direct text
+ * only, so the channel an agent is most likely to copy from produces the one locator this query
+ * cannot resolve.
+ *
+ * Naming the container ends it in one step: `ref` is a locator, and `self: true` returns the scope
+ * element itself, so the recovery is a query the agent can paste rather than another guess.
+ */
+/** The container descriptor the browser attaches to a missed text query. */
+export interface SplitTextOwner {
+    ref?: string;
+    role?: string;
+    name?: string;
+}
+/**
+ * The "…but it IS here, split across children" clause, or undefined when there is nothing to say.
+ *
+ * Undefined — not a vaguer sentence — when the browser found no container: an ordinary miss keeps the
+ * short message it already had. A clause that fires on every failure stops carrying information.
+ */
+export declare function describeSplitTextMiss(owner: SplitTextOwner | undefined): string | undefined;

package/dist/events/split-text-miss.js

@@ -0,0 +1,44 @@
+/**
+ * Turning "no element matched {text: …}" into something an agent can act on, when the string IS here.
+ *
+ * `by: text` matches an element's own text nodes. A label rendered across several children —
+ * `v-html`, one `<span>` per word, a highlighted substring — is on the page and matches nothing, and
+ * the verdict is byte-identical to the one for an element that never rendered.
+ *
+ * That equivalence is the expensive part. Reported from the field: `act_and_wait` returned
+ * `effect.appeared` containing `"Move to Reticle Repro Folder"`, the `until` predicate in the SAME
+ * call searched for that string and failed, and the drive ended in a bug report against an app that
+ * had rendered correctly. `appeared` concatenates an added subtree while `text` reads direct text
+ * only, so the channel an agent is most likely to copy from produces the one locator this query
+ * cannot resolve.
+ *
+ * Naming the container ends it in one step: `ref` is a locator, and `self: true` returns the scope
+ * element itself, so the recovery is a query the agent can paste rather than another guess.
+ */
+/** Enough of the label to recognise it; the message is read in a tool result, not a log. */
+const MAX_TEXT = 60;
+/** What the container is, in the fewest words that still identify it on the page. */
+function nameOf(owner) {
+    const name = owner.name !== undefined && owner.name.length > 0 ? owner.name : undefined;
+    const role = owner.role !== undefined && owner.role.length > 0 ? owner.role : 'element';
+    return name === undefined ? role : `${role} '${truncate(name)}'`;
+}
+function truncate(value) {
+    return value.length > MAX_TEXT ? `${value.slice(0, MAX_TEXT)}…` : value;
+}
+/**
+ * The "…but it IS here, split across children" clause, or undefined when there is nothing to say.
+ *
+ * Undefined — not a vaguer sentence — when the browser found no container: an ordinary miss keeps the
+ * short message it already had. A clause that fires on every failure stops carrying information.
+ */
+export function describeSplitTextMiss(owner) {
+    if (owner === undefined)
+        return undefined;
+    const where = nameOf(owner);
+    const scope = owner.ref !== undefined && owner.ref.length > 0 ? owner.ref : undefined;
+    const recovery = scope === undefined
+        ? 'scope to that container and match it as a whole'
+        : `retry as { scope: '${scope}', self: true }`;
+    return `that text IS on the page, split across the children of ${where} — no single element's own text carries it, so no text query can match it; ${recovery}`;
+}

package/dist/flows/flake.d.ts

@@ -9,11 +9,11 @@ declare const FlakeRecordSchema: z.ZodObject<{
     runs: z.ZodNumber;
     fails: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    fails: number;
     runs: number;
-}, {
     fails: number;
+}, {
     runs: number;
+    fails: number;
 }>;
 export type FlakeRecord = z.infer<typeof FlakeRecordSchema>;
 /** Per-flow map (flow name → record). */
@@ -24,23 +24,23 @@ export declare const FlakeFileSchema: z.ZodObject<{
         runs: z.ZodNumber;
         fails: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        fails: number;
         runs: number;
-    }, {
         fails: number;
+    }, {
         runs: number;
+        fails: number;
     }>>;
 }, "strip", z.ZodTypeAny, {
     version: 1;
     flows: Record<string, {
-        fails: number;
         runs: number;
+        fails: number;
     }>;
 }, {
     version: 1;
     flows: Record<string, {
-        fails: number;
         runs: number;
+        fails: number;
     }>;
 }>;
 export declare function emptyRecord(): FlakeRecord;

package/dist/flows/flow-memory-consult.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What the team already knows about the flow being verified.
+ *
+ * ## Why a replay should ask at all
+ *
+ * Shared memory is written on every verification and, measured across this project's whole corpus,
+ * read essentially never: every subject on the dashboard showed `fetches: 0` and `readers: []`. Not
+ * because the data is useless — because consulting it is a SEPARATE act an agent has to remember to
+ * perform. Knowledge that must be deliberately fetched is a wiki, and wikis are not read.
+ *
+ * So verification asks on the agent's behalf. Replaying `checkout` returns what the project knows
+ * about checkout beside the verdict, which is the difference between memory the platform stores and
+ * memory the platform USES — and it is the only way the read counts on the coverage map ever become
+ * a real signal rather than a number nobody moves.
+ *
+ * ## Why this file is pure
+ *
+ * The fetch is the caller's. What a replay is ENTITLED to ask for — which subject, how much of it —
+ * is a rule worth testing without a network, and the rule is where the mistakes live.
+ */
+import type { FlowFile } from '@reticlehq/core';
+/**
+ * How many records travel back with a verdict.
+ *
+ * Small on purpose. This rides on every replay, and a verdict that arrives with fifty statements
+ * attached is one whose actual result is now below the fold. The subject page is one call away for
+ * an agent that wants the rest.
+ */
+export declare const MEMORY_CONSULT_LIMIT = 5;
+/**
+ * The subject a replay should ask about.
+ *
+ * The FLOW NAME, because a flow is a feature and that is the axis the store shards on — replaying
+ * `checkout` should surface what the team knows about checkout, not about the route it happens to
+ * start on. A flow whose name says nothing gets nothing: asking for `unsorted` would return the
+ * project's junk drawer on every verdict, which is worse than silence because it looks like an
+ * answer.
+ */
+export declare function consultSubjectFor(flow: FlowFile): string | undefined;
+/** One thing the project knows, as it travels back with a verdict. */
+export interface ConsultedMemory {
+    statement: string;
+    status: string;
+}
+/**
+ * Trim what came back to what is worth carrying.
+ *
+ * PROVED records first: a statement something has actually verified is stronger evidence about the
+ * feature than one somebody proposed and never checked. Beyond that the order is the server's, and
+ * anything without a statement is dropped rather than rendered as an empty line.
+ */
+export declare function selectConsulted(entries: readonly {
+    statement?: unknown;
+    status?: unknown;
+}[], limit?: number): ConsultedMemory[];

package/dist/flows/flow-memory-consult.js

@@ -0,0 +1,38 @@
+/**
+ * How many records travel back with a verdict.
+ *
+ * Small on purpose. This rides on every replay, and a verdict that arrives with fifty statements
+ * attached is one whose actual result is now below the fold. The subject page is one call away for
+ * an agent that wants the rest.
+ */
+export const MEMORY_CONSULT_LIMIT = 5;
+/**
+ * The subject a replay should ask about.
+ *
+ * The FLOW NAME, because a flow is a feature and that is the axis the store shards on — replaying
+ * `checkout` should surface what the team knows about checkout, not about the route it happens to
+ * start on. A flow whose name says nothing gets nothing: asking for `unsorted` would return the
+ * project's junk drawer on every verdict, which is worse than silence because it looks like an
+ * answer.
+ */
+export function consultSubjectFor(flow) {
+    const name = flow.name;
+    if ('string' !== typeof name || 0 === name.trim().length)
+        return undefined;
+    return name.trim();
+}
+/**
+ * Trim what came back to what is worth carrying.
+ *
+ * PROVED records first: a statement something has actually verified is stronger evidence about the
+ * feature than one somebody proposed and never checked. Beyond that the order is the server's, and
+ * anything without a statement is dropped rather than rendered as an empty line.
+ */
+export function selectConsulted(entries, limit = MEMORY_CONSULT_LIMIT) {
+    const usable = entries.flatMap((e) => 'string' === typeof e.statement && e.statement.trim().length > 0
+        ? [{ statement: e.statement, status: 'string' === typeof e.status ? e.status : 'unknown' }]
+        : []);
+    const proved = usable.filter((e) => 'proved' === e.status);
+    const rest = usable.filter((e) => 'proved' !== e.status);
+    return [...proved, ...rest].slice(0, limit);
+}

package/dist/flows/flow-replay-run.d.ts

@@ -1,4 +1,7 @@
-import { FlowErrorCode, type FlowFile, type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
+import { FlowErrorCode, type CommandResult, type FlowFile, type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
+import type { ArrivalClock } from '../tools/navigate-arrival.js';
+import type { SessionManager } from '../session/session-manager.js';
+import type { Session } from '../session/session.js';
 import type { ToolDeps } from '../tools/tools.js';
 export declare function latestRecordedFlow(events: ReticleEvent[]): {
     name: string;
@@ -6,18 +9,25 @@ export declare function latestRecordedFlow(events: ReticleEvent[]): {
 } | undefined;
 /** Map a structured FlowErrorCode to a legible one-line message for the agent. */
 export declare function flowErrorMessage(code: FlowErrorCode): string;
+/** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
+interface StartPathSession {
+    url?: string;
+    eventsSince(cursor: number): ReticleEvent[];
+}
 /**
  * When a flow records the page its journey started on (`startPath`) and the tab is currently on a
  * different route, step 1 drifts for a reason that has nothing to do with the app regressing — the
  * anchor simply isn't on this page yet. Detect that so the decision says "navigate there first"
  * instead of a mystifying "a step no longer matches". Returns undefined when the routes agree or the
- * current route is unobservable (no route event) — never a false alarm. Replay itself does NOT
- * navigate: a full-page load mid-replay tears down the session socket; the agent navigates between
- * tool calls (reticle_navigate) where the session is re-resolved fresh.
+ * current route is unobservable — never a false alarm. Replay normally never gets here on a
+ * wrong page (arriveAtStartPath navigates before step 1); this is the fallback for when that
+ * navigation was refused or the SDK never reconnected in the window.
  */
-export declare function startPathMismatchHint(flow: FlowFile, session: {
-    eventsSince(cursor: number): ReticleEvent[];
-}): string | undefined;
+export declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
+export declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
+    id: string;
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock): Promise<Session | undefined>;
 /**
  * Replay one named flow end to end: load → re-resolve+run each step → assert the success oracle →
  * status + decision. Shared by reticle_flow_replay (single flow) and reticle_flow_verify (whole suite) so
@@ -30,3 +40,4 @@ export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unk
  * documented to work headless), so a missing/unknown session degrades to the global/legacy store.
  */
 export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): string | undefined;
+export {};