Skip to content

Commit 5731692

Browse files
committed
refactor(daemon): take the four review findings, three of which delete code
Review on #1615, all non-blocking; applied rather than deferred because three of the four remove lines. 1. Named the capture-strategy union. `SnapshotCaptureBackend` now lives in kernel/snapshot beside `SnapshotBackend`, and `SnapshotQualityVerdict` uses it. The two docblocks whose only job was saying what the type is NOT (11 lines in types.ts, 4 on CapturedSurface) collapse to the load-bearing #1569 comparability warning. 2. Trimmed comment mass. The key-vs-identity rationale said one thing three times over 20 lines; it says it once. `rectsWithinTolerance` no longer names its callers — that roster drifts the first time a fourth lands. The test comment restating the (now deleted) docblock is gone; the test name carries it. That also fixes a drift already present: the removed docblock claimed `gesture <subtype> …` reaches the warning by default, when `isPostGestureStabilizingAction` only admits `gesture swipe`. 3. Deleted the scroll exception, the numeric heuristic's last vestige. `describeGesturePositionals` and its 17-line docblock existed to suppress one token (`scroll down 0.6` -> "scroll down"). Positionals now echo verbatim: the warning names the gesture the agent issued, and `scroll down 0.6` is what they issued. Helper, docblock and exception all go; one test assertion updates. 4. `PostGestureStabilization.positionals` is required. Its only writer always sets it, so `pending.positionals ?? []` guarded an impossible state. Tightening it caught five test fixtures constructing the state without the field — the type doing its job. 93 files / 733 tests green; typecheck, lint, format, check:layering clean.
1 parent 1d040ab commit 5731692

8 files changed

Lines changed: 42 additions & 80 deletions

File tree

