Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
17c7b37
refactor(reasons): declare the R6b reasons in ReasonTable rows
thymikee Nov 21, 2026
50d8c3c
refactor(reasons): declare find_snapshot_unreadable in capture-kit, w…
thymikee Nov 21, 2026
6dab43a
refactor(reasons): keep the 15 module-local reason tables private
thymikee Nov 21, 2026
f79abea
refactor(reasons): drop the settings app-not-consumed alias
thymikee Nov 21, 2026
95fd770
docs(reasons): say a contact sheet could not obtain usable extracted …
thymikee Nov 21, 2026
4a436c9
Merge remote-tracking branch 'origin/main' into t3/r6b-typed-reasons
thymikee Nov 22, 2026
76c74b4
docs(reasons): cover over-budget frames in the contact-sheet extracti…
thymikee Nov 22, 2026
7d577f1
Merge remote-tracking branch 'origin/main' into t3/r6b-typed-reasons
thymikee Nov 22, 2026
fbb7342
refactor(find): build the sparse-capture refusal once in capture-kit …
thymikee Nov 22, 2026
79bd18b
fix(replay): keep a sparse find refusal's scrubbed verdict in replay …
thymikee Nov 22, 2026
5e458f1
refactor(replay): split the cause-detail projection to stay under the…
thymikee Nov 22, 2026
ba67ebb
Merge remote-tracking branch 'origin/main' into t3/r6b-typed-reasons
thymikee Nov 22, 2026
b4c9bd6
docs(reasons): daemon_exit_unconfirmed covers every unconfirmed stop,…
thymikee Nov 22, 2026
7c0c244
docs(reasons): png_decode_failed covers any input that is not decodab…
thymikee Nov 22, 2026
4db8a3a
refactor(replay): pass the sparse verdict code through unchanged, scr…
thymikee Nov 22, 2026
31fd73c
Merge remote-tracking branch 'origin/main' into t3/r6b-typed-reasons
thymikee Nov 22, 2026
40b5ff1
fix(selectors): keep the off-screen reasons beside the module that pu…
thymikee Nov 22, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions packages/capture-kit/src/alert-tree-driver.ts
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
import {
ALERT_REFUSAL_REASONS,
type AlertAction,
ALERT_ACTION_RETRY_MS,
ALERT_BUTTON_UNDECIDED_REASON,
ALERT_CAPTURE_UNDECIDED_REASON,
type AlertCapture,
type AlertInfo,
type AlertPlatform,
ALERT_NOT_FOUND_REASON,
ALERT_POLL_INTERVAL_MS,
ALERT_WAIT_TIMEOUT_REASON,
ALERT_WINDOW_EXPIRED_REASON,
type AlertStatusKind,
DEFAULT_ALERT_TIMEOUT_MS,
MAX_ALERT_WINDOW_MS,
Expand Down Expand Up @@ -252,7 +250,7 @@ async function actOnTreeAlert<
'COMMAND_FAILED',
`alert ${action} found an alert but no button that clearly matches the action`,
{
reason: ALERT_BUTTON_UNDECIDED_REASON,
reason: ALERT_REFUSAL_REASONS.buttonUndecided.reason,
dispatched: 'no',
alert: candidate.alert,
hint: 'Inspect alert get --json for the visible buttons, then press the choice you want by label/ref.',
Expand Down Expand Up @@ -350,7 +348,7 @@ async function confirmTreeAlertGone<
`alert ${action} pressed the button but the dismissal could not be confirmed`,
{
alert: dismissed,
reason: ALERT_WINDOW_EXPIRED_REASON,
reason: ALERT_REFUSAL_REASONS.windowExpired.reason,
hint: 'The alert button was pressed; the post-press checks never settled the dialog as gone, so it may already be gone. Run alert get --json before retrying.',
},
);
Expand All @@ -369,7 +367,7 @@ function lookupRefusal(
'COMMAND_FAILED',
`alert ${action} refused: the capture is alert-shaped but cannot be resolved to one alert`,
{
reason: ALERT_CAPTURE_UNDECIDED_REASON,
reason: ALERT_REFUSAL_REASONS.captureUndecided.reason,
dispatched: 'no',
hint: 'Inspect alert get --json and snapshot -i, then press the visible choice by label/ref.',
},
Expand All @@ -392,7 +390,7 @@ function visibleAfterPressFailure<TAlert extends AlertInfo & { buttons: string[]
): AppError {
return new AppError('COMMAND_FAILED', `alert ${action} did not dismiss the visible alert`, {
alert: dismissed,
reason: ALERT_WINDOW_EXPIRED_REASON,
reason: ALERT_REFUSAL_REASONS.windowExpired.reason,
hint: 'The alert button was pressed but the dialog was visible on the last check that answered. Inspect alert get --json, then press the visible button by label/ref or retry.',
});
}
Expand Down
21 changes: 18 additions & 3 deletions packages/capture-kit/src/durable-capture/fence.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { AppError } from '@agent-device/kernel/errors';
import { AppError, type ReasonTable } from '@agent-device/kernel/errors';
import type {
DurableResourceEnvelope,
DurableResourceLifecycleState,
Expand All @@ -8,6 +8,18 @@ import type { DurableCaptureResourceRecord, DurableCaptureResourceStore } from '

const resourceFenceTails = new Map<string, Promise<void>>();

/**
* What the durable-capture record store answers when a caller arrives at a record that can no
* longer carry its work. `ownership-fence-lost` itself belongs to contracts' durable-resource
* outcome union, so it is not declared here.
*/
export const DURABLE_CAPTURE_REFUSAL_REASONS = {
// The record is already committed, so a finish, cleanup, or late progress write is refused.
alreadyCompleted: { reason: 'resource-already-completed' },
// The record the caller holds a descriptor for no longer exists on disk.
missing: { reason: 'resource-missing' },
} as const satisfies ReasonTable<'durable capture'>;

/** The lease over a record this fence found open; it is the only way a run may write that record. */
export type DurableCaptureOpenResourceFenceLease<K extends string> = Readonly<{
envelope: DurableResourceEnvelope<K>;
Expand Down Expand Up @@ -156,7 +168,10 @@ function releasedLeaseError(store: DurableCaptureResourceStore<string>): AppErro
* settled: the record is committed, so the resource is released, whatever the record could replay.
*/
export function isCompletedDurableCaptureError(error: unknown): boolean {
return error instanceof AppError && error.details?.reason === 'resource-already-completed';
return (
error instanceof AppError &&
error.details?.reason === DURABLE_CAPTURE_REFUSAL_REASONS.alreadyCompleted.reason
);
}

/**
Expand All @@ -169,7 +184,7 @@ export function completedDurableCaptureError(store: DurableCaptureResourceStore<
'COMMAND_FAILED',
`${store.displayName} resource record is already completed`,
{
reason: 'resource-already-completed',
reason: DURABLE_CAPTURE_REFUSAL_REASONS.alreadyCompleted.reason,
retriable: false,
hint: `Read the completed ${store.displayName.toLowerCase()} record instead of finishing or cleaning it again.`,
},
Expand Down
4 changes: 2 additions & 2 deletions packages/capture-kit/src/durable-capture/finish-recovered.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import {
type DurableCaptureRecoveryControl,
} from './recovery-authority.ts';
import { allowsDurableCaptureDescriptorCleanup } from './recovery.ts';
import { withDurableCaptureResourceFence } from './fence.ts';
import { DURABLE_CAPTURE_REFUSAL_REASONS, withDurableCaptureResourceFence } from './fence.ts';
import type { DurableCaptureRecordDefinition } from './definition.ts';
import { capitalizeDurableCaptureLabel, durableCaptureDiagnosticPrefix } from './labels.ts';
import {
Expand Down Expand Up @@ -96,7 +96,7 @@ export async function finishRecoveredDurableCapture<
'COMMAND_FAILED',
`${capitalizeDurableCaptureLabel(definition.displayName)} is missing`,
{
reason: 'resource-missing',
reason: DURABLE_CAPTURE_REFUSAL_REASONS.missing.reason,
hint: definition.messages.cleanupPendingHint,
},
);
Expand Down
4 changes: 2 additions & 2 deletions packages/capture-kit/src/png-worker-client.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { afterAll, test } from 'vitest';
import assert from 'node:assert/strict';
import { AppError } from '@agent-device/kernel/errors';
import { PNG } from './png.ts';
import { IMAGE_DECODE_REASONS, PNG } from './png.ts';
import {
computePngRgbDifferenceAsync,
computeScreenshotDiffPixelsAsync,
Expand Down Expand Up @@ -141,7 +141,7 @@ test('decodePngAsync rejects invalid PNG data with the canonical decode AppError
assert.equal(error.code, 'COMMAND_FAILED');
assert.match(error.message, /Failed to decode fixture as PNG/);
assert.equal(error.details?.label, 'fixture');
assert.ok(String(error.details?.reason).length > 0);
assert.equal(error.details?.reason, IMAGE_DECODE_REASONS.pngDecodeFailed.reason);
return true;
},
);
Expand Down
17 changes: 15 additions & 2 deletions packages/capture-kit/src/png.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,20 @@
import { AppError } from '@agent-device/kernel/errors';
import { AppError, type ReasonTable } from '@agent-device/kernel/errors';
import { PNG } from 'pngjs';

export { PNG };

/**
* Why a screenshot image did not decode. The two containers are refused apart, so a caller tells a
* corrupt PNG from a corrupt JPEG without reading the decoder's prose, which now travels as
* `details.decoderError`.
*/
export const IMAGE_DECODE_REASONS = {
// The input could not be decoded as PNG: its signature is missing or its body is corrupt.
pngDecodeFailed: { reason: 'png_decode_failed' },
// The bytes carry a JPEG signature but the JPEG decoder could not read them.
jpegDecodeFailed: { reason: 'jpeg_decode_failed' },
} as const satisfies ReasonTable<'image decoding'>;

const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);

/** Whether the bytes open with the PNG signature, before any decode is attempted. */
Expand All @@ -21,7 +33,8 @@ export function decodePng(buffer: Buffer, label: string): PNG {
} catch (error) {
throw new AppError('COMMAND_FAILED', `Failed to decode ${label} as PNG`, {
label,
reason: error instanceof Error ? error.message : String(error),
reason: IMAGE_DECODE_REASONS.pngDecodeFailed.reason,
decoderError: error instanceof Error ? error.message : String(error),
});
}
}
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { test } from 'vitest';
import assert from 'node:assert/strict';
import { AppError } from '@agent-device/kernel/errors';
import { CONTACT_SHEET_UNSUPPORTED_HOST_REASON } from '../contact-sheet-report.ts';
import { CONTACT_SHEET_REASONS } from '../contact-sheet-report.ts';
import { assertContactSheetHostSupport } from '../contact-sheet-frames.ts';

test('contact sheets are explicitly unsupported on non-macOS hosts', () => {
Expand All @@ -11,7 +11,7 @@ test('contact sheets are explicitly unsupported on non-macOS hosts', () => {
return (
error instanceof AppError &&
error.code === 'UNSUPPORTED_OPERATION' &&
error.details?.reason === CONTACT_SHEET_UNSUPPORTED_HOST_REASON
error.details?.reason === CONTACT_SHEET_REASONS.unsupportedHost.reason
);
},
);
Expand Down
24 changes: 10 additions & 14 deletions packages/capture-kit/src/recording/contact-sheet-frames.test.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,7 @@
import { beforeEach, describe, expect, test, vi } from 'vitest';
import { createTestHost } from '../host-environment.fixtures.ts';
import path from 'node:path';
import {
CONTACT_SHEET_EXTRACTION_REASON,
CONTACT_SHEET_NO_FRAMES_REASON,
CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
} from './contact-sheet-report.ts';
import { CONTACT_SHEET_REASONS } from './contact-sheet-report.ts';
import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors';
import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts';
import { solidPng } from '../png-pixels.fixtures.ts';
Expand Down Expand Up @@ -72,7 +68,7 @@ describe('extractRecordingFrames', () => {
hostPlatform: 'linux',
}),
),
).toBe(CONTACT_SHEET_UNSUPPORTED_HOST_REASON);
).toBe(CONTACT_SHEET_REASONS.unsupportedHost.reason);
// Refused before the compiler or the decoder ran, so a Linux host never pays for a spawn.
expect(mockRunCmd).not.toHaveBeenCalled();
});
Expand Down Expand Up @@ -203,7 +199,7 @@ describe('extractRecordingFrames', () => {
timesMs: [0],
}),
),
).toBe(CONTACT_SHEET_EXTRACTION_REASON);
).toBe(CONTACT_SHEET_REASONS.frameExtractionFailed.reason);
});

