e2e 0.16.0 → 0.18.0

package/dist/agent/replay.js

@@ -11,7 +11,6 @@
  * timeout, cancellation) rethrow untouched; they are the step's truth, not a
  * divergence.
  */
-import { anchorsPresent } from '../cache/anchors.js';
 import { isRelocatableDescriptor, MAIN_LIST_SHARE, relocateDescriptor } from '../cache/relocate.js';
 import { isNodeAction } from '../cache/trace.js';
 import { hasCause } from '../internal/errors.js';
@@ -146,25 +145,30 @@ export async function replayTrace(host, trace, options = {}) {
                     break;
                 }
                 case 'free':
+                    if (previous !== undefined && options.looksBeforeFree?.() === true)
+                        await firstLook(host, look);
                     await planned.invoke();
                     break;
                 case 'scroll': {
-                    if (planned.list === undefined) {
-                        // A viewport scroll relocates nothing, so each later repeat takes
-                        // a settled look of its own, as the live loop did between them.
-                        for (let index = 0; index < planned.times; index += 1) {
+                    // A scroll on a list is paced by the relocation before each repeat.
+                    // A viewport scroll relocates nothing, so each later repeat takes a
+                    // settled look of its own, as the live loop did between them. A
+                    // list judged lost scrolls as the viewport from then on, instead of
+                    // waiting out the relocation backoff again on every repeat.
+                    let list = planned.list;
+                    for (let index = 0; index < planned.times; index += 1) {
+                        if (list === undefined) {
                             if (index > 0)
                                 await host.observe('held-still');
                             await host.actions.scroll(planned.direction);
-                            repeated += 1;
                         }
-                        break;
-                    }
-                    // A scroll on a list is paced by the relocation before each repeat.
-                    for (let index = 0; index < planned.times; index += 1) {
-                        const lost = await scrollOnce(host, planned.direction, planned.list, index === 0 ? look : HELD_STILL);
-                        if (lost !== undefined)
-                            return stop(lost, partial());
+                        else {
+                            const scrolled = await scrollOnce(host, planned.direction, list, index === 0 ? look : HELD_STILL);
+                            if (scrolled.kind === 'failed')
+                                return stop(scrolled.failure, partial());
+                            if (scrolled.kind === 'viewport')
+                                list = undefined;
+                        }
                         repeated += 1;
                     }
                     break;
@@ -228,21 +232,19 @@ export async function replayTrace(host, trace, options = {}) {
     return { completed: true, executed: summaries.length, total, summaries };
 }
 /**
- * Verifies a trace's recorded end anchors against the live screen: every
- * anchor must be present again (`anchors.ts`, every recorded field equal) or
- * the replay must not pass on its own. Waits on the same settling backoff
+ * Waits for a trace's recorded end state on the live screen: `holds` (the
+ * recorded delta, `cache/anchors.ts`) must be true of one look, or the
+ * replay must not pass on its own. Waits on the same settling backoff
  * relocation uses, because the recording run's final look came seconds of
  * model latency after its last action and a replay's comes right away: a
  * save still in flight is a wait, not a divergence. A surface that cannot be
  * observed at all is a mismatch too — the executor gets the step and judges
  * the live state; only runtime hard stops propagate.
  */
-export async function verifyAnchors(host, anchors, options = {}) {
-    if (anchors.length === 0)
-        return true;
+export async function verifyEndState(host, holds, options = {}) {
     const startedMs = Date.now();
     try {
-        const present = await pollSettled(host, ({ nodes }) => anchorsPresent(anchors, nodes, host) ? true : undefined, options.initial === undefined ? HELD_STILL : { kind: 'in-hand', screen: options.initial });
+        const present = await pollSettled(host, (screen) => holds(screen) ? true : undefined, options.initial === undefined ? HELD_STILL : { kind: 'in-hand', screen: options.initial });
         if (present === true)
             return true;
         // The settling backoff covers a slow re-render; the recorded run may have
@@ -255,7 +257,7 @@ export async function verifyAnchors(host, anchors, options = {}) {
             const screen = await host.observe('raw');
             if (screen.kind === 'pixels' || !host.traceEligible)
                 return false;
-            if (anchorsPresent(anchors, screen.nodes, host))
+            if (holds(screen))
                 return true;
         }
         return false;
@@ -272,10 +274,9 @@ const END_WAIT_POLL_MS = 1_000;
 const END_WAIT_RESERVE_MS = 20_000;
 /** Relocates one descriptor against the settling screen, looking again while `retryable` says the failure may pass. */
 async function relocate(host, descriptor, look) {
-    const options = { redact: host.redact };
     let last = { kind: 'failed', failure: 'target-not-found' };
     const settled = await pollSettled(host, (screen) => {
-        const result = relocateDescriptor(descriptor, screen.nodes, options);
+        const result = relocateDescriptor(descriptor, screen.nodes);
         if (result.kind === 'failed') {
             last = result.failure === 'target-not-found' ? result : { ...result, screen };
             return retryable(result.failure, descriptor) ? undefined : last;
@@ -294,17 +295,16 @@ async function relocate(host, descriptor, look) {
  * unpositioned ambiguity is not.
  */
 async function relocatePair(host, source, destination, look) {
-    const options = { redact: host.redact };
     let last = 'target-not-found';
     const failed = (descriptor, failure) => {
         last = failure;
         return retryable(failure, descriptor) ? undefined : { kind: 'failed', failure };
     };
     const settled = await pollSettled(host, (screen) => {
-        const from = relocateDescriptor(source, screen.nodes, options);
+        const from = relocateDescriptor(source, screen.nodes);
         if (from.kind === 'failed')
             return failed(source, from.failure);
-        const to = relocateDescriptor(destination, screen.nodes, options);
+        const to = relocateDescriptor(destination, screen.nodes);
         if (to.kind === 'failed')
             return failed(destination, to.failure);
         return { kind: 'found', source: from.id, destination: to.id };
@@ -380,12 +380,12 @@ async function scrollOnce(host, direction, list, look) {
     const relocated = await relocate(host, list.descriptor, look);
     if (relocated.kind === 'found') {
         await host.actions.scroll(direction, { id: relocated.id });
-        return undefined;
+        return { kind: 'list' };
     }
     if ((list.spans ?? 0) < MAIN_LIST_SHARE)
-        return relocated.failure;
+        return { kind: 'failed', failure: relocated.failure };
     await host.actions.scroll(direction);
-    return undefined;
+    return { kind: 'viewport' };
 }
 /** A fresh look that proves the screen holds still: the first look of a replay without a start capture, and the look after an action that moved the screen. */
 const HELD_STILL = { kind: 'capture', settle: 'held-still' };

package/dist/agent/scroll-target.d.ts

@@ -10,11 +10,10 @@
  * all scrolls as the viewport does, which is what scrolling the main list
  * does; a smaller region that vanished is gone, as for any other action.
  */
-import type { SemanticNode } from '../engine/surface.ts';
 import { type Box } from '../internal/geometry.ts';
 import type { ExecutorTarget } from './executor.ts';
 import { type ObservationFeed, type Resolved } from './observation-feed.ts';
-import type { SemanticAgentObservation } from './observation.ts';
+import type { RedactedNode, SemanticAgentObservation } from './observation.ts';
 /**
  * The node a scroll target names now: the node itself, its descriptor's
  * match, or the same-role node in its old place. Undefined for a lost list
@@ -22,4 +21,4 @@ import type { SemanticAgentObservation } from './observation.ts';
  */
 export declare function resolveScrollTarget(feed: ObservationFeed, target: ExecutorTarget): Resolved | undefined;
 /** The listed node of the role whose box overlaps `box` most, when it overlaps enough. */
-export declare function samePlace(observation: SemanticAgentObservation, role: string | undefined, box: Box): SemanticNode | undefined;
+export declare function samePlace(observation: SemanticAgentObservation, role: string | undefined, box: Box): RedactedNode | undefined;

package/dist/agent/step-cache.d.ts

@@ -12,6 +12,7 @@
  * when replay performed no action.
  */
 import type { AgentCacheContext } from '../cache/context.ts';
+import type { CacheAgentIdentity } from '../cache/identity.ts';
 import { type ParamTemplate } from '../cache/template.ts';
 import { type DerivedReason } from '../cache/trace.ts';
 import type { StepCacheInfo } from '../run/steps.ts';
@@ -42,7 +43,11 @@ export interface StepCacheOptions {
         readonly name: string;
         readonly version?: string;
     };
+    /** The agent the step runs with, part of the key (`cache/identity.ts`). */
+    readonly agent: CacheAgentIdentity;
     readonly redact: (text: string) => string;
+    /** `redact` for a field cut at its observed limit (`SecretLedger.redactCut`). */
+    readonly redactCut: (text: string) => string;
     readonly maxActions: number;
     /** Timeline index of the step being dispatched. */
     readonly stepIndex: number;
@@ -60,8 +65,11 @@ export declare class StepTraceSession {
     private readonly host;
     private readonly cache;
     private readonly keyHash;
+    /** The claimed key and the step it names, which an entry records as its provenance. */
+    private readonly claim;
     private readonly recorder;
     private readonly options;
+    private readonly redaction;
     private info;
     private prefix;
     private startPath;
@@ -85,6 +93,8 @@ export declare class StepTraceSession {
     private replayedWhole;
     /** True once a cached entry's actions were run this step, fully or partly. */
     private consumedReplay;
+    /** True once the store returned an entry for this step, whether or not it replayed. */
+    private readEntryHit;
     /** True once `cache.strict` failed the step on its recording, which is then kept for review rather than evicted. */
     private failedStale;
     /** Grammar actions recorded so far when an end-mismatch hand-off happened. */
@@ -107,7 +117,8 @@ export declare class StepTraceSession {
      * self-finalized verdict on a full replay whose postcondition holds;
      * undefined dispatches the executor — after a miss from the top, after a
      * divergence mid-step with `replayedPrefix` set. Every failure to replay is
-     * a miss, never an error; only runtime hard stops propagate.
+     * a miss, never an error; only runtime hard stops and a policy denial on
+     * the opening look propagate.
      */
     begin(): Promise<StepVerdict | undefined>;
     /**
@@ -117,6 +128,14 @@ export declare class StepTraceSession {
      * model call to absorb on every run. The report keeps the cache detail.
      */
     private failIfStale;
+    /**
+     * Under `cache.strict`, ends a step whose key found no entry while the
+     * store holds a recording made for the same step under another key: the
+     * runner, the engine, the app, or the agent's context changed since, and
+     * the recording no longer replays as surely as one that diverged. A step
+     * whose instruction or params changed is a new step and still runs live.
+     */
+    private failIfRekeyed;
     /**
      * Closes the session once the step has settled. The whole write-side
      * decision lives here, in read-write mode only:
@@ -136,6 +155,10 @@ export declare class StepTraceSession {
      *   anchor, or end wait, so drift is repaired only once a relocation fails
      *   and the hand-off that follows re-records.
      * - passed otherwise: stage the recorded trace for attempt-end settlement.
+     *   When this pass leaves nothing to stage (it changed nothing a replay
+     *   could check) and an entry was read for the step, evict that entry: it
+     *   did not serve this pass, and nothing recorded will replace it, so
+     *   keeping it would hand every later run off the same way.
      * - failed after consuming a replay: evict. Without this, a diverged replay
      *   whose step then fails stages nothing — and the poisoned entry would
      *   replay its bad prefix on every future first attempt.
@@ -172,18 +195,22 @@ export declare class StepTraceSession {
     private replayEntry;
     /**
      * The trace's postcondition against the live screen: the recorded end
-     * route (when the live location is known) and every recorded end anchor
-     * present again. A route the path leaves undecided is the recorded screen
-     * only if the anchors are already on it, which then needs no second look.
+     * route when the live location is known, the recorded delta on the
+     * screen (`deltaHolds`), and evidence that the replay produced it rather
+     * than finding it there (`deltaEvidenced`). The evidence is measured from
+     * the first screen the replay saw on the route it ended on (`screens`, in
+     * order): the start for a step that stays on one screen, the page a
+     * recorded navigate opened before the switch on it was tapped. An outcome
+     * already showing there proves nothing, and neither does a recording with
+     * no delta at all.
      */
     private endStateMatches;
     /**
      * Captures the semantic end state once its route matches the recording,
-     * polling while a navigation the last action started commits. Reports
-     * whether the anchors were what settled the route, so the caller does not
-     * verify them again. A route still undecided when the poll runs out is
-     * handed on with the anchors unseen: the caller's anchor wait, sized by
-     * the recording, is the one that decides it, as for a route that matched.
+     * polling while a navigation the last action started commits. A route
+     * that never matches is another screen, whatever it shows: a link that
+     * now lands on a page sharing the recorded one's layout is exactly the
+     * flow that went wrong.
      */
     private endScreen;
     private selfFinalize;
@@ -199,12 +226,13 @@ export declare class StepTraceSession {
      *
      * The end path and a fresh settled observation are the trace's
      * postcondition — the state the step passed in. The delta between the
-     * baseline and the passing observation becomes the end anchors. When the
-     * step moved to another pathname the whole new screen is the delta, and its
-     * first stable anchors back the path check, which matches a created
-     * record's page up to the id the app minted for it. A postcondition that
-     * cannot be captured stages nothing: a trace without its check would
-     * replay on mechanics alone.
+     * baseline and the passing observation becomes the anchors: what appeared
+     * and what vanished. When the step moved to another pathname the whole new
+     * screen is the delta, and its first stable anchors back the path check,
+     * which matches a created record's page up to the id the app minted for
+     * it. A postcondition that cannot be captured stages nothing, and neither
+     * does a step that changed nothing a replay could check, no node and no
+     * route: a trace without its check would replay on mechanics alone.
      */
     private stage;
     /**