11import { FOLD_FLAGS } from '@agent-device/command-registry/flag-groups' ;
2+ import type { CommandResultMap } from '@agent-device/command-registry/command-result' ;
23import type { ClipboardCommandOptions } from '@agent-device/contracts/client' ;
34import {
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' ;
1416import { type BackMode , BACK_MODES } from '@agent-device/contracts/back-mode' ;
1517import {
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' ;
2125import { AppError } from '@agent-device/kernel/errors' ;
2226import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema' ;
2327import {
@@ -28,13 +32,19 @@ import {
2832 requiredDaemonString ,
2933} from '../cli-grammar/common.ts' ;
3034import type { CliReader , DaemonWriter } from '../cli-grammar/types.ts' ;
35+ import type { JsonSchema } from '../command-contract.ts' ;
3136import {
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' ;
3949import { compactRecord } from '../input-readers.ts' ;
4050import {
@@ -64,6 +74,158 @@ const TV_REMOTE_LONGPRESS_PRESET_MS = 500;
6474const CLIPBOARD_ACTION_VALUES = [ 'read' , 'write' ] as const ;
6575const 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+
67229const appStateCommandDescription =
68230 'Show foreground app/activity (Android; iOS answers per command)' ;
69231const backCommandDescription =
0 commit comments