Skip to content

Commit 5d75c3f

Browse files
committed
refactor(mcp): project device management family output schemas from their owning module
Moves the 2 hand-authored MCP outputSchema entries for boot and shutdown out of command-output-schemas.ts into a frozen DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS map exported from src/commands/management/device.ts, following the #2810 projection seam already used for the interaction and system families on this stack. Registers the family in the PROJECTED_FAMILIES disjointness check and adds a colocated command-tools-management-device-schemas.test.ts proving reference equality with the module object. Neither command carries the post-action observation trait, so no settle-graft copy applies here. DEVICE_KINDS is duplicated locally rather than imported back from command-output-schemas.ts (which still needs its own copy for `prepare`), matching the constSchema/responseCostSchema duplication precedent from the system and interaction families' moves. Part of #2819.
1 parent dd27903 commit 5d75c3f

6 files changed

Lines changed: 97 additions & 39 deletions

File tree

‎packages/kernel/src/device.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ export type PublicPlatform = (typeof PUBLIC_PLATFORMS)[number];
3939
// aliases `ios`/`macos`, which still resolve to `apple` devices (read-path back-compat).
4040
export const PLATFORM_SELECTORS = [...PLATFORMS, 'ios', 'macos'] as const;
4141
export type PlatformSelector = (typeof PLATFORM_SELECTORS)[number];
42-
const DEVICE_KINDS = ['simulator', 'emulator', 'device'] as const;
42+
export const DEVICE_KINDS = ['simulator', 'emulator', 'device'] as const;
4343
export type DeviceKind = (typeof DEVICE_KINDS)[number];
4444
export const DEVICE_TARGETS = ['mobile', 'tv', 'desktop'] as const;
4545
export type DeviceTarget = (typeof DEVICE_TARGETS)[number];