‎packages/kernel/src/snapshot.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,18 @@
66
* snapshot-quality.ts so SnapshotNode can reference it without a cyclic import;
77
* snapshot-quality.ts (the validation logic) re-exports it for existing callers.
88
*/
9+
/**
10+
* Which capture STRATEGY produced a snapshot, within one platform's plan —
11+
* distinct from `SnapshotBackend`, which names the platform channel
12+
* (`xctest`/`android`/…). The iOS plan walks these in order, so a single
13+
* session can change strategy mid-sequence; two strategies do not return
14+
* comparable views of one screen (#1569).
15+
*/
16+
export type SnapshotCaptureBackend = 'tree' | 'queries' | 'private-ax';
17+
918
export type SnapshotQualityVerdict = {
1019
state: 'healthy' | 'recovered' | 'sparse';
11-
backend: 'tree' | 'queries' | 'private-ax';
20+
backend: SnapshotCaptureBackend;
1221
reason?: string;
1322
// 'deferred' = the penalty circuit breaker pre-selected a non-XCTest backend; nothing new
1423
// degraded on THIS capture (no repeated warning, no settle budget reset).

‎src/daemon/__tests__/direct-ios-selector.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ test('isLocalIosRunnerSession: iOS local sessions are eligible, Android and unde
108108

109109
test('isLocalIosRunnerSession: skipPendingPostGestureStabilization:true excludes a pending session (the tap fast path)', () => {
110110
const pending = makeSession('ios', {
111-
postGestureStabilization: { action: 'scroll', markedAt: Date.now() },
111+
postGestureStabilization: { action: 'scroll', positionals: [], markedAt: Date.now() },
112112
});
113113
assert.equal(
114114
isLocalIosRunnerSession(pending, { skipPendingPostGestureStabilization: true }),
@@ -118,7 +118,7 @@ test('isLocalIosRunnerSession: skipPendingPostGestureStabilization:true excludes
118118

119119
test('isLocalIosRunnerSession: skipPendingPostGestureStabilization:false keeps a pending session eligible (the offscreen double-check)', () => {
120120
const pending = makeSession('ios', {
121-
postGestureStabilization: { action: 'scroll', markedAt: Date.now() },
121+
postGestureStabilization: { action: 'scroll', positionals: [], markedAt: Date.now() },
122122
});
123123
assert.equal(
124124
isLocalIosRunnerSession(pending, { skipPendingPostGestureStabilization: false }),

‎src/daemon/__tests__/post-gesture-stabilization.test.ts‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -236,8 +236,10 @@ test('scope drift accepts stale but is vetoed from claiming no-effect (#1601 P1
236236
});
237237

238238
test('formatGestureNoEffectWarning names the gesture and the raw-drag escape hatch', () => {
239+
// Positionals echo verbatim: the warning names the gesture the agent just
240+
// issued, and `scroll down 1` is what they issued.
239241
const scrollWarning = formatGestureNoEffectWarning('scroll', ['down', '1']);
240-
assert.match(scrollWarning, /scroll down produced no visible change/);
242+
assert.match(scrollWarning, /scroll down 1 produced no visible change/);
241243
assert.match(scrollWarning, /swipe x1 y1 x2 y2/);
242244
assert.match(scrollWarning, /already at its edge/);
243245

@@ -248,11 +250,6 @@ test('formatGestureNoEffectWarning names the gesture and the raw-drag escape hat
248250
assert.match(bareWarning, /swipe produced no visible change/);
249251
});
250252

251-
// `swipe`'s positionals are ALWAYS coordinates (swipePayloadFromPositionals),
252-
// never a semantic label — the previous "drop anything numeric-looking"
253-
// filter stripped all four and left a bare, contentless "swipe". Reading
254-
// swipe's own fixed positional grammar instead of guessing from string shape
255-
// keeps them.
256253
test('formatGestureNoEffectWarning keeps swipe coordinates instead of dropping every positional', () => {
257254
const swipeWarning = formatGestureNoEffectWarning('swipe', ['10', '20', '30', '40']);
258255
assert.match(swipeWarning, /^swipe 10 20 30 40 produced no visible change/);

‎src/daemon/handlers/__tests__/interaction.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -849,7 +849,7 @@ test('click simple iOS id selector waits for snapshot path after pending gesture
849849
const sessionStore = makeSessionStore();
850850
const sessionName = 'ios-direct-selector-after-swipe';
851851
const session = makeIosSession(sessionName, { appBundleId: 'com.example.app' });
852-
session.postGestureStabilization = { action: 'swipe', markedAt: Date.now() };
852+
session.postGestureStabilization = { action: 'swipe', positionals: [], markedAt: Date.now() };
853853
sessionStore.set(sessionName, session);
854854

855855
mockDispatch.mockImplementation(async (_device, command, positionals) => {
@@ -3107,7 +3107,7 @@ test('is simple iOS selector falls back to snapshot while gesture stabilization
31073107
const sessionStore = makeSessionStore();
31083108
const sessionName = 'is-selected-ios-stabilizing';
31093109
const session = makeIosSession(sessionName, { appBundleId: 'com.example.app' });
3110-
session.postGestureStabilization = { action: 'swipe', markedAt: Date.now() };
3110+
session.postGestureStabilization = { action: 'swipe', positionals: [], markedAt: Date.now() };
31113111
sessionStore.set(sessionName, session);
31123112

31133113
mockDispatch.mockImplementation(async (_device, command) => {

‎src/daemon/handlers/__tests__/snapshot-handler.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1286,6 +1286,7 @@ test('captureSnapshot retries pending tap outcome before post-gesture stabilizat
12861286
};
12871287
session.postGestureStabilization = {
12881288
action: 'click',
1289+
positionals: [],
12891290
markedAt: Date.now(),
12901291
};
12911292

@@ -1361,6 +1362,7 @@ test('captureSnapshot composes post-gesture stabilization with Android freshness
13611362
};
13621363
session.postGestureStabilization = {
13631364
action: 'click',
1365+
positionals: [],
13641366
markedAt: Date.now(),
13651367
};
13661368

‎src/daemon/interaction-outcome-policy.ts‎

Lines changed: 9 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -191,12 +191,9 @@ export function areInteractionSurfaceSignaturesStable(
191191
}
192192

193193
/**
194-
* Shared rect-tolerance comparison for the three surface-stability checks in
195-
* this module (`areInteractionSurfaceSignaturesStable`,
196-
* `classifyBaselineSurfaceEvidence`, `haveIdenticalDiscriminatingSurfaces`).
197-
* Each entry's `x`/`y`/`width`/`height` are already the rounded values built
198-
* by `buildInteractionSurfaceEntry`, so a shared `RECT_TOLERANCE_PX` band
199-
* absorbs sub-pixel/rounding drift consistently across all three.
194+
* Shared rect-tolerance comparison for the surface-stability checks in this
195+
* module. Entry rects are already rounded by `buildInteractionSurfaceEntry`,
196+
* so one `RECT_TOLERANCE_PX` band absorbs residual drift consistently.
200197
*/
201198
function rectsWithinTolerance(
202199
a: Pick<InteractionSurfaceSignature[number], 'x' | 'y' | 'width' | 'height'>,
@@ -310,25 +307,12 @@ function identifiedContent(
310307
* the claim. Scope drift between baseline and capture vetoes too — silence
311308
* is the safe failure mode for a message that steers the agent's next move.
312309
*
313-
* Deliberately matches on `key`, not `identity` — the opposite choice from
314-
* `interactionSurfaceIdentity`'s own docblock, which calls keying on
315-
* `hittable`/`enabled`/`selected` "wrong for... is this the same element as
316-
* before the gesture" because scrolling flips `hittable` the moment a node's
317-
* centre leaves the viewport. That conclusion is about
318-
* `classifyBaselineSurfaceEvidence`, the primary movement oracle: it must
319-
* not lose an element's evidence to a volatile-state flip, so it keys on the
320-
* flip-tolerant `identity`. This function runs strictly AFTER that oracle
321-
* already returned `'unchanged'` — it exists only to decide whether an
322-
* already-accepted stale read is trustworthy enough for an agent-facing "no
323-
* visible change" claim, and for that a stricter key is the right tool: any
324-
* volatile-state flip (a hittability change, a selection toggle) makes the
325-
* two `key`s mismatch, `rightByKey.get` misses, and this function returns
326-
* `false`. That withholds the claim — it does not falsify anything, since
327-
* the caller still returns its result, just without `gestureNoEffect` set.
328-
* Silence on a coincidental flip is an acceptable cost; a false "nothing
329-
* happened" told to the agent is not. Using `identity` here instead would
330-
* make this veto more permissive, which is precisely wrong for a check whose
331-
* only job is to catch what the permissive oracle above already let through.
310+
* Matches on `key`, not the flip-tolerant `identity`
311+
* `classifyBaselineSurfaceEvidence` uses — deliberately the opposite choice.
312+
* That oracle must not lose evidence to a volatile-state flip; this runs only
313+
* after it already returned `'unchanged'`, and a veto wants precision over
314+
* recall: any flip makes the keys mismatch and returns `false`, withholding
315+
* the claim rather than falsifying anything.
332316
*/
333317
export function haveIdenticalDiscriminatingSurfaces(
334318
left: InteractionSurfaceSignature,

‎src/daemon/post-gesture-stabilization.ts‎

Lines changed: 4 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { emitDiagnostic } from '../utils/diagnostics.ts';
22
import { isApplePlatform, isMobilePlatform } from '@agent-device/kernel/device';
33
import type { CommandFlags } from '../core/dispatch.ts';
4-
import type { SnapshotQualityVerdict, SnapshotState } from '@agent-device/kernel/snapshot';
4+
import type { SnapshotCaptureBackend, SnapshotState } from '@agent-device/kernel/snapshot';
55
import { sleep } from '../utils/timeouts.ts';
66
import {
77
areInteractionSurfaceSignaturesStable,
@@ -109,10 +109,7 @@ export function decidePostGestureStabilityVerdict(params: {
109109
type CapturedSurface<T> = {
110110
value: T;
111111
signature: InteractionSurfaceSignature;
112-
// iOS capture-plan backend (`SnapshotQualityVerdict['backend']`), not the
113-
// platform `SnapshotBackend` — see `PostGestureStabilization.baselineBackend`
114-
// in types.ts.
115-
backend: SnapshotQualityVerdict['backend'] | undefined;
112+
backend: SnapshotCaptureBackend | undefined;
116113
};
117114

118115
async function captureInteractionSurface<T>(
@@ -241,29 +238,6 @@ export async function capturePostGestureStabilizedResult<T>(params: {
241238
return { value: previous.value };
242239
}
243240

244-
/**
245-
* Which positionals name the gesture in the warning. Echo them all, with one
246-
* exception: `scroll <direction> [amount]` carries a trailing magnitude that
247-
* is not part of the gesture's identity, so `scroll down 0.6` reads back as
248-
* "scroll down".
249-
*
250-
* Everything else echoes verbatim, which is both simpler and more truthful
251-
* than the "drop numeric-looking tokens" heuristic this replaces. That rule
252-
* ate every positional of `swipe <x1> <y1> <x2> <y2>` — the one action whose
253-
* coordinates ARE its identity — and reported a contentless bare "swipe".
254-
*
255-
* Only `scroll`, `swipe` and `gesture <subtype> …` reach here by default
256-
* (`isPostGestureStabilizingAction`); `--postGestureStabilization` can force
257-
* an arbitrary action through, and echoing its positionals is the honest
258-
* answer for one warning string. Reconstructing each `gesture` subtype's
259-
* layout would fork a grammar that lives in `GestureSemanticInput`, built
260-
* downstream of the raw positionals this function receives.
261-
*/
262-
function describeGesturePositionals(action: string, positionals: string[]): string[] {
263-
if (action !== 'scroll') return positionals;
264-
return positionals.slice(0, 1);
265-
}
266-
267241
/**
268242
* The agent-facing wording for a proven no-effect gesture. Names the exact
269243
* gesture, admits the honest ambiguity (at-edge is a legitimate no-op the
@@ -272,7 +246,7 @@ function describeGesturePositionals(action: string, positionals: string[]): stri
272246
* raw `swipe` worked where scroll/fling/pan all silently no-opped).
273247
*/
274248
export function formatGestureNoEffectWarning(action: string, positionals: string[]): string {
275-
const gesture = [action, ...describeGesturePositionals(action, positionals)].join(' ').trim();
249+
const gesture = [action, ...positionals].join(' ').trim();
276250
return (
277251
`${gesture} produced no visible change: the tree still matches its pre-gesture state. ` +
278252
'Either the container is already at its edge, or it ignores synthesized scrolls — ' +
@@ -299,7 +273,7 @@ function buildAcceptedStabilizedResult<T>(
299273
value: current.value,
300274
gestureNoEffect: {
301275
action: pending.action,
302-
positionals: pending.positionals ?? [],
276+
positionals: pending.positionals,
303277
},
304278
};
305279
}

‎src/daemon/types.ts‎

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ import type {
1818
DaemonRequest as WireRequest,
1919
} from '@agent-device/kernel/contracts';
2020
import type { DeviceInfo, Platform, PlatformSelector } from '@agent-device/kernel/device';
21-
import type { Rect, SnapshotQualityVerdict, SnapshotState } from '@agent-device/kernel/snapshot';
21+
import type { Rect, SnapshotCaptureBackend, SnapshotState } from '@agent-device/kernel/snapshot';
2222
import type { ExecBackgroundResult, ExecResult } from '../utils/exec.ts';
2323
// Type-only import; erased at runtime. ref-frame.ts imports SessionState from
2424
// here, so this back-edge must stay type-only to avoid a runtime cycle.
@@ -239,9 +239,9 @@ export type InteractionSurfaceEntry = {
239239

240240
export type PostGestureStabilization = {
241241
action: string;
242-
/** The gesture's own positionals (e.g. scroll direction) — wording input for
243-
* the #1600 no-effect warning; never re-dispatched. */
244-
positionals?: string[];
242+
/** The gesture's own positionals — wording input for the #1600 no-effect
243+
* warning; never re-dispatched. Always set by the only writer. */
244+
positionals: string[];
245245
markedAt: number;
246246
/**
247247
* Pre-gesture interaction-surface signature, captured from the session's
@@ -255,17 +255,13 @@ export type PostGestureStabilization = {
255255
*/
256256
baselineSignature?: InteractionSurfaceEntry[];
257257
/**
258-
* iOS snapshot capture-plan backend (`SnapshotQualityVerdict['backend']`:
259-
* `'tree' | 'queries' | 'private-ax'`) that produced `baselineSignature` —
260-
* NOT the platform `SnapshotBackend` (`xctest`/`android`/...): this is the
261-
* iOS runner's own capture-strategy choice among its plan's ordered chain
262-
* (see `SnapshotQualityVerdict` in `@agent-device/kernel/snapshot`).
263-
* Backends do not return comparable views of one screen — on the same iOS
264-
* screen private AX returns the scrolled-away content the tree backend
265-
* prunes — so a quiet capture from a different backend can only be
266-
* re-baselined against, never concluded from (#1569).
258+
* Capture strategy that produced `baselineSignature`. Two strategies do not
259+
* return comparable views of one screen — on the same iOS screen private AX
260+
* returns the scrolled-away content the tree strategy prunes — so a quiet
261+
* capture from a different one can only be re-baselined against, never
262+
* concluded from (#1569).
267263
*/
268-
baselineBackend?: SnapshotQualityVerdict['backend'];
264+
baselineBackend?: SnapshotCaptureBackend;
269265
};
270266

271267
export type PendingInteractionOutcome = {

0 commit comments

Comments
 (0)