Skip to content

Commit 651a68b

Browse files
committed
fix(replay): keep installation metadata outside lazy compatibility help
1 parent 5fe9441 commit 651a68b

8 files changed

Lines changed: 62 additions & 62 deletions

File tree

‎packages/ad-script/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ export {
6161
} from './internal/vars.ts';
6262

6363
export {
64+
getReplayPluginInstallation,
6465
isMaestroYamlPath,
6566
isReplayBackendId,
6667
maestroBackendRequiredMessage,

‎packages/ad-script/src/internal/format.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,26 @@ import path from 'node:path';
22

33
export type ReplayFormat = 'ad' | 'maestro';
44

5+
const REPLAY_PLUGIN_INSTALLATIONS = {
6+
ad: {
7+
package: '@agent-device/replay',
8+
summary: 'Native .ad replay and test suites',
9+
installationHint:
10+
'Install on the daemon host for native .ad replay and all test suites. Core clients can read and send native .ad sources without this plugin.',
11+
},
12+
maestro: {
13+
package: '@agent-device/maestro',
14+
summary: 'Supported Maestro YAML commands, grammar, and runtime boundaries',
15+
installationHint:
16+
'Install on the client for source collection/export and on the daemon host for Maestro execution.',
17+
},
18+
} as const;
19+
20+
/** Vetted installation facts for the replay format vocabulary, without loading an engine. */
21+
export function getReplayPluginInstallation(id: ReplayFormat) {
22+
return { id, ...REPLAY_PLUGIN_INSTALLATIONS[id] };
23+
}
24+
525
export function isMaestroYamlPath(sourcePath: string): boolean {
626
const extension = path.extname(sourcePath).toLowerCase();
727
return extension === '.yaml' || extension === '.yml';

‎packages/command-surface/src/replay/index.ts‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,22 +28,24 @@ import { METRO_RELOAD_FLAGS, REPLAY_FLAGS } from '@agent-device/command-registry
2828
import { withCommandRuntimeHints } from '../runtime-hints.ts';
2929
import {
3030
collectReplayShellEnv,
31+
getReplayPluginInstallation,
3132
parseReplayCliEnvEntries,
3233
readReplayCliEnvEntries,
3334
resolveReplayFormat,
3435
type ReplayFormat,
3536
} from '@agent-device/ad-script';
3637
import { loadReplayScriptSourceBundle } from '@agent-device/replay-port/script-source-bundle';
37-
import { replayPluginInstallHelp } from '@agent-device/replay-port/replay-backend-declarations';
3838
import { discoverReplaySourcePaths } from '@agent-device/replay-port/source-discovery';
3939

4040
const REPLAY_COMMAND_NAME = 'replay';
4141
const TEST_COMMAND_NAME = 'test';
4242

43-
const replayPluginMcpDetail = [
44-
replayPluginInstallHelp('ad'),
45-
replayPluginInstallHelp('maestro'),
46-
].join(' ');
43+
const replayPluginMcpDetail = (['ad', 'maestro'] as const)
44+
.map((id) => {
45+
const declaration = getReplayPluginInstallation(id);
46+
return `${declaration.summary} (plugin, install separately). ${declaration.installationHint}`;
47+
})
48+
.join(' ');
4749

4850
const REPLAY_SHELL_ENV_PREFIX = 'AD_VAR_';
4951

‎packages/replay-port/src/daemon-port/__tests__/replay-backend-registry.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
1+
import { getReplayPluginInstallation } from '@agent-device/ad-script';
12
import { expect, test } from 'vitest';
23
import { createRuntimeStateHandle } from '@agent-device/host-kit/runtime-slots';
34
import { getReplayBackendDeclaration } from '../replay-backend-declarations.ts';
45
import { getReplayBackend, openReplayBackend } from '../replay-backend-registry.ts';
56
import { mkdtempForTestSync } from '@agent-device/test-kit';
67

78
test('help declares the exact optional package without requiring a working plugin', () => {
8-
expect(getReplayBackendDeclaration('maestro')).toMatchObject({
9+
expect(getReplayBackendDeclaration(getReplayPluginInstallation('maestro'))).toMatchObject({
910
id: 'maestro',
1011
package: '@agent-device/maestro',
1112
});
Lines changed: 21 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { ReplayFormat } from '@agent-device/ad-script';
1+
import type { getReplayPluginInstallation, ReplayFormat } from '@agent-device/ad-script';
22
import type { ReplayBackendDeclaration } from '@agent-device/contracts/replay-backend';
33

44
export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
@@ -34,60 +34,34 @@ function formatMaestroCompatibilityReference(): string {
3434
].join('\n');
3535
}
3636

37-
const maestroPackage = '@agent-device/maestro';
38-
const nativePackage = '@agent-device/replay';
39-
40-
const maestroReplayBackendDeclaration: ReplayBackendDeclaration<'maestro'> = {
41-
id: 'maestro',
42-
package: maestroPackage,
43-
installationHint:
44-
'Install on the client for source collection/export and on the daemon host for Maestro execution.',
45-
help: {
46-
summary: 'Supported Maestro YAML commands, grammar, and runtime boundaries',
47-
body: `agent-device help maestro
37+
/** Full compatibility help is composed only by help consumers, from the vetted installation. */
38+
export function getReplayBackendDeclaration(
39+
installation: ReturnType<typeof getReplayPluginInstallation>,
40+
): ReplayBackendDeclaration<ReplayFormat> {
41+
const body =
42+
installation.id === 'ad'
43+
? `Run agent-device plugins add ${installation.package} on the daemon host for native .ad replay and all test suites. Existing scripts and arguments stay the same. Ordinary open/close --save-script recording stays in core. Restart the daemon after changing plugins, then retry the original invocation with all its arguments.`
44+
: `agent-device help maestro
4845
49-
Install with agent-device plugins add ${maestroPackage} on the client and daemon host. Restart the daemon after installation.
46+
Install with agent-device plugins add ${installation.package} on the client and daemon host. Restart the daemon after installation.
5047
5148
Run Maestro compatibility flows with replay <flow.yaml> --maestro or test <path> --maestro. Bind an iOS or Android target with --platform or an existing session.
5249
5350
${formatMaestroCompatibilityReference()}
5451
5552
Unsupported syntax fails loudly rather than being skipped. Architecture, performance tradeoffs, and declared conformance divergences: ${MAESTRO_COMPATIBILITY_ADR_URL}
56-
Focused compatibility request: ${MAESTRO_COMPATIBILITY_ISSUE_URL}`,
57-
},
58-
};
59-
60-
/**
61-
* The engine-free half of every registered replay backend (#3377), as `help` lists it. Kept apart
62-
* from the registry so reading a declaration adds nothing to the closure of the daemon routes
63-
* that only load backends. Keys come from the format grammar's vocabulary, and each declaration's
64-
* `id` is typed to its key, as each plugin's is in the registry, so help cannot describe a backend
65-
* other than the one its id loads.
66-
*/
67-
const REPLAY_BACKEND_DECLARATIONS: {
68-
readonly [TId in ReplayFormat]: ReplayBackendDeclaration<TId>;
69-
} = {
70-
ad: {
71-
id: 'ad',
72-
package: nativePackage,
73-
installationHint:
74-
'Install on the daemon host for native .ad replay and all test suites. Core clients can read and send native .ad sources without this plugin.',
75-
help: {
76-
summary: 'Native .ad replay and test suites',
77-
body: `Run agent-device plugins add ${nativePackage} on the daemon host for native .ad replay and all test suites. Existing scripts and arguments stay the same. Ordinary open/close --save-script recording stays in core. Restart the daemon after changing plugins, then retry the original invocation with all its arguments.`,
78-
},
79-
},
80-
maestro: maestroReplayBackendDeclaration,
81-
};
82-
83-
export function getReplayBackendDeclaration(
84-
id: ReplayFormat,
85-
): ReplayBackendDeclaration<ReplayFormat> {
86-
return REPLAY_BACKEND_DECLARATIONS[id];
53+
Focused compatibility request: ${MAESTRO_COMPATIBILITY_ISSUE_URL}`;
54+
return {
55+
id: installation.id,
56+
package: installation.package,
57+
installationHint: installation.installationHint,
58+
help: { summary: installation.summary, body },
59+
};
8760
}
8861

8962
/** Installation guidance uses the same vetted package declaration as missing-plugin errors. */
90-
export function replayPluginInstallHelp(id: ReplayFormat): string {
91-
const declaration = getReplayBackendDeclaration(id);
92-
return `${declaration.help.summary} (plugin, install separately). Run agent-device plugins add ${declaration.package}.`;
63+
export function replayPluginInstallHelp(
64+
installation: ReturnType<typeof getReplayPluginInstallation>,
65+
): string {
66+
return `${installation.summary} (plugin, install separately). Run agent-device plugins add ${installation.package}.`;
9367
}

‎packages/replay-port/src/daemon-port/replay-backend-registry.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -122,11 +122,11 @@ async function missingReplayBackend(id: ReplayFormat): Promise<AppError> {
122122
backend: id,
123123
package: packageName,
124124
installCommand,
125-
hint: `${(await import('./replay-backend-declarations.ts')).getReplayBackendDeclaration(id).installationHint} Restart the daemon after changing plugins; retry the original command with all its arguments.`,
125+
hint: `${(await import('@agent-device/ad-script')).getReplayPluginInstallation(id).installationHint} Restart the daemon after changing plugins; retry the original command with all its arguments.`,
126126
},
127127
);
128128
}
129129

130130
async function backendPackage(id: ReplayFormat): Promise<string> {
131-
return (await import('./replay-backend-declarations.ts')).getReplayBackendDeclaration(id).package;
131+
return (await import('@agent-device/ad-script')).getReplayPluginInstallation(id).package;
132132
}

‎src/commands/schema/cli-help.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { getReplayPluginInstallation } from '@agent-device/ad-script';
12
import { gestureHelpTopic } from './cli-help-gestures.ts';
23
import { listCliCommandNames } from '@agent-device/command-registry/catalog';
34
import {
@@ -73,7 +74,7 @@ const HELP_TOPICS = {
7374
body: 'agent-device help commands',
7475
},
7576
...manualQaHelpTopics,
76-
maestro: getReplayBackendDeclaration('maestro').help,
77+
maestro: getReplayBackendDeclaration(getReplayPluginInstallation('maestro')).help,
7778
workflow: {
7879
summary: 'Normal agent-device bootstrap, exploration, and validation loop',
7980
body: `agent-device help workflow
@@ -879,9 +880,9 @@ export function buildCommandUsageText(commandName: string): string | null {
879880
);
880881
const sections: string[] = [];
881882
if (commandName === 'replay' || commandName === 'test') {
882-
sections.push(replayPluginInstallHelp('ad'));
883-
sections.push(getReplayBackendDeclaration('ad').help.body);
884-
sections.push(replayPluginInstallHelp('maestro'));
883+
sections.push(replayPluginInstallHelp(getReplayPluginInstallation('ad')));
884+
sections.push(getReplayBackendDeclaration(getReplayPluginInstallation('ad')).help.body);
885+
sections.push(replayPluginInstallHelp(getReplayPluginInstallation('maestro')));
885886
}
886887
if (commandName === 'connect') {
887888
sections.push(`Optional provider plugins:\n${providerPluginHelp()}`);

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,15 @@ afterEach(() => {
1919

2020
let temporaryDirectory: string | undefined;
2121

22-
test('MCP replay discovery identifies optional plugins and installation commands', () => {
22+
test('MCP replay discovery identifies optional plugins and installation scopes', () => {
2323
const tools = listCommandTools({ outputSchemas: true });
2424
for (const name of ['replay', 'test']) {
2525
const tool = tools.find((candidate) => candidate.name === name);
2626
assert.ok(tool);
2727
assert.match(tool.description, /plugin, install separately/);
28-
assert.ok(tool.description.includes('agent-device plugins add @agent-device/replay'));
29-
assert.ok(tool.description.includes('agent-device plugins add @agent-device/maestro'));
28+
assert.match(tool.description, /Native \.ad replay and test suites/);
29+
assert.match(tool.description, /Install on the daemon host/);
30+
assert.match(tool.description, /Install on the client for source collection/);
3031
assert.ok(tool.inputSchema.properties);
3132
assert.ok(tool.outputSchema);
3233
}

0 commit comments

Comments
 (0)