Skip to content

Commit 2a8e330

Browse files
committed
fix(record): let only an unreadable file end the recording
The wrap I added explained too much. It took every error the export path raised — a telemetry write that failed once, a finalize hiccup — gave it `retriable: false` and the "close this session" hint, and dropped the original `hint` along the way, so a failure a retry would fix told the user to give up. It now fires only on `recording-output-unplayable`, keeps the details it was handed and adds the exit facts to them; anything else the export path raises comes through exactly as it was. The reason the two layers match on is now one exported constant instead of a string each, and the exit details come from `execFailureDetails`, whose parameter accepts the null exit code a process killed by a signal reports — the shape `AppErrorDetails.exitCode` already allows.
1 parent c9ed057 commit 2a8e330

5 files changed

Lines changed: 67 additions & 27 deletions

File tree

‎packages/contracts/src/screen-recording-runtime.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ import type { ResourceOwnershipFence } from './platform-runtime.ts';
99

1010
export const SCREEN_RECORDING_RESOURCE_KIND = 'screen-recording' as const;
1111

12+
/** The recording's file exists and is not a video, which only a still-finalizing recorder can undo. */
13+
export const RECORDING_OUTPUT_UNPLAYABLE_REASON = 'recording-output-unplayable';
14+
1215
type RecordingTelemetryBase = Readonly<{
1316
tMs: number;
1417
x: number;

‎packages/host-kit/src/internal/exec.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -646,10 +646,11 @@ export function requireExecSuccess(
646646
/**
647647
* COMMAND_FAILED details for a non-zero exec result. `processExitError: true`
648648
* lets normalizeError surface the first meaningful stderr line as the user-facing
649-
* message instead of the generic wrap message.
649+
* message instead of the generic wrap message. A process killed by a signal reports
650+
* no exit code, so the raw child_process null is accepted as well.
650651
*/
651652
export function execFailureDetails(
652-
result: Pick<ExecResult, 'stdout' | 'stderr' | 'exitCode'>,
653+
result: Pick<ExecResult, 'stdout' | 'stderr'> & Readonly<{ exitCode: number | null }>,
653654
extra?: Record<string, unknown>,
654655
): Record<string, unknown> {
655656
return {

‎packages/platform-apple/src/recording/runtime.test.ts‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import assert from 'node:assert/strict';
22
import { expect, test, vi } from 'vitest';
33
import { AppError } from '@agent-device/kernel/errors';
4+
import { RECORDING_OUTPUT_UNPLAYABLE_REASON } from '@agent-device/contracts/screen-recording-runtime';
45
import type { AppleScreenRecordingRunnerRequest } from '@agent-device/contracts/screen-recording-runtime-host';
56
import type { DeviceInfo } from '@agent-device/kernel/device';
67
import { localRuntimeOwner } from '@agent-device/contracts/platform-runtime';
@@ -231,7 +232,10 @@ test('a refused simulator finish is re-driven by the next record stop', async ()
231232
const finalize = async () => {
232233
finalizeCalls += 1;
233234
if (finalizeCalls === 1) {
234-
throw new Error('recording was not finalized into a playable video');
235+
throw new AppError('COMMAND_FAILED', 'recording was not finalized into a playable video', {
236+
reason: RECORDING_OUTPUT_UNPLAYABLE_REASON,
237+
retriable: true,
238+
});
235239
}
236240
return {};
237241
};
@@ -302,6 +306,34 @@ test('an unreadable recording names the exit that made it permanent and the way
302306
});
303307
});
304308

309+
test('an export failure the recorder did not cause keeps its own verdict', async () => {
310+
const transient = new AppError('COMMAND_FAILED', 'recording telemetry could not be written', {
311+
reason: 'telemetry-write-failed',
312+
retriable: true,
313+
hint: 'Retry record stop.',
314+
});
315+
const operations = createAppleScreenRecordingOperations({
316+
host: appleHost({
317+
apple: {
318+
startSimulator: async () => ({
319+
markers: [processIdentity],
320+
wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 1 }),
321+
terminate: async () => {},
322+
}),
323+
},
324+
complete: async () => {
325+
throw transient;
326+
},
327+
}),
328+
device: simulator,
329+
owner: localRuntimeOwner('apple'),
330+
signal: new AbortController().signal,
331+
});
332+
const handle = (await operations.screenRecordingStart(input())).pendingHandle.transfer();
333+
334+
await expect(handle.finish()).rejects.toBe(transient);
335+
});
336+
305337
test('a recorder that record stop terminated itself is collected without a warning', async () => {
306338
const operations = createAppleScreenRecordingOperations({
307339
host: appleHost({

‎packages/platform-apple/src/recording/runtime.ts‎

Lines changed: 26 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
import { isIosFamily, type DeviceInfo } from '@agent-device/kernel/device';
22
import { AppError, asAppError } from '@agent-device/kernel/errors';
3+
import { execFailureDetails } from '@agent-device/host-kit/command';
34
import type { CleanupOutcome } from '@agent-device/contracts/durable-resource';
45
import type { HostCommandResult } from '@agent-device/contracts/platform-runtime-host';
56
import type { RuntimeOwnerRef } from '@agent-device/contracts/platform-runtime';
67
import type { ScreenRecordingRuntimeHost } from '@agent-device/contracts/screen-recording-runtime-host';
7-
import type {
8-
ScreenRecordingLiveSnapshot,
9-
ScreenRecordingRuntimeOperations,
10-
ScreenRecordingStartInput,
8+
import {
9+
RECORDING_OUTPUT_UNPLAYABLE_REASON,
10+
type ScreenRecordingLiveSnapshot,
11+
type ScreenRecordingRuntimeOperations,
12+
type ScreenRecordingStartInput,
1113
} from '@agent-device/contracts/screen-recording-runtime';
1214
import { PendingTransferGuard } from '@agent-device/contracts/async-lifecycle';
1315
import { createScreenRecordingLiveHandle } from '@agent-device/capture-kit';
@@ -134,7 +136,7 @@ async function startAppleSimulatorRecording(params: AppleRecordingStartParams) {
134136
`${exit} before record stop; the video covers only what the recorder wrote before it stopped.`,
135137
);
136138
} catch (exportError) {
137-
throw recorderExitLostTheExport(exportError, exit, result);
139+
throw recorderExitEndedTheRecording(exportError, exit, result);
138140
}
139141
},
140142
cleanup: async () => {
@@ -250,28 +252,29 @@ function describeSimctlRecorderExit(result: HostCommandResult): string | undefin
250252
: `simctl recordVideo exited with code ${result.exitCode}`;
251253
}
252254

253-
// The exit is the fact that makes an unreadable file permanent, so it belongs in the error the
254-
// operator reads: the next `record stop` re-reads the same settled exit and the same bytes.
255-
function recorderExitLostTheExport(
255+
// An unreadable file is the one export failure the recorder's exit explains: the next `record stop`
256+
// re-reads the same settled exit and the same bytes, so it names the exit and the way out. Anything
257+
// else the export path raised keeps its own verdict — a telemetry or transport failure a retry can fix
258+
// must not be told to close the session.
259+
function recorderExitEndedTheRecording(
256260
exportError: unknown,
257261
exit: string,
258262
result: HostCommandResult,
259-
): AppError {
263+
): unknown {
260264
const original = asAppError(exportError, 'COMMAND_FAILED');
261-
const { reason } = original.details ?? {};
262-
// `processExitError` is what makes normalizeError append the recorder's first stderr line, so the
263-
// exit facts reach the operator without repeating them in this message.
264-
return new AppError(original.code, `${original.message}; ${exit}`, {
265-
stderr: result.stderr,
266-
exitCode: result.exitCode,
267-
processExitError: true,
268-
...(typeof reason === 'string' ? { reason } : {}),
269-
...(result.signal === undefined ? {} : { signal: result.signal }),
270-
retriable: false,
271-
hint:
272-
'The recorder exited before record stop, so the next record stop reads the same file. ' +
273-
'Close this session to release the device, then record again.',
274-
});
265+
if (original.details?.reason !== RECORDING_OUTPUT_UNPLAYABLE_REASON) return exportError;
266+
return new AppError(
267+
original.code,
268+
`${original.message}; ${exit}`,
269+
execFailureDetails(result, {
270+
...(original.details ?? {}),
271+
...(result.signal === undefined ? {} : { signal: result.signal }),
272+
retriable: false,
273+
hint:
274+
'The recorder exited before record stop, so the next record stop reads the same file. ' +
275+
'Close this session to release the device, then record again.',
276+
}),
277+
);
275278
}
276279

277280
function runnerDescriptorMatchesDevice(

‎src/platform-runtime-screen-recording-finalizer-host.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { AppError } from '@agent-device/kernel/errors';
2+
import { RECORDING_OUTPUT_UNPLAYABLE_REASON } from '@agent-device/contracts/screen-recording-runtime';
23
import type { ScreenRecordingRuntimeHost } from '@agent-device/contracts/screen-recording-runtime-host';
34
import {
45
getRecordingOverlaySupportWarning,
@@ -25,7 +26,7 @@ async function finalizeScreenRecording(
2526
'COMMAND_FAILED',
2627
`recording was not finalized into a playable video: ${input.outputPath}`,
2728
{
28-
reason: 'recording-output-unplayable',
29+
reason: RECORDING_OUTPUT_UNPLAYABLE_REASON,
2930
retriable: true,
3031
hint:
3132
'Run record stop again: a recorder that is still finalizing its file is playable on the ' +

0 commit comments

Comments
 (0)