Skip to content

Commit 1c5ae11

Browse files
committed
refactor(mcp): project recording family output schemas from their owning module
Moves the 2 hand-authored MCP outputSchema entries for record and trace out of command-output-schemas.ts into a frozen RECORDING_COMMAND_OUTPUT_SCHEMAS map exported from src/commands/recording/index.ts, following the #2810 projection seam already used by the replay, system, interaction, device-management, and push-management families on this stack. Registers the family in the PROJECTED_FAMILIES disjointness check and extends the pre-existing command-tools-recording-schemas.test.ts with a reference-equality proof against the module object and an owner-file check, matching the pattern from the other projected families. Neither command carries the post-action observation trait, so no settle-graft copy applies here. The moved code is byte-identical to what command-output-schemas.ts held: same objectSchema/stringSchema/enumSchema calls and field order, with a locally duplicated constSchema helper and artifactSchema object matching the precedent from the other families' moves (artifactSchema had no other consumer in command-output-schemas.ts once record/trace moved, so it moved outright rather than staying duplicated). Part of #2819.
1 parent c6c6834 commit 1c5ae11

4 files changed

Lines changed: 127 additions & 77 deletions

File tree

‎src/commands/recording/index.ts‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,118 @@ import {
77
RECORDING_EXPORT_QUALITIES,
88
RECORDING_SCOPE_VALUES,
99
} from '@agent-device/contracts/recording';
10+
import { NATIVE_PATH_DISPOSITION_VALUES } from '@agent-device/contracts/recording-native-path';
11+
import { RECORDER_OBSERVATION_VALUES } from '@agent-device/contracts/recording-stop-observation';
1012
import { AppError } from '@agent-device/kernel/errors';
1113
import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema';
14+
import type { CommandResultMap } from '@agent-device/command-registry/command-result';
1215
import type { FlagKey } from '@agent-device/command-registry/flag-types';
1316
import { commonInputFromFlags, direct, optionalString } from '../cli-grammar/common.ts';
1417
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
18+
import type { JsonSchema } from '../command-contract.ts';
1519
import {
1620
booleanField,
21+
booleanSchema,
22+
constSchema,
1723
enumField,
24+
enumSchema,
1825
integerField,
26+
numberSchema,
27+
objectSchema,
28+
looseObjectSchema,
1929
requiredField,
2030
retiredField,
2131
stringField,
32+
stringSchema,
2233
} from '../command-input.ts';
2334
import { defineCommandFacet, defineCommandFamilyFromFacets } from '../family/types.ts';
2435
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
2536
import { recordingCliOutputFormatters } from './output.ts';
2637

38+
const artifactSchema = objectSchema(
39+
{
40+
field: stringSchema(),
41+
artifactType: stringSchema(),
42+
path: stringSchema(),
43+
localPath: stringSchema(),
44+
fileName: stringSchema(),
45+
},
46+
['field'],
47+
);
48+
49+
/**
50+
* This family's advertised MCP `outputSchema`s, keyed by daemon command name and projected into
51+
* the command map by `src/mcp/command-output-schemas.ts`. Non-strict like every other entry: no
52+
* `additionalProperties: false`, so additive response fields keep validating. Neither command
53+
* carries the post-action observation trait (#1652): both fire-and-report a recording or trace
54+
* lifecycle change, not an interaction, so no settle-graft copy applies here.
55+
*/
56+
export const RECORDING_COMMAND_OUTPUT_SCHEMAS = {
57+
// packages/contracts/src/recording.ts
58+
record: {
59+
type: 'object',
60+
oneOf: [
61+
objectSchema(
62+
{
63+
recording: constSchema('started'),
64+
outPath: stringSchema(),
65+
sessionStateDir: stringSchema(),
66+
recordingBackend: stringSchema(),
67+
recordingScope: stringSchema(),
68+
recordOnlySession: booleanSchema(),
69+
activeSessionApp: looseObjectSchema(),
70+
showTouches: booleanSchema(),
71+
},
72+
['recording', 'outPath', 'sessionStateDir', 'showTouches'],
73+
),
74+
objectSchema(
75+
{
76+
recording: constSchema('stopped'),
77+
outPath: stringSchema(),
78+
telemetryPath: stringSchema(),
79+
artifacts: { type: 'array', items: artifactSchema },
80+
recordingBackend: stringSchema(),
81+
recordingScope: stringSchema(),
82+
recordOnlySession: booleanSchema(),
83+
activeSessionApp: looseObjectSchema(),
84+
durationMs: numberSchema(),
85+
capturedDurationMs: numberSchema(),
86+
recorder: enumSchema(
87+
RECORDER_OBSERVATION_VALUES,
88+
'What the recorder was observed doing when the recording was stopped: confirmed, or lost when the session holding it died. ADR 0024 reserves unconfirmed for the step that gains the probe.',
89+
),
90+
nativePathDisposition: enumSchema(
91+
NATIVE_PATH_DISPOSITION_VALUES,
92+
'What became of the artifact path the recorder writes to: retirable while it still owes a removal, retired once that removal was verified. ADR 0024 reserves pending.',
93+
),
94+
showTouches: booleanSchema(),
95+
warning: stringSchema(),
96+
overlayWarning: stringSchema(),
97+
chunks: { type: 'array', items: looseObjectSchema() },
98+
},
99+
['recording', 'outPath', 'artifacts', 'durationMs', 'showTouches'],
100+
),
101+
],
102+
},
103+
trace: {
104+
type: 'object',
105+
oneOf: [
106+
objectSchema({ trace: constSchema('started'), outPath: stringSchema() }, [
107+
'trace',
108+
'outPath',
109+
]),
110+
objectSchema(
111+
{
112+
trace: constSchema('stopped'),
113+
outPath: stringSchema(),
114+
artifacts: { type: 'array', items: artifactSchema },
115+
},
116+
['trace', 'outPath', 'artifacts'],
117+
),
118+
],
119+
},
120+
} satisfies Pick<Record<keyof CommandResultMap, JsonSchema>, 'record' | 'trace'>;
121+
27122
const RECORD_COMMAND_NAME = 'record';
28123
const TRACE_COMMAND_NAME = 'trace';
29124
const RECORDING_ACTION_VALUES = ['start', 'stop'] as const;

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,36 @@
11
import assert from 'node:assert/strict';
22
import { test } from 'vitest';
3+
import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
4+
import { RECORDING_COMMAND_OUTPUT_SCHEMAS } from '../../commands/recording/index.ts';
35
import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
46
import { validateAgainstSchema } from './output-schema-validator.ts';
57

