Skip to content

Commit 1481f36

Browse files
committed
fix(command-registry): pin the readiness cap without importing the selector policy
The envelope widening imported the promotedTarget selector row to read its 2 s poll ceiling, which made every command-registry entry and src/cli.ts evaluate the selector policy module. The cap is now READINESS_BUDGET_MAX_MS in timeout-policy.ts, pinned by test to the row's maxTimeoutMs; selectors cannot import command-registry, so the test is the tie. The same eager-closure gate showed two more new edges from this branch: - replay's native and test command entries evaluated observe-until and the selector policy through the target gate. Both now load inside the gate's readiness path, the only code that uses them. - src/cli.ts evaluated the new target-readiness-grammar module. Its one function moves into interaction/metadata.ts, its one caller, and its tests into metadata.test.ts.
1 parent 09cbe1e commit 1481f36

10 files changed

Lines changed: 85 additions & 80 deletions

File tree

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

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import { SELECTOR_PIPELINE_POLICIES } from '@agent-device/selectors/selector-pipeline-policy';
21
import type { CommandTimeoutBudget, CommandTimeoutPolicy } from './types.ts';
32

43
// Request-envelope constants, relocated from src/daemon/request-timeouts.ts when
@@ -87,6 +86,12 @@ export function resolveCommandRequestTimeoutMs(
8786
return envelopeMs + readinessBudgetMs(policy, input.flags);
8887
}
8988

