Skip to content

Commit c19112a

Browse files
committed
refactor(interaction): keep readiness comments to their constraints
1 parent 5c2bddb commit c19112a

18 files changed

Lines changed: 62 additions & 87 deletions

‎packages/capture-kit/src/observe-until.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@ import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
44

55
/**
66
* The one observation loop: capture until a verdict accepts, on a schedule, under a budget that is
7-
* enforced by cancellation. Owns exactly what every loop in this codebase used to re-implement —
8-
* cadence, the deadline, abort-and-join of an in-flight capture, which capture errors are ridden
9-
* out, and the per-poll timeline. Owns nothing about WHAT is observed: the verdict is the caller's,
10-
* and so is the equality rule behind it (digest, signature, pixel).
7+
* enforced by cancellation. Owns cadence, the deadline, abort-and-join of an in-flight capture,
8+
* which capture errors are ridden out, and the per-poll timeline. Owns nothing about WHAT is
9+
* observed: the verdict is the caller's, and so is the equality rule behind it (digest, signature,
10+
* pixel).
1111
*/
1212

1313
export type ObservationSchedule = Readonly<{
@@ -23,8 +23,8 @@ export type ObservationSchedule = Readonly<{
2323
minPolls?: number;
2424
/**
2525
* `'start'` (default) bounds every capture, the first included. `'first-capture'` leaves the first
26-
* capture unbounded and spends the budget only on retries, so a caller whose first attempt is the
27-
* pre-existing one-shot behaviour pays nothing on its success path.
26+
* capture unbounded and spends the budget only on retries, so a caller whose first attempt is a
27+
* one-shot pays nothing on its success path.
2828
*/
2929
budgetFrom?: 'start' | 'first-capture';
3030
}>;

‎packages/contracts/src/client-gesture.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,8 @@ export type SettleCommandOptions = {
3636
};
3737

3838
/**
39-
* Operator-only readiness budget (#1656 promotedTarget row): how long a tap-shaped interaction may
40-
* poll for a target that does not exist yet, capped at the row's maxTimeoutMs. Never model- or
41-
* CLI-writable; omitted means the one-attempt resolution path unchanged from before this option
42-
* existed.
39+
* How long a tap-shaped interaction may poll for a target that does not exist yet, capped at the
40+
* promotedTarget row's maxTimeoutMs. Never model- or CLI-writable; omitted means one attempt.
4341
*/
4442
export type ReadinessBudgetOptions = {
4543
readinessTimeoutMs?: number;

‎packages/contracts/src/command-flags.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,8 @@ export type CommandFlags = Omit<CliFlags, DaemonExcludedCliFlag> & {
3636
maestro?: MaestroRuntimeFlags;
3737
postGestureStabilization?: boolean;
3838
/**
39-
* Operator-only readiness budget for press/click/longpress (#1656 promotedTarget row), capped at
40-
* its maxTimeoutMs. No CliFlags counterpart: never CLI- or model-writable, so it is a daemon-side
41-
* addition here rather than an `Omit<CliFlags, ...>` member.
39+
* Readiness budget for press/click/longpress, capped at the promotedTarget row's maxTimeoutMs.
40+
* No CliFlags counterpart: never CLI- or model-writable.
4241
*/
4342
readinessTimeoutMs?: number;
4443
snapshotIncludeHiddenContentHints?: boolean;

‎packages/contracts/src/interaction-guarantees.ts‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -175,10 +175,7 @@ const TAP_OUTCOME_NOT_OBSERVED_GAP: GuaranteeEnforcement = {
175175
// dispatch ONE fused XCTest runner request (`command: 'tap'` with a selectorKey/selectorValue) built
176176
// in packages/platform-apple/src/interactions.ts#tapElementSelector — not the separate
177177
// packages/maestro/ flow-script engine, which drives standalone `.yaml` Maestro flows and never
178-
// participates in an ordinary daemon click. Verified by reading the dispatch call graph
179-
// (interaction-touch-direct-ios.ts -> BoundTouchExecutor.tapElementSelector ->
180-
// platform-apple/src/interactions.ts) before writing this cell (AGENTS.md: verify each claim
181-
// against the native implementation).
178+
// participates in an ordinary daemon click.
182179
const DIRECT_IOS_SINGLE_QUERY_READINESS: GuaranteeEnforcement = {
183180
kind: 'waived',
184181
reason:
@@ -288,9 +285,8 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
288285
via: 'src/commands/interaction/runtime/selector-action-resolution.ts#resolveActionSelector',
289286
},
290287
// press/click/longpress poll the promotedTarget row's readiness budget only when the caller
291-
// (operator-only readinessTimeoutMs, never model- or CLI-writable) supplies one, capped at the
292-
// row's maxTimeoutMs; fill/hover resolve against the resolvedTarget row, which declares no
293-
// poll budget at all (#1656).
288+
// supplies readinessTimeoutMs (never model- or CLI-writable), capped at the row's
289+
// maxTimeoutMs; fill/hover resolve against the resolvedTarget row, which declares no poll budget.
294290
targetReadiness: {
295291
kind: 'runtime',
296292
via: 'src/commands/interaction/runtime/selector-readiness.ts#pollForSelectorReadiness',
@@ -388,7 +384,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
388384
targetReadiness: {
389385
kind: 'inapplicable',
390386
reason:
391-
'Both endpoints resolve through the resolvedTarget row (#1656), which declares no poll budget; the readiness budget this feature adds is scoped to the promotedTarget row only.',
387+
'Both endpoints resolve through the resolvedTarget row, which declares no poll budget; only the promotedTarget row carries a readiness budget.',
392388
},
393389
outcomeObservation: {
394390
kind: 'waived',

‎packages/contracts/src/request-envelope.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,9 @@ export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> &
3939
holdMs?: number;
4040
jitterPx?: number;
4141
/**
42-
* Operator-only: the readiness budget a tap-shaped interaction (press/click/longpress) may
43-
* spend polling for a target that does not exist yet, capped at the promotedTarget row's
44-
* maxTimeoutMs. Never model- or CLI-writable; absent means the one-attempt resolution path.
42+
* The readiness budget a tap-shaped interaction (press/click/longpress) may spend polling for a
43+
* target that does not exist yet, capped at the promotedTarget row's maxTimeoutMs. Never model-
44+
* or CLI-writable; absent means one attempt.
4545
*/
4646
readinessTimeoutMs?: number;
4747
pixels?: number;

‎packages/replay-port/src/daemon-port/session-replay-action-runtime.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -216,11 +216,8 @@ function readResponseTiming(data: unknown): Record<string, unknown> | undefined
216216
}
217217

218218
/**
219-
* A press/click/longpress step replays against a UI that may still be a render or two behind where
220-
* it was recorded — the same render race #1656's operator-only readiness budget absorbs live. A
221-
* replayed step carries no recorded budget of its own (there is no CLI flag for it), so every such
222-
* step defaults to one here unless the merged flags already name one — future-proofing against a
223-
* flag source this PR does not add, rather than a live possibility today.
219+
* A replayed press/click/longpress step carries no readiness budget of its own; replay supplies one
220+
* so a step recorded against a loading screen can land.
224221
*/
225222
const REPLAY_DEFAULT_READINESS_TIMEOUT_MS = 2_000;
226223
const READINESS_BUDGETED_REPLAY_COMMANDS: ReadonlySet<string> = new Set([

‎packages/selectors/src/selector-pipeline-policy.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ export type WaitPollBudget = {
7878
/**
7979
* `promotedTarget`: the row states only a ceiling and a cadence, never a default — a miss with no
8080
* caller-supplied budget takes the one-attempt path instead of polling (`resolveSelectorInteractionTarget`).
81-
* When the caller does supply one (an operator-only `readinessTimeoutMs`, never model- or
81+
* When the caller does supply one (`readinessTimeoutMs`, never model- or
8282
* CLI-writable), it is capped at `maxTimeoutMs` before it bounds the readiness loop.
8383
*/
8484
export type ReadinessPollBudget = {
@@ -132,12 +132,11 @@ const WAIT_POLL_BUDGET: WaitPollBudget = { defaultTimeoutMs: 10_000, intervalMs:
132132
export const SELECTOR_PIPELINE_POLICIES = {
133133
/**
134134
* `click`/`press`/`longpress`: the tap lands on the actionable owner of the
135-
* match. When the caller supplies an operator-only readiness budget, polls for the target to
135+
* match. When the caller supplies a readiness budget, polls for the target to
136136
* appear and become resolvable (a rect), capped at this row's `maxTimeoutMs`, before refusing —
137137
* resolution only; occlusion, off-screen, and promotion still run once, against the winning
138-
* capture, after the loop ends (#1656). A miss with no caller-supplied budget takes the
139-
* one-attempt path instead (`resolveSelectorInteractionTarget`), unchanged from before this
140-
* budget existed.
138+
* capture, after the loop ends. A miss with no caller-supplied budget takes the one-attempt path
139+
* (`resolveSelectorInteractionTarget`).
141140
*/
142141
promotedTarget: {
143142
resolution: SELECTOR_RESOLUTION_POLICIES.act,

‎src/__tests__/client-interactions-readiness.test.ts‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,9 @@ import { test } from 'vitest';
33
import { createAgentDeviceClient } from '../agent-device-client.ts';
44
import { createTransport } from './client-transport-fixture.ts';
55

6-
// #1656 follow-up: the operator-only readiness budget rides the same common-input seam as every
7-
// other option (`commonToClientOptions`), so it must reach `req.flags` for press/click/longpress
8-
// exactly like `button`/`durationMs` do (see client.test.ts). Never CLI- or model-writable — this
9-
// is the SDK-only route the option exists for. Split out of client.test.ts, which is already over
10-
// the test-file-size-ratchet tripwire and may not grow (docs/agents/testing.md).
6+
// The readiness budget rides the common-input seam (`commonToClientOptions`), so it must reach
7+
// `req.flags` for press/click/longpress exactly like `button`/`durationMs` do. It is never CLI- or
8+
// model-writable; the SDK client option is its route.
119
test('readinessTimeoutMs on press/click/longpress reaches the request flags', async () => {
1210
const setup = createTransport(async () => ({ ok: true, data: {} }));
1311
const client = createAgentDeviceClient(setup.config, { transport: setup.transport });

‎src/commands/common-input-fields.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ export type CommonCommandInput = Pick<
3232
/** `--no-record`: common to every recordable command (see `commonInputFromFlags`). */
3333
noRecord?: boolean;
3434
/**
35-
* Operator-only readiness budget for a tap-shaped interaction (press/click/longpress), capped at
36-
* the promotedTarget row's maxTimeoutMs. No `flagIn`/`flagKey`: it never rides a CLI flag or the
35+
* Readiness budget for a tap-shaped interaction (press/click/longpress), capped at the
36+
* promotedTarget row's maxTimeoutMs. No `flagIn`/`flagKey`: it never rides a CLI flag or the
3737
* client "selection" projection, only the CLI/Node structured-input and SDK client option seams.
3838
*/
3939
readinessTimeoutMs?: number;
@@ -227,9 +227,8 @@ const COMMON_INPUT_FIELDS = {
227227
"Operator-only: how long press/click/longpress may poll for a target that does not exist yet, in milliseconds. Capped at the promotedTarget row's maxTimeoutMs; omitted takes the one-attempt resolution path.",
228228
},
229229
read: (record) => readOptionalInteger(record, 'readinessTimeoutMs', { min: 1 }),
230-
// Not accepted as a tool argument, and no CLI flag exists for it (deliberately: agents mostly
231-
// miss on a wrong selector, where fast feedback matters more than absorbing a render race) — an
232-
// operator supplies it directly through the CLI/Node structured input or the SDK client option.
230+
// No CLI flag: agents mostly miss on a wrong selector, where fast feedback beats absorbing a
231+
// render race.
233232
audience: operatorAudience({
234233
operatorPath:
235234
'Pass readinessTimeoutMs directly as CLI/Node.js command input; it is not exposed to model-facing tools.',

‎src/commands/interaction/runtime/gestures.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,8 @@ export type LongPressCommandOptions = CommandContext & {
9696
target: InteractionTarget;
9797
durationMs?: number;
9898
/**
99-
* Operator-only readiness budget (#1656 promotedTarget row): polls for the target to exist and
100-
* become actionable, capped at the row's maxTimeoutMs. Absent takes the one-attempt path.
99+
* Polls for the target to exist and become actionable, capped at the promotedTarget row's
100+
* maxTimeoutMs. Absent takes one attempt.
101101
*/
102102
readinessTimeoutMs?: number;
103103
/** ADR 0012 step 4: replay-only post-resolution guard; see resolution.ts. */

0 commit comments

Comments
 (0)