@reticlehq/server 3.7.0 → 3.8.1

package/dist/surface/tools/act/act-danger.js

@@ -1,4 +1,4 @@
-import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, outwardActionOf, outwardRefusal, } from '@reticlehq/core';
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, OutwardAction, isDangerousActionText, isDangerousNavigation, isInertHref, isPaymentProviderUrl, outwardActionOf, outwardRefusal, withoutFilenameTokens, } from '@reticlehq/core';
 import { currentDrivenBy, harnessOutwardAllowed } from '../../../hooks/driven-by.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
@@ -14,10 +14,12 @@ import { asRecord, asString } from '@reticlehq/core';
  */
 function descriptorText(value) {
     const descriptor = asRecord(value);
+    // Filename tokens are stripped from the name, the text and the value only: an href or a
+    // formAction is a target, not words on the control, and its destination must be read whole.
     return [
-        asString(descriptor['name']) ?? '',
-        asString(descriptor['text']) ?? '',
-        asString(descriptor['value']) ?? '',
+        withoutFilenameTokens(asString(descriptor['name']) ?? ''),
+        withoutFilenameTokens(asString(descriptor['text']) ?? ''),
+        withoutFilenameTokens(asString(descriptor['value']) ?? ''),
         asString(descriptor['href']) ?? '',
         asString(descriptor['formAction']) ?? '',
         asString(descriptor['formText']) ?? '',
@@ -28,27 +30,47 @@ function descriptorRole(value) {
     return role !== undefined && role.length > 0 ? role : undefined;
 }
 function isDestructiveDescriptor(value) {
+    // A real link is a navigation, judged by where it goes: the same rule as the SDK path.
+    const href = asString(asRecord(value)['href']);
+    if (href !== undefined && !isInertHref(href)) {
+        return isDangerousNavigation(href);
+    }
     return isDangerousActionText(descriptorText(value), descriptorRole(value));
 }
 /** A Harness call presses an outward control only when its journey asked (`harnessOutwardAllowed`). */
 function assertOutwardAllowed(...descriptors) {
     const allowed = harnessOutwardAllowed();
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return;
+    }
     for (const descriptor of descriptors) {
         const kind = outwardActionOf(descriptorText(descriptor), descriptorRole(descriptor));
-        if (kind !== undefined && !allowed.includes(kind))
+        if (kind !== undefined && !allowed.includes(kind)) {
             throw new Error(outwardRefusal(kind));
+        }
+    }
+}
+/** A Harness call goes to a payment provider's origin only when its journey asked to pay. */
+export function assertNotPaymentNavigation(url) {
+    const allowed = harnessOutwardAllowed();
+    if (allowed === undefined || allowed.includes(OutwardAction.PAY)) {
+        return;
+    }
+    if (isPaymentProviderUrl(url)) {
+        throw new Error(outwardRefusal(OutwardAction.PAY));
     }
 }
 export function assertNotDestructive(action, innerArgs, inspected) {
-    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
+    if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK) {
         return;
+    }
     assertOutwardAllowed(inspected);
-    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG]) {
         return;
-    if (!isDestructiveDescriptor(inspected))
+    }
+    if (!isDestructiveDescriptor(inspected)) {
         return;
+    }
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
 /**
@@ -58,10 +80,12 @@ export function assertNotDestructive(action, innerArgs, inspected) {
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
     assertOutwardAllowed(from, to);
-    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG]) {
         return;
-    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
+    }
+    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to)) {
         return;
+    }
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
 /**
@@ -78,8 +102,9 @@ export const NATIVE_INPUT_UNSUPPORTED = `reticle_act_and_wait cannot drive nativ
     'consequence with reticle_assert / reticle_observe using the `since` cursor it returns.';
 /** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
 export function assertNativeInputSupported(innerArgs) {
-    if (true === innerArgs[NATIVE_INPUT_ARG])
+    if (true === innerArgs[NATIVE_INPUT_ARG]) {
         throw new Error(NATIVE_INPUT_UNSUPPORTED);
+    }
 }
 /**
  * The agent's own declaration counts as the confirmation, for that one control.
@@ -92,10 +117,12 @@ export function assertNativeInputSupported(innerArgs) {
  * guard decides alone.
  */
 export function confirmedByDeclaration(innerArgs, target, declared) {
-    if (!declared || true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+    if (!declared || true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG]) {
         return innerArgs;
-    if (currentDrivenBy() !== undefined)
+    }
+    if (currentDrivenBy() !== undefined) {
         return innerArgs;
+    }
     const named = asRecord(target);
     // The words must themselves be the dangerous ones: naming "Continue" on a button whose form posts
     // to /delete-account consents to nothing, and the guard still reads the whole control.

package/dist/surface/tools/act/act-observation.d.ts

@@ -47,6 +47,17 @@ export declare const DISABLED_TARGET_NOTE: string;
  * consequence then says nothing about the app, so the verdict is undecided rather than "no".
  */
 export declare function disabledTargetNote(pass: boolean, actResult: unknown): string | undefined;
+/**
+ * Why the click behind a verdict is not one a person could have made, or undefined when it is.
+ *
+ * Synthetic dispatch reaches a covered, sizeless or off-screen target all the same, so the declared
+ * consequence can hold. A "yes" on it says nothing about what the app's users can do: the act
+ * result already warned, and the verdict now agrees. Undecided, never a pass and never the app's
+ * failure, whichever way the consequence went.
+ */
+export declare function unreachableTargetNote(actResult: unknown): string | undefined;
+/** Why the acted target leaves the verdict undecided: no person could reach it, or it was disabled. */
+export declare function actTargetNote(pass: boolean, actResult: unknown): string | undefined;
 /**
  * The requests of a failed check's window, as its record carries them: method, url, status and the
  * start of the response body (redacted in the page before it was ever sent). Dev tooling is left out.

package/dist/surface/tools/act/act-observation.js

@@ -48,6 +48,39 @@ export function disabledTargetNote(pass, actResult) {
         return undefined;
     return false === asRecord(actResult)['enabled'] ? DISABLED_TARGET_NOTE : undefined;
 }
+/** The words a verdict carries for a click no person could have made. */
+const UNREACHABLE = {
+    covered: (by) => `a person could not have clicked the target: it is covered by ${by}. Dismiss or move what ` +
+        'covers it, then act again',
+    NO_SIZE: 'a person could not have clicked the target: it has no size (0×0). Give it a size, or act on ' +
+        'the control a person actually clicks',
+    OFF_VIEWPORT: 'a person could not have clicked the target: it is outside the viewport even after scrolling ' +
+        'it into view. Bring it on screen, then act again',
+};
+/**
+ * Why the click behind a verdict is not one a person could have made, or undefined when it is.
+ *
+ * Synthetic dispatch reaches a covered, sizeless or off-screen target all the same, so the declared
+ * consequence can hold. A "yes" on it says nothing about what the app's users can do: the act
+ * result already warned, and the verdict now agrees. Undecided, never a pass and never the app's
+ * failure, whichever way the consequence went.
+ */
+export function unreachableTargetNote(actResult) {
+    const effect = asRecord(asRecord(actResult)['effect']);
+    if (true === effect['occluded']) {
+        const by = asString(effect['occluderName']) ?? asString(effect['occludedBy']);
+        return UNREACHABLE.covered(by ?? 'another element');
+    }
+    if (true === effect['noSize'])
+        return UNREACHABLE.NO_SIZE;
+    if (true === effect['offViewport'])
+        return UNREACHABLE.OFF_VIEWPORT;
+    return undefined;
+}
+/** Why the acted target leaves the verdict undecided: no person could reach it, or it was disabled. */
+export function actTargetNote(pass, actResult) {
+    return unreachableTargetNote(actResult) ?? disabledTargetNote(pass, actResult);
+}
 /** Calls quoted on a failed check, and how much of each response body. */
 const MAX_NET_CALLS = 5;
 const MAX_BODY_CHARS = 300;

package/dist/surface/tools/act/act-preflight.js

@@ -12,6 +12,7 @@
  */
 import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
 import { SESSION_REF, isGlobalPressCall, unissuedRefRefusal } from '@reticlehq/core';
+import { isDocumentGoneError } from '../../../portal/session/facts/session-replaced.js';
 import { SessionReplacedError } from '../../../portal/session/page-commands/pending-commands.js';
 import { assertNativeInputSupported } from './act-danger.js';
 import { unevaluablePredicateReason, vacuousPredicateReason, } from '@reticlehq/engine/question/predicate/predicate-precheck.js';
@@ -118,8 +119,14 @@ export function assertSequenceSteps(steps) {
          * the very thing it just wrote. Same false green as an unreadable key, through a key this tool
          * does read.
          */
-        if (step['expect'] !== undefined && !PredicateSchema.safeParse(step['expect']).success) {
-            throw new Error(`step ${String(i)} carries an \`expect\` this tool cannot parse. ` +
+        const parsed = step['expect'] === undefined ? undefined : PredicateSchema.safeParse(step['expect']);
+        if (parsed !== undefined && !parsed.success) {
+            // The schema's own words, such as the keys it saw when it could not tell the kind.
+            const said = parsed.error.issues
+                .filter((issue) => 'custom' === issue.code)
+                .map((issue) => ` ${issue.message}.`)
+                .join('');
+            throw new Error(`step ${String(i)} carries an \`expect\` this tool cannot parse.${said} ` +
                 'A consequence is a predicate object with a `kind` — e.g. { kind: "signal", name: ' +
                 '"order:placed" }, { kind: "element", by: "testid", value: "receipt" }, or ' +
                 '{ kind: "settled" } — the same shape reticle_act_and_wait takes as `until`. ' +
@@ -184,7 +191,7 @@ export async function dispatchAct(send) {
         return await send();
     }
     catch (error) {
-        if (error instanceof SessionReplacedError)
+        if (error instanceof SessionReplacedError || isDocumentGoneError(error))
             return null;
         throw error;
     }

package/dist/surface/tools/act/act-sequence-retry.js

@@ -50,7 +50,8 @@ export function describeStepResult(step, result) {
         settled: result['settled'] ?? null,
         settleReason: result['settleReason'] ?? null,
     };
-    for (const key of ['testid', 'component', 'role', 'name', 'source', 'warning']) {
+    // `reticleUi`: the step hit Reticle's own HUD, so the recorder leaves it out of the app's flow.
+    for (const key of ['testid', 'component', 'role', 'name', 'source', 'warning', 'reticleUi']) {
         if (result[key] !== undefined)
             out[key] = result[key];
     }

package/dist/surface/tools/act/act-target.js

@@ -8,7 +8,7 @@
  * line count. This resolves a TARGET and dispatches only QUERY, so that guard is untouched.
  */
 import { ReticleCommand, SESSION_REF, isGlobalPressCall, unissuedRefRefusal, } from '@reticlehq/core';
-import { normalizeQueryArgs } from '../read/query-shape.js';
+import { emptyQueryRefusal, normalizeQueryArgs } from '../read/query-shape.js';
 import { resolveTargetRef } from './resolve-target.js';
 import { asRecord, asString, asNumber } from '@reticlehq/core';
 import { appearanceDecision } from '@reticlehq/engine/window/appearance-budget.js';
@@ -52,17 +52,29 @@ appearanceMs) {
     if (ref !== undefined && ref.length > 0) {
         // Refused here, at the boundary, and never re-read as a `target`: guessing what an arbitrary
         // string meant is the silent re-resolution the stale-ref refusal exists to prevent.
-        if (!SESSION_REF.test(ref))
+        if (!SESSION_REF.test(ref)) {
             return { kind: 'error', message: unissuedRefRefusal(ref) };
+        }
         return { kind: 'ref', ref };
     }
     const target = args['target'];
     if (target === undefined) {
-        if (isGlobalPressCall(args))
+        if (isGlobalPressCall(args)) {
             return { kind: 'global', ref: '' };
+        }
         return { kind: 'error', message: MISSING_ACT_TARGET };
     }
+    // A ref from a look, given as the target. It is the agent's own explicit ref, not a guess.
+    if ('string' === typeof target && SESSION_REF.test(target)) {
+        return { kind: 'ref', ref: target };
+    }
     const q = normalizeQueryArgs(asRecord(target));
+    // A target that names nothing (a CSS string, an empty object) is not sent to the page: there it
+    // read as "matched no element", which says the element is gone when nothing was searched.
+    const empty = emptyQueryRefusal(q);
+    if (empty !== undefined) {
+        return { kind: 'error', message: empty.message };
+    }
     /*
      * Look again while the step's own budget lasts, instead of once.
      *
@@ -87,8 +99,9 @@ appearanceMs) {
             name: q['name'],
             scope: q['scope'],
         });
-        if (!out.ok)
+        if (!out.ok) {
             return { kind: 'error', message: out.error ?? 'target query failed' };
+        }
         const elements = asRecord(out.result)['elements'];
         const found = Array.isArray(elements) ? elements : [];
         const decision = appearanceDecision({
@@ -98,8 +111,9 @@ appearanceMs) {
         });
         // One match, or an ambiguity: both are answered by the existing resolver, which already ranks
         // candidates inside its refusal so the next turn needs no snapshot.
-        if ('wait' !== decision.do)
+        if ('wait' !== decision.do) {
             return resolveTargetRef(found, asRecord(out.result)['hint']);
+        }
         await new Promise((resolve) => setTimeout(resolve, decision.waitMs));
     }
 }

package/dist/surface/tools/act/durable.js

@@ -20,7 +20,7 @@ export const durableArg = z
     .describe('After a yes, reload and require the element/text/state part of `until` to hold again.');
 // Loose and undescribed on purpose: the output surface is re-sent every turn. `because` carries
 // the answer; this is the detail — { held?, observed?, skipped? }.
-export const durableOutput = z.record(z.unknown()).optional();
+export const durableOutput = z.record(z.string(), z.unknown()).optional();
 const RE_READABLE = new Set([
     PredicateKind.ELEMENT,
     PredicateKind.TEXT,

package/dist/surface/tools/act/navigation/navigate-arrival.d.ts

@@ -67,17 +67,19 @@ export interface ArrivalScope {
      * document identity proves the replacement; `undefined` on both sides proves nothing and waits.
      */
     navigatedFromDocumentId?: string;
-    /** Sessions already on the target before dispatch cannot prove this navigation arrived. */
+    /**
+     * Sessions connected before dispatch cannot prove this navigation arrived. One already on the
+     * target was there before it. One elsewhere, such as a lease on the same app, is another tab: it
+     * can reach the target during the wait, but it is not the new document of the navigated tab.
+     */
     priorIds: ReadonlySet<string>;
 }
 /**
- * The sessions already on `target` — the set `ArrivalScope.priorIds` is built from, sampled before
- * the navigation is dispatched.
- *
- * Shares `samePage` with the arrival scan on purpose: "was it already there" and "is it there now"
- * are the same question asked at two moments, and two spellings of it would eventually disagree.
+ * The sessions connected when the navigation is dispatched: the set `ArrivalScope.priorIds` is
+ * built from. The navigated tab's new document is not one of them, so none of the others can be
+ * the arrival.
  */
-export declare function idsAtTarget(sessions: SessionManager, target: string): ReadonlySet<string>;
+export declare function idsOpenAtDispatch(sessions: SessionManager): ReadonlySet<string>;
 export interface ArrivalClock {
     now: () => number;
     sleep: (ms: number) => Promise<void>;

package/dist/surface/tools/act/navigation/navigate-arrival.js

@@ -17,7 +17,7 @@
  * would make the daemon wait. `assert` / `wait_for` / `act_and_wait` all spend the caller's
  * `timeout_ms` (resolve-within.ts); this is the same budget applied to the same wait.
  */
-import { awaitDocumentSuccessor } from '../../../../portal/session/session-successor.js';
+import { awaitDocumentSuccessor, claimedSessionOf, } from '../../../../portal/session/session-successor.js';
 /**
  * The default when the caller gives no `timeout_ms`: long enough for a dev server to serve a page
  * and the SDK to dial back; short enough to not hang. A caller who knows the app is slower says so.
@@ -71,19 +71,12 @@ export function absoluteTarget(target, base) {
     }
 }
 /**
- * The sessions already on `target` — the set `ArrivalScope.priorIds` is built from, sampled before
- * the navigation is dispatched.
- *
- * Shares `samePage` with the arrival scan on purpose: "was it already there" and "is it there now"
- * are the same question asked at two moments, and two spellings of it would eventually disagree.
+ * The sessions connected when the navigation is dispatched: the set `ArrivalScope.priorIds` is
+ * built from. The navigated tab's new document is not one of them, so none of the others can be
+ * the arrival.
  */
-export function idsAtTarget(sessions, target) {
-    const ids = new Set();
-    for (const s of sessions.all()) {
-        if (samePage(s.url, target))
-            ids.add(s.id);
-    }
-    return ids;
+export function idsOpenAtDispatch(sessions) {
+    return new Set(sessions.all().map((s) => s.id));
 }
 /**
  * Whether `current` is a different document from the one the navigation was dispatched on.
@@ -124,10 +117,14 @@ function findArrival(sessions, target, scope, currentSession) {
             // the document has a chance to reach the requested target.
             continue;
         }
-        // A different session that was already at the target cannot prove this
+        // A different session that was connected at dispatch cannot prove this
         // navigation arrived.
         if (scope.priorIds.has(s.id))
             continue;
+        // A session that claims another identity (a lease) is another tab, not the new document of
+        // the navigated one, even when it reconnects at the target during the wait.
+        if (claimedSessionOf(s.url) !== claimedSessionOf(scope.navigatedFrom))
+            continue;
         // While the replaced document is still connected, a DIFFERENT session at the target is an
         // unrelated arrival (a second tab, a neighbour app): the replacement this navigation waits
         // for has not reported yet, and letting the newcomer stand in would confirm too early and

package/dist/surface/tools/act/unsettled-find.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A zero-match `find` read while the last act is still landing says so (#1259).
+ *
+ * `reticle_act` returns before an async render: a click that opens a modal after a fetch, then an
+ * immediate `find` for the modal's combobox, answers 0. A find is a point-in-time read, and an agent
+ * reads 0 as "not there" and goes down the wrong path. The read itself stays instant. What changes
+ * is that a 0 taken while the page is demonstrably still moving carries `unsettled`, naming why and
+ * the call that waits.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+/** A DOM change this recent means the render the act started may not have landed yet. */
+export declare const UNSETTLED_DOM_QUIET_MS = 500;
+export interface UnsettledFind {
+    reason: string;
+    inFlight?: string[];
+    lastDomChangeMsAgo?: number;
+}
+/** The slice of a session this reads: the last act's window and the clock. */
+export interface UnsettledFindSession {
+    lastAct: {
+        cursor(): number | undefined;
+    };
+    eventsSince(cursor: number): readonly ReticleEvent[];
+    elapsed(): number;
+    url: string;
+    background: readonly string[];
+}
+/**
+ * `unsettled` for a zero-match read taken while the last act's window is still moving, else nothing.
+ *
+ * Moving means a request that window started has not come back, or the DOM changed within
+ * `UNSETTLED_DOM_QUIET_MS`. With no act yet there is no window to judge, so nothing is said.
+ */
+export declare function unsettledFind(session: UnsettledFindSession, result: unknown): UnsettledFind | undefined;
+/** The query result, with `unsettled` added when a zero-match read was taken mid-render. */
+export declare function withUnsettledFind(session: UnsettledFindSession, result: unknown): unknown;

package/dist/surface/tools/act/unsettled-find.js

@@ -0,0 +1,71 @@
+/**
+ * A zero-match `find` read while the last act is still landing says so (#1259).
+ *
+ * `reticle_act` returns before an async render: a click that opens a modal after a fetch, then an
+ * immediate `find` for the modal's combobox, answers 0. A find is a point-in-time read, and an agent
+ * reads 0 as "not there" and goes down the wrong path. The read itself stays instant. What changes
+ * is that a 0 taken while the page is demonstrably still moving carries `unsettled`, naming why and
+ * the call that waits.
+ */
+import { EventType } from '@reticlehq/core';
+import { inFlightRequestLabels } from './settle-in-flight.js';
+/** A DOM change this recent means the render the act started may not have landed yet. */
+export const UNSETTLED_DOM_QUIET_MS = 500;
+const DOM_CHANGES = new Set([
+    EventType.DOM_ADDED,
+    EventType.DOM_REMOVED,
+    EventType.DOM_ATTR,
+    EventType.DOM_TEXT,
+]);
+/** What the next call should be, in the words every unsettled answer uses. */
+const WAIT_INSTEAD = 'a 0 here may only mean it has not rendered yet. Wait for it with reticle_assert { action: "wait", predicate: { kind: "element", query: ... } }, or act with reticle_act_and_wait { until } next time';
+/** How many elements a query result matched, or `undefined` when it is not a query result. */
+function matchedCount(result) {
+    if (null === result || 'object' !== typeof result)
+        return undefined;
+    const rec = result;
+    if ('number' === typeof rec['count'])
+        return rec['count'];
+    return Array.isArray(rec['elements']) ? rec['elements'].length : undefined;
+}
+/**
+ * `unsettled` for a zero-match read taken while the last act's window is still moving, else nothing.
+ *
+ * Moving means a request that window started has not come back, or the DOM changed within
+ * `UNSETTLED_DOM_QUIET_MS`. With no act yet there is no window to judge, so nothing is said.
+ */
+export function unsettledFind(session, result) {
+    if (0 !== matchedCount(result))
+        return undefined;
+    // A test double, or any session that cannot say what its last act was, gets the read as before.
+    if (undefined === session.lastAct)
+        return undefined;
+    const cursor = session.lastAct.cursor();
+    if (cursor === undefined)
+        return undefined;
+    const window = session.eventsSince(cursor);
+    const inFlight = inFlightRequestLabels(window, session.url, session.background);
+    let lastDom;
+    for (const e of window)
+        if (DOM_CHANGES.has(e.type))
+            lastDom = Math.max(lastDom ?? e.t, e.t);
+    const msAgo = lastDom === undefined ? undefined : Math.max(0, session.elapsed() - lastDom);
+    const recent = msAgo !== undefined && msAgo < UNSETTLED_DOM_QUIET_MS;
+    if (0 === inFlight.length && !recent)
+        return undefined;
+    const why = 0 < inFlight.length
+        ? `the last act started ${String(inFlight.length)} request(s) that have not come back`
+        : `the page changed ${String(msAgo)} ms ago, after the last act`;
+    return {
+        reason: `this read found nothing while the page was still changing: ${why}, so ${WAIT_INSTEAD}`,
+        ...(0 < inFlight.length ? { inFlight } : {}),
+        ...(msAgo === undefined ? {} : { lastDomChangeMsAgo: msAgo }),
+    };
+}
+/** The query result, with `unsettled` added when a zero-match read was taken mid-render. */
+export function withUnsettledFind(session, result) {
+    const unsettled = unsettledFind(session, result);
+    if (unsettled === undefined || null === result || 'object' !== typeof result)
+        return result;
+    return { ...result, unsettled };
+}