test('refuses a frame entry that cannot say which frame it is', async () => {
Expand All @@ -225,7 +221,7 @@ describe('extractRecordingFrames', () => {
timesMs: [0],
}),
),
).toBe(CONTACT_SHEET_EXTRACTION_REASON);
).toBe(CONTACT_SHEET_REASONS.frameExtractionFailed.reason);
});

test('counts samples the manifest neither answered nor declared skipped', async () => {
Expand Down Expand Up @@ -257,7 +253,7 @@ describe('extractRecordingFrames', () => {
timesMs: [0],
}),
),
).toBe(CONTACT_SHEET_EXTRACTION_REASON);
).toBe(CONTACT_SHEET_REASONS.frameExtractionFailed.reason);
});

test('keeps the extraction reason when the decoder never started', async () => {
Expand All @@ -272,7 +268,7 @@ describe('extractRecordingFrames', () => {
timesMs: [0],
}),
),
).toBe(CONTACT_SHEET_EXTRACTION_REASON);
).toBe(CONTACT_SHEET_REASONS.frameExtractionFailed.reason);
});

test('hands the decoder the cancellation of the request it serves', async () => {
Expand Down Expand Up @@ -331,7 +327,7 @@ describe('extractRecordingFrames', () => {
timesMs: [0],
}),
),
).toBe(CONTACT_SHEET_EXTRACTION_REASON);
).toBe(CONTACT_SHEET_REASONS.frameExtractionFailed.reason);
});

