From 17c7b37f409f9ba6d9d0c0333fabf675489ba417 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 21:25:11 +0100 Subject: [PATCH 01/13] refactor(reasons): declare the R6b reasons in ReasonTable rows Migrates the 59 published error.details.reason values of the R6b packages into ReasonTable rows beside the code that raises them, so every wire spelling is declared once and read as TABLE.member.reason. Three sites published prose or an internal code as their reason and now publish a typed value instead: the PNG and JPEG screenshot decoders (png_decode_failed / jpeg_decode_failed, decoder message moved to details.decoderError), the sparse-capture find refusal (find_snapshot_unreadable, verdict prose moved to details.verdictReason), and the snapshot router's cancelled rethrow (always request_canceled, the kernel-owned value it already carried in details). Regenerated website/docs/docs/error-reasons.md. --- packages/capture-kit/src/alert-tree-driver.ts | 12 +- .../capture-kit/src/durable-capture/fence.ts | 21 +++- .../src/durable-capture/finish-recovered.ts | 4 +- .../capture-kit/src/png-worker-client.test.ts | 4 +- packages/capture-kit/src/png.ts | 17 ++- .../contact-sheet-frames-host-support.test.ts | 4 +- .../recording/contact-sheet-frames.test.ts | 24 ++-- .../src/recording/contact-sheet-frames.ts | 16 +-- .../src/recording/contact-sheet-plan.test.ts | 8 +- .../src/recording/contact-sheet-plan.ts | 4 +- .../src/recording/contact-sheet-render.ts | 4 +- .../src/recording/contact-sheet-report.ts | 50 +++++--- .../src/recording/contact-sheet.test.ts | 37 +++--- .../src/recording/contact-sheet.ts | 17 ++- packages/capture-kit/src/recording/video.ts | 19 ++- .../capture-kit/src/screenshot-image.test.ts | 19 ++- packages/capture-kit/src/screenshot-image.ts | 7 +- .../capture-kit/src/snapshot-router/router.ts | 10 +- packages/client/src/lease-client.ts | 10 +- .../runtime/selector-read-utils.ts | 12 +- .../interaction/runtime/selector-read.test.ts | 9 +- .../runtime/target-visibility-stages.ts | 15 ++- .../recording/runtime/contact-sheet.test.ts | 4 +- .../recording/runtime/contact-sheet.ts | 4 +- .../src/interaction/interactions.ts | 14 ++- packages/contracts/src/alert-contract.ts | 56 +++++---- .../src/application-lifecycle-interaction.ts | 19 ++- packages/contracts/src/device-inventory.ts | 17 ++- .../src/interactor-operation-binding.ts | 11 +- packages/contracts/src/lease-scope.ts | 14 +-- packages/contracts/src/replay.ts | 24 ++-- packages/contracts/src/screenshot-runtime.ts | 14 ++- packages/contracts/src/settings.ts | 27 ++-- .../src/snapshot-private-evidence.ts | 9 +- packages/contracts/src/snapshot-runtime.ts | 22 +++- .../src/daemon-registration-owner.ts | 27 +++- .../daemon-contracts/src/daemon-resolution.ts | 12 +- packages/daemon-contracts/src/daemon-stop.ts | 14 ++- .../src/session-repair-tombstone.ts | 10 +- packages/gestures/src/gesture-plan.ts | 26 +++- packages/kernel/src/errors.ts | 13 +- .../src/internal/compatibility-errors.ts | 10 +- .../platform-harmonyos/src/app-lifecycle.ts | 10 +- packages/platform-vega/src/tool-provider.ts | 10 +- .../src/agent-browser-provider.ts | 21 ++-- .../platform-web/src/agent-browser-tool.ts | 31 ++++- packages/platform-web/src/provider.ts | 14 ++- .../src/internal/session-test-runtime.ts | 15 ++- packages/selectors/src/interaction-error.ts | 22 ++++ packages/selectors/src/node-touch-point.ts | 2 +- website/docs/docs/error-reasons.md | 117 ++++++++++++++++++ 51 files changed, 683 insertions(+), 229 deletions(-) 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..997bc799b8 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 bytes carry a PNG signature but the PNG decoder could not read them. + 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..d09fef1229 100644 --- a/packages/capture-kit/src/recording/contact-sheet-report.ts +++ b/packages/capture-kit/src/recording/contact-sheet-report.ts @@ -1,28 +1,40 @@ +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 = { + /** Frame decoding is Apple AVFoundation tooling, so a host on another platform cannot build one. */ + // 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. */ + // The MP4 timeline could not be read, so no bounded sample grid can be planned. + durationUnknown: { reason: 'contact_sheet_duration_unknown' }, + /** Frame extraction ran and failed, rather than returning fewer frames. */ + // Frame extraction ran and failed, rather than returning fewer frames. + frameExtractionFailed: { reason: 'contact_sheet_frame_extraction_failed' }, + /** Extraction returned nothing usable, so there is no sheet to draw. */ + // Extraction returned nothing usable, so there is no sheet to draw. + noFrames: { reason: 'contact_sheet_no_frames' }, + /** The requested sheet would exceed the caller's image pixel budget even at the smallest cell. */ + // 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. */ + // 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. */ + // 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. */ + // 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. */ + // 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..2705554fbb 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. */ +export 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-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..2e962281f5 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. */ +export 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..c8b0ebe32e 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 @@ -3,11 +3,17 @@ import type { InteractionRefTarget, InteractionSelectorTarget, } from '@agent-device/contracts/interaction'; -import { AppError } from '@agent-device/kernel/errors'; +import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; import type { FindLocator } from '@agent-device/selectors'; export { findNodeByLabel, resolveRefLabel } from '@agent-device/capture-kit/snapshot-node-lookup'; +/** Why `find` refuses a capture that cannot be read as the screen. */ +export 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'>; + function shouldScopeFind(locator: string): boolean { return locator === 'text' || locator === 'label' || locator === 'any'; } @@ -41,7 +47,9 @@ 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, + 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.', }); } 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..bc7556db6f 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 @@ -5,7 +5,7 @@ import { createLocalArtifactAdapter } from '@agent-device/host-kit/local-artifac import { createAgentDevice } from '../../../runtime.ts'; import { localCommandPolicy } from '@agent-device/contracts/command-policy'; import type { CommandSessionStore } from '@agent-device/contracts/runtime-contract'; -import { selector } from './selector-read-utils.ts'; +import { FIND_READ_REASONS, selector } from './selector-read-utils.ts'; import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures'; import { createFakeClock, @@ -287,9 +287,10 @@ 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_READ_REASONS.snapshotUnreadable.reason); + assert.equal(details?.verdictReason, 'sparse tree'); + assert.match(String(details?.hint ?? ''), /snapshot quality verdict is sparse/); return true; }, ); diff --git a/packages/command-runtime/src/commands/interaction/runtime/target-visibility-stages.ts b/packages/command-runtime/src/commands/interaction/runtime/target-visibility-stages.ts index a66a95a2fc..1274d8a09d 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/target-visibility-stages.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/target-visibility-stages.ts @@ -14,13 +14,16 @@ import type { ResolvedInteractionTarget, SurfaceScopedNodes, } from '@agent-device/contracts/interaction'; +import { + coveredInteractionDetails, + INTERACTION_ERROR_REASONS, +} from '@agent-device/selectors/interaction-error'; import { runNodePipelineStages, type SelectorPipelineHooks, } from '@agent-device/selectors/selector-pipeline'; import type { ActingPipelinePolicy } from '@agent-device/selectors/selector-pipeline-policy'; import { createSnapshotVisibility } from '@agent-device/contracts/snapshot'; -import { coveredInteractionDetails } from '@agent-device/selectors/interaction-error'; import { classifyOffscreenScrollDirection, type OffscreenScrollDirection, @@ -129,7 +132,10 @@ export async function assertVisibleSelectorTarget( ): Promise { return await throwIfOffscreenInteractionTarget(runtime, options, node, nodes, { message: `Selector ${selector} resolved to an off-screen element and is not safe to ${action}`, - details: { reason: 'offscreen_selector', selector }, + details: { + reason: INTERACTION_ERROR_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, @@ -151,7 +157,10 @@ export async function assertVisibleRefTarget( ): Promise { return await throwIfOffscreenInteractionTarget(runtime, options, node, nodes, { message: `Ref ${refInput} is off-screen and not safe to ${action}`, - details: { reason: 'offscreen_ref', ref: normalizeRef(refInput) }, + details: { + reason: INTERACTION_ERROR_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/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..69b7dfd5f1 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. */ +export 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 231bddfdaf..5f96d14280 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. @@ -60,14 +62,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 @@ -200,22 +226,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..97b8a1c360 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. */ +export 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 c9279d78d1..d1ef58fce9 100644 --- a/packages/contracts/src/device-inventory.ts +++ b/packages/contracts/src/device-inventory.ts @@ -11,7 +11,15 @@ import { type DeviceTarget, type PlatformSelector, } from '@agent-device/kernel/device'; -import { AppError } from '@agent-device/kernel/errors'; +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', @@ -125,7 +133,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, }); @@ -184,7 +192,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 cd6a9862eb..6ea2a5e51a 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' }, } 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..eb82bd1605 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. */ +export 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.ts b/packages/contracts/src/settings.ts index ab472b4108..eef0691846 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,20 @@ 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'; +export 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'>; + +export const SETTINGS_APP_NOT_CONSUMED_REASON = SETTINGS_REFUSAL_REASONS.appNotConsumed.reason; /** * The refusal a mutation answers with when its target consumes no app: the code, sentence, typed @@ -148,7 +161,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..0d16f52ad6 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. */ +export 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..c868ba67ae 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. + */ +export 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 c994f6b190..ec1f78dbbf 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. */ +export 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. */ @@ -391,7 +399,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..71f29815a7 100644 --- a/packages/daemon-contracts/src/daemon-stop.ts +++ b/packages/daemon-contracts/src/daemon-stop.ts @@ -1,6 +1,15 @@ -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: + * it signaled the process and the observation never came back the way the rule needs. + */ +const DAEMON_STOP_REASONS = { + // The process was signaled but stayed alive, so the stop cannot claim it ended. + exitUnconfirmed: { reason: 'daemon_exit_unconfirmed' }, +} as const satisfies ReasonTable<'daemon lifecycle'>; + import { DAEMON_LIFECYCLE_REASONS, embeddedCloseHint, @@ -142,7 +151,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/gestures/src/gesture-plan.ts b/packages/gestures/src/gesture-plan.ts index cce52a2cd8..cccf6a4079 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. */ +export 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 83e004840d..e34a9001f1 100644 --- a/packages/kernel/src/errors.ts +++ b/packages/kernel/src/errors.ts @@ -399,7 +399,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, @@ -414,6 +414,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..37f6bd9932 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. */ +export 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 d330c18674..f485f39ad1 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 { runCmd } from '@agent-device/host-kit/command'; import { runHarmonyShell } from './hdc.ts'; import { invalidateHarmonyGestureViewport } from './snapshot.ts'; @@ -202,10 +202,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. */ +export 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..1e4c2598b9 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. */ +export 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..f7006f4551 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). + */ +export 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..0799c8d1b6 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. */ +export 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..a870fa2e63 100644 --- a/packages/selectors/src/interaction-error.ts +++ b/packages/selectors/src/interaction-error.ts @@ -60,6 +60,28 @@ 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' }, + /** + * 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 part of a covered node a refusal reports. */ 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 030b59b874..647db0ee60 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -11,6 +11,14 @@ Treat a reason that this page does not list as unknown, not as an error in the r ## Commands +### `alert` + +| 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. | + ### `audit` | Reason | Meaning | @@ -23,6 +31,19 @@ Treat a reason that this page does not list as unknown, not as an error in the r | --- | --- | | `MACOS_APP_TERMINATION_TIMEOUT` | The macOS app was still running after every termination attempt. | +### `fill` + +| Reason | Meaning | +| --- | --- | +| `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. | + +### `find` + +| Reason | Meaning | +| --- | --- | +| `find_snapshot_unreadable` | The capture came back sparse, so no selector could be resolved against it. | + ### `fold` | Reason | Meaning | @@ -41,6 +62,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. | + ### `logs` | Reason | Meaning | @@ -51,10 +82,12 @@ 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. | | `ios-simulator-openurl-timeout` | CoreSimulator did not answer `simctl openurl` in time, so the URL open failed. | | `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. | ### `orientation` @@ -70,6 +103,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` | Frame extraction ran and failed, rather than returning fewer frames. | +| `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_destination_not_requested` | A remote recording was saved to the current directory because the request named no destination; a warning. | @@ -77,12 +121,18 @@ 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. | +| `maestro-test-failure` | A Maestro assertion or condition failed, so the replayed flow does not match the recording. | +| `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. | @@ -117,12 +167,15 @@ 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. | | `app-no-data-container` | `clear-app-state` was refused because the installed app owns no data container. | ### `snapshot` | 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. | @@ -143,6 +196,12 @@ Treat a reason that this page does not list as unknown, not as an error in the r These reasons can come from more than one command. +### 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. | + ### Apple app resolution | Reason | Meaning | @@ -162,10 +221,31 @@ These reasons can come from more than one command. | `daemon-not-running` | An attaching client found no daemon to connect to. | | `daemon-incompatible` | The running daemon does not match the client; `details.daemon` and `details.client` hold both identities. | | `daemon-drain-timeout` | A daemon accepted the request to leave but was still running 60 s later and could not be retired. | +| `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_exit_unconfirmed` | The process was signaled but stayed alive, so the stop cannot claim it ended. | +| `repair_evidence_invalid` | The repair tombstone file exists but does not parse into a valid marker. | + +### 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. | + +### 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 @@ -176,6 +256,13 @@ These reasons can come from more than one command. | `panel-table-unreadable` | The foldable's lit panel could not be named from its panel table, so nothing was sent. | | `panel-probe-budget-exhausted` | Reading the panel table spent the request's time budget, so nothing was sent. | +### Image decoding + +| Reason | Meaning | +| --- | --- | +| `png_decode_failed` | The bytes carry a PNG signature but the PNG decoder could not read them. | +| `jpeg_decode_failed` | The bytes carry a JPEG signature but the JPEG decoder could not read them. | + ### Interaction | Reason | Meaning | @@ -189,14 +276,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. | | `LEASE_ID_IN_USE` | The requested lease id already names a lease that this daemon issued. | | `LEASE_CAPACITY_EXCEEDED` | Every iOS simulator lease slot is taken; retry after another lease is released. | | `LEASE_SESSION_MISMATCH` | The lease scope of the request differs from the lease of its session; `details.field` names the field. | @@ -240,3 +339,21 @@ These reasons can come from more than one command. | `simulator-target-identity-unavailable` | The app's simulator process was found, but its identity could not be read. | | `simulator-runtime-probe-failed` | The simulator could not be asked for its runtime. | | `simulator-runtime-unavailable` | The simulator reported no runtime. | + +### 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. | From 50d8c3c73163fc1263067272e1f30330205a6d8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 22:30:17 +0100 Subject: [PATCH 02/13] refactor(reasons): declare find_snapshot_unreadable in capture-kit, where both find paths load it The daemon find path (#4936) cannot import command-runtime, so the row lives in capture-kit/snapshot-quality-verdict.ts, byte-identical to #4936's declaration. Co-Authored-By: Claude Opus 5.5 --- packages/capture-kit/src/snapshot-quality-verdict.ts | 10 ++++++++++ .../interaction/runtime/selector-read-utils.ts | 9 ++------- .../commands/interaction/runtime/selector-read.test.ts | 3 ++- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/packages/capture-kit/src/snapshot-quality-verdict.ts b/packages/capture-kit/src/snapshot-quality-verdict.ts index 475d09009f..4a939931a6 100644 --- a/packages/capture-kit/src/snapshot-quality-verdict.ts +++ b/packages/capture-kit/src/snapshot-quality-verdict.ts @@ -1,3 +1,4 @@ +import type { ReasonTable } from '@agent-device/kernel/errors'; import type { SnapshotQualityState, SnapshotQualityVerdict } from '@agent-device/kernel/snapshot'; import { SNAPSHOT_QUALITY_BACKEND_CAPABILITIES } from './snapshot-quality-backend-capabilities.ts'; @@ -93,6 +94,15 @@ 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 = { + // The capture came back sparse, so no selector could be resolved against it. + snapshotUnreadable: { reason: 'find_snapshot_unreadable' }, +} as const satisfies ReasonTable<'find'>; + export function isSparseSnapshotQualityVerdict( verdict: SnapshotQualityVerdict | undefined, ): verdict is SnapshotQualityVerdict { 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 c8b0ebe32e..98367d25cf 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 @@ -3,17 +3,12 @@ import type { InteractionRefTarget, InteractionSelectorTarget, } from '@agent-device/contracts/interaction'; -import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; +import { AppError } from '@agent-device/kernel/errors'; +import { FIND_READ_REASONS } 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'; -/** Why `find` refuses a capture that cannot be read as the screen. */ -export 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'>; - function shouldScopeFind(locator: string): boolean { return locator === 'text' || locator === 'label' || locator === 'any'; } 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 bc7556db6f..d127ff590a 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 @@ -5,7 +5,8 @@ import { createLocalArtifactAdapter } from '@agent-device/host-kit/local-artifac import { createAgentDevice } from '../../../runtime.ts'; import { localCommandPolicy } from '@agent-device/contracts/command-policy'; import type { CommandSessionStore } from '@agent-device/contracts/runtime-contract'; -import { FIND_READ_REASONS, selector } from './selector-read-utils.ts'; +import { FIND_READ_REASONS } from '@agent-device/capture-kit/snapshot-quality-verdict'; +import { selector } from './selector-read-utils.ts'; import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures'; import { createFakeClock, From 6dab43ae68ce208a7234eca4bc57d48a0534f74e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 22:37:40 +0100 Subject: [PATCH 03/13] refactor(reasons): keep the 15 module-local reason tables private Nothing imports them; the reasons collector also reads tables that are not exported. Co-Authored-By: Claude Opus 5.5 --- packages/capture-kit/src/recording/video.ts | 2 +- packages/client/src/lease-client.ts | 2 +- packages/command-surface/src/interaction/interactions.ts | 2 +- packages/contracts/src/application-lifecycle-interaction.ts | 2 +- packages/contracts/src/screenshot-runtime.ts | 2 +- packages/contracts/src/settings.ts | 2 +- packages/contracts/src/snapshot-runtime.ts | 2 +- packages/daemon-contracts/src/daemon-registration-owner.ts | 2 +- packages/daemon-contracts/src/daemon-resolution.ts | 2 +- packages/gestures/src/gesture-plan.ts | 2 +- packages/maestro/src/internal/compatibility-errors.ts | 2 +- packages/platform-harmonyos/src/app-lifecycle.ts | 2 +- packages/platform-vega/src/tool-provider.ts | 2 +- packages/platform-web/src/provider.ts | 2 +- packages/replay-test/src/internal/session-test-runtime.ts | 2 +- 15 files changed, 15 insertions(+), 15 deletions(-) diff --git a/packages/capture-kit/src/recording/video.ts b/packages/capture-kit/src/recording/video.ts index 2705554fbb..677eb2fcea 100644 --- a/packages/capture-kit/src/recording/video.ts +++ b/packages/capture-kit/src/recording/video.ts @@ -15,7 +15,7 @@ import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { hasPlayableWebmStructure } from './video-webm.ts'; /** Why the MP4 playability validator cannot answer. */ -export const VIDEO_VALIDATOR_REFUSAL_REASONS = { +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. diff --git a/packages/client/src/lease-client.ts b/packages/client/src/lease-client.ts index 2e962281f5..3f8b3f8f84 100644 --- a/packages/client/src/lease-client.ts +++ b/packages/client/src/lease-client.ts @@ -78,7 +78,7 @@ function normalizeHumanControlHold(value: unknown): HumanControlHold { } /** Why this client refuses a daemon answer it cannot turn into a lease. */ -export const LEASE_CLIENT_REFUSAL_REASONS = { +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'>; diff --git a/packages/command-surface/src/interaction/interactions.ts b/packages/command-surface/src/interaction/interactions.ts index 69b7dfd5f1..e67e71af87 100644 --- a/packages/command-surface/src/interaction/interactions.ts +++ b/packages/command-surface/src/interaction/interactions.ts @@ -162,7 +162,7 @@ export const interactionDaemonWriters = { } satisfies Record; /** What `fill --text-stdin` refuses in the caller's arguments before it reads anything. */ -export const FILL_TEXT_STDIN_REFUSAL_REASONS = { +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. diff --git a/packages/contracts/src/application-lifecycle-interaction.ts b/packages/contracts/src/application-lifecycle-interaction.ts index 97b8a1c360..44777b790a 100644 --- a/packages/contracts/src/application-lifecycle-interaction.ts +++ b/packages/contracts/src/application-lifecycle-interaction.ts @@ -22,7 +22,7 @@ import type { } from './application-lifecycle-runtime.ts'; /** Why `open` refuses before it resolves an interactor for the chosen owner. */ -export const APPLICATION_LIFECYCLE_ADMISSION_REFUSAL_REASONS = { +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'>; diff --git a/packages/contracts/src/screenshot-runtime.ts b/packages/contracts/src/screenshot-runtime.ts index eb82bd1605..c92947c674 100644 --- a/packages/contracts/src/screenshot-runtime.ts +++ b/packages/contracts/src/screenshot-runtime.ts @@ -18,7 +18,7 @@ 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. */ -export const SCREENSHOT_CAPTURE_REFUSAL_REASONS = { +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. diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index eef0691846..f1ed448965 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -128,7 +128,7 @@ export function settingsAppScope( * 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_REFUSAL_REASONS = { +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 diff --git a/packages/contracts/src/snapshot-runtime.ts b/packages/contracts/src/snapshot-runtime.ts index 0d16f52ad6..f717af9c13 100644 --- a/packages/contracts/src/snapshot-runtime.ts +++ b/packages/contracts/src/snapshot-runtime.ts @@ -17,7 +17,7 @@ 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. */ -export const SNAPSHOT_RUNTIME_REFUSAL_REASONS = { +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'>; diff --git a/packages/daemon-contracts/src/daemon-registration-owner.ts b/packages/daemon-contracts/src/daemon-registration-owner.ts index c868ba67ae..92186a9431 100644 --- a/packages/daemon-contracts/src/daemon-registration-owner.ts +++ b/packages/daemon-contracts/src/daemon-registration-owner.ts @@ -65,7 +65,7 @@ import { DAEMON_PROGRESS_CHANNEL_ENV } from './daemon-startup-phases.ts'; * is a fail-closed answer: the state dir, the startup, or the admission gate does not resolve to a * lifetime this host started. */ -export const DAEMON_OWNERSHIP_REFUSAL_REASONS = { +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. diff --git a/packages/daemon-contracts/src/daemon-resolution.ts b/packages/daemon-contracts/src/daemon-resolution.ts index ec1f78dbbf..3bd5e55e66 100644 --- a/packages/daemon-contracts/src/daemon-resolution.ts +++ b/packages/daemon-contracts/src/daemon-resolution.ts @@ -91,7 +91,7 @@ const DAEMON_STATE_ROOT_REASONS = { } as const satisfies ReasonTable<'daemon lifecycle'>; /** Why this build refuses to send a request whose delivery the answering daemon cannot promise. */ -export const DAEMON_CAPABILITY_REFUSAL_REASONS = { +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'>; diff --git a/packages/gestures/src/gesture-plan.ts b/packages/gestures/src/gesture-plan.ts index cccf6a4079..65a15335b8 100644 --- a/packages/gestures/src/gesture-plan.ts +++ b/packages/gestures/src/gesture-plan.ts @@ -34,7 +34,7 @@ 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. */ -export const GESTURE_PLAN_REFUSAL_REASONS = { +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. diff --git a/packages/maestro/src/internal/compatibility-errors.ts b/packages/maestro/src/internal/compatibility-errors.ts index 37f6bd9932..3b5d889985 100644 --- a/packages/maestro/src/internal/compatibility-errors.ts +++ b/packages/maestro/src/internal/compatibility-errors.ts @@ -1,7 +1,7 @@ import { AppError, type AppErrorDetails, type ReasonTable } from '@agent-device/kernel/errors'; /** Why a Maestro-compatibility step ends its run. */ -export const MAESTRO_COMPATIBILITY_REASONS = { +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'>; diff --git a/packages/platform-harmonyos/src/app-lifecycle.ts b/packages/platform-harmonyos/src/app-lifecycle.ts index f485f39ad1..12280fd63b 100644 --- a/packages/platform-harmonyos/src/app-lifecycle.ts +++ b/packages/platform-harmonyos/src/app-lifecycle.ts @@ -203,7 +203,7 @@ function combineHarmonySignals( const HARMONY_ABILITY_NAME = /^[A-Za-z][A-Za-z0-9_.]*$/; /** Why a HarmonyOS app-open argument is refused before any device is touched. */ -export const HARMONY_LIFECYCLE_REFUSAL_REASONS = { +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'>; diff --git a/packages/platform-vega/src/tool-provider.ts b/packages/platform-vega/src/tool-provider.ts index 1e4c2598b9..dfbd121787 100644 --- a/packages/platform-vega/src/tool-provider.ts +++ b/packages/platform-vega/src/tool-provider.ts @@ -54,7 +54,7 @@ export function createLocalVegaCliAdapter(host: HostEnvironment): VegaCliAdapter * an ambient environment (#3794). */ /** Why this tool provider refuses when its CLI adapter was never bound to a host. */ -export const VEGA_TOOL_PROVIDER_REFUSAL_REASONS = { +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'>; diff --git a/packages/platform-web/src/provider.ts b/packages/platform-web/src/provider.ts index f7006f4551..dc05250d6f 100644 --- a/packages/platform-web/src/provider.ts +++ b/packages/platform-web/src/provider.ts @@ -7,7 +7,7 @@ import { AppError, type ReasonTable } from '@agent-device/kernel/errors'; * provider, which is a composition bug, so every capability answers closed instead of borrowing a * host it was never given (#3794). */ -export const WEB_PROVIDER_COMPOSITION_REFUSAL_REASONS = { +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'>; diff --git a/packages/replay-test/src/internal/session-test-runtime.ts b/packages/replay-test/src/internal/session-test-runtime.ts index 0799c8d1b6..3c9821c0bc 100644 --- a/packages/replay-test/src/internal/session-test-runtime.ts +++ b/packages/replay-test/src/internal/session-test-runtime.ts @@ -19,7 +19,7 @@ const REPLAY_TEST_TIMEOUT_HINT = 'Replay test timeouts are cooperative; the active command may take a short grace period to stop.'; /** Why a `replay --test` attempt ends as an infrastructure failure on the timeout path. */ -export const REPLAY_TEST_TIMEOUT_REASONS = { +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. From f79abeab2923353fe8674fcc18758c3f95e54c06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 22:41:16 +0100 Subject: [PATCH 04/13] refactor(reasons): drop the settings app-not-consumed alias Its only reader was a test, which now asserts the published spelling. Co-Authored-By: Claude Opus 5.5 --- packages/contracts/src/settings.test.ts | 3 +-- packages/contracts/src/settings.ts | 2 -- 2 files changed, 1 insertion(+), 4 deletions(-) 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 f1ed448965..c15cab4dda 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -138,8 +138,6 @@ const SETTINGS_REFUSAL_REASONS = { appNotConsumed: { reason: 'setting_app_not_consumed' }, } as const satisfies ReasonTable<'settings'>; -export const SETTINGS_APP_NOT_CONSUMED_REASON = SETTINGS_REFUSAL_REASONS.appNotConsumed.reason; - /** * The refusal a mutation answers with when its target consumes no app: the code, sentence, typed * details, and hint as data, so the daemon can answer with it through its own response builder From 95fd770457f78f435f2f4c73c933a51f31e1ff4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 23:09:17 +0100 Subject: [PATCH 05/13] docs(reasons): say a contact sheet could not obtain usable extracted frames Also drops the JSDoc lines that repeated each row's summary comment. Co-Authored-By: Claude Opus 5.5 --- .../capture-kit/src/recording/contact-sheet-report.ts | 9 +-------- website/docs/docs/error-reasons.md | 2 +- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts index d09fef1229..c11ab740cb 100644 --- a/packages/capture-kit/src/recording/contact-sheet-report.ts +++ b/packages/capture-kit/src/recording/contact-sheet-report.ts @@ -10,28 +10,21 @@ export const CONTACT_SHEET_REASONS = { /** Frame decoding is Apple AVFoundation tooling, so a host on another platform cannot build one. */ // 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. */ // The MP4 timeline could not be read, so no bounded sample grid can be planned. durationUnknown: { reason: 'contact_sheet_duration_unknown' }, - /** Frame extraction ran and failed, rather than returning fewer frames. */ - // Frame extraction ran and failed, rather than returning fewer frames. + // The contact sheet could not obtain usable extracted frames: the extractor failed to start or run. frameExtractionFailed: { reason: 'contact_sheet_frame_extraction_failed' }, - /** Extraction returned nothing usable, so there is no sheet to draw. */ // Extraction returned nothing usable, so there is no sheet to draw. noFrames: { reason: 'contact_sheet_no_frames' }, /** The requested sheet would exceed the caller's image pixel budget even at the smallest cell. */ // 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. */ // 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. */ // 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. */ // 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. */ // The change threshold is not a finite share between 0 and 1. thresholdInvalid: { reason: 'contact_sheet_threshold_invalid' }, } as const satisfies ReasonTable<'record'>; diff --git a/website/docs/docs/error-reasons.md b/website/docs/docs/error-reasons.md index 647db0ee60..b36b573cc2 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -105,7 +105,7 @@ Treat a reason that this page does not list as unknown, not as an error in the r | --- | --- | | `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` | Frame extraction ran and failed, rather than returning fewer frames. | +| `contact_sheet_frame_extraction_failed` | The contact sheet could not obtain usable extracted frames: the extractor failed to start or run. | | `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. | From 76c74b415b2519696d6e75f1bf92ede420972991 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 08:25:32 +0100 Subject: [PATCH 06/13] docs(reasons): cover over-budget frames in the contact-sheet extraction summary Co-Authored-By: Claude Opus 5.5 --- packages/capture-kit/src/recording/contact-sheet-report.ts | 4 +--- website/docs/docs/error-reasons.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/packages/capture-kit/src/recording/contact-sheet-report.ts b/packages/capture-kit/src/recording/contact-sheet-report.ts index c11ab740cb..77905a481b 100644 --- a/packages/capture-kit/src/recording/contact-sheet-report.ts +++ b/packages/capture-kit/src/recording/contact-sheet-report.ts @@ -7,16 +7,14 @@ import type { ReasonTable } from '@agent-device/kernel/errors'; * package; a caller branches on a reason instead of reading an error message. */ export const CONTACT_SHEET_REASONS = { - /** Frame decoding is Apple AVFoundation tooling, so a host on another platform cannot build one. */ // 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 or run. + // 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 requested sheet would exceed the caller's image pixel budget even at the smallest cell. */ // 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. diff --git a/website/docs/docs/error-reasons.md b/website/docs/docs/error-reasons.md index 49331d7f75..23605fb1ed 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -152,7 +152,7 @@ Treat a reason that this page does not list as unknown, not as an error in the r | --- | --- | | `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 or run. | +| `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. | From fbb7342799d3391060977a2a27e4c8afe71ac367 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 11:02:41 +0100 Subject: [PATCH 07/13] refactor(find): build the sparse-capture refusal once in capture-kit for both find routes Co-Authored-By: Claude Opus 5.5 --- .../capture-kit/src/snapshot-quality-verdict.ts | 15 ++++++++++++++- .../interaction/runtime/selector-read-utils.ts | 10 +++------- .../interaction/runtime/selector-read.test.ts | 3 +-- .../interaction/internal/__tests__/find.test.ts | 4 +++- .../interaction/internal/find-target-capture.ts | 7 +++---- 5 files changed, 24 insertions(+), 15 deletions(-) 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/command-runtime/src/commands/interaction/runtime/selector-read-utils.ts b/packages/command-runtime/src/commands/interaction/runtime/selector-read-utils.ts index 98367d25cf..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,7 +4,7 @@ import type { InteractionSelectorTarget, } from '@agent-device/contracts/interaction'; import { AppError } from '@agent-device/kernel/errors'; -import { FIND_READ_REASONS } from '@agent-device/capture-kit/snapshot-quality-verdict'; +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'; @@ -41,10 +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: 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 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 d127ff590a..09be668fd5 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 @@ -5,7 +5,6 @@ import { createLocalArtifactAdapter } from '@agent-device/host-kit/local-artifac import { createAgentDevice } from '../../../runtime.ts'; import { localCommandPolicy } from '@agent-device/contracts/command-policy'; import type { CommandSessionStore } from '@agent-device/contracts/runtime-contract'; -import { FIND_READ_REASONS } from '@agent-device/capture-kit/snapshot-quality-verdict'; import { selector } from './selector-read-utils.ts'; import { makeSnapshotState } from '@agent-device/selectors/snapshot-geometry-fixtures'; import { @@ -289,7 +288,7 @@ test('runtime find wait reports sparse snapshot verdicts on the selector-read ro assert.ok(error instanceof Error); assert.equal(error.message, 'find could not read the current accessibility tree'); const details = (error as { details?: Record }).details; - assert.equal(details?.reason, FIND_READ_REASONS.snapshotUnreadable.reason); + assert.equal(details?.reason, 'find_snapshot_unreadable'); assert.equal(details?.verdictReason, 'sparse tree'); assert.match(String(details?.hint ?? ''), /snapshot quality verdict is sparse/); return true; diff --git a/packages/daemon/src/execution/interaction/internal/__tests__/find.test.ts b/packages/daemon/src/execution/interaction/internal/__tests__/find.test.ts index 8b524a2a6c..844c41cf67 100644 --- a/packages/daemon/src/execution/interaction/internal/__tests__/find.test.ts +++ b/packages/daemon/src/execution/interaction/internal/__tests__/find.test.ts @@ -242,7 +242,9 @@ test('handleFindCommands click tries query-scoped full retry before failing spar code: 'COMMAND_FAILED', message: 'find could not read the current accessibility tree', details: { - reason: 'sparse tree', + reason: 'find_snapshot_unreadable', + verdictReason: 'sparse tree', + verdictReasonCode: 'sparse-tree', hint: expect.stringContaining('snapshot quality verdict is sparse'), }, }); 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 6e041fc64c..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,6 +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 { 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'; @@ -72,10 +73,8 @@ export function createFindTargetCapture( } export function sparseFindSnapshotResponse(verdict: SnapshotQualityVerdict): DaemonResponse { - return errorResponse('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 errorResponse('COMMAND_FAILED', refusal.message, refusal.details); } function shouldScopeFind(locator: FindLocator): boolean { From 79bd18b76c181b2633590bf457003ebbd10960be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 11:08:44 +0100 Subject: [PATCH 08/13] fix(replay): keep a sparse find refusal's scrubbed verdict in replay failure details Co-Authored-By: Claude Opus 5.5 --- ...on-replay-runtime-failure-response.test.ts | 29 +++++++++++++++++++ ...session-replay-runtime-failure-response.ts | 7 +++++ 2 files changed, 36 insertions(+) diff --git a/packages/replay-port/src/daemon-port/__tests__/session-replay-runtime-failure-response.test.ts b/packages/replay-port/src/daemon-port/__tests__/session-replay-runtime-failure-response.test.ts index f3a850b939..742e46d880 100644 --- a/packages/replay-port/src/daemon-port/__tests__/session-replay-runtime-failure-response.test.ts +++ b/packages/replay-port/src/daemon-port/__tests__/session-replay-runtime-failure-response.test.ts @@ -119,6 +119,35 @@ test('cleanup failed steps retain their type while replay variables are scrubbed expect(JSON.stringify(response)).not.toContain('secret-value'); }); +test('a sparse find refusal keeps its verdict while replay variables are scrubbed', () => { + const response = buildReplayDivergenceFailureResponseFromDescriptor({ + error: { + code: 'COMMAND_FAILED', + message: 'find could not read the current accessibility tree', + details: { + reason: 'find_snapshot_unreadable', + verdictReason: 'sparse tree near secret-value', + verdictReasonCode: 'sparse-tree', + }, + }, + actionLabel: 'find', + action: 'find', + positionals: ['label', 'Submit', 'click'], + step: 1, + replayPath: '/tmp/find.ad', + artifactPaths: [], + divergence: {}, + scrubVars: [{ name: 'SECRET', value: 'secret-value' }], + }); + if (response.ok) throw new Error('expected a failure response'); + expect(response.error.details).toMatchObject({ + reason: 'find_snapshot_unreadable', + verdictReason: 'sparse tree near ', + verdictReasonCode: 'sparse-tree', + }); + expect(JSON.stringify(response)).not.toContain('secret-value'); +}); + // #2997: the Android platform states `open --test-ime` because it sees one dispatched // session-open. On this surface that advice is unactionable — a flow caller never runs // `open` — so the cause's hint is replaced off the typed reason, never off the message. diff --git a/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts b/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts index f9a7f2744d..0670378829 100644 --- a/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts +++ b/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts @@ -153,6 +153,9 @@ const SAFE_CAUSE_DETAIL_KEYS = [ 'systemSurface', ] as const; +// Free text a cause may echo from the device, such as a sparse capture verdict, so it is scrubbed. +const SCRUBBED_CAUSE_DETAIL_KEYS = ['verdictReason', 'verdictReasonCode'] as const; + function pickSafeCauseDetails( details: Record | undefined, scrubVars: readonly ReplayVarScrubEntry[], @@ -162,6 +165,10 @@ function pickSafeCauseDetails( for (const key of SAFE_CAUSE_DETAIL_KEYS) { if (details[key] !== undefined) safe[key] = details[key]; } + for (const key of SCRUBBED_CAUSE_DETAIL_KEYS) { + const value = readStringDetail(details, key); + if (value !== undefined) safe[key] = scrubReplayVarValues(value, scrubVars); + } if ( details.reason === 'session_cleanup_incomplete' && Array.isArray(details.failedSteps) && From 5e458f17c3cc5a9758888c5ad6670ebf8bd9cc5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 11:13:15 +0100 Subject: [PATCH 09/13] refactor(replay): split the cause-detail projection to stay under the complexity limit Co-Authored-By: Claude Opus 5.5 --- ...session-replay-runtime-failure-response.ts | 37 +++++++++++-------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts b/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts index 0670378829..ce76120841 100644 --- a/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts +++ b/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts @@ -169,21 +169,26 @@ function pickSafeCauseDetails( const value = readStringDetail(details, key); if (value !== undefined) safe[key] = scrubReplayVarValues(value, scrubVars); } - if ( - details.reason === 'session_cleanup_incomplete' && - Array.isArray(details.failedSteps) && - details.failedSteps.every((step) => typeof step === 'string') - ) { - safe.failedSteps = details.failedSteps.map((step: string) => - scrubReplayVarValues(step, scrubVars), - ); - } - if (details.reason === BOUNDED_COMPOSITE_RESOURCE_UNSUPPORTED_REASON) { - if (details.dispatched === 'no') safe.dispatched = 'no'; - const shape = readStringDetail(details, 'shape'); - if (shape !== undefined) safe.shape = shape; - const commandName = readStringDetail(details, 'standaloneCommandName'); - if (commandName !== undefined) safe.standaloneCommandName = commandName; - } + return { ...safe, ...pickCleanupFailedSteps(details, scrubVars), ...pickBoundedRefusal(details) }; +} + +function pickCleanupFailedSteps( + details: Record, + scrubVars: readonly ReplayVarScrubEntry[], +): Record { + const steps = details.failedSteps; + if (details.reason !== 'session_cleanup_incomplete' || !Array.isArray(steps)) return {}; + if (!steps.every((step) => typeof step === 'string')) return {}; + return { failedSteps: steps.map((step: string) => scrubReplayVarValues(step, scrubVars)) }; +} + +function pickBoundedRefusal(details: Record): Record { + if (details.reason !== BOUNDED_COMPOSITE_RESOURCE_UNSUPPORTED_REASON) return {}; + const safe: Record = {}; + if (details.dispatched === 'no') safe.dispatched = 'no'; + const shape = readStringDetail(details, 'shape'); + if (shape !== undefined) safe.shape = shape; + const commandName = readStringDetail(details, 'standaloneCommandName'); + if (commandName !== undefined) safe.standaloneCommandName = commandName; return safe; } From b4c9bd64df1179b75b8f1473c8ddd864d8c3260c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 14:08:12 +0100 Subject: [PATCH 10/13] docs(reasons): daemon_exit_unconfirmed covers every unconfirmed stop, not only a surviving process Co-Authored-By: Claude Opus 5.5 --- packages/daemon-contracts/src/daemon-stop.ts | 5 +++-- website/docs/docs/error-reasons.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/daemon-contracts/src/daemon-stop.ts b/packages/daemon-contracts/src/daemon-stop.ts index 71f29815a7..d403e95e51 100644 --- a/packages/daemon-contracts/src/daemon-stop.ts +++ b/packages/daemon-contracts/src/daemon-stop.ts @@ -3,10 +3,11 @@ import type { DaemonRetirementResult } from './daemon-registration-owner.ts'; /** * Why `daemon stop` reports a retirement it could not prove. The owner is the retirement watchdog: - * it signaled the process and the observation never came back the way the rule needs. + * the observation never came back the way the rule needs. */ const DAEMON_STOP_REASONS = { - // The process was signaled but stayed alive, so the stop cannot claim it ended. + // 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'>; diff --git a/website/docs/docs/error-reasons.md b/website/docs/docs/error-reasons.md index fbfc0ed96d..ac11fd3242 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -493,7 +493,7 @@ These reasons can come from more than one command. | `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_exit_unconfirmed` | The process was signaled but stayed alive, so the stop cannot claim it ended. | +| `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-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. | From 7c0c244aab39abe5c150bf39884d003a620f948a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 15:04:35 +0100 Subject: [PATCH 11/13] docs(reasons): png_decode_failed covers any input that is not decodable PNG; assert the read-only find verdict code Co-Authored-By: Claude Opus 5.5 --- packages/capture-kit/src/png.ts | 2 +- .../src/commands/interaction/runtime/selector-read.test.ts | 1 + website/docs/docs/error-reasons.md | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/capture-kit/src/png.ts b/packages/capture-kit/src/png.ts index 997bc799b8..338c4ac116 100644 --- a/packages/capture-kit/src/png.ts +++ b/packages/capture-kit/src/png.ts @@ -9,7 +9,7 @@ export { PNG }; * `details.decoderError`. */ export const IMAGE_DECODE_REASONS = { - // The bytes carry a PNG signature but the PNG decoder could not read them. + // 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' }, 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 09be668fd5..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 @@ -290,6 +290,7 @@ test('runtime find wait reports sparse snapshot verdicts on the selector-read ro 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/website/docs/docs/error-reasons.md b/website/docs/docs/error-reasons.md index ac11fd3242..9f6df43fdb 100644 --- a/website/docs/docs/error-reasons.md +++ b/website/docs/docs/error-reasons.md @@ -570,7 +570,7 @@ These reasons can come from more than one command. | Reason | Meaning | | --- | --- | -| `png_decode_failed` | The bytes carry a PNG signature but the PNG decoder could not read them. | +| `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 From 4db8a3ae596ab5004cad7f784254f2fb57f3f784 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 16:13:07 +0100 Subject: [PATCH 12/13] refactor(replay): pass the sparse verdict code through unchanged, scrub only its prose Co-Authored-By: Claude Opus 5.5 --- .../src/daemon-port/session-replay-runtime-failure-response.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts b/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts index ce76120841..36ece9bdb2 100644 --- a/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts +++ b/packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts @@ -151,10 +151,11 @@ const SAFE_CAUSE_DETAIL_KEYS = [ 'snapshotQuality', 'supportedOn', 'systemSurface', + 'verdictReasonCode', ] as const; // Free text a cause may echo from the device, such as a sparse capture verdict, so it is scrubbed. -const SCRUBBED_CAUSE_DETAIL_KEYS = ['verdictReason', 'verdictReasonCode'] as const; +const SCRUBBED_CAUSE_DETAIL_KEYS = ['verdictReason'] as const; function pickSafeCauseDetails( details: Record | undefined, From 40b5ff12deea61d0ef44a7e5d4ef3365cf5cf700 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 18:19:06 +0100 Subject: [PATCH 13/13] fix(selectors): keep the off-screen reasons beside the module that publishes them interaction-offscreen.ts imported interaction-error.ts only to read two reason rows, which added a module to its eager closure and failed the closure budget. The rows now live in the module's own ReasonTable. Co-Authored-By: Claude Opus 5.5 --- packages/selectors/src/interaction-error.ts | 14 ----------- .../selectors/src/interaction-offscreen.ts | 24 +++++++++++++++---- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/packages/selectors/src/interaction-error.ts b/packages/selectors/src/interaction-error.ts index a870fa2e63..c49f762178 100644 --- a/packages/selectors/src/interaction-error.ts +++ b/packages/selectors/src/interaction-error.ts @@ -68,20 +68,6 @@ export const INTERACTION_ERROR_REASONS = { */ // Every tappable region of the target belongs to one of its interactive children. coveredByInteractiveDescendants: { reason: 'covered_by_interactive_descendants' }, - /** - * 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 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 3eabfe187a..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 { @@ -7,7 +7,23 @@ import { type OffscreenScrollDirection, } from '@agent-device/capture-kit/mobile-snapshot-semantics'; import type { InteractionAction } from './interaction-action.ts'; -import { INTERACTION_ERROR_REASONS } from './interaction-error.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 @@ -73,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: INTERACTION_ERROR_REASONS.offscreenSelector.reason, 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, @@ -91,7 +107,7 @@ export function offscreenRefFailure( ): Parameters[2] { return { message: `Ref ${refInput} is off-screen and not safe to ${action}`, - details: { reason: INTERACTION_ERROR_REASONS.offscreenRef.reason, 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