Skip to content

Commit cad4ee2

Browse files
committed
fix(limrun): stop the recorder once and download the served MP4 as a bounded, retriable step
The first cut asked the SDK to stop and download in one call, so a dropped transfer after a successful server stop left the next record stop re-stopping an idle recorder and never fetching the finished file. The device session now stops without a local path and answers the served URL; the host downloads it with a deadline and the discard signal through a new LimrunHostAdapter.downloadFile port, and the transport helper memoizes the stop so only the download is retried. ADR 0024 gains the Limrun row and --quality help names the Limrun mapping.
1 parent c89b151 commit cad4ee2

18 files changed

Lines changed: 450 additions & 206 deletions

‎CHANGELOG.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,13 @@
33
## Unreleased
44

55
- Added (limrun): `record start` and `record stop` on Limrun iOS and Android direct sessions. The
6-
runtime declared recording unavailable although the Limrun SDK exposes a server-side recorder;
7-
start now asks the instance to record (`--quality medium` maps to Limrun quality 5, `high` to 8)
8-
and stop downloads the finished MP4 to the output path. The capture is always the whole simulator
9-
or emulator screen; `--fps` and `--hide-touches` are refused, and a recording cannot be reattached
10-
after a daemon restart.
6+
runtime declared recording unavailable although the Limrun SDK exposes a server-side recorder.
7+
Start asks the instance to record (`--quality medium` maps to Limrun quality 5, `high` to 8);
8+
stop asks the instance to stop once, then downloads the served MP4 to the output path as a
9+
separate bounded step, so a dropped transfer is retried by the next `record stop` without a
10+
second remote stop. The capture is always the whole simulator or emulator screen; `--fps` and
11+
`--hide-touches` are refused, and a recording cannot be reattached after a daemon restart. The
12+
web recorder now shares the same transport-recording runtime.
1113
- Added (limrun): `longpress` on Limrun iOS direct sessions. The interactor refused it as
1214
unsupported although the SDK exposes the HID primitives; it now holds one touch as a
1315
`performActions` batch of `touchDown`, `wait`, `touchUp`, defaulting to the 800 ms the Android

‎docs/adr/0024-screen-recording-provable-signal.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -316,7 +316,8 @@ rotation stays. This lands after 2.1–2.7 and is not required by them.
316316
| Android | probe `/proc`, then `kill -2` → `-9`; `unconfirmed` when `/proc` is unreadable | same, from the pid triple in the descriptor | `adb pull` of every chunk, playability sniff | reattach through the device manifest; five ownership states |
317317
| HarmonyOS | one `aa start` toggle, tracked by the handle | **no signal**; `mediatool query` by file name; `unconfirmed` if found, `lost` if not | stage + `hdc file recv` | `cleanup-pending`, manual |
318318
| Web | provider `record stop` on the session browser | stop if the browser is alive, else `lost` | local copy of the WebM; native file retained while the browser is not proven gone | `cleanup-pending`, manual |
319-
| Limrun, WebDriver providers, Vega | unavailable | — | — | unchanged |
319+
| Limrun (iOS, Android) | provider stop RPC on the live session; the served download URL is memoized so a stop is never repeated | **no signal**: the recording lives and dies with the instance; `unreattachable` | bounded, cancellable HTTP download of the served MP4 to the output path; retriable from the memoized URL while the instance lives | `cleanup-pending`, manual; the instance (and its file) is deleted on lease release |
320+
| WebDriver providers, Vega | unavailable | — | — | unchanged |
320321

321322
Two traps stay visible: a blind HarmonyOS toggle **starts** a recording, so only the live handle
322323
may toggle; and the Apple runner recording dies with the runner process, so `lost` after a keep-hot

‎packages/command-registry/src/flag-definitions-action.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
4242
type: 'string',
4343
usageLabel: '--quality <medium|high>',
4444
usageDescription:
45-
'Record: output quality preset; Android maps this to screenrecord bitrate, Apple targets use it for export/encoding. Legacy numeric values 5-7 map to medium; 8-10 map to high',
45+
'Record: output quality preset; Android maps this to screenrecord bitrate, Apple targets use it for export/encoding, Limrun sessions map medium to recorder quality 5 and high to 8. Legacy numeric values 5-7 map to medium; 8-10 map to high',
4646
projectConfig: true,
4747
recorded: true,
4848
},

