e2e 0.16.0 → 0.17.0

package/dist/agent/observation.js

@@ -15,10 +15,11 @@ const UNAVAILABLE_TREE_MARKER = '[semantic capture unavailable: no nodes were re
  *
  * Pixels whose masking the engine cannot prove (fewer masked regions than
  * secure nodes) are withheld before they reach a model or disk; the semantic
- * tree never carries secure values. Registered secret values are additionally
- * replaced by their stable secret name, and so is the leading part of one a
- * field the engine cut at its limit ends with. A field holding one keeps no
- * selection, as a secure field keeps none.
+ * tree never carries secure values. Every string of every node is redacted
+ * once, here (`redactNode`): registered secret values are replaced by their
+ * stable secret name, and so is the leading part of one a field the engine
+ * cut at its limit ends with. A field holding one keeps no selection, as a
+ * secure field keeps none.
  */
 export function prepareObservation(observation, options) {
     const location = observation.location === undefined ? undefined : options.redact(observation.location);
@@ -42,11 +43,10 @@ export function prepareObservation(observation, options) {
             pixels: pixels.cleared,
         };
     }
-    const tree = protectSecrets(observation.tree, options);
+    const tree = redactNode(observation.tree, options);
     const nodes = new Map();
     const parents = new Map();
     indexNodes(tree, nodes, parents);
-    const redact = options.redact;
     const lines = [];
     const encoder = new TextEncoder();
     // The marker is reserved up front so a truncated observation still fits the
