Skip to content

Commit 7579026

Browse files
feat: project navigation client and MCP contracts from executable definitions
Collapse the three independent per-command projection declarations (facet clientMethod, public client method signature, MCP output schema) for the typed system navigation subset (home, back, rotate, app-switcher, tv-remote) onto a single colocated projection in src/contracts/navigation.ts. The family builder, public client type, and MCP schema map now derive from those five projections. Refs #1185 Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
1 parent db21b56 commit 7579026

10 files changed

Lines changed: 324 additions & 84 deletions

File tree

‎docs/agents/contract-projection-output-economy-spike.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,3 +75,22 @@ failed request remains identifiable and actionable from the digest.
7575

7676
The merge-base size baseline is 1,659,106 raw JS bytes, 529,658 gzip bytes, and 636,721 tarball
7777
bytes on Node 24.13.0.
78+
79+
## Contract projection results (#1185)
80+
81+
The five selected navigation commands now carry one colocated projection declaration each in
82+
`src/commands/system/navigation-projection.ts` (`NAVIGATION_COMMAND_PROJECTIONS`): client-method name, public option
83+
shape, closed result type, and MCP `outputSchema`. The family builder derives `clientCommandMethods`
84+
from those projections, `AgentDeviceCommandClient` derives the five navigation methods via
85+
`ProjectedNavigationCommandClient`, and `COMMAND_OUTPUT_SCHEMAS` spreads the projected schemas.
86+
87+
- Declarations: 15 -> 5 (10 fewer). Removed the per-command facet `clientMethod`, the hand-written
88+
client method signature, and the hand-authored MCP schema entry.
89+
- Behavior: CLI, daemon, client runtime, and MCP output schemas unchanged (unit/client/MCP tests pass).
90+
- Bundle: +773 B raw JS, +146 B gzip, +620 B tarball; no material chunk regression, no dependency change.
91+
- Runtime: CLI --version 20.3 ms / --help 39.5 ms median (20 runs); no cold-start regression.
92+
- Layering/Fallow: green; no new value back-edge (type-only import from client, value import only
93+
from the already-command-importing MCP schema map).
94+
95+
Recommendation: #1185 should CONTINUE incrementally, one already-typed closed-contract family at a
96+
time, re-measuring declarations and bundle each step and stopping on any stop condition.

‎src/agent-device-client.ts‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -64,11 +64,10 @@ import { readSerializedSnapshotCaptureAnnotations } from './snapshot-capture-ann
6464
import { readSnapshotDiagnosticsSummary } from './snapshot-diagnostics.ts';
6565
import type { CommandFlags } from './core/dispatch-context.ts';
6666
import type { AgentArtifactsResult } from './cloud-artifacts.ts';
67+
import type { ProjectedNavigationCommandClient } from './commands/system/navigation-projection.ts';
6768

68-
type ProjectedSystemCommandClient = Pick<
69-
AgentDeviceCommandClient,
70-
'appState' | 'back' | 'home' | 'rotate' | 'appSwitcher' | 'keyboard' | 'clipboard' | 'tvRemote'
71-
>;
69+
type ProjectedSystemCommandClient = ProjectedNavigationCommandClient<InternalRequestOptions> &
70+
Pick<AgentDeviceCommandClient, 'appState' | 'keyboard' | 'clipboard'>;
7271