‎packages/provider-limrun/src/android.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ type LimrunAndroidAdbSession = {
3434
instanceId: string;
3535
device: DeviceInfo;
3636
client: LimrunAndroidClient;
37+
/** Instance bearer token; the recording download the SDK would run inline is done by the host instead. */
38+
readonly token: string;
3739
adbTunnel?: LimrunAdbTunnel;
3840
adbSerial?: string;
3941
adbTunnelPromise?: Promise<string>;
@@ -67,6 +69,7 @@ export async function createLimrunAndroidSession(
6769
instanceId: options.instanceId,
6870
device: options.device,
6971
client,
72+
token: options.token,
7073
dependencies,
7174
};
7275
const adbProvider: LimrunAdbProvider = {

‎packages/provider-limrun/src/device-session.test.ts‎

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import { AppError } from '@agent-device/kernel/errors';
77
import type {
88
LimrunAdbExecutor,
99
LimrunAdbProvider,
10+
LimrunFileDownload,
1011
LimrunRuntimeDependencies,
1112
} from './runtime-dependencies.ts';
1213
import type { LimrunAndroidSession } from './android.ts';
@@ -18,6 +19,8 @@ const IOS_APPS = [
1819
{ bundleId: 'com.example.ios', name: 'Example', installType: 'User' },
1920
];
2021

22+
const downloadFile = vi.fn(async (_options: LimrunFileDownload) => undefined);
23+
2124
const TEST_DEPENDENCIES = {
2225
clientVersion: 'test-version',
2326
android: {
@@ -49,6 +52,7 @@ const TEST_DEPENDENCIES = {
4952
host: {
5053
runAdb: async () => adbResult(''),
5154
archiveDirectory: async () => undefined,
55+
downloadFile,
5256
},
5357
ios: {
5458
resolveAppAlias: async (app: string) => app,
@@ -90,10 +94,11 @@ test('iOS device session exposes reusable capabilities without its raw client',
9094
await session.pressKey('enter', ['command']);
9195
assert.equal(await session.readLogs('com.example.ios', 200), 'line one\nline two\n');
9296
await session.startRecording({ quality: 8 });
93-
assert.equal(
94-
await session.stopRecording({ outPath: '/tmp/ios-recording.mp4' }),
95-
'https://ios.example/recording',
96-
);
97+
assert.deepEqual(await session.stopRecording(), { downloadUrl: 'https://ios.example/recording' });
98+
await session.downloadRecording({
99+
downloadUrl: 'https://ios.example/recording',
100+
outPath: '/tmp/ios-recording.mp4',
101+
});
97102
assert.deepEqual(await session.runSimctl(['listapps', 'booted']).wait(), {
98103
code: 0,
99104
stdout: 'ok',
@@ -103,7 +108,15 @@ test('iOS device session exposes reusable capabilities without its raw client',
103108
assert.deepEqual(pressKey.mock.calls[0], ['enter', ['command']]);
104109
assert.deepEqual(readLogs.mock.calls[0], ['com.example.ios', 200]);
105110
assert.deepEqual(startRecording.mock.calls[0], [{ quality: 8 }]);
106-
assert.deepEqual(stopRecording.mock.calls[0], [{ localPath: '/tmp/ios-recording.mp4' }]);
111+
assert.deepEqual(stopRecording.mock.calls[0], [{}]);
112+
assert.deepEqual(downloadFile.mock.calls.at(-1), [
113+
{
114+
url: 'https://ios.example/recording',
115+
headers: { Authorization: 'Bearer ios-instance-token' },
116+
destinationPath: '/tmp/ios-recording.mp4',
117+
timeoutMs: 120_000,
118+
},
119+
]);
107120
assert.deepEqual(simctl.mock.calls[0], [['listapps', 'booted']]);
108121
assert.equal('client' in session, false);
109122
});
@@ -173,16 +186,28 @@ test('Android device session exposes semantic ADB capabilities without its raw c
173186
assert.equal(await session.installRemoteApp('https://assets.example/android.apk'), undefined);
174187
await session.pressKey('KEYCODE_ENTER', ['shift']);
175188
await session.startRecording({ quality: 7 });
176-
assert.equal(
177-
await session.stopRecording({ outPath: '/tmp/android-recording.mp4' }),
178-
'https://android.example/recording',
179-
);
189+
assert.deepEqual(await session.stopRecording(), {
190+
downloadUrl: 'https://android.example/recording',
191+
});
192+
await session.downloadRecording({
193+
downloadUrl: 'https://android.example/recording',
194+
outPath: '/tmp/android-recording.mp4',
195+
timeoutMs: 30_000,
196+
});
180197
await session.adb.reverse?.remove('tcp:8081');
181198

182199
assert.deepEqual(sendAsset.mock.calls[0], ['https://assets.example/android.apk']);
183200
assert.deepEqual(pressKey.mock.calls[0], ['KEYCODE_ENTER', ['shift']]);
184201
assert.deepEqual(startRecording.mock.calls[0], [{ quality: 7 }]);
185-
assert.deepEqual(stopRecording.mock.calls[0], [{ localPath: '/tmp/android-recording.mp4' }]);
202+
assert.deepEqual(stopRecording.mock.calls[0], [{}]);
203+
assert.deepEqual(downloadFile.mock.calls.at(-1), [
204+
{
205+
url: 'https://android.example/recording',
206+
headers: { Authorization: 'Bearer android-instance-token' },
207+
destinationPath: '/tmp/android-recording.mp4',
208+
timeoutMs: 30_000,
209+
},
210+
]);
186211
assert.deepEqual(removeReverse.mock.calls[0], ['tcp:8081']);
187212
assert.equal(session.adb, provider);
188213
assert.equal('client' in session, false);
@@ -195,6 +220,7 @@ function iosSession(client: Record<string, unknown>): LimrunIosSession {
195220
instanceId: 'ios-instance',
196221
device: device('ios'),
197222
client,
223+
token: 'ios-instance-token',
198224
dependencies: TEST_DEPENDENCIES,
199225
} as unknown as LimrunIosSession;
200226
}
@@ -210,6 +236,7 @@ function androidSession(
210236
device: device('android'),
211237
client,
212238
adbProvider,
239+
token: 'android-instance-token',
213240
dependencies: TEST_DEPENDENCIES,
214241
} as unknown as LimrunAndroidSession;
215242
}

‎packages/provider-limrun/src/device-session.ts‎

Lines changed: 38 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import type {
55
LimrunAdbProvider,
66
LimrunAndroidKeyboardDismissResult,
77
LimrunAndroidKeyboardState,
8+
LimrunHostAdapter,
89
} from './runtime-dependencies.ts';
910
import { createLimrunAndroidInteractor, type LimrunAndroidSession } from './android.ts';
1011
import {
@@ -59,14 +60,25 @@ type LimrunDeviceSessionBase = {
5960
listApps(filter?: AppsFilter): Promise<LimrunInstalledApp[]>;
6061
pressKey(key: string, modifiers?: string[]): Promise<void>;
6162
startRecording(options?: { quality?: LimrunRecordingQuality }): Promise<void>;
62-
stopRecording(options: { outPath: string }): Promise<string>;
63+
/** Stops the instance recorder and answers where the finished file is served; nothing is downloaded. */
64+
stopRecording(): Promise<{ downloadUrl: string }>;
65+
/** Fetches a served recording to `outPath`, bounded by `timeoutMs` and `signal`. Retriable while the instance lives. */
66+
downloadRecording(input: {
67+
downloadUrl: string;
68+
outPath: string;
69+
signal?: AbortSignal;
70+
timeoutMs?: number;
71+
}): Promise<void>;
6372
};
6473

6574
type LimrunRecordingClient = {
6675
startRecording(options?: { quality?: LimrunRecordingQuality }): Promise<void>;
67-
stopRecording(options: { localPath: string }): Promise<string>;
76+
stopRecording(saveTo: { localPath?: string }): Promise<string>;
6877
};
6978

79+
/** The SDK's own inline download has no deadline; a served MP4 of a few minutes fits well inside this. */
80+
const LIMRUN_RECORDING_DOWNLOAD_TIMEOUT_MS = 120_000;
81+
7082
export type LimrunAndroidDeviceSession = LimrunDeviceSessionBase & {
7183
readonly platform: 'android';
7284
readonly adb: LimrunAdbProvider;
@@ -115,7 +127,7 @@ function createAndroidDeviceSession(session: LimrunAndroidSession): LimrunAndroi
115127
getKeyboardState: async () => await session.dependencies.android.getKeyboardState(adb),
116128
dismissKeyboard: async () => await session.dependencies.android.dismissKeyboard(adb),
117129
readLogs: async (lineLimit) => await session.dependencies.android.readLogs(adb, lineLimit),
118-
...createRecordingOperations(session.client),
130+
...createRecordingOperations(session.client, session.token, session.dependencies.host),
119131
installRemoteApp: async (url) => {
120132
await session.client.sendAsset(url);
121133
},
@@ -144,19 +156,38 @@ function createIosDeviceSession(session: LimrunIosSession): LimrunIosDeviceSessi
144156
await session.client.pressKey(key, modifiers);
145157
},
146158
readLogs: async (appId, lineLimit) => await session.client.appLogTail(appId, lineLimit),
147-
...createRecordingOperations(session.client),
159+
...createRecordingOperations(session.client, session.token, session.dependencies.host),
148160
installRemoteApp: async (url, options) =>
149161
await installLimrunIosRemoteApp(session, url, options),
150162
runSimctl: (args): LimrunIosCommandExecution => session.client.simctl(args),
151163
};
152164
}
153165

154-
function createRecordingOperations(client: LimrunRecordingClient) {
166+
function createRecordingOperations(
167+
client: LimrunRecordingClient,
168+
token: string,
169+
host: Pick<LimrunHostAdapter, 'downloadFile'>,
170+
) {
155171
return {
156172
startRecording: async (options?: { quality?: LimrunRecordingQuality }) => {
157173
await client.startRecording(options);
158174
},
159-
stopRecording: async ({ outPath }: { outPath: string }) =>
160-
await client.stopRecording({ localPath: outPath }),
175+
// Without `localPath` the SDK only stops the recorder and returns the served URL; a download
176+
// tied to the one-shot stop could not be retried after a dropped transfer.
177+
stopRecording: async () => ({ downloadUrl: await client.stopRecording({}) }),
178+
downloadRecording: async (input: {
179+
downloadUrl: string;
180+
outPath: string;
181+
signal?: AbortSignal;
182+
timeoutMs?: number;
183+
}) => {
184+
await host.downloadFile({
185+
url: input.downloadUrl,
186+
headers: { Authorization: `Bearer ${token}` },
187+
destinationPath: input.outPath,
188+
timeoutMs: input.timeoutMs ?? LIMRUN_RECORDING_DOWNLOAD_TIMEOUT_MS,
189+
...(input.signal === undefined ? {} : { signal: input.signal }),
190+
});
191+
},
161192
};
162193
}

‎packages/provider-limrun/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ export { LIMRUN_PROVIDER } from './device.ts';
22
export { createLimrunRuntime, type LimrunRuntime, type LimrunRuntimeOptions } from './runtime.ts';
33
export { verifyLimrunConnection } from './connection-verification.ts';
44

5-
export type { LimrunRuntimeDependencies } from './runtime-dependencies.ts';
5+
export type { LimrunFileDownload, LimrunRuntimeDependencies } from './runtime-dependencies.ts';
66

77
export type {
88
LimrunAndroidDeviceSession,

‎packages/provider-limrun/src/ios.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ export type LimrunIosSession = {
3131
instanceId: string;
3232
device: DeviceInfo;
3333
client: LimrunIosClient;
34+
/** Instance bearer token; the recording download the SDK would run inline is done by the host instead. */
35+
readonly token: string;
3436
readonly dependencies: Pick<LimrunRuntimeDependencies, 'host' | 'ios'>;
3537
};
3638

@@ -67,6 +69,7 @@ export async function createLimrunIosSession(
6769
instanceId: options.instanceId,
6870
device: options.device,
6971
client,
72+
token: options.token,
7073
dependencies,
7174
};
7275
}

0 commit comments

Comments
 (0)