Skip to content

Commit 02a089b

Browse files
committed
refactor(mcp): project system family output schemas from their owning module
Moves the 10 hand-authored MCP outputSchema entries for back, home, orientation, app-switcher, fold, action-button, tv-remote, clipboard, appstate, and keyboard out of command-output-schemas.ts into a frozen SYSTEM_COMMAND_OUTPUT_SCHEMAS map exported from src/commands/system/index.ts, following the #2810 projection seam. Registers the family in PROJECTED_FAMILIES and moves its shape-assertion tests into a colocated command-tools-system-schemas.test.ts, including a reference-equality proof that accounts for the one entry (back) the settle-observation derivation pass copies rather than passing through untouched. Part of #2819.
1 parent 1433e11 commit 02a089b

6 files changed

Lines changed: 369 additions & 271 deletions

‎src/commands/system/index.ts‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { FOLD_FLAGS } from '@agent-device/command-registry/flag-groups';
2+
import type { CommandResultMap } from '@agent-device/command-registry/command-result';
23
import type { ClipboardCommandOptions } from '@agent-device/contracts/client';
34
import {
45
type FoldKeyframe,
@@ -11,13 +12,16 @@ import {
1112
FOLD_POSE_USAGE,
1213
parseDeviceRotation,
1314
} from '@agent-device/contracts/device';
15+
import { FOLD_SCREEN_COORDINATE_SPACE } from '@agent-device/contracts/fold-runtime';
1416
import { type BackMode, BACK_MODES } from '@agent-device/contracts/back-mode';
1517
import {
1618
TV_REMOTE_BUTTONS,
1719
TV_REMOTE_BUTTON_USAGE,
1820
parseTvRemoteButton,
1921
tvRemoteDurationMode,
2022
} from '@agent-device/contracts/tv-remote';
23+
import { APPLE_APPLICATION_STATES } from '@agent-device/kernel/snapshot';
24+
import { SESSION_SURFACES } from '@agent-device/contracts/session';
2125
import { AppError } from '@agent-device/kernel/errors';
2226
import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema';
2327
import {
@@ -28,13 +32,19 @@ import {
2832
requiredDaemonString,
2933
} from '../cli-grammar/common.ts';
3034
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
35+
import type { JsonSchema } from '../command-contract.ts';
3136
import {
3237
enumField,
3338
integerField,
3439
requiredField,
3540
stringField,
3641
jsonSchemaField,
3742
readFieldInput,
43+
booleanSchema,
44+
enumSchema,
45+
numberSchema,
46+
objectSchema,
47+
stringSchema,
3848
} from '../command-input.ts';
3949
import { compactRecord } from '../input-readers.ts';
4050
import {
@@ -64,6 +74,158 @@ const TV_REMOTE_LONGPRESS_PRESET_MS = 500;
6474
const CLIPBOARD_ACTION_VALUES = ['read', 'write'] as const;
6575
const KEYBOARD_METADATA_ACTION_VALUES = ['status', 'dismiss', 'enter', 'return'] as const;
6676

77+
function constSchema(value: string): JsonSchema {
78+
return { type: 'string', const: value };
79+
}
80+
81+
/**
82+
* This family's advertised MCP `outputSchema`s, keyed by daemon command name and projected into
83+
* the command map by `src/mcp/command-output-schemas.ts`. Non-strict like every other entry: no
84+
* `additionalProperties: false`, so additive response fields such as `settle`/`cost` keep
85+
* validating. `back`'s settle observation is grafted separately by the trait derivation pass.
86+
*/
87+
export const SYSTEM_COMMAND_OUTPUT_SCHEMAS = {
88+
back: objectSchema(
89+
{
90+
action: constSchema('back'),
91+
mode: enumSchema(BACK_MODES),
92+
message: stringSchema(),
93+
},
94+
['action', 'mode', 'message'],
95+
),
96+
home: objectSchema({ action: constSchema('home'), message: stringSchema() }, [
97+
'action',
98+
'message',
99+
]),
100+
orientation: objectSchema(
101+
{
102+
action: constSchema('orientation'),
103+
orientation: enumSchema(DEVICE_ROTATIONS),
104+
message: stringSchema(),
105+
confirmed: booleanSchema(),
106+
warning: stringSchema(),
107+
},
108+
['action', 'orientation', 'message'],
109+
),
110+
'app-switcher': objectSchema({ action: constSchema('app-switcher'), message: stringSchema() }, [
111+
'action',
112+
'message',
113+
]),
114+
fold: objectSchema(
115+
{
116+
action: constSchema('fold'),
117+
pose: enumSchema(FOLD_POSES),
118+
hingeAngleDegrees: numberSchema('Hinge angle CoreDevice read back after the pose settled.'),
119+
screen: objectSchema(
120+
{
121+
display: stringSchema('CoreDevice name of the panel the device now lights.'),
122+
coordinateSpace: constSchema(FOLD_SCREEN_COORDINATE_SPACE),
123+
widthPt: numberSchema(
124+
'Panel width in native panel points (pixels divided by point scale), NOT snapshot coordinates; take a fresh snapshot to place a tap.',
125+
),
126+
heightPt: numberSchema(
127+
'Panel height in native panel points (pixels divided by point scale), NOT snapshot coordinates; take a fresh snapshot to place a tap.',
128+
),
129+
},
130+
['display', 'coordinateSpace', 'widthPt', 'heightPt'],
131+
),
132+
message: stringSchema(),
133+
},
134+
['action', 'pose', 'hingeAngleDegrees', 'message'],
135+
),
136+
'action-button': objectSchema({ action: constSchema('action-button'), message: stringSchema() }, [
137+
'action',
138+
'message',
139+
]),
140+
'tv-remote': objectSchema(
141+
{
142+
action: constSchema('tv-remote'),
143+
button: enumSchema(TV_REMOTE_BUTTONS),
144+
durationMs: numberSchema(),
145+
message: stringSchema(),
146+
},
147+
['action', 'button', 'message'],
148+
),
149+
// packages/contracts/src/clipboard.ts — discriminated union on `action`.
150+
clipboard: {
151+
type: 'object',
152+
oneOf: [
153+
objectSchema({ action: constSchema('read'), text: stringSchema() }, ['action', 'text']),
154+
objectSchema(
155+
{ action: constSchema('write'), textLength: numberSchema(), message: stringSchema() },
156+
['action', 'textLength', 'message'],
157+
),
158+
],
159+
},
160+
// packages/contracts/src/app-state.ts — discriminated union on `platform`.
161+
appstate: {
162+
type: 'object',
163+
oneOf: [
164+
objectSchema(
165+
{
166+
platform: enumSchema(['ios', 'macos']),
167+
appName: stringSchema(),
168+
appBundleId: stringSchema(),
169+
source: enumSchema(
170+
['session', 'runner'],
171+
'runner when a live runner read the session app state; session when the record alone answered.',
172+
),
173+
state: enumSchema(
174+
APPLE_APPLICATION_STATES,
175+
'The session app XCUIApplication state as a live runner reads it; absent with source session.',
176+
),
177+
surface: enumSchema(SESSION_SURFACES),
178+
device_udid: stringSchema('iOS only — the session device UDID.'),
179+
ios_simulator_device_set: {
180+
type: ['string', 'null'],
181+
description: 'iOS only — the simulator set path, or null when unknown.',
182+
},
183+
},
184+
['platform', 'appName', 'source', 'surface'],
185+
),
186+
objectSchema(
187+
{
188+
platform: constSchema('android'),
189+
package: stringSchema(),
190+
activity: stringSchema(),
191+
},
192+
['platform', 'package', 'activity'],
193+
),
194+
],
195+
},
196+
// packages/contracts/src/keyboard.ts — flat closed shape; `platform`/`action` always present.
197+
keyboard: objectSchema(
198+
{
199+
platform: enumSchema(['android', 'ios']),
200+
action: enumSchema(['status', 'dismiss', 'enter']),
201+
visible: booleanSchema(),
202+
wasVisible: booleanSchema(),
203+
dismissed: booleanSchema(),
204+
attempts: numberSchema(),
205+
inputType: stringSchema(),
206+
type: enumSchema(['text', 'number', 'email', 'phone', 'password', 'datetime', 'unknown']),
207+
inputMethodPackage: stringSchema(),
208+
focusedPackage: stringSchema(),
209+
focusedResourceId: stringSchema(),
210+
inputOwner: enumSchema(['app', 'ime', 'unknown']),
211+
message: stringSchema(),
212+
},
213+
['platform', 'action'],
214+
),
215+
} satisfies Pick<
216+
Record<keyof CommandResultMap, JsonSchema>,
217+
| 'back'
218+
| 'home'
219+
| 'orientation'
220+
| 'app-switcher'
221+
| 'fold'
222+
| 'action-button'
223+
| 'tv-remote'
224+
| 'clipboard'
225+
| 'appstate'
226+
| 'keyboard'
227+
>;
228+
67229
const appStateCommandDescription =
68230
'Show foreground app/activity (Android; iOS answers per command)';
69231
const backCommandDescription =

‎src/mcp/__tests__/command-tools-appstate-schema.test.ts‎

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

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

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

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

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@ import assert from 'node:assert/strict';
22
import { test } from 'vitest';
33
import type { ReplayCommandResult, ReplaySuiteResult } from '@agent-device/contracts/replay';
44
import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
5+
import { commandSupportsSettleObservation } from '@agent-device/command-registry/registry';
56
import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../../commands/replay/index.ts';
7+
import { SYSTEM_COMMAND_OUTPUT_SCHEMAS } from '../../commands/system/index.ts';
68
import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
79
import { validateAgainstSchema } from './output-schema-validator.ts';
810

@@ -66,7 +68,10 @@ test('the projected family map declares exactly the commands its module owns', (
6668
* stays the compiler's; this owns the shadowing half. Every family the seam spreads is listed here,
6769
* so registering a new family is the migration step.
6870
*/
69-
const PROJECTED_FAMILIES = [{ name: 'replay', schemas: REPLAY_COMMAND_OUTPUT_SCHEMAS }] as const;
71+
const PROJECTED_FAMILIES = [
72+
{ name: 'replay', schemas: REPLAY_COMMAND_OUTPUT_SCHEMAS },
73+
{ name: 'system', schemas: SYSTEM_COMMAND_OUTPUT_SCHEMAS },
74+
] as const;
7075

7176
test('projected output-schema families claim disjoint commands and survive the composition intact', () => {
7277
const claimedBy = new Map<string, string>();
@@ -83,11 +88,23 @@ test('projected output-schema families claim disjoint commands and survive the c
8388
}
8489
for (const family of PROJECTED_FAMILIES) {
8590
for (const [command, schema] of Object.entries(family.schemas)) {
86-
assert.equal(
87-
COMMAND_OUTPUT_SCHEMAS[command as keyof typeof COMMAND_OUTPUT_SCHEMAS],
88-
schema,
89-
`${family.name}.${command} is not the schema the map publishes`,
90-
);
91+
const published = COMMAND_OUTPUT_SCHEMAS[command as keyof typeof COMMAND_OUTPUT_SCHEMAS];
92+
// A command with the post-action observation trait (#1652) is grafted onto a COPY by
93+
// deriveSettleObservationSchemas, so it is deliberately not reference-equal here; a
94+
// trait-free command must survive the spread untouched.
95+
if (commandSupportsSettleObservation(command)) {
96+
assert.notEqual(
97+
published,
98+
schema,
99+
`${family.name}.${command} carries the settle trait but was not copied by the derivation pass`,
100+
);
101+
} else {
102+
assert.equal(
103+
published,
104+
schema,
105+
`${family.name}.${command} is not the schema the map publishes`,
106+
);
107+
}
91108
}
92109
}
93110
});

0 commit comments

Comments
 (0)