@@ -63,7 +63,7 @@ export function prepareObservation(observation, options) {
     const emit = (node, depth) => {
         if (cutByBudget)
             return;
-        const line = formatNode(node, depth, redact, options.appOrigin);
+        const line = formatNode(node, depth, options.appOrigin);
         const size = encoder.encode(`${line}\n`).byteLength;
         if (lines.length > 0 && bytes + size > budget) {
             cutByBudget = true;
@@ -97,40 +97,94 @@ export function prepareObservation(observation, options) {
         ...(pixels.withheld === undefined ? {} : { pixelsWithheld: pixels.withheld }),
     };
 }
-/** The fields an engine may cut, each at its observed limit. */
-const CUT_FIELDS = [
-    ['name', OBSERVED_NAME_LIMIT],
-    ['text', OBSERVED_TEXT_LIMIT],
-    ['value', OBSERVED_TEXT_LIMIT],
-    ['selection', OBSERVED_TEXT_LIMIT],
-];
+/** Leaves a field the engine fills from a closed set (an enum, booleans, numbers) or mints itself as it is. */
+const keep = (value) => value;
 /**
- * The tree with what whole-value redaction misses taken out, before any
- * consumer reads it. Every field exactly as long as its observed limit, and
- * so possibly cut there, passes through `redactCut`: a secret the cut stopped
- * partway through leaves a leading part at the end that no whole value
- * matches. A shorter field is whole, and so is a longer one (a native input's
- * value, which no engine cuts); both are left to `redact`. A selection that
- * may show part of a secret is dropped, as a secure field's is. A subtree
- * with nothing changed is returned as it is.
+ * How each field of a node is redacted, one entry per field of
+ * `SemanticNode`: a field added to the contract does not compile until it
+ * says how its text is redacted, and a key an engine sends that the
+ * contract does not name is dropped. Every string passes through
+ * `redactText`. A secure node keeps no value or selection, and a selection
+ * that may show part of a secret is dropped, as a secure field's is. The ref
+ * is the engine's own handle, sent back to it to act, never page text.
  */
-function protectSecrets(node, redaction) {
-    const withhold = node.selection !== undefined && selectionMayHoldSecret(node, node.selection, redaction);
-    const changed = {};
-    for (const [field, limit] of CUT_FIELDS) {
-        const text = node[field];
-        if (text?.length !== limit || (withhold && field === 'selection'))
+const NODE_FIELDS = {
+    ref: keep,
+    role: (role, _node, redaction) => redactText(role, redaction),
+    name: (name, _node, redaction) => redactText(name, redaction, OBSERVED_NAME_LIMIT),
+    text: (text, _node, redaction) => redactText(text, redaction, OBSERVED_TEXT_LIMIT),
+    value: (value, node, redaction) => (node.states?.secure === true ? undefined : redactText(value, redaction, OBSERVED_TEXT_LIMIT)),
+    selection: (selection, node, redaction) => node.states?.secure === true || selectionMayHoldSecret(node, selection, redaction)
+        ? undefined
+        : redactText(selection, redaction, OBSERVED_TEXT_LIMIT),
+    testId: (testId, _node, redaction) => redactText(testId, redaction),
+    inputPurpose: keep,
+    states: keep,
+    level: keep,
+    attributes: (attributes, _node, redaction) => Object.fromEntries(Object.entries(attributes).map(([key, value]) => [redactText(key, redaction), redactText(value, redaction)])),
+    rect: keep,
+    selector: (selector, _node, redaction) => redactText(selector, redaction),
+    framePath: (framePath, _node, redaction) => framePath.map((selector) => redactText(selector, redaction)),
+};
+/**
+ * The node and its subtree with every secret taken out of every field
+ * (`NODE_FIELDS`), before any consumer reads it: the model's text, the
+ * executor's tree, cache descriptors and anchors, failure evidence.
+ */
+export function redactNode(node, redaction) {
+    const redacted = {};
+    for (const [field, value] of Object.entries(node)) {
+        if (field === 'children' || value === undefined || !Object.hasOwn(NODE_FIELDS, field))
             continue;
-        const redacted = redaction.redactCut(text);
-        if (redacted !== text)
-            changed[field] = redacted;
+        const redactValue = NODE_FIELDS[field];
+        const result = redactValue(value, node, redaction);
+        if (result !== undefined)
+            redacted[field] = result;
     }
-    const children = node.children?.map((child) => protectSecrets(child, redaction));
-    const sameChildren = (children ?? []).every((child, index) => child === node.children?.[index]);
-    if (!withhold && Object.keys(changed).length === 0 && sameChildren)
-        return node;
-    const { selection: _selection, ...withoutSelection } = node;
-    return { ...(withhold ? withoutSelection : node), ...changed, ...(children === undefined ? {} : { children }) };
+    if (node.children !== undefined)
+        redacted['children'] = node.children.map((child) => redactNode(child, redaction));
+    return redacted;
+}
+/**
+ * An earlier capture's nodes redacted again through the ledger as it is now,
+ * each on its own fields, then linked to its redacted-again children, so the
+ * tree keeps its shape (which nodes are leaves) without a subtree redacted
+ * once per ancestor. A secret a provider resolved after the capture masks
+ * text the capture still shows, so the two captures read alike wherever the
+ * screen did not change. Redacting redacted text changes nothing else: a
+ * marker is never read again.
+ */
+export function redactNodesAgain(nodes, redaction) {
+    const again = new Map();
+    for (const [id, { children: _children, ...fields }] of nodes)
+        again.set(id, redactNode(fields, redaction));
+    for (const [id, { children }] of nodes) {
+        const node = again.get(id);
+        if (node === undefined || children === undefined)
+            continue;
+        node.children = children.map((child) => again.get(child.ref.id)).filter((child) => child !== undefined);
+    }
+    return again;
+}
+/**
+ * One observed string with every secret taken out, in the form it is written
+ * and in the one-line form a line, a descriptor, or an anchor shows it
+ * (`collapseText`). A field exactly as long as `limit`, and so possibly cut
+ * there, passes through `redactCut`: a secret the cut stopped partway through
+ * leaves a leading part at the end that no whole value matches. A shorter
+ * field is whole, and so is a longer one (a native input's value, which no
+ * engine cuts); both pass through `redact`. A field whose collapsed form
+ * still holds a secret (the whitespace inside a value widened) is kept
+ * collapsed and redacted, so no later collapse brings the value back.
+ */
+function redactText(text, redaction, limit) {
+    const pass = text.length === limit ? redaction.redactCut : redaction.redact;
+    const redacted = pass(text);
+    const collapsed = collapseText(redacted);
+    if (collapsed === redacted)
+        return redacted;
+    const read = pass(collapsed);
+    return read === collapsed ? redacted : read;
 }
 /**
  * Whether a node's selection may show part of a secret, which no whole-value
@@ -142,7 +196,7 @@ function protectSecrets(node, redaction) {
 function selectionMayHoldSecret(node, selection, redaction) {
     const fields = [node.value, node.text].filter((text) => text !== undefined);
     const cut = (text) => text.length === OBSERVED_TEXT_LIMIT;
-    if (fields.some((text) => (cut(text) ? redaction.redactCut(text) : redaction.redact(text)) !== text))
+    if (fields.some((text) => redactText(text, redaction, OBSERVED_TEXT_LIMIT) !== text))
         return true;
     return fields.some(cut) && !fields.some((text) => text.includes(selection));
 }
@@ -234,33 +288,29 @@ export function interactiveNodeCount(observation) {
     return count;
 }
 /**
- * Projects the raw tree onto the executor-facing node shape: the same
- * redaction the text serialization applies, field by field, and no value or
- * selection at all for a secure node, and a link target bounded as a line
+ * Projects a redacted tree onto the executor-facing node shape, the fields
+ * the text serialization renders, with a link target bounded as a line
  * bounds it: a target on `appOrigin` keeps that origin and loses no more of
  * its path than the line does. Selectors stay behind — they are relocation
  * material for the trace cache, not something a brain reasons about.
  */
-export function projectTree(node, redact, appOrigin) {
-    const secure = node.states?.secure === true;
+export function projectTree(node, appOrigin) {
     const attributes = node.attributes === undefined
         ? undefined
-        : Object.fromEntries(Object.entries(node.attributes).map(([key, value]) => [key, key === 'href' ? treeHref(redact(value), appOrigin) : redact(value)]));
+        : Object.fromEntries(Object.entries(node.attributes).map(([key, value]) => [key, key === 'href' ? treeHref(value, appOrigin) : value]));
     return {
         id: node.ref.id,
         ...(node.role === undefined ? {} : { role: node.role }),
-        ...(node.name === undefined ? {} : { name: redact(node.name) }),
-        ...(node.text === undefined ? {} : { text: redact(node.text) }),
-        ...(node.value === undefined || secure ? {} : { value: redact(node.value) }),
-        ...(node.selection === undefined || secure ? {} : { selection: redact(node.selection) }),
+        ...(node.name === undefined ? {} : { name: node.name }),
+        ...(node.text === undefined ? {} : { text: node.text }),
+        ...(node.value === undefined ? {} : { value: node.value }),
+        ...(node.selection === undefined ? {} : { selection: node.selection }),
         ...(node.inputPurpose === undefined ? {} : { inputPurpose: node.inputPurpose }),
         ...(node.states === undefined ? {} : { states: node.states }),
         ...(attributes === undefined ? {} : { attributes }),
         ...(node.rect === undefined ? {} : { rect: node.rect }),
         ...(node.framePath === undefined ? {} : { framePath: node.framePath }),
-        ...(node.children === undefined
-            ? {}
-            : { children: node.children.map((child) => projectTree(child, redact, appOrigin)) }),
+        ...(node.children === undefined ? {} : { children: node.children.map((child) => projectTree(child, appOrigin)) }),
     };
 }
 /** Depth beyond this renders flat; deep chrome must not buy tokens with spaces. */
@@ -273,37 +323,37 @@ const MAX_HREF_LENGTH = 256;
  * lines, and the model needs their text, not a filler word. A link target on
  * `appOrigin`, the app base URL's, renders as its path.
  */
-export function formatNode(node, depth, redact, appOrigin) {
+export function formatNode(node, depth, appOrigin) {
     const parts = [`#${node.ref.id}`];
     if (node.role !== undefined && node.role !== '')
         parts.push(node.role);
     if (node.name !== undefined && node.name !== '')
-        parts.push(JSON.stringify(redact(node.name)));
+        parts.push(JSON.stringify(node.name));
     const text = node.text === undefined ? '' : collapseText(node.text);
     if (text !== '' && text !== node.name)
-        parts.push(`text=${JSON.stringify(redact(text))}`);
+        parts.push(`text=${JSON.stringify(text)}`);
     // Disambiguators the model needs when role and name repeat. The engine has
     // already reduced href to origin and path.
     if (node.testId !== undefined && node.testId !== '')
         parts.push(`testid=${JSON.stringify(node.testId)}`);
     const href = node.attributes?.['href'];
     if (href !== undefined && href !== '')
-        parts.push(`href=${JSON.stringify(renderHref(redact(href), appOrigin))}`);
+        parts.push(`href=${JSON.stringify(renderHref(href, appOrigin))}`);
     const placeholder = node.attributes?.['placeholder'];
     if (placeholder !== undefined && placeholder !== '' && (node.name ?? '') === '') {
-        parts.push(`placeholder=${JSON.stringify(redact(placeholder))}`);
+        parts.push(`placeholder=${JSON.stringify(placeholder)}`);
     }
     if (node.states?.secure === true) {
         parts.push('value=<secure>');
     }
     else if (node.value !== undefined && node.value !== '') {
-        parts.push(`value=${JSON.stringify(redact(node.value))}`);
+        parts.push(`value=${JSON.stringify(node.value)}`);
     }
     // What a Shift+Arrow press selected: without it the model extends a
     // selection blind and cannot tell one word from its neighbour. Rendered
     // verbatim (escaped), since a selected space or newline is a selection too.
-    if (node.selection !== undefined && node.selection !== '' && node.states?.secure !== true) {
-        parts.push(`selection=${JSON.stringify(redact(node.selection))}`);
+    if (node.selection !== undefined && node.selection !== '') {
+        parts.push(`selection=${JSON.stringify(node.selection)}`);
     }
     if (node.inputPurpose !== undefined && node.inputPurpose !== 'none') {
         parts.push(`purpose=${node.inputPurpose}`);

package/dist/agent/point-tap.d.ts

@@ -7,9 +7,9 @@
  * screenshot are scaled into the observation's CSS pixels first.
  */
 import type { PointActionName } from '../cache/trace.ts';
-import type { SemanticNode, ViewportPoint, ViewportSize } from '../engine/surface.ts';
+import type { ViewportPoint, ViewportSize } from '../engine/surface.ts';
 import type { ExecutorPixels } from './executor.ts';
-import { type AgentObservation } from './observation.ts';
+import { type AgentObservation, type RedactedNode } from './observation.ts';
 /**
  * Scales a point read off a screenshot into the observation's CSS pixels and
  * clamps it to the viewport. `pixels.scale` is image pixels per CSS pixel
@@ -23,9 +23,9 @@ export declare function imagePointToViewport(point: {
 }, pixels: Pick<ExecutorPixels, 'width' | 'height' | 'scale'>, viewport: ViewportSize): ViewportPoint;
 export interface HitTest {
     /** The innermost enabled control whose box contains the point, if any. */
-    readonly control: SemanticNode | undefined;
+    readonly control: RedactedNode | undefined;
     /** The innermost listed node of any role whose box contains the point, if any. */
-    readonly under: SemanticNode | undefined;
+    readonly under: RedactedNode | undefined;
 }
 /**
  * Finds what the newest observation lists at a viewport point. Only an
@@ -54,12 +54,12 @@ export declare const POINT_VERBS: Readonly<Record<PointActionName, {
 export declare function describePointAction(input: PointProse & {
     readonly verb: PointActionName;
     readonly point: ViewportPoint;
-    readonly control: SemanticNode | undefined;
-    readonly under: SemanticNode | undefined;
+    readonly control: RedactedNode | undefined;
+    readonly under: RedactedNode | undefined;
 }): string;
 /** What one hit test found, for the model that named the point. */
 export declare function describePointHit(input: PointProse & {
     readonly point: ViewportPoint;
-    readonly control: SemanticNode | undefined;
-    readonly under: SemanticNode | undefined;
+    readonly control: RedactedNode | undefined;
+    readonly under: RedactedNode | undefined;
 }): string;

package/dist/agent/point-tap.js

@@ -41,7 +41,7 @@ export function hitTest(observation, point) {
  * The innermost listed node whose box contains the point, among those
  * `accept` admits: deepest in the tree, then the smallest box. Hidden nodes
  * and nodes without a box are skipped. Every box is in the top-level
- * viewport's CSS pixels, nested documents included (`SemanticNode.rect`), so
+ * viewport's CSS pixels, nested documents included (`RedactedNode.rect`), so
  * a node inside an iframe is found like any other.
  */
 function innermostAt(observation, point, accept = () => true) {

package/dist/agent/replay.d.ts

@@ -11,15 +11,20 @@
  * timeout, cancellation) rethrow untouched; they are the step's truth, not a
  * divergence.
  */
-import { type ActionTrace, type DerivedReason, type TraceTargetDescriptor, type TraceViewport } from '../cache/trace.ts';
-import type { SemanticNode } from '../engine/surface.ts';
+import { type ActionTrace, type DerivedReason, type TraceViewport } from '../cache/trace.ts';
+import type { RedactedNode } from './observation.ts';
 import { type ExecutorActions, type ReplayHandOffReason } from './executor.ts';
 import { type SettleMode } from './settle-policy.ts';
 /** The nodes of one observation, keyed by their per-observation ids. */
-export type ObservedNodes = ReadonlyMap<string, SemanticNode>;
+export type ObservedNodes = ReadonlyMap<string, RedactedNode>;
 /** One capture's location and viewport, with nodes only when semantic evidence is available. */
 export type ObservedScreen = {
     readonly viewport: TraceViewport;
+    /**
+     * Where the capture was, as the cache compares it (`appLocation`): on the
+     * app's own origin its path, query, and fragment; elsewhere the whole
+     * location; a device's screen title as it is.
+     */
     readonly path?: string;
 } & ({
     readonly kind: 'semantic';
@@ -45,7 +50,6 @@ export interface ReplayHost {
     readonly actions: ExecutorActions;
     readonly signal: AbortSignal;
     remainingMs(): number;
-    readonly redact: (text: string) => string;
 }
 export interface ReplayOutcome {
     /** True when every recorded action executed; the step self-finalizes. */
@@ -67,20 +71,27 @@ export interface ReplayOptions {
      * instead of capturing again: nothing has happened since it was taken.
      */
     readonly initial?: SemanticScreen;
+    /**
+     * Asked before a free action (a navigate, typed text, a key) that follows
+     * another action; true takes the look a targeted action would have taken.
+     * A free action reads no screen, so without it the screen the previous
+     * action left goes unseen.
+     */
+    readonly looksBeforeFree?: () => boolean;
 }
 /** Replays one trace until it completes or diverges. */
 export declare function replayTrace(host: ReplayHost, trace: ActionTrace, options?: ReplayOptions): Promise<ReplayOutcome>;
 /**
- * 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 declare function verifyAnchors(host: ReplayHost, anchors: readonly TraceTargetDescriptor[], options?: {
+export declare function verifyEndState(host: ReplayHost, holds: (screen: SemanticScreen) => boolean, options?: {
     readonly waitMs?: number;
     readonly initial?: SemanticScreen;
 }): Promise<boolean>;

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,6 +145,8 @@ 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': {
@@ -228,21 +229,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 +254,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 +271,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 +292,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 };

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. */
@@ -117,6 +127,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 +154,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 +194,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 +225,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;
     /**