Skip to content

Commit ae21067

Browse files
fix(mcp): advertise public Apple platform leaves in boot/shutdown/prepare output schemas (callstack#1224)
The boot and shutdown MCP outputSchemas (and the non-exposed prepare schema) enumerated the internal PLATFORMS vocabulary (apple | android | linux | web), while the command contracts and runtime emit PublicPlatform (ios | macos | android | linux | web). Point the schemas at PUBLIC_PLATFORMS so a valid ios/macos result validates and the internal apple identity is never advertised on these public result fields. Add a focused, non-strict JSON Schema validator and use it to validate representative ios/macos structured content against the complete advertised schema (enums/consts + nested required), with negative coverage for the internal apple value, unknown enum values, the booted const, and a missing nested field. Closes callstack#1219 Co-authored-by: Michał Pierzchała <[email protected]> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
1 parent 260ec45 commit ae21067

3 files changed

Lines changed: 243 additions & 3 deletions

File tree

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { createCommandToolExecutor, listCommandTools } from '../command-tools.ts
55
import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
66
import { AppError } from '../../kernel/errors.ts';
77
import { NAVIGATION_COMMAND_PROJECTIONS } from '../../commands/system/navigation-projection.ts';
8+
import { validateAgainstSchema } from './output-schema-validator.ts';
89

910
test('MCP command tool executor hides client creation behind an execution adapter', async () => {
1011
const client = {} as AgentDeviceClient;
@@ -379,6 +380,136 @@ test('MCP boot structuredContent is consistent with its advertised outputSchema'
379380
assert.deepEqual(result.structuredContent, bootResult);
380381
});
381382

383+
// --- #1219 public Apple platform parity in MCP output schemas ---
384+
// These validate representative structured content against the COMPLETE
385+
// advertised schema (enums/consts and nested required fields), not just the
386+
// presence of required keys, and pin the negative cases the required-only check
387+
// silently accepted.
388+
389+
function bootResultFor(platform: 'ios' | 'macos') {
390+
return {
391+
platform,
392+
target: platform === 'macos' ? 'desktop' : 'mobile',
393+
device: platform === 'macos' ? 'My Mac' : 'iPhone 16',
394+
id: 'UDID-123',
395+
kind: platform === 'macos' ? 'device' : 'simulator',
396+
booted: true,
397+
// Additive Apple-OS discriminant rides alongside the leaf platform.
398+
appleOs: platform,
399+
} as const;
400+
}
401+
402+
function shutdownResultFor(platform: 'ios' | 'macos') {
403+
const { platform: leaf, target, device, id, kind, appleOs } = bootResultFor(platform);
404+
return {
405+
platform: leaf,
406+
target,
407+
device,
408+
id,
409+
kind,
410+
appleOs,
411+
shutdown: { success: true, exitCode: 0, stdout: '', stderr: '' },
412+
};
413+
}
414+
415+
function prepareResultFor(platform: 'ios' | 'macos') {
416+
return {
417+
action: 'ios-runner',
418+
platform,
419+
deviceId: 'UDID-123',
420+
deviceName: 'iPhone 16',
421+
kind: 'simulator',
422+
durationMs: 1200,
423+
runner: {},
424+
connectMs: 100,
425+
healthCheckMs: 50,
426+
timing: {
427+
totalMs: 1200,
428+
additiveParts: { connectAfterBuildMs: 100, healthCheckMs: 50 },
429+
containment: { healthCheckMs: [] },
430+
note: 'ok',
431+
},
432+
message: 'prepared',
433+
};
434+
}
435+
436+
test('MCP boot/shutdown schemas advertise public Apple leaves, never internal apple', () => {
437+
const platformEnum = COMMAND_OUTPUT_SCHEMAS.boot.properties?.platform?.enum;
438+
assert.deepEqual(platformEnum, ['ios', 'macos', 'android', 'linux', 'web']);
439+
assert.equal(platformEnum?.includes('apple'), false);
440+
// shutdown shares the same resolved-device header.
441+
assert.deepEqual(COMMAND_OUTPUT_SCHEMAS.shutdown.properties?.platform?.enum, platformEnum);
442+
});
443+
444+
test('MCP valid ios/macos boot results satisfy the complete boot schema', () => {
445+
for (const platform of ['ios', 'macos'] as const) {
446+
assert.deepEqual(
447+
validateAgainstSchema(bootResultFor(platform), COMMAND_OUTPUT_SCHEMAS.boot),
448+
[],
449+
);
450+
}
451+
});
452+
453+
test('MCP valid ios/macos shutdown results satisfy the complete shutdown schema', () => {
454+
for (const platform of ['ios', 'macos'] as const) {
455+
assert.deepEqual(
456+
validateAgainstSchema(shutdownResultFor(platform), COMMAND_OUTPUT_SCHEMAS.shutdown),
457+
[],
458+
);
459+
}
460+
});
461+
462+
test('MCP boot schema rejects the internal apple platform and unknown enum values', () => {
463+
// Internal identity must not be advertised on the public result field.
464+
assert.notDeepEqual(
465+
validateAgainstSchema(
466+
{ ...bootResultFor('ios'), platform: 'apple' },
467+
COMMAND_OUTPUT_SCHEMAS.boot,
468+
),
469+
[],
470+
);
471+
assert.notDeepEqual(
472+
validateAgainstSchema(
473+
{ ...bootResultFor('ios'), platform: 'windows' },
474+
COMMAND_OUTPUT_SCHEMAS.boot,
475+
),
476+
[],
477+
);
478+
// The `booted` discriminant is a const true; a false value fails the schema.
479+
assert.notDeepEqual(
480+
validateAgainstSchema({ ...bootResultFor('ios'), booted: false }, COMMAND_OUTPUT_SCHEMAS.boot),
481+
[],
482+
);
483+
// A missing nested-required shutdown field (stderr) fails validation.
484+
assert.notDeepEqual(
485+
validateAgainstSchema(
486+
{ ...shutdownResultFor('ios'), shutdown: { success: true, exitCode: 0, stdout: '' } },
487+
COMMAND_OUTPUT_SCHEMAS.shutdown,
488+
),
489+
[],
490+
);
491+
});
492+
493+
test('MCP prepare schema mirrors its PublicPlatform contract', () => {
494+
const platformEnum = COMMAND_OUTPUT_SCHEMAS.prepare.properties?.platform?.enum;
495+
assert.deepEqual(platformEnum, ['ios', 'macos', 'android', 'linux', 'web']);
496+
assert.equal(platformEnum?.includes('apple'), false);
497+
498+
for (const platform of ['ios', 'macos'] as const) {
499+
assert.deepEqual(
500+
validateAgainstSchema(prepareResultFor(platform), COMMAND_OUTPUT_SCHEMAS.prepare),
501+
[],
502+
);
503+
}
504+
assert.notDeepEqual(
505+
validateAgainstSchema(
506+
{ ...prepareResultFor('ios'), platform: 'apple' },
507+
COMMAND_OUTPUT_SCHEMAS.prepare,
508+
),
509+
[],
510+
);
511+
});
512+
382513
test('MCP session tool exposes state-dir resolution without a daemon round-trip', async () => {
383514
const sessionTool = listCommandTools().find((tool) => tool.name === 'session');
384515
assert.ok(sessionTool);
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
import type { JsonSchema } from '../../commands/command-contract.ts';
2+
3+
/**
4+
* A focused JSON Schema validator for the MCP `outputSchema` dialect actually
5+
* used by COMMAND_OUTPUT_SCHEMAS: `type` (including union type arrays), `enum`,
6+
* `const`, `required`, `properties`, `items`, and `oneOf`. It exists so the
7+
* command-tools tests can validate representative structured content against the
8+
* COMPLETE advertised schema — enums/consts and nested required fields — rather
9+
* than only checking that required keys are present.
10+
*
11+
* It is intentionally NON-STRICT: unknown properties are allowed (mirroring the
12+
* schemas' deliberate absence of `additionalProperties: false`, so additive
13+
* fields such as `cost` validate). It is a test helper, not a schema generator.
14+
*/
15+
export function validateAgainstSchema(value: unknown, schema: JsonSchema): string[] {
16+
return collectErrors(value, schema, '$');
17+
}
18+
19+
/** Convenience predicate for the common "does it validate at all" assertion. */
20+
export function matchesSchema(value: unknown, schema: JsonSchema): boolean {
21+
return collectErrors(value, schema, '$').length === 0;
22+
}
23+
24+
function collectErrors(value: unknown, schema: JsonSchema, path: string): string[] {
25+
if (schema.oneOf) return oneOfErrors(value, schema.oneOf, path);
26+
27+
const errors = [...constErrors(value, schema, path), ...enumErrors(value, schema, path)];
28+
29+
if (schema.type !== undefined && !matchesType(value, schema.type)) {
30+
errors.push(
31+
`${path}: expected type ${JSON.stringify(schema.type)}, got ${describeType(value)}`,
32+
);
33+
return errors;
34+
}
35+
36+
errors.push(...objectErrors(value, schema, path), ...arrayErrors(value, schema, path));
37+
return errors;
38+
}
39+
40+
function oneOfErrors(value: unknown, branches: readonly JsonSchema[], path: string): string[] {
41+
const matching = branches.filter((branch) => collectErrors(value, branch, path).length === 0);
42+
if (matching.length === 1) return [];
43+
return [`${path}: expected to match exactly one oneOf branch, matched ${matching.length}`];
44+
}
45+
46+
function constErrors(value: unknown, schema: JsonSchema, path: string): string[] {
47+
if (!('const' in schema) || value === schema.const) return [];
48+
return [`${path}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`];
49+
}
50+
51+
function enumErrors(value: unknown, schema: JsonSchema, path: string): string[] {
52+
if (!schema.enum || schema.enum.includes(value)) return [];
53+
return [`${path}: ${JSON.stringify(value)} is not one of ${JSON.stringify(schema.enum)}`];
54+
}
55+
56+
function objectErrors(value: unknown, schema: JsonSchema, path: string): string[] {
57+
if (!isPlainObject(value)) return [];
58+
const errors: string[] = [];
59+
for (const key of schema.required ?? []) {
60+
if (!(key in value)) errors.push(`${path}.${key}: missing required property`);
61+
}
62+
for (const [key, propSchema] of Object.entries(schema.properties ?? {})) {
63+
if (key in value) errors.push(...collectErrors(value[key], propSchema, `${path}.${key}`));
64+
}
65+
return errors;
66+
}
67+
68+
function arrayErrors(value: unknown, schema: JsonSchema, path: string): string[] {
69+
if (!Array.isArray(value) || !schema.items) return [];
70+
const items = schema.items;
71+
return value.flatMap((item, index) => collectErrors(item, items, `${path}[${index}]`));
72+
}
73+
74+
function matchesType(value: unknown, type: string | readonly string[]): boolean {
75+
const types = Array.isArray(type) ? type : [type];
76+
return types.some((candidate) => matchesSingleType(value, candidate));
77+
}
78+
79+
function matchesSingleType(value: unknown, type: string): boolean {
80+
switch (type) {
81+
case 'object':
82+
return isPlainObject(value);
83+
case 'array':
84+
return Array.isArray(value);
85+
case 'string':
86+
return typeof value === 'string';
87+
case 'number':
88+
return typeof value === 'number';
89+
case 'boolean':
90+
return typeof value === 'boolean';
91+
case 'null':
92+
return value === null;
93+
default:
94+
return false;
95+
}
96+
}
97+
98+
function describeType(value: unknown): string {
99+
if (value === null) return 'null';
100+
if (Array.isArray(value)) return 'array';
101+
return typeof value;
102+
}
103+
104+
function isPlainObject(value: unknown): value is Record<string, unknown> {
105+
return typeof value === 'object' && value !== null && !Array.isArray(value);
106+
}

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { projectedSystemCommandOutputSchemas } from '../commands/system/index.ts
33
import type { CommandResultMap } from '../core/command-descriptor/command-result.ts';
44
import { booleanSchema, looseObjectSchema, stringSchema } from '../commands/command-input.ts';
55
import { SESSION_SURFACES } from '../contracts/session-surface.ts';
6-
import { DEVICE_TARGETS, PLATFORMS } from '../kernel/device.ts';
6+
import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '../kernel/device.ts';
77

88
/**
99
* Registry of per-command MCP `outputSchema`s, keyed by the daemon command
@@ -260,7 +260,9 @@ const settleObservationSchema: JsonSchema = objectSchema(
260260

261261
// boot / shutdown share the resolved-device header (src/contracts/device.ts).
262262
const deviceHeaderProperties: Record<string, JsonSchema> = {
263-
platform: enumSchema(PLATFORMS),
263+
// Public leaf vocabulary (ios | macos | android | linux | web): boot/shutdown
264+
// emit publicPlatformString, never the internal `apple` platform.
265+
platform: enumSchema(PUBLIC_PLATFORMS),
264266
target: enumSchema(DEVICE_TARGETS),
265267
device: stringSchema('Human-readable device name.'),
266268
id: stringSchema('Stable device id.'),
@@ -353,7 +355,8 @@ export const COMMAND_OUTPUT_SCHEMAS = {
353355
prepare: objectSchema(
354356
{
355357
action: constSchema('ios-runner'),
356-
platform: enumSchema(PLATFORMS),
358+
// PublicPlatform leaf, mirroring PrepareCommandResult (src/contracts/prepare.ts).
359+
platform: enumSchema(PUBLIC_PLATFORMS),
357360
deviceId: stringSchema(),
358361
deviceName: stringSchema(),
359362
kind: enumSchema(DEVICE_KINDS),

0 commit comments

Comments
 (0)