7372
export function createAgentDeviceClient(
7473
config: AgentDeviceClientConfig = {},

‎src/client/client-types.ts‎

Lines changed: 14 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,17 @@ import type { BackMode } from '../contracts/back-mode.ts';
2323
import type { ClickButton } from '../core/click-button.ts';
2424
import type { RecordingExportQuality } from '../core/recording-export-quality.ts';
2525
import type { RecordingScope } from '../contracts/recording-scope.ts';
26-
import type { DeviceRotation } from '../contracts/device-rotation.ts';
27-
import type { TvRemoteButton } from '../contracts/tv-remote.ts';
2826
import type {
2927
ScrollDirection,
3028
SwipePattern,
3129
SwipePreset,
3230
TransformGestureParams,
3331
} from '../contracts/scroll-gesture.ts';
3432
import type { ScrollInputDirection } from '../commands/interaction/runtime/gestures.ts';
33+
import type {
34+
NavigationCommandOptions,
35+
ProjectedNavigationCommandClient,
36+
} from '../commands/system/navigation-projection.ts';
3537
import type { LogAction } from '../contracts/logs.ts';
3638
import type { SessionSurface } from '../contracts/session-surface.ts';
3739
import type { FindLocator } from '../selectors/find.ts';
@@ -534,17 +536,12 @@ export type AlertCommandResult = DaemonResponseData & {
534536

535537
export type AppStateCommandOptions = DeviceCommandBaseOptions;
536538

537-
export type BackCommandOptions = DeviceCommandBaseOptions & {
538-
mode?: BackMode;
539-
};
540-
541-
type HomeCommandOptions = DeviceCommandBaseOptions;
539+
export type BackCommandOptions = DeviceCommandBaseOptions & NavigationCommandOptions<'back'>;
542540

543-
export type RotateCommandOptions = DeviceCommandBaseOptions & {
544-
orientation: DeviceRotation;
545-
};
541+
export type RotateCommandOptions = DeviceCommandBaseOptions & NavigationCommandOptions<'rotate'>;
546542

547-
export type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
543+
export type AppSwitcherCommandOptions = DeviceCommandBaseOptions &
544+
NavigationCommandOptions<'app-switcher'>;
548545

549546
export type KeyboardCommandOptions = DeviceCommandBaseOptions & {
550547
action?: 'status' | 'dismiss' | 'enter' | 'return';
@@ -559,10 +556,8 @@ export type ClipboardCommandOptions =
559556
text: string;
560557
});
561558

562-
export type TvRemoteCommandOptions = DeviceCommandBaseOptions & {
563-
button: TvRemoteButton;
564-
durationMs?: number;
565-
};
559+
export type TvRemoteCommandOptions = DeviceCommandBaseOptions &
560+
NavigationCommandOptions<'tv-remote'>;
566561

567562
export type ReactNativeCommandOptions = DeviceCommandBaseOptions & {
568563
action: 'dismiss-overlay';
@@ -583,17 +578,12 @@ export type ViewportCommandOptions = DeviceCommandBaseOptions & {
583578
height: number;
584579
};
585580

586-
export type AgentDeviceCommandClient = {
581+
type NonNavigationCommandClient = {
587582
wait: (options: WaitCommandOptions) => Promise<CommandResult<'wait'>>;
588583
alert: (options?: AlertCommandOptions) => Promise<CommandRequestResult>;
589584
appState: (options?: AppStateCommandOptions) => Promise<CommandResult<'appstate'>>;
590-
back: (options?: BackCommandOptions) => Promise<CommandResult<'back'>>;
591-
home: (options?: HomeCommandOptions) => Promise<CommandResult<'home'>>;
592-
rotate: (options: RotateCommandOptions) => Promise<CommandResult<'rotate'>>;
593-
appSwitcher: (options?: AppSwitcherCommandOptions) => Promise<CommandResult<'app-switcher'>>;
594585
keyboard: (options?: KeyboardCommandOptions) => Promise<CommandResult<'keyboard'>>;
595586
clipboard: (options: ClipboardCommandOptions) => Promise<CommandResult<'clipboard'>>;
596-
tvRemote: (options: TvRemoteCommandOptions) => Promise<CommandResult<'tv-remote'>>;
597587
reactNative: (options: ReactNativeCommandOptions) => Promise<CommandRequestResult>;
598588
doctor: (options?: DoctorCommandOptions) => Promise<CommandResult<'doctor'>>;
599589
/**
@@ -604,6 +594,9 @@ export type AgentDeviceCommandClient = {
604594
viewport: (options: ViewportCommandOptions) => Promise<CommandResult<'viewport'>>;
605595
};
606596

597+
export type AgentDeviceCommandClient = ProjectedNavigationCommandClient<DeviceCommandBaseOptions> &
598+
NonNavigationCommandClient;
599+
607600
type SelectorSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'scope' | 'raw'>;
608601
type FindSnapshotCommandOptions = Pick<CaptureSnapshotOptions, 'depth' | 'raw'>;
609602

‎src/commands/command-contract.ts‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,11 @@ export type ExecutableCommandContract<Name extends string, Input, Result> = Comm
3030
invoke: (client: AgentDeviceClient, input: unknown) => Promise<Result>;
3131
};
3232

33+
export type ExecutableCommandProjection<ClientMethod extends string = string> = {
34+
clientMethod: ClientMethod;
35+
outputSchema: JsonSchema;
36+
};
37+
3338
export type CliOutput = {
3439
data: unknown;
3540
jsonData?: unknown;
@@ -46,10 +51,32 @@ export function defineCommandMetadata<Name extends string, Input>(
4651
export function defineExecutableCommand<Name extends string, Input, Result>(
4752
metadata: CommandMetadata<Name, Input>,
4853
run: (client: AgentDeviceClient, input: Input) => Promise<Result>,
49-
): ExecutableCommandContract<Name, Input, Result> {
54+
): ExecutableCommandContract<Name, Input, Result>;
55+
56+
export function defineExecutableCommand<
57+
Name extends string,
58+
Input,
59+
Result,
60+
const ClientMethod extends string,
61+
>(
62+
metadata: CommandMetadata<Name, Input>,
63+
run: (client: AgentDeviceClient, input: Input) => Promise<Result>,
64+
projection: ExecutableCommandProjection<ClientMethod>,
65+
): ExecutableCommandContract<Name, Input, Result> & {
66+
projection: ExecutableCommandProjection<ClientMethod>;
67+
};
68+
69+
export function defineExecutableCommand<Name extends string, Input, Result>(
70+
metadata: CommandMetadata<Name, Input>,
71+
run: (client: AgentDeviceClient, input: Input) => Promise<Result>,
72+
projection?: ExecutableCommandProjection,
73+
): ExecutableCommandContract<Name, Input, Result> & {
74+
projection?: ExecutableCommandProjection;
75+
} {
5076
return {
5177
...metadata,
5278
run,
5379
invoke: async (client, input) => await run(client, metadata.readInput(input)),
80+
...(projection ? { projection } : {}),
5481
};
5582
}

‎src/commands/family/types.ts‎

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
import type { AgentDeviceClient } from '../../client/client-types.ts';
22
import type { CommandSchemaOverride } from '../../cli-schema/types.ts';
33
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
4-
import type { CommandMetadata, JsonSchema } from '../command-contract.ts';
4+
import type {
5+
CommandMetadata,
6+
ExecutableCommandProjection,
7+
JsonSchema,
8+
} from '../command-contract.ts';
59
import type { CliOutputFormatter } from '../output-common.ts';
610

711
export type AnyCommandMetadata<Name extends string = string> = CommandMetadata<Name, unknown>;
@@ -11,6 +15,7 @@ export type AnyCommandDefinition<Name extends string = string> = {
1115
description: string;
1216
inputSchema: JsonSchema;
1317
invoke: (client: AgentDeviceClient, input: unknown) => Promise<unknown>;
18+
projection?: ExecutableCommandProjection;
1419
};
1520

1621
export type CommandFamilyFacet<TCommandName extends string = string> = {
@@ -47,6 +52,13 @@ type CommandFacetDefinitions<TCommands extends readonly CommandFacet[]> = {
4752

4853
type CommandFacetName<TCommands extends readonly CommandFacet[]> = TCommands[number]['name'];
4954

55+
export type ProjectedCommandOutputSchemas<TDefinitions extends readonly AnyCommandDefinition[]> = {
56+
[TDefinition in Extract<
57+
TDefinitions[number],
58+
{ projection: ExecutableCommandProjection }
59+
> as TDefinition['name']]: JsonSchema;
60+
};
61+
5062
export function defineCommandFacet<
5163
const TCommandName extends string,
5264
const TCommand extends CommandFacet<TCommandName>,
@@ -68,13 +80,9 @@ export function defineCommandFamilyFromFacets<
6880
if (command.cliSchema) {
6981
addRecordEntry(cliSchemas, 'CLI schema', command.name, command.cliSchema);
7082
}
71-
if (command.clientMethod) {
72-
addRecordEntry(
73-
clientCommandMethods,
74-
'client command method',
75-
command.clientMethod,
76-
command.name,
77-
);
83+
const clientMethod = command.definition.projection?.clientMethod ?? command.clientMethod;
84+
if (clientMethod) {
85+
addRecordEntry(clientCommandMethods, 'client command method', clientMethod, command.name);
7886
}
7987
addRecordEntry(cliReaders, 'CLI reader', command.name, command.cliReader);
8088
if (command.daemonWriter) {
@@ -115,6 +123,23 @@ export function defineCommandFamilyFromFacets<
115123
};
116124
}
117125

126+
export function projectCommandOutputSchemas<
127+
const TDefinitions extends readonly AnyCommandDefinition[],
128+
>(definitions: TDefinitions): ProjectedCommandOutputSchemas<TDefinitions> {
129+
const schemas: Record<string, JsonSchema> = {};
130+
for (const definition of definitions) {
131+
if (definition.projection) {
132+
addRecordEntry(
133+
schemas,
134+
'command output schema',
135+
definition.name,
136+
definition.projection.outputSchema,
137+
);
138+
}
139+
}
140+
return schemas as ProjectedCommandOutputSchemas<TDefinitions>;
141+
}
142+
118143
function addRecordEntry<TValue>(
119144
record: Record<string, TValue>,
120145
label: string,

‎src/commands/system/index.test.ts‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
1-
import { describe, expect, test } from 'vitest';
1+
import { describe, expect, expectTypeOf, test } from 'vitest';
2+
import type {
3+
AgentDeviceCommandClient,
4+
AppSwitcherCommandOptions,
5+
BackCommandOptions,
6+
RotateCommandOptions,
7+
TvRemoteCommandOptions,
8+
} from '../../client/client-types.ts';
9+
import type { CommandResult } from '../../core/command-descriptor/command-result.ts';
210
import type { CliFlags } from '../cli-grammar/flag-types.ts';
311
import {
412
appStateCliReader,
@@ -34,6 +42,21 @@ function expectInvalidArgs(fn: () => unknown, messageFragment: string) {
3442
}
3543

3644
describe('system command interface', () => {
45+
test('navigation executable contracts project the public client signatures', () => {
46+
expectTypeOf<AgentDeviceCommandClient['back']>().toEqualTypeOf<
47+
(options?: BackCommandOptions) => Promise<CommandResult<'back'>>
48+
>();
49+
expectTypeOf<AgentDeviceCommandClient['rotate']>().toEqualTypeOf<
50+
(options: RotateCommandOptions) => Promise<CommandResult<'rotate'>>
51+
>();
52+
expectTypeOf<AgentDeviceCommandClient['appSwitcher']>().toEqualTypeOf<
53+
(options?: AppSwitcherCommandOptions) => Promise<CommandResult<'app-switcher'>>
54+
>();
55+
expectTypeOf<AgentDeviceCommandClient['tvRemote']>().toEqualTypeOf<
56+
(options: TvRemoteCommandOptions) => Promise<CommandResult<'tv-remote'>>
57+
>();
58+
});
59+
3760
test('system command family projects Node client command methods', () => {
3861
expect(systemCommandFamily.clientCommandMethods).toEqual({
3962
appState: 'appstate',
@@ -47,6 +70,22 @@ describe('system command interface', () => {
4770
});
4871
});
4972

73+
test('navigation executable contracts own their MCP output schemas', () => {
74+
expect(
75+
Object.fromEntries(
76+
systemCommandFamily.definitions.flatMap((definition) =>
77+
'projection' in definition ? [[definition.name, definition.projection.clientMethod]] : [],
78+
),
79+
),
80+
).toEqual({
81+
back: 'back',
82+
home: 'home',
83+
rotate: 'rotate',
84+
'app-switcher': 'appSwitcher',
85+
'tv-remote': 'tvRemote',
86+
});
87+
});
88+
5089
test('parameterless readers project common selection flags through', () => {
5190
for (const reader of [appStateCliReader, homeCliReader, appSwitcherCliReader]) {
5291
expect(reader([], flags({ platform: 'ios' }))).toEqual({

0 commit comments

Comments
 (0)