Skip to content

Commit 442d367

Browse files
committed
chore(gates): export the contact-sheet refusal vocabulary
1 parent d1a5999 commit 442d367

5 files changed

Lines changed: 78 additions & 24 deletions

File tree

‎apple/runner/AgentDeviceRunner/RecordingScripts/recording-frames.swift‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,20 @@ func run() throws {
9393
continue
9494
}
9595

96+
// A frame the decoder cannot place on the timeline is not a frame at 0 ms. Writing it would
97+
// label a mid-clip moment as the opening one, so the sample goes unanswered instead and the
98+
// manifest says so.
99+
guard CMTIME_IS_VALID(actualTime), actualTime.timescale != 0 else {
100+
skipped.append(
101+
FrameManifest.Skipped(
102+
index: index,
103+
requestedTimeMs: requestedTimeMs,
104+
reason: "Decoder returned no presentation time for this frame"
105+
)
106+
)
107+
continue
108+
}
109+
96110
let outputURL = outputDirectoryURL.appendingPathComponent(frameFileName(index: index))
97111
do {
98112
try writePNG(cgImage: cgImage, to: outputURL)

‎packages/capture-kit/src/recording/contact-sheet-frames.test.ts‎

Lines changed: 40 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import path from 'node:path';
33
import {
44
CONTACT_SHEET_EXTRACTION_REASON,
55
CONTACT_SHEET_NO_FRAMES_REASON,
6+
CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
67
} from '@agent-device/contracts/recording-contact-sheet';
78
import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors';
89
import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts';
@@ -34,6 +35,13 @@ function reasonOf(action: () => Promise<unknown>): Promise<unknown> | unknown {
3435
);
3536
}
3637