8+
const RECORDING_COMMANDS = Object.keys(RECORDING_COMMAND_OUTPUT_SCHEMAS) as Array<
9+
keyof typeof RECORDING_COMMAND_OUTPUT_SCHEMAS
10+
>;
11+
12+
// Neither record nor trace carries the post-action observation trait (#1652): both fire-and-report
13+
// a recording or trace lifecycle change, not an interaction, so the composed map never copies
14+
// either entry and reference equality must hold for both.
15+
test('MCP recording family output schemas are the family module entries, not copies', () => {
16+
for (const command of RECORDING_COMMANDS) {
17+
assert.equal(
18+
COMMAND_OUTPUT_SCHEMAS[command],
19+
RECORDING_COMMAND_OUTPUT_SCHEMAS[command],
20+
`${command} is not reference-equal to the recording module's own schema object`,
21+
);
22+
}
23+
});
24+
25+
test('the projected family map declares exactly the commands its module owns', () => {
26+
for (const command of RECORDING_COMMANDS) {
27+
assert.ok(
28+
ownerFilesForCommand(command).includes('src/commands/recording/index.ts'),
29+
`${command} projects its output schema from this module but does not name it as its owner`,
30+
);
31+
}
32+
});
33+
634
// `record stop` answers two independent questions (ADR 0024): whether a playable export exists, and
735
// whether its recorder stopped. Only the second one's words are additive properties here — the
836
// stopped branch's required list is what it was before either fact was reported.

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { commandSupportsSettleObservation } from '@agent-device/command-registry
66
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/device.ts';
77
import { PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/push.ts';
88
import { INTERACTION_COMMAND_OUTPUT_SCHEMAS } from '../../commands/interaction/index.ts';
9+
import { RECORDING_COMMAND_OUTPUT_SCHEMAS } from '../../commands/recording/index.ts';
910
import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../../commands/replay/index.ts';
1011
import { SYSTEM_COMMAND_OUTPUT_SCHEMAS } from '../../commands/system/index.ts';
1112
import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
@@ -77,6 +78,7 @@ const PROJECTED_FAMILIES = [
7778
{ name: 'interaction', schemas: INTERACTION_COMMAND_OUTPUT_SCHEMAS },
7879
{ name: 'management-device', schemas: DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS },
7980
{ name: 'management-push', schemas: PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS },
81+
{ name: 'recording', schemas: RECORDING_COMMAND_OUTPUT_SCHEMAS },
8082
] as const;
8183

8284
test('projected output-schema families claim disjoint commands and survive the composition intact', () => {

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

Lines changed: 2 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,9 @@ import {
1717
INTERACTION_COMMAND_OUTPUT_SCHEMAS,
1818
postActionSurfaceChangeSchema,
1919
} from '../commands/interaction/index.ts';
20+
import { RECORDING_COMMAND_OUTPUT_SCHEMAS } from '../commands/recording/index.ts';
2021
import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../commands/replay/index.ts';
2122
import { SYSTEM_COMMAND_OUTPUT_SCHEMAS } from '../commands/system/index.ts';
22-
import { NATIVE_PATH_DISPOSITION_VALUES } from '@agent-device/contracts/recording-native-path';
23-
import { RECORDER_OBSERVATION_VALUES } from '@agent-device/contracts/recording-stop-observation';
2423
import { DEVICE_KINDS, DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
2524

2625
/**
@@ -52,17 +51,6 @@ import { DEVICE_KINDS, DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/ke
5251
* trait (#1652).
5352
*/
5453

55-
const artifactSchema = objectSchema(
56-
{
57-
field: stringSchema(),
58-
artifactType: stringSchema(),
59-
path: stringSchema(),
60-
localPath: stringSchema(),
61-
fileName: stringSchema(),
62-
},
63-
['field'],
64-
);
65-
6654
// SettleObservation (packages/contracts/src/interaction.ts) — opt-in `--settle` settled
6755
// diff observation (#1101).
6856
const settleObservationSchema: JsonSchema = objectSchema(
@@ -330,77 +318,14 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
330318
['mode', 'baselineInitialized', 'summary', 'lines'],
331319
),
332320

333-
// packages/contracts/src/recording.ts
334-
record: {
335-
type: 'object',
336-
oneOf: [
337-
objectSchema(
338-
{
339-
recording: constSchema('started'),
340-
outPath: stringSchema(),
341-
sessionStateDir: stringSchema(),
342-
recordingBackend: stringSchema(),
343-
recordingScope: stringSchema(),
344-
recordOnlySession: booleanSchema(),
345-
activeSessionApp: looseObjectSchema(),
346-
showTouches: booleanSchema(),
347-
},
348-
['recording', 'outPath', 'sessionStateDir', 'showTouches'],
349-
),
350-
objectSchema(
351-
{
352-
recording: constSchema('stopped'),
353-
outPath: stringSchema(),
354-
telemetryPath: stringSchema(),
355-
artifacts: { type: 'array', items: artifactSchema },
356-
recordingBackend: stringSchema(),
357-
recordingScope: stringSchema(),
358-
recordOnlySession: booleanSchema(),
359-
activeSessionApp: looseObjectSchema(),
360-
durationMs: numberSchema(),
361-
capturedDurationMs: numberSchema(),
362-
recorder: enumSchema(
363-
RECORDER_OBSERVATION_VALUES,
364-
'What the recorder was observed doing when the recording was stopped: confirmed, or lost when the session holding it died. ADR 0024 reserves unconfirmed for the step that gains the probe.',
365-
),
366-
nativePathDisposition: enumSchema(
367-
NATIVE_PATH_DISPOSITION_VALUES,
368-
'What became of the artifact path the recorder writes to: retirable while it still owes a removal, retired once that removal was verified. ADR 0024 reserves pending.',
369-
),
370-
showTouches: booleanSchema(),
371-
warning: stringSchema(),
372-
overlayWarning: stringSchema(),
373-
chunks: { type: 'array', items: looseObjectSchema() },
374-
},
375-
['recording', 'outPath', 'artifacts', 'durationMs', 'showTouches'],
376-
),
377-
],
378-
},
379-
trace: {
380-
type: 'object',
381-
oneOf: [
382-
objectSchema({ trace: constSchema('started'), outPath: stringSchema() }, [
383-
'trace',
384-
'outPath',
385-
]),
386-
objectSchema(
387-
{
388-
trace: constSchema('stopped'),
389-
outPath: stringSchema(),
390-
artifacts: { type: 'array', items: artifactSchema },
391-
},
392-
['trace', 'outPath', 'artifacts'],
393-
),
394-
],
395-
},
396-
397321
// A family that owns its commands authors their advertised response shape beside the
398322
// command surface and projects it here. This spread stays last: a hand-written entry for
399323
// a projected command then fails as TS2783 instead of quietly overriding the family's,
400324
// and this map's `satisfies` still refuses a missing `CommandResultMap` key.
401325
...DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
402326
...PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
403327
...INTERACTION_COMMAND_OUTPUT_SCHEMAS,
328+
...RECORDING_COMMAND_OUTPUT_SCHEMAS,
404329
...REPLAY_COMMAND_OUTPUT_SCHEMAS,
405330
...SYSTEM_COMMAND_OUTPUT_SCHEMAS,
406331
} satisfies Record<keyof CommandResultMap, JsonSchema>;

0 commit comments

Comments
 (0)