89+
/**
90+
* The ceiling of a `targetReadiness: 'budgeted'` command's readiness budget: the promotedTarget
91+
* selector row's poll ceiling, pinned to it by test.
92+
*/
93+
export const READINESS_BUDGET_MAX_MS = 2_000;
94+
9095
/**
9196
* A readiness budget is target-poll time spent before the action itself, so it extends whatever
9297
* envelope the command otherwise has; the daemon's own poll must never outlive the client's clock.
@@ -99,7 +104,7 @@ function readinessBudgetMs(
99104
if (policy.targetReadiness !== 'budgeted') return 0;
100105
const budgetMs = flags?.readinessTimeoutMs;
101106
if (typeof budgetMs !== 'number' || !Number.isInteger(budgetMs) || budgetMs <= 0) return 0;
102-
return Math.min(budgetMs, SELECTOR_PIPELINE_POLICIES.promotedTarget.poll.maxTimeoutMs);
107+
return Math.min(budgetMs, READINESS_BUDGET_MAX_MS);
103108
}
104109

105110
function resolvePositionalBudgetTimeoutMs(

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,8 +85,8 @@ export type CommandTimeoutPolicy = {
8585

8686
/**
8787
* `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`.
88+
* a caller-supplied `readinessTimeoutMs`, capped at `READINESS_BUDGET_MAX_MS` (`timeout-policy.ts`).
89+
* Must match the commands the `targetReadiness` interaction guarantee cells mark `runtime`.
9090
*/
9191
export type CommandTargetReadiness = 'budgeted';
9292

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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ import type {
77
} from '@agent-device/replay-port/command-types';
88
import { mergeParentFlags } from '@agent-device/command-registry/batch';
99
import { commandAcceptsReadinessBudget } from '@agent-device/command-registry/registry';
10-
import { SELECTOR_PIPELINE_POLICIES } from '@agent-device/selectors/selector-pipeline-policy';
1110
import { AppError, normalizeError } from '@agent-device/kernel/errors';
1211
import {
1312
gesturePayloadFromPositionals,
@@ -236,12 +235,15 @@ const REPLAY_DEFAULT_READINESS_TIMEOUT_MS = 2_000;
236235
* step's command does not wait for its target. The pre-dispatch target gate polls under the same
237236
* schedule, so neither refuses a target the other would still wait for.
238237
*/
239-
export function replayStepReadinessSchedule(
238+
export async function replayStepReadinessSchedule(
240239
parentFlags: CommandFlags | undefined,
241240
action: SessionAction,
242-
): { intervalMs: number; budgetMs: number } | undefined {
241+
): Promise<{ intervalMs: number; budgetMs: number } | undefined> {
243242
const { readinessTimeoutMs } = buildReplayActionFlags(parentFlags, action.flags, action.command);
244243
if (readinessTimeoutMs === undefined || readinessTimeoutMs <= 0) return undefined;
244+
// Loaded only by a step that waits, so the replay entry does not evaluate the selector policy.
245+
const { SELECTOR_PIPELINE_POLICIES } =
246+
await import('@agent-device/selectors/selector-pipeline-policy');
245247
const poll = SELECTOR_PIPELINE_POLICIES.promotedTarget.poll;
246248
return { intervalMs: poll.intervalMs, budgetMs: Math.min(readinessTimeoutMs, poll.maxTimeoutMs) };
247249
}

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@ import type {
2626
AdReplayStepRuntime,
2727
AdReplayTargetObservation,
2828
} from '@agent-device/ad-replay';
29-
import { observeUntil } from '@agent-device/capture-kit/observe-until';
3029
import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
3130
import { collectReplayActionArtifactPaths } from '@agent-device/replay-port/session-replay-runtime-artifacts';
3231
import {
@@ -228,8 +227,9 @@ export function createAdReplayStepRuntime(params: {
228227
// command resolving a selector (a `@ref` resolves without a wait).
229228
const readiness = token.startsWith('@')
230229
? undefined
231-
: replayStepReadinessSchedule(ctx.replayReq.flags, action);
230+
: await replayStepReadinessSchedule(ctx.replayReq.flags, action);
232231
if (!readiness) return await observeOnce();
232+
const { observeUntil } = await import('@agent-device/capture-kit/observe-until');
233233
const observed = await observeUntil<AdReplayTargetObservation, AdReplayTargetObservation>({
234234
capture: observeOnce,
235235
verdict: (latest) =>

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import { INTERACTION_DISPATCH_PATHS } from '@agent-device/contracts/interaction-
1111
import { SELECTOR_PIPELINE_POLICIES } from '@agent-device/selectors/selector-pipeline-policy';
1212
import {
1313
DEFAULT_TIMEOUT_POLICY,
14+
READINESS_BUDGET_MAX_MS,
1415
resolveCommandRequestTimeoutMs,
1516
} from '@agent-device/command-registry/timeout-policy';
1617
import { DEFAULT_STABLE_TIMEOUT_MS } from '../commands/interaction/runtime/stable-capture.ts';
@@ -428,9 +429,15 @@ test('a readiness budget widens the request envelope on top of the settle envelo
428429
assert.equal(resolveCommandRequestTimeoutMs(press, { flags: { readinessTimeoutMs: 0 } }), 90_000);
429430
assert.equal(
430431
resolveCommandRequestTimeoutMs(press, { flags: { readinessTimeoutMs: 999_000 } }),
431-
90_000 + SELECTOR_PIPELINE_POLICIES.promotedTarget.poll.maxTimeoutMs,
432+
90_000 + 2_000,
433+
);
434+
});
435+
436+
test('the envelope readiness cap is the promotedTarget row poll ceiling', () => {
437+
assert.equal(
438+
READINESS_BUDGET_MAX_MS,
439+
SELECTOR_PIPELINE_POLICIES.promotedTarget.poll.maxTimeoutMs,
432440
);
433-
assert.equal(SELECTOR_PIPELINE_POLICIES.promotedTarget.poll.maxTimeoutMs, 2_000);
434441
assert.equal(
435442
resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('fill'), {
436443
flags: { readinessTimeoutMs: 2_000 },

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ export type CommonCommandInput = Pick<
3434

3535
export type CommonInputReadOptions = {
3636
readTargetAlias?: boolean;
37-
/** The command's own fields declare `readinessTimeoutMs` (`target-readiness-grammar.ts`). */
37+
/** The command's own fields declare `readinessTimeoutMs` (`interaction/metadata.ts`). */
3838
readinessBudgetDeclared?: boolean;
3939
};
4040

‎src/commands/interaction/metadata.test.ts‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import { expect, test } from 'vitest';
22
import { AppError } from '@agent-device/kernel/errors';
3+
import { commandAcceptsReadinessBudget } from '@agent-device/command-registry/registry';
4+
import { findCommandMetadata, listCommandMetadata } from '../command-metadata.ts';
35
import { interactionCommandMetadata } from './metadata.ts';
46

57
// `fill <target> ""` is the clear-field primitive (#2063): before it existed, emptying an input
@@ -50,3 +52,34 @@ test('type keeps refusing an empty text: appending nothing is not a clear', () =
5052
expect((error as AppError).code).toBe('INVALID_ARGS');
5153
}
5254
});
55+
56+
const SELECTOR_TARGET = { kind: 'selector', selector: 'label=Continue' };
57+
58+
test('a command advertises readinessTimeoutMs exactly when its descriptor declares the budget', () => {
59+
for (const metadata of listCommandMetadata()) {
60+
const properties = metadata.inputSchema.properties ?? {};
61+
expect('readinessTimeoutMs' in properties, metadata.name).toBe(
62+
commandAcceptsReadinessBudget(metadata.name),
63+
);
64+
}
65+
});
66+
67+
test('press reads readinessTimeoutMs', () => {
68+
const input = findCommandMetadata('press').readInput({
69+
target: SELECTOR_TARGET,
70+
readinessTimeoutMs: 2_000,
71+
}) as { readinessTimeoutMs?: number };
72+
expect(input.readinessTimeoutMs).toBe(2_000);
73+
});
74+
75+
test('fill refuses readinessTimeoutMs with an input error, and reads without it', () => {
76+
const fill = findCommandMetadata('fill');
77+
expect(() => fill.readInput({ target: SELECTOR_TARGET, text: 'hi' })).not.toThrow();
78+
let refusal: unknown;
79+
try {
80+
fill.readInput({ target: SELECTOR_TARGET, text: 'hi', readinessTimeoutMs: 2_000 });
81+
} catch (error) {
82+
refusal = error;
83+
}
84+
expect(refusal instanceof AppError && refusal.code).toBe('INVALID_ARGS');
85+
});

‎src/commands/interaction/metadata.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,15 @@ import {
2121
SWIPE_REPETITION_MAX,
2222
} from '@agent-device/contracts/scroll-gesture';
2323
import { FIND_LOCATORS } from '@agent-device/selectors';
24+
import { commandAcceptsReadinessBudget } from '@agent-device/command-registry/registry';
2425
import {
2526
booleanField,
2627
elementTargetField,
2728
enumField,
2829
integerField,
2930
interactionTargetField,
3031
numberField,
32+
operatorField,
3133
pointField,
3234
repeatedFields,
3335
requiredField,
@@ -40,7 +42,6 @@ import { readCommonInput, type CommonCommandInput } from '../common-input-fields
4042
import { readInputRecord } from '../input-readers.ts';
4143
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
4244
import { postActionObservationFields } from '../post-action-observation-grammar.ts';
43-
import { targetReadinessFields } from '../target-readiness-grammar.ts';
4445

4546
const FIND_ACTION_VALUES = [
4647
'click',
@@ -79,6 +80,30 @@ const interactionCommandDescriptions = {
7980

8081
type InteractionCommandName = keyof typeof interactionCommandDescriptions;
8182

83+
/**
84+
* The input field a command's `targetReadiness: 'budgeted'` descriptor trait entitles it to. Only
85+
* those commands declare `readinessTimeoutMs`; the common input reader refuses the key for every
86+
* command whose fields do not (`common-input-fields.ts`). Fails closed at module load for a command
87+
* without the trait, so a field map cannot advertise a budget its runtime never polls under.
88+
*/
89+
function targetReadinessFields(command: InteractionCommandName) {
90+
if (!commandAcceptsReadinessBudget(command)) {
91+
throw new Error(`${command} does not declare targetReadiness: 'budgeted'`);
92+
}
93+
return {
94+
readinessTimeoutMs: operatorField(
95+
integerField(
96+
"Operator-only: how long the command 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.",
97+
{ min: 1 },
98+
),
99+
{
100+
operatorPath:
101+
'Pass readinessTimeoutMs directly as CLI/Node.js command input; it is not exposed to model-facing tools.',
102+
},
103+
),
104+
};
105+
}
106+
82107
const clickFields = {
83108
target: requiredField(interactionTargetField()),
84109
button: enumField(CLICK_BUTTONS, 'Pointer button for platforms that support mouse buttons.'),

‎src/commands/target-readiness-grammar.test.ts‎

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎src/commands/target-readiness-grammar.ts‎

Lines changed: 0 additions & 26 deletions
This file was deleted.

0 commit comments

Comments
 (0)