diff --git a/packages/capture-kit/src/alert-tree-driver.ts b/packages/capture-kit/src/alert-tree-driver.ts index c70a4f1b45..686a0a31ec 100644 --- a/packages/capture-kit/src/alert-tree-driver.ts +++ b/packages/capture-kit/src/alert-tree-driver.ts @@ -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, @@ -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.', @@ -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.', }, ); @@ -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.', }, @@ -392,7 +390,7 @@ function visibleAfterPressFailure>(); +/** + * 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 = Readonly<{ envelope: DurableResourceEnvelope; @@ -156,7 +168,10 @@ function releasedLeaseError(store: DurableCaptureResourceStore): 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 + ); } /** @@ -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.`, }, diff --git a/packages/capture-kit/src/durable-capture/finish-recovered.ts b/packages/capture-kit/src/durable-capture/finish-recovered.ts index 1c041b304a..98db3919f9 100644 --- a/packages/capture-kit/src/durable-capture/finish-recovered.ts +++ b/packages/capture-kit/src/durable-capture/finish-recovered.ts @@ -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 { @@ -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, }, ); diff --git a/packages/capture-kit/src/png-worker-client.test.ts b/packages/capture-kit/src/png-worker-client.test.ts index 9938fe2ce3..185adc2f65 100644 --- a/packages/capture-kit/src/png-worker-client.test.ts +++ b/packages/capture-kit/src/png-worker-client.test.ts @@ -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, @@ -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; }, ); diff --git a/packages/capture-kit/src/png.ts b/packages/capture-kit/src/png.ts index 4fc90b23d7..338c4ac116 100644 --- a/packages/capture-kit/src/png.ts +++ b/packages/capture-kit/src/png.ts @@ -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. */ @@ -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), }); } } diff --git a/packages/capture-kit/src/recording/__tests__/contact-sheet-frames-host-support.test.ts b/packages/capture-kit/src/recording/__tests__/contact-sheet-frames-host-support.test.ts index f2a0148af5..2c64f3ae6c 100644 --- a/packages/capture-kit/src/recording/__tests__/contact-sheet-frames-host-support.test.ts +++ b/packages/capture-kit/src/recording/__tests__/contact-sheet-frames-host-support.test.ts @@ -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', () => { @@ -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 ); }, ); diff --git a/packages/capture-kit/src/recording/contact-sheet-frames.test.ts b/packages/capture-kit/src/recording/contact-sheet-frames.test.ts index 239bde7aa0..4fa51e0b11 100644 --- a/packages/capture-kit/src/recording/contact-sheet-frames.test.ts +++ b/packages/capture-kit/src/recording/contact-sheet-frames.test.ts @@ -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'; @@ -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(); }); @@ -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 () => { @@ -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 () => { @@ -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 () => { @@ -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 () => { @@ -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 () => { @@ -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 () => { @@ -361,7 +357,7 @@ 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 () => { @@ -369,7 +365,7 @@ describe('extractRecordingFrames', () => { 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(); }); }); diff --git a/packages/capture-kit/src/recording/contact-sheet-frames.ts b/packages/capture-kit/src/recording/contact-sheet-frames.ts index 2b188bf951..ab87c4419b 100644 --- a/packages/capture-kit/src/recording/contact-sheet-frames.ts +++ b/packages/capture-kit/src/recording/contact-sheet-frames.ts @@ -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, @@ -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.', }, @@ -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, }); } @@ -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, }, @@ -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, }, @@ -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, ); } diff --git a/packages/capture-kit/src/recording/contact-sheet-plan.test.ts b/packages/capture-kit/src/recording/contact-sheet-plan.test.ts index c3c0ed5bc9..717503d793 100644 --- a/packages/capture-kit/src/recording/contact-sheet-plan.test.ts +++ b/packages/capture-kit/src/recording/contact-sheet-plan.test.ts @@ -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, @@ -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, ); }); }); diff --git a/packages/capture-kit/src/recording/contact-sheet-plan.ts b/packages/capture-kit/src/recording/contact-sheet-plan.ts index 049a7c21f4..66cda5179f 100644 --- a/packages/capture-kit/src/recording/contact-sheet-plan.ts +++ b/packages/capture-kit/src/recording/contact-sheet-plan.ts @@ -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. */ @@ -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.', }, diff --git a/packages/capture-kit/src/recording/contact-sheet-render.ts b/packages/capture-kit/src/recording/contact-sheet-render.ts index d6c0827c03..402a8260d4 100644 --- a/packages/capture-kit/src/recording/contact-sheet-render.ts +++ b/packages/capture-kit/src/recording/contact-sheet-render.ts @@ -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'; @@ -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.', diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts index 6647c10240..77905a481b 100644 --- a/packages/capture-kit/src/recording/contact-sheet-report.ts +++ b/packages/capture-kit/src/recording/contact-sheet-report.ts @@ -1,28 +1,31 @@ +import type { ReasonTable } from '@agent-device/kernel/errors'; + /** * What a contact sheet reports: the shape of the finished grid, and the typed reasons it refuses with * when there is no grid to draw. Both stay here rather than in cross-layer contracts because nothing * but this package's pipeline produces them and the surface that reads them already imports this * package; a caller branches on a reason instead of reading an error message. */ - -/** The host cannot extract frames at all: frame decoding is Apple AVFoundation tooling. */ -export const CONTACT_SHEET_UNSUPPORTED_HOST_REASON = 'contact_sheet_unsupported_host'; -/** The MP4 timeline could not be read, so no bounded sample grid can be planned. */ -export const CONTACT_SHEET_DURATION_REASON = 'contact_sheet_duration_unknown'; -/** Frame extraction ran and failed, rather than returning fewer frames. */ -export const CONTACT_SHEET_EXTRACTION_REASON = 'contact_sheet_frame_extraction_failed'; -/** Extraction returned nothing usable, so there is no sheet to draw. */ -export const CONTACT_SHEET_NO_FRAMES_REASON = 'contact_sheet_no_frames'; -/** The requested sheet would exceed the caller's image pixel budget even at the smallest cell. */ -export const CONTACT_SHEET_PIXEL_BUDGET_REASON = 'contact_sheet_pixel_budget_exceeded'; -/** The file is present but is not a container this feature decodes, such as a WebM recording. */ -export const CONTACT_SHEET_CONTAINER_REASON = 'contact_sheet_container_unsupported'; -/** The sheet could not be written where it was asked to land. */ -export const CONTACT_SHEET_OUTPUT_WRITE_REASON = 'contact_sheet_output_write_failed'; -/** The output resolves to the recording itself, which a sheet must never replace. */ -export const CONTACT_SHEET_OUTPUT_COLLISION_REASON = 'contact_sheet_output_collides_with_input'; -/** The change threshold is not a finite share between 0 and 1. */ -export const CONTACT_SHEET_THRESHOLD_REASON = 'contact_sheet_threshold_invalid'; +export const CONTACT_SHEET_REASONS = { + // The host cannot decode frames at all: frame decoding is Apple AVFoundation tooling. + unsupportedHost: { reason: 'contact_sheet_unsupported_host' }, + // The MP4 timeline could not be read, so no bounded sample grid can be planned. + durationUnknown: { reason: 'contact_sheet_duration_unknown' }, + // The contact sheet could not obtain usable extracted frames: the extractor failed to start, run, or return frames the sheet can use. + frameExtractionFailed: { reason: 'contact_sheet_frame_extraction_failed' }, + // Extraction returned nothing usable, so there is no sheet to draw. + noFrames: { reason: 'contact_sheet_no_frames' }, + // The sheet would exceed the caller's image pixel budget even at the smallest cell. + pixelBudgetExceeded: { reason: 'contact_sheet_pixel_budget_exceeded' }, + // The file is present but is not a container this feature decodes, such as a WebM recording. + containerUnsupported: { reason: 'contact_sheet_container_unsupported' }, + // The sheet could not be written where it was asked to land. + outputWriteFailed: { reason: 'contact_sheet_output_write_failed' }, + // The output resolves to the recording itself, which a sheet must never replace. + outputCollidesWithInput: { reason: 'contact_sheet_output_collides_with_input' }, + // The change threshold is not a finite share between 0 and 1. + thresholdInvalid: { reason: 'contact_sheet_threshold_invalid' }, +} as const satisfies ReasonTable<'record'>; export type RecordingContactSheetCell = { /** Presentation time of the decoded frame this cell shows, in milliseconds from the clip start. */ diff --git a/packages/capture-kit/src/recording/contact-sheet.test.ts b/packages/capture-kit/src/recording/contact-sheet.test.ts index 1844c744af..021bac113f 100644 --- a/packages/capture-kit/src/recording/contact-sheet.test.ts +++ b/packages/capture-kit/src/recording/contact-sheet.test.ts @@ -2,14 +2,7 @@ import { beforeEach, describe, expect, test, vi } from 'vitest'; import { createTestHost } from '../host-environment.fixtures.ts'; import fs from 'node:fs'; import path from 'node:path'; -import { - CONTACT_SHEET_CONTAINER_REASON, - CONTACT_SHEET_DURATION_REASON, - CONTACT_SHEET_EXTRACTION_REASON, - CONTACT_SHEET_OUTPUT_COLLISION_REASON, - CONTACT_SHEET_PIXEL_BUDGET_REASON, - CONTACT_SHEET_UNSUPPORTED_HOST_REASON, -} from './contact-sheet-report.ts'; +import { CONTACT_SHEET_REASONS } from './contact-sheet-report.ts'; import { AppError } from '@agent-device/kernel/errors'; import { BLACK, RED, WHITE, paintPng, solidPng } from '../png-pixels.fixtures.ts'; import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts'; @@ -192,7 +185,9 @@ describe('buildRecordingContactSheet', () => { const error = await build(webm).catch((error: unknown) => error); expect(error).toBeInstanceOf(AppError); - expect((error as AppError).details?.reason).toBe(CONTACT_SHEET_CONTAINER_REASON); + expect((error as AppError).details?.reason).toBe( + CONTACT_SHEET_REASONS.containerUnsupported.reason, + ); expect((error as AppError).message).toMatch(/WebM/); }); @@ -200,12 +195,14 @@ describe('buildRecordingContactSheet', () => { const notAVideo = path.join(directory, 'broken.mp4'); fs.writeFileSync(notAVideo, 'not a video at all'); - expect(await reasonOf(() => build(notAVideo))).toBe(CONTACT_SHEET_CONTAINER_REASON); + expect(await reasonOf(() => build(notAVideo))).toBe( + CONTACT_SHEET_REASONS.containerUnsupported.reason, + ); }); test('refuses a clip whose timeline the container cannot name', async () => { expect(await reasonOf(() => build(recording('no-duration', -1)))).toBe( - CONTACT_SHEET_DURATION_REASON, + CONTACT_SHEET_REASONS.durationUnknown.reason, ); }); @@ -219,7 +216,9 @@ describe('buildRecordingContactSheet', () => { }), ); - expect(await reasonOf(() => build(video))).toBe(CONTACT_SHEET_EXTRACTION_REASON); + expect(await reasonOf(() => build(video))).toBe( + CONTACT_SHEET_REASONS.frameExtractionFailed.reason, + ); expect(fs.existsSync(recordingContactSheetPath(video))).toBe(false); }); @@ -227,7 +226,7 @@ describe('buildRecordingContactSheet', () => { const video = recording('unsupported-host', 1_000); expect(await reasonOf(() => build(video, { hostPlatform: 'linux' }))).toBe( - CONTACT_SHEET_UNSUPPORTED_HOST_REASON, + CONTACT_SHEET_REASONS.unsupportedHost.reason, ); expect(mockRunCmd).not.toHaveBeenCalled(); }); @@ -255,7 +254,7 @@ describe('buildRecordingContactSheet', () => { const video = recording('collision', 1_000); expect(await reasonOf(() => build(video, { outputPath: video }))).toBe( - CONTACT_SHEET_OUTPUT_COLLISION_REASON, + CONTACT_SHEET_REASONS.outputCollidesWithInput.reason, ); // Refused before the decoder ran, so a mistyped --out cannot cost a ruined recording. expect(mockRunCmd).not.toHaveBeenCalled(); @@ -271,7 +270,7 @@ describe('buildRecordingContactSheet', () => { for (const outputPath of [symlink, hardLink]) { expect(await reasonOf(() => build(video, { outputPath }))).toBe( - CONTACT_SHEET_OUTPUT_COLLISION_REASON, + CONTACT_SHEET_REASONS.outputCollidesWithInput.reason, ); } // Neither alias was opened for writing, so the recording is still whole behind both names. @@ -292,7 +291,7 @@ describe('buildRecordingContactSheet', () => { ); expect(await reasonOf(() => build(video, { maxPixels: 100 }))).toBe( - CONTACT_SHEET_EXTRACTION_REASON, + CONTACT_SHEET_REASONS.frameExtractionFailed.reason, ); }); @@ -308,7 +307,9 @@ describe('buildRecordingContactSheet', () => { }), ); - expect(await reasonOf(() => build(video))).toBe(CONTACT_SHEET_EXTRACTION_REASON); + expect(await reasonOf(() => build(video))).toBe( + CONTACT_SHEET_REASONS.frameExtractionFailed.reason, + ); }); test('refuses a sheet the pixel budget cannot hold and leaves nothing at the output', async () => { @@ -317,7 +318,7 @@ describe('buildRecordingContactSheet', () => { answerForGrid({ timesMs: [0, 250, 500, 750, 1000], changedMs: [250, 500, 750, 1000] }); expect(await reasonOf(() => build(video, { outputPath: out, maxPixels: 200 }))).toBe( - CONTACT_SHEET_PIXEL_BUDGET_REASON, + CONTACT_SHEET_REASONS.pixelBudgetExceeded.reason, ); expect(fs.existsSync(out)).toBe(false); expect(fs.readdirSync(directory).filter((name) => name.endsWith('.writing'))).toEqual([]); diff --git a/packages/capture-kit/src/recording/contact-sheet.ts b/packages/capture-kit/src/recording/contact-sheet.ts index b3f3a0fb88..411c60d3e2 100644 --- a/packages/capture-kit/src/recording/contact-sheet.ts +++ b/packages/capture-kit/src/recording/contact-sheet.ts @@ -3,10 +3,7 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import os from 'node:os'; import path from 'node:path'; import { - CONTACT_SHEET_CONTAINER_REASON, - CONTACT_SHEET_EXTRACTION_REASON, - CONTACT_SHEET_OUTPUT_COLLISION_REASON, - CONTACT_SHEET_OUTPUT_WRITE_REASON, + CONTACT_SHEET_REASONS, type RecordingContactSheetCell, type RecordingContactSheetResult, } from './contact-sheet-report.ts'; @@ -39,7 +36,7 @@ export { recordingContactSheetPath }; * travels on the error the pipeline threw, so it stays in the module that raises it until some surface * asks for it by name. */ -export { CONTACT_SHEET_THRESHOLD_REASON } from './contact-sheet-report.ts'; +export { CONTACT_SHEET_REASONS } from './contact-sheet-report.ts'; export type { RecordingContactSheetResult } from './contact-sheet-report.ts'; /** @@ -73,7 +70,7 @@ export async function buildRecordingContactSheet( ? `Contact sheets need an MP4 recording; ${videoPath} is WebM, whose frames this decoder does not read` : `Contact sheets need an MP4 recording; ${videoPath} is not a readable MP4`, { - reason: CONTACT_SHEET_CONTAINER_REASON, + reason: CONTACT_SHEET_REASONS.containerUnsupported.reason, videoPath, container: container ?? 'unknown', hint: 'Re-record on a backend that exports MP4, or pass the MP4 artifact the recording produced.', @@ -137,7 +134,7 @@ async function decodeFrameSamples( 'COMMAND_FAILED', `Frame extraction returned a ${size.width}px-wide frame when the sheet asked for ${CONTACT_SHEET_FRAME_WIDTH}px cells`, { - reason: CONTACT_SHEET_EXTRACTION_REASON, + reason: CONTACT_SHEET_REASONS.frameExtractionFailed.reason, framePath: frame.path, frameWidth: size.width, frameWidthLimit: CONTACT_SHEET_FRAME_WIDTH, @@ -149,7 +146,7 @@ async function decodeFrameSamples( 'COMMAND_FAILED', `Frame extraction returned a ${size.width}x${size.height} frame, above the ${maxPixels}-pixel budget for the whole sheet`, { - reason: CONTACT_SHEET_EXTRACTION_REASON, + reason: CONTACT_SHEET_REASONS.frameExtractionFailed.reason, framePath: frame.path, framePixels: size.width * size.height, maxPixels, @@ -183,7 +180,7 @@ function assertOutputDoesNotReplaceRecording(videoPath: string, outputPath: stri 'INVALID_ARGS', `A contact sheet cannot be written over the recording it describes: ${outputPath}`, { - reason: CONTACT_SHEET_OUTPUT_COLLISION_REASON, + reason: CONTACT_SHEET_REASONS.outputCollidesWithInput.reason, videoPath, outputPath, hint: 'Choose a different --out path, or omit it to write beside the recording.', @@ -250,7 +247,7 @@ function writeContactSheetFile(outputPath: string, bytes: Buffer): void { throw new AppError( 'COMMAND_FAILED', `Failed to write the contact sheet to ${outputPath}: ${error instanceof Error ? error.message : String(error)}`, - { reason: CONTACT_SHEET_OUTPUT_WRITE_REASON, outputPath }, + { reason: CONTACT_SHEET_REASONS.outputWriteFailed.reason, outputPath }, ); } } diff --git a/packages/capture-kit/src/recording/video.ts b/packages/capture-kit/src/recording/video.ts index 9488680ff5..677eb2fcea 100644 --- a/packages/capture-kit/src/recording/video.ts +++ b/packages/capture-kit/src/recording/video.ts @@ -1,5 +1,5 @@ import fs from 'node:fs'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import { execFailureDetails, isCommandTimeoutError } from '@agent-device/host-kit/command'; import { type Deadline, sleep } from '@agent-device/host-kit/retry'; import { settleWithin } from '@agent-device/host-kit/settle-within'; @@ -14,6 +14,14 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { hasPlayableWebmStructure } from './video-webm.ts'; +/** Why the MP4 playability validator cannot answer. */ +const VIDEO_VALIDATOR_REFUSAL_REASONS = { + // The Swift compile is still running past the caller's wait; try the stop again. + compileTimeout: { reason: 'video_validator_compile_timeout' }, + // The validator could not be built or run at all, so playability stays unverified. + unavailable: { reason: 'video_validator_unavailable' }, +} as const satisfies ReasonTable<'record'>; + // A cold Swift module cache makes the validator compile take over 30 s on a loaded CI runner, so a // caller with a deadline, such as `record stop`, waits for the compile until that deadline instead. const VALIDATOR_COMPILE_WAIT_MS = 30_000; @@ -159,7 +167,7 @@ async function waitForValidatorCompile(host: HostEnvironment, waitMs: number): P 'COMMAND_FAILED', `The video validator did not compile within ${Math.round(waitMs)}ms`, { - reason: 'video_validator_compile_timeout', + reason: VIDEO_VALIDATOR_REFUSAL_REASONS.compileTimeout.reason, timeoutMs: waitMs, retriable: true, hint: @@ -170,7 +178,10 @@ async function waitForValidatorCompile(host: HostEnvironment, waitMs: number): P } function unavailableVideoValidator(cause: unknown): AppError { - if (cause instanceof AppError && cause.details?.reason === 'video_validator_unavailable') + if ( + cause instanceof AppError && + cause.details?.reason === VIDEO_VALIDATOR_REFUSAL_REASONS.unavailable.reason + ) return cause; // A cache the validator may not be run from keeps its own reason: the fix is the cache, not the toolchain. if (isUntrustedSwiftCacheError(cause)) return cause; @@ -180,7 +191,7 @@ function unavailableVideoValidator(cause: unknown): AppError { 'The video validator is unavailable; MP4 playability could not be verified.', { ...details, - reason: 'video_validator_unavailable', + reason: VIDEO_VALIDATOR_REFUSAL_REASONS.unavailable.reason, retriable: false, hint: details?.hint ?? diff --git a/packages/capture-kit/src/screenshot-image.test.ts b/packages/capture-kit/src/screenshot-image.test.ts index cad4e7c0af..09ee5fc832 100644 --- a/packages/capture-kit/src/screenshot-image.test.ts +++ b/packages/capture-kit/src/screenshot-image.test.ts @@ -1,7 +1,7 @@ import { expect, test } from 'vitest'; import fc from 'fast-check'; import { encode as encodeJpeg } from 'jpeg-js'; -import { PNG } from './png.ts'; +import { IMAGE_DECODE_REASONS, PNG } from './png.ts'; import { decodeScreenshotImage, detectScreenshotImageFormat } from './screenshot-image.ts'; function solidRgba(width: number, height: number, rgba: readonly [number, number, number, number]) { @@ -37,7 +37,11 @@ test('a valid SOI marker followed by garbage is refused with the typed decode er expect(thrownBy(() => decodeScreenshotImage(garbage, 'Limrun iOS screenshot'))).toMatchObject({ code: 'COMMAND_FAILED', message: 'Failed to decode Limrun iOS screenshot as JPEG', - details: { label: 'Limrun iOS screenshot', reason: expect.any(String) }, + details: { + label: 'Limrun iOS screenshot', + reason: IMAGE_DECODE_REASONS.jpegDecodeFailed.reason, + decoderError: expect.any(String), + }, }); }); @@ -87,7 +91,11 @@ test('decoding refuses bytes in neither container and a JPEG body that cannot be expect(thrownBy(() => decodeScreenshotImage(corrupt, 'fixture'))).toMatchObject({ code: 'COMMAND_FAILED', message: 'Failed to decode fixture as JPEG', - details: { label: 'fixture', reason: expect.any(String) }, + details: { + label: 'fixture', + reason: IMAGE_DECODE_REASONS.jpegDecodeFailed.reason, + decoderError: expect.any(String), + }, }); }); @@ -152,6 +160,9 @@ test('the JPEG decoder enforces the budget through malformed APP marker recovery expect(decodeScreenshotImage(malformed, 'current', 4).width).toBe(2); expect(thrownBy(() => decodeScreenshotImage(malformed, 'current', 3))).toMatchObject({ code: 'COMMAND_FAILED', - details: { reason: expect.stringContaining('maxResolutionInMP') }, + details: { + reason: IMAGE_DECODE_REASONS.jpegDecodeFailed.reason, + decoderError: expect.stringContaining('maxResolutionInMP'), + }, }); }); diff --git a/packages/capture-kit/src/screenshot-image.ts b/packages/capture-kit/src/screenshot-image.ts index 9a64e4cb6b..96ffa9b432 100644 --- a/packages/capture-kit/src/screenshot-image.ts +++ b/packages/capture-kit/src/screenshot-image.ts @@ -1,6 +1,6 @@ import { AppError } from '@agent-device/kernel/errors'; import { decode as decodeJpeg } from 'jpeg-js'; -import { decodePng, hasPngSignature, PNG } from './png.ts'; +import { decodePng, hasPngSignature, IMAGE_DECODE_REASONS, PNG } from './png.ts'; import { validateScreenshotImagePixels } from './screenshot-image-size.ts'; const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff]); @@ -30,7 +30,7 @@ export function decodeScreenshotImage(bytes: Buffer, label: string, maxPixels?: throw unsupportedContainer(label, bytes); } -/** A JPEG signature does not prove a decodable body; a failure keeps the label and the decoder's reason. */ +/** A JPEG signature does not prove a decodable body; a failure keeps the label and the decoder's message. */ function decodeJpegImage(bytes: Buffer, label: string, maxPixels?: number): PNG { try { const decoded = decodeJpeg(bytes, { @@ -48,7 +48,8 @@ function decodeJpegImage(bytes: Buffer, label: string, maxPixels?: number): PNG } catch (error) { throw new AppError('COMMAND_FAILED', `Failed to decode ${label} as JPEG`, { label, - reason: error instanceof Error ? error.message : String(error), + reason: IMAGE_DECODE_REASONS.jpegDecodeFailed.reason, + decoderError: error instanceof Error ? error.message : String(error), }); } } diff --git a/packages/capture-kit/src/snapshot-quality-verdict.ts b/packages/capture-kit/src/snapshot-quality-verdict.ts index 4a939931a6..233f4d1da4 100644 --- a/packages/capture-kit/src/snapshot-quality-verdict.ts +++ b/packages/capture-kit/src/snapshot-quality-verdict.ts @@ -98,11 +98,24 @@ function readCustomActionCoverage( * Why `find` refuses a capture whose verdict is sparse. The daemon and command-runtime `find` * paths both raise it; the runner's own wording moves to `details.verdictReason`. */ -export const FIND_READ_REASONS = { +const FIND_READ_REASONS = { // The capture came back sparse, so no selector could be resolved against it. snapshotUnreadable: { reason: 'find_snapshot_unreadable' }, } as const satisfies ReasonTable<'find'>; +/** The message and details both `find` routes publish when they refuse a sparse capture. */ +export function sparseFindRefusal(verdict: SnapshotQualityVerdict) { + return { + message: 'find could not read the current accessibility tree', + details: { + reason: FIND_READ_REASONS.snapshotUnreadable.reason, + verdictReason: verdict.reason, + verdictReasonCode: verdict.reasonCode, + hint: 'The snapshot quality verdict is sparse. Use screenshot as visual truth, navigate with coordinates if needed, then retry find after reaching a readable screen.', + }, + } as const; +} + export function isSparseSnapshotQualityVerdict( verdict: SnapshotQualityVerdict | undefined, ): verdict is SnapshotQualityVerdict { diff --git a/packages/capture-kit/src/snapshot-router/router.ts b/packages/capture-kit/src/snapshot-router/router.ts index 3e6de49836..d9a032f92e 100644 --- a/packages/capture-kit/src/snapshot-router/router.ts +++ b/packages/capture-kit/src/snapshot-router/router.ts @@ -13,7 +13,11 @@ import type { } from '@agent-device/contracts/ios-snapshot'; import { IOS_SYSTEM_SURFACE_HOSTS } from '@agent-device/contracts/ios-system-surface'; import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; -import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors'; +import { + AppError, + isRequestCanceledError, + REQUEST_CANCELED_REASON, +} from '@agent-device/kernel/errors'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { buildIosSnapshotPresentationKey, @@ -325,9 +329,11 @@ export function createSnapshotRouter( function rethrowCancelledFailure(failure: SnapshotSourceFailure, signal: AbortSignal): void { if (failure.kind !== 'cancelled') return; signal.throwIfAborted(); + // Every cancelled source failure stamps `request_canceled` into its own details; the router's + // own reason is that same typed value, never the bridge's internal `abort-signal` code. throw new AppError('COMMAND_FAILED', 'Simulator AX snapshot acquisition was cancelled.', { - reason: failure.code, ...failure.details, + reason: REQUEST_CANCELED_REASON, }); } diff --git a/packages/client/src/lease-client.ts b/packages/client/src/lease-client.ts index c0275c891a..3f8b3f8f84 100644 --- a/packages/client/src/lease-client.ts +++ b/packages/client/src/lease-client.ts @@ -1,6 +1,6 @@ import type { HumanControlHold, Lease } from '@agent-device/contracts/client'; import type { InternalRequestOptions } from '@agent-device/contracts/command'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import { INTERNAL_COMMANDS } from '@agent-device/command-registry/catalog'; import { isRecord } from '@agent-device/kernel/record'; import { readLeaseDevice } from '@agent-device/contracts/lease-scope'; @@ -77,6 +77,12 @@ function normalizeHumanControlHold(value: unknown): HumanControlHold { }; } +/** Why this client refuses a daemon answer it cannot turn into a lease. */ +const LEASE_CLIENT_REFUSAL_REASONS = { + // The daemon's lease answer is missing an identity field the client must key on. + invalidResponse: { reason: 'INVALID_LEASE_RESPONSE' }, +} as const satisfies ReasonTable<'leases'>; + function normalizeLease(data: Record): Lease { const rawLease = data.lease; const leaseId = isRecord(rawLease) ? readOptionalString(rawLease, 'leaseId') : undefined; @@ -85,7 +91,7 @@ function normalizeLease(data: Record): Lease { const backend = isRecord(rawLease) ? readOptionalString(rawLease, 'backend') : undefined; if (!isRecord(rawLease) || !leaseId || !tenantId || !runId || !backend) { throw new AppError('COMMAND_FAILED', 'Invalid lease response from daemon', { - reason: 'INVALID_LEASE_RESPONSE', + reason: LEASE_CLIENT_REFUSAL_REASONS.invalidResponse.reason, response: data, }); } diff --git a/packages/command-runtime/src/commands/interaction/runtime/selector-read-utils.ts b/packages/command-runtime/src/commands/interaction/runtime/selector-read-utils.ts index 377c2ed366..43da2dd91e 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/selector-read-utils.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/selector-read-utils.ts @@ -4,6 +4,7 @@ import type { InteractionSelectorTarget, } from '@agent-device/contracts/interaction'; import { AppError } from '@agent-device/kernel/errors'; +import { sparseFindRefusal } from '@agent-device/capture-kit/snapshot-quality-verdict'; import type { FindLocator } from '@agent-device/selectors'; export { findNodeByLabel, resolveRefLabel } from '@agent-device/capture-kit/snapshot-node-lookup'; @@ -40,8 +41,6 @@ export function findSnapshotScope( } export function sparseSelectorSnapshotError(verdict: SnapshotQualityVerdict): AppError { - return new AppError('COMMAND_FAILED', 'find could not read the current accessibility tree', { - reason: verdict.reason, - hint: 'The snapshot quality verdict is sparse. Use screenshot as visual truth, navigate with coordinates if needed, then retry find after reaching a readable screen.', - }); + const refusal = sparseFindRefusal(verdict); + return new AppError('COMMAND_FAILED', refusal.message, refusal.details); } diff --git a/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts b/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts index bbbaa7f275..2265c717b1 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/selector-read.test.ts @@ -287,9 +287,11 @@ test('runtime find wait reports sparse snapshot verdicts on the selector-read ro (error: unknown) => { assert.ok(error instanceof Error); assert.equal(error.message, 'find could not read the current accessibility tree'); - const details = (error as { details?: { reason?: string; hint?: string } }).details; - assert.equal(details?.reason, 'sparse tree'); - assert.match(details?.hint ?? '', /snapshot quality verdict is sparse/); + const details = (error as { details?: Record }).details; + assert.equal(details?.reason, 'find_snapshot_unreadable'); + assert.equal(details?.verdictReason, 'sparse tree'); + assert.equal(details?.verdictReasonCode, 'sparse-tree'); + assert.match(String(details?.hint ?? ''), /snapshot quality verdict is sparse/); return true; }, ); diff --git a/packages/command-runtime/src/commands/recording/runtime/contact-sheet.test.ts b/packages/command-runtime/src/commands/recording/runtime/contact-sheet.test.ts index 1c773e2362..4cf516afa4 100644 --- a/packages/command-runtime/src/commands/recording/runtime/contact-sheet.test.ts +++ b/packages/command-runtime/src/commands/recording/runtime/contact-sheet.test.ts @@ -3,7 +3,7 @@ import { bindTestCommandHost, createLiveTestHostEnvironment } from '@agent-devic import { beforeEach, test, vi } from 'vitest'; import { buildRecordingContactSheet, - CONTACT_SHEET_THRESHOLD_REASON, + CONTACT_SHEET_REASONS, } from '@agent-device/capture-kit/recording-contact-sheet'; import type { ArtifactAdapter, @@ -179,7 +179,7 @@ test('record contact-sheet refuses a change threshold that is not a share of the }), (error: unknown) => (error as { details?: { reason?: string } }).details?.reason === - CONTACT_SHEET_THRESHOLD_REASON, + CONTACT_SHEET_REASONS.thresholdInvalid.reason, ); } // Nothing is decoded for an argument that could only print every frame or none of them. diff --git a/packages/command-runtime/src/commands/recording/runtime/contact-sheet.ts b/packages/command-runtime/src/commands/recording/runtime/contact-sheet.ts index b01fe57015..8c68a8552b 100644 --- a/packages/command-runtime/src/commands/recording/runtime/contact-sheet.ts +++ b/packages/command-runtime/src/commands/recording/runtime/contact-sheet.ts @@ -1,7 +1,7 @@ import path from 'node:path'; import { buildRecordingContactSheet, - CONTACT_SHEET_THRESHOLD_REASON, + CONTACT_SHEET_REASONS, recordingContactSheetPath, type RecordingContactSheetResult, } from '@agent-device/capture-kit/recording-contact-sheet'; @@ -122,7 +122,7 @@ function assertContactSheetThreshold(threshold: number | undefined): void { 'INVALID_ARGS', `record contact-sheet needs a changedPixelThreshold between 0 and 1, got ${threshold}`, { - reason: CONTACT_SHEET_THRESHOLD_REASON, + reason: CONTACT_SHEET_REASONS.thresholdInvalid.reason, changedPixelThreshold: threshold, hint: 'Omit it to use the calibrated default, or pass a share of the frame between 0 and 1.', }, diff --git a/packages/command-surface/src/interaction/interactions.ts b/packages/command-surface/src/interaction/interactions.ts index c22ea2323a..e67e71af87 100644 --- a/packages/command-surface/src/interaction/interactions.ts +++ b/packages/command-surface/src/interaction/interactions.ts @@ -9,7 +9,7 @@ import { assertNoRemovedSwipeInput, swipePayloadFromPositionals, } from '@agent-device/gestures/gesture-normalization'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog'; import { readFillTargetFromPositionals, @@ -161,6 +161,14 @@ export const interactionDaemonWriters = { ]), } satisfies Record; +/** What `fill --text-stdin` refuses in the caller's arguments before it reads anything. */ +const FILL_TEXT_STDIN_REFUSAL_REASONS = { + // The stdin text mode's positional list does not decode to exactly one target. + stdinTargetInvalid: { reason: 'fill_text_stdin_target_invalid' }, + // The stdin text mode was also given a text argument, so the two sources disagree. + textSourceConflict: { reason: 'fill_text_source_conflict' }, +} as const satisfies ReasonTable<'fill'>; + /** * Reads only the target for `fill --text-stdin`. A stray positional may be the secret itself * (`fill --text-stdin "$PASSWORD"`), so neither a parse failure nor the conflict echoes any of them. @@ -174,7 +182,7 @@ function readStdinFillTarget( } catch (error) { if (!(error instanceof AppError)) throw error; throw new AppError('INVALID_ARGS', 'fill --text-stdin could not read the target.', { - reason: 'fill_text_stdin_target_invalid', + reason: FILL_TEXT_STDIN_REFUSAL_REASONS.stdinTargetInvalid.reason, hint: 'Pass only the target: an @ref, a quoted selector, or x y coordinates. The text itself goes to stdin.', }); } @@ -183,7 +191,7 @@ function readStdinFillTarget( 'INVALID_ARGS', 'fill --text-stdin reads the text from stdin, so it cannot also take a text argument.', { - reason: 'fill_text_source_conflict', + reason: FILL_TEXT_STDIN_REFUSAL_REASONS.textSourceConflict.reason, hint: 'Pass only the target, for example: printf %s "$PASSWORD" | agent-device fill @e3 --text-stdin. Quote a multi-word selector so no part of it is read as text.', }, ); diff --git a/packages/contracts/src/alert-contract.ts b/packages/contracts/src/alert-contract.ts index da953bc620..e182f688c6 100644 --- a/packages/contracts/src/alert-contract.ts +++ b/packages/contracts/src/alert-contract.ts @@ -1,3 +1,5 @@ +import type { ReasonTable } from '@agent-device/kernel/errors'; + export const ALERT_POLL_INTERVAL_MS = 300; /** * The minimum budget for a retry of `alert accept` or `alert dismiss` through the XCTest runner. @@ -51,14 +53,38 @@ export const ALERT_NOT_FOUND_REASON = 'alert-not-found'; export const ALERT_UNRESOLVED_RUNNER_CODE = 'ALERT_UNRESOLVED'; /** - * The acting leg's confirm budget ran out after a press landed without settling whether the - * alert is gone: the dialog was seen standing again after the press ("did not dismiss"), or no - * post-press read ever resolved to an answer ("could not be confirmed"). Typed so a caller can - * tell "a press went out and the screen never proved it worked" from absence or an - * unresolvable capture. The lookup never answers with it — a budget ends its loop, it does not - * cancel a started capture — so a quiet screen is always `alert-not-found`. + * The tree-based acting leg's refusals, raised by the shared tree driver in + * `capture-kit/alert-tree-driver.ts`: before anything was pressed (no candidate, or no single + * choice), and after a press the confirm window never settled. The pre-press rows answer with + * `dispatched: 'no'`; callers branch on `error.details.reason` instead of the prose. */ -export const ALERT_WINDOW_EXPIRED_REASON = 'alert-window-expired'; +export const ALERT_REFUSAL_REASONS = { + /** + * The acting leg (`alert accept|dismiss`) refuses after seeing an alert: the visible buttons + * name no single choice for the asked-for action. `dispatched: 'no'` states the refusal ran + * before any press. + */ + // The sheet's buttons name no single choice for the asked-for action. + buttonUndecided: { reason: 'alert_button_undecided' }, + /** + * The acting leg refuses before it has a candidate at all: the capture was alert-shaped but + * unresolvable (degraded buttons, competing sheets, an unverifiable owner). This is not absence — + * reporting `alert-not-found` over it would state more than the capture supports — and confirming + * a dismissal must never accept such a capture as proof of absence. + */ + // The capture is alert-shaped but resolves to no single alert. + captureUndecided: { reason: 'alert_capture_undecided' }, + /** + * The confirm budget ran out after a press landed without settling whether the alert is gone: + * the dialog was seen standing again after the press ("did not dismiss"), or no post-press read + * ever resolved to an answer ("could not be confirmed"). Typed so a caller can tell "a press + * went out and the screen never proved it worked" from absence or an unresolvable capture. The + * lookup never answers with it — a budget ends its loop, it does not cancel a started capture — + * so a quiet screen is always `alert-not-found`. + */ + // A press went out but the confirm window never settled whether the alert is gone. + windowExpired: { reason: 'alert-window-expired' }, +} as const satisfies ReasonTable<'alert'>; /** * `alert wait` saw no actionable alert within its window and no stronger typed failure applies. A @@ -191,22 +217,6 @@ export function selectRankedAlertButtonByRole< return first.button; } -/** - * The reason a tree-based acting leg (`alert accept|dismiss`) refuses after seeing an alert: the - * visible buttons name no single choice for the asked-for action. Callers branch on - * `error.details.reason` instead of the prose; `dispatched: 'no'` states the refusal ran before - * any press. - */ -export const ALERT_BUTTON_UNDECIDED_REASON = 'alert_button_undecided'; - -/** - * The reason a tree-based acting leg refuses before it has a candidate at all: the capture was - * alert-shaped but unresolvable (degraded buttons, competing sheets, an unverifiable owner). - * This is not absence — reporting `alert-not-found` over it would state more than the capture - * supports — and confirming a dismissal must never accept such a capture as proof of absence. - */ -export const ALERT_CAPTURE_UNDECIDED_REASON = 'alert_capture_undecided'; - export const ALERT_ACTIONS = ['get', 'accept', 'dismiss', 'wait'] as const; export type AlertAction = (typeof ALERT_ACTIONS)[number]; diff --git a/packages/contracts/src/application-lifecycle-interaction.ts b/packages/contracts/src/application-lifecycle-interaction.ts index ef1abca297..44777b790a 100644 --- a/packages/contracts/src/application-lifecycle-interaction.ts +++ b/packages/contracts/src/application-lifecycle-interaction.ts @@ -5,7 +5,11 @@ import { } from './launch-console.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { isIosFamily } from '@agent-device/kernel/device'; -import { AppError } from '@agent-device/kernel/errors'; +import { + AppError, + INTERACTOR_BINDING_REFUSAL_REASONS, + type ReasonTable, +} from '@agent-device/kernel/errors'; import type { ApplicationLaunchReport, Interactor, RunnerContext } from './interactor-types.ts'; import type { ApplicationLifecycleExecution, @@ -17,6 +21,12 @@ import type { OpenTargetResolutionInput, } from './application-lifecycle-runtime.ts'; +/** Why `open` refuses before it resolves an interactor for the chosen owner. */ +const APPLICATION_LIFECYCLE_ADMISSION_REFUSAL_REASONS = { + // --launch-console was asked for on an app-launch owner that cannot stream a console. + launchConsoleUnadmitted: { reason: 'launch-console-owner-unadmitted' }, +} as const satisfies ReasonTable<'open'>; + /** * The exact request-bound interactor authority for a lifecycle operation. It is deliberately * smaller than a platform runtime: platform packages own target, runner, hint, and durable-state @@ -92,7 +102,7 @@ function bindApplicationLifecycleInteractor( 'UNSUPPORTED_OPERATION', '--launch-console is supported only for a local or Limrun iOS simulator app launch', { - reason: 'launch-console-owner-unadmitted', + reason: APPLICATION_LIFECYCLE_ADMISSION_REFUSAL_REASONS.launchConsoleUnadmitted.reason, deviceId: device.id, hint: 'Remove --launch-console, or use a local or Limrun iOS simulator for launch output.', }, @@ -103,7 +113,10 @@ function bindApplicationLifecycleInteractor( throw new AppError( 'UNSUPPORTED_OPERATION', 'Provider-owned application lifecycle operation has no bound provider interactor.', - { reason: 'provider-runtime-interactor-missing', deviceId: device.id }, + { + reason: INTERACTOR_BINDING_REFUSAL_REASONS.providerInteractorMissing.reason, + deviceId: device.id, + }, ); }, }); diff --git a/packages/contracts/src/device-inventory.ts b/packages/contracts/src/device-inventory.ts index 4933ae5b3d..6c4c411739 100644 --- a/packages/contracts/src/device-inventory.ts +++ b/packages/contracts/src/device-inventory.ts @@ -13,6 +13,14 @@ import { } from '@agent-device/kernel/device'; import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; +/** The refusals this inventory's own input validation and provider-instance lookup answer with. */ +const DEVICE_INVENTORY_REFUSAL_REASONS = { + // A device-pin selector names a platform, device, udid, or serial the request cannot carry. + invalidDevicePin: { reason: 'invalid_device_pin' }, + // The provider connection has no allocated instance to route to. + providerInstanceUnallocated: { reason: 'provider_instance_unallocated' }, +} as const satisfies ReasonTable<'device inventory'>; + export const LOCAL_DEVICE_INVENTORY_PLATFORM_SELECTORS = [ 'android', 'harmonyos', @@ -130,7 +138,7 @@ export function isDeviceClaimConflictReason(value: unknown): value is DeviceClai /** A provider connection that has no live instance: none was allocated, or the last one ended. */ export function providerInstanceUnallocatedError(leaseProvider: string): AppError { return new AppError('DEVICE_NOT_FOUND', 'The provider connection has no allocated instance.', { - reason: 'provider_instance_unallocated', + reason: DEVICE_INVENTORY_REFUSAL_REASONS.providerInstanceUnallocated.reason, hint: 'Run boot or open to allocate an instance. SDK callers allocate one with leases.allocate and pass its leaseId.', leaseProvider, }); @@ -189,7 +197,10 @@ export function readDevicePin(value: unknown): DevicePin | undefined { } function invalidDevicePin(message: string, pinSource: string): never { - throw new AppError('INVALID_ARGS', message, { reason: 'invalid_device_pin', pinSource }); + throw new AppError('INVALID_ARGS', message, { + reason: DEVICE_INVENTORY_REFUSAL_REASONS.invalidDevicePin.reason, + pinSource, + }); } function isPinRecord(value: unknown): value is Record { diff --git a/packages/contracts/src/interactor-operation-binding.ts b/packages/contracts/src/interactor-operation-binding.ts index 1640772628..0357deaeae 100644 --- a/packages/contracts/src/interactor-operation-binding.ts +++ b/packages/contracts/src/interactor-operation-binding.ts @@ -1,5 +1,9 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; -import { AppError, createRuntimeContractInvalidError } from '@agent-device/kernel/errors'; +import { + AppError, + createRuntimeContractInvalidError, + INTERACTOR_BINDING_REFUSAL_REASONS, +} from '@agent-device/kernel/errors'; import type { Interactor, RunnerContext } from './interactor-types.ts'; /** @@ -57,7 +61,10 @@ export function providerInteractorSource( throw new AppError( 'UNSUPPORTED_OPERATION', `Provider-owned ${params.operation} operation has no bound provider interactor.`, - { reason: 'provider-runtime-interactor-missing', deviceId: params.device.id }, + { + reason: INTERACTOR_BINDING_REFUSAL_REASONS.providerInteractorMissing.reason, + deviceId: params.device.id, + }, ); }; } diff --git a/packages/contracts/src/lease-scope.ts b/packages/contracts/src/lease-scope.ts index c46e1ee042..2baccbf726 100644 --- a/packages/contracts/src/lease-scope.ts +++ b/packages/contracts/src/lease-scope.ts @@ -283,12 +283,6 @@ export const LEASE_DEVICE_SPEC_KEYS = [ type LeaseDeviceSpecKey = (typeof LEASE_DEVICE_SPEC_KEYS)[number]; -/** The typed reason a request naming a device spec is refused with. */ -const DEVICE_SPEC_UNSUPPORTED_REASON = 'device-spec-unsupported'; - -/** The typed reason a request giving a device-spec key a value of the wrong type is refused with. */ -const DEVICE_SPEC_INVALID_REASON = 'device-spec-invalid'; - // A Cloud provider profile field added without joining the projection would be dropped from the // envelope and fail `prepareSession` on the remote daemon — this makes that omission fail to build. type LeaseAllocateProfileKeysAreExhaustive = @@ -410,7 +404,7 @@ export function deviceSpecUnsupportedError( ): AppError { return new AppError('UNSUPPORTED_OPERATION', message, { ...details, - reason: DEVICE_SPEC_UNSUPPORTED_REASON, + reason: LEASE_REASONS.deviceSpecUnsupported.reason, keys: [...keys], hint: 'Drop --os, --image-tag, --device-mode, --device-baseline and --physical, or connect through a proxy whose backend picks devices by spec.', }); @@ -421,7 +415,7 @@ export function deviceSpecInvalidError(keys: readonly string[]): AppError { return new AppError( 'INVALID_ARGS', 'osVersion, imageTag, deviceMode and deviceBaseline take a string, and physical takes a boolean.', - { reason: DEVICE_SPEC_INVALID_REASON, keys: [...keys] }, + { reason: LEASE_REASONS.deviceSpecInvalid.reason, keys: [...keys] }, ); } @@ -516,6 +510,10 @@ export const LEASE_REASONS = { scopeMismatch: { reason: 'LEASE_SCOPE_MISMATCH' }, // The lease was allocated with an owner scope that the request does not repeat. scopeRequired: { reason: 'LEASE_SCOPE_REQUIRED' }, + // The request picks a device by OS version, image tag, device mode, baseline, or class, and nothing on its path honours a spec. + deviceSpecUnsupported: { reason: 'device-spec-unsupported' }, + // A device-spec key was given a value of the wrong type. + deviceSpecInvalid: { reason: 'device-spec-invalid' }, // The device instance behind the lease ended outside the daemon, which ends the lease with it. instanceEnded: { reason: 'provider-instance-ended' }, } as const satisfies ReasonTable<'leases'>; diff --git a/packages/contracts/src/replay.ts b/packages/contracts/src/replay.ts index 29b1fc60a6..835755bab8 100644 --- a/packages/contracts/src/replay.ts +++ b/packages/contracts/src/replay.ts @@ -1,4 +1,4 @@ -import type { DaemonError } from '@agent-device/kernel/errors'; +import type { DaemonError, ReasonTable } from '@agent-device/kernel/errors'; import type { DaemonResponse } from '@agent-device/kernel/contracts'; import type { Rect } from '@agent-device/kernel/snapshot'; import type { SnapshotState } from '@agent-device/contracts/snapshot-model'; @@ -28,14 +28,20 @@ export type ReplayTargetGuardDenotation = { structural: NodeStructuralDenotation; }; -/** - * `details.reason` marker on the pre-action refusal thrown by dispatch's - * post-resolution guard (`assertExpectedResolvedTarget`, - * `packages/command-runtime/src/commands/interaction/runtime/replay-target-guard.ts`), detected by the replay - * step loop to convert the refusal into an identity-mismatch target-binding - * divergence. - */ -export const REPLAY_TARGET_GUARD_MISMATCH_REASON = 'replay_target_guard_mismatch'; +/** Why a replay step refuses to act on the node dispatch resolved for it. */ +const REPLAY_TARGET_GUARD_REASONS = { + /** + * `details.reason` marker on the pre-action refusal thrown by dispatch's + * post-resolution guard (`assertExpectedResolvedTarget`, + * `packages/command-runtime/src/commands/interaction/runtime/replay-target-guard.ts`), detected by the replay + * step loop to convert the refusal into an identity-mismatch target-binding + * divergence. + */ + // Dispatch resolved a different node than the replay plan verified for this step. + mismatch: { reason: 'replay_target_guard_mismatch' }, +} as const satisfies ReasonTable<'replay'>; + +export const REPLAY_TARGET_GUARD_MISMATCH_REASON = REPLAY_TARGET_GUARD_REASONS.mismatch.reason; /** * #1349: `details.reason` marker on the timeout refusal `wait` throws when diff --git a/packages/contracts/src/screenshot-runtime.ts b/packages/contracts/src/screenshot-runtime.ts index 472be6fcc6..c92947c674 100644 --- a/packages/contracts/src/screenshot-runtime.ts +++ b/packages/contracts/src/screenshot-runtime.ts @@ -1,4 +1,4 @@ -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { localInteractorSource, @@ -17,6 +17,14 @@ import type { ScreenshotCaptureBackend } from './screenshot.ts'; export type { ScreenshotCaptureFacts, ScreenshotOptions } from './interactor-types.ts'; +/** Why this capture seam refuses an option the selected capture owner cannot honour. */ +const SCREENSHOT_CAPTURE_REFUSAL_REASONS = { + // `--capture-backend` names a backend the selected capture owner does not declare. + captureBackendUnsupported: { reason: 'screenshot-capture-backend-unsupported' }, + // `--screen-mask` was asked for on a device whose capture path cannot read the screen mask. + screenMaskUnsupported: { reason: 'screenshot-screen-mask-unsupported' }, +} as const satisfies ReasonTable<'screenshot'>; + /** Runner metadata needed by the selected capture implementation, without request-owned state. */ export type ScreenshotRuntimeExecution = Readonly>; @@ -64,7 +72,7 @@ export async function assertScreenshotCaptureSupport( throw new AppError( 'UNSUPPORTED_OPERATION', `--capture-backend ${backend} is not supported: ${capabilities.captureBackendRefusal ?? 'this capture owner declares no such backend'}`, - { reason: 'screenshot-capture-backend-unsupported' }, + { reason: SCREENSHOT_CAPTURE_REFUSAL_REASONS.captureBackendUnsupported.reason }, ); } if (options?.screenMask === undefined) return; @@ -74,7 +82,7 @@ export async function assertScreenshotCaptureSupport( throw new AppError( 'UNSUPPORTED_OPERATION', '--screen-mask requires a handheld iOS simulator simctl capture', - { reason: 'screenshot-screen-mask-unsupported' }, + { reason: SCREENSHOT_CAPTURE_REFUSAL_REASONS.screenMaskUnsupported.reason }, ); } } diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts index 6ab1889f73..fb805731c4 100644 --- a/packages/contracts/src/settings.test.ts +++ b/packages/contracts/src/settings.test.ts @@ -12,7 +12,6 @@ import { settingsAppNotConsumedRefusal, settingsAppScope, settingsHelpLines, - SETTINGS_APP_NOT_CONSUMED_REASON, SETTINGS_INVALID_ARGS_MESSAGE, SETTINGS_USAGE_OVERRIDE, textSizeSettingPayload, @@ -258,7 +257,7 @@ describe('settingsAppNotConsumedRefusal', () => { expect(refusal.code).toBe('INVALID_ARGS'); expect(refusal.message).toContain('settings location on'); expect(refusal.message).toContain('com.example.app'); - expect(refusal.details.reason).toBe(SETTINGS_APP_NOT_CONSUMED_REASON); + expect(refusal.details.reason).toBe('setting_app_not_consumed'); expect(refusal.details.dispatched).toBe('no'); expect(refusal.details.app).toBe('com.example.app'); expect(refusal.hint).toContain('settings permission grant location --app com.example.app'); diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index 5ac568e7e6..8534baba0b 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -1,4 +1,9 @@ -import { AppError, appNotInstalledDetails, discloseDispatch } from '@agent-device/kernel/errors'; +import { + AppError, + appNotInstalledDetails, + discloseDispatch, + type ReasonTable, +} from '@agent-device/kernel/errors'; import { APPEARANCE_ACTIONS, MOBILE_PERMISSION_TARGETS, @@ -120,12 +125,18 @@ export function settingsAppScope( } /** - * The reason a request is told its app names nothing: what a caller does about it — drop the app or - * move to a target whose mutation is app-scoped — is the reason's meaning, so a driver can branch - * on `error.details.reason` instead of the prose. Paired with `dispatched: no`, because the - * refusal runs before a device is touched. + * The `settings` refusal family: a request is told what its input cannot do, paired with + * `dispatched: no`, because the refusal runs before a device is touched. */ -export const SETTINGS_APP_NOT_CONSUMED_REASON = 'setting_app_not_consumed'; +const SETTINGS_REFUSAL_REASONS = { + /** + * The reason a request is told its app names nothing: what a caller does about it — drop the app + * or move to a target whose mutation is app-scoped — is the reason's meaning, so a driver can + * branch on `error.details.reason` instead of the prose. + */ + // The asked-for setting applies to the target itself, so the named app consumes nothing. + appNotConsumed: { reason: 'setting_app_not_consumed' }, +} as const satisfies ReasonTable<'settings'>; /** * The refusal a mutation answers with when its target consumes no app: the code, sentence, typed @@ -148,7 +159,7 @@ export function settingsAppNotConsumedRefusal( code: 'INVALID_ARGS', message: `settings ${described} applies to the target itself, not to an app: ${app} names nothing it can grant or revoke.`, details: { - reason: SETTINGS_APP_NOT_CONSUMED_REASON, + reason: SETTINGS_REFUSAL_REASONS.appNotConsumed.reason, dispatched: 'no', setting: described, app, diff --git a/packages/contracts/src/snapshot-private-evidence.ts b/packages/contracts/src/snapshot-private-evidence.ts index 42b74d9e47..b992448938 100644 --- a/packages/contracts/src/snapshot-private-evidence.ts +++ b/packages/contracts/src/snapshot-private-evidence.ts @@ -1,6 +1,13 @@ import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot'; +import type { ReasonTable } from '@agent-device/kernel/errors'; import type { IosViewportEvidence } from './ios-snapshot.ts'; +/** Why coordinate-derived input is refused on top of the capture it was measured from. */ +const SCREEN_ORIGIN_REFUSAL_REASONS = { + // The capture never established where its window sits on screen, so coordinates are unverifiable. + windowOriginUnknown: { reason: 'window-origin-unknown' }, +} as const satisfies ReasonTable<'snapshot'>; + /** * Capture-local clickability facts for consumers that reproduce Maestro's private * TreeNode semantics. This is deliberately kept outside the regular SnapshotNode: @@ -50,7 +57,7 @@ export async function assertSnapshotScreenOrigin(owner: object, label: string): const { AppError, discloseDispatch } = await import('@agent-device/kernel/errors'); throw discloseDispatch( new AppError('COMMAND_FAILED', `${label} has no established screen-coordinate origin`, { - reason: 'window-origin-unknown', + reason: SCREEN_ORIGIN_REFUSAL_REASONS.windowOriginUnknown.reason, hint: 'Take a fresh snapshot after the accessibility channel recovers, or use screenshot to choose screen coordinates.', }), 'no', diff --git a/packages/contracts/src/snapshot-runtime.ts b/packages/contracts/src/snapshot-runtime.ts index 93df5d1be6..f717af9c13 100644 --- a/packages/contracts/src/snapshot-runtime.ts +++ b/packages/contracts/src/snapshot-runtime.ts @@ -1,5 +1,9 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; -import { AppError } from '@agent-device/kernel/errors'; +import { + AppError, + INTERACTOR_BINDING_REFUSAL_REASONS, + type ReasonTable, +} from '@agent-device/kernel/errors'; import type { Interactor, RunnerContext, @@ -12,6 +16,12 @@ import type { RuntimeOperationFact } from './platform-runtime.ts'; export type { SnapshotRuntimeAcquiredResult, SnapshotResult } from './interactor-types.ts'; +/** Why this snapshot seam refuses before or after the interactor runs. */ +const SNAPSHOT_RUNTIME_REFUSAL_REASONS = { + // An acquired iOS snapshot reached a host with no presentation owner to publish it through. + presenterMissing: { reason: 'ios-snapshot-presenter-missing' }, +} as const satisfies ReasonTable<'snapshot'>; + /** Runner metadata needed by the selected snapshot implementation, without request-owned state. */ export type SnapshotRuntimeExecution = Readonly>; @@ -131,7 +141,10 @@ function bindSnapshotInteractor( throw new AppError( 'UNSUPPORTED_OPERATION', 'Provider-owned snapshot operation has no bound provider interactor.', - { reason: 'provider-runtime-interactor-missing', deviceId: params.device.id }, + { + reason: INTERACTOR_BINDING_REFUSAL_REASONS.providerInteractorMissing.reason, + deviceId: params.device.id, + }, ); } const result: SnapshotRuntimeResult = await interactor.snapshot({ ...input.options, signal }); @@ -140,7 +153,10 @@ function bindSnapshotInteractor( throw new AppError( 'COMMAND_FAILED', 'Acquired iOS snapshot has no host presentation owner.', - { reason: 'ios-snapshot-presenter-missing', deviceId: params.device.id }, + { + reason: SNAPSHOT_RUNTIME_REFUSAL_REASONS.presenterMissing.reason, + deviceId: params.device.id, + }, ); } return await params.presentIosAcquisition(result, input.options); diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index 68a82f8c3a..92186a9431 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -6,7 +6,12 @@ import { type ExecDetachedChannel, type ExecDetachedExit, } from '@agent-device/host-kit/command'; -import { AppError, normalizeError, type NormalizedError } from '@agent-device/kernel/errors'; +import { + AppError, + normalizeError, + type NormalizedError, + type ReasonTable, +} from '@agent-device/kernel/errors'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { stopDaemonProcess, @@ -55,6 +60,20 @@ import { } from './daemon-shutdown-report.ts'; import { DAEMON_PROGRESS_CHANNEL_ENV } from './daemon-startup-phases.ts'; +/** + * Why the daemon's owner refuses to start or observe a process it cannot prove it owns. Every row + * is a fail-closed answer: the state dir, the startup, or the admission gate does not resolve to a + * lifetime this host started. + */ +const DAEMON_OWNERSHIP_REFUSAL_REASONS = { + // Replay's admission gate is closed, so no new daemon startup is allowed. + startupAdmissionClosed: { reason: 'daemon_startup_admission_closed' }, + // The private replay state dir does not resolve to the one this host sealed for that capability. + privateStateUnowned: { reason: 'daemon_private_state_unowned' }, + // The observed process is not one of the startups this host launched and tracks. + privateStartupUnowned: { reason: 'daemon_private_startup_unowned' }, +} as const satisfies ReasonTable<'daemon lifecycle'>; + export const DAEMON_STARTUP_EXIT_CODES = Object.freeze({ busy: 75, unproven: 78 }); export type DaemonRegistrationFields = Readonly<{ socketPort?: number; @@ -275,7 +294,7 @@ export function launchDaemonProcess( const owned = input.ownedStateDir && requirePrivateReplayState(input.ownedStateDir, input.paths); if (owned?.sealed) throw new AppError('COMMAND_FAILED', 'Replay daemon startup admission is closed.', { - reason: 'daemon_startup_admission_closed', + reason: DAEMON_OWNERSHIP_REFUSAL_REASONS.startupAdmissionClosed.reason, }); admitDaemonStateRoot({ paths: input.paths, mode: 'establish' }); const logFd = fs.openSync(input.paths.logPath, 'a', 0o600); @@ -337,7 +356,7 @@ function requirePrivateReplayState( throw new AppError( 'COMMAND_FAILED', 'Private replay directory ownership could not be verified.', - { reason: 'daemon_private_state_unowned' }, + { reason: DAEMON_OWNERSHIP_REFUSAL_REASONS.privateStateUnowned.reason }, ); } return owned; @@ -466,7 +485,7 @@ function confirmOwnedStartupIdentity( function unownedStartupError(): AppError { return new AppError('COMMAND_FAILED', 'The observed daemon is not an owned startup lifetime.', { - reason: 'daemon_private_startup_unowned', + reason: DAEMON_OWNERSHIP_REFUSAL_REASONS.privateStartupUnowned.reason, }); } diff --git a/packages/daemon-contracts/src/daemon-resolution.ts b/packages/daemon-contracts/src/daemon-resolution.ts index 0df93a1bf0..f40b5d0c63 100644 --- a/packages/daemon-contracts/src/daemon-resolution.ts +++ b/packages/daemon-contracts/src/daemon-resolution.ts @@ -73,7 +73,7 @@ function resolveStateDir(raw: string | undefined, options: ResolveDaemonPathsOpt 'INVALID_ARGS', `State dir "${value}" is relative and no working directory was given.`, { - reason: 'relative_state_dir_without_cwd', + reason: DAEMON_STATE_ROOT_REASONS.relativeWithoutCwd.reason, }, ); } @@ -86,6 +86,14 @@ const DAEMON_STATE_ROOT_REASONS = { // The state directory, or a directory above it, is not private to your account; `details.fix` // says how to fix it. unsafe: { reason: 'daemon_state_root_unsafe' }, + // The state dir is a relative path and the caller gave no working directory to resolve it from. + relativeWithoutCwd: { reason: 'relative_state_dir_without_cwd' }, +} as const satisfies ReasonTable<'daemon lifecycle'>; + +/** Why this build refuses to send a request whose delivery the answering daemon cannot promise. */ +const DAEMON_CAPABILITY_REFUSAL_REASONS = { + // The remote daemon reports no script-artifacts capability, so it would record to its own disk. + scriptArtifactsUnsupported: { reason: 'remote_script_artifacts_unsupported' }, } as const satisfies ReasonTable<'daemon lifecycle'>; /** What the operator is told, per problem: how the component fails, and what ends it. */ @@ -390,7 +398,7 @@ export function readDaemonLifecycleFence(input: unknown): DaemonLifecycleFence | export function assertScriptArtifactsCapability(capabilities: readonly string[] | undefined): void { if (capabilities?.includes('script-artifacts')) return; throw new AppError('INVALID_ARGS', 'The remote daemon cannot deliver session scripts.', { - reason: 'remote_script_artifacts_unsupported', + reason: DAEMON_CAPABILITY_REFUSAL_REASONS.scriptArtifactsUnsupported.reason, daemonRequestSent: false, hint: 'Upgrade the daemon that owns the session. Through a proxy, the upstream daemon must report the script-artifacts capability in its /health response.', }); diff --git a/packages/daemon-contracts/src/daemon-stop.ts b/packages/daemon-contracts/src/daemon-stop.ts index 865d4c0214..d403e95e51 100644 --- a/packages/daemon-contracts/src/daemon-stop.ts +++ b/packages/daemon-contracts/src/daemon-stop.ts @@ -1,6 +1,16 @@ -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import type { DaemonRetirementResult } from './daemon-registration-owner.ts'; +/** + * Why `daemon stop` reports a retirement it could not prove. The owner is the retirement watchdog: + * the observation never came back the way the rule needs. + */ +const DAEMON_STOP_REASONS = { + // The stop could not confirm the daemon exited: the process stayed alive after the signal, the + // signal failed, or its start time or identity could not be verified. + exitUnconfirmed: { reason: 'daemon_exit_unconfirmed' }, +} as const satisfies ReasonTable<'daemon lifecycle'>; + import { DAEMON_LIFECYCLE_REASONS, embeddedCloseHint, @@ -142,7 +152,8 @@ function daemonRetirementError( pid: info.pid, processStartTime: info.startTime, reason: - refusal?.reason ?? (failure ? 'daemon_exit_unconfirmed' : 'daemon_retirement_unconfirmed'), + refusal?.reason ?? + (failure ? DAEMON_STOP_REASONS.exitUnconfirmed.reason : 'daemon_retirement_unconfirmed'), terminationReason: failure?.reason, signal: failure?.signal, retirement, diff --git a/packages/daemon-contracts/src/session-repair-tombstone.ts b/packages/daemon-contracts/src/session-repair-tombstone.ts index 638942782c..b78ed88a69 100644 --- a/packages/daemon-contracts/src/session-repair-tombstone.ts +++ b/packages/daemon-contracts/src/session-repair-tombstone.ts @@ -1,6 +1,12 @@ import path from 'node:path'; import fs from 'node:fs'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; + +/** Why this tombstone reader refuses to trust the marker on disk. */ +const REPAIR_EVIDENCE_REFUSAL_REASONS = { + // The repair tombstone file exists but does not parse into a valid marker. + invalid: { reason: 'repair_evidence_invalid' }, +} as const satisfies ReasonTable<'daemon lifecycle'>; /** * ADR 0012 decision 6, R7 (C5a): a reaped repair session leaves this bounded @@ -72,7 +78,7 @@ function parseRepairTombstone(raw: string, tombstonePath: string): RepairSession throw new AppError( 'COMMAND_FAILED', 'Repair evidence could not be inspected.', - { reason: 'repair_evidence_invalid', path: tombstonePath }, + { reason: REPAIR_EVIDENCE_REFUSAL_REASONS.invalid.reason, path: tombstonePath }, error instanceof Error ? error : undefined, ); } diff --git a/packages/daemon/src/execution/interaction/internal/find-target-capture.ts b/packages/daemon/src/execution/interaction/internal/find-target-capture.ts index de0598d3a5..f9213661ee 100644 --- a/packages/daemon/src/execution/interaction/internal/find-target-capture.ts +++ b/packages/daemon/src/execution/interaction/internal/find-target-capture.ts @@ -2,7 +2,7 @@ import type { DaemonResponse } from '@agent-device/kernel/contracts'; import type { FindLocator } from '@agent-device/selectors'; import type { BoundSelectorCapture } from '../../selector-capture-binding.ts'; import type { SnapshotQualityVerdict } from '@agent-device/kernel/snapshot'; -import { FIND_READ_REASONS } from '@agent-device/capture-kit/snapshot-quality-verdict'; +import { sparseFindRefusal } from '@agent-device/capture-kit/snapshot-quality-verdict'; import type { SnapshotState } from '@agent-device/contracts/snapshot-model'; import type { CaptureProvenance, RequestCaptureProof } from '../../../core/capture-disclosure.ts'; import { createSelectorCaptureRuntime } from '../../selector-capture-runtime.ts'; @@ -73,12 +73,8 @@ export function createFindTargetCapture( } export function sparseFindSnapshotResponse(verdict: SnapshotQualityVerdict): DaemonResponse { - return errorResponse('COMMAND_FAILED', 'find could not read the current accessibility tree', { - reason: FIND_READ_REASONS.snapshotUnreadable.reason, - verdictReason: verdict.reason, - verdictReasonCode: verdict.reasonCode, - hint: 'The snapshot quality verdict is sparse. Use screenshot as visual truth, navigate with coordinates if needed, then retry find after reaching a readable screen.', - }); + const refusal = sparseFindRefusal(verdict); + return errorResponse('COMMAND_FAILED', refusal.message, refusal.details); } function shouldScopeFind(locator: FindLocator): boolean { diff --git a/packages/gestures/src/gesture-plan.ts b/packages/gestures/src/gesture-plan.ts index cce52a2cd8..65a15335b8 100644 --- a/packages/gestures/src/gesture-plan.ts +++ b/packages/gestures/src/gesture-plan.ts @@ -1,4 +1,4 @@ -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import type { PublicPlatform } from '@agent-device/kernel/device'; import type { Point, Rect } from '@agent-device/kernel/snapshot'; import { @@ -32,6 +32,20 @@ import type { export const GESTURE_SAMPLE_INTERVAL_MS = 16; export const GESTURE_INITIAL_ANGLE_DEGREES = -90; + +/** Why a `gesture` input cannot be planned into an executable trajectory. */ +const GESTURE_PLAN_REFUSAL_REASONS = { + // Two tap contacts share coordinates, so one contact would press where another already rests. + tapDuplicatePoint: { reason: 'GESTURE_TAP_DUPLICATE_POINT' }, + // The gesture path has fewer usable samples than any recognizable motion needs. + pathTooShort: { reason: 'GESTURE_PATH_TOO_SHORT' }, + // The path's sample timeline is not ordered and finite, so no clock can play it back. + pathInvalidTimeline: { reason: 'GESTURE_PATH_INVALID_TIMELINE' }, + // A trajectory sample carries a non-finite coordinate. + trajectoryNonFinite: { reason: 'GESTURE_TRAJECTORY_NON_FINITE' }, + // A trajectory sample leaves the viewport, so the contact would press outside the screen. + trajectoryOutOfBounds: { reason: 'GESTURE_TRAJECTORY_OUT_OF_BOUNDS' }, +} as const satisfies ReasonTable<'gesture'>; const GESTURE_FLING_DEFAULT_DISTANCE = 180; const GESTURE_INITIAL_SPAN_RATIO = 0.25; @@ -452,7 +466,7 @@ function tapContactPoints(points: readonly Point[]): Point[] { const earlier = finite.findIndex((other) => other.x === point.x && other.y === point.y); if (earlier !== index) { throw new AppError('INVALID_ARGS', 'gesture tap points must be distinct', { - reason: 'GESTURE_TAP_DUPLICATE_POINT', + reason: GESTURE_PLAN_REFUSAL_REASONS.tapDuplicatePoint.reason, point, hint: 'Give each contact its own coordinates.', }); @@ -495,7 +509,7 @@ export function densifyGesturePath( const durationMs = canonical.at(-1)?.offsetMs ?? 0; if (canonical.length < 2 || !Number.isFinite(durationMs) || durationMs <= 0) { throw new AppError('INVALID_ARGS', 'gesture path needs at least two timed samples', { - reason: 'GESTURE_PATH_TOO_SHORT', + reason: GESTURE_PLAN_REFUSAL_REASONS.pathTooShort.reason, }); } if ( @@ -509,7 +523,7 @@ export function densifyGesturePath( 'INVALID_ARGS', 'gesture path needs a strictly increasing timeline from zero', { - reason: 'GESTURE_PATH_INVALID_TIMELINE', + reason: GESTURE_PLAN_REFUSAL_REASONS.pathInvalidTimeline.reason, }, ); } @@ -562,7 +576,7 @@ function assertSamplesInViewport( if (!Number.isFinite(x) || !Number.isFinite(y)) { throw new AppError('INVALID_ARGS', 'Gesture motion produces non-finite pointer coordinates', { ...details, - reason: 'GESTURE_TRAJECTORY_NON_FINITE', + reason: GESTURE_PLAN_REFUSAL_REASONS.trajectoryNonFinite.reason, hint: 'Reduce the requested rotation, translation, or scale.', }); } @@ -580,7 +594,7 @@ function assertSamplesInViewport( function trajectoryOutOfBounds(details: Record): AppError { return new AppError('INVALID_ARGS', 'Gesture trajectory does not fit inside the viewport', { ...details, - reason: 'GESTURE_TRAJECTORY_OUT_OF_BOUNDS', + reason: GESTURE_PLAN_REFUSAL_REASONS.trajectoryOutOfBounds.reason, hint: 'Move the gesture away from the edge or reduce its translation, scale, or rotation.', }); } diff --git a/packages/kernel/src/errors.ts b/packages/kernel/src/errors.ts index 5d7ec4d4c4..3279d23316 100644 --- a/packages/kernel/src/errors.ts +++ b/packages/kernel/src/errors.ts @@ -407,7 +407,7 @@ export function sessionOrDeviceSelectorRequiredDetails(): RefusalDetails< * cancellation through untouched (retry loops, provider adapters, runner * transports) dispatches on the same typed reason. */ -const REQUEST_CANCELED_REASON = 'request_canceled'; +export const REQUEST_CANCELED_REASON = 'request_canceled'; const REQUEST_CANCELED_MESSAGE = 'request canceled'; /** * A runtime owner whose facts advertised an operation it cannot actually perform: a contract bug, @@ -422,6 +422,17 @@ export function createRuntimeContractInvalidError(message: string): AppError { }); } +/** + * The provider fail-closed refusal every interactor binder answers with when the selected provider + * no longer exposes its interactor. Facts advertised the operation, so this names an ownership + * bug, and each binder pairs it with its own message. Declared beside the error factories because + * the binders in contracts raise it from modules that must not grow their eager closure. + */ +export const INTERACTOR_BINDING_REFUSAL_REASONS = { + // The selected provider owns this operation but exposes no bound interactor for it. + providerInteractorMissing: { reason: 'provider-runtime-interactor-missing' }, +} as const satisfies ReasonTable<'interactor binding'>; + const REQUEST_CANCELED_HINT = 'The request was canceled intentionally (explicit cancel or client disconnect) — no retry is needed unless the cancellation was unintended.'; diff --git a/packages/maestro/src/internal/compatibility-errors.ts b/packages/maestro/src/internal/compatibility-errors.ts index 5238a53fc3..3b5d889985 100644 --- a/packages/maestro/src/internal/compatibility-errors.ts +++ b/packages/maestro/src/internal/compatibility-errors.ts @@ -1,6 +1,12 @@ -import { AppError, type AppErrorDetails } from '@agent-device/kernel/errors'; +import { AppError, type AppErrorDetails, type ReasonTable } from '@agent-device/kernel/errors'; -const MAESTRO_TEST_FAILURE_REASON = 'maestro-test-failure'; +/** Why a Maestro-compatibility step ends its run. */ +const MAESTRO_COMPATIBILITY_REASONS = { + // A Maestro assertion or condition failed, so the replayed flow does not match the recording. + testFailure: { reason: 'maestro-test-failure' }, +} as const satisfies ReasonTable<'replay'>; + +const MAESTRO_TEST_FAILURE_REASON = MAESTRO_COMPATIBILITY_REASONS.testFailure.reason; export function maestroTestFailure(message: string, details: AppErrorDetails = {}): AppError { return new AppError('COMMAND_FAILED', message, { diff --git a/packages/platform-harmonyos/src/app-lifecycle.ts b/packages/platform-harmonyos/src/app-lifecycle.ts index a5d68f6c3d..9ae8049704 100644 --- a/packages/platform-harmonyos/src/app-lifecycle.ts +++ b/packages/platform-harmonyos/src/app-lifecycle.ts @@ -1,6 +1,6 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; import type { ShellWord } from '@agent-device/kernel/device-shell'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import { runHarmonyShell } from './hdc.ts'; import { invalidateHarmonyGestureViewport } from './snapshot.ts'; @@ -177,10 +177,16 @@ function combineHarmonySignals( /** A module.json5 ability name: a letter, then letters, digits, `_`, or `.`. */ const HARMONY_ABILITY_NAME = /^[A-Za-z][A-Za-z0-9_.]*$/; +/** Why a HarmonyOS app-open argument is refused before any device is touched. */ +const HARMONY_LIFECYCLE_REFUSAL_REASONS = { + // --activity is not an ability name the module.json5 format can carry. + invalidAbilityName: { reason: 'invalid-harmony-ability-name' }, +} as const satisfies ReasonTable<'open'>; + function requireHarmonyAbilityName(ability: string): void { if (HARMONY_ABILITY_NAME.test(ability)) return; throw new AppError('INVALID_ARGS', `Invalid HarmonyOS ability name: ${ability}`, { - reason: 'invalid-harmony-ability-name', + reason: HARMONY_LIFECYCLE_REFUSAL_REASONS.invalidAbilityName.reason, ability, hint: 'Pass --activity as the ability name from module.json5, such as EntryAbility.', }); diff --git a/packages/platform-vega/src/tool-provider.ts b/packages/platform-vega/src/tool-provider.ts index 5e63e7224e..dfbd121787 100644 --- a/packages/platform-vega/src/tool-provider.ts +++ b/packages/platform-vega/src/tool-provider.ts @@ -1,5 +1,5 @@ import type { VegaTvRemoteKey } from '@agent-device/contracts/tv-remote'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import { runCmd, type ExecOptions, type ExecResult } from '@agent-device/host-kit/command'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { createScopedProvider } from '@agent-device/kernel/scoped-provider'; @@ -53,10 +53,16 @@ export function createLocalVegaCliAdapter(host: HostEnvironment): VegaCliAdapter * runs, so reaching this default means the caller forgot to bind one — refuse instead of reading * an ambient environment (#3794). */ +/** Why this tool provider refuses when its CLI adapter was never bound to a host. */ +const VEGA_TOOL_PROVIDER_REFUSAL_REASONS = { + // A Vega CLI call reached the scope default: no caller composed a host-bound adapter first. + adapterHostUnbound: { reason: 'vega-adapter-host-unbound' }, +} as const satisfies ReasonTable<'Vega CLI adapter'>; + function unboundVegaCliAdapter(): VegaCliAdapter { const refuse = async (): Promise => { throw new AppError('COMMAND_FAILED', 'The Vega CLI adapter is not bound to a host.', { - reason: 'vega-adapter-host-unbound', + reason: VEGA_TOOL_PROVIDER_REFUSAL_REASONS.adapterHostUnbound.reason, }); }; return { run: refuse, isAvailable: refuse }; diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 6f619f4a37..1d6e2084cd 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -29,9 +29,11 @@ import { } from './json-utils.ts'; import type { WebProvider, WebSnapshotOptions, WebSnapshotResult } from './provider.ts'; import { + AGENT_BROWSER_REFUSAL_REASONS, getManagedAgentBrowserStatus, mapManagedAgentBrowserError, runManagedAgentBrowser, + type AgentBrowserBatchRefusal, } from './agent-browser-tool.ts'; import { agentBrowserFleetOf, type AgentBrowserFleet } from './agent-browser-fleet.ts'; import { cleanupManagedAgentBrowserOrphansForProviderStartup } from './agent-browser-lifecycle.ts'; @@ -227,7 +229,7 @@ async function sendTextEntry( cmd: AGENT_BROWSER, args: ['batch'], command: commandName, - reason: 'text-entry-result-unusable', + reason: AGENT_BROWSER_REFUSAL_REASONS.textEntryResultUnusable.reason, hint: AGENT_BROWSER_DOCTOR_HINT, }); } @@ -238,7 +240,7 @@ async function sendTextEntry( cmd: AGENT_BROWSER, args: ['batch'], command: commandName, - reason: 'text-entry-failed', + reason: AGENT_BROWSER_REFUSAL_REASONS.textEntryFailed.reason, // The backend ran and refused this entry, so its install is not the suspect. hint: userCommand === 'fill' @@ -424,7 +426,7 @@ async function fetchRefRects( { cmd: AGENT_BROWSER, args: ['batch'], - reason: 'snapshot-refs-unmeasurable', + reason: AGENT_BROWSER_REFUSAL_REASONS.snapshotRefsUnmeasurable.reason, requestedRefs: refs.length, measuredRects: 0, hint: AGENT_BROWSER_DOCTOR_HINT, @@ -486,7 +488,7 @@ function parseBatchEntries( commands: readonly (readonly string[])[], captureRefs: number, ): AgentBrowserBatchEntry[] { - const unusable = (reason: string): AppError => + const unusable = (reason: AgentBrowserBatchRefusal): AppError => new AppError( 'COMMAND_FAILED', `agent-browser returned an unusable batch result for snapshot geometry (${reason})`, @@ -499,12 +501,15 @@ function parseBatchEntries( hint: AGENT_BROWSER_DOCTOR_HINT, }, ); - if (!Array.isArray(data)) throw unusable('batch-result-not-a-list'); - if (data.length !== commands.length) throw unusable('entry-count'); - if (!data.every(isBatchEntry)) throw unusable('entry-shape'); + if (!Array.isArray(data)) + throw unusable(AGENT_BROWSER_REFUSAL_REASONS.batchResultNotAList.reason); + if (data.length !== commands.length) + throw unusable(AGENT_BROWSER_REFUSAL_REASONS.entryCount.reason); + if (!data.every(isBatchEntry)) throw unusable(AGENT_BROWSER_REFUSAL_REASONS.entryShape.reason); const entries = data; for (const [index, entry] of entries.entries()) { - if (!sameBatchCommand(entry.command, commands[index])) throw unusable('entry-command'); + if (!sameBatchCommand(entry.command, commands[index])) + throw unusable(AGENT_BROWSER_REFUSAL_REASONS.entryCommand.reason); } return entries; } diff --git a/packages/platform-web/src/agent-browser-tool.ts b/packages/platform-web/src/agent-browser-tool.ts index 8ab9c70f79..defd57d917 100644 --- a/packages/platform-web/src/agent-browser-tool.ts +++ b/packages/platform-web/src/agent-browser-tool.ts @@ -18,7 +18,7 @@ import { hostProcessId, readProcessStartTime, } from '@agent-device/host-kit/process'; -import { AppError, asAppError } from '@agent-device/kernel/errors'; +import { AppError, asAppError, type ReasonTable } from '@agent-device/kernel/errors'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { ManagedWebBackendStatus } from '@agent-device/contracts/managed-web-backend'; import { @@ -314,3 +314,32 @@ export function mapManagedAgentBrowserError(error: unknown): AppError { : 'Run `agent-device web setup` to install the managed web backend.', }); } + +/** + * Why the managed `agent-browser` backend's answer cannot be trusted. The backend runs and prints + * JSON; these rows are the shapes that JSON can have which prove the round trip went wrong, and + * the text-entry refusals the entry's own verdict gives. + */ +export const AGENT_BROWSER_REFUSAL_REASONS = { + // The batch call for a text entry answered with something other than its one echoed entry. + textEntryResultUnusable: { reason: 'text-entry-result-unusable' }, + // The backend ran the fill or type entry and the page refused it. + textEntryFailed: { reason: 'text-entry-failed' }, + // Every snapshot ref failed to measure, so the capture's refs belong to no live nodes. + snapshotRefsUnmeasurable: { reason: 'snapshot-refs-unmeasurable' }, + // The batch call answered with something that is not an entry list. + batchResultNotAList: { reason: 'batch-result-not-a-list' }, + // The batch answer has a different entry count than the commands that were sent. + entryCount: { reason: 'entry-count' }, + // A batch answer entry is not an entry shape this backend publishes. + entryShape: { reason: 'entry-shape' }, + // A batch answer entry echoes a different command than the one that was sent. + entryCommand: { reason: 'entry-command' }, +} as const satisfies ReasonTable<'web backend'>; + +/** The refusal shape a batch answer can take, as the provider's batch parser reads it. */ +export type AgentBrowserBatchRefusal = + | typeof AGENT_BROWSER_REFUSAL_REASONS.batchResultNotAList.reason + | typeof AGENT_BROWSER_REFUSAL_REASONS.entryCount.reason + | typeof AGENT_BROWSER_REFUSAL_REASONS.entryShape.reason + | typeof AGENT_BROWSER_REFUSAL_REASONS.entryCommand.reason; diff --git a/packages/platform-web/src/provider.ts b/packages/platform-web/src/provider.ts index f13fb6d080..dc05250d6f 100644 --- a/packages/platform-web/src/provider.ts +++ b/packages/platform-web/src/provider.ts @@ -1,6 +1,16 @@ import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture'; import type { SessionSurface } from '@agent-device/contracts/session'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; + +/** + * Why the un-composed web provider refuses: a request reached a web device with no composed + * provider, which is a composition bug, so every capability answers closed instead of borrowing a + * host it was never given (#3794). + */ +const WEB_PROVIDER_COMPOSITION_REFUSAL_REASONS = { + // A web-device request arrived with no composed provider for it. + providerMissing: { reason: 'web-provider-missing' }, +} as const satisfies ReasonTable<'web provider'>; import { createScopedProvider } from '@agent-device/kernel/scoped-provider'; import type { RawSnapshotNode } from '@agent-device/kernel/snapshot'; import type { @@ -80,7 +90,7 @@ export type WebProvider = { function uncomposedWebProviderFailure(): Promise { return Promise.reject( new AppError('COMMAND_FAILED', 'The web provider is not composed for this request.', { - reason: 'web-provider-missing', + reason: WEB_PROVIDER_COMPOSITION_REFUSAL_REASONS.providerMissing.reason, }), ); } diff --git a/packages/replay-test/src/internal/session-test-runtime.ts b/packages/replay-test/src/internal/session-test-runtime.ts index ecdf22b2fa..3c9821c0bc 100644 --- a/packages/replay-test/src/internal/session-test-runtime.ts +++ b/packages/replay-test/src/internal/session-test-runtime.ts @@ -1,7 +1,7 @@ import fs from 'node:fs'; import path from 'node:path'; import { setTimeout as sleep } from 'node:timers/promises'; -import { normalizeError } from '@agent-device/kernel/errors'; +import { normalizeError, type ReasonTable } from '@agent-device/kernel/errors'; import { replayTestAttemptFailure, type ReplayTestAttemptFailed, @@ -17,7 +17,14 @@ import { const REPLAY_TIMEOUT_CLEANUP_GRACE_MS = 2_000; const REPLAY_TEST_TIMEOUT_HINT = 'Replay test timeouts are cooperative; the active command may take a short grace period to stop.'; -const REPLAY_TIMEOUT_CLEANUP_PENDING_REASON = 'timeout_cleanup_pending'; + +/** Why a `replay --test` attempt ends as an infrastructure failure on the timeout path. */ +const REPLAY_TEST_TIMEOUT_REASONS = { + // The cooperative deadline ended the attempt while the abandoned replay may still run. + timeout: { reason: 'timeout' }, + // Cleanup of an abandoned replay is still pending, so the suite stops instead of retrying. + cleanupPending: { reason: 'timeout_cleanup_pending' }, +} as const satisfies ReasonTable<'replay'>; export async function runReplayTestAttempt( params: { @@ -328,7 +335,7 @@ function markReplayTimeoutCleanupPending( ...outcome.error, details: { ...(outcome.error.details ?? {}), - reason: REPLAY_TIMEOUT_CLEANUP_PENDING_REASON, + reason: REPLAY_TEST_TIMEOUT_REASONS.cleanupPending.reason, timeoutCleanupPending: true, }, }, @@ -399,7 +406,7 @@ function createReplayTestTimeoutOutcome( message: `TIMEOUT after ${timeoutMs}ms`, hint: REPLAY_TEST_TIMEOUT_HINT, details: { - reason: 'timeout', + reason: REPLAY_TEST_TIMEOUT_REASONS.timeout.reason, timeoutMs, timeoutMode: 'cooperative', artifactPaths, diff --git a/packages/selectors/src/interaction-error.ts b/packages/selectors/src/interaction-error.ts index f0e58c1950..c49f762178 100644 --- a/packages/selectors/src/interaction-error.ts +++ b/packages/selectors/src/interaction-error.ts @@ -60,6 +60,14 @@ export const INTERACTION_ERROR_REASONS = { */ // The target did not come to rest before the press; wait for the screen, then retry. targetStillMoving: { reason: 'target_still_moving' }, + /** + * Every tappable region of the target belongs to one of its interactive children, so a press on + * the parent would land on a child control. `details.competitorRefs` names up to five of those + * children and `details.competitorCount` counts them. The owner is + * `packages/selectors/src/node-touch-point.ts`. + */ + // Every tappable region of the target belongs to one of its interactive children. + coveredByInteractiveDescendants: { reason: 'covered_by_interactive_descendants' }, } as const satisfies ReasonTable<'interaction'>; /** The part of a covered node a refusal reports. */ diff --git a/packages/selectors/src/interaction-offscreen.ts b/packages/selectors/src/interaction-offscreen.ts index 1d56279e80..b97392b370 100644 --- a/packages/selectors/src/interaction-offscreen.ts +++ b/packages/selectors/src/interaction-offscreen.ts @@ -1,5 +1,5 @@ import { shellQuote } from '@agent-device/kernel/device-shell'; -import { AppError, discloseDispatch } from '@agent-device/kernel/errors'; +import { AppError, discloseDispatch, type ReasonTable } from '@agent-device/kernel/errors'; import { normalizeRef, type Rect, type SnapshotNode } from '@agent-device/kernel/snapshot'; import { createSnapshotVisibility } from '@agent-device/contracts/snapshot'; import { @@ -8,6 +8,23 @@ import { } from '@agent-device/capture-kit/mobile-snapshot-semantics'; import type { InteractionAction } from './interaction-action.ts'; +const OFFSCREEN_REFUSAL_REASONS = { + /** + * The acting pipeline's off-screen stage refused a target named by selector: the resolved node + * sits outside the screen, so nothing was pressed and `details.selector` names the target. The + * owner is `packages/command-runtime/src/commands/interaction/runtime/target-visibility-stages.ts`. + */ + // A selector resolved to an element outside the screen, so nothing was pressed. + offscreenSelector: { reason: 'offscreen_selector' }, + /** + * The acting pipeline's off-screen stage refused a target named by `@ref`: the resolved node sits + * outside the screen, so nothing was pressed and `details.ref` names it. The owner is + * `packages/command-runtime/src/commands/interaction/runtime/target-visibility-stages.ts`. + */ + // An @ref resolved to an element outside the screen, so nothing was pressed. + offscreenRef: { reason: 'offscreen_ref' }, +} as const satisfies ReasonTable<'interaction'>; + /** * The one off-screen rule every element-targeted dispatch applies: the acting runtime paths through * `throwIfOffscreenInteractionTarget`, and `find focus|type`, which dispatches its point @@ -72,7 +89,7 @@ export function offscreenSelectorFailure( ): Parameters[2] { return { message: `Selector ${selector} resolved to an off-screen element and is not safe to ${action}`, - details: { reason: 'offscreen_selector', selector }, + details: { reason: OFFSCREEN_REFUSAL_REASONS.offscreenSelector.reason, selector }, // A selector re-resolves against a fresh snapshot on every attempt, so the // recovery is: move the named direction, then retry THIS selector - no // separate snapshot step, and no @ref (a scroll expires the ref frame, @@ -90,7 +107,7 @@ export function offscreenRefFailure( ): Parameters[2] { return { message: `Ref ${refInput} is off-screen and not safe to ${action}`, - details: { reason: 'offscreen_ref', ref: normalizeRef(refInput) }, + details: { reason: OFFSCREEN_REFUSAL_REASONS.offscreenRef.reason, ref: normalizeRef(refInput) }, // The scroll that reveals the target expires the ref frame (#1366, ADR // 0014), so retrying this @ref would be rejected next. Steer to a selector, // which re-resolves against a fresh snapshot and bypasses the ref-frame guard diff --git a/packages/selectors/src/node-touch-point.ts b/packages/selectors/src/node-touch-point.ts index 24fc62e6c1..3ba8a0cbfa 100644 --- a/packages/selectors/src/node-touch-point.ts +++ b/packages/selectors/src/node-touch-point.ts @@ -188,7 +188,7 @@ export function resolveNodeTouchPoint( 'COMMAND_FAILED', `${failure.blockedTargetLabel} has no parent-owned touch point outside its interactive descendants`, { - reason: 'covered_by_interactive_descendants', + reason: INTERACTION_ERROR_REASONS.coveredByInteractiveDescendants.reason, ...failure.blockedTargetDetails, competitorRefs: resolution.competitorRefs.slice(0, 5).map((ref) => `@${ref}`), competitorCount: resolution.competitorCount, diff --git a/website/docs/docs/error-reasons.md b/website/docs/docs/error-reasons.md index 9091c1f074..635d81ac3e 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -15,6 +15,9 @@ Treat a reason that this page does not list as unknown, not as an error in the r | Reason | Meaning | | --- | --- | +| `alert_button_undecided` | The sheet's buttons name no single choice for the asked-for action. | +| `alert_capture_undecided` | The capture is alert-shaped but resolves to no single alert. | +| `alert-window-expired` | A press went out but the confirm window never settled whether the alert is gone. | | `alert-wait-window-too-long` | `alert wait` was given a longer window than it can honour; the command refuses it before running and never shortens it. `details.maxWaitWindowMs` names the limit. | ### `audit` @@ -91,6 +94,8 @@ Treat a reason that this page does not list as unknown, not as an error in the r | --- | --- | | `no_text_input_at_point` | A coordinate `fill` point identified no text input, so nothing was tapped or typed. | | `text_input_probe_unavailable` | The runner could not tell whether a coordinate `fill` point holds a text input; nothing was tapped. | +| `fill_text_stdin_target_invalid` | The stdin text mode's positional list does not decode to exactly one target. | +| `fill_text_source_conflict` | The stdin text mode was also given a text argument, so the two sources disagree. | | `android_shell_text_unsupported` | The adb-shell fallback carries ASCII text only; a helper or provider channel is needed. | | `android_ime_helper_no_ack` | The test IME helper gave no evidence it attempted the dispatch, so nothing is proven typed. | | `android_ime_helper_dispatch_rejected` | The test IME helper answered that it rejected the dispatch, so nothing was typed. | @@ -126,6 +131,16 @@ Treat a reason that this page does not list as unknown, not as an error in the r | `fold-angle-unverified` | The iOS simulator hinge did not reach the angle of the final keyframe. | | `fold-pose-unsettled` | The iOS simulator hinge reached the pose but never came to rest. | +### `gesture` + +| Reason | Meaning | +| --- | --- | +| `GESTURE_TAP_DUPLICATE_POINT` | Two tap contacts share coordinates, so one contact would press where another already rests. | +| `GESTURE_PATH_TOO_SHORT` | The gesture path has fewer usable samples than any recognizable motion needs. | +| `GESTURE_PATH_INVALID_TIMELINE` | The path's sample timeline is not ordered and finite, so no clock can play it back. | +| `GESTURE_TRAJECTORY_NON_FINITE` | A trajectory sample carries a non-finite coordinate. | +| `GESTURE_TRAJECTORY_OUT_OF_BOUNDS` | A trajectory sample leaves the viewport, so the contact would press outside the screen. | + ### `install-from-source` | Reason | Meaning | @@ -144,6 +159,7 @@ Treat a reason that this page does not list as unknown, not as an error in the r | Reason | Meaning | | --- | --- | +| `launch-console-owner-unadmitted` | --launch-console was asked for on an app-launch owner that cannot stream a console. | | `claim-lost-during-open` | The device lost the claim this open was made with; close the session and open the device again. | | `runtime-hints-operation-missing` | Runtime hints were requested, but the device runtime admitted no operation to apply or clear them. | | `android_port_reverse_rebind_refused` | The endpoint already has a device mapping, which a `--no-rebind` reverse never replaces. | @@ -155,6 +171,7 @@ Treat a reason that this page does not list as unknown, not as an error in the r | `system-surface-host-not-openable` | The bundle hosts an iOS system surface, which `open` refuses to launch as an app. | | `launch_confirmation_foreign_app` | iOS asks to open another app's URL scheme instead of the session app's. | | `launch_confirmation_unanswered` | The Simulator has not completed the launch URL; an "Open in" prompt may still be waiting. | +| `invalid-harmony-ability-name` | --activity is not an ability name the module.json5 format can carry. | | `android_test_ime_recovery_fence_failed` | The recovery records that keep the IME switch safe could not be persisted, so the switch stays unsafe. | | `foreground_app_ambiguous` | `open --foreground` found no single running app to bring forward on the selected simulator. | @@ -225,6 +242,17 @@ Treat a reason that this page does not list as unknown, not as an error in the r | Reason | Meaning | | --- | --- | +| `contact_sheet_unsupported_host` | The host cannot decode frames at all: frame decoding is Apple AVFoundation tooling. | +| `contact_sheet_duration_unknown` | The MP4 timeline could not be read, so no bounded sample grid can be planned. | +| `contact_sheet_frame_extraction_failed` | The contact sheet could not obtain usable extracted frames: the extractor failed to start, run, or return frames the sheet can use. | +| `contact_sheet_no_frames` | Extraction returned nothing usable, so there is no sheet to draw. | +| `contact_sheet_pixel_budget_exceeded` | The sheet would exceed the caller's image pixel budget even at the smallest cell. | +| `contact_sheet_container_unsupported` | The file is present but is not a container this feature decodes, such as a WebM recording. | +| `contact_sheet_output_write_failed` | The sheet could not be written where it was asked to land. | +| `contact_sheet_output_collides_with_input` | The output resolves to the recording itself, which a sheet must never replace. | +| `contact_sheet_threshold_invalid` | The change threshold is not a finite share between 0 and 1. | +| `video_validator_compile_timeout` | The Swift compile is still running past the caller's wait; try the stop again. | +| `video_validator_unavailable` | The validator could not be built or run at all, so playability stays unverified. | | `android_screenrecord_startup_failed` | Android `screenrecord` exited before it began writing; its startup output says why. | | `recording-output-unplayable` | The recording's file is not a playable video, which only a recorder still finalizing it can undo. | | `native_recovery_evidence_unavailable` | The marker exists but the device could not be read, so it cannot be classified. | @@ -242,16 +270,22 @@ Treat a reason that this page does not list as unknown, not as an error in the r | Reason | Meaning | | --- | --- | +| `replay_target_guard_mismatch` | Dispatch resolved a different node than the replay plan verified for this step. | | `wait_landmark_identity_mismatch` | A replay destination guard refused the match because its identity differs from the recorded landmark. | | `bounded_composite_resource_unsupported` | The composite refused this step before dispatch because it must run as its own command, such as a recording, trace, log, audio or perf capture. `details.shape` names the refused operation or option, and `details.standaloneCommandName` the public command to run instead. Earlier steps may have run. | +| `maestro-test-failure` | A Maestro assertion or condition failed, so the replayed flow does not match the recording. | | `android-process-probe-unavailable` | `adb pidof` or the resumed-activity read did not answer, so process state is unknown. | | `android-kill-process-survived` | `am kill` returned and the process is still running; force-stop it instead. | | `android-kill-requires-background-app` | `am kill` only reaps background processes, so it refuses the foreground app. | +| `timeout` | The cooperative deadline ended the attempt while the abandoned replay may still run. | +| `timeout_cleanup_pending` | Cleanup of an abandoned replay is still pending, so the suite stops instead of retrying. | ### `screenshot` | Reason | Meaning | | --- | --- | +| `screenshot-capture-backend-unsupported` | `--capture-backend` names a backend the selected capture owner does not declare. | +| `screenshot-screen-mask-unsupported` | `--screen-mask` was asked for on a device whose capture path cannot read the screen mask. | | `CROP_SELECTOR_INVALID` | The `--crop-on` value is not a valid selector expression. | | `CROP_TARGET_NOT_FOUND` | No element matches the `--crop-on` selector. | | `CROP_TARGET_AMBIGUOUS` | More than one element matches the `--crop-on` selector. | @@ -295,6 +329,7 @@ Treat a reason that this page does not list as unknown, not as an error in the r | Reason | Meaning | | --- | --- | +| `setting_app_not_consumed` | The asked-for setting applies to the target itself, so the named app consumes nothing. | | `android_bluetooth_adapter_missing` | The device declares no Bluetooth adapter, so there is nothing to turn on or off. | | `android_bluetooth_command_unavailable` | The build predates `svc bluetooth`, so the adapter cannot be switched from the shell. | | `bluetooth-not-applied` | The device kept Bluetooth in its prior state after `svc bluetooth` accepted the request. | @@ -321,6 +356,8 @@ Treat a reason that this page does not list as unknown, not as an error in the r | Reason | Meaning | | --- | --- | +| `window-origin-unknown` | The capture never established where its window sits on screen, so coordinates are unverifiable. | +| `ios-snapshot-presenter-missing` | An acquired iOS snapshot reached a host with no presentation owner to publish it through. | | `observation-unavailable` | The runner answered an observe-only snapshot request without an observe-only snapshot. | | `empty-snapshot` | XCTest returned a snapshot with no nodes on an iOS simulator. | @@ -371,6 +408,12 @@ These reasons can come from more than one command. | --- | --- | | `swift_cache_untrusted` | The Swift helper cache, a helper compiled into it, or the selected `DEVELOPER_DIR` is not a trusted path that only this user or root can change. | +### Vega CLI adapter + +| Reason | Meaning | +| --- | --- | +| `vega-adapter-host-unbound` | A Vega CLI call reached the scope default: no caller composed a host-bound adapter first. | + ### Android adb port reverse | Reason | Meaning | @@ -505,11 +548,18 @@ These reasons can come from more than one command. | `startup-stalled` | The daemon stayed registered and reachable but never reported the startup phase that follows. | | `startup-ceiling` | Startup passed the ceiling its own startup budget allows, so this client stopped waiting. | | `daemon_binding_with_remote_base_url` | The client named both a pinned daemon instance and a daemon base URL, which answer "which daemon" two different ways. | +| `daemon_startup_admission_closed` | Replay's admission gate is closed, so no new daemon startup is allowed. | +| `daemon_private_state_unowned` | The private replay state dir does not resolve to the one this host sealed for that capability. | +| `daemon_private_startup_unowned` | The observed process is not one of the startups this host launched and tracks. | | `daemon_state_root_unsafe` | The state directory, or a directory above it, is not private to your account; `details.fix` says how to fix it. | +| `relative_state_dir_without_cwd` | The state dir is a relative path and the caller gave no working directory to resolve it from. | +| `remote_script_artifacts_unsupported` | The remote daemon reports no script-artifacts capability, so it would record to its own disk. | | `daemon-busy` | The daemon still holds work, so it refused to leave; `details` counts that work. | | `daemon-instance-mismatch` | The request names a different daemon instance than the one answering it. | | `daemon-owner-embedded` | A live host process owns this daemon and ends it through its own `close()`. | | `daemon_shutting_down` | The daemon has begun to leave, so it refuses every new request; retry against a new daemon. | +| `daemon_exit_unconfirmed` | The stop could not confirm the daemon exited: the process stayed alive after the signal, the signal failed, or its start time or identity could not be verified. | +| `repair_evidence_invalid` | The repair tombstone file exists but does not parse into a valid marker. | | `daemon_registration_refused` | Another daemon holds this state directory, or its registration could not be proven free, so this daemon did not start; `details.status` says which. | | `daemon-clean-not-detached` | The record does not prove the process is a daemon of its own, so its process tree may be someone else's work. | @@ -553,6 +603,13 @@ These reasons can come from more than one command. | `DEVICE_CLAIM_RECOVERY_PENDING` | The recorded owner is gone and its resources still need settling before the claim is released. | | `DEVICE_CLAIM_OWNER_UNCERTAIN` | A claim exists, but its owner cannot be verified as live or gone. | +### Device inventory + +| Reason | Meaning | +| --- | --- | +| `invalid_device_pin` | A device-pin selector names a platform, device, udid, or serial the request cannot carry. | +| `provider_instance_unallocated` | The provider connection has no allocated instance to route to. | + ### Device selection | Reason | Meaning | @@ -569,6 +626,13 @@ These reasons can come from more than one command. | `hdc-shell-fragment-unsupported` | `hdc` double-quotes every element, so a shell fragment cannot reach the device as a script. | | `unguarded-device-shell-argv` | A `shell`/`exec-out` command the device-shell builder did not build was refused before dispatch. | +### Durable capture + +| Reason | Meaning | +| --- | --- | +| `resource-already-completed` | The record is already committed, so a finish, cleanup, or late progress write is refused. | +| `resource-missing` | The record the caller holds a descriptor for no longer exists on disk. | + ### Foldable panels | Reason | Meaning | @@ -603,6 +667,13 @@ These reasons can come from more than one command. | --- | --- | | `human_control_active` | A human holds the device, so state-changing commands are refused while the hold is active; retry after it is released. | +### Image decoding + +| Reason | Meaning | +| --- | --- | +| `png_decode_failed` | The input could not be decoded as PNG: its signature is missing or its body is corrupt. | +| `jpeg_decode_failed` | The bytes carry a JPEG signature but the JPEG decoder could not read them. | + ### Interaction | Reason | Meaning | @@ -616,14 +687,26 @@ These reasons can come from more than one command. | `target_not_hittable` | The platform reports the target as not hittable, so nothing was pressed. | | `target_disabled` | `find focus` or `find type` resolved to a disabled text field. | | `target_still_moving` | The target did not come to rest before the press; wait for the screen, then retry. | +| `covered_by_interactive_descendants` | Every tappable region of the target belongs to one of its interactive children. | +| `offscreen_selector` | A selector resolved to an element outside the screen, so nothing was pressed. | +| `offscreen_ref` | An @ref resolved to an element outside the screen, so nothing was pressed. | + +### Interactor binding + +| Reason | Meaning | +| --- | --- | +| `provider-runtime-interactor-missing` | The selected provider owns this operation but exposes no bound interactor for it. | ### Leases | Reason | Meaning | | --- | --- | +| `INVALID_LEASE_RESPONSE` | The daemon's lease answer is missing an identity field the client must key on. | | `LEASE_NOT_FOUND` | The lease that the request names is not active. | | `LEASE_SCOPE_MISMATCH` | The lease does not match the tenant, run, backend, provider, device, or client of the request. | | `LEASE_SCOPE_REQUIRED` | The lease was allocated with an owner scope that the request does not repeat. | +| `device-spec-unsupported` | The request picks a device by OS version, image tag, device mode, baseline, or class, and nothing on its path honours a spec. | +| `device-spec-invalid` | A device-spec key was given a value of the wrong type. | | `provider-instance-ended` | The device instance behind the lease ended outside the daemon, which ends the lease with it. | | `DEVICE_LEASE_BUSY` | Another lease, or this tenant run, already holds the device; retry after that lease is released or expires. | | `LEASE_ID_IN_USE` | The requested lease id already names a lease that this daemon issued. | @@ -845,6 +928,24 @@ These reasons can come from more than one command. | `transfer_ingress_deadline_exceeded` | The upload request exceeded its aggregate deadline (`details.timeoutMs`), which also covers processing after the body arrived. | | `upload_canceled` | The client disconnected or canceled before the upload finished. | +### Web backend + +| Reason | Meaning | +| --- | --- | +| `text-entry-result-unusable` | The batch call for a text entry answered with something other than its one echoed entry. | +| `text-entry-failed` | The backend ran the fill or type entry and the page refused it. | +| `snapshot-refs-unmeasurable` | Every snapshot ref failed to measure, so the capture's refs belong to no live nodes. | +| `batch-result-not-a-list` | The batch call answered with something that is not an entry list. | +| `entry-count` | The batch answer has a different entry count than the commands that were sent. | +| `entry-shape` | A batch answer entry is not an entry shape this backend publishes. | +| `entry-command` | A batch answer entry echoes a different command than the one that was sent. | + +### Web provider + +| Reason | Meaning | +| --- | --- | +| `web-provider-missing` | A web-device request arrived with no composed provider for it. | + ### Web session naming | Reason | Meaning |