Skip to content

Commit 3d903d4

Browse files
authored
refactor(mcp): project system family output schemas from their owning module (#3014)
* 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. * fix(contracts): keep the fold coordinate-space constant off the CLI closure FOLD_SCREEN_COORDINATE_SPACE lived in fold-runtime.ts, a module the CLI closure did not otherwise load. Importing it directly from src/commands/system/index.ts pulled fold-runtime.ts (and its own dependents) into cli.ts's eager import graph, tripping the eager-closure-budgets gate (295 -> 296 modules). Move the constant's declaration to device-rotation.ts, which the same file already loads via the @agent-device/contracts/device facade for DEVICE_ROTATIONS/FOLD_POSES, and re-export it from the device facade so importers reach it there. fold-runtime.ts keeps publishing FOLD_SCREEN_COORDINATE_SPACE (an external, released API on this subpath) as a literal rather than a re-export, so importing it does not eagerly load device-rotation.ts and its own eager closure does not grow either; a type-only import of the new FoldScreenCoordinateSpace alias still makes any drift between the two a compile error. Its runtime value consumer (platform-apple's fold pose runtime) now takes the constant from the device facade it already imports. * fix(mcp): share one constSchema and prove ownership both ways constSchema was hand-copied into src/commands/system/index.ts, drifting from the identical private helper in command-output-schemas.ts. Export it once from command-input.ts, next to the other schema-primitive builders, and import it at both sites. The ownership test for the projected family map only checked that each of the module's own entries names the module as owner; it did not check the inverse, so a system-family command the registry attributes to this module but missing from SYSTEM_COMMAND_OUTPUT_SCHEMAS would still pass. Compare the two sets directly.
1 parent c0e1a7c commit 3d903d4

11 files changed

Lines changed: 405 additions & 285 deletions

‎packages/contracts/src/device-rotation.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
import { AppError } from '@agent-device/kernel/errors';
22

3+
/** Single source of truth for the discriminator the Apple owner sets and the MCP schema advertises. */
4+
export const FOLD_SCREEN_COORDINATE_SPACE = 'native-panel' as const;
5+
export type FoldScreenCoordinateSpace = typeof FOLD_SCREEN_COORDINATE_SPACE;
6+
37
export const DEVICE_ROTATIONS = [
48
'portrait',
59
'portrait-upside-down',

‎packages/contracts/src/facades/device.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ export type {
3131
export {
3232
DEVICE_ROTATIONS,
3333
DEVICE_ROTATION_SURFACE_INDEX,
34+
FOLD_SCREEN_COORDINATE_SPACE,
3435
MAX_FOLD_DURATION_MS,
3536
MAX_FOLD_KEYFRAMES,
3637
parseFoldInput,
@@ -47,6 +48,7 @@ export type {
4748
DeviceRotation,
4849
FoldPose,
4950
FoldKeyframe,
51+
FoldScreenCoordinateSpace,
5052
SetFoldPoseInput,
5153
} from '../device-rotation.ts';
5254
export type { BootCommandResult, ShutdownCommandResult } from '../device.ts';

‎packages/contracts/src/fold-runtime.ts‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
1-
import type { FoldPose, SetFoldPoseInput } from './device-rotation.ts';
1+
import type { FoldPose, FoldScreenCoordinateSpace, SetFoldPoseInput } from './device-rotation.ts';
22
import type { RuntimeOperationFact } from './platform-runtime.ts';
33

4-
/** Single source of truth for the discriminator the Apple owner sets and the MCP schema advertises. */
5-
export const FOLD_SCREEN_COORDINATE_SPACE = 'native-panel' as const;
4+
/**
5+
* Mirrors `device-rotation.ts`'s `FOLD_SCREEN_COORDINATE_SPACE` (the single source of truth) as a
6+
* literal rather than a re-export, so importing this published subpath does not also eagerly load
7+
* `device-rotation.ts`. The `FoldScreenCoordinateSpace` type import above still makes any drift
8+
* between the two a compile error.
9+
*/
10+
export const FOLD_SCREEN_COORDINATE_SPACE: FoldScreenCoordinateSpace = 'native-panel';
611

712
/**
813
* The panel the device lights after the pose settled, in that panel's own native points: its pixel
914
* size divided by its point scale, never rotated. `coordinateSpace` is always
10-
* {@link FOLD_SCREEN_COORDINATE_SPACE}, and these numbers are NOT snapshot coordinates — the active
15+
* {@link FoldScreenCoordinateSpace}, and these numbers are NOT snapshot coordinates — the active
1116
* app window can differ from the panel (iPhone Duo: a 669x951 inner panel hosts a 951x669 app
1217
* window), so they cannot place a tap. A caller that needs the app viewport must take a fresh
1318
* snapshot.
@@ -16,7 +21,7 @@ export type FoldScreenReport = Readonly<{
1621
/** The CoreDevice display name of the panel the device now lights. */
1722
display: string;
1823
/** Marks these dimensions as the panel's native points, never a snapshot's app viewport. */
19-
coordinateSpace: typeof FOLD_SCREEN_COORDINATE_SPACE;
24+
coordinateSpace: FoldScreenCoordinateSpace;
2025
widthPt: number;
2126
heightPt: number;
2227
}>;

‎packages/platform-apple/src/foldable/pose.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
11
import {
22
type SetFoldPoseInput,
33
foldPoseForHingeAngle,
4+
FOLD_SCREEN_COORDINATE_SPACE,
45
type FoldPose,
56
} from '@agent-device/contracts/device';
6-
import {
7-
FOLD_SCREEN_COORDINATE_SPACE,
8-
type FoldScreenReport,
9-
type SetFoldPoseResult,
10-
} from '@agent-device/contracts/fold-runtime';
7+
import type { FoldScreenReport, SetFoldPoseResult } from '@agent-device/contracts/fold-runtime';
118
import type { DeviceInfo } from '@agent-device/kernel/device';
129
import { AppError } from '@agent-device/kernel/errors';
1310
import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';

‎src/commands/command-input.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,11 @@ export function enumSchema(values: readonly string[], description?: string): Jso
106106
return { type: 'string', enum: values, ...(description ? { description } : {}) };
107107
}
108108

109+
/** A single-valued string schema, for a discriminant field an output shape always fixes. */
110+
export function constSchema(value: string): JsonSchema {
111+
return { type: 'string', const: value };
112+
}
113+
109114
export function stringSchema(description?: string): JsonSchema {
110115
return { type: 'string', ...(description ? { description } : {}) };
111116
}

‎src/commands/system/index.ts‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
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,
6+
FOLD_SCREEN_COORDINATE_SPACE,
57
MAX_FOLD_DURATION_MS,
68
MAX_FOLD_KEYFRAMES,
79
parseFoldInput,
@@ -18,6 +20,8 @@ import {
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,20 @@ 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+
constSchema,
45+
enumSchema,
46+
numberSchema,
47+
objectSchema,
48+
stringSchema,
3849
} from '../command-input.ts';
3950
import { compactRecord } from '../input-readers.ts';
4051
import {
@@ -64,6 +75,154 @@ const TV_REMOTE_LONGPRESS_PRESET_MS = 500;
6475
const CLIPBOARD_ACTION_VALUES = ['read', 'write'] as const;
6576
const KEYBOARD_METADATA_ACTION_VALUES = ['status', 'dismiss', 'enter', 'return'] as const;
6677

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

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

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

0 commit comments

Comments
 (0)