Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions packages/command-registry/src/descriptor-timeout-policies.ts
Original file line number Diff line number Diff line change
@@ -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';

Expand Down Expand Up @@ -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 <ms>` 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 <ms>` 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 },
};
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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 },
Expand Down
12 changes: 12 additions & 0 deletions packages/command-registry/src/timeout-policy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Comment thread
thymikee marked this conversation as resolved.
Resolved

/** Daemon-side runner budget for `prepare` without `--timeout` (`readPrepareIosRunnerTimeoutMs`). */
export const PREPARE_STARTUP_BUDGET_MS = 240_000;

Expand Down
2 changes: 1 addition & 1 deletion packages/command-surface/src/capture/alert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 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,
Expand Down
17 changes: 14 additions & 3 deletions packages/contracts/src/alert-contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -201,3 +208,78 @@ 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.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
// `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,
});
});
18 changes: 12 additions & 6 deletions packages/daemon/src/execution/handlers/snapshot-alert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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 {
Expand Down Expand Up @@ -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;
Expand Down
Loading
Loading