38+
/** Decoding is Apple tooling, so every case here states the host it is pretending to be. */
39+
function extract(
40+
input: Omit<Parameters<typeof extractRecordingFrames>[0], 'hostPlatform'>,
41+
): Promise<Awaited<ReturnType<typeof extractRecordingFrames>>> {
42+
return extractRecordingFrames({ ...input, hostPlatform: 'darwin' });
43+
}
44+
3745
function withTimes(args: readonly string[], times: string): string[] {
3846
const rewritten = [...args];
3947
rewritten[rewritten.indexOf('--times') + 1] = times;
@@ -51,6 +59,22 @@ describe('extractRecordingFrames', () => {
5159
mockRunCmd.mockReset();
5260
});
5361

62+
test('refuses to decode at all on a host with no frame decoder', async () => {
63+
expect(
64+
await reasonOf(() =>
65+
extractRecordingFrames({
66+
videoPath: VIDEO,
67+
scratchDir,
68+
maxWidth: CELL_WIDTH,
69+
timesMs: [0],
70+
hostPlatform: 'linux',
71+
}),
72+
),
73+
).toBe(CONTACT_SHEET_UNSUPPORTED_HOST_REASON);
74+
// Refused before the compiler or the decoder ran, so a Linux host never pays for a spawn.
75+
expect(mockRunCmd).not.toHaveBeenCalled();
76+
});
77+
5478
test('asks the helper for exactly the grid it was given', async () => {
5579
answerWith(
5680
new Map([
@@ -59,7 +83,7 @@ describe('extractRecordingFrames', () => {
5983
]),
6084
);
6185

62-
await extractRecordingFrames({
86+
await extract({
6387
videoPath: VIDEO,
6488
scratchDir,
6589
maxWidth: CELL_WIDTH,
@@ -90,7 +114,7 @@ describe('extractRecordingFrames', () => {
90114
]),
91115
);
92116

93-
const extracted = await extractRecordingFrames({
117+
const extracted = await extract({
94118
videoPath: VIDEO,
95119
scratchDir,
96120
maxWidth: CELL_WIDTH,
@@ -105,7 +129,7 @@ describe('extractRecordingFrames', () => {
105129
test('counts the sample times the decoder declined', async () => {
106130
answerWith(new Map([[0, { png: solidPng(4, 4), actualTimeMs: 0 }]]));
107131

108-
const extracted = await extractRecordingFrames({
132+
const extracted = await extract({
109133
videoPath: VIDEO,
110134
scratchDir,
111135
maxWidth: CELL_WIDTH,
@@ -131,7 +155,7 @@ describe('extractRecordingFrames', () => {
131155
return { ...result, stdout: JSON.stringify(manifest) };
132156
});
133157

134-
const extracted = await extractRecordingFrames({
158+
const extracted = await extract({
135159
videoPath: VIDEO,
136160
scratchDir,
137161
maxWidth: CELL_WIDTH,
@@ -160,7 +184,7 @@ describe('extractRecordingFrames', () => {
160184

161185
expect(
162186
await reasonOf(() =>
163-
extractRecordingFrames({
187+
extract({
164188
videoPath: VIDEO,
165189
scratchDir,
166190
maxWidth: CELL_WIDTH,
@@ -182,7 +206,7 @@ describe('extractRecordingFrames', () => {
182206

183207
expect(
184208
await reasonOf(() =>
185-
extractRecordingFrames({
209+
extract({
186210
videoPath: VIDEO,
187211
scratchDir,
188212
maxWidth: CELL_WIDTH,
@@ -195,7 +219,7 @@ describe('extractRecordingFrames', () => {
195219
test('counts samples the manifest neither answered nor declared skipped', async () => {
196220
answerWith(new Map([[0, { png: solidPng(4, 4), actualTimeMs: 0 }]]));
197221

198-
const extracted = await extractRecordingFrames({
222+
const extracted = await extract({
199223
videoPath: VIDEO,
200224
scratchDir,
201225
maxWidth: CELL_WIDTH,
@@ -214,7 +238,7 @@ describe('extractRecordingFrames', () => {
214238

215239
expect(
216240
await reasonOf(() =>
217-
extractRecordingFrames({
241+
extract({
218242
videoPath: VIDEO,
219243
scratchDir,
220244
maxWidth: CELL_WIDTH,
@@ -229,7 +253,7 @@ describe('extractRecordingFrames', () => {
229253

230254
expect(
231255
await reasonOf(() =>
232-
extractRecordingFrames({
256+
extract({
233257
videoPath: VIDEO,
234258
scratchDir,
235259
maxWidth: CELL_WIDTH,
@@ -243,7 +267,7 @@ describe('extractRecordingFrames', () => {
243267
answerWith(new Map([[0, { png: solidPng(4, 4), actualTimeMs: 0 }]]));
244268
const controller = new AbortController();
245269

246-
await extractRecordingFrames({
270+
await extract({
247271
videoPath: VIDEO,
248272
scratchDir,
249273
maxWidth: CELL_WIDTH,
@@ -261,7 +285,7 @@ describe('extractRecordingFrames', () => {
261285
const controller = new AbortController();
262286
controller.abort();
263287

264-
const error = await extractRecordingFrames({
288+
const error = await extract({
265289
videoPath: VIDEO,
266290
scratchDir,
267291
maxWidth: CELL_WIDTH,
@@ -284,11 +308,11 @@ describe('extractRecordingFrames', () => {
284308
);
285309

286310
await expect(
287-
extractRecordingFrames({ videoPath: VIDEO, scratchDir, maxWidth: CELL_WIDTH, timesMs: [0] }),
311+
extract({ videoPath: VIDEO, scratchDir, maxWidth: CELL_WIDTH, timesMs: [0] }),
288312
).rejects.toThrow(/could not open asset/);
289313
expect(
290314
await reasonOf(() =>
291-
extractRecordingFrames({
315+
extract({
292316
videoPath: VIDEO,
293317
scratchDir,
294318
maxWidth: CELL_WIDTH,
@@ -303,7 +327,7 @@ describe('extractRecordingFrames', () => {
303327

304328
expect(
305329
await reasonOf(() =>
306-
extractRecordingFrames({
330+
extract({
307331
videoPath: VIDEO,
308332
scratchDir,
309333
maxWidth: CELL_WIDTH,
@@ -318,7 +342,7 @@ describe('extractRecordingFrames', () => {
318342

319343
expect(
320344
await reasonOf(() =>
321-
extractRecordingFrames({
345+
extract({
322346
videoPath: VIDEO,
323347
scratchDir,
324348
maxWidth: CELL_WIDTH,
@@ -331,7 +355,7 @@ describe('extractRecordingFrames', () => {
331355
test('refuses to spawn a decoder for an empty grid', async () => {
332356
expect(
333357
await reasonOf(() =>
334-
extractRecordingFrames({ videoPath: VIDEO, scratchDir, maxWidth: CELL_WIDTH, timesMs: [] }),
358+
extract({ videoPath: VIDEO, scratchDir, maxWidth: CELL_WIDTH, timesMs: [] }),
335359
),
336360
).toBe(CONTACT_SHEET_NO_FRAMES_REASON);
337361
expect(mockRunCmd).not.toHaveBeenCalled();

‎packages/capture-kit/src/recording/contact-sheet-frames.ts‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,12 @@ import {
55
CONTACT_SHEET_NO_FRAMES_REASON,
66
CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
77
} from '@agent-device/contracts/recording-contact-sheet';
8-
import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors';
8+
import {
9+
AppError,
10+
createRequestCanceledError,
11+
errorMessage,
12+
isRequestCanceledError,
13+
} from '@agent-device/kernel/errors';
914
import { runCmd } from '@agent-device/host-kit/command';
1015
import { findProjectRoot } from '@agent-device/host-kit/version';
1116
import {
@@ -67,9 +72,14 @@ export async function extractRecordingFrames(
6772
timesMs: readonly number[];
6873
/** Widest cell the caller will draw, so no frame is decoded wider than it can be shown. */
6974
maxWidth: number;
75+
hostPlatform?: NodeJS.Platform;
7076
signal?: AbortSignal;
7177
}>,
7278
): Promise<ExtractedRecordingFrames> {
79+
// Decoding is the Apple tooling, so the host question has to be answered before this module
80+
// spawns anything; a caller that only asks for frames gets the same reason as one that asked
81+
// for a sheet.
82+
assertContactSheetHostSupport(input.hostPlatform ?? process.platform);
7383
if (input.timesMs.length === 0) {
7484
throw new AppError('COMMAND_FAILED', 'Contact sheet sampling requested no frames', {
7585
reason: CONTACT_SHEET_NO_FRAMES_REASON,
@@ -103,7 +113,7 @@ export async function extractRecordingFrames(
103113
},
104114
);
105115
} catch (error) {
106-
throw asExtractionFailure(error, input.videoPath, 'Failed to run the frame decoder');
116+
throwExtractionFailure(error, input.videoPath, 'Failed to run the frame decoder');
107117
}
108118
if (result.exitCode !== 0) {
109119
throw new AppError(
@@ -219,14 +229,15 @@ function extractionUnreadable(videoPath: string, detail: string): AppError {
219229
/**
220230
* A helper that could not start, was killed at its deadline, or never compiled is an extraction
221231
* failure too; letting a raw process error escape would strand it outside the typed taxonomy. A
222-
* failure that already names its reason keeps it.
232+
* canceled request and a failure that already names its reason are both answers the caller asked
233+
* for, so they travel unchanged.
223234
*/
224-
function asExtractionFailure(error: unknown, videoPath: string, stage: string): AppError {
235+
function throwExtractionFailure(error: unknown, videoPath: string, stage: string): never {
236+
if (isRequestCanceledError(error)) throw error;
225237
if (error instanceof AppError && error.code === 'COMMAND_FAILED' && error.details?.reason) {
226-
return error;
238+
throw error;
227239
}
228-
const detail = error instanceof Error ? error.message : String(error);
229-
return extractionError(`${stage} for ${videoPath}: ${detail}`, videoPath, error);
240+
throw extractionError(`${stage} for ${videoPath}: ${errorMessage(error)}`, videoPath, error);
230241
}
231242

232243
function readRecord(value: unknown): Record<string, unknown> {
@@ -258,7 +269,7 @@ async function compileDecoder(input: { videoPath: string; signal?: AbortSignal }
258269
timeoutMs: COMPILATION_TIMEOUT_MS,
259270
});
260271
} catch (error) {
261-
throw asExtractionFailure(error, input.videoPath, 'Could not build the frame decoder');
272+
throwExtractionFailure(error, input.videoPath, 'Could not build the frame decoder');
262273
}
263274
}
264275

‎packages/contracts/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,10 @@
368368
"types": "./src/facades/recording.ts",
369369
"default": "./src/facades/recording.ts"
370370
},
371+
"./recording-contact-sheet": {
372+
"types": "./src/recording-contact-sheet.ts",
373+
"default": "./src/recording-contact-sheet.ts"
374+
},
371375
"./recording-native-path": {
372376
"types": "./src/recording-native-path.ts",
373377
"default": "./src/recording-native-path.ts"

‎scripts/layering/contracts-exports.snapshot.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@
8888
"@agent-device/contracts/react-native-overlay",
8989
"@agent-device/contracts/record-runtime-execution",
9090
"@agent-device/contracts/recording",
91+
"@agent-device/contracts/recording-contact-sheet",
9192
"@agent-device/contracts/recording-native-path",
9293
"@agent-device/contracts/recording-stop-observation",
9394
"@agent-device/contracts/recording-stop-progress",

0 commit comments

Comments
 (0)