Skip to content

Commit bd0aff2

Browse files
committed
refactor(replay): read the readiness-budgeted commands from their declaration
Replay hardcoded press/click/longpress as the commands that get a default readinessTimeoutMs. Nothing declared that set per command: readinessTimeoutMs is a common input field every command reads. press, click and longpress now declare `targetReadiness: 'budgeted'` in the command registry. Replay reads it through commandAcceptsReadinessBudget. resolveCommandTimeoutPolicy attaches the trait to the resolved timeout policy, and resolveCommandRequestTimeoutMs widens the envelope by the readiness budget only when that trait is present. Before, it widened for any command whose flags carried readinessTimeoutMs; only these three commands forward the field to request flags, so no request changes. A test asserts that the commands with the trait equal the commands the `runtime` targetReadiness guarantee cells in interaction-guarantees.ts apply to. The replay default test iterates the declared set.
1 parent 3b3489d commit bd0aff2

6 files changed

Lines changed: 74 additions & 12 deletions

File tree

‎packages/command-registry/src/registry.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1301,6 +1301,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
13011301
},
13021302
timeoutPolicy: postActionObservationTimeoutPolicy('click', PRESERVE_DAEMON_TIMEOUT_POLICY),
13031303
postActionObservation: postActionObservation('click'),
1304+
targetReadiness: 'budgeted',
13041305
responseDataTransform: TOUCH_INTERACTION_RESPONSE_DATA_TRANSFORM,
13051306
batchable: true,
13061307
platformExecution: { kind: 'device-runtime', uses: clickRuntimeUses },
@@ -1330,6 +1331,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
13301331
envelopeMs: 210_000,
13311332
},
13321333
postActionObservation: postActionObservation('longpress'),
1334+
targetReadiness: 'budgeted',
13331335
batchable: true,
13341336
platformExecution: { kind: 'device-runtime', uses: longPressRuntimeUses },
13351337
},
@@ -1358,6 +1360,7 @@ export const RAW_COMMAND_DESCRIPTORS = [
13581360
frameworkTier: 'core',
13591361
timeoutPolicy: postActionObservationTimeoutPolicy('press', PRESERVE_DAEMON_TIMEOUT_POLICY),
13601362
postActionObservation: postActionObservation('press'),
1363+
targetReadiness: 'budgeted',
13611364
responseDataTransform: TOUCH_INTERACTION_RESPONSE_DATA_TRANSFORM,
13621365
batchable: true,
13631366
platformExecution: { kind: 'device-runtime', uses: pressRuntimeUses },
@@ -1972,7 +1975,12 @@ function readCatalogKey(descriptor: {
19721975
}
19731976

19741977
const TIMEOUT_POLICY_BY_COMMAND: ReadonlyMap<string, CommandTimeoutPolicy> = new Map(
1975-
commandDescriptors.map((descriptor) => [descriptor.name, descriptor.timeoutPolicy]),
1978+
Array.from(COMMAND_DESCRIPTOR_BY_NAME.values(), (descriptor) => [
1979+
descriptor.name,
1980+
descriptor.targetReadiness
1981+
? { ...descriptor.timeoutPolicy, targetReadiness: descriptor.targetReadiness }
1982+
: descriptor.timeoutPolicy,
1983+
]),
19761984
);
19771985

19781986
const DEVICE_CLAIM_POLICY_BY_COMMAND: ReadonlyMap<string, DeviceClaimPolicy> = new Map(
@@ -1999,6 +2007,11 @@ export function commandSupportsSettleObservation(command: string | undefined): b
19992007
return resolveCommandPostActionObservationSupport(command) !== undefined;
20002008
}
20012009

2010+
export function commandAcceptsReadinessBudget(command: string | undefined): boolean {
2011+
if (command === undefined) return false;
2012+
return COMMAND_DESCRIPTOR_BY_NAME.get(command)?.targetReadiness === 'budgeted';
2013+
}
2014+
20022015
export function commandSupportsVerifyEvidence(command: string | undefined): boolean {
20032016
return resolveCommandPostActionObservationSupport(command) === 'settle-and-verify';
20042017
}

‎packages/command-registry/src/timeout-policy.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,14 +83,18 @@ export function resolveCommandRequestTimeoutMs(
8383
resolvePositionalBudgetTimeoutMs(boundedPolicy, input.positionals ?? []) ??
8484
resolveFlagBudgetTimeoutMs(boundedPolicy, input.flags) ??
8585
boundedPolicy.envelopeMs;
86-
return envelopeMs + readinessBudgetMs(input.flags);
86+
return envelopeMs + readinessBudgetMs(policy, input.flags);
8787
}
8888

8989
/**
9090
* A readiness budget is target-poll time spent before the action itself, so it extends whatever
9191
* envelope the command otherwise has; the daemon's own poll must never outlive the client's clock.
9292
*/
93-
function readinessBudgetMs(flags: RequestTimeoutInput['flags']): number {
93+
function readinessBudgetMs(
94+
policy: CommandTimeoutPolicy,
95+
flags: RequestTimeoutInput['flags'],
96+
): number {
97+
if (policy.targetReadiness !== 'budgeted') return 0;
9498
const budgetMs = flags?.readinessTimeoutMs;
9599
return typeof budgetMs === 'number' && Number.isFinite(budgetMs) && budgetMs > 0 ? budgetMs : 0;
96100
}

‎packages/command-registry/src/types.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,8 +75,21 @@ export type CommandTimeoutPolicy = {
7575
budget: CommandTimeoutBudget;
7676
envelopeMs: number | 'unbounded';
7777
onTimeout: 'preserve-daemon' | 'reset-daemon';
78+
/**
79+
* The descriptor's {@link CommandTargetReadiness} trait, attached by `resolveCommandTimeoutPolicy`
80+
* so the envelope can widen by the readiness budget. Descriptors declare it as `targetReadiness`,
81+
* never on their `timeoutPolicy`.
82+
*/
83+
targetReadiness?: CommandTargetReadiness;
7884
};
7985

86+
/**
87+
* `budgeted`: the command's target resolution may poll for a target that does not exist yet, under
88+
* a caller-supplied `readinessTimeoutMs`. Must match the commands the `targetReadiness` interaction
89+
* guarantee cells mark `runtime`.
90+
*/
91+
export type CommandTargetReadiness = 'budgeted';
92+
8093
/**
8194
* #1320 "Command descriptor policy": what a command may do with the host-global
8295
* device claim store. REQUIRED on every descriptor (no default), and read by the
@@ -199,6 +212,9 @@ export type TargetIdentityVerification = 'pre-dispatch' | 'post-resolution';
199212
* commands that support `--settle`/`--verify`; consumed by
200213
* command surfaces and timeout policy instead of repeated
201214
* command-name lists.
215+
* - `targetReadiness` — optional; the commands whose target resolution accepts a
216+
* `readinessTimeoutMs` budget. Read by replay (which supplies a
217+
* default budget) and by the request envelope (which widens by it).
202218
* - `responseDataTransform` — optional public response data shaping rules for
203219
* command-owned fields in daemon responses. This keeps
204220
* response shaping on the same descriptor surface as other
@@ -221,6 +237,7 @@ type CommandDescriptorBase = {
221237
*/
222238
deviceClaimPolicy: DeviceClaimPolicy;
223239
postActionObservation?: PostActionObservationSupport;
240+
targetReadiness?: CommandTargetReadiness;
224241
responseDataTransform?: CommandResponseDataTransform;
225242
catalog: CommandCatalogFacet;
226243
/** Required iff `catalog.group === 'public'`; see {@link CommandFrameworkTier}. */

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

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import type {
66
ReplayInvoke,
77
} from '@agent-device/replay-port/command-types';
88
import { mergeParentFlags } from '@agent-device/command-registry/batch';
9+
import { commandAcceptsReadinessBudget } from '@agent-device/command-registry/registry';
910
import { AppError, normalizeError } from '@agent-device/kernel/errors';
1011
import {
1112
gesturePayloadFromPositionals,
@@ -216,23 +217,18 @@ function readResponseTiming(data: unknown): Record<string, unknown> | undefined
216217
}
217218

218219
/**
219-
* A replayed press/click/longpress step carries no readiness budget of its own; replay supplies one
220+
* A replayed step of a readiness-budgeted command carries no budget of its own; replay supplies one
220221
* so a step recorded against a loading screen can land.
221222
*/
222223
const REPLAY_DEFAULT_READINESS_TIMEOUT_MS = 2_000;
223-
const READINESS_BUDGETED_REPLAY_COMMANDS: ReadonlySet<string> = new Set([
224-
'press',
225-
'click',
226-
'longpress',
227-
]);
228224

229225
function buildReplayActionFlags(
230226
parentFlags: CommandFlags | undefined,
231227
actionFlags: SessionAction['flags'] | undefined,
232228
command: string,
233229
): CommandFlags {
234230
const flags = mergeParentFlags(parentFlags, { ...(actionFlags ?? {}) });
235-
if (READINESS_BUDGETED_REPLAY_COMMANDS.has(command) && flags.readinessTimeoutMs === undefined) {
231+
if (commandAcceptsReadinessBudget(command) && flags.readinessTimeoutMs === undefined) {
236232
flags.readinessTimeoutMs = REPLAY_DEFAULT_READINESS_TIMEOUT_MS;
237233
}
238234
return flags;

‎src/__tests__/command-descriptor-timeout-policy.test.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@ import { test } from 'vitest';
22
import assert from 'node:assert/strict';
33
import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
44
import {
5+
commandAcceptsReadinessBudget,
56
commandDescriptors,
67
resolveCommandPostActionObservationSupport,
78
resolveCommandTimeoutPolicy,
89
} from '@agent-device/command-registry/registry';
10+
import { INTERACTION_DISPATCH_PATHS } from '@agent-device/contracts/interaction-guarantees';
911
import {
1012
DEFAULT_TIMEOUT_POLICY,
1113
resolveCommandRequestTimeoutMs,
@@ -423,4 +425,26 @@ test('a readiness budget widens the request envelope on top of the settle envelo
423425
212_000,
424426
);
425427
assert.equal(resolveCommandRequestTimeoutMs(press, { flags: { readinessTimeoutMs: 0 } }), 90_000);
428+
assert.equal(
429+
resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('fill'), {
430+
flags: { readinessTimeoutMs: 2_000 },
431+
}),
432+
90_000,
433+
);
434+
});
435+
436+
test('the readiness-budgeted commands are the ones a runtime targetReadiness cell enforces', () => {
437+
const declared = commandDescriptors
438+
.map((descriptor) => descriptor.name)
439+
.filter((command) => commandAcceptsReadinessBudget(command))
440+
.sort();
441+
const enforced = [
442+
...new Set(
443+
Object.values(INTERACTION_DISPATCH_PATHS).flatMap((path) => {
444+
const cell = path.guarantees.targetReadiness;
445+
return cell.kind === 'runtime' ? (cell.appliesTo ?? path.commands) : [];
446+
}),
447+
),
448+
].sort();
449+
assert.deepEqual(declared, enforced);
426450
});

‎src/daemon/__tests__/replay-runtime/session-replay-action-runtime.test.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ import type { DaemonRequest } from '../../daemon-request.ts';
66
import { invokeReplayAction } from '@agent-device/replay-port/session-replay-action-runtime';
77
import { replayDaemonDependencies } from '../../handlers/session-replay-command.ts';
88
import { resolveReplayAction } from '@agent-device/ad-script';
9+
import {
10+
commandAcceptsReadinessBudget,
11+
commandDescriptors,
12+
} from '@agent-device/command-registry/registry';
913

1014
const REPLAY_REQUEST: DaemonRequest = {
1115
token: 'token',
@@ -58,9 +62,13 @@ test.each(['', ' '])(
5862
},
5963
);
6064

65+
const READINESS_BUDGETED_COMMANDS = commandDescriptors
66+
.map((descriptor) => descriptor.name)
67+
.filter((command) => commandAcceptsReadinessBudget(command));
68+
6169
// A replay step has no CLI flag to carry a readiness budget, so `buildReplayActionFlags` defaults
62-
// one in for press/click/longpress.
63-
test.each(['press', 'click', 'longpress'])(
70+
// one in for every readiness-budgeted command.
71+
test.each(READINESS_BUDGETED_COMMANDS)(
6472
'replay defaults readinessTimeoutMs onto a dispatched %s step',
6573
async (command) => {
6674
const action: SessionAction = { ts: 0, command, positionals: ['label="Continue"'], flags: {} };

0 commit comments

Comments
 (0)