Skip to content

Commit 8c01a37

Browse files
authored
refactor(maestro): shape the replay backend as a create(host) plugin (#3623)
* refactor(maestro): shape the replay backend as a create(host) plugin * chore(gates): pin the maestro replay backend plugin surface and closure approval * fix(maestro): assert the suggestion source, first trace write, and pinned help URLs * refactor(replay-port): tie each backend's declaration and plugin to its id, drop unread fields Both id-keyed tables are mapped over ReplayBackendId, so a declaration or plugin registered under another backend's id fails to type-check. The tables stay apart so the daemon routes that load backends do not evaluate help text. ReplayBackendPlugin.declaration and ReplayBackendDeclaration.apiVersion had no reader; the installed-plugin loader that would check them is not part of #3377 yet. * chore(gates): drop the #3616 over-ceiling approvals the merge-base now carries
1 parent f6074a9 commit 8c01a37

33 files changed

Lines changed: 595 additions & 330 deletions

‎packages/contracts/src/replay-backend.ts‎

Lines changed: 63 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,30 @@ import type { DaemonError } from '@agent-device/kernel/errors';
22
import type { DaemonResponse, SessionRuntimeHints } from '@agent-device/kernel/contracts';
33
import type { DeviceInfo } from '@agent-device/kernel/device';
44
import type { SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
5+
import type { CommandFlags } from './command-flags.ts';
56
import type { DaemonWireRequest } from './daemon-wire-request.ts';
67
import type {
78
ReplayDivergenceResume,
89
ReplayDivergenceSuggestionBasis,
910
} from './replay-divergence.ts';
10-
import type { ReplayDispatchOptions, ReplayObservationAuthorityBinder } from './replay.ts';
11+
import type {
12+
ReplayDispatchOptions,
13+
ReplayObservationAuthorityBinder,
14+
ReplayScriptSourceBundle,
15+
} from './replay.ts';
1116
import type { SessionAction } from './session-action.ts';
1217
import type {
1318
SnapshotDiagnosticsState,
1419
SnapshotDiagnosticsSummary,
1520
} from './snapshot-diagnostics.ts';
1621

1722
/**
18-
* The replay backend contract (#3377): the session and command shapes a non-native replay engine
19-
* is handed, the capabilities it implements, and the failure descriptor the daemon reports for a
20-
* failed step. Everything here is type-only, so an engine can depend on this module without
23+
* The replay backend plugin contract (#3377): what a non-native replay engine implements
24+
* (`ReplayBackendPlugin`) and the host services the daemon lends it (`ReplayBackendHost`).
25+
*
26+
* The replay port owns the registry and builds the host; an engine package owns its plugin and
27+
* reaches process state, session policy, and daemon dispatch only through `host` and the command
28+
* it is handed. Everything here is type-only, so an engine can depend on this module without
2129
* evaluating any host code.
2230
*/
2331

@@ -205,3 +213,54 @@ export type ReplayBackendActionFailure = Readonly<{
205213
snapshot: Readonly<{ createdAt: number; nodes: SnapshotNode[] }>,
206214
): readonly Readonly<{ node: SnapshotNode; basis: ReplayDivergenceSuggestionBasis }>[];
207215
}>;
216+
217+
/** The device-binding facts a backend resolves a target device from. */
218+
export type ReplayBackendDeviceBinding = Readonly<{
219+
/** The flow's static app target, when it declares one. */
220+
appTarget: string | undefined;
221+
platform: CommandFlags['platform'] | undefined;
222+
}>;
223+
224+
/**
225+
* The host services a backend plugin reaches. Everything holding process state or daemon
226+
* session policy is a member; stateless workspace packages stay direct imports of the plugin.
227+
*/
228+
export type ReplayBackendHost = Readonly<{
229+
/** Appends one record to the run's trace file, if any; failures are diagnostics, never thrown. */
230+
appendTraceEvent(tracePath: string | undefined, event: Record<string, unknown>): void;
231+
/** The `AD_*` variables every replay run is seeded with. */
232+
buildBuiltinVars(params: {
233+
req: DaemonWireRequest;
234+
sessionName: string;
235+
resolvedPath: string;
236+
}): Record<string, string>;
237+
/** Reads one file out of the request's script source bundle; throws when it was not sent. */
238+
readScriptSourceFile(bundle: ReplayScriptSourceBundle, resolvedPath: string): string;
239+
scriptSourceRequiredMessage: string;
240+
/**
241+
* Selects the device a run binds when no session or explicit platform already names one. It
242+
* applies the Maestro device-binding rule (the flow's app target steers selection on iOS only),
243+
* the same rule `packages/daemon/src/server/replay-device-selection.ts` applies when it
244+
* pre-binds a device for the request.
245+
*/
246+
resolveTargetDevice(
247+
flags: CommandFlags,
248+
binding: ReplayBackendDeviceBinding,
249+
): Promise<DeviceInfo>;
250+
/** The abort signal of the in-flight daemon request. */
251+
requestSignal(requestId: string | undefined): AbortSignal | undefined;
252+
/** Builds the REPLAY_DIVERGENCE failure response: screen capture, ranking, bounding, resume. */
253+
buildActionFailureResponse(failure: ReplayBackendActionFailure): Promise<DaemonResponse>;
254+
}>;
255+
256+
/**
257+
* Engine-free metadata, importable without evaluating the engine, so help stays light.
258+
*/
259+
export type ReplayBackendDeclaration<TId extends string = string> = Readonly<{
260+
id: TId;
261+
help: Readonly<{ summary: string; body: string }>;
262+
}>;
263+
264+
export type ReplayBackendPlugin<TId extends string = string> = Readonly<{
265+
create(host: ReplayBackendHost): ReplayBackend<TId>;
266+
}>;

‎packages/daemon/src/sessions/__tests__/replay-maestro/session-replay-maestro-error-projection.test.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import fs from 'node:fs';
22
import path from 'node:path';
33
import { expect, test } from 'vitest';
44
import { stringify } from 'yaml';
5-
import { runTypedMaestroReplay } from '@agent-device/replay-port/session-replay-maestro-runtime';
5+
import { getReplayBackend } from '@agent-device/replay-port/replay-backend-registry';
66
import { SessionStore } from '../../../core/session-store.ts';
77
import { replayCommandForTest } from '../replay-runtime/replay-command-fixture.ts';
88
import { makeIosSession } from '../../../__tests__/support/session-factories.ts';
@@ -35,7 +35,9 @@ test('a typed Maestro replay error keeps its recovery hint', async () => {
3535
meta: { requestId: 'req-maestro-hint' },
3636
} as unknown as DaemonRequest;
3737

38-
const response = await runTypedMaestroReplay(
38+
const response = await (
39+
await getReplayBackend('maestro')
40+
).runReplay(
3941
replayCommandForTest({
4042
req,
4143
sessionName: 'default',

‎packages/daemon/src/sessions/__tests__/replay-maestro/session-replay-maestro-failure.test.ts‎

Lines changed: 38 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import { noMaestroIncludeSources } from '@agent-device/replay-port/replay-script-source-fixtures';
21
import { beforeEach, expect, test, vi } from 'vitest';
32
import { mkdtempForTestSync } from '@agent-device/test-kit/tmp-dir';
43

@@ -13,23 +12,12 @@ vi.mock('../../../core/snapshot-interactor-capture.ts', () => ({
1312
import fs from 'node:fs';
1413
import path from 'node:path';
1514
import { stringify } from 'yaml';
16-
import {
17-
executeMaestroFlow,
18-
inspectMaestroFlow,
19-
type MaestroFailedAction,
20-
type MaestroRuntimeCommand,
21-
type MaestroRuntimePort,
22-
} from '@agent-device/maestro';
23-
import {
24-
buildTypedMaestroFailureReportProjection,
25-
buildTypedMaestroFailureResponse,
26-
} from '@agent-device/replay-port/session-replay-maestro-failure';
15+
import type { MaestroRuntimeCommand } from '@agent-device/maestro';
2716
import { runReplayForTest } from '../replay-runtime/replay-command-fixture.ts';
2817
import { SessionStore } from '../../../core/session-store.ts';
2918
import { captureSnapshotWithInteractor } from '../../../core/snapshot-interactor-capture.ts';
3019
import { makeIosSession } from '../../../__tests__/support/session-factories.ts';
3120
import { baseReplayRequest as baseReq } from '../replay-runtime/session-replay-runtime.fixtures.ts';
32-
import { replaySessionForTest } from '../replay-divergence/replay-session-fixture.ts';
3321
import type { SnapshotNode } from '@agent-device/kernel/snapshot';
3422
import {
3523
captureSnapshotThroughLegacyDispatchFixture,
@@ -47,30 +35,35 @@ beforeEach(() => {
4735
mockCaptureSnapshotWithInteractor.mockImplementation(captureSnapshotThroughLegacyDispatchFixture);
4836
});
4937

38+
/**
39+
* Runs a one-step flow whose action fails, so the divergence report is built the way the daemon
40+
* builds it: `nodes` is the screen captured after the failure, `engineNodes` what the flow's own
41+
* target lookup sees before it.
42+
*/
5043
async function buildFailureScenario(
5144
command: MaestroRuntimeCommand,
5245
nodes: SnapshotNode[],
53-
options: { warnings?: readonly string[] } = {},
54-
): Promise<{
55-
response: Extract<Awaited<ReturnType<typeof buildTypedMaestroFailureResponse>>, { ok: false }>;
56-
sessionStore: SessionStore;
57-
sessionName: string;
58-
}> {
46+
options: { engineNodes?: SnapshotNode[] } = {},
47+
) {
5948
const root = mkdtempForTestSync('agent-device-maestro-suggestions-');
6049
const sessionName = 'default';
6150
const sessionStore = new SessionStore(path.join(root, 'sessions'));
6251
sessionStore.publish(sessionName, makeIosSession(sessionName));
63-
const replaySession = replaySessionForTest(sessionStore, sessionName);
52+
const flowPath = path.join(root, 'flow.yaml');
53+
fs.writeFileSync(flowPath, maestroFlowForCommand(command));
6454
mockDispatchCommand.mockResolvedValue({ nodes, truncated: false, backend: 'xctest' });
65-
const failure = await captureMaestroFailure(command, path.join(root, 'flow.yaml'));
66-
const response = await buildTypedMaestroFailureResponse({
67-
error: { code: 'COMMAND_FAILED', message: 'typed Maestro action failed' },
68-
failure: options.warnings ? { ...failure, warnings: options.warnings } : failure,
69-
replayPath: path.join(root, 'flow.yaml'),
70-
req: baseReq({ flags: { replayBackend: 'maestro', platform: 'ios' } }),
71-
sessionStore: replaySession.store,
72-
observationStore: replaySession.observationStore,
55+
const response = await runReplayForTest({
56+
req: baseReq({
57+
positionals: [flowPath],
58+
flags: { replayBackend: 'maestro', platform: 'ios' },
59+
}),
60+
sessionName,
7361
logPath: path.join(root, 'daemon.log'),
62+
sessionStore,
63+
invoke: async (req) =>
64+
req.command === 'snapshot'
65+
? { ok: true, data: { nodes: options.engineNodes ?? nodes } }
66+
: { ok: false, error: { code: 'COMMAND_FAILED', message: 'typed Maestro action failed' } },
7467
});
7568
if (response.ok) throw new Error('expected typed Maestro failure response');
7669
return { response, sessionStore, sessionName };
@@ -79,85 +72,11 @@ async function buildFailureScenario(
7972
async function buildFailureResponse(
8073
command: MaestroRuntimeCommand,
8174
nodes: SnapshotNode[],
82-
options: { warnings?: readonly string[] } = {},
83-
): Promise<Extract<Awaited<ReturnType<typeof buildTypedMaestroFailureResponse>>, { ok: false }>> {
75+
options: { engineNodes?: SnapshotNode[] } = {},
76+
) {
8477
return (await buildFailureScenario(command, nodes, options)).response;
8578
}
8679

87-
test('typed Maestro failure response carries warnings accumulated before the failing step (#2560)', async () => {
88-
const response = await buildFailureResponse(
89-
{
90-
kind: 'tapOn' as const,
91-
source: { path: '/flows/login.yaml', line: 4 },
92-
target: { space: 'target' as const, selector: { id: 'save' } },
93-
},
94-
[],
95-
{ warnings: ['Optional Maestro assertVisible skipped at line 2: no match'] },
96-
);
97-
98-
if (!response.error.details) throw new Error('expected error details on the failure response');
99-
const details = response.error.details;
100-
expect(details.warnings).toEqual(['Optional Maestro assertVisible skipped at line 2: no match']);
101-
expect((details.divergence as { kind: string }).kind).toBe('action-failure');
102-
});
103-
104-
test('typed Maestro failure response omits an empty warnings channel', async () => {
105-
const response = await buildFailureResponse(
106-
{
107-
kind: 'tapOn' as const,
108-
source: { path: '/flows/login.yaml', line: 4 },
109-
target: { space: 'target' as const, selector: { id: 'save' } },
110-
},
111-
[],
112-
{ warnings: [] },
113-
);
114-
115-
expect('warnings' in (response.error.details ?? {})).toBe(false);
116-
});
117-
118-
test('typed Maestro failure projection keeps action and source provenance', async () => {
119-
const command = {
120-
kind: 'tapOn' as const,
121-
source: { path: '/flows/login.yaml', line: 4 },
122-
target: { space: 'target' as const, selector: { id: 'save' } },
123-
};
124-
const request = baseReq({ flags: { replayBackend: 'maestro' } });
125-
const failure = await captureMaestroFailure(command, command.source.path);
126-
const projection = buildTypedMaestroFailureReportProjection(failure, request);
127-
128-
expect(projection.command).toEqual({ kind: 'tapOn' });
129-
expect(projection.source).toEqual({ path: command.source.path, line: 3 });
130-
expect(projection.progress).toEqual({ command: 'tapOn', value: 'save' });
131-
expect(projection.action).toEqual({
132-
command: 'click',
133-
positionals: ['save'],
134-
flags: request.flags,
135-
});
136-
expect(Object.keys(projection.action)).toEqual(['command', 'positionals', 'flags']);
137-
});
138-
139-
async function captureMaestroFailure(
140-
command: MaestroRuntimeCommand,
141-
sourcePath: string,
142-
): Promise<MaestroFailedAction> {
143-
const flow = inspectMaestroFlow(maestroFlowForCommand(command), sourcePath);
144-
const error = new Error('typed Maestro action failed');
145-
const port: MaestroRuntimePort = {
146-
execute: async () => {
147-
throw error;
148-
},
149-
observe: async () => {
150-
throw error;
151-
},
152-
};
153-
const outcome = await executeMaestroFlow(flow, port, {
154-
platform: 'ios',
155-
readSource: noMaestroIncludeSources,
156-
});
157-
if (outcome.ok || !outcome.failure) throw new Error('expected typed Maestro failure');
158-
return outcome.failure;
159-
}
160-
16180
function maestroFlowForCommand(command: MaestroRuntimeCommand): string {
16281
const authored =
16382
command.kind === 'inputText'
@@ -378,7 +297,7 @@ test('typed Maestro failure publishes exactly the refs exposed by its divergence
378297
source: { path: '/flows/actions.yaml', line: 4 },
379298
target: { space: 'target' as const, selector: { text: 'Missing' } },
380299
} satisfies Extract<MaestroRuntimeCommand, { kind: 'tapOn' }>;
381-
const scenario = await buildFailureScenario(command, [
300+
const screen: SnapshotNode[] = [
382301
{
383302
ref: 'e1',
384303
index: 0,
@@ -394,7 +313,20 @@ test('typed Maestro failure publishes exactly the refs exposed by its divergence
394313
rect: { x: 16, y: 40, width: 140, height: 44 },
395314
hittable: true,
396315
},
397-
]);
316+
];
317+
const scenario = await buildFailureScenario(command, screen, {
318+
engineNodes: [
319+
...screen,
320+
{
321+
index: 2,
322+
parentIndex: 0,
323+
label: 'Missing',
324+
type: 'Button',
325+
rect: { x: 16, y: 96, width: 140, height: 44 },
326+
hittable: true,
327+
},
328+
],
329+
});
398330
const divergence = scenario.response.error.details?.divergence as {
399331
screen: { state: string; refs: Array<{ ref: string }> };
400332
};

‎packages/daemon/src/sessions/__tests__/replay-maestro/session-replay-maestro-session-address.test.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import fs from 'node:fs';
22
import path from 'node:path';
33
import { expect, test } from 'vitest';
44
import { stringify } from 'yaml';
5-
import { runTypedMaestroReplay } from '@agent-device/replay-port/session-replay-maestro-runtime';
5+
import { getReplayBackend } from '@agent-device/replay-port/replay-backend-registry';
66
import { SessionStore } from '../../../core/session-store.ts';
77
import { replayCommandForTest } from '../replay-runtime/replay-command-fixture.ts';
88
import { makeIosSession } from '../../../__tests__/support/session-factories.ts';
@@ -37,7 +37,9 @@ test('a typed Maestro selector conflict names the session store key, not "defaul
3737
meta: { requestId: 'req-maestro-address' },
3838
} as unknown as DaemonRequest;
3939

40-
const response = await runTypedMaestroReplay(
40+
const response = await (
41+
await getReplayBackend('maestro')
42+
).runReplay(
4143
replayCommandForTest({
4244
req,
4345
sessionName: SCOPED_ADDRESS,

‎packages/maestro/package.json‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"type": "module",
77
"description": "Private Maestro compatibility engine for agent-device.",
88
"dependencies": {
9+
"@agent-device/ad-script": "workspace:*",
910
"@agent-device/capture-kit": "workspace:*",
1011
"@agent-device/contracts": "workspace:*",
1112
"@agent-device/host-kit": "workspace:*",
@@ -18,9 +19,13 @@
1819
"types": "./src/index.ts",
1920
"default": "./src/index.ts"
2021
},
21-
"./daemon-runtime-port": {
22-
"types": "./src/daemon-port/daemon-runtime-port.ts",
23-
"default": "./src/daemon-port/daemon-runtime-port.ts"
22+
"./replay-backend": {
23+
"types": "./src/replay-backend/replay-maestro-backend.ts",
24+
"default": "./src/replay-backend/replay-maestro-backend.ts"
25+
},
26+
"./replay-backend-declaration": {
27+
"types": "./src/replay-backend/replay-maestro-declaration.ts",
28+
"default": "./src/replay-backend/replay-maestro-declaration.ts"
2429
},
2530
"./run-script-http": {
2631
"types": "./src/daemon-port/run-script-http.ts",

‎packages/maestro/src/index.test.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,19 @@ describe('@agent-device/maestro facade', () => {
1919
expect(exports).not.toContain('rankMaestroFailureCandidates');
2020
});
2121

22-
test('keeps the daemon-side port off the engine entry and declares pure modules', () => {
22+
test('keeps the plugin and helper off the engine entry and declares pure modules', () => {
2323
const manifest = JSON.parse(
2424
fs.readFileSync(path.join(import.meta.dirname, '../package.json'), 'utf8'),
2525
) as { exports: Record<string, unknown>; sideEffects?: boolean };
26-
// The daemon-side runtime port (#2544) and its runScript HTTP helper are subpaths, not part
27-
// of the engine entry. This pins the surface; scripts/__tests__/eager-closure-budgets.test.ts
28-
// is what keeps `.` from starting to evaluate host-kit, capture-kit, or provision-kit.
26+
// The runScript HTTP helper is a subpath, not part of the engine entry, and the replay
27+
// backend plugin (#3377) is the only other way in: its engine-free declaration lets help list
28+
// the backend without evaluating the engine. This pins the surface;
29+
// scripts/__tests__/eager-closure-budgets.test.ts is what keeps `.` from starting to evaluate
30+
// host-kit, capture-kit, or provision-kit.
2931
expect(Object.keys(manifest.exports)).toEqual([
3032
'.',
31-
'./daemon-runtime-port',
33+
'./replay-backend',
34+
'./replay-backend-declaration',
3235
'./run-script-http',
3336
]);
3437
expect(manifest.sideEffects).toBe(false);

‎packages/maestro/src/index.ts‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,6 @@ export {
2929
export { MAESTRO_SELECTOR_PROJECTION } from './internal/selector-vocabulary.ts';
3030

3131
export {
32-
formatMaestroCompatibilityReference,
33-
MAESTRO_COMPATIBILITY_ADR_URL,
34-
MAESTRO_COMPATIBILITY_ISSUE_URL,
3532
MAESTRO_COMPAT_LIMITATIONS,
3633
MAESTRO_COMPAT_SUPPORTED_CAPABILITIES,
3734
} from './internal/facade-support.ts';
Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
11
export {
2-
formatMaestroCompatibilityReference,
3-
MAESTRO_COMPATIBILITY_ADR_URL,
4-
MAESTRO_COMPATIBILITY_ISSUE_URL,
52
MAESTRO_COMPAT_LIMITATIONS,
63
MAESTRO_COMPAT_SUPPORTED_CAPABILITIES,
74
} from './support-matrix.ts';

0 commit comments

Comments
 (0)