‎src/commands/management/device.ts‎

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,65 @@
11
import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
22
import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema';
3-
import { booleanField } from '../command-input.ts';
3+
import type { CommandResultMap } from '@agent-device/command-registry/command-result';
4+
import { DEVICE_KINDS, DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
5+
import {
6+
booleanField,
7+
booleanSchema,
8+
enumSchema,
9+
looseObjectSchema,
10+
numberSchema,
11+
objectSchema,
12+
stringSchema,
13+
} from '../command-input.ts';
14+
import type { JsonSchema } from '../command-contract.ts';
415
import { commonInputFromFlags, direct } from '../cli-grammar/common.ts';
516
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
617
import { defineCommandFacet } from '../family/types.ts';
718
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
819
import { managementCliOutputFormatters } from './output.ts';
920

21+
// boot / shutdown share the resolved-device header (packages/contracts/src/device.ts).
22+
const deviceHeaderProperties: Record<string, JsonSchema> = {
23+
// Public leaf vocabulary (ios | macos | android | harmonyos | vega | linux | web): boot/shutdown
24+
// emit publicPlatformString, never the internal `apple` platform.
25+
platform: enumSchema(PUBLIC_PLATFORMS),
26+
target: enumSchema(DEVICE_TARGETS),
27+
device: stringSchema('Human-readable device name.'),
28+
id: stringSchema('Stable device id.'),
29+
kind: enumSchema(DEVICE_KINDS),
30+
};
31+
const deviceHeaderRequired = ['platform', 'target', 'device', 'id', 'kind'] as const;
32+
33+
// TargetShutdownResult (packages/contracts/src/target-shutdown-contract.ts).
34+
const targetShutdownResultSchema: JsonSchema = objectSchema(
35+
{
36+
success: booleanSchema(),
37+
exitCode: numberSchema(),
38+
stdout: stringSchema(),
39+
stderr: stringSchema(),
40+
error: looseObjectSchema('Normalized error detail when shutdown failed.'),
41+
},
42+
['success', 'exitCode', 'stdout', 'stderr'],
43+
);
44+
45+
/**
46+
* This family's advertised MCP `outputSchema`s, keyed by daemon command name and projected into
47+
* the command map by `src/mcp/command-output-schemas.ts`. Non-strict like every other entry: no
48+
* `additionalProperties: false`, so additive response fields such as `cost` keep validating.
49+
* Neither command carries the post-action observation trait (#1652): both are device-runtime
50+
* commands, not interaction commands, so no settle graft applies here.
51+
*/
52+
export const DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS = {
53+
boot: objectSchema({ ...deviceHeaderProperties, booted: { type: 'boolean', const: true } }, [
54+
...deviceHeaderRequired,
55+
'booted',
56+
]),
57+
shutdown: objectSchema({ ...deviceHeaderProperties, shutdown: targetShutdownResultSchema }, [
58+
...deviceHeaderRequired,
59+
'shutdown',
60+
]),
61+
} satisfies Pick<Record<keyof CommandResultMap, JsonSchema>, 'boot' | 'shutdown'>;
62+
1063
const devicesCommandMetadata = defineFieldCommandMetadata(
1164
'devices',
1265
'List available devices and simulators that can be selected for automation. Use platform, device, udid, or serial inputs on later commands to target one result.',
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
4+
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/device.ts';
5+
import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
6+
7+
const DEVICE_MANAGEMENT_COMMANDS = ['boot', 'shutdown'] as const;
8+
9+
test('the family map declares exactly boot and shutdown', () => {
10+
assert.deepEqual(Object.keys(DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS).sort(), [
11+
...DEVICE_MANAGEMENT_COMMANDS,
12+
]);
13+
});
14+
15+
// Neither boot nor shutdown carries the post-action observation trait (#1652): both are
16+
// device-runtime commands, not interaction commands, so the composed map never copies either
17+
// entry and reference equality must hold for both.
18+
test('MCP device management family output schemas are the family module entries, not copies', () => {
19+
for (const command of DEVICE_MANAGEMENT_COMMANDS) {
20+
assert.equal(
21+
COMMAND_OUTPUT_SCHEMAS[command],
22+
DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS[command],
23+
`${command} is not reference-equal to the device management module's own schema object`,
24+
);
25+
}
26+
});
27+
28+
test('the projected family map declares exactly the commands its module owns', () => {
29+
for (const command of DEVICE_MANAGEMENT_COMMANDS) {
30+
assert.ok(
31+
ownerFilesForCommand(command).includes('src/commands/management/device.ts'),
32+
`${command} projects its output schema from this module but does not name it as its owner`,
33+
);
34+
}
35+
});

‎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 { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/device.ts';
67
import { INTERACTION_COMMAND_OUTPUT_SCHEMAS } from '../../commands/interaction/index.ts';
78
import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../../commands/replay/index.ts';
89
import { SYSTEM_COMMAND_OUTPUT_SCHEMAS } from '../../commands/system/index.ts';
@@ -73,6 +74,7 @@ const PROJECTED_FAMILIES = [
7374
{ name: 'replay', schemas: REPLAY_COMMAND_OUTPUT_SCHEMAS },
7475
{ name: 'system', schemas: SYSTEM_COMMAND_OUTPUT_SCHEMAS },
7576
{ name: 'interaction', schemas: INTERACTION_COMMAND_OUTPUT_SCHEMAS },
77+
{ name: 'management-device', schemas: DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS },
7678
] as const;
7779

7880
test('projected output-schema families claim disjoint commands and survive the composition intact', () => {

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

Lines changed: 3 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import {
1111
stringArraySchema,
1212
stringSchema,
1313
} from '../commands/command-input.ts';
14+
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/device.ts';
1415
import {
1516
INTERACTION_COMMAND_OUTPUT_SCHEMAS,
1617
postActionSurfaceChangeSchema,
@@ -19,7 +20,7 @@ import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../commands/replay/index.ts';
1920
import { SYSTEM_COMMAND_OUTPUT_SCHEMAS } from '../commands/system/index.ts';
2021
import { NATIVE_PATH_DISPOSITION_VALUES } from '@agent-device/contracts/recording-native-path';
2122
import { RECORDER_OBSERVATION_VALUES } from '@agent-device/contracts/recording-stop-observation';
22-
import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
23+
import { DEVICE_KINDS, DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
2324

2425
/**
2526
* Registry of per-command MCP `outputSchema`s, keyed by the daemon command
@@ -50,7 +51,6 @@ import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
5051
* trait (#1652).
5152
*/
5253

53-
export const DEVICE_KINDS = ['simulator', 'emulator', 'device'] as const;
5454

5555
const artifactSchema = objectSchema(
5656
{
@@ -132,30 +132,6 @@ const settleObservationSchema: JsonSchema = objectSchema(
132132
['settled', 'waitedMs', 'captures', 'quietMs', 'timeoutMs'],
133133
);
134134

135-
// boot / shutdown share the resolved-device header (packages/contracts/src/device.ts).
136-
const deviceHeaderProperties: Record<string, JsonSchema> = {
137-
// Public leaf vocabulary (ios | macos | android | linux | web): boot/shutdown
138-
// emit publicPlatformString, never the internal `apple` platform.
139-
platform: enumSchema(PUBLIC_PLATFORMS),
140-
target: enumSchema(DEVICE_TARGETS),
141-
device: stringSchema('Human-readable device name.'),
142-
id: stringSchema('Stable device id.'),
143-
kind: enumSchema(DEVICE_KINDS),
144-
};
145-
const deviceHeaderRequired = ['platform', 'target', 'device', 'id', 'kind'] as const;
146-
147-
// TargetShutdownResult (packages/contracts/src/target-shutdown-contract.ts).
148-
const targetShutdownResultSchema: JsonSchema = objectSchema(
149-
{
150-
success: booleanSchema(),
151-
exitCode: numberSchema(),
152-
stdout: stringSchema(),
153-
stderr: stringSchema(),
154-
error: looseObjectSchema('Normalized error detail when shutdown failed.'),
155-
},
156-
['success', 'exitCode', 'stdout', 'stderr'],
157-
);
158-
159135
/** Grafts the opt-in `--settle` observation onto a closed schema or union branch. */
160136
function withSettleObservation(schema: JsonSchema): JsonSchema {
161137
// Union-shaped results (fill) carry the observation in EACH branch, never
@@ -189,16 +165,6 @@ function deriveSettleObservationSchemas(
189165
}
190166

191167
const BASE_COMMAND_OUTPUT_SCHEMAS = {
192-
// packages/contracts/src/device.ts
193-
boot: objectSchema({ ...deviceHeaderProperties, booted: { type: 'boolean', const: true } }, [
194-
...deviceHeaderRequired,
195-
'booted',
196-
]),
197-
shutdown: objectSchema({ ...deviceHeaderProperties, shutdown: targetShutdownResultSchema }, [
198-
...deviceHeaderRequired,
199-
'shutdown',
200-
]),
201-
202168
// packages/contracts/src/viewport.ts
203169
viewport: objectSchema(
204170
{ width: numberSchema(), height: numberSchema(), message: stringSchema() },
@@ -464,6 +430,7 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
464430
// command surface and projects it here. This spread stays last: a hand-written entry for
465431
// a projected command then fails as TS2783 instead of quietly overriding the family's,
466432
// and this map's `satisfies` still refuses a missing `CommandResultMap` key.
433+
...DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
467434
...INTERACTION_COMMAND_OUTPUT_SCHEMAS,
468435
...REPLAY_COMMAND_OUTPUT_SCHEMAS,
469436
...SYSTEM_COMMAND_OUTPUT_SCHEMAS,

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import type { JsonSchema } from '../commands/command-contract.ts';
22
import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
3-
import { COMMAND_OUTPUT_SCHEMAS, DEVICE_KINDS } from './command-output-schemas.ts';
3+
import { DEVICE_KINDS } from '@agent-device/kernel/device';
4+
import { COMMAND_OUTPUT_SCHEMAS } from './command-output-schemas.ts';
45

56
const MCP_COLLECTION_OUTPUT_SCHEMAS = {
67
devices: {

0 commit comments

Comments
 (0)