test('reports an unreadable manifest as an extraction failure', async () => {
Expand All @@ -346,7 +342,7 @@ describe('extractRecordingFrames', () => {
timesMs: [0],
}),
),
).toBe(CONTACT_SHEET_EXTRACTION_REASON);
).toBe(CONTACT_SHEET_REASONS.frameExtractionFailed.reason);
});

test('reports a clip that returned nothing usable', async () => {
Expand All @@ -361,15 +357,15 @@ describe('extractRecordingFrames', () => {
timesMs: [0],
}),
),
).toBe(CONTACT_SHEET_NO_FRAMES_REASON);
).toBe(CONTACT_SHEET_REASONS.noFrames.reason);
});

test('refuses to spawn a decoder for an empty grid', async () => {
expect(
await reasonOf(() =>
extract({ videoPath: VIDEO, scratchDir, maxWidth: CELL_WIDTH, timesMs: [] }),
),
).toBe(CONTACT_SHEET_NO_FRAMES_REASON);
).toBe(CONTACT_SHEET_REASONS.noFrames.reason);
expect(mockRunCmd).not.toHaveBeenCalled();
});
});
16 changes: 6 additions & 10 deletions packages/capture-kit/src/recording/contact-sheet-frames.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,7 @@
import fs from 'node:fs';
import type { HostEnvironment } from '@agent-device/kernel/source-value';
import path from 'node:path';
import {
CONTACT_SHEET_EXTRACTION_REASON,
CONTACT_SHEET_NO_FRAMES_REASON,
CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
} from './contact-sheet-report.ts';
import { CONTACT_SHEET_REASONS } from './contact-sheet-report.ts';
import {
AppError,
createRequestCanceledError,
Expand All @@ -30,7 +26,7 @@ export function assertContactSheetHostSupport(
'UNSUPPORTED_OPERATION',
'Contact sheets can only be built on macOS hosts, which is where the frame decoder runs',
{
reason: CONTACT_SHEET_UNSUPPORTED_HOST_REASON,
reason: CONTACT_SHEET_REASONS.unsupportedHost.reason,
hostPlatform,
hint: 'Run this command on the macOS host that recorded the clip, or read the video artifact itself.',
},
Expand Down Expand Up @@ -76,7 +72,7 @@ export async function extractRecordingFrames(
assertContactSheetHostSupport(input.hostPlatform ?? process.platform);
if (input.timesMs.length === 0) {
throw new AppError('COMMAND_FAILED', 'Contact sheet sampling requested no frames', {
reason: CONTACT_SHEET_NO_FRAMES_REASON,
reason: CONTACT_SHEET_REASONS.noFrames.reason,
videoPath: input.videoPath,
});
}
Expand Down Expand Up @@ -114,7 +110,7 @@ export async function extractRecordingFrames(
'COMMAND_FAILED',
`Failed to extract frames from the recording: ${lastNonEmptyLine(result.stderr) || `exit ${result.exitCode}`}`,
{
reason: CONTACT_SHEET_EXTRACTION_REASON,
reason: CONTACT_SHEET_REASONS.frameExtractionFailed.reason,
videoPath: input.videoPath,
exitCode: result.exitCode,
},
Expand All @@ -132,7 +128,7 @@ export async function extractRecordingFrames(
'COMMAND_FAILED',
'The recording returned no decodable frames for a contact sheet',
{
reason: CONTACT_SHEET_NO_FRAMES_REASON,
reason: CONTACT_SHEET_REASONS.noFrames.reason,
videoPath: input.videoPath,
skippedSampleCount: extracted.skippedSampleCount,
},
Expand Down Expand Up @@ -211,7 +207,7 @@ function extractionError(message: string, videoPath: string, cause?: unknown): A
return new AppError(
'COMMAND_FAILED',
message,
{ reason: CONTACT_SHEET_EXTRACTION_REASON, videoPath },
{ reason: CONTACT_SHEET_REASONS.frameExtractionFailed.reason, videoPath },
cause,
);
}
Expand Down
8 changes: 4 additions & 4 deletions packages/capture-kit/src/recording/contact-sheet-plan.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { describe, expect, test } from 'vitest';
import { CONTACT_SHEET_DURATION_REASON } from './contact-sheet-report.ts';
import { CONTACT_SHEET_REASONS } from './contact-sheet-report.ts';
import { AppError } from '@agent-device/kernel/errors';
import {
CONTACT_SHEET_SAMPLE_INTERVAL_MS,
Expand Down Expand Up @@ -57,13 +57,13 @@ describe('planContactSheetSampleTimes', () => {

test('refuses to plan over a timeline the container cannot name', () => {
expect(reasonOf(() => planContactSheetSampleTimes(undefined, VIDEO))).toBe(
CONTACT_SHEET_DURATION_REASON,
CONTACT_SHEET_REASONS.durationUnknown.reason,
);
expect(reasonOf(() => planContactSheetSampleTimes(Number.NaN, VIDEO))).toBe(
CONTACT_SHEET_DURATION_REASON,
CONTACT_SHEET_REASONS.durationUnknown.reason,
);
expect(reasonOf(() => planContactSheetSampleTimes(-1, VIDEO))).toBe(
CONTACT_SHEET_DURATION_REASON,
CONTACT_SHEET_REASONS.durationUnknown.reason,
);
});
});
4 changes: 2 additions & 2 deletions packages/capture-kit/src/recording/contact-sheet-plan.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { CONTACT_SHEET_DURATION_REASON } from './contact-sheet-report.ts';
import { CONTACT_SHEET_REASONS } from './contact-sheet-report.ts';
import { AppError } from '@agent-device/kernel/errors';

/** Spacing between requested sample times, in milliseconds. */
Expand Down Expand Up @@ -38,7 +38,7 @@ export function planContactSheetSampleTimes(
'COMMAND_FAILED',
`Cannot plan a contact sheet: the video timeline of ${videoPath} could not be read`,
{
reason: CONTACT_SHEET_DURATION_REASON,
reason: CONTACT_SHEET_REASONS.durationUnknown.reason,
videoPath,
hint: 'Retry once the recording finished finalizing; a clip whose container is still being written has no readable duration.',
},
Expand Down
4 changes: 2 additions & 2 deletions packages/capture-kit/src/recording/contact-sheet-render.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { CONTACT_SHEET_PIXEL_BUDGET_REASON } from './contact-sheet-report.ts';
import { CONTACT_SHEET_REASONS } from './contact-sheet-report.ts';
import { AppError } from '@agent-device/kernel/errors';
import { encodePngPixels } from '../png-encode.ts';
import { PNG } from '../png.ts';
Expand Down Expand Up @@ -125,7 +125,7 @@ function fitLayout(
'COMMAND_FAILED',
`Contact sheet would be ${smallest.width * smallest.height} pixels, above the configured maxImagePixels limit of ${input.maxPixels}`,
{
reason: CONTACT_SHEET_PIXEL_BUDGET_REASON,
reason: CONTACT_SHEET_REASONS.pixelBudgetExceeded.reason,
cellCount: input.cells.length,
maxPixels: input.maxPixels,
hint: 'Shorten the recording or raise the command policy maxImagePixels limit.',
Expand Down
Loading
Loading