Skip to content

Commit 40a5cb0

Browse files
thymikeeclaude
andcommitted
fix(interaction): refuse the retired readinessTimeoutMs with migration guidance
Removing the option let readFieldInput and the tap writers drop it silently, so a released caller's press became a one-attempt press with no signal. Declare it retired at the common input row and refuse it in the click, press and longpress writers that the Node client reaches directly. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent af02fbf commit 40a5cb0

5 files changed

Lines changed: 96 additions & 38 deletions

File tree

‎src/__tests__/client-interactions-input-filtering.test.ts‎

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

6-
test('tap commands filter undeclared input without losing post-action observation', async () => {
6+
const RETIRED = /readinessTimeoutMs was removed; add an explicit wait for the target/;
7+
8+
test('tap commands refuse the retired readinessTimeoutMs before sending anything', async () => {
79
const setup = createTransport(async () => ({ ok: true, data: {} }));
810
const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
911

10-
await client.interactions.press({
11-
selector: 'label=Foo',
12-
settle: true,
12+
const calls = [
1313
// @ts-expect-error readinessTimeoutMs is not a client option.
14-
readinessTimeoutMs: 2_000,
15-
});
16-
await client.interactions.click({
17-
selector: 'label=Foo',
18-
settle: true,
14+
() => client.interactions.press({ selector: 'label=Foo', readinessTimeoutMs: 2_000 }),
1915
// @ts-expect-error readinessTimeoutMs is not a client option.
20-
readinessTimeoutMs: 1_500,
21-
});
22-
await client.interactions.longPress({
23-
selector: 'label=Foo',
24-
settle: true,
16+
() => client.interactions.click({ selector: 'label=Foo', readinessTimeoutMs: 1_500 }),
2517
// @ts-expect-error readinessTimeoutMs is not a client option.
26-
readinessTimeoutMs: 900,
27-
});
28-
29-
assert.deepEqual(
30-
setup.calls.map((call) => call.command),
31-
['press', 'click', 'longpress'],
32-
);
33-
for (const call of setup.calls) {
34-
assert.equal(Object.hasOwn(call.flags ?? {}, 'readinessTimeoutMs'), false);
35-
assert.equal(call.flags?.settle, true);
18+
() => client.interactions.longPress({ selector: 'label=Foo', readinessTimeoutMs: 900 }),
19+
];
20+
for (const call of calls) {
21+
await assert.rejects(call(), (error: { code?: string; message: string }) => {
22+
assert.equal(error.code, 'INVALID_ARGS');
23+
assert.match(error.message, RETIRED);
24+
return true;
25+
});
3626
}
27+
assert.deepEqual(setup.calls, []);
28+
});
29+
30+
test('tap commands still carry post-action observation flags', async () => {
31+
const setup = createTransport(async () => ({ ok: true, data: {} }));
32+
const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
33+
34+
await client.interactions.press({ selector: 'label=Foo', settle: true });
35+
36+
assert.equal(setup.calls[0]?.command, 'press');
37+
assert.equal(setup.calls[0]?.flags?.settle, true);
3738
});

‎src/commands/__tests__/input-audience.test.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,14 +49,26 @@ test('a key neither env nor config resolves states its own operator path', () =>
4949
// in `mcp/__tests__/command-tools-operator-inputs.test.ts`.)
5050
test('an operator-owned common key stays in the CLI and Node input schema', () => {
5151
const advertised = commonProperties();
52-
const operatorKeys = Object.keys(COMMON_INPUT_AUDIENCE);
52+
const operatorKeys = Object.keys(COMMON_INPUT_AUDIENCE).filter(
53+
(key) => COMMON_INPUT_AUDIENCE[key]?.kind === 'operator',
54+
);
5355
assert.ok(operatorKeys.length > 0, 'the table declares operator-owned common keys');
5456
for (const key of operatorKeys) {
55-
assert.equal(COMMON_INPUT_AUDIENCE[key]?.kind, 'operator');
5657
assert.ok(key in advertised, `${key} must stay readable by the CLI and Node client`);
5758
}
5859
});
5960

61+
test('a retired common key is advertised on no input schema', () => {
62+
const advertised = commonProperties();
63+
const retiredKeys = Object.keys(COMMON_INPUT_AUDIENCE).filter(
64+
(key) => COMMON_INPUT_AUDIENCE[key]?.kind === 'retired',
65+
);
66+
assert.deepEqual(retiredKeys, ['readinessTimeoutMs']);
67+
for (const key of retiredKeys) {
68+
assert.equal(key in advertised, false, `${key} is retired`);
69+
}
70+
});
71+
6072
// Schema, readers, and projection are three derivations of one table. A row
6173
// that loses its reader or its projection entry drops the key silently at the
6274
// seam nothing else covers, which is the failure `--no-record` hit twice

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

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,17 @@ type CommonInputFieldSpec = {
8686
*/
8787
const ENV_OR_OPERATOR_CONFIG = operatorAudience({ operatorConfig: true });
8888

89+
const RETIRED_READINESS_TIMEOUT_MESSAGE =
90+
'readinessTimeoutMs was removed; add an explicit wait for the target before the interaction.';
91+
92+
/** Refuses the released `readinessTimeoutMs` key, which the target-readiness wait owned. */
93+
export function assertNoRetiredReadinessTimeout(record: Record<string, unknown>): undefined {
94+
if (Object.hasOwn(record, 'readinessTimeoutMs')) {
95+
throw new AppError('INVALID_ARGS', RETIRED_READINESS_TIMEOUT_MESSAGE);
96+
}
97+
return undefined;
98+
}
99+
89100
const COMMON_INPUT_FIELDS = {
90101
session: {
91102
schema: { type: 'string', description: 'Agent-device session name.' },
@@ -215,6 +226,10 @@ const COMMON_INPUT_FIELDS = {
215226
flagKey: 'noRecord',
216227
flagIn: ['input', 'selection'],
217228
},
229+
readinessTimeoutMs: {
230+
audience: { kind: 'retired', message: RETIRED_READINESS_TIMEOUT_MESSAGE },
231+
read: assertNoRetiredReadinessTimeout,
232+
},
218233
daemonBaseUrl: {
219234
schema: { type: 'string', description: 'Remote daemon base URL.' },
220235
read: (record) => optionalString(record, 'daemonBaseUrl'),
@@ -249,7 +264,10 @@ const COMMON_INPUT_FIELDS = {
249264
schema: { type: 'boolean', description: 'Enable debug diagnostics.' },
250265
read: (record) => optionalBoolean(record, 'debug'),
251266
},
252-
} as const satisfies Record<keyof CommonCommandInput | 'target', CommonInputFieldSpec>;
267+
} as const satisfies Record<
268+
keyof CommonCommandInput | 'target' | 'readinessTimeoutMs',
269+
CommonInputFieldSpec
270+
>;
253271

254272
const COMMON_INPUT_ROWS: ReadonlyArray<readonly [string, CommonInputFieldSpec]> =
255273
Object.entries(COMMON_INPUT_FIELDS);

‎src/commands/interaction/interactions.ts‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import {
3333
targetInputFromClientTarget,
3434
} from '../cli-grammar/common.ts';
3535
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
36+
import { assertNoRetiredReadinessTimeout } from '../common-input-fields.ts';
3637
import type { ScrollInputDirection } from '@agent-device/contracts/scroll-gesture';
3738

3839
export const interactionCliReaders = {
@@ -120,17 +121,22 @@ export const interactionCliReaders = {
120121
} satisfies Record<string, CliReader>;
121122

122123
export const interactionDaemonWriters = {
123-
click: (input) =>
124-
request(PUBLIC_COMMANDS.click, interactionTargetPositionals(input as InteractionTarget), {
125-
...input,
126-
clickButton: input.button,
127-
}),
128-
press: direct(PUBLIC_COMMANDS.press, (input) =>
129-
interactionTargetPositionals(input as InteractionTarget),
130-
),
131-
longpress: direct(PUBLIC_COMMANDS.longPress, (input) =>
132-
longPressPositionals(input as LongPressOptions),
133-
),
124+
click: (input) => {
125+
assertNoRetiredReadinessTimeout(input);
126+
return request(
127+
PUBLIC_COMMANDS.click,
128+
interactionTargetPositionals(input as InteractionTarget),
129+
{ ...input, clickButton: input.button },
130+
);
131+
},
132+
press: direct(PUBLIC_COMMANDS.press, (input) => {
133+
assertNoRetiredReadinessTimeout(input);
134+
return interactionTargetPositionals(input as InteractionTarget);
135+
}),
136+
longpress: direct(PUBLIC_COMMANDS.longPress, (input) => {
137+
assertNoRetiredReadinessTimeout(input);
138+
return longPressPositionals(input as LongPressOptions);
139+
}),
134140
hover: direct(PUBLIC_COMMANDS.hover, (input) =>
135141
interactionTargetPositionals(input as InteractionTarget),
136142
),

‎src/mcp/__tests__/command-tools-operator-inputs.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,27 @@ test('MCP refuses every explicit operator-owned argument with guidance', async (
8686
assert.deepEqual(calls, [], 'a refused operator input must never reach the command route');
8787
});
8888

89+
test('MCP neither advertises nor admits the retired readiness budget', async () => {
90+
for (const tool of listCommandTools()) {
91+
const properties = tool.inputSchema.properties ?? {};
92+
assert.equal('readinessTimeoutMs' in properties, false, `${tool.name} advertises it`);
93+
}
94+
// The real command route (no runCommand injection), like the retired maxSize regressions:
95+
// retired keys pass admission so the command's own reader answers with migration guidance.
96+
const executor = createCommandToolExecutor({
97+
createClient: () => ({}) as AgentDeviceClient,
98+
});
99+
100+
for (const [command, input] of [
101+
['press', { target: { kind: 'selector', selector: 'label=Continue' } }],
102+
['fill', { target: { kind: 'selector', selector: 'label=Name' }, text: 'x' }],
103+
] as const) {
104+
const result = await executor.execute(command, { ...input, readinessTimeoutMs: 2_000 });
105+
assert.equal(result.isError, true, command);
106+
assert.match(result.content[0]?.text ?? '', /readinessTimeoutMs was removed/, command);
107+
}
108+
});
109+
89110
test('MCP refuses an explicit daemonAuthToken argument with env guidance', async () => {
90111
const calls: unknown[] = [];
91112
const executor = createCommandToolExecutor({

0 commit comments

Comments
 (0)