From e9ad4fac9fc11ad48fdb305a920d115ef8da407d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 09:39:21 +0100 Subject: [PATCH 1/2] fix(alert): derive the request envelope from an alert wait window The alert command's request envelope was the fixed 90s default, so a longer 'alert wait' window was cut off by the transport before its poll window ended. ALERT_TIMEOUT_POLICY now reads the action and the accepted window through the existing positional-parser budget: only 'wait' widens the envelope to window + margin; get, accept and dismiss keep the fixed envelope. A window above the armable ceiling (2147453647 ms, the client timer limit minus the request margin) is refused by the handler before anything runs with INVALID_ARGS, details.reason 'alert-wait-window-too-long' and details.maxWaitWindowMs, never clamped. Closes #4566 Co-authored-by: Apex --- .../src/descriptor-timeout-policies.ts | 38 ++++++++++ .../src/descriptors/device-operations.ts | 3 +- .../command-registry/src/timeout-policy.ts | 12 +++ packages/command-surface/src/capture/alert.ts | 2 +- packages/contracts/src/alert-contract.ts | 17 ++++- .../handlers/__tests__/snapshot-alert.test.ts | 76 +++++++++++++++++++ .../src/execution/handlers/snapshot-alert.ts | 18 +++-- .../command-descriptor-timeout-policy.test.ts | 65 +++++++++++++++- website/docs/docs/commands.md | 2 +- 9 files changed, 218 insertions(+), 15 deletions(-) diff --git a/packages/command-registry/src/descriptor-timeout-policies.ts b/packages/command-registry/src/descriptor-timeout-policies.ts index 897dc0d815..8b52a6748d 100644 --- a/packages/command-registry/src/descriptor-timeout-policies.ts +++ b/packages/command-registry/src/descriptor-timeout-policies.ts @@ -1,8 +1,10 @@ import { resolvePostActionObservationSupport } from './post-action-observation.ts'; +import { parseTimeout } from './parse-timeout.ts'; import { DEFAULT_TIMEOUT_POLICY, INSTALL_REQUEST_TIMEOUT_MS, LEASE_ALLOCATE_REQUEST_TIMEOUT_MS, + MAX_ARMABLE_ALERT_WAIT_WINDOW_MS, } from './timeout-policy.ts'; import type { CommandTimeoutPolicy } from './types.ts'; @@ -66,3 +68,39 @@ export function postActionObservationTimeoutPolicy( ? SETTLE_FLAG_PRESERVE_DAEMON_TIMEOUT_POLICY : withoutObservation; } + +/** The one `alert` subaction whose trailing number is a wait the command polls. */ +const ALERT_WAIT_ACTION = 'wait'; + +/** + * The `alert` budget travels as the second positional, and what it means depends on the + * subaction that comes first: + * + * - `alert wait ` is the window the leg polls, so the request envelope has to sit above it + * (#4566) — the same shape `wait`'s positional budget has. + * - `alert get ` is the Apple runner's read budget, which its owner clamps to 25 s (#4540), + * and `accept`/`dismiss` run their own retry window. Neither is a request budget, so neither + * widens anything: reading the trailing number without its subaction would turn every + * `alert get 120000` into a 150 s envelope the command never uses. + * + * A window past {@link MAX_ARMABLE_ALERT_WAIT_WINDOW_MS} resolves to no envelope rather than a + * shortened one: the alert handler refuses it with its own typed reason before it polls, so the + * caller never watches a wait end early. + */ +function resolveAlertWaitBudgetMs(positionals: string[]): number | null { + const action = positionals[0] ?? 'get'; + if (action.toLowerCase() !== ALERT_WAIT_ACTION) return null; + const windowMs = parseTimeout(positionals[1]); + if (windowMs === null || windowMs <= 0) return null; + return windowMs > MAX_ARMABLE_ALERT_WAIT_WINDOW_MS ? null : windowMs; +} + +/** + * `alert` keeps the default envelope for `get`, `accept` and `dismiss`, and widens it past the + * window only for `wait`. Timeout-on-timeout stays the default's daemon reset: a wait cut off by + * its envelope is the daemon's own `alert wait` answer, and the read legs never reach it. + */ +export const ALERT_TIMEOUT_POLICY: CommandTimeoutPolicy = { + ...DEFAULT_TIMEOUT_POLICY, + budget: { source: 'positional-parser', parser: resolveAlertWaitBudgetMs }, +}; diff --git a/packages/command-registry/src/descriptors/device-operations.ts b/packages/command-registry/src/descriptors/device-operations.ts index 9ef94461a1..40e7066781 100644 --- a/packages/command-registry/src/descriptors/device-operations.ts +++ b/packages/command-registry/src/descriptors/device-operations.ts @@ -22,6 +22,7 @@ import { type RawCommandDescriptor, } from '../descriptor-traits.ts'; import { + ALERT_TIMEOUT_POLICY, PRESERVE_DAEMON_TIMEOUT_POLICY, SETTLE_FLAG_PRESERVE_DAEMON_TIMEOUT_POLICY, postActionObservationTimeoutPolicy, @@ -115,7 +116,7 @@ export const DEVICE_OPERATION_COMMAND_DESCRIPTORS = { route: 'snapshot', refFrameEffect: alertRefFrameEffect, }, - timeoutPolicy: DEFAULT_TIMEOUT_POLICY, + timeoutPolicy: ALERT_TIMEOUT_POLICY, batchable: true, compositeResource: 'none', platformExecution: { kind: 'device-runtime', uses: alertRuntimePlanUses }, diff --git a/packages/command-registry/src/timeout-policy.ts b/packages/command-registry/src/timeout-policy.ts index e1aa395776..699f85695c 100644 --- a/packages/command-registry/src/timeout-policy.ts +++ b/packages/command-registry/src/timeout-policy.ts @@ -18,6 +18,18 @@ export const INSTALL_SOURCE_REQUEST_TIMEOUT_MS = 600_000; // envelope below the command's declared base. const REQUEST_TIMEOUT_BUDGET_MARGIN_MS = 30_000; +/** + * The longest `alert wait` window the request envelope can be armed for. + * + * The client arms its envelope with a timer whose delay ceiling is 2^31-1 ms; past it Node does not + * reject the value, it fires the timer after 1 ms. The envelope a wait window derives is that window + * plus the daemon-result margin, so the window has to leave room for the margin. A longer window is + * refused by the alert handler as `alert-wait-window-too-long` rather than accepted and then cut off + * or misfired. The contract's larger `MAX_ALERT_WINDOW_MS` is the ceiling one leg's own window signal + * stops accepting, which is not the same as what this command can honour end to end. + */ +export const MAX_ARMABLE_ALERT_WAIT_WINDOW_MS = 2_147_483_647 - REQUEST_TIMEOUT_BUDGET_MARGIN_MS; + /** Daemon-side runner budget for `prepare` without `--timeout` (`readPrepareIosRunnerTimeoutMs`). */ export const PREPARE_STARTUP_BUDGET_MS = 240_000; diff --git a/packages/command-surface/src/capture/alert.ts b/packages/command-surface/src/capture/alert.ts index 32767a6788..3603e7279a 100644 --- a/packages/command-surface/src/capture/alert.ts +++ b/packages/command-surface/src/capture/alert.ts @@ -21,7 +21,7 @@ import { AppError } from '@agent-device/kernel/errors'; const ALERT_COMMAND_NAME = 'alert'; const alertCommandDescription = - "Inspect, wait for, accept, or dismiss a platform alert. The get action reads alert content; accept and dismiss change the active alert state. Each iOS XCTest execution activates once, then only observes. Apple XCTest and Limrun iOS choose recognized English labels by preference (Allow While Using App before Allow Once); on iOS simulators, including Limrun, the runner also recognizes the device's preferred languages' wording of those labels from the OS permission-prompt strings, on any alert; equal-ranked choices and unknown labels refuse, including a lone unknown button. Open, Done, and Confirm… accept; Keep Browsing, Deny, and Skip dismiss. On the Apple XCUITest runner, dismiss taps only a recognized decline label (Cancel, Don't Allow, Ask App Not to Track, and similar) or the close element of a popover whose accessibility marker reads exactly \"dismiss popup\"; when no button fits the action, accept and dismiss answer ALERT_BUTTON_NOT_FOUND having tapped nothing. The get action exposes labels for explicit button targeting. On the Apple XCUITest runner, get takes the timeout argument as the runner's budget (10 s by default, at least 1.5 s, at most 25 s). A get the runner's watchdog (the same budget) cuts off answers runner_main_thread_timeout with dispatched: unknown, which does not mean no alert; the next get waits out RUNNER_BUSY while abandoned work drains, and still answers RUNNER_BUSY (dispatched: no) if that outlasts the bounded resends. A get result with status none reports no alert. An alert-not-found refusal means no alert was found and no button was pressed. An alert-wait-timeout means no actionable alert resolved within the wait window. A refusal with dispatched: no means no button was activated. After a press, an unconfirmed outcome leaves the resulting alert state unknown."; + "Inspect, wait for, accept, or dismiss a platform alert. The get action reads alert content; accept and dismiss change the active alert state. Each iOS XCTest execution activates once, then only observes. Apple XCTest and Limrun iOS choose recognized English labels by preference (Allow While Using App before Allow Once); on iOS simulators, including Limrun, the runner also recognizes the device's preferred languages' wording of those labels from the OS permission-prompt strings, on any alert; equal-ranked choices and unknown labels refuse, including a lone unknown button. Open, Done, and Confirm… accept; Keep Browsing, Deny, and Skip dismiss. On the Apple XCUITest runner, dismiss taps only a recognized decline label (Cancel, Don't Allow, Ask App Not to Track, and similar) or the close element of a popover whose accessibility marker reads exactly \"dismiss popup\"; when no button fits the action, accept and dismiss answer ALERT_BUTTON_NOT_FOUND having tapped nothing. The get action exposes labels for explicit button targeting. The timeout argument is the poll window only for wait: a wait polls its whole window, accepted up to 2147453647 ms, and a longer one is refused before anything runs with reason alert-wait-window-too-long and details.maxWaitWindowMs, never shortened. get takes the same argument as the runner's read budget (10 s by default, at least 1.5 s, at most 25 s), and accept and dismiss run their own retry window and ignore it. A get the runner's watchdog (the same budget) cuts off answers runner_main_thread_timeout with dispatched: unknown, which does not mean no alert; the next get waits out RUNNER_BUSY while abandoned work drains, and still answers RUNNER_BUSY (dispatched: no) if that outlasts the bounded resends. A get result with status none reports no alert. An alert-not-found refusal means no alert was found and no button was pressed. An alert-wait-timeout means no actionable alert resolved within the wait window. A refusal with dispatched: no means no button was activated. After a press, an unconfirmed outcome leaves the resulting alert state unknown."; const alertCommandMetadata = defineFieldCommandMetadata( ALERT_COMMAND_NAME, diff --git a/packages/contracts/src/alert-contract.ts b/packages/contracts/src/alert-contract.ts index 5bac9263d8..e1998b4c11 100644 --- a/packages/contracts/src/alert-contract.ts +++ b/packages/contracts/src/alert-contract.ts @@ -23,12 +23,23 @@ export const ALERT_ACTION_RETRY_MS = 2_000; /** * The largest alert budget the legs accept. The window signal rides `AbortSignal.timeout`, whose * Node ceiling is 2^31-1 ms: larger values are rejected outright there, and its underlying timer - * overflows to a 1 ms firing when merely exceeded. The daemon refuses a larger `alert wait` - * budget as `INVALID_ARGS`, and a tree driver reads one as the bounded default — never a - * silently shortened window. + * overflows to a 1 ms firing when merely exceeded. A tree driver reads one as the bounded default — + * never a silently shortened window. The `alert` command admits a shorter maximum: what it can + * honour end to end is bounded by the request envelope its caller arms for the wait, so + * `MAX_ARMABLE_ALERT_WAIT_WINDOW_MS` is the value a caller can rely on and this is the leg's own + * last line for budgets that arrive by other routes. */ export const MAX_ALERT_WINDOW_MS = 2_147_483_647; +/** + * `alert wait` was given a window longer than the command can honour. The request envelope is a + * timer too, and it is armed above the window with the daemon-result margin, so past that ceiling + * the wait would be cut off mid-window or misfire at 1 ms. The command refuses the window before + * anything runs, with `details.maxWaitWindowMs` naming what it will accept; it never shortens the + * window the caller asked for. + */ +export const ALERT_WAIT_WINDOW_TOO_LONG_REASON = 'alert-wait-window-too-long'; + /** * The one alert failure the family retries on: the backend looked and there was no alert *yet*. * Both Apple backends state it in typed form — the XCTest runner as this `ErrorPayload.code` diff --git a/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts b/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts index 58e00cf468..752e355980 100644 --- a/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts +++ b/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts @@ -1,5 +1,12 @@ import { test, expect, vi, beforeEach } from 'vitest'; import { AppError } from '@agent-device/kernel/errors'; +import { + ALERT_RUNNER_MAX_BUDGET_MS, + ALERT_WAIT_WINDOW_TOO_LONG_REASON, + DEFAULT_ALERT_TIMEOUT_MS, + MAX_ALERT_WINDOW_MS, +} from '@agent-device/contracts/alert-contract'; +import { MAX_ARMABLE_ALERT_WAIT_WINDOW_MS } from '@agent-device/command-registry/timeout-policy'; import type { SessionState } from '../../../core/session-state.ts'; import { SessionStore } from '../../../core/session-store.ts'; import { handleSnapshotCommands as handleProductionSnapshotCommands } from '../../../sessions/handlers/snapshot.ts'; @@ -201,3 +208,72 @@ test('alert wait refuses a budget past the window ceiling instead of arming a mi ).rejects.toThrow(/exceeds the maximum/); expect(mockRunnerCommand).not.toHaveBeenCalled(); }); + +// #4566: the envelope the client arms for a wait is a timer as well, armed above the window with +// the daemon-result margin. So the wait ceiling the command honours is the armable window, and a +// window above it is refused up front with the typed reason rather than polled and then cut off. +test('alert wait refuses a window the request envelope cannot be armed for, naming what it accepts', async () => { + const sessionStore = makeSessionStore(); + const sessionName = 'ios-sim'; + sessionStore.publish(sessionName, makeSession(sessionName)); + + const refusal = await handleSnapshotCommands(sessionName, sessionStore, [ + 'wait', + String(MAX_ARMABLE_ALERT_WAIT_WINDOW_MS + 1), + ]).catch((error: unknown) => error); + expect(refusal).toBeInstanceOf(AppError); + expect((refusal as AppError).code).toBe('INVALID_ARGS'); + expect((refusal as AppError).details?.reason).toBe(ALERT_WAIT_WINDOW_TOO_LONG_REASON); + expect((refusal as AppError).details?.maxWaitWindowMs).toBe(MAX_ARMABLE_ALERT_WAIT_WINDOW_MS); + // The contract's own larger ceiling is refused for the same typed reason: the command never + // accepts a window it cannot honour and shortens it on the way down. + await expect( + handleSnapshotCommands(sessionName, sessionStore, ['wait', String(MAX_ALERT_WINDOW_MS)]), + ).rejects.toThrow(/exceeds the maximum/); + expect(mockRunnerCommand).not.toHaveBeenCalled(); + + // The largest window the command does honour reaches the leg as the caller's own window, and an + // `alert get` keeps spending its own bounded read budget whatever the number says (#4540). + mockRunnerCommand.mockResolvedValueOnce({ status: 'visible' }); + const waited = await handleSnapshotCommands(sessionName, sessionStore, [ + 'wait', + String(MAX_ARMABLE_ALERT_WAIT_WINDOW_MS), + ]); + expect(waited?.ok).toBe(true); + expect(mockRunnerCommand.mock.calls.at(-1)?.[1]).toMatchObject({ + command: 'alert', + action: 'get', + // One runner attempt is capped at the runner's own alert budget, whatever the window says. + timeoutMs: ALERT_RUNNER_MAX_BUDGET_MS, + }); +}); + +test('an alert wait window inside the ceiling reaches the polling leg while the other legs keep their own budgets', async () => { + const sessionStore = makeSessionStore(); + const sessionName = 'ios-sim'; + sessionStore.publish(sessionName, makeSession(sessionName)); + mockRunnerCommand.mockResolvedValue({ accepted: true, dismissed: true, status: 'visible' }); + + // `wait` enters the polling leg, whose first attempt takes the runner's capped budget — the + // window is the poll's extent, not one attempt's budget (#4540). + await handleSnapshotCommands(sessionName, sessionStore, ['wait', '120000']); + expect(mockRunnerCommand.mock.calls.at(-1)?.[1]).toMatchObject({ + command: 'alert', + action: 'get', + timeoutMs: ALERT_RUNNER_MAX_BUDGET_MS, + }); + // `get` still spends its own clamped read budget, unchanged by the envelope it now travels under. + await handleSnapshotCommands(sessionName, sessionStore, ['get', '120000']); + expect(mockRunnerCommand.mock.calls.at(-1)?.[1]).toMatchObject({ + command: 'alert', + action: 'get', + timeoutMs: ALERT_RUNNER_MAX_BUDGET_MS, + }); + // `accept` ignores the number and runs its own action budget, as `dismiss` does. + await handleSnapshotCommands(sessionName, sessionStore, ['accept', '120000']); + expect(mockRunnerCommand.mock.calls.at(-1)?.[1]).toMatchObject({ + command: 'alert', + action: 'accept', + timeoutMs: DEFAULT_ALERT_TIMEOUT_MS, + }); +}); diff --git a/packages/daemon/src/execution/handlers/snapshot-alert.ts b/packages/daemon/src/execution/handlers/snapshot-alert.ts index 78901d1e76..e52e7fce33 100644 --- a/packages/daemon/src/execution/handlers/snapshot-alert.ts +++ b/packages/daemon/src/execution/handlers/snapshot-alert.ts @@ -5,7 +5,7 @@ import { parseAlertAction, type AlertAction, DEFAULT_ALERT_TIMEOUT_MS as DEFAULT_TIMEOUT_MS, - MAX_ALERT_WINDOW_MS, + ALERT_WAIT_WINDOW_TOO_LONG_REASON, } from '@agent-device/contracts/alert-contract'; import { AppError } from '@agent-device/kernel/errors'; import { @@ -21,6 +21,7 @@ import type { SessionRef, SessionState } from '../../core/session-state.ts'; import { SessionStore } from '../../core/session-store.ts'; import { recordSessionAction } from '../../core/session-action-recorder.ts'; import { parseTimeout } from '@agent-device/command-registry/parse-timeout'; +import { MAX_ARMABLE_ALERT_WAIT_WINDOW_MS } from '@agent-device/command-registry/timeout-policy'; import { resolveRefFrameEffect } from '../../core/daemon-command-registry.ts'; import { expireRefFrame } from '../../core/ref-frame.ts'; import type { @@ -164,17 +165,22 @@ function readAlertAction(raw: string | undefined): AlertAction { /** * The `alert` timeout before it reaches any leg: the window `alert wait` polls in, and the budget - * one `alert get` read spends. Past the contract's window ceiling a wait cannot be armed as a timer - * at all, so the command refuses the argument instead of starting a wait that would misfire; the driver's own default remains the last line for + * one `alert get` read spends. Past the window the request envelope can be armed for, a wait cannot + * be armed as a timer at all, so the command refuses the argument instead of starting a wait that + * would misfire or be cut off mid-window; the driver's own default remains the last line for * budgets that arrive by other routes. */ function alertTimeoutMs(action: AlertAction, rawTimeout: string | undefined): number { const timeoutMs = parseTimeout(rawTimeout) ?? DEFAULT_TIMEOUT_MS; - if (action === 'wait' && timeoutMs > MAX_ALERT_WINDOW_MS) { + if (action === 'wait' && timeoutMs > MAX_ARMABLE_ALERT_WAIT_WINDOW_MS) { throw new AppError( 'INVALID_ARGS', - `alert wait timeoutMs exceeds the maximum of ${MAX_ALERT_WINDOW_MS} ms`, - { hint: 'Pass a shorter timeout, or run repeated alert waits.' }, + `alert wait timeoutMs exceeds the maximum of ${MAX_ARMABLE_ALERT_WAIT_WINDOW_MS} ms`, + { + hint: 'Pass a shorter timeout, or run repeated alert waits.', + reason: ALERT_WAIT_WINDOW_TOO_LONG_REASON, + maxWaitWindowMs: MAX_ARMABLE_ALERT_WAIT_WINDOW_MS, + }, ); } return timeoutMs; diff --git a/src/__tests__/command-descriptor-timeout-policy.test.ts b/src/__tests__/command-descriptor-timeout-policy.test.ts index 8cb1de36a1..e71f11fb40 100644 --- a/src/__tests__/command-descriptor-timeout-policy.test.ts +++ b/src/__tests__/command-descriptor-timeout-policy.test.ts @@ -6,10 +6,15 @@ import { resolveCommandPostActionObservationSupport, resolveCommandTimeoutPolicy, } from '@agent-device/command-registry/registry'; -import { ALERT_RUNNER_MAX_BUDGET_MS } from '@agent-device/contracts/alert-contract'; +import { + ALERT_RUNNER_MAX_BUDGET_MS, + MAX_ALERT_WINDOW_MS, +} from '@agent-device/contracts/alert-contract'; import { OVERLAY_BUDGET_MS } from '@agent-device/capture-kit/recording-overlay'; import { DEFAULT_TIMEOUT_POLICY, + MAX_ARMABLE_ALERT_WAIT_WINDOW_MS, + resolveCommandDaemonBudgetMs, resolveCommandRequestTimeoutMs, } from '@agent-device/command-registry/timeout-policy'; @@ -124,8 +129,9 @@ test('budget sources deviating from the default are bounded, reviewed sets', () // --timeout bounds the --settle wait on these commands (#1101); like wait's // positional budget it only ever widens the envelope, never shrinks it. assert.deepEqual(flagWidenBudget.sort(), settleObservationCommandNames()); - // wait's budget travels as a positional and must widen the envelope. - assert.deepEqual(positionalBudget, ['wait']); + // wait's budget travels as a positional and must widen the envelope. So does + // alert's, but only for its `wait` subaction (#4566). + assert.deepEqual(positionalBudget.sort(), ['alert', 'wait']); }); test('request envelopes deviating from the default are bounded, reviewed sets', () => { @@ -416,3 +422,56 @@ test('the fixed alert request envelope stays above the largest runner alert budg const envelopeMs = resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('alert'), {}); assert.ok(envelopeMs !== undefined && envelopeMs > ALERT_RUNNER_MAX_BUDGET_MS); }); + +// #4566: `alert wait` polls the window its caller passed, so the request envelope has to sit above +// that window. The parser is action-aware: the same trailing number on `alert get` is the runner's +// read budget (#4540) and on `accept`/`dismiss` it is the retry window, and those keep the fixed +// envelope. A window the runtime cannot arm as a timer is classified as unhonorable, so no +// envelope is derived from it and the command refuses it before it polls anything. +test('alert wait widens the request envelope past its window while every other alert leg keeps the fixed one', () => { + const request = (positionals: string[]) => + resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('alert'), { + positionals, + flags: {}, + }); + + // A window past the fixed envelope extends it by the window plus the daemon-result margin. + assert.equal(request(['wait', '120000']), 150_000); + // The documented accepted ceiling keeps a plain timer: the envelope it derives is the Node + // timer ceiling exactly, never a value past it that would fire after 1 ms instead. + assert.equal(request(['wait', String(MAX_ARMABLE_ALERT_WAIT_WINDOW_MS)]), 2_147_483_647); + // A window inside the fixed envelope never shrinks it. + assert.equal(request(['wait', '5000']), 90_000); + // `alert wait` without a window takes the command's default, which sits inside the envelope. + assert.equal(request(['wait']), 90_000); + // A window the client cannot honour widens nothing: the daemon refuses it up front. + assert.equal(request(['wait', String(MAX_ARMABLE_ALERT_WAIT_WINDOW_MS + 1)]), 90_000); + assert.equal(request(['wait', String(MAX_ALERT_WINDOW_MS)]), 90_000); + // Only the wait leg widens. `alert get`'s number is the runner's read budget, capped at 25 s by + // the owner, and accept/dismiss run their own retry window; both keep the fixed envelope. + assert.equal(request(['get', '120000']), 90_000); + assert.equal(request(['accept', '120000']), 90_000); + assert.equal(request(['dismiss', '120000']), 90_000); + // The bare command and an absent action read as `get`, so its number never widens the envelope. + assert.equal(request([]), 90_000); + assert.equal(request(['get']), 90_000); + // The subaction is read the way the daemon reads it: case-insensitively. + assert.equal(request(['WAIT', '120000']), 150_000); + // A missing or malformed window is not a budget: the legs' own default answers for it. + assert.equal(request(['wait', 'abc']), 90_000); + assert.equal(request(['wait', '0']), 90_000); + assert.equal(request(['wait', '-1000']), 90_000); +}); + +test('the alert wait result deadline the daemon admits tracks the accepted window', () => { + // The daemon keeps the envelope's result margin, so a wait's own deadline must stay inside the + // window it polls — otherwise the request is cut off mid-wait, which is the bug. + const resultDeadline = (positionals: string[]) => + resolveCommandDaemonBudgetMs(resolveCommandTimeoutPolicy('alert'), { + positionals, + flags: {}, + }); + assert.equal(resultDeadline(['wait', '120000']), 120_000); + assert.equal(resultDeadline(['get', '120000']), 60_000); + assert.equal(resultDeadline([]), 60_000); +}); diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 50ee9cdbd3..1b2e060e64 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -451,7 +451,7 @@ agent-device alert dismiss - `wait_stable_timeout`: the UI did not settle. - Branch on `readableCaptures`, `waitedMs`, `matches`, and `firstMatch` instead of parsing error text. `firstMatch` carries identity and text only; absence failures make no visibility or rect claim. - Polling wait timeouts, and a replayed wait refused with `wait_landmark_identity_mismatch`, also carry `captures`, `readableCaptures`, and `polls` so you can see where the budget went. Each poll has `startedMs`, `durationMs`, and an `outcome`: `readable`, `unreadable`, `retriable`, `deadline`, `runner-restart`, or `readiness`. Long waits keep the first 5 and last 25 polls. A wait that never saw a readable capture reports the error its polls hit, with that error's code and retry details, instead of a generic timeout; `wait stable` and a never-readable strict absence keep their own diagnostics. `logPath` links the full request log. -- `alert` (same as `alert get`) inspects or handles system alerts on iOS simulator, macOS desktop, and Android permission dialogs. On iOS it also covers app-owned modal popups with native blocking markers. On the Apple XCUITest runner it also covers Safari's own page prompts, such as "Open this page in …?". The `[timeout]` argument applies to `alert wait` on every backend: `alert wait ` takes a budget up to 2147483647 ms (~24.8 days), larger is refused as `INVALID_ARGS` before anything runs. On the Apple XCUITest runner, `alert get ` also takes it as the runner's budget for the read, clamped to 1500–25000 ms and 10000 ms without an argument; a longer `alert wait` polls in runner attempts of at most 25 s. Other backends' `get`, and every backend's `accept` and `dismiss`, run their own fixed budgets and ignore it. For `alert`, the runner's main-thread watchdog is that same budget. An `alert get` it cuts off reports `reason: runner_main_thread_timeout` with `dispatched: unknown`: it does not mean there is no alert, which is `alert-not-found`. The next `alert get` waits out the runner's `RUNNER_BUSY` refusal while the abandoned work drains, then runs; the resends are bounded, so if the work has not drained by then it still returns `RUNNER_BUSY` (`dispatched: no`) and you retry. +- `alert` (same as `alert get`) inspects or handles system alerts on iOS simulator, macOS desktop, and Android permission dialogs. On iOS it also covers app-owned modal popups with native blocking markers. On the Apple XCUITest runner it also covers Safari's own page prompts, such as "Open this page in …?". The `[timeout]` argument is the wait window of `alert wait` on every backend: it polls its whole window, accepted up to 2147453647 ms (~24.8 days); a longer window is refused as `INVALID_ARGS` before anything runs, never shortened. On the Apple XCUITest runner, `alert get ` also takes it as the runner's budget for the read, clamped to 1500–25000 ms and 10000 ms without an argument; a longer `alert wait` polls in runner attempts of at most 25 s. Other backends' `get`, and every backend's `accept` and `dismiss`, run their own fixed budgets and ignore it. For `alert`, the runner's main-thread watchdog is that same budget. An `alert get` it cuts off reports `reason: runner_main_thread_timeout` with `dispatched: unknown`: it does not mean there is no alert, which is `alert-not-found`. The next `alert get` waits out the runner's `RUNNER_BUSY` refusal while the abandoned work drains, then runs; the resends are bounded, so if the work has not drained by then it still returns `RUNNER_BUSY` (`dispatched: no`) and you retry. - On the snapshot-derived Android backends `alert get --json` answers with a typed `status`: `visible`, `none`, or `undecided` (an alert-shaped capture that resolves to no single alert). Branch on `status`, not on the message. - On those backends, `alert accept` presses the lasting grant when a permission sheet offers several: Android orders its grants by the platform's own ids (full-access "Allow all", then foreground-only, then always, then the picker-limited "Select photos and videos", then one-time) whatever the button language — this is what makes the Android 14+ partial-media sheet answer "Allow all" — and elsewhere the English label table decides ("while using the app" over "only this time"). Android acts only on the grant ids it declares with a role and a rank; a sheet carrying an allow- or deny-shaped grant id it does not declare (a vendor fork's own button, or a newer Android grant) is refused for both `accept` and `dismiss` — `dismiss` answers with the Back key, the cancel that grants nothing. A sheet whose choices no rank orders — or that names the same choice at two points — is refused with `alert_button_undecided` and `dispatched: no`, never pressed by position; read the labels with `alert get` and press your choice by label/ref. - On those backends, when `alert accept`/`dismiss` fails before pressing anything, `error.details.reason` names why (a capture or transport failure that is not a driver refusal may instead surface as its own error without a `reason`). A budget never cancels a running capture or press: it only ends the polling loop, so every check that started inside the budget finishes and counts. Before any press, `dispatched: no` and the reason is `alert-not-found` (the action budget ended with no alert on screen), `alert_capture_undecided`, or `alert_button_undecided` (the sheet is too ambiguous to act on). After a press, `dispatched` is absent and the reason is `alert-window-expired`; “did not dismiss the visible alert” means the latest post-press capture that answered named the same dialog again, “could not be confirmed” means the press went out but the latest read was unresolvable or never answered, so the dialog may already be gone. If you cancel the request at any point from the press onward — the tap in flight, or the post-press checks — the cancellation reports `dispatched: unknown`: the device may already have received the tap. The one exception is a cancel whose post-press check nevertheless finished and proved the alert gone; then the command reports the handled alert, because the outcome is known. Run `alert get` before acting again. From 4a808cd54215c1b9eb72ec9e6b511bd0aac23f89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Mon, 16 Nov 2026 09:56:06 +0100 Subject: [PATCH 2/2] fix(alert): address timeout policy review findings --- packages/command-surface/src/capture/alert.ts | 2 +- .../execution/handlers/__tests__/snapshot-alert.test.ts | 8 +++++++- website/docs/docs/commands.md | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/command-surface/src/capture/alert.ts b/packages/command-surface/src/capture/alert.ts index 3603e7279a..c72dae3da7 100644 --- a/packages/command-surface/src/capture/alert.ts +++ b/packages/command-surface/src/capture/alert.ts @@ -21,7 +21,7 @@ import { AppError } from '@agent-device/kernel/errors'; const ALERT_COMMAND_NAME = 'alert'; const alertCommandDescription = - "Inspect, wait for, accept, or dismiss a platform alert. The get action reads alert content; accept and dismiss change the active alert state. Each iOS XCTest execution activates once, then only observes. Apple XCTest and Limrun iOS choose recognized English labels by preference (Allow While Using App before Allow Once); on iOS simulators, including Limrun, the runner also recognizes the device's preferred languages' wording of those labels from the OS permission-prompt strings, on any alert; equal-ranked choices and unknown labels refuse, including a lone unknown button. Open, Done, and Confirm… accept; Keep Browsing, Deny, and Skip dismiss. On the Apple XCUITest runner, dismiss taps only a recognized decline label (Cancel, Don't Allow, Ask App Not to Track, and similar) or the close element of a popover whose accessibility marker reads exactly \"dismiss popup\"; when no button fits the action, accept and dismiss answer ALERT_BUTTON_NOT_FOUND having tapped nothing. The get action exposes labels for explicit button targeting. The timeout argument is the poll window only for wait: a wait polls its whole window, accepted up to 2147453647 ms, and a longer one is refused before anything runs with reason alert-wait-window-too-long and details.maxWaitWindowMs, never shortened. get takes the same argument as the runner's read budget (10 s by default, at least 1.5 s, at most 25 s), and accept and dismiss run their own retry window and ignore it. A get the runner's watchdog (the same budget) cuts off answers runner_main_thread_timeout with dispatched: unknown, which does not mean no alert; the next get waits out RUNNER_BUSY while abandoned work drains, and still answers RUNNER_BUSY (dispatched: no) if that outlasts the bounded resends. A get result with status none reports no alert. An alert-not-found refusal means no alert was found and no button was pressed. An alert-wait-timeout means no actionable alert resolved within the wait window. A refusal with dispatched: no means no button was activated. After a press, an unconfirmed outcome leaves the resulting alert state unknown."; + "Inspect, wait for, accept, or dismiss a platform alert. The get action reads alert content; accept and dismiss change the active alert state. Each iOS XCTest execution activates once, then only observes. Apple XCTest and Limrun iOS choose recognized English labels by preference (Allow While Using App before Allow Once); on iOS simulators, including Limrun, the runner also recognizes the device's preferred languages' wording of those labels from the OS permission-prompt strings, on any alert; equal-ranked choices and unknown labels refuse, including a lone unknown button. Open, Done, and Confirm… accept; Keep Browsing, Deny, and Skip dismiss. On the Apple XCUITest runner, dismiss taps only a recognized decline label (Cancel, Don't Allow, Ask App Not to Track, and similar) or the close element of a popover whose accessibility marker reads exactly \"dismiss popup\"; when no button fits the action, accept and dismiss answer ALERT_BUTTON_NOT_FOUND having tapped nothing. The get action exposes labels for explicit button targeting. The timeout argument is the poll window only for wait: a wait polls its whole window, accepted up to 2147453647 ms, and a longer one is refused before anything runs with details.reason: alert-wait-window-too-long and details.maxWaitWindowMs, never shortened. On the Apple XCUITest runner, get takes the same argument as the runner's read budget (10 s by default, at least 1.5 s, at most 25 s); other backends' get ignores it. For wait, the first XCTest read uses the requested window capped at 25 s; later reads use the remaining window with the same cap, without the 1.5 s floor. Every backend's accept and dismiss run their own retry window and ignore the argument. A get the runner's watchdog (the same budget) cuts off answers runner_main_thread_timeout with dispatched: unknown, which does not mean no alert; the next get waits out RUNNER_BUSY while abandoned work drains, and still answers RUNNER_BUSY (dispatched: no) if that outlasts the bounded resends. A get result with status none reports no alert. An alert-not-found refusal means no alert was found and no button was pressed. An alert-wait-timeout means no actionable alert resolved within the wait window. A refusal with dispatched: no means no button was activated. After a press, an unconfirmed outcome leaves the resulting alert state unknown."; const alertCommandMetadata = defineFieldCommandMetadata( ALERT_COMMAND_NAME, diff --git a/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts b/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts index 752e355980..c6fa79da33 100644 --- a/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts +++ b/packages/daemon/src/execution/handlers/__tests__/snapshot-alert.test.ts @@ -229,7 +229,13 @@ test('alert wait refuses a window the request envelope cannot be armed for, nami // accepts a window it cannot honour and shortens it on the way down. await expect( handleSnapshotCommands(sessionName, sessionStore, ['wait', String(MAX_ALERT_WINDOW_MS)]), - ).rejects.toThrow(/exceeds the maximum/); + ).rejects.toMatchObject({ + code: 'INVALID_ARGS', + details: { + reason: ALERT_WAIT_WINDOW_TOO_LONG_REASON, + maxWaitWindowMs: MAX_ARMABLE_ALERT_WAIT_WINDOW_MS, + }, + }); expect(mockRunnerCommand).not.toHaveBeenCalled(); // The largest window the command does honour reaches the leg as the caller's own window, and an diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 1b2e060e64..927777d796 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -451,7 +451,7 @@ agent-device alert dismiss - `wait_stable_timeout`: the UI did not settle. - Branch on `readableCaptures`, `waitedMs`, `matches`, and `firstMatch` instead of parsing error text. `firstMatch` carries identity and text only; absence failures make no visibility or rect claim. - Polling wait timeouts, and a replayed wait refused with `wait_landmark_identity_mismatch`, also carry `captures`, `readableCaptures`, and `polls` so you can see where the budget went. Each poll has `startedMs`, `durationMs`, and an `outcome`: `readable`, `unreadable`, `retriable`, `deadline`, `runner-restart`, or `readiness`. Long waits keep the first 5 and last 25 polls. A wait that never saw a readable capture reports the error its polls hit, with that error's code and retry details, instead of a generic timeout; `wait stable` and a never-readable strict absence keep their own diagnostics. `logPath` links the full request log. -- `alert` (same as `alert get`) inspects or handles system alerts on iOS simulator, macOS desktop, and Android permission dialogs. On iOS it also covers app-owned modal popups with native blocking markers. On the Apple XCUITest runner it also covers Safari's own page prompts, such as "Open this page in …?". The `[timeout]` argument is the wait window of `alert wait` on every backend: it polls its whole window, accepted up to 2147453647 ms (~24.8 days); a longer window is refused as `INVALID_ARGS` before anything runs, never shortened. On the Apple XCUITest runner, `alert get ` also takes it as the runner's budget for the read, clamped to 1500–25000 ms and 10000 ms without an argument; a longer `alert wait` polls in runner attempts of at most 25 s. Other backends' `get`, and every backend's `accept` and `dismiss`, run their own fixed budgets and ignore it. For `alert`, the runner's main-thread watchdog is that same budget. An `alert get` it cuts off reports `reason: runner_main_thread_timeout` with `dispatched: unknown`: it does not mean there is no alert, which is `alert-not-found`. The next `alert get` waits out the runner's `RUNNER_BUSY` refusal while the abandoned work drains, then runs; the resends are bounded, so if the work has not drained by then it still returns `RUNNER_BUSY` (`dispatched: no`) and you retry. +- `alert` (same as `alert get`) inspects or handles system alerts on iOS simulator, macOS desktop, and Android permission dialogs. On iOS it also covers app-owned modal popups with native blocking markers. On the Apple XCUITest runner it also covers Safari's own page prompts, such as "Open this page in …?". The `[timeout]` argument is the wait window of `alert wait` on every backend: it polls its whole window, accepted up to 2147453647 ms (~24.8 days); a longer window is refused as `INVALID_ARGS` with `details.reason: alert-wait-window-too-long` and `details.maxWaitWindowMs` before anything runs, never shortened. On the Apple XCUITest runner, `alert get ` also takes it as the runner's budget for the read, clamped to 1500–25000 ms and 10000 ms without an argument; the first XCTest read for `alert wait` uses the requested window capped at 25 s, and later reads use the remaining window with the same cap. The 1500 ms floor does not apply to `alert wait`. Other backends' `get`, and every backend's `accept` and `dismiss`, run their own fixed budgets and ignore it. For `alert`, the runner's main-thread watchdog is that same budget. An `alert get` it cuts off reports `reason: runner_main_thread_timeout` with `dispatched: unknown`: it does not mean there is no alert, which is `alert-not-found`. The next `alert get` waits out the runner's `RUNNER_BUSY` refusal while the abandoned work drains, then runs; the resends are bounded, so if the work has not drained by then it still returns `RUNNER_BUSY` (`dispatched: no`) and you retry. - On the snapshot-derived Android backends `alert get --json` answers with a typed `status`: `visible`, `none`, or `undecided` (an alert-shaped capture that resolves to no single alert). Branch on `status`, not on the message. - On those backends, `alert accept` presses the lasting grant when a permission sheet offers several: Android orders its grants by the platform's own ids (full-access "Allow all", then foreground-only, then always, then the picker-limited "Select photos and videos", then one-time) whatever the button language — this is what makes the Android 14+ partial-media sheet answer "Allow all" — and elsewhere the English label table decides ("while using the app" over "only this time"). Android acts only on the grant ids it declares with a role and a rank; a sheet carrying an allow- or deny-shaped grant id it does not declare (a vendor fork's own button, or a newer Android grant) is refused for both `accept` and `dismiss` — `dismiss` answers with the Back key, the cancel that grants nothing. A sheet whose choices no rank orders — or that names the same choice at two points — is refused with `alert_button_undecided` and `dispatched: no`, never pressed by position; read the labels with `alert get` and press your choice by label/ref. - On those backends, when `alert accept`/`dismiss` fails before pressing anything, `error.details.reason` names why (a capture or transport failure that is not a driver refusal may instead surface as its own error without a `reason`). A budget never cancels a running capture or press: it only ends the polling loop, so every check that started inside the budget finishes and counts. Before any press, `dispatched: no` and the reason is `alert-not-found` (the action budget ended with no alert on screen), `alert_capture_undecided`, or `alert_button_undecided` (the sheet is too ambiguous to act on). After a press, `dispatched` is absent and the reason is `alert-window-expired`; “did not dismiss the visible alert” means the latest post-press capture that answered named the same dialog again, “could not be confirmed” means the press went out but the latest read was unresolvable or never answered, so the dialog may already be gone. If you cancel the request at any point from the press onward — the tap in flight, or the post-press checks — the cancellation reports `dispatched: unknown`: the device may already have received the tap. The one exception is a cancel whose post-press check nevertheless finished and proved the alert gone; then the command reports the handled alert, because the outcome is known. Run `alert get` before acting again.