Skip to content

Commit bfaaeb9

Browse files
committed
fix: read replay scripts on the caller and ship them with the request
Closes #1802
1 parent 2b6d04a commit bfaaeb9

80 files changed

Lines changed: 2004 additions & 735 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTEXT.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,11 @@ task touches:
247247
- Destination guard: portable selector-targeted `wait` near the end of an open-to-destination script
248248
that confirms a landmark on the ready destination screen before replay hands the live session to
249249
its caller.
250+
- Replay script source bundle: every script file one `replay`/`test` run needs, read and resolved by
251+
the CALLER and shipped inside the request — an entry display path plus a resolved-path-to-text map
252+
covering the `.ad` script or the Maestro flow and its `runFlow` includes. The daemon executes only
253+
what the bundle carries and resolves no caller path, so a local run and a run against a remote
254+
daemon read identical bytes (#1802). Avoid: script upload, flow payload.
250255
- Screen-recording facet: runtime facet that starts platform screen/video capture and returns a live
251256
handle plus its durable descriptor. It is distinct from script recording.
252257
- Live resource handle: process-local authority to finish or forcibly dispose active app-log,
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { AppError } from '@agent-device/kernel/errors';
4+
import { inspectAdReplay } from '../inspect.ts';
5+
6+
const SCRIPT = 'context platform=ios\nopen "Demo"\nclick label="Save"\n';
7+
8+
test('inspectAdReplay parses script text into actions, a line table and header metadata', () => {
9+
const manifest = inspectAdReplay(SCRIPT);
10+
11+
assert.deepEqual(
12+
manifest.actions.map((action) => action.command),
13+
['open', 'click'],
14+
);
15+
assert.deepEqual(manifest.actionLines, [2, 3]);
16+
assert.equal(manifest.metadata.platform, 'ios');
17+
});
18+
19+
/**
20+
* ADR 0012's `--from`/`--plan-digest` resume quotes a digest back from a divergence report, so the
21+
* digest for a given script must not move. #1802 changed only HOW the script reaches the daemon
22+
* (a replay script source bundle instead of a path it opened itself); the digest is computed over
23+
* the same text and stays byte-identical, which is what keeps a resume issued before the change
24+
* valid after it.
25+
*/
26+
test('inspectAdReplay pins the plan digest for a known script', () => {
27+
assert.equal(
28+
inspectAdReplay(SCRIPT).planDigest,
29+
inspectAdReplay(SCRIPT, { platform: 'ios' }).planDigest,
30+
);
31+
assert.equal(
32+
inspectAdReplay(SCRIPT).planDigest,
33+
'0641236777b11822d90d446022965629ec99ac2ba1af2d5c637f06dd684fe695',
34+
);
35+
});
36+
37+
test('inspectAdReplay rejects a legacy JSON replay payload', () => {
38+
assert.throws(
39+
() => inspectAdReplay('[{"command":"open"}]'),
40+
(error: unknown) =>
41+
error instanceof AppError &&
42+
error.code === 'INVALID_ARGS' &&
43+
error.message.includes('JSON replay payloads are no longer supported'),
44+
);
45+
});

‎packages/ad-replay/src/internal/__tests__/step-loop.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ import type { TargetAnnotationV1 } from '@agent-device/contracts/replay';
1111
* terminal-close suppression) is engine-private — never re-exported by the
1212
* façade (`packages/ad-replay/src/index.ts`) — so these tests exercise it
1313
* only through `runAdReplay` itself, the same way the daemon's own
14-
* `session-replay-runtime.ts` (`runReplayScriptFile`) does. The equivalent
15-
* daemon-level assertions (full `SessionStore`/`runReplayScriptFile` round
14+
* `session-replay-runtime.ts` (`runReplayScriptSource`) does. The equivalent
15+
* daemon-level assertions (full `SessionStore`/`runReplayScriptSource` round
1616
* trip, including the `--keep-session` live-session postcondition) live in
1717
* `src/daemon/handlers/__tests__/session-replay-runtime-keep-session.test.ts`
1818
* (renamed from `session-replay-terminal-lifecycle.test.ts` by the #1555

‎packages/ad-replay/src/internal/inspect.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import fs from 'node:fs';
21
import { AppError } from '@agent-device/kernel/errors';
32
import type { SessionAction } from '@agent-device/contracts/session';
43
import {
@@ -12,7 +11,7 @@ import { resolveReplayEntryIndex, type PendingRecordAndHeal } from './resume.ts'
1211

1312
/**
1413
* #1478 P5 stage C2b: the read-only `.ad` inspection façade. Moved out of
15-
* `session-replay-runtime.ts`'s old `parseReplayScript` (the fs read + the
14+
* `session-replay-runtime.ts`'s old `parseReplayScript` (the
1615
* legacy-JSON-payload rejection it guarded) plus the `parseReplayInput`
1716
* composition (`src/compat/replay-input.ts`) it fed into — this is the same
1817
* `parseReplayScriptDetailed` + `readReplayScriptMetadata` pair
@@ -50,12 +49,14 @@ export type AdReplayManifest = Readonly<{
5049
export type AdReplayDigestFlags = Readonly<{ platform?: string; target?: string }>;
5150

5251
/**
53-
* Reads `sourcePath` once and returns its parsed actions/line table, header
54-
* metadata, plan digest, and resume-index resolver. Throws
52+
* Parses one `.ad` script's TEXT and returns its actions/line table, header
53+
* metadata, plan digest, and resume-index resolver. Takes the script itself,
54+
* never a path: #1802 made the CALLER read every script file a replay run
55+
* needs, so nothing below this façade opens a file. Throws
5556
* `AppError('INVALID_ARGS', …)` for the one source format `.ad` replay no
5657
* longer accepts — a legacy JSON replay payload — matching the daemon's
5758
* prior explicit rejection exactly. Callers do not need to check for this
58-
* case separately: `runReplayScriptFile`'s top-level catch (`asAppError`)
59+
* case separately: `runReplayScriptSource`'s top-level catch (`asAppError`)
5960
* maps a thrown `AppError` straight to the same `errorResponse` the old
6061
* explicit branch built, so this is not a behavior change, only where the
6162
* check lives.
@@ -67,10 +68,9 @@ export type AdReplayDigestFlags = Readonly<{ platform?: string; target?: string
6768
* `open` wins; absent that, the `context platform=`/`target=` header line.
6869
*/
6970
export function inspectAdReplay(
70-
sourcePath: string,
71+
script: string,
7172
digestFlags?: AdReplayDigestFlags,
7273
): AdReplayManifest {
73-
const script = fs.readFileSync(sourcePath, 'utf8');
7474
const firstNonWhitespace = script.trimStart()[0];
7575
if (firstNonWhitespace === '{' || firstNonWhitespace === '[') {
7676
throw new AppError(

‎packages/ad-replay/src/internal/step-loop.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ import type {
7171
*
7272
* #1478 P5 follow-up (one daemon-owned artifact ledger): artifact-path
7373
* accumulation used to be DOUBLE-WRITTEN — `dispatchStep` added each step's
74-
* entries to the daemon's own `Set` (`runReplayScriptFile`'s, read by its
74+
* entries to the daemon's own `Set` (`runReplayScriptSource`'s, read by its
7575
* catch block so a mid-loop throw still reports what was collected) AND
7676
* returned them for this loop to add to a second `Set` of its own. Two
7777
* mutable collections, kept in sync by hand, with no single owner. The

‎packages/contracts/src/cli-flags.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import type {
2020
} from './remote-config-fields.ts';
2121
import type { ScreenshotRequestFlags } from './screenshot.ts';
2222
import type { RecordingScope } from './recording-scope.ts';
23+
import type { ReplayScriptSourceBundle } from './replay.ts';
2324

2425
export type CliFlags = CloudProviderProfileFields &
2526
RemoteConfigMetroOptions &
@@ -143,6 +144,13 @@ export type CliFlags = CloudProviderProfileFields &
143144
replayMaestro?: boolean;
144145
replayEnv?: string[];
145146
replayShellEnv?: Record<string, string>;
147+
/**
148+
* #1802: the caller-read script text `replay` executes. The daemon never
149+
* opens a caller path, so this is the ONLY source a replay run reads.
150+
*/
151+
replayScriptSource?: ReplayScriptSourceBundle;
152+
/** #1802: `test`'s caller-side discovery result — one bundle per discovered source, in run order. */
153+
replayScriptSources?: ReplayScriptSourceBundle[];
146154
replayFrom?: number;
147155
replayPlanDigest?: string;
148156
/** Replay: leave the session active by suppressing an authored terminal close in native .ad. */

‎packages/contracts/src/client-request.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import type {
1515
SessionRuntimeHints,
1616
} from '@agent-device/kernel/contracts';
1717
import type { DaemonBatchStep } from './batch-step.ts';
18+
import type { ReplayScriptSourceBundle } from './replay.ts';
1819
import type { AgentDeviceClientConfig, AgentDeviceSelectionOptions } from './client-connection.ts';
1920

2021
export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
@@ -54,6 +55,10 @@ export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
5455
replayBackend?: string;
5556
replayEnv?: string[];
5657
replayShellEnv?: Record<string, string>;
58+
/** #1802: caller-read script text for `replay`; the daemon never opens a caller path. */
59+
replayScriptSource?: ReplayScriptSourceBundle;
60+
/** #1802: caller-side `test` discovery result — one bundle per discovered source, in run order. */
61+
replayScriptSources?: ReplayScriptSourceBundle[];
5762
replayFrom?: number;
5863
replayPlanDigest?: string;
5964
replayKeepSession?: boolean;

‎packages/contracts/src/facades/replay.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ export type { RefFrameEffect } from '../ref-frame-effect.ts';
22
export { REPLAY_TARGET_GUARD_MISMATCH_REASON, WAIT_LANDMARK_MISMATCH_REASON } from '../replay.ts';
33
export type {
44
ReplayCommandResult,
5+
ReplayScriptSourceBundle,
56
ReplaySuiteAttemptFailure,
67
ReplaySuiteResult,
78
ReplaySuiteTestFailed,

‎packages/contracts/src/replay.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,3 +141,25 @@ export type ReplaySuiteResult = {
141141
tests: ReplaySuiteTestResult[];
142142
snapshotDiagnostics?: SnapshotDiagnosticsSummary;
143143
};
144+
145+
/**
146+
* A **replay script source bundle**: every script file one replay run needs,
147+
* read and resolved by the CALLER and shipped with the request.
148+
*
149+
* `replay <path>` used to send only the path, which the daemon then opened on
150+
* ITS filesystem. That works only while caller and daemon share a disk; against
151+
* a remote daemon it fails with `ENOENT` on a path the caller can read (#1802).
152+
* The bundle removes the class: the daemon never resolves a caller path, so a
153+
* local run and a remote run read exactly the same bytes.
154+
*
155+
* `entry` is the caller-resolved absolute path of the script that was invoked —
156+
* it is also the display path every error, line reference, and
157+
* `actionSourcePaths` entry is stated in, and it is always a key of `files`.
158+
* `files` maps each caller-resolved absolute path to that file's text: one
159+
* entry for a native `.ad` script, plus one per transitively included flow for
160+
* Maestro YAML `runFlow`.
161+
*/
162+
export type ReplayScriptSourceBundle = Readonly<{
163+
entry: string;
164+
files: Readonly<Record<string, string>>;
165+
}>;

‎packages/maestro/src/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,13 @@ export {
1111
type MaestroFlow,
1212
} from './internal/facade-execution.ts';
1313

14+
export type { MaestroSourceReader } from './internal/program-loader.ts';
15+
16+
export {
17+
collectMaestroFlowSources,
18+
type MaestroOptionalSourceReader,
19+
} from './internal/source-closure.ts';
20+
1421
export {
1522
exportReplayActionsToMaestro,
1623
MAESTRO_SELECTOR_PROJECTION,

0 commit comments

Comments
 (0)