Skip to content

Commit 2f27436

Browse files
committed
refactor(mcp): project wait family output schema from its owning module
Moves the single hand-authored MCP outputSchema entry for wait out of command-output-schemas.ts into a frozen WAIT_COMMAND_OUTPUT_SCHEMAS map exported from src/commands/capture/wait.ts, following the #2810 projection seam already used by the replay, system, interaction, device-management, push-management, recording, and viewport families on this stack. Registers the family in the PROJECTED_FAMILIES disjointness check and adds command-tools-capture-wait-schemas.test.ts with a reference-equality proof against the module object and an owner-file check, matching the pattern from the other projected families. wait's descriptor declares no post-action observation trait (#1652), so no settle-graft copy applies here. The moved code is byte-identical to what command-output-schemas.ts held: same objectSchema/numberSchema/stringSchema/constSchema call and field order. Verified the published outputSchema for wait is byte-identical to origin/main by dumping COMMAND_OUTPUT_SCHEMAS.wait as JSON on both refs. Part of #2819.
1 parent 8faeba2 commit 2f27436

4 files changed

Lines changed: 74 additions & 16 deletions

File tree

‎src/commands/capture/wait.ts‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,18 @@ import type { WaitCommandOptions } from '@agent-device/contracts/client';
44
import { parseWaitPositionals } from '@agent-device/command-registry/wait-positionals';
55
import type { WaitParsed } from '@agent-device/command-registry/wait-positionals';
66
import { SELECTOR_SNAPSHOT_FLAGS } from '@agent-device/command-registry/flag-groups';
7+
import type { CommandResultMap } from '@agent-device/command-registry/command-result';
78
import { AppError } from '@agent-device/kernel/errors';
89
import { isValidSelectorExpression } from '@agent-device/selectors';
9-
import { booleanField, enumField, integerField, stringField } from '../command-input.ts';
10+
import {
11+
booleanField,
12+
enumField,
13+
integerField,
14+
numberSchema,
15+
objectSchema,
16+
stringField,
17+
stringSchema,
18+
} from '../command-input.ts';
1019
import { optionalEnum } from '../input-readers.ts';
1120
import {
1221
direct,
@@ -15,6 +24,7 @@ import {
1524
selectorSnapshotOptionsFromFlags,
1625
} from '../cli-grammar/common.ts';
1726
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
27+
import type { JsonSchema } from '../command-contract.ts';
1828
import { defineCommandFacet } from '../family/types.ts';
1929
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
2030
import { messageOutput } from '../output-common.ts';
@@ -24,6 +34,34 @@ import { absenceCaptureOptionError } from '@agent-device/selectors/absence-obser
2434

2535
const WAIT_COMMAND_NAME = 'wait';
2636

37+
function constSchema(value: string): JsonSchema {
38+
return { type: 'string', const: value };
39+
}
40+
41+
/**
42+
* This family's advertised MCP `outputSchema`, keyed by daemon command name and projected into
43+
* the command map by `src/mcp/command-output-schemas.ts`. Non-strict like every other entry: no
44+
* `additionalProperties: false`, so additive response fields keep validating. `wait` does not
45+
* carry the post-action observation trait (#1652): its descriptor declares no post-action
46+
* observation, so no settle-graft copy applies here.
47+
*/
48+
export const WAIT_COMMAND_OUTPUT_SCHEMAS = {
49+
// packages/contracts/src/wait.ts — compact public daemon projection.
50+
wait: objectSchema(
51+
{
52+
waitedMs: numberSchema(),
53+
kind: constSchema('selector'),
54+
text: stringSchema(),
55+
selector: stringSchema(),
56+
captures: numberSchema(),
57+
nodeCount: numberSchema(),
58+
hint: stringSchema(),
59+
warning: stringSchema(),
60+
},
61+
['waitedMs'],
62+
),
63+
} satisfies Pick<Record<keyof CommandResultMap, JsonSchema>, 'wait'>;
64+
2765
const waitCommandDescription =
2866
'Wait for a duration, text, snapshot ref, selector to appear, selector to be strictly absent, or stable UI. Use the strict absence target when zero selector matches are required; stable waits until the UI stays quiet for the requested window.';
2967

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
4+
import { WAIT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/capture/wait.ts';
5+
import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
6+
7+
const WAIT_COMMANDS = Object.keys(WAIT_COMMAND_OUTPUT_SCHEMAS) as Array<
8+
keyof typeof WAIT_COMMAND_OUTPUT_SCHEMAS
9+
>;
10+
11+
// wait does not carry the post-action observation trait (#1652): its descriptor declares no
12+
// post-action observation, so the composed map never copies the entry and reference equality
13+
// must hold.
14+
test('MCP wait family output schemas are the family module entries, not copies', () => {
15+
for (const command of WAIT_COMMANDS) {
16+
assert.equal(
17+
COMMAND_OUTPUT_SCHEMAS[command],
18+
WAIT_COMMAND_OUTPUT_SCHEMAS[command],
19+
`${command} is not reference-equal to the wait module's own schema object`,
20+
);
21+
}
22+
});
23+
24+
test('the projected family map declares exactly the commands its module owns', () => {
25+
for (const command of WAIT_COMMANDS) {
26+
assert.ok(
27+
ownerFilesForCommand(command).includes('src/commands/capture/wait.ts'),
28+
`${command} projects its output schema from this module but does not name it as its owner`,
29+
);
30+
}
31+
});

‎src/mcp/__tests__/command-tools-replay-schemas.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { test } from 'vitest';
33
import type { ReplayCommandResult, ReplaySuiteResult } from '@agent-device/contracts/replay';
44
import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
55
import { commandSupportsSettleObservation } from '@agent-device/command-registry/registry';
6+
import { WAIT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/capture/wait.ts';
67
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/device.ts';
78
import { PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/push.ts';
89
import { VIEWPORT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/viewport.ts';
@@ -77,6 +78,7 @@ const PROJECTED_FAMILIES = [
7778
{ name: 'replay', schemas: REPLAY_COMMAND_OUTPUT_SCHEMAS },
7879
{ name: 'system', schemas: SYSTEM_COMMAND_OUTPUT_SCHEMAS },
7980
{ name: 'interaction', schemas: INTERACTION_COMMAND_OUTPUT_SCHEMAS },
81+
{ name: 'capture-wait', schemas: WAIT_COMMAND_OUTPUT_SCHEMAS },
8082
{ name: 'management-device', schemas: DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS },
8183
{ name: 'management-push', schemas: PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS },
8284
{ name: 'management-viewport', schemas: VIEWPORT_COMMAND_OUTPUT_SCHEMAS },

‎src/mcp/command-output-schemas.ts‎

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import {
1010
stringArraySchema,
1111
stringSchema,
1212
} from '../commands/command-input.ts';
13+
import { WAIT_COMMAND_OUTPUT_SCHEMAS } from '../commands/capture/wait.ts';
1314
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/device.ts';
1415
import { PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/push.ts';
1516
import { VIEWPORT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/viewport.ts';
@@ -171,21 +172,6 @@ function deriveSettleObservationSchemas(
171172
}
172173

173174
const BASE_COMMAND_OUTPUT_SCHEMAS = {
174-
// packages/contracts/src/wait.ts — compact public daemon projection.
175-
wait: objectSchema(
176-
{
177-
waitedMs: numberSchema(),
178-
kind: constSchema('selector'),
179-
text: stringSchema(),
180-
selector: stringSchema(),
181-
captures: numberSchema(),
182-
nodeCount: numberSchema(),
183-
hint: stringSchema(),
184-
warning: stringSchema(),
185-
},
186-
['waitedMs'],
187-
),
188-
189175
// packages/contracts/src/scroll-command.ts — ScrollCommandResult. The
190176
// settle-capable generic-route pair must both be typed so the trait
191177
// derivation grafts the observation onto each (#1652); platform leaves add
@@ -334,6 +320,7 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
334320
// command surface and projects it here. This spread stays last: a hand-written entry for
335321
// a projected command then fails as TS2783 instead of quietly overriding the family's,
336322
// and this map's `satisfies` still refuses a missing `CommandResultMap` key.
323+
...WAIT_COMMAND_OUTPUT_SCHEMAS,
337324
...DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
338325
...PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
339326
...VIEWPORT_COMMAND_OUTPUT_SCHEMAS,

0 commit comments

Comments
 (0)