Skip to content

Commit 2f6305a

Browse files
thymikeeclaude
andcommitted
fix(interaction): end in-flight admission reads at the request deadline
Reads during admission carry a signal that also aborts at the request deadline, and an aborted read refuses with the typed reason. The runtime sleep ends on abort with or without an installed clock. Kernel owns the request-deadline reason constant and predicate; host-kit dispatches on them. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent b2cb280 commit 2f6305a

6 files changed

Lines changed: 130 additions & 58 deletions

File tree

‎packages/command-runtime/src/commands/interaction/runtime/moving-target-gate.ts‎

Lines changed: 20 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -220,25 +220,19 @@ export type MovingTargetObservation = MovingTargetMeasurement & {
220220

221221
/** Whether a look produced a position of its own, or nothing to compare against. */
222222
type MovingTargetMeasurement =
223-
/** The position this observation's own capture reported for the target, on that capture's surface. */
224-
| MovingTargetMeasured
223+
/**
224+
* The position this observation's own capture reported for the target, and on which surface. The
225+
* surface rides along because a rect is only comparable to one measured on the same presentation
226+
* (#2438).
227+
*/
228+
| { measured: true; rect: Rect; surfaceBundleId: string | undefined }
225229
/**
226230
* No position of its own. Two of these would "agree" trivially — rest certified by a
227231
* non-measurement, the one outcome the check must never produce — so the first of them ends the
228232
* recheck, and a refusal reports no `movedToRect` rather than a stale one.
229233
*/
230234
| { measured: false; rect: undefined };
231235

232-
/**
233-
* A look that measured the target: where it put it, and on which surface. The surface rides along
234-
* because a rect is only comparable to one measured on the same presentation (#2438).
235-
*/
236-
type MovingTargetMeasured = {
237-
measured: true;
238-
rect: Rect;
239-
surfaceBundleId: string | undefined;
240-
};
241-
242236
/**
243237
* One observation of the same target, asked as the original question rather than a narrower one.
244238
*
@@ -310,34 +304,20 @@ function resolvedRect(resolved: ResolvedInteractionTarget): Rect | undefined {
310304
return 'node' in resolved ? resolved.node?.rect : undefined;
311305
}
312306

313-
/**
314-
* The hint published beside every `target_still_moving` refusal, owned by the refusal's module so
315-
* the reason cannot be published without its recovery.
316-
*
317-
* A selector re-resolves against a fresh capture and can be retried as-is. An `@ref` cannot survive
318-
* the wait: the capture a `wait` takes retires the ref frame (ADR 0014), which is the same reason
319-
* the off-screen guard sends its `@ref` refusals to a selector. The selector is quoted for the
320-
* caller's shell the way the daemon's other recovery hints quote values (`shellQuoteIfNeeded`), so
321-
* a label carrying an apostrophe cannot turn the suggested command into a copy-paste failure.
322-
*/
323-
function targetStillMovingHint(params: { selector: string | undefined }): string {
324-
const reobserve = params.selector
325-
? `Run wait ${shellQuoteIfNeeded(params.selector)} and retry with the same selector`
326-
: 'Run snapshot -i and retry with a selector (text=/id=) rather than this @ref — re-observing retires the ref frame';
327-
return (
328-
'The target had no confirmed resting position when the transition window after the previous action ran ' +
329-
`out, so nothing was dispatched. ${reobserve}; or pass --settle to have the action itself wait for the ` +
330-
'UI to go quiet.'
331-
);
332-
}
333-
334307
/**
335308
* The refusal, keyed on the reason the whole interaction surface shares and raised beside the guard
336309
* that owns it. `rect` is the position the caller's own resolution produced and `movedToRect` where
337310
* the last re-observation found the target — the pair that says which way the surface is going.
338311
* `movedToRect` is the one optional member: a re-observation that measured nothing (the ref kept its
339312
* authorized frame node) has no position to name, and an absent value is the honest report rather
340313
* than a stale one.
314+
*
315+
* The hint is owned here so the reason cannot be published without its recovery. A selector
316+
* re-resolves against a fresh capture and can be retried as-is. An `@ref` cannot survive the wait:
317+
* the capture a `wait` takes retires the ref frame (ADR 0014), which is the same reason the
318+
* off-screen guard sends its `@ref` refusals to a selector. The selector is quoted for the caller's
319+
* shell (`shellQuoteIfNeeded`), so a label carrying an apostrophe cannot turn the suggested command
320+
* into a copy-paste failure.
341321
*/
342322
export function motionRefusal(
343323
resolved: Exclude<ResolvedInteractionTarget, { kind: 'point' }>,
@@ -346,6 +326,9 @@ export function motionRefusal(
346326
): Error {
347327
const selector = resolved.target.kind === 'selector' ? resolved.target.selector : undefined;
348328
const ref = resolved.target.kind === 'ref' ? resolved.target.ref : undefined;
329+
const reobserve = selector
330+
? `Run wait ${shellQuoteIfNeeded(selector)} and retry with the same selector`
331+
: 'Run snapshot -i and retry with a selector (text=/id=) rather than this @ref — re-observing retires the ref frame';
349332
return discloseDispatch(
350333
new AppError(
351334
'COMMAND_FAILED',
@@ -358,7 +341,10 @@ export function motionRefusal(
358341
...(resolved.node?.rect ? { rect: resolved.node.rect } : {}),
359342
...(movedToRect ? { movedToRect } : {}),
360343
waitedMs,
361-
hint: targetStillMovingHint({ selector }),
344+
hint:
345+
'The target had no confirmed resting position when the transition window after the previous action ran ' +
346+
`out, so nothing was dispatched. ${reobserve}; or pass --settle to have the action itself wait for the ` +
347+
'UI to go quiet.',
362348
},
363349
),
364350
'no',

‎packages/command-runtime/src/commands/interaction/runtime/pre-dispatch-admission.test.ts‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,10 @@ function createAdmissionDevice(params: {
5050
baselineAgeMs?: number;
5151
baselineTree?: SnapshotState;
5252
captureMs?: number;
53-
onSleep?: () => void;
54-
onCapture?: (capture: number) => void;
53+
/** Runs inside each scenario-clock sleep; a returned promise holds the sleep open. */
54+
onSleep?: () => void | Promise<void>;
55+
/** Runs inside each capture with the signal it received; a returned promise holds it open. */
56+
onCapture?: (capture: number, signal: AbortSignal | undefined) => void | Promise<void>;
5557
}) {
5658
let nowMs = 0;
5759
const sleeps: number[] = [];
@@ -62,16 +64,16 @@ function createAdmissionDevice(params: {
6264
sleep: async (ms: number) => {
6365
sleeps.push(ms);
6466
nowMs += ms;
65-
params.onSleep?.();
67+
await params.onSleep?.();
6668
},
6769
};
6870
const backend: AgentDeviceBackend = {
6971
platform: params.platform,
70-
captureSnapshot: async () => {
72+
captureSnapshot: async (context) => {
7173
captureStarts.push(nowMs);
7274
nowMs += params.captureMs ?? 0;
7375
const snapshot = params.trees[Math.min(captureStarts.length - 1, params.trees.length - 1)]!;
74-
params.onCapture?.(captureStarts.length);
76+
await params.onCapture?.(captureStarts.length, context.signal);
7577
return { snapshot };
7678
},
7779
tap: async (_context, point) => {
@@ -194,6 +196,55 @@ test('a cancellation during a look sends no input, even when the look shows rest
194196
assert.deepEqual(harness.taps, []);
195197
});
196198

199+
test('a cancellation ends a scenario-clock sleep that would not return on its own', async () => {
200+
const controller = new AbortController();
201+
const harness = createAdmissionDevice({
202+
platform: 'ios',
203+
trees: [slideTree(240), slideTree(10)],
204+
baselineAgeMs: 100,
205+
onSleep: () => {
206+
setTimeout(() => controller.abort(), 0);
207+
return new Promise<void>(() => {});
208+
},
209+
});
210+
211+
await assert.rejects(
212+
() =>
213+
harness.device.interactions.press(selector('label="Slide target"'), {
214+
session: 'default',
215+
signal: controller.signal,
216+
}),
217+
assertCanceledBeforeDispatch,
218+
);
219+
assert.deepEqual(harness.taps, []);
220+
});
221+
222+
test('the request deadline interrupts a look still in flight and sends no input', async () => {
223+
const harness = createAdmissionDevice({
224+
platform: 'android',
225+
trees: [slideTree(240), slideTree(10)],
226+
baselineAgeMs: 0,
227+
// The first look never answers on its own; only an abort of the signal it carries ends it.
228+
onCapture: (capture, signal) =>
229+
capture === 2
230+
? new Promise<void>((_resolve, reject) => {
231+
signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
232+
})
233+
: undefined,
234+
});
235+
236+
await assert.rejects(
237+
() =>
238+
harness.device.interactions.press(selector('label="Slide target"'), {
239+
session: 'default',
240+
deadlineAtMs: Date.now() + 30,
241+
}),
242+
assertDeadlineBeforeDispatch,
243+
);
244+
assert.equal(harness.captureStarts.length, 2);
245+
assert.deepEqual(harness.taps, []);
246+
});
247+
197248
test('the request deadline ends a motion wait that the window would continue', async () => {
198249
const deadlineAtMs = Date.now() + 1_000;
199250
const harness = createAdmissionDevice({

‎packages/command-runtime/src/commands/interaction/runtime/pre-dispatch-admission.ts‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,23 @@ type AdmissionBudget = Readonly<{
6262
signal: AbortSignal | undefined;
6363
deadlineMs: number;
6464
clock: ObservationClock;
65-
/** Runs one awaited read with the budget checked before and after it. */
66-
read<T>(read: () => Promise<T>): Promise<T>;
65+
/**
66+
* Runs one awaited read with the budget checked before and after it. The read receives a signal
67+
* that also aborts at the request deadline, so a read in flight ends there and refuses.
68+
*/
69+
read<T>(read: (signal: AbortSignal | undefined) => Promise<T>): Promise<T>;
6770
}>;
6871

6972
function requestBudget(runtime: AgentDeviceRuntime, options: CommandContext): AdmissionBudget {
7073
const signal = options.signal ?? runtime.signal;
74+
const deadlineSignal =
75+
options.deadlineAtMs === undefined
76+
? undefined
77+
: AbortSignal.timeout(Math.max(0, options.deadlineAtMs - Date.now()));
78+
const readSignal =
79+
signal && deadlineSignal
80+
? AbortSignal.any([signal, deadlineSignal])
81+
: (signal ?? deadlineSignal);
7182
const budget: AdmissionBudget = {
7283
signal,
7384
deadlineMs: now(runtime) + ((options.deadlineAtMs ?? Infinity) - Date.now()),
@@ -80,8 +91,14 @@ function requestBudget(runtime: AgentDeviceRuntime, options: CommandContext): Ad
8091
},
8192
read: async (read) => {
8293
assertWithinBudget(budget);
83-
const value = await read();
84-
assertWithinBudget(budget);
94+
let value;
95+
try {
96+
value = await read(readSignal);
97+
} catch (error) {
98+
if (readSignal?.aborted) assertWithinBudget(budget, deadlineSignal?.aborted || undefined);
99+
throw error;
100+
}
101+
assertWithinBudget(budget, deadlineSignal?.aborted || undefined);
85102
return value;
86103
},
87104
};
@@ -126,7 +143,8 @@ async function awaitRest(
126143
MovingTargetObservation,
127144
Exclude<ReturnType<typeof judgeMotionLook>, { kind: 'wait' }>
128145
>({
129-
capture: () => budget.read(() => reObserveTarget(runtime, options, params)),
146+
capture: () =>
147+
budget.read((signal) => reObserveTarget(runtime, { ...options, signal }, params)),
130148
verdict: (look, previous) => {
131149
const verdict = judgeMotionLook(look, previous, restingSinceMs, wait.policy);
132150
if (verdict.kind !== 'wait') return { kind: 'done', result: verdict };

‎packages/command-runtime/src/commands/runtime-common.ts‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,21 +17,28 @@ export function now(runtime: Pick<AgentDeviceRuntime, 'clock'>): number {
1717
return runtime.clock?.now() ?? Date.now();
1818
}
1919

20-
/** Sleeps on the runtime clock; without one, a timer that an abort of `signal` ends early. */
20+
/** Sleeps on the runtime clock, or a timer without one; an abort of `signal` ends either early. */
2121
export async function sleep(
2222
runtime: Pick<AgentDeviceRuntime, 'clock'>,
2323
ms: number,
2424
signal?: AbortSignal,
2525
): Promise<void> {
26-
if (runtime.clock) return await runtime.clock.sleep(ms);
2726
if (signal?.aborted) return;
28-
await new Promise<void>((resolve) => {
29-
const finish = () => {
30-
clearTimeout(timer);
31-
signal?.removeEventListener('abort', finish);
32-
resolve();
33-
};
34-
const timer = setTimeout(finish, ms);
35-
signal?.addEventListener('abort', finish, { once: true });
27+
let timer: ReturnType<typeof setTimeout> | undefined;
28+
let onAbort = () => {};
29+
const aborted = new Promise<void>((resolve) => {
30+
onAbort = resolve;
31+
signal?.addEventListener('abort', onAbort, { once: true });
3632
});
33+
const slept = runtime.clock
34+
? runtime.clock.sleep(ms)
35+
: new Promise<void>((resolve) => {
36+
timer = setTimeout(resolve, ms);
37+
});
38+
try {
39+
await Promise.race([slept, aborted]);
40+
} finally {
41+
clearTimeout(timer);
42+
signal?.removeEventListener('abort', onAbort);
43+
}
3744
}

‎packages/host-kit/src/internal/request-cancel.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ import {
44
createRequestDeadlineError,
55
isRequestCanceledDetails,
66
isRequestCanceledError,
7+
isRequestDeadlineDetails,
8+
REQUEST_DEADLINE_REASON,
79
} from '@agent-device/kernel/errors';
810
import type { DaemonResponse } from '@agent-device/kernel/contracts';
911
import { runtimeSlot } from '../runtime-slots.ts';
@@ -181,7 +183,7 @@ function deadlineFailure(error: unknown, timeoutMs: number, requestId: string):
181183
return createRequestDeadlineError(
182184
{
183185
...prior,
184-
...(typeof prior.reason === 'string' && prior.reason !== 'daemon_request_timeout'
186+
...(typeof prior.reason === 'string' && !isRequestDeadlineDetails(prior)
185187
? { causeReason: prior.reason }
186188
: {}),
187189
timeoutMs,
@@ -205,10 +207,10 @@ function projectDeadlineResponse(result: DaemonResponse, timeoutMs: number): Dae
205207
: {}),
206208
details: {
207209
...result.error.details,
208-
...(typeof priorReason === 'string' && priorReason !== 'daemon_request_timeout'
210+
...(typeof priorReason === 'string' && !isRequestDeadlineDetails(result.error.details)
209211
? { causeReason: priorReason }
210212
: {}),
211-
reason: 'daemon_request_timeout',
213+
reason: REQUEST_DEADLINE_REASON,
212214
timeoutMs,
213215
},
214216
},

‎packages/kernel/src/errors.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -404,6 +404,14 @@ export function createRequestCanceledError(details?: AppErrorDetails, cause?: un
404404
);
405405
}
406406

407+
/** `details.reason` of a request whose deadline passed before its work could finish. */
408+
export const REQUEST_DEADLINE_REASON = 'daemon_request_timeout';
409+
410+
/** Whether `details` carry the {@link REQUEST_DEADLINE_REASON}, for a caller holding details. */
411+
export function isRequestDeadlineDetails(details: AppErrorDetails | undefined): boolean {
412+
return details?.reason === REQUEST_DEADLINE_REASON;
413+
}
414+
407415
/**
408416
* The error of a request whose deadline passed before its work could finish. `details` may add
409417
* evidence (`timeoutMs`, `requestId`, a cause reason) or override the hint; the reason is fixed.
@@ -415,7 +423,7 @@ export function createRequestDeadlineError(details?: AppErrorDetails, cause?: un
415423
{
416424
hint: 'Check completed steps and the current device state before retrying the timed-out operation.',
417425
...details,
418-
reason: 'daemon_request_timeout',
426+
reason: REQUEST_DEADLINE_REASON,
419427
},
420428
cause,
421429
);

0 commit comments

Comments
 (0)