Compare commits

..
Author SHA1 Message Date
Brent Vatne e39b7aa6da Capture iPhone Duo on EAS with agent-device, and pin agent-device's slider fix
agent-device folds only inside a session, so on EAS the app now opens before
the fold, as it does on a local simulator. Its fold then fails to read the
hinge back, so the display is the check instead: agent-device's screenshot
must be in the pose's shape and drawn (not one flat colour). The first fold
of a fresh session can light a black panel, as it does for Argent; the
capture then restarts SpringBoard, reopens the app and folds again, once,
and otherwise fails with CONTROLLER_READER_STUCK.

agent-device 0.21.28 wedged its iOS runner on @expo/ui sliders on a
regular-width display (an opened iPhone Duo or an iPad): every read of
euxy's lane editor failed. callstack/agent-device#3776 fixes it; it is not
in a stable release yet, so agent-device is pinned to
0.21.29-nightly.20261018.74, which captured the opened Duo 16 of 16 on EAS.

doctor reports Argent's single appearance only for an Android EAS session:
on an iOS EAS session (simulator:control appearance.set) and on this Mac the
host switches it.

solidColour moves to shared/png-evidence, for the display check.
2026-10-17 20:39:44 -07:00
Brent Vatne 6a999e858d Start a new EAS Simulator session when EAS fails to start one
EAS sometimes ends a session while it boots (ERRORED), or a start request
fails before it names one. A capture now starts a new session in its
place, up to five times within 30 minutes of the first failure, waiting
10 s, 20 s, 40 s, 80 s and 120 s, each start capped by what is left of the
30 minutes. Each new session has a name of its own.

Only a failure that is provably EAS's is retried: a session that matches
this capture's id, name, type, platform and project and ended, or a start
that failed for a temporary reason (a failed request, a timeout, a lost
connection, no capacity). After every failed start, a live session by that
exact name is stopped first, so none is left running; one that cannot be
proven this project's stops the retry instead, and is never stopped.
Account failures (authorization, quota, plan) fail at once, a failed lookup
reports the start's own failure, and Ctrl+C stops the wait.

A session EAS ended is reported as SIMULATOR_START_FAILED with the
sessions it tried, not as a handoff whose ownership is in doubt.

The README no longer says the reset before a fold prevents the stuck
reader on EAS: in a real capture it did not, and the SpringBoard restart
is what recovered it.
2026-10-17 18:28:59 -07:00
Brent Vatne 31d69a7994 Capture iPhone Duo on EAS Simulator with eas simulator:control
EAS iOS sessions on serve-sim 0.10.0 offer host actions through
eas simulator:control. Explore uses them only for what the session's
controller cannot do itself:

- app.approveUrlScheme after installing the app, so its own links open
  without iOS asking first (capture, and explore:binary on EAS);
- appearance.set for Argent, so an Argent capture on an iOS EAS session
  records every appearance the config asks for;
- springboard.restart as the last step of the stuck-reader recovery.

On a fresh EAS session, Argent's first fold of an iPhone Duo left the
inner panel black and its reader on the cover panel every time: the
tool-server's device helpers, started at boot, did not follow the fold.
The bridge now resets them (stop-all-simulator-servers) before each fold,
which reads the inner panel at once. If a fold is still not read, it
resets once more; on EAS, capture then restarts SpringBoard and folds
again, and otherwise fails with CONTROLLER_READER_STUCK. The session's
tool-server is never stopped.

eas-cli is pinned to 25.2.0, which adds simulator:control.
2026-10-17 17:19:34 -07:00
Brent Vatne a75cbf84ea Link the deployment when the example alias still serves an earlier one
The example report reuses one token and the same fixture reports, so an alias
still pointing at the previous deployment serves the token page and the same
report bytes; only its reports.json (an older Viewer's listing) differed, and
that mismatch failed the job as PREVIEW_VERIFY_FAILED. The alias now counts as
moved only once it serves this deployment's listing and reports, and an alias
that never does is PREVIEW_ALIAS_BEHIND: the verified deployment is linked
with a warning. The deployment's own origin is still checked strictly.

The README's "Run it yourself" now opens with the two ways to use Explore and
which one needs an Expo account.
2026-10-17 16:26:40 -07:00
Brent Vatne 6c10477c5b Run explore:binary on a local simulator, and bring the README up to date (#8)
explore:binary --simulator local explores a build on a simulator or emulator
it creates on this Mac, with no EAS login: the same devices capture uses,
recorded for the startup sweep, driven by agent-device with its own daemon or
by a local Argent tool-server. The report opens in the local Viewer; --upload
hosts it.

The README now covers local repack and local simulators, a single-path quick
start that reviews a change or explores a build, targets, and requirements
split by what each path needs. The explore-binary, explore-setup and
readme-refresh skills follow.
2026-10-17 15:53:21 -07:00
26 changed files with 783 additions and 151 deletions

No files matched your search

+6 -5
View File
@@ -85,6 +85,8 @@ You need Node.js 24.12+. Reviewing a change needs an Expo account and an Expo SD
<details>
<summary><strong>Run it yourself</strong></summary>
There are two ways to use Explore: review a change to your Expo app, which needs an Expo account, or explore an iOS or Android build of any app directly, which needs no Expo account when it runs on your Mac.
**Review a change**, from your app's directory:
1. Make the app buildable on EAS, if it is not yet:
@@ -339,7 +341,7 @@ Explore pins each controller's version and starts the EAS session with it. Repor
Neither controller is installed with Explore. The first run that needs one downloads its pinned npm release (agent-device 1.6 MB, Argent 27 MB), checks it against the integrity hash Explore pins, and keeps it in `~/.cache/expo-explore/controllers` (`EXPLORE_CONTROLLER_CACHE` moves it). Behind a private registry, set `EXPLORE_NPM_REGISTRY` to a mirror of it.
Argent cannot switch the simulator's appearance yet ([software-mansion/argent#1509](https://github.com/software-mansion/argent/pull/1509)), so an Argent capture on EAS Simulator records one appearance: the one the app forces, else light. Explore warns when it skips one. On a [local simulator](#simulator) the host switches it, so every appearance the config asks for is captured.
Argent cannot switch the simulator's appearance yet ([software-mansion/argent#1509](https://github.com/software-mansion/argent/pull/1509)), so the host switches it: on an iOS EAS Simulator session (`eas simulator:control appearance.set`) and on a [local simulator](#simulator), every appearance the config asks for is captured. An Argent capture on an Android EAS Simulator session records one appearance: the one the app forces, else light. Explore warns when it skips one.
</details>
@@ -370,7 +372,7 @@ For a review, builds still run on EAS. The app is repacked with the route observ
With `--controller argent`, Explore installs Argent's tool-server on first use with `npm ci` from a lockfile Explore ships, so every dependency is pinned (about 160 MB, in the controller cache), and starts one per device. The host switches the appearance, so a local Argent capture records every appearance the config asks for. Reports record where they were captured, and a baseline is reused only by a review captured the same way.
A foldable folds before the app first opens (`pose` on a [target](#targets)); with agent-device on a local simulator it folds just after, since agent-device folds only inside a session. With Argent, an opened iPhone Duo is captured upright, in landscape. After a fold, Argent's reader can stay on the panel that went dark; Explore then restarts its tool-server, and if that is not enough SpringBoard as well, and opens the app again.
A foldable folds before the app first opens (`pose` on a [target](#targets)); with agent-device on a local simulator it folds just after, since agent-device folds only inside a session. With Argent, an opened iPhone Duo is captured upright, in landscape. After a fold, Argent's reader can stay on the panel that went dark, so Explore checks that the lit panel is read. If it isn't, Explore restarts the tool-server on a local simulator. On EAS Simulator, where the tool-server is the session's, it resets Argent's device helpers, then restarts SpringBoard and folds again. On EAS Simulator, an opened iPhone Duo usually needs that SpringBoard restart, which adds about a minute.
Each capture records what it starts on your Mac (simulators, emulators, controller daemons, tool-servers) and removes it when it ends. If a review or a local `explore:binary` run is stopped hard, the next local one stops what it left running; nothing Explore did not record is touched.
@@ -512,7 +514,7 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
1. The review workflow runs on open, non-draft PRs from the repository whose author has write access. Bots such as Devin go under `ci.trustedAuthors` in `.expo-explore/config.yaml`.
2. Explore reads the diff and your router source to pick the affected screens.
3. It builds both revisions on EAS (reusing a build with the same native fingerprint) and captures each screen on EAS Simulator (or, on your machine, a local simulator), reusing a baseline of the base commit when one exists.
3. It builds both revisions on EAS (reusing a build with the same native fingerprint) and captures each screen on EAS Simulator (or, on your machine, a local simulator), reusing a baseline of the base commit when one exists. If EAS fails to start a session, Explore starts a new one, up to five times within 30 minutes.
4. It compares the captures. A screen with a source change is **Modified** if its captures differ.
5. It uploads the report to GitHub Actions and posts a PR comment.
@@ -531,8 +533,7 @@ Reports and baselines are kept for 30 days and diagnostics for 7. Hosted deploym
- The launch is captured once per appearance and compared like any screen. The comment says how long the splash stayed as it first appeared, when it first changed (a native launch screen handing over to an app-drawn one, an animation starting on it), and when the first screen settled. `capture.launch: video` adds a recording; a launch too fast to observe is reported as "no splash observed".
- On Android the splash usually shows only in the recording, which needs `ffmpeg`. The generated workflows install it.
- Hosted acceptance of agent mode with an API key is incomplete.
- With `capture.controller: argent` on EAS Simulator, each capture records one appearance (see [device controller](#controller)).
- On EAS Simulator, an opened iPhone Duo can fail to capture when Argent's reader stays on the cover panel after the fold. A [local simulator](#simulator) recovers from it.
- With `capture.controller: argent` on an Android EAS Simulator session, each capture records one appearance (see [device controller](#controller)).
- A local simulator runs only on your machine; the CI workflows capture on EAS Simulator.
- `explore:session` explores EAS Simulator sessions only.
+2 -2
View File
@@ -105,7 +105,7 @@ device:
exploration:
scope: changes # changes | all
capture:
# controller: agent-device # agent-device (default) | argent (one appearance per capture on EAS Simulator until Argent can switch it; --controller overrides it for one run)
# controller: agent-device # agent-device (default) | argent (one appearance per capture on Android EAS Simulator until Argent can switch it; --controller overrides it for one run)
# simulator: eas # eas (EAS Simulator, default) | local (a simulator or emulator Explore starts on this machine with Xcode or the Android SDK; --simulator overrides it for one run)
maxMinutes: 30
maxActions: 500
@@ -286,7 +286,7 @@ The provider selects the runtime that owns the navigation loop:
| `anthropic` | Claude Code through `@anthropic-ai/claude-agent-sdk` 0.3.285 and its platform-native package | `ANTHROPIC_API_KEY` |
| `openai` | Codex app-server from `@openai/codex` 0.159.2 and its platform-native package | `OPENAI_API_KEY` |
Both runtimes use Explore's device tools to operate the existing EAS Simulator through official `agent-device` 0.21.28. The runtime and native binaries come from the pinned tools installation. CI does not use the development-only `node_modules/.bin/claude` executable or an interactive subscription login.
Both runtimes use Explore's device tools to operate the existing EAS Simulator through official `agent-device` 0.21.29-nightly.20261018.74. The runtime and native binaries come from the pinned tools installation. CI does not use the development-only `node_modules/.bin/claude` executable or an interactive subscription login.
Create and commit the nonempty English prose file named by `agent.instructions`. The shared setup skill authors it from source and asks for missing test data or environment inputs. Describe how to reach the app's screens, necessary prerequisites, the representative state to use on both revisions, readiness signals, and actions to avoid. This file guides the runtime agent; it is not a list of mandatory YAML steps or a second screen inventory.
+47 -33
View File
@@ -29,7 +29,7 @@
"@types/react-dom": "^19.2.4",
"@vitejs/plugin-react": "^4.7.0",
"@xyflow/react": "^12.11.3",
"agent-device": "0.21.28",
"agent-device": "0.21.29-nightly.20261018.74",
"babel-plugin-react-compiler": "^1.0.0",
"eslint": "^10.12.0",
"eslint-plugin-react-hooks": "^7.1.1",
@@ -48,7 +48,7 @@
"optionalDependencies": {
"@anthropic-ai/claude-agent-sdk": "0.3.285",
"@openai/codex": "0.159.2",
"eas-cli": "25.0.0"
"eas-cli": "25.2.0"
}
},
"node_modules/@0no-co/graphql.web": {
@@ -1600,15 +1600,15 @@
}
},
"node_modules/@expo/eas-build-job": {
"version": "25.0.0",
"resolved": "https://registry.npmjs.org/@expo/eas-build-job/-/eas-build-job-25.0.0.tgz",
"integrity": "sha512-Vuai42tVopKuK2KFyTWUsW9cL1YMY1dWhFAKz+evUV5AKaMCk4dYxOYZ6tBWNhIJ15bGK3p4N0YUomlAqubFWg==",
"version": "25.2.0",
"resolved": "https://registry.npmjs.org/@expo/eas-build-job/-/eas-build-job-25.2.0.tgz",
"integrity": "sha512-RUp8sZniYWCiLQLGJrnMeAx8094BoejS6lm7EdSUs4nKkm6TtxyydRutGtoHlvBpvXOw3+OgimemqXUpmU5R8Q==",
"license": "MIT",
"optional": true,
"dependencies": {
"@expo/logger": "25.0.0",
"@expo/logger": "25.2.0",
"@expo/results": "1.0.0",
"@expo/turtle-spawn": "25.0.0",
"@expo/turtle-spawn": "25.2.0",
"joi": "^17.13.1",
"semver": "^7.6.2",
"zod": "^4.3.5"
@@ -1642,14 +1642,14 @@
}
},
"node_modules/@expo/eas-json": {
"version": "25.0.0",
"resolved": "https://registry.npmjs.org/@expo/eas-json/-/eas-json-25.0.0.tgz",
"integrity": "sha512-ilPw4O0Lnce/6lbu1GPwega8KF2GqTio9vuNFjNaGL78pfxz7GdktBsJ9JRaGtiM0LYdPa09W2FYb7DcMY8xWA==",
"version": "25.2.0",
"resolved": "https://registry.npmjs.org/@expo/eas-json/-/eas-json-25.2.0.tgz",
"integrity": "sha512-ZikfZLZHadl5gzq5UZ7qWMTWFZNAO4K6NJC6iF8JmVh3kR1Blv+Zo2AolC0CYzSYOCyaRCZx+v2ZlJZeiVCf8w==",
"license": "MIT",
"optional": true,
"dependencies": {
"@babel/code-frame": "7.23.5",
"@expo/eas-build-job": "25.0.0",
"@expo/eas-build-job": "25.2.0",
"chalk": "4.1.2",
"env-string": "1.0.1",
"fs-extra": "11.2.0",
@@ -1836,6 +1836,19 @@
"node": ">=6"
}
},
"node_modules/@expo/experimentation": {
"version": "0.0.5",
"resolved": "https://registry.npmjs.org/@expo/experimentation/-/experimentation-0.0.5.tgz",
"integrity": "sha512-eQtx5f7tUDZLeq2EXYOkBX+KivYa73CjUMkrEFh5sNMOpCWynisbdSiaSdSLHALWzYKz3uc0QlgWTz3V/6JESQ==",
"license": "MIT",
"optional": true,
"dependencies": {
"nullthrows": "^1.1.1"
},
"engines": {
"node": ">=16"
}
},
"node_modules/@expo/image-utils": {
"version": "0.7.6",
"resolved": "https://registry.npmjs.org/@expo/image-utils/-/image-utils-0.7.6.tgz",
@@ -1900,9 +1913,9 @@
}
},
"node_modules/@expo/logger": {
"version": "25.0.0",
"resolved": "https://registry.npmjs.org/@expo/logger/-/logger-25.0.0.tgz",
"integrity": "sha512-KcNOYmeJH8GESYEjbiewg+LU98XH/yBs368XlPqmEHVZekkbOONpIzPd5AFcFRWO1BW0c2nl/58BUI876UFT8A==",
"version": "25.2.0",
"resolved": "https://registry.npmjs.org/@expo/logger/-/logger-25.2.0.tgz",
"integrity": "sha512-gtf/Lk9zE3k2wfEalAwioxDwvse69A2e/OhoDT7IRjlorRgcNJghr6V4FvDAZckQUkFR1IEHz2+FXvLKf9kjgg==",
"license": "BUSL-1.1",
"optional": true,
"dependencies": {
@@ -2592,14 +2605,14 @@
}
},
"node_modules/@expo/steps": {
"version": "25.0.0",
"resolved": "https://registry.npmjs.org/@expo/steps/-/steps-25.0.0.tgz",
"integrity": "sha512-+o04mm5akQJRX0j9TwwkdZiuNM9swLxw9DsDPtFhbWceg95gky/vc/0qF200kjZL4DEMfd/WhzngBW9aqJ0JQg==",
"version": "25.2.0",
"resolved": "https://registry.npmjs.org/@expo/steps/-/steps-25.2.0.tgz",
"integrity": "sha512-KKM8STsb0dAdI6lyN7WHfczvDdQlCx+vF4unq/qFk6PZgZMvE9+IT8mh25fqgwxNcpR7Ti+xFCip2hhvpK2yng==",
"license": "BUSL-1.1",
"optional": true,
"dependencies": {
"@expo/eas-build-job": "25.0.0",
"@expo/logger": "25.0.0",
"@expo/eas-build-job": "25.2.0",
"@expo/logger": "25.2.0",
"@expo/spawn-async": "^1.7.2",
"arg": "^5.0.2",
"fast-glob": "^3.3.2",
@@ -2637,13 +2650,13 @@
"optional": true
},
"node_modules/@expo/turtle-spawn": {
"version": "25.0.0",
"resolved": "https://registry.npmjs.org/@expo/turtle-spawn/-/turtle-spawn-25.0.0.tgz",
"integrity": "sha512-XBQZ2azxh0IWozO5hCxIJt150LjIGbk6VZakeyA6UXPHp1ESenm97o0JIHOvzQNOgBV481muV88KmIWHGt0yIA==",
"version": "25.2.0",
"resolved": "https://registry.npmjs.org/@expo/turtle-spawn/-/turtle-spawn-25.2.0.tgz",
"integrity": "sha512-1Lor7/+4T1JEb6kqu0dHstD+xOWTGbwA7QqWTBKYx4qtgtJ4Wbor17bzlp87KENAYDeWuX+7VHKxT66170m9wg==",
"license": "BUSL-1.1",
"optional": true,
"dependencies": {
"@expo/logger": "25.0.0",
"@expo/logger": "25.2.0",
"@expo/spawn-async": "^1.7.2"
}
},
@@ -4580,9 +4593,9 @@
}
},
"node_modules/agent-device": {
"version": "0.21.28",
"resolved": "https://registry.npmjs.org/agent-device/-/agent-device-0.21.28.tgz",
"integrity": "sha512-uGEENVhPzSpIACrVlt16O1mloODWJyAemTCT0boDb4L006JXN2rG747u1TRoQJudOpdP/Pm2urxNRHeECLMLfg==",
"version": "0.21.29-nightly.20261018.74",
"resolved": "https://registry.npmjs.org/agent-device/-/agent-device-0.21.29-nightly.20261018.74.tgz",
"integrity": "sha512-7+ajWLr0J+8iLZ9q11ERbj6U14mC20umBK5BQQdw5aERA79yeXc3Ze6KmtvnILnWjEtoVkYQsXQasL8RL6Uatw==",
"dev": true,
"license": "MIT",
"bin": {
@@ -5722,9 +5735,9 @@
}
},
"node_modules/eas-cli": {
"version": "25.0.0",
"resolved": "https://registry.npmjs.org/eas-cli/-/eas-cli-25.0.0.tgz",
"integrity": "sha512-FBY3pIo/3L0s+8KK5ZpMKzlLrA5jOmr5kOpoOwkAXsxMrI4vo+LNoEsciRcOxjce9efc08GqEEPc/CxLRAWIvA==",
"version": "25.2.0",
"resolved": "https://registry.npmjs.org/eas-cli/-/eas-cli-25.2.0.tgz",
"integrity": "sha512-FFA6fSl2bPet9D3Eslupig3icXjyBzAbrsLE5r67wbEbh/CPDZQ+Q4W5TrpRui0uqfF16w58EGsFUQoQ0te0KQ==",
"license": "MIT",
"optional": true,
"dependencies": {
@@ -5732,11 +5745,12 @@
"@expo/code-signing-certificates": "0.0.5",
"@expo/config": "55.0.10",
"@expo/config-plugins": "55.0.7",
"@expo/eas-build-job": "25.0.0",
"@expo/eas-json": "25.0.0",
"@expo/eas-build-job": "25.2.0",
"@expo/eas-json": "25.2.0",
"@expo/env": "^1.0.0",
"@expo/experimentation": "0.0.5",
"@expo/json-file": "8.3.3",
"@expo/logger": "25.0.0",
"@expo/logger": "25.2.0",
"@expo/multipart-body-parser": "2.0.0",
"@expo/osascript": "2.1.4",
"@expo/package-manager": "1.9.10",
@@ -5748,7 +5762,7 @@
"@expo/results": "1.0.0",
"@expo/rudder-sdk-node": "1.1.1",
"@expo/spawn-async": "1.7.2",
"@expo/steps": "25.0.0",
"@expo/steps": "25.2.0",
"@expo/timeago.js": "1.0.0",
"@oclif/core": "^4.8.3",
"@oclif/plugin-autocomplete": "^3.2.40",
+2 -2
View File
@@ -73,7 +73,7 @@
"optionalDependencies": {
"@anthropic-ai/claude-agent-sdk": "0.3.285",
"@openai/codex": "0.159.2",
"eas-cli": "25.0.0"
"eas-cli": "25.2.0"
},
"devDependencies": {
"@anthropic-ai/claude-code": "2.1.285",
@@ -83,7 +83,7 @@
"@types/react-dom": "^19.2.4",
"@vitejs/plugin-react": "^4.7.0",
"@xyflow/react": "^12.11.3",
"agent-device": "0.21.28",
"agent-device": "0.21.29-nightly.20261018.74",
"babel-plugin-react-compiler": "^1.0.0",
"eslint": "^10.12.0",
"eslint-plugin-react-hooks": "^7.1.1",
+20 -16
View File
@@ -1,5 +1,4 @@
import { createHash, randomUUID } from "node:crypto";
import { createRequire } from "node:module";
import { lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -17,13 +16,14 @@ import { agentDeviceLauncher, ensureArgentToolServer, ensureController } from ".
import { agentDeviceClaims, approveLinkScheme, createLocalSimulator, deleteLocalEmulator, deleteLocalSimulator, hostEmulatorAbi, installOnLocalEmulator, installOnLocalSimulator, startLocalArgentServer,
startLocalEmulator, stopLocalAgentDevice, stopLocalArgentServer, waitForLocalEmulator, waitForLocalSimulator, type LocalArgentServer } from "../capture/local-simulator.js";
import { openLocalCaptureRecord, sweepLocalCaptures } from "../capture/local-registry.js";
import { approveSessionUrlSchemes, simulatorControlActions, type EasCommand } from "../capture/simulator-control.js";
import { DEFAULT_ANDROID_DEVICE } from "../config/explore-config.js";
import { createExplorationInputs } from "../config/exploration-inputs.js";
import { ExploreStore, getCoverage } from "../map/store.js";
import { whoamiAccounts } from "../report/preview-deploy.js";
import { CiError, serializeCiError, toCiError } from "../shared/ci-errors.js";
import { packageBin } from "../shared/package-paths.js";
import { assertDecodedPng, type DecodedFrame } from "../shared/png-evidence.js";
import { assertDecodedPng, solidColour } from "../shared/png-evidence.js";
import { CONTRACT, type ExploreMap, type Platform } from "../types.js";
import { assertEmulatorCompatible, extractIosBundle, inspectArchive, type ArchiveKind, type InspectedArchive, readArchiveIcon } from "./archive.js";
import { runBlackBoxExploration, type BlackBoxExplorerResult, type BlackBoxFrame, SYSTEM_DIALOG_PACKAGES } from "./explorer.js";
@@ -277,6 +277,8 @@ export type ConnectedSessionExploration = {
* serial (agent-device with a daemon of its own in `stateDirectory`, or a local Argent tool-server pinned to it).
*/
local?: { deviceId: string; osVersion: string; stateDirectory: string };
/** Runs once the app is installed and before anything opens it, as an EAS session's link approval must. */
afterInstall?: () => void;
};
/** Drives an agent-device daemon we already hold a connection to: optional install, open, then the model-led exploration. */
@@ -317,6 +319,7 @@ export async function exploreConnectedSession(ctx: ConnectedSessionExploration):
try { controller(["install", install.path, "--json"], 15 * 60_000); }
catch (error) { throw binaryError("APP_INSTALL_FAILED", `${controllerName} could not install the app: ${failureText(error)}`, "Check that the archive is a simulator build for this platform and under the size limit, then rerun.", { sessionId: connection.sessionId }); }
}
ctx.afterInstall?.();
// On a local device, the first open also builds agent-device's iOS runner.
const opened = controller(["open", bundleId, "--level", "full", "--json"], local ? 15 * 60_000 : 2 * 60_000);
const openedDevice = openedSimulatorDevice(opened.stdout, bundleId, "initial app open", platform, controllerSession);
@@ -714,7 +717,8 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
let installPath = archive.path;
if (archive.kind === "ios-tgz" || archive.kind === "ios-ipa") { say("unpacking the iOS bundle"); installPath = await extractIosBundle(archive, join(work, "bundle")); }
const appIcon = await readArchiveIcon(archive);
const exploreOn = (connection: SimulatorConnection, sessionJson: () => string, localDevice?: LocalDevice) => exploreConnectedSession({ connection, platform, device, bundleId,
const exploreOn = (connection: SimulatorConnection, sessionJson: () => string, localDevice?: LocalDevice, afterInstall?: () => void) => exploreConnectedSession({ connection, platform, device, bundleId,
...(afterInstall ? { afterInstall } : {}),
...(appIcon ? { appIcon } : {}), app: { name: archive.appName, ...(archive.version ? { version: archive.version } : {}) },
// A local device has the app installed by simctl or adb before the controller starts.
...(localDevice ? { local: localDevice } : { install: { path: installPath, kind: archive.kind } }),
@@ -770,7 +774,18 @@ export async function runBinaryExploration(options: BinaryExploreOptions): Promi
if (handoff.validationError) throw handoff.validationError;
if (!handoff.connection) throw new Error("Simulator handoff is missing its controller connection");
await rm(dotenvPath, { force: true });
({ runtime, exploration } = await exploreOn(handoff.connection, () => eas(["simulator:get", "--id", handoff.connection!.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout));
// The app's own links open without iOS asking first, when the session's host can approve them (serve-sim 0.10.0).
const verifiedSession = sessionId;
const sessionEas: EasCommand = (args, commandOptions) => {
const result = eas(args, commandOptions?.timeoutMs);
if (result.status !== 0 && !commandOptions?.allowFailure) throw new Error(lastLine(result.stderr || result.stdout) || `eas ${args[0]} failed`);
return result;
};
const afterInstall = platform === "ios" && archive.urlSchemes.length ? () => {
const approved = approveSessionUrlSchemes(sessionEas, verifiedSession, simulatorControlActions(sessionEas, verifiedSession), bundleId, archive.urlSchemes);
if (approved.length) say(`approved ${approved.map(item => `${item}://`).join(", ")} links on the session`);
} : undefined;
({ runtime, exploration } = await exploreOn(handoff.connection, () => eas(["simulator:get", "--id", handoff.connection!.sessionId, "--json", "--non-interactive"], 2 * 60_000).stdout, undefined, afterInstall));
}
} catch (error) {
primaryError = toCiError(error, { code: "EXPLORE_BINARY_FAILED", stage: "exploration", nextAction: "Inspect the diagnostic, correct the failing prerequisite, and rerun explore:binary." });
@@ -839,18 +854,7 @@ export function assertAppUrl(url: string, appSchemes: readonly string[] = []): v
export const BLANK_SCREENSHOT_MESSAGE = "The app blocks screen capture on this screen (Android FLAG_SECURE), so its screenshot came back blank.";
/** A capture-protected screen comes back as a single flat colour (black on Android); every 97th pixel is enough to tell. */
export function solidColour(png: Buffer): boolean {
let frame: DecodedFrame;
try { frame = createRequire(import.meta.url.replace(/\?.*$/, ""))("pngjs").PNG.sync.read(png, { checkCRC: false }) as DecodedFrame; }
catch { return false; }
const { data } = frame;
if (data.length < 4) return false;
for (let offset = 0; offset + 3 < data.length; offset += 4 * 97) {
if (data[offset] !== data[0] || data[offset + 1] !== data[1] || data[offset + 2] !== data[2]) return false;
}
return true;
}
export { solidColour };
/** Setup commands whose last positional is free text (`fill <ref> <text>`, `type <text>`): move the flags ahead of a `--` separator. */
export function guardPositionals(args: readonly string[]): string[] {
+29 -7
View File
@@ -301,7 +301,8 @@ export async function runBridgeCommand(argv: readonly string[], context: ArgentB
/** Reads are resent after a transport failure (they change nothing); a UI action is sent once, after a health check. */
const call = async (tool: string, args: Record<string, unknown> = {}, options?: { out?: string }): Promise<Record<string, unknown>> => {
const withDevice = tool === "list-devices" ? args : { udid: state.udid, ...args };
// Tools that name devices their own way (or none) take no udid.
const withDevice = tool === "list-devices" || tool === "stop-all-simulator-servers" ? args : { udid: state.udid, ...args };
for (let attempt = 0; ; attempt++) {
try { return record(await context.call(tool, withDevice, options)); }
catch (error) {
@@ -619,6 +620,10 @@ export async function runBridgeCommand(argv: readonly string[], context: ArgentB
const posture = positional[0];
if (posture !== "closed" && posture !== "half-open" && posture !== "open") throw new BridgeFailure("INVALID_ARGS", "fold needs closed, half-open or open.");
await beforeAction();
// Helpers the tool-server started before a fold can leave the panel it lights black and unread: on a fresh EAS
// session, whose tool-server started them at boot, the first fold opened to a black inner panel every time
// without this, and read the panel at once with it. A local tool-server is Explore's own and starts clean.
await call("stop-all-simulator-servers", { devices: [state.udid] });
const folded = await call("fold", { posture });
// The other panel lights at another size: every stored coordinate and element reference is stale.
delete state.screen;
@@ -630,16 +635,33 @@ export async function runBridgeCommand(argv: readonly string[], context: ArgentB
const lit = record(folded.screen);
if (finite(lit.width) && finite(lit.height) && lit.height > 0) {
const litRatio = lit.width / lit.height;
let followed = false;
for (let poll = 0; poll < 10 && !followed; poll++) {
const shape = (await tree()).screen;
followed = !!shape && shape.height > 0 && Math.abs(shape.width / shape.height - litRatio) < 0.004;
if (!followed) await context.sleep(1_000);
const follows = async () => {
for (let poll = 0; poll < 10; poll++) {
const shape = (await tree()).screen;
if (shape && shape.height > 0 && Math.abs(shape.width / shape.height - litRatio) < 0.004) return true;
await context.sleep(1_000);
}
return false;
};
// A reader still stuck on the dark panel is reset once more (the device's helpers, as reset-reader does): it is
// cheap and leaves the app alone. If that is not enough, capture restarts SpringBoard and folds again.
if (!await follows() && !await call("stop-all-simulator-servers", { devices: [state.udid] }).then(follows, () => false)) {
throw new BridgeFailure("CONTROLLER_FOLD_UNVERIFIED", `Argent kept reading the other panel after folding the device ${posture}, and after its device helpers were reset.`);
}
if (!followed) throw new BridgeFailure("CONTROLLER_FOLD_UNVERIFIED", `Argent kept reading the other panel after folding the device ${posture}.`);
}
return success({ action: "fold", pose: posture, ...(folded.panel !== undefined ? { panel: folded.panel } : {}) });
}
case "reset-reader": {
// Stops the device's Argent helpers, among them the accessibility service describe reads through; the
// tool-server starts fresh ones on the next call. It is how a reader stuck on the panel a fold turned off is
// reset where the tool-server itself cannot be restarted, as on EAS (it started it; never stop it there).
await ensureDevice();
const stopped = await call("stop-all-simulator-servers", { devices: [state.udid] });
delete state.screen;
delete state.refs;
state.generation += 1;
return success({ action: "reset-reader", stopped: Array.isArray(stopped.stopped) ? stopped.stopped.filter(item => typeof item === "string") : [] });
}
case "apps": return success({ apps: [] });
case "session": return success({ sessions: [] });
// TODO(argent#1509): map `settings appearance <scheme>` to Argent's `set-appearance` once a release with it is pinned.
+1 -1
View File
@@ -1,6 +1,6 @@
import { CiError } from "../shared/ci-errors.js";
export const EAS_CLI_VERSION = "25.0.0";
export const EAS_CLI_VERSION = "25.2.0";
export { AGENT_DEVICE_VERSION } from "../shared/agent-device-version.js";
export const CONTROLLER_SESSION = "expo-explore-runtime";
+1 -1
View File
@@ -92,7 +92,7 @@ export function approveLinkScheme(options: { runner: CommandRunner; udid: string
}
/** The pixel size of a PNG, from its header. */
function pngSize(bytes: Buffer): { width: number; height: number } | undefined {
export function pngSize(bytes: Buffer): { width: number; height: number } | undefined {
if (bytes.length < 24 || bytes.toString("latin1", 12, 16) !== "IHDR") return undefined;
return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
}
+206 -19
View File
@@ -22,14 +22,16 @@ import { loadAppIcon, loadCachedAppIcon, storeAppIcon } from "./app-icon.js";
import { defaultRunner, runAgentControllerCommand } from "./controller.js";
import { silentProgress, type Progress } from "../shared/progress.js";
import { assertCaptureEasProfile, assertSimulatorAvailable, fingerprintFrom, hasEasEnvironmentFetchFailure, nativeBuildFrom, existingBuild, repackProfileFrom, prepareExactSourceBuild, type RepackMode } from "./eas-build.js";
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, controllerVersion, simulatorOsVersion, type ActiveSimulatorRuntime, type SimulatorConnection } from "./simulator.js";
import { SIMULATOR_DOTENV_FILE_NAME, SIMULATOR_DOTENV_HEADER, endedOwnSimulatorSession, liveSimulatorSessionsNamed, simulatorSessionName, simulatorStartFailure, readSimulatorDotenvHandoff, assertSimulatorSessionIdentity, assertSimulatorStopped, collectRuntime, controllerVersion, simulatorOsVersion, type ActiveSimulatorRuntime, type SimulatorConnection } from "./simulator.js";
import { argentControllerInvocation } from "./controller-invocation.js";
import { sharedBuild } from "./shared-build.js";
import { LOCAL_EMULATOR_STATE_PREFIX, LOCAL_SIMULATOR_STATE_PREFIX, agentDeviceClaims, assertLocalEmulatorCompatible, createLocalSimulator, startLocalEmulator, waitForLocalEmulator, waitForLocalSimulator, deleteLocalEmulator,
deleteLocalSimulator, hostEmulatorAbi, installOnLocalEmulator, installOnLocalSimulator, approveLinkScheme, localPoseShown,
setLocalEmulatorAppearance, setLocalSimulatorAppearance, startLocalArgentServer, stopLocalAgentDevice, stopLocalArgentServer, type LocalArgentServer } from "./local-simulator.js";
pngSize, setLocalEmulatorAppearance, setLocalSimulatorAppearance, startLocalArgentServer, stopLocalAgentDevice, stopLocalArgentServer, type LocalArgentServer } from "./local-simulator.js";
import { ensureArgentToolServer } from "../shared/controller-cache.js";
import { openLocalCaptureRecord } from "./local-registry.js";
import { approveSessionUrlSchemes, simulatorControl, simulatorControlActions, type EasCommand } from "./simulator-control.js";
import { solidColour } from "../shared/png-evidence.js";
import { type UnattributedSetting } from "./unattributed.js";
import { appScheme, hasConcreteRoutePath, unavailableRoute, capturePlannedRoutes, deviceArgs } from "./route-capture.js";
@@ -98,6 +100,20 @@ export type CiMapResult = {
};
/** New EAS sessions a capture starts in place of one EAS failed to start (ERRORED while booting, or never named). */
const SESSION_START_RETRIES = 5;
/**
* The most time, from the first failed start, that replacement sessions may take, waits included. It keeps a review
* inside its CI job (90 minutes for a baseline) with a native build, a repack and both captures still to run.
*/
const SESSION_RETRY_BUDGET_MS = 30 * 60_000;
/** How long one `eas simulator:start` may take: eas-cli waits up to 15 minutes for a session, not counting the queue. */
const SESSION_START_TIMEOUT_MS = 20 * 60_000;
/** The wait before each of them: 10 s, doubling, at most 2 minutes. */
export function sessionRetryDelayMs(retry: number): number {
return Math.min(10_000 * 2 ** (retry - 1), 120_000);
}
/**
* Minutes an EAS session is asked for beyond the capture's own budget. The session starts beside the repack, and the
* capture deadline only starts once the app is installed, so the session also has to outlast a slow or queued hosted
@@ -113,6 +129,17 @@ function sessionDurationLimit(error: unknown): number | undefined {
return match ? Math.floor(Number(match[1])) : undefined;
}
/**
* A start failure EAS may not repeat on the next try: a failed request, a dropped connection, a timeout, or no capacity
* right now. An account's quota, plan or permissions are not, and fail at once rather than after every retry.
*/
function transientSessionStartFailure(error: unknown): boolean {
if (error instanceof CiError && error.code === "CONTROLLER_REQUEST_TIMEOUT") return true;
const message = error instanceof Error ? error.message : String(error);
if (/not authori[sz]ed|unauthori[sz]ed|forbidden|permission|quota|billing|max duration/i.test(message)) return false;
return /GraphQL request failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|timed out|\b50[234]\b|capacity/i.test(message);
}
function positiveInteger(value: number, name: string): number {
if (!Number.isInteger(value) || value <= 0) {
throw new Error(`${name} must be a positive integer`);
@@ -411,17 +438,26 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
say(`reading EAS build profile ${options.easProfile}`);
const eas = (args: string[], timeoutMs = 5 * 60_000, cwd = project) => runner({ command: options.easCommand, args,
cwd, environment: easEnvironment, timeoutMs });
// `eas simulator:control` names the session by id, from the session's own project directory.
const sessionEas: EasCommand = (args, commandOptions) => runner({ command: options.easCommand, args, cwd: simulatorProject, environment: easEnvironment,
timeoutMs: commandOptions?.timeoutMs ?? 5 * 60_000, ...(commandOptions?.allowFailure ? { allowFailure: true } : {}) });
// What the EAS session's host can do through simulator:control (iOS sessions on serve-sim 0.10.0 or later).
let controlActions = new Set<string>();
const configResult = eas(["config", "--platform", options.platform, "--profile", options.easProfile, "--json", "--non-interactive"]);
const profile = repackProfileFrom(configResult.stdout);
const configValue = parseJson(configResult.stdout, "eas config") as { appConfig: Record<string, unknown>; buildProfile: Record<string, unknown> };
scheme ??= appScheme(configValue.appConfig.scheme);
colorSchemes = resolveColorSchemes(options.appearance ?? "auto", configValue.appConfig, options.platform);
// Argent cannot switch the appearance itself; on a local device the host switches it (simctl, adb), so it is kept.
if (controller === "argent" && !local) {
const single = argentColorSchemes(colorSchemes, configValue.appConfig, options.platform);
if (single.skipped.length) say(`Argent cannot switch appearance yet (software-mansion/argent#1509); capturing ${single.schemes[0]} only, skipped ${single.skipped.join(", ")}`);
colorSchemes = single.schemes;
}
// Argent cannot switch the appearance itself. On a local device the host switches it (simctl, adb); on an EAS iOS
// session serve-sim does (appearance.set), which is known once the session starts; otherwise one appearance is captured.
let argentSchemes = controller === "argent" && !local ? argentColorSchemes(colorSchemes, configValue.appConfig, options.platform) : undefined;
const narrowToArgentScheme = () => {
if (!argentSchemes) return;
if (argentSchemes.skipped.length) say(`Argent cannot switch appearance on this session; capturing ${argentSchemes.schemes[0]} only, skipped ${argentSchemes.skipped.join(", ")}`);
colorSchemes = argentSchemes.schemes;
argentSchemes = undefined;
};
if (options.platform !== "ios") narrowToArgentScheme();
app = { name: profile.projectIdentity.name, ...(profile.projectIdentity.version ? { version: profile.projectIdentity.version } : {}),
...(profile.projectIdentity.buildNumber ? { buildNumber: profile.projectIdentity.buildNumber } : {}) };
projectId = profile.projectIdentity.projectId;
@@ -491,19 +527,23 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
}
} catch (error) { await stopEarlyDevice().catch(() => undefined); throw error; }
// The session is named before its app exists: an EAS session starts while the app is repacked (startSession).
const sessionName = simulatorSessionName({ mapName: options.name, mapId: options.buildId, gitCommit: options.gitCommit, easBuildId: local ? "local" : "installed",
runIdentity: JSON.stringify({ mapDirectory, outputDirectory, run: sourceEnvironment.GITHUB_RUN_ID, attempt: sourceEnvironment.GITHUB_RUN_ATTEMPT }) });
// A session EAS failed to start is replaced once (see the session block), under a name of its own.
const sessionNameFor = (retry: number) => simulatorSessionName({ mapName: options.name, mapId: options.buildId, gitCommit: options.gitCommit, easBuildId: local ? "local" : "installed",
runIdentity: JSON.stringify({ mapDirectory, outputDirectory, run: sourceEnvironment.GITHUB_RUN_ID, attempt: sourceEnvironment.GITHUB_RUN_ATTEMPT, ...(retry ? { sessionRetry: retry } : {}) }) });
let sessionRetries = 0;
let sessionName = sessionNameFor(0);
/**
* Starts the EAS Simulator session in the background, empty, once the build to repack is known (not while a native
* build runs, which can take most of an hour of session time). The app is installed through the controller when both
* are ready. Resolves with the start command's failure, if any; the session block verifies what EAS handed over.
*/
const startSession = () => {
const startSession = (retry?: { timeoutMs: number }) => {
if (local || sessionStart) return;
say(`starting an EAS Simulator session (${options.device}) while the app is repacked`);
if (!retry) say(`starting an EAS Simulator session (${options.device}) while the app is repacked`);
const request = (minutes: number) => ({ command: options.easCommand, args: ["simulator:start", "--name", sessionName, "--platform", options.platform, "--device", options.device,
"--type", controller, "--package-version", controllerVersion(controller), "--public-link",
"--max-duration-minutes", String(minutes), "--out-config-type", "dotenv", "--non-interactive"], cwd: simulatorProject, environment: easEnvironment, timeoutMs: 20 * 60_000 });
"--max-duration-minutes", String(minutes), "--out-config-type", "dotenv", "--non-interactive"], cwd: simulatorProject, environment: easEnvironment,
timeoutMs: retry?.timeoutMs ?? SESSION_START_TIMEOUT_MS });
// An injected runner (tests) answers synchronously; a real start runs beside the repack.
const start = async (minutes: number) => options.runner ? options.runner(request(minutes)) : runAgentControllerCommand(request(minutes), options.signal ?? new AbortController().signal);
sessionStart = writeFile(dotenvPath, SIMULATOR_DOTENV_HEADER, { flag: "wx", mode: 0o600 })
@@ -597,8 +637,72 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
throw new Error("The local device did not start before capture");
} else {
if (!localApp || !sessionStart) throw new Error("An EAS Simulator session needs the instrumented app on this machine");
const startError = await sessionStart;
const handoff = await readSimulatorDotenvHandoff(dotenvPath);
let startError = await sessionStart;
let handoff = await readSimulatorDotenvHandoff(dotenvPath);
// EAS sometimes fails to start a session: it errors while booting, or the start request fails before a session is
// named. After every failed start, whatever it may have left running is accounted for; then, when the failure is
// provably EAS's, a new session replaces it, up to SESSION_START_RETRIES times within SESSION_RETRY_BUDGET_MS, with
// a growing wait. A session Explore cannot prove is its own is never replaced or stopped: that stays a handoff
// failure below, as does a lookup that fails.
const clock = options.now ?? Date.now;
const endedSessions: string[] = [];
let ended: { sessionId: string; status: string } | undefined;
let retryDeadline: number | undefined;
for (;;) {
const easRead = (args: string[]) => {
try { return runner({ command: options.easCommand, args, cwd: project, environment: easEnvironment, timeoutMs: 2 * 60_000, allowFailure: true }).stdout; }
catch { return ""; }
};
let reason: string | undefined;
ended = undefined;
if (handoff.sessionId) {
const status = endedOwnSimulatorSession(easRead(["simulator:get", "--id", handoff.sessionId, "--json", "--non-interactive"]),
{ sessionId: handoff.sessionId, sessionName, project: profile.projectIdentity, type: controller, platform: options.platform });
if (status) {
ended = { sessionId: handoff.sessionId, status };
endedSessions.push(handoff.sessionId);
reason = `EAS ended simulator session ${handoff.sessionId} (${status}) before it was ready`;
}
} else if (startError && transientSessionStartFailure(startError)) {
// The failed request may still have created a session: any by this exact name is stopped, so none is left running.
const live = liveSimulatorSessionsNamed(easRead(["simulator:list", "--name", sessionName, "--status", "new", "--status", "queued", "--status", "starting",
"--status", "in-progress", "--limit", "100", "--json", "--non-interactive"]), sessionName, profile.projectIdentity);
if (live) {
for (const id of live) assertSimulatorStopped(eas(["simulator:stop", "--id", id, "--json", "--non-interactive"], 2 * 60_000).stdout, id);
reason = `EAS could not start the simulator session (${simulatorStartFailure(startError, [options.expoToken]).message})`;
}
}
if (!reason || sessionRetries >= SESSION_START_RETRIES) break;
retryDeadline ??= clock() + SESSION_RETRY_BUDGET_MS;
const delayMs = sessionRetryDelayMs(sessionRetries + 1);
// A new start needs at least a minute of the budget after its wait; one started later could not finish in it.
const startTimeoutMs = Math.min(SESSION_START_TIMEOUT_MS, retryDeadline - clock() - delayMs);
if (startTimeoutMs < 60_000) break;
sessionRetries += 1;
say(`${reason}; starting a new EAS Simulator session in ${Math.round(delayMs / 1000)} s (${sessionRetries}/${SESSION_START_RETRIES})`);
options.signal?.throwIfAborted();
// Asynchronous and cancellable, so targets capturing beside this one keep running and Ctrl+C stops the wait.
if (options.sleep) options.sleep(delayMs);
else await new Promise<void>((resolve, reject) => {
const timer = setTimeout(() => { options.signal?.removeEventListener("abort", abort); resolve(); }, delayMs);
const abort = () => { clearTimeout(timer); reject(options.signal!.reason); };
options.signal?.addEventListener("abort", abort, { once: true });
});
options.signal?.throwIfAborted();
await rm(dotenvPath, { force: true });
sessionName = sessionNameFor(sessionRetries);
sessionStart = undefined;
startSession({ timeoutMs: startTimeoutMs });
startError = await sessionStart;
handoff = await readSimulatorDotenvHandoff(dotenvPath);
}
// Every session EAS ended is its own failure to start, never a question of ownership.
if (ended) throw new CiError({ code: "SIMULATOR_START_FAILED", stage: "session",
message: `EAS could not start a simulator session: ${endedSessions.length === 1 ? `session ${ended.sessionId} ended (${ended.status}) before it was ready`
: `${endedSessions.length} sessions ended before they were ready (the last, ${ended.sessionId}, ${ended.status})`}.`,
nextAction: "Rerun Explore. If sessions keep failing to start, check the EAS Simulator status and the sessions' logs on expo.dev.",
retryable: true, details: { attempts: sessionRetries + 1, endedSessions, ...(startError ? { startFailure: simulatorStartFailure(startError, [options.expoToken]) } : {}) },
...(startError ? { cause: startError } : {}) });
const startSecrets = [options.expoToken, ...(handoff.connection ? [handoff.connection.daemonAuthToken] : [])];
const startFailure = startError ? simulatorStartFailure(startError, startSecrets) : undefined;
if (handoff.sessionId) {
@@ -628,6 +732,8 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
if (!handoff.connection) throw new Error("Simulator handoff is missing its controller connection");
connection = handoff.connection;
await rm(dotenvPath, { force: true });
if (options.platform === "ios") controlActions = simulatorControlActions(sessionEas, sessionId);
if (!controlActions.has("appearance.set")) narrowToArgentScheme();
}
const controllerConfig = join(simulatorProject, "agent-device.json");
await writeFile(controllerConfig, "{}\n", { flag: "wx", mode: 0o400 });
@@ -655,14 +761,22 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
say(`installing the app on session ${sessionId}`);
runner({ command: controllerCommand, args: ["install", localApp, "--session", CONTROLLER_SESSION, ...deviceArgs({ platform: options.platform, deviceModel: options.device }),
"--platform", options.platform, "--json"], cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 15 * 60_000 });
// Before any link opens, as a local capture does with simctl: the app's own links then open without the prompt.
if (sessionId && scheme) {
const approved = approveSessionUrlSchemes(sessionEas, sessionId, controlActions, options.bundleId, [scheme]);
if (approved.length) say(`approved ${approved.map(item => `${item}://`).join(", ")} links on session ${sessionId}`);
}
}
if (options.devicePose) {
// A fold relights the other panel and resizes the window. It comes before the app is first opened or read, so the
// controller's accessibility reader starts on the lit panel: Argent's, started on the outer panel, can stay there.
say(`folding ${options.device} ${options.devicePose}`);
const target = deviceArgs({ platform: options.platform, deviceModel: options.device, ...(localDevice() ? { provider: "local-simulator" as const, controllerDeviceId: localDevice()! } : {}) });
// agent-device reads the hinge back after folding and fails to (locally and on EAS); its display is checked instead.
const easAgentDevice = !!sessionId && controller === "agent-device";
const fold = () => runner({ command: controllerCommand, args: ["fold", options.devicePose!, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, ...(localSimulator ? { allowFailure: true } : {}) });
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, ...(localSimulator || easAgentDevice ? { allowFailure: true } : {}) });
const pause = options.sleep ?? (milliseconds => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds); });
if (localSimulator && controller === "argent") {
// Argent folds without a session and checks the fold against its own reader; this machine also checks the display.
fold();
@@ -680,6 +794,59 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
...(options.sleep ? { sleep: options.sleep } : {}) })) throw new CiError({ code: "CONTROLLER_FOLD_UNVERIFIED", stage: "session",
message: `${options.device} did not show the ${options.devicePose} display after folding: ${(folded.stderr || folded.stdout).trim().split("\n").at(-1) ?? ""}`.trim(),
nextAction: "Rerun; if it persists, check that this Xcode's simulator supports folding the device." });
} else if (easAgentDevice && sessionId) {
// On EAS, agent-device also folds only inside a session, so the app opens first. The first fold of a fresh session
// can leave the panel it lights black, as it does for Argent: the controller then reads the old panel and a
// relaunch draws nothing. The display is the check, through the controller's own screenshot: in the pose's shape
// and drawn. If it is not, SpringBoard is restarted, the app reopened and the device folded again, once.
const open = (relaunch: boolean) => runner({ command: controllerCommand, args: ["open", options.bundleId, ...(relaunch ? ["--relaunch"] : []), "--session", CONTROLLER_SESSION,
...target, "--platform", options.platform, "--json"], cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 15 * 60_000 });
const shown = async () => {
if (options.devicePose !== "open" && options.devicePose !== "closed") return true;
const file = join(simulatorProject, "pose.png");
// The display relights and resizes over a moment after the hinge moves.
for (let attempt = 0; attempt < 10; attempt += 1) {
if (attempt) pause(1_000);
runner({ command: controllerCommand, args: ["screenshot", file, "--session", CONTROLLER_SESSION, ...target, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000, allowFailure: true });
const png = await readFile(file).catch(() => Buffer.alloc(0));
await rm(file, { force: true });
const size = pngSize(png);
if (size && (options.devicePose === "open" ? size.width > size.height : size.height > size.width) && !solidColour(png)) return true;
}
return false;
};
open(false);
fold();
if (!await shown()) {
if (!controlActions.has("springboard.restart")) throw new CiError({ code: "CONTROLLER_FOLD_UNVERIFIED", stage: "session",
message: `${options.device} did not show the ${options.devicePose} display after folding.`, nextAction: "Rerun the capture on a new session." });
say(`${options.device} did not draw the ${options.devicePose} display after the fold; restarting SpringBoard and folding ${options.devicePose} again`);
simulatorControl(sessionEas, sessionId, "springboard.restart");
pause(8_000);
open(true);
fold();
if (!await shown()) throw new CiError({ code: "CONTROLLER_READER_STUCK", stage: "session",
message: `${options.device} did not draw the ${options.devicePose} display after folding, nor after SpringBoard was restarted and it was folded again.`,
nextAction: "Rerun the capture; if it keeps happening, report it to Explore with the session's link." });
}
} else if (controller === "argent" && sessionId && controlActions.has("springboard.restart")) {
// The bridge has already reset Argent's device helpers once when its reader stayed on the dark panel. On EAS the
// tool-server cannot be restarted, so the next step is SpringBoard, then the same fold and check again.
try { fold(); }
catch (error) {
if (toCiError(error).code !== "CONTROLLER_FOLD_UNVERIFIED") throw error;
say(`Argent kept reading the other panel after the fold; restarting SpringBoard and folding ${options.devicePose} again`);
simulatorControl(sessionEas, sessionId, "springboard.restart");
pause(8_000);
try { fold(); }
catch (retry) {
if (toCiError(retry).code !== "CONTROLLER_FOLD_UNVERIFIED") throw retry;
throw new CiError({ code: "CONTROLLER_READER_STUCK", stage: "session",
message: `Argent's accessibility reader kept reading the panel the fold turned off, after its device helpers were reset and SpringBoard was restarted.`,
nextAction: "Rerun the capture; if it keeps happening, report it to Explore: this session's Argent tool-server needs a restart that EAS cannot do yet.", cause: retry });
}
}
} else fold();
}
runtimeStage = "runtime";
@@ -690,9 +857,28 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
// (APP_NOT_READY). On this machine the capture runs that reader, so it recovers in two steps, each followed by one more
// open: a fresh tool-server, whose reader starts on the lit panel; then, as XcodeBuildMCP#537 found for this panel,
// SpringBoard restarted as well. The bridge's cached view of the device goes with the old server.
// On EAS the tool-server is the session's and must never be stopped, so the recovery there resets Argent's device
// helpers (reset-reader), then restarts SpringBoard as well, and then gives up with a reason rather than retrying.
const easArgentRecovery = !local && controller === "argent" && !!sessionId && options.platform === "ios";
for (let recovery = 0; ; recovery += 1) try { runtime = collect(); break; }
catch (error) {
if (!localArgent || recovery === 2 || toCiError(error).code !== "APP_NOT_READY") throw error;
if (toCiError(error).code !== "APP_NOT_READY") throw error;
if (easArgentRecovery && sessionId) {
if (recovery === 2 || recovery === 1 && !controlActions.has("springboard.restart")) throw new CiError({ code: "CONTROLLER_READER_STUCK", stage: "session",
message: "Argent's accessibility reader kept reading the panel the fold turned off, after its device helpers were reset"
+ `${recovery === 2 ? " and SpringBoard was restarted" : ""}.`,
nextAction: "Rerun the capture; if it keeps happening, report it to Explore: this session's Argent tool-server needs a restart that EAS cannot do yet.", cause: error });
if (recovery === 1) {
say("Argent still did not read the app; restarting SpringBoard, then resetting Argent's device helpers and opening the app again");
simulatorControl(sessionEas, sessionId, "springboard.restart");
// SpringBoard takes a moment to come back, and sends the app to the background; the next open brings it back.
(options.sleep ?? (milliseconds => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds); }))(8_000);
} else say("Argent did not read the app after starting it; resetting Argent's device helpers and opening the app again");
runner({ command: controllerCommand, args: ["reset-reader", "--session", CONTROLLER_SESSION, "--platform", options.platform, "--json"],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 2 * 60_000 });
continue;
}
if (!localArgent || recovery === 2) throw error;
say(recovery === 0 ? "Argent did not read the app after starting it; restarting Argent's tool-server and opening the app again"
: "Argent still did not read the app; restarting SpringBoard and Argent's tool-server and opening the app again");
stopLocalArgentServer(localArgent);
@@ -729,10 +915,11 @@ async function executeCiMap(options: CiMapOptions, setStage: (stage: string) =>
const passes: CaptureBundle["outcomes"][] = [];
const recordingTools = launchSetting === "off" ? undefined : options.recordingTools === undefined ? ffmpegRecordingTools() : options.recordingTools ?? undefined;
for (const [index, colorScheme] of colorSchemes.entries()) {
// Argent cannot switch the appearance yet (software-mansion/argent#1509): on EAS its single pass runs as the device
// starts, and on this machine the host switches it.
// Argent cannot switch the appearance yet (software-mansion/argent#1509): the host does, simctl or adb on this
// machine and serve-sim on an EAS iOS session; elsewhere its single pass runs as the device starts.
if (controller !== "argent") runner({ command: controllerCommand, args: [...appearanceArgs(colorScheme), "--session", CONTROLLER_SESSION, ...deviceArgs(runtime), "--platform", options.platform],
cwd: simulatorProject, environment: controllerEnvironment, timeoutMs: 60_000 });
else if (sessionId && controlActions.has("appearance.set")) simulatorControl(sessionEas, sessionId, "appearance.set", [colorScheme]);
else if (localSimulator) setLocalSimulatorAppearance({ runner, udid: localSimulator, scheme: colorScheme, cwd: simulatorProject, environment: restrictedEnvironment });
else if (localEmulator) setLocalEmulatorAppearance({ runner, serial: localEmulator, scheme: colorScheme, cwd: simulatorProject, environment: restrictedEnvironment });
// A scheme change recreates the Android activity in place, and the sheets it re-presents lose their inset; a
+42
View File
@@ -0,0 +1,42 @@
import { isRecord } from "./common.js";
/** Runs the pinned EAS CLI with these arguments; throws when it exits non-zero unless `allowFailure` is set. */
export type EasCommand = (args: string[], options?: { timeoutMs?: number; allowFailure?: boolean }) => { stdout: string; stderr?: string };
/**
* The host actions an EAS Simulator iOS session offers through `eas simulator:control` (serve-sim's actions, 0.10.0 and
* later for the ones Explore uses): an empty set when the session or the EAS CLI offers none, so a caller falls back to
* what it did before them. The session is always named by id, never taken from a `.env.eas-simulator` beside it.
*
* These are a fallback: what the session's controller can do itself (agent-device or Argent: fold, appearance, a
* reader reset) goes through the controller. Explore uses an action here only for what neither controller offers —
* approving a link scheme, restarting SpringBoard, and Argent's appearance (software-mansion/argent#1509).
*/
export function simulatorControlActions(eas: EasCommand, sessionId: string): Set<string> {
try {
const listed = eas(["simulator:control", "--list", "--id", sessionId, "--json", "--non-interactive"], { timeoutMs: 2 * 60_000, allowFailure: true });
const actions = JSON.parse(listed.stdout) as unknown;
return new Set(isRecord(actions) ? Object.keys(actions) : []);
} catch { return new Set(); }
}
/** Runs one `eas simulator:control` action on the session; eas-cli fills in the device. Throws with EAS's reason. */
export function simulatorControl(eas: EasCommand, sessionId: string, action: string, values: readonly string[] = []): void {
// Values follow `--` so one that starts with a dash is never read as a flag.
eas(["simulator:control", action, "--id", sessionId, "--json", "--non-interactive", "--", ...values], { timeoutMs: 2 * 60_000 });
}
/**
* Lets the app open its own links without iOS asking "Open in “App”?" first, like local captures do with simctl. A
* session without the action keeps the controllers' prompt handling; http and https never prompt and are skipped.
*/
export function approveSessionUrlSchemes(eas: EasCommand, sessionId: string, actions: ReadonlySet<string>, bundleId: string, schemes: readonly string[]): string[] {
if (!actions.has("app.approveUrlScheme")) return [];
const approved: string[] = [];
for (const scheme of new Set(schemes.map(value => value.toLowerCase()))) {
if (scheme === "http" || scheme === "https" || !/^[a-z][a-z0-9+.-]*$/.test(scheme)) continue;
simulatorControl(eas, sessionId, "app.approveUrlScheme", [bundleId, scheme]);
approved.push(scheme);
}
return approved;
}
+41 -11
View File
@@ -237,17 +237,7 @@ export function assertSimulatorSessionIdentity(
) {
throw new Error("eas simulator:get did not prove the exact expected simulator session");
}
// eas-cli 22.4.0 omits the `app` record; its `deviceRunSessionUrl` still binds the session
// to one exact owner and slug, so accept either proof but never neither.
const expectedSessionUrl = `https://expo.dev/accounts/${expectedProject.owner}`
+ `/projects/${expectedProject.slug}/simulator-sessions/${expectedSessionId}`;
const projectProven = isRecord(value.app)
? value.app.id === expectedProject.projectId
&& value.app.slug === expectedProject.slug
&& isRecord(value.app.ownerAccount)
&& value.app.ownerAccount.name === expectedProject.owner
: value.deviceRunSessionUrl === expectedSessionUrl;
if (!projectProven) {
if (!sessionProjectProven(value, expectedSessionId, expectedProject)) {
throw new Error("eas simulator:get did not prove the exact expected simulator session");
}
if (expectedConnection && !remoteConfigMatches(value.remoteConfig, expectedConnection)) {
@@ -255,6 +245,46 @@ export function assertSimulatorSessionIdentity(
}
}
/**
* eas-cli 22.4.0 omits the `app` record; its `deviceRunSessionUrl` still binds the session to one exact owner and
* slug, so either proof is accepted but never neither.
*/
function sessionProjectProven(value: Record<string, unknown>, sessionId: string, project: RepackProfile["projectIdentity"]): boolean {
const expectedSessionUrl = `https://expo.dev/accounts/${project.owner}/projects/${project.slug}/simulator-sessions/${sessionId}`;
return isRecord(value.app)
? value.app.id === project.projectId && value.app.slug === project.slug && isRecord(value.app.ownerAccount) && value.app.ownerAccount.name === project.owner
: value.deviceRunSessionUrl === expectedSessionUrl;
}
/**
* The status (ERRORED or STOPPED) of a session `eas simulator:get` shows EAS ended before Explore could use it, when it
* is provably this capture's own: the exact id, name, type, platform and project. Only such a session is replaced by a
* new one; anything less certain (undefined here) stays a handoff failure.
*/
export function endedOwnSimulatorSession(stdout: string, expected: { sessionId: string; sessionName: string; project: RepackProfile["projectIdentity"];
type: "agent-device" | "argent"; platform: Platform }): "ERRORED" | "STOPPED" | undefined {
let value: unknown;
try { value = JSON.parse(stdout); } catch { return undefined; }
return isRecord(value) && value.id === expected.sessionId && value.name === expected.sessionName && value.type === expected.type
&& value.platform === expected.platform.toUpperCase() && (value.status === "ERRORED" || value.status === "STOPPED")
&& sessionProjectProven(value, expected.sessionId, expected.project) ? value.status : undefined;
}
/**
* This project's sessions with exactly this name that EAS may still be starting or running, from
* `eas simulator:list --json`: their ids when every one is provably this project's, or undefined when the listing
* cannot be read or a session by that name cannot be proven Explore's, so a caller never assumes none exist.
*/
export function liveSimulatorSessionsNamed(stdout: string, sessionName: string, project: RepackProfile["projectIdentity"]): string[] | undefined {
let value: unknown;
try { value = JSON.parse(stdout); } catch { return undefined; }
if (!isRecord(value) || !Array.isArray(value.sessions)) return undefined;
const live = new Set(["NEW", "QUEUED", "STARTING", "IN_PROGRESS"]);
const named = value.sessions.filter((session): session is Record<string, unknown> => isRecord(session) && session.name === sessionName && live.has(String(session.status)));
if (named.some(session => typeof session.id !== "string" || !/^[A-Za-z0-9._-]{1,256}$/.test(session.id) || !sessionProjectProven(session, session.id, project))) return undefined;
return named.map(session => session.id as string);
}
/** The session's published controller endpoint is the one Explore holds: agent-device's daemon, or Argent's tool-server. */
function remoteConfigMatches(remoteConfig: unknown, connection: SimulatorConnection): boolean {
if (!isRecord(remoteConfig)) return false;
+15 -7
View File
@@ -474,7 +474,8 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
checks.push(config.mode === "agent"
? { step: 3, id: "mode", status: "pass", message: `Agent mode with ${config.agent!.provider} ${config.agent!.model}. Capture navigation uses the model and is billed to your ${config.agent!.provider} account.` }
: { step: 3, id: "mode", status: "pass", message: "Deterministic mode: capture replays config.yaml without a model, so it needs no API key and has no AI charges." });
if (runTargets(config, { controller: options.controller }).some(target => target.capture.controller === "argent")) checks.push(argentCheck(environment));
const argentTargets = runTargets(config, { controller: options.controller }).filter(target => target.capture.controller === "argent");
if (argentTargets.length) checks.push(argentCheck(environment, argentTargets.some(target => target.app.platform === "android" && target.capture.simulator !== "local")));
if (config.capture.launch !== "off") {
const ffmpeg = run("ffmpeg", ["-version"], project);
checks.push(ffmpeg.status === 0
@@ -630,13 +631,20 @@ export function summarizeCaptureCheck(plan: SourceCapturePlan, bundle: CaptureBu
* Capture the committed HEAD the way the baseline workflow does, with the local EAS login. This is
* the only doctor step that starts an EAS build and a simulator session.
*/
/** An Argent capture records one appearance, and fetches the pinned Argent release on first use. agent-device, the default, is not reported. */
function argentCheck(environment: NodeJS.ProcessEnv): DoctorCheck {
/**
* Argent fetches its pinned release on first use, and cannot switch the appearance itself (software-mansion/argent#1509):
* the host does, through `simulator:control` on an iOS EAS session or simctl and adb on this Mac. Only an Android EAS
* session has no host to ask, so its captures record one appearance. agent-device, the default, is not reported.
*/
function argentCheck(environment: NodeJS.ProcessEnv, androidOnEas: boolean): DoctorCheck {
const cached = controllerCached("argent", environment);
return { step: 3, id: "controller", status: "warn", code: "CONTROLLER_APPEARANCE_FIXED",
message: `Device controller: Argent ${ARGENT_VERSION} (${cached ? "cached on this machine" : "fetched from npm on the first capture, about 27 MB"}). `
+ "Argent cannot switch the simulator's appearance yet (software-mansion/argent#1509), so each capture records one appearance: the app's forced one, else light.",
nextAction: "Nothing to do unless you need dark-mode screenshots; use agent-device (the default) for those." };
const release = `Device controller: Argent ${ARGENT_VERSION} (${cached ? "cached on this machine" : "fetched from npm on the first capture, about 27 MB"}). `;
return androidOnEas
? { step: 3, id: "controller", status: "warn", code: "CONTROLLER_APPEARANCE_FIXED",
message: `${release}Argent cannot switch the appearance on an Android EAS Simulator session yet (software-mansion/argent#1509), so those captures record one appearance: the app's forced one, else light.`,
nextAction: "Nothing to do unless you need dark-mode screenshots on Android; use agent-device (the default) for those." }
: { step: 3, id: "controller", status: "pass",
message: `${release}The simulator's host switches the appearance, so every appearance the config asks for is captured.` };
}
export async function runCaptureCheck(options: { project: string; output: string; platform?: ExplorePlatform; controller?: string | undefined; simulator?: string | undefined; repack?: string | undefined; target?: string | undefined; environment?: NodeJS.ProcessEnv; runner?: CommandRunner; progress?: Progress }): Promise<CaptureCheckResult> {
+28 -16
View File
@@ -765,16 +765,40 @@ async function verifyDeployment(check: { origin: string; token: string; reports:
"Check EAS Hosting availability and rerun the deploy job.", { retryable: true, cause: error });
}
};
// What the token serves differs from what was deployed: a listing or report that does not match, or undefined.
const mismatch = async (): Promise<CiError | undefined> => {
for (const expected of check.reports) {
const report = await get(`/p/${check.token}/report.zip${expected.query}`);
const bytes = report.status === 200 ? new Uint8Array(await report.arrayBuffer()) : new Uint8Array();
if (report.status !== 200 || bytes.byteLength !== expected.bytes || createHash("sha256").update(bytes).digest("hex") !== expected.sha256) {
return deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not serve the exact report that was deployed.",
"Rerun the deploy job; the deployment's sealed key or ciphertext did not match.", { details: { status: report.status, report: expected.query } });
}
}
if (check.listing !== undefined) {
const list = await get(`/p/${check.token}/reports.json`);
const body = list.status === 200 ? await list.text() : "";
if (list.status !== 200 || body !== check.listing) return deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not list the targets that were deployed.",
"Rerun the deploy job; the deployment's report listing did not match.", { details: { status: list.status } });
}
return undefined;
};
const started = check.now();
let liveAfterMs = 0;
for (;;) {
// A browser's request: the token page negotiates, and anything that does not ask for HTML gets the Markdown index.
const shell = await get(`/p/${check.token}`, "text/html");
if (shell.status === 200 && (shell.headers.get("content-type") ?? "").startsWith("text/html")) { liveAfterMs = check.now() - started; break; }
const serving = shell.status === 200 && (shell.headers.get("content-type") ?? "").startsWith("text/html");
// An alias with a fixed token (the example report) serves the token page from the deployment it still points at, so
// it has moved only once it serves this deployment's listing and reports as well.
const stale = serving && check.alias ? await mismatch() : undefined;
if (serving && !stale) { liveAfterMs = check.now() - started; break; }
const waitedMs = check.now() - started;
if (waitedMs > check.timeoutMs) {
// An alias that does not serve the token page yet still points at an earlier deployment; the deployment itself not serving is a failed deployment.
if (check.alias) throw deployError("PREVIEW_ALIAS_BEHIND", `The alias ${check.origin} still answers HTTP ${shell.status} ${Math.round(waitedMs / 1000)} s after eas deploy returned.`,
if (check.alias) throw deployError("PREVIEW_ALIAS_BEHIND", stale
? `The alias ${check.origin} still serves an earlier deployment ${Math.round(waitedMs / 1000)} s after eas deploy returned.`
: `The alias ${check.origin} still answers HTTP ${shell.status} ${Math.round(waitedMs / 1000)} s after eas deploy returned.`,
"Nothing to do: the alias catches up on its own, and the next push verifies it again.", { retryable: true, details: { origin: check.origin, status: shell.status, waitedMs } });
throw deployError("PREVIEW_VERIFY_FAILED", `The hosted preview did not become available (HTTP ${shell.status}).`,
"Rerun the deploy job; if the deployment keeps failing verification, inspect it in the EAS Hosting dashboard.", { retryable: true, details: { origin: check.origin, status: shell.status, waitedMs } });
@@ -785,20 +809,8 @@ async function verifyDeployment(check: { origin: string; token: string; reports:
if (api.status !== 200 || !(api.headers.get("content-type") ?? "").startsWith("application/json")) {
throw deployError("PREVIEW_VERIFY_FAILED", `The hosted preview did not answer the agent API (HTTP ${api.status}).`, "Rerun the deploy job; if the deployment keeps failing verification, inspect it in the EAS Hosting dashboard.", { retryable: true });
}
for (const expected of check.reports) {
const report = await get(`/p/${check.token}/report.zip${expected.query}`);
const bytes = report.status === 200 ? new Uint8Array(await report.arrayBuffer()) : new Uint8Array();
if (report.status !== 200 || bytes.byteLength !== expected.bytes || createHash("sha256").update(bytes).digest("hex") !== expected.sha256) {
throw deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not serve the exact report that was deployed.",
"Rerun the deploy job; the deployment's sealed key or ciphertext did not match.", { details: { status: report.status, report: expected.query } });
}
}
if (check.listing !== undefined) {
const list = await get(`/p/${check.token}/reports.json`);
const body = list.status === 200 ? await list.text() : "";
if (list.status !== 200 || body !== check.listing) throw deployError("PREVIEW_VERIFY_FAILED", "The hosted preview did not list the targets that were deployed.",
"Rerun the deploy job; the deployment's report listing did not match.", { details: { status: list.status } });
}
// The deployment itself serves exactly what was deployed or it failed; the alias was checked while it was polled.
if (!check.alias) { const failure = await mismatch(); if (failure) throw failure; }
const other = check.token.endsWith("a") ? `${check.token.slice(0, -1)}b` : `${check.token.slice(0, -1)}a`;
// Errors name each probe by its shape: the near-miss token differs from the real one in its last character only.
for (const [path, shape] of [["/", "/"], [`/p/${other}`, "/p/<wrong token>"], [`/p/${other}/report.zip`, "/p/<wrong token>/report.zip"],
+1 -1
View File
@@ -3,4 +3,4 @@
* controller (`--package-version`), the daemon health check, and the screenshot diff tool must
* all be this version; each caller checks it by exact equality.
*/
export const AGENT_DEVICE_VERSION = "0.21.28";
export const AGENT_DEVICE_VERSION = "0.21.29-nightly.20261018.74";
+1 -1
View File
@@ -21,7 +21,7 @@ export type ControllerName = "agent-device" | "argent";
/** Each controller's npm release, the file Explore runs from it, and the integrity npm publishes for it. */
export const CONTROLLER_PACKAGES: Record<ControllerName, { name: string; version: string; bin: string; integrity: string }> = {
"agent-device": { name: "agent-device", version: AGENT_DEVICE_VERSION, bin: "bin/agent-device.mjs",
integrity: "sha512-uGEENVhPzSpIACrVlt16O1mloODWJyAemTCT0boDb4L006JXN2rG747u1TRoQJudOpdP/Pm2urxNRHeECLMLfg==" },
integrity: "sha512-7+ajWLr0J+8iLZ9q11ERbj6U14mC20umBK5BQQdw5aERA79yeXc3Ze6KmtvnILnWjEtoVkYQsXQasL8RL6Uatw==" },
argent: { name: "@swmansion/argent", version: ARGENT_VERSION, bin: "dist/cli.js",
integrity: "sha512-XXWlWZJlHKqnAvNx3RDhuiVFQOPqh5EDB76+mFAyqC2mutC6irzw03+M/6S/WQ+Dzz2IYOkEfOzQnOOdhrGgJg==" },
};
+17
View File
@@ -1,4 +1,5 @@
import { Buffer } from "node:buffer";
import { createRequire } from "node:module";
import { inflateSync } from "node:zlib";
import { STATUS_BAR_BAND_PERCENT } from "../contracts/capture.js";
@@ -7,6 +8,22 @@ export { STATUS_BAR_BAND_PERCENT };
/** Decoded RGBA pixels of one frame, as pngjs returns them (four bytes per pixel, row by row). */
export type DecodedFrame = { width: number; height: number; data: Buffer };
/**
* Whether a screenshot is a single flat colour: a capture-protected screen (black on Android), or a display that is lit
* but not drawn (an iPhone Duo's inner panel after its first fold on EAS). Every 97th pixel is enough to tell.
*/
export function solidColour(png: Buffer): boolean {
let frame: DecodedFrame;
try { frame = createRequire(import.meta.url.replace(/\?.*$/, ""))("pngjs").PNG.sync.read(png, { checkCRC: false }) as DecodedFrame; }
catch { return false; }
const { data } = frame;
if (data.length < 4) return false;
for (let offset = 0; offset + 3 < data.length; offset += 4 * 97) {
if (data[offset] !== data[0] || data[offset + 1] !== data[1] || data[offset + 2] !== data[2]) return false;
}
return true;
}
/**
* Whether a coordinate tap at normalized height `y` would act on a changed frame. Differences inside
* the status-bar band are ignored only when the tap lands below the band: a tap inside it acts on
+8 -1
View File
@@ -179,7 +179,14 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
}
return ok(identity(device));
}
if (command === 'fold') return ok({ action: 'fold', pose: request.args[1] });
if (command === 'fold') { device.pose = request.args[1]; return ok({ action: 'fold', pose: request.args[1] }); }
// The display a fold lit, as a pose check reads it: landscape when opened, and drawn.
if (command === 'screenshot' && request.args[1].endsWith('/pose.png')) {
const display = new PNG(device.pose === 'open' ? { width: 24, height: 16 } : { width: 16, height: 24 });
display.data[0] = 255;
writeFileSync(request.args[1], PNG.sync.write(display));
return ok({ path: request.args[1] });
}
if (command === 'install') {
const app = request.args[1];
device.build = platform === 'android' ? readFileSync(app, 'utf8') : readFileSync(join(app, 'build-id'), 'utf8');
+29 -3
View File
@@ -395,9 +395,18 @@ test("when Argent reads nothing while the prompt is up, Open is tapped from a sc
assert.equal(context.state.deepLinkPromptAccepted, true);
});
test("reset-reader stops the device's Argent helpers by its UDID and forgets what the old reader saw", async () => {
const state = { generation: 3, udid: UDID, screen: { width: 402, height: 874 }, refs: { e1: {} } };
const { calls, run } = harness("ios", { "stop-all-simulator-servers": { stopped: [`NativeDevtools:${UDID}`, `AXService:${UDID}`] } }, { state });
const reset = await run(["reset-reader", ...flags("ios")]);
assert.deepEqual(reset.json.data, { action: "reset-reader", stopped: [`NativeDevtools:${UDID}`, `AXService:${UDID}`] });
assert.deepEqual(calls, [{ tool: "stop-all-simulator-servers", args: { devices: [UDID] } }]);
assert.equal(state.screen, undefined); assert.equal(state.refs, undefined); assert.equal(state.generation, 4);
});
test("fold moves a foldable to a pose and forgets the old panel's geometry", async () => {
// Argent's fold answers with the panel it lit, in pixels; the inner panel is 2007 × 2853 (669 × 951 points).
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "ui-tree": [DUO_HOME, DUO_OPEN_EDIT_LANE],
const { run, calls, context } = harness("ios", { "list-devices": DUO_DEVICES, "ui-tree": [DUO_HOME, DUO_OPEN_EDIT_LANE], "stop-all-simulator-servers": { stopped: [] },
fold: { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 } });
await run(["snapshot", ...flags("ios")]);
const generation = context.state.generation;
@@ -407,12 +416,29 @@ test("fold moves a foldable to a pose and forgets the old panel's geometry", asy
const fold = calls.findIndex(call => call.tool === "fold");
assert.equal(calls.slice(0, fold).filter(call => call.tool === "ui-tree").length, reads, "nothing is read between the command and the fold");
assert.deepEqual(calls[fold].args, { udid: "74195B53-4DBC-4EAA-9991-F98E5BB86BA8", posture: "open" });
// The device's helpers are reset just before the fold, so the panel it lights is read by fresh ones.
assert.deepEqual(calls[fold - 1], { tool: "stop-all-simulator-servers", args: { devices: ["74195B53-4DBC-4EAA-9991-F98E5BB86BA8"] } });
assert.equal(context.state.screen, undefined);
assert.equal(context.state.refs, undefined);
assert.equal(context.state.generation, generation + 1);
assert.equal((await run(["fold", "sideways", ...flags("ios")])).json.error.code, "INVALID_ARGS");
});
test("a reader stuck on the dark panel after a fold is reset once more before the fold is called unverified", async () => {
const fold = { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 };
const stopped = { stopped: ["AXService:74195B53-4DBC-4EAA-9991-F98E5BB86BA8"] };
// Ten reads still in the cover panel's shape (as on EAS, 2026-10-17), then the inner panel once the helpers restart.
const recovers = harness("ios", { "list-devices": DUO_DEVICES, fold, "stop-all-simulator-servers": stopped, "ui-tree": [...Array(10).fill(DUO_HOME), DUO_OPEN_EDIT_LANE] });
assert.deepEqual((await recovers.run(["fold", "open", ...flags("ios")])).json.data, { action: "fold", pose: "open" });
assert.deepEqual(recovers.calls.filter(call => call.tool === "stop-all-simulator-servers").map(call => call.args), Array(2).fill({ devices: ["74195B53-4DBC-4EAA-9991-F98E5BB86BA8"] }));
const stuck = harness("ios", { "list-devices": DUO_DEVICES, fold, "stop-all-simulator-servers": stopped, "ui-tree": DUO_HOME });
const failed = await stuck.run(["fold", "open", ...flags("ios")]);
assert.equal(failed.json.error.code, "CONTROLLER_FOLD_UNVERIFIED");
assert.match(failed.json.error.message, /after its device helpers were reset/);
assert.equal(stuck.calls.filter(call => call.tool === "stop-all-simulator-servers").length, 2, "before the fold and once after, not in a loop");
});
test("an alert that is not the link prompt is left for capture to answer", async () => {
const other = { ...IOS_HOME, alertVisible: true, foregroundApp: "com.apple.springboard",
roots: [{ type: "Alert", label: "Delete all data?", frame: { x: 0.1, y: 0.4, width: 0.8, height: 0.2 }, children: [
@@ -534,9 +560,9 @@ test("a node its ancestor clips away is still reported hidden on iOS", () => {
test("a fold whose panel Argent never reads fails clearly instead of capturing the dark panel", async () => {
const lit = { activeScreen: 3, screen: { id: 3, panel: "inner panel", width: 2007, height: 2853 }, posture: "open", hingeAngle: 180 };
const blindClosed = { ...DUO_HOME, foregroundApp: undefined, roots: [{ role: "AXGroup", children: [] }] };
const late = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "ui-tree": [blindClosed, blindClosed, DUO_OPEN_EDIT_LANE] });
const late = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "stop-all-simulator-servers": { stopped: [] }, "ui-tree": [blindClosed, blindClosed, DUO_OPEN_EDIT_LANE] });
assert.equal((await late.run(["fold", "open", ...flags("ios")])).exitCode, 0, "a reader that catches up within the wait is fine");
const stuck = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "ui-tree": blindClosed });
const stuck = harness("ios", { "list-devices": DUO_DEVICES, fold: lit, "stop-all-simulator-servers": { stopped: [] }, "ui-tree": blindClosed });
const failed = await stuck.run(["fold", "open", ...flags("ios")]);
assert.equal(failed.json.error.code, "CONTROLLER_FOLD_UNVERIFIED");
assert.equal(stuck.calls.filter(call => call.tool === "fold").length, 1, "the session is not folded back and forth");
+221 -17
View File
@@ -112,6 +112,10 @@ async function fixture(t, settings = {}) {
const requests = [];
let current = '/'; let snapshots = 0; let sessionName; let screenshotAttempts = 0; let splashLeft = 0; let recordingPath = ''; let alert = null; let appearance = 'light'; let alertReads = 0;
let enteredName = false; let scrolledToContinue = false; let finishHidden = false; let wedgeCleared = false; let deviceLost = false; let relaunchedAfterForeign = false; let serverStarts = 0; let unreadableLeft = settings.unreadableAfterFold ?? 0;
// startsErrored / startsUnnamed: how many session starts EAS fails, after naming the session (it ERRORS) or before.
let starts = 0; let currentSession = 'session-1'; const erroredSessions = new Set(); let foldUnverifiedLeft = settings.foldUnverified ?? 0;
// blackAfterFold: the first so many folds of an EAS agent-device session light the panel but draw nothing.
let folds = 0;
const deviceName = settings.android ? 'Pixel 7' : 'iPhone 17 Pro';
const platform = settings.android ? 'android' : 'ios';
// A local simulator is the one the capture created, named for Explore.
@@ -182,6 +186,14 @@ async function fixture(t, settings = {}) {
appConfig: { name: 'Example', slug: 'example', owner: 'acme', ...(settings.userInterfaceStyle ? { userInterfaceStyle: settings.userInterfaceStyle } : {}), scheme: settings.noScheme ? undefined : 'sample',
...(settings.android ? { android: { package: 'com.example.app' } } : { ios: { bundleIdentifier: 'com.example.app' } }), extra: { eas: { projectId: PROJECT_ID } } } });
if (command === 'simulator:availability') return json({ available: settings.available !== false });
// controlActions: what the session's serve-sim offers through simulator:control (none unless a test names them).
if (command === 'simulator:control') {
assert.equal(value(request, '--id'), currentSession, 'simulator:control names the session');
if (request.args.includes('--list')) return json(Object.fromEntries((settings.controlActions ?? []).map(action => [action, { type: 'object' }])));
assert.ok((settings.controlActions ?? []).includes(request.args[1]), `${request.args[1]} is offered by the session`);
if (request.args[1] === 'appearance.set') appearance = request.args.at(-1);
return json({ id: currentSession, action: request.args[1], output: '' });
}
if (command === 'fingerprint:generate') return json({ hash: 'source-fingerprint' });
const buildMetadata = settings.buildMetadata ? { appVersion: '2.1.0', appBuildVersion: '42' } : {};
if (command === 'build:list') return json(settings.reuse ? [{ id: 'native-build', ...buildMetadata }] : []);
@@ -211,13 +223,23 @@ async function fixture(t, settings = {}) {
}
if (command === 'simulator:start') {
sessionName = value(request, '--name');
writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER + "EAS_SIMULATOR_SESSION_ID='session-1'\n" + (settings.argent
starts += 1; currentSession = `session-${starts}`;
if (starts <= (settings.startsUnnamed ?? 0)) { writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER); throw new Error('GraphQL request failed.'); }
if (starts <= (settings.startsErrored ?? 0)) erroredSessions.add(currentSession);
writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER + `EAS_SIMULATOR_SESSION_ID='${currentSession}'\n` + (settings.argent
? "ARGENT_TOOLS_URL='https://controller.example/session'\nARGENT_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n"
: "AGENT_DEVICE_DAEMON_BASE_URL='https://controller.example/session'\nAGENT_DEVICE_DAEMON_AUTH_TOKEN='" + DAEMON_TOKEN + "'\n"));
if (settings.startFailure) throw new Error('start reported failure after allocation');
if (erroredSessions.has(currentSession)) throw new Error('Simulator session errored while starting');
return { stdout: 'ready', stderr: '' };
}
if (command === 'simulator:get') return json({ id: 'session-1', name: sessionName, type: settings.argent ? 'argent' : 'agent-device', platform: settings.android ? 'ANDROID' : 'IOS', status: 'IN_PROGRESS',
// orphanFromFailedStart: a start that failed before naming the session had still created one.
if (command === 'simulator:list') return json({ sessions: settings.orphanFromFailedStart && value(request, '--name') === sessionName ? [{ id: 'orphan-1', name: sessionName,
type: settings.argent ? 'argent' : 'agent-device', status: 'STARTING', platform: 'IOS',
// orphanUnproven: the session by that name does not show it belongs to this project.
deviceRunSessionUrl: `https://expo.dev/accounts/${settings.orphanUnproven ? 'someone-else' : 'acme'}/projects/example/simulator-sessions/orphan-1` }] : [], pageInfo: {} });
if (command === 'simulator:get') return json({ id: value(request, '--id'), name: sessionName, type: settings.argent ? 'argent' : 'agent-device', platform: settings.android ? 'ANDROID' : 'IOS',
status: erroredSessions.has(value(request, '--id')) ? 'ERRORED' : 'IN_PROGRESS',
app: { id: settings.wrongProject ? 'foreign-project' : PROJECT_ID, slug: 'example', ownerAccount: { name: 'acme' } },
remoteConfig: { ...(settings.argent ? { toolsUrl: 'https://controller.example/session', toolsAuthToken: DAEMON_TOKEN }
: { agentDeviceRemoteSessionUrl: 'https://controller.example/session', agentDeviceRemoteSessionToken: DAEMON_TOKEN }),
@@ -226,7 +248,7 @@ async function fixture(t, settings = {}) {
...(settings.previewApiUrl ? { previewApiUrl: settings.previewApiUrl } : {}) } });
if (command === 'simulator:stop') {
if (settings.stopFailure) throw new Error('stop unavailable');
return json({ id: 'session-1', status: 'STOPPED' });
return json({ id: value(request, '--id'), status: 'STOPPED' });
}
}
if (request.command === 'fake-repack') {
@@ -241,6 +263,7 @@ async function fixture(t, settings = {}) {
// An Argent capture runs its per-run bridge in place of agent-device; the bridge answers in agent-device's envelopes.
if (request.command === 'fake-controller' || (settings.argent && request.command.endsWith('/argent-controller'))) {
if (command === '--version') return { stdout: settings.argent ? '0.29.0' : AGENT_DEVICE_VERSION, stderr: '' };
if (command === 'reset-reader') return json({ success: true, data: { action: 'reset-reader', stopped: ['AXService:device'] } });
if (command === 'open') {
// unreadableAfterFold: Argent's reader stayed on the outer panel, so the first app opens find no readable app.
if (unreadableLeft > 0 && !request.args[2]?.startsWith('sample://')) { unreadableLeft -= 1;
@@ -274,6 +297,11 @@ async function fixture(t, settings = {}) {
// An EAS session starts empty while the app is repacked; the controller installs the app from this machine.
if (command === 'install') { assert.ok(existsSync(request.args[1]), 'the repacked app is on this machine'); return ok({ installed: true, appBundleId: 'com.example.app' }); }
// agent-device 0.21.15 cannot read Xcode 27.1's hinge angle back, so a local fold reports a failure after folding.
// foldUnverified: the bridge's reader stayed on the dark panel through its own reset, for that many folds.
// The bridge exits non-zero, and the runner throws its structured error, as defaultRunner does.
if (command === 'fold') folds += 1;
if (command === 'fold' && foldUnverifiedLeft > 0) { foldUnverifiedLeft -= 1;
throw controllerCommandFailure(json({ success: false, error: { code: 'CONTROLLER_FOLD_UNVERIFIED', message: 'Argent kept reading the other panel after folding the device open, and after its device helpers were reset.' } }).stdout, 'fold'); }
if (command === 'fold') return settings.local ? json({ success: false, error: { code: 'COMMAND_FAILED', message: "CoreDevice reported no hinge angle sample: Unknown option '--device'" } })
: ok({ action: 'fold', pose: request.args[1] });
if (command === 'record' && settings.recording) {
@@ -347,6 +375,13 @@ async function fixture(t, settings = {}) {
if (request.args[1] === 'appearance') appearance = request.args[2];
return ok({ setting: request.args[1], value: request.args[2] });
}
// The display after a fold, as agent-device's screenshot shows it on EAS: in the pose's shape, drawn or black.
if (command === 'screenshot' && request.args[1]?.endsWith('/pose.png')) {
const display = new PNG(settings.devicePose === 'open' ? { width: 30, height: 20 } : { width: 20, height: 30 });
if (folds > (settings.blackAfterFold ?? 0)) display.data[0] = 255;
writeFileSync(request.args[1], PNG.sync.write(display));
return ok({ path: request.args[1] });
}
if (command === 'screenshot') {
screenshotAttempts += 1;
if (settings.firstScreenshotFails && screenshotAttempts === 1) throw new Error('temporary screenshot transport error');
@@ -468,7 +503,7 @@ test('an Argent capture starts an argent session, drives it through the bridge,
}
// Argent cannot switch appearance yet: one pass, no `settings appearance`, and a warning naming what was skipped.
assert.equal(f.requests.some(request => request.args[0] === 'settings'), false);
assert.ok(lines.some(line => /Argent cannot switch appearance yet .*capturing light only, skipped dark/.test(line)), lines.join('\n'));
assert.ok(lines.some(line => /Argent cannot switch appearance on this session; capturing light only, skipped dark/.test(line)), lines.join('\n'));
const map = JSON.parse(await readFile(join(f.options.outputDirectory, 'screen-map.json'), 'utf8'));
assert.equal(map.run.controller, 'argent');
assert.equal(map.run.environment.colorSchemes, undefined);
@@ -480,6 +515,150 @@ test('an Argent capture starts an argent session, drives it through the bridge,
assert.equal(execution.controllerPackageVersion, '0.29.0');
});
test('on an EAS iOS session with serve-sim\'s appearance.set, an Argent capture records every appearance', async t => {
const f = await fixture(t, { argent: true, userInterfaceStyle: 'automatic', controlActions: ['appearance.set'] });
const lines = [];
assert.equal((await runCiMap({ ...f.options, progress: line => lines.push(line) })).runStatus, 'complete');
assert.equal(lines.some(line => /Argent cannot switch appearance/.test(line)), false, lines.join('\n'));
assert.deepEqual(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'appearance.set').map(request => request.args.at(-1)), ['light', 'dark']);
const map = JSON.parse(await readFile(join(f.options.outputDirectory, 'screen-map.json'), 'utf8'));
assert.deepEqual(map.run.environment.colorSchemes, ['light', 'dark']);
});
test('an EAS iOS session approves the app\'s link scheme after installing it and before any link opens', async t => {
for (const argent of [false, true]) {
const f = await fixture(t, { argent, controlActions: ['app.approveUrlScheme'] });
assert.equal((await runCiMap(f.options)).runStatus, 'complete');
const approve = f.requests.findIndex(request => request.args[0] === 'simulator:control' && request.args[1] === 'app.approveUrlScheme');
assert.ok(approve >= 0, argent ? 'Argent' : 'agent-device');
assert.deepEqual(f.requests[approve].args.slice(f.requests[approve].args.indexOf('--') + 1), ['com.example.app', 'sample']);
const controller = f.requests.map((request, index) => ({ request, index })).filter(({ request }) => request.command === 'fake-controller' || request.command.endsWith('/argent-controller'));
const install = controller.find(({ request }) => request.args[0] === 'install');
const firstLink = controller.find(({ request }) => request.args[0] === 'open' && request.args[2]?.startsWith('sample://'));
assert.ok(install.index < approve && approve < firstLink.index, 'installed, then approved, then the first link');
}
// A session whose serve-sim predates the action keeps the controllers' prompt handling, and is not asked.
const older = await fixture(t, { argent: true });
assert.equal((await runCiMap(older.options)).runStatus, 'complete');
assert.equal(older.requests.some(request => request.args[0] === 'simulator:control' && !request.args.includes('--list')), false);
});
test('when Argent cannot read the app after a fold on EAS, the capture resets its device helpers, then restarts SpringBoard, and never stops the tool-server', async t => {
const actions = ['springboard.restart'];
for (const [unreadable, completes, resets, restarts] of [[1, true, 1, 0], [2, true, 2, 1], [3, false, 2, 1]]) {
const f = await fixture(t, { argent: true, devicePose: 'open', unreadableAfterFold: unreadable, controlActions: actions });
const lines = [];
const run = runCiMap({ ...f.options, progress: line => lines.push(line), sleep: () => {} });
if (completes) assert.equal((await run).runStatus, 'complete', `${unreadable} unreadable opens`);
else await assert.rejects(run, error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
assert.equal(f.requests.filter(request => request.command.endsWith('/argent-controller') && request.args[0] === 'reset-reader').length, resets);
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart').length, restarts);
assert.equal(f.requests.some(request => request.args.join(' ').includes('server stop')), false, 'the session\'s tool-server is never stopped');
assert.ok(lines.some(line => /resetting Argent's device helpers/.test(line)), lines.join('\n'));
}
// Without springboard.restart (an older serve-sim), a second unreadable open is reported after the reset alone.
const older = await fixture(t, { argent: true, devicePose: 'open', unreadableAfterFold: 2 });
await assert.rejects(runCiMap({ ...older.options, sleep: () => {} }), error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
});
test('when a fold on EAS leaves Argent reading the dark panel, the capture restarts SpringBoard and folds again, once', async t => {
for (const [unverified, completes] of [[1, true], [2, false]]) {
const f = await fixture(t, { argent: true, devicePose: 'open', foldUnverified: unverified, controlActions: ['springboard.restart'] });
const run = runCiMap({ ...f.options, sleep: () => {} });
if (completes) assert.equal((await run).runStatus, 'complete');
else await assert.rejects(run, error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
assert.equal(f.requests.filter(request => request.command.endsWith('/argent-controller') && request.args[0] === 'fold').length, 2);
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart').length, 1);
}
});
test('a session EAS ends while starting is replaced by a new one, under a name of its own, up to five times with a growing wait', async t => {
const f = await fixture(t, { startsErrored: 1 });
const lines = []; const waits = [];
const result = await runCiMap({ ...f.options, progress: line => lines.push(line), sleep: ms => { waits.push(ms); } });
assert.equal(result.runStatus, 'complete');
const started = f.requests.filter(request => request.args[0] === 'simulator:start').map(request => value(request, '--name'));
assert.equal(started.length, 2);
assert.notEqual(started[0], started[1], 'the new session has a name of its own');
assert.ok(lines.some(line => /EAS ended simulator session session-1 \(ERRORED\) before it was ready; starting a new EAS Simulator session in 10 s \(1\/5\)/.test(line)), lines.join('\n'));
assert.equal(lines.filter(line => /while the app is repacked/.test(line)).length, 1, 'only the first start runs beside the repack');
assert.equal(result.simulatorSessionId, 'session-2');
assert.ok(waits.includes(10_000));
// Five new sessions at most, waiting 10 s, 20 s, 40 s, 80 s and 120 s before them; then the failure to start is reported as one.
const always = await fixture(t, { startsErrored: 6 });
const backoff = [];
await assert.rejects(runCiMap({ ...always.options, sleep: ms => { if (ms >= 10_000) backoff.push(ms); } }),
error => error.code === 'SIMULATOR_START_FAILED' && /6 sessions ended before they were ready \(the last, session-6, ERRORED\)/.test(error.message)
&& error.details.endedSessions.length === 6 && error.details.attempts === 6);
assert.equal(always.requests.filter(request => request.args[0] === 'simulator:start').length, 6);
assert.deepEqual(backoff, [10_000, 20_000, 40_000, 80_000, 120_000]);
assert.equal(new Set(always.requests.filter(request => request.args[0] === 'simulator:start').map(request => value(request, '--name'))).size, 6, 'every session has its own name');
// One session that ended is a failure to start too, not a question of ownership.
const once = await fixture(t, { startsErrored: 6 });
await assert.rejects(runCiMap({ ...once.options, sleep: () => {}, runner: request => {
if (request.args[0] === 'simulator:start' && once.requests.filter(r => r.args[0] === 'simulator:start').length >= 1) throw new Error('Controller simulator:start exited with status 1: quota exhausted');
return once.options.runner(request);
} }), error => error.code === 'SIMULATOR_START_FAILED');
});
test('new sessions stay within 30 minutes of the first failed start, each start capped by what is left', async t => {
const f = await fixture(t, { startsErrored: 6 });
let clock = Date.parse('2026-10-18T00:00:00Z');
const timeouts = [];
await assert.rejects(runCiMap({ ...f.options, now: () => clock, sleep: ms => { clock += ms; }, runner: request => {
// Each start takes 10 minutes before EAS ends the session.
if (request.args[0] === 'simulator:start') { timeouts.push(request.timeoutMs); clock += 10 * 60_000; }
return f.options.runner(request);
} }), error => error.code === 'SIMULATOR_START_FAILED');
// The budget runs from the first failure, at 10:00, to 40:00. The start at 10:10 fits whole; those at 20:30 and 31:10
// get only what is left (19:30, then 8:50); after 41:10 none starts.
assert.deepEqual(timeouts, [20 * 60_000, 20 * 60_000, 19.5 * 60_000, (8 * 60 + 50) * 1000]);
});
test('Ctrl+C while waiting for a new session stops the review instead of starting one', async t => {
const f = await fixture(t, { startsErrored: 6 });
const controller = new AbortController();
await assert.rejects(runCiMap({ ...f.options, signal: controller.signal, sleep: () => controller.abort(new Error('interrupted')) }));
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length, 1);
});
test('a start that fails before naming a session stops any session of that name first, then starts a new one', async t => {
const f = await fixture(t, { startsUnnamed: 1, orphanFromFailedStart: true });
assert.equal((await runCiMap({ ...f.options, sleep: () => {} })).runStatus, 'complete');
const order = f.requests.map(request => request.args[0] === 'simulator:stop' && value(request, '--id') === 'orphan-1' ? 'stop-orphan' : request.args[0] === 'simulator:start' ? 'start' : undefined).filter(Boolean);
assert.deepEqual(order, ['start', 'stop-orphan', 'start']);
// The last failed start is accounted for as well, though no new session follows it.
const always = await fixture(t, { startsUnnamed: 6, orphanFromFailedStart: true });
await assert.rejects(runCiMap({ ...always.options, sleep: () => {} }), error => error.code === 'SIMULATOR_START_FAILED');
assert.equal(always.requests.filter(request => request.args[0] === 'simulator:stop' && value(request, '--id') === 'orphan-1').length, 6);
});
test('a session of that name Explore cannot prove is its own is never stopped or replaced', async t => {
const f = await fixture(t, { startsUnnamed: 1, orphanFromFailedStart: true, orphanUnproven: true });
await assert.rejects(runCiMap({ ...f.options, sleep: () => {} }), error => error.code === 'SIMULATOR_START_FAILED');
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length, 1);
assert.equal(f.requests.some(request => request.args[0] === 'simulator:stop'), false);
});
test('a session Explore cannot prove is its own is never replaced, even one that ERRORED', async t => {
const f = await fixture(t, { wrongProject: true, startsErrored: 1 });
await assert.rejects(runCiMap(f.options), error => /SESSION_HANDOFF_UNVERIFIED/.test(JSON.stringify(error)));
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:start').length, 1);
});
test('account failures to start are not retried; temporary ones and timeouts are', async t => {
for (const [message, retried] of [['GraphQL request failed: not authorized', false], ['quota exhausted', false], ['GraphQL request failed.', true], ['No simulator capacity for iPhone Duo', true]]) {
const f = await fixture(t);
let starts = 0;
const run = runCiMap({ ...f.options, sleep: () => {}, runner: request => {
if (request.args[0] === 'simulator:start' && ++starts === 1) { writeFileSync(join(request.cwd, '.env.eas-simulator'), HEADER); throw new Error(`Controller simulator:start exited with status 1: ${message}`); }
return f.options.runner(request);
} });
if (retried) assert.equal((await run).runStatus, 'complete', message); else await assert.rejects(run, error => error.code === 'SIMULATOR_START_FAILED', message);
assert.equal(starts, retried ? 2 : 1, message);
}
});
test('an Argent capture of an app pinned to dark is labelled dark and is not warned about', async t => {
const f = await fixture(t, { argent: true, userInterfaceStyle: 'dark' });
const lines = [];
@@ -489,20 +668,45 @@ test('an Argent capture of an app pinned to dark is labelled dark and is not war
assert.equal(execution.colorScheme, 'dark');
});
test('device.pose folds the device first, before the app is opened, read or captured', async t => {
for (const argent of [false, true]) {
const f = await fixture(t, { devicePose: 'open', argent });
assert.equal((await runCiMap(f.options)).runStatus, 'complete');
const controller = f.requests.filter(request => request.command === 'fake-controller' || request.command.endsWith('/argent-controller'));
const folds = controller.filter(request => request.args[0] === 'fold');
assert.equal(folds.length, 1);
assert.deepEqual(folds[0].args.slice(0, 2), ['fold', 'open']);
const foldAt = controller.indexOf(folds[0]);
// The fold comes first: the app is installed but not opened, read or captured before it, so the controller starts on the lit panel.
assert.deepEqual(controller.slice(0, foldAt).map(request => request.args[0]).filter(command => command !== '--version' && command !== 'install'), []);
// Argent's bridge is told the pose, so it captures the opened panel's landscape UI upright.
if (argent) for (const request of controller) assert.equal(request.environment.EXPLORE_ARGENT_POSE, 'open');
test('device.pose with Argent folds the device first, before the app is opened, read or captured', async t => {
const f = await fixture(t, { devicePose: 'open', argent: true });
assert.equal((await runCiMap(f.options)).runStatus, 'complete');
const controller = f.requests.filter(request => request.command.endsWith('/argent-controller'));
const folds = controller.filter(request => request.args[0] === 'fold');
assert.equal(folds.length, 1);
assert.deepEqual(folds[0].args.slice(0, 2), ['fold', 'open']);
const foldAt = controller.indexOf(folds[0]);
// The fold comes first: the app is installed but not opened, read or captured before it, so the controller starts on the lit panel.
assert.deepEqual(controller.slice(0, foldAt).map(request => request.args[0]).filter(command => command !== '--version' && command !== 'install'), []);
// Argent's bridge is told the pose, so it captures the opened panel's landscape UI upright.
for (const request of controller) assert.equal(request.environment.EXPLORE_ARGENT_POSE, 'open');
});
test('device.pose with agent-device on EAS opens the app, folds, and checks the display it lit', async t => {
const f = await fixture(t, { devicePose: 'open' });
assert.equal((await runCiMap({ ...f.options, sleep: () => {} })).runStatus, 'complete');
const controller = f.requests.filter(request => request.command === 'fake-controller').map(request => request.args[0] === 'screenshot' && request.args[1].endsWith('/pose.png') ? 'pose' : request.args[0]);
// agent-device folds only inside a session, so the app opens first; the fold's hinge readback is not trusted, the display is.
assert.deepEqual(controller.filter(command => command !== '--version' && command !== 'install').slice(0, 3), ['open', 'fold', 'pose']);
assert.equal(f.requests.some(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart'), false);
});
test('when an agent-device fold on EAS lights a black panel, the capture restarts SpringBoard, reopens the app and folds again, once', async t => {
for (const [black, completes] of [[1, true], [2, false]]) {
const f = await fixture(t, { devicePose: 'open', blackAfterFold: black, controlActions: ['springboard.restart'] });
const lines = [];
const run = runCiMap({ ...f.options, sleep: () => {}, progress: line => lines.push(line) });
if (completes) assert.equal((await run).runStatus, 'complete');
else await assert.rejects(run, error => JSON.stringify(error).includes('CONTROLLER_READER_STUCK'));
const controller = f.requests.filter(request => request.command === 'fake-controller');
assert.equal(controller.filter(request => request.args[0] === 'fold').length, 2);
assert.ok(controller.some(request => request.args[0] === 'open' && request.args.includes('--relaunch')), 'the app is reopened after SpringBoard');
assert.equal(f.requests.filter(request => request.args[0] === 'simulator:control' && request.args[1] === 'springboard.restart').length, 1);
assert.ok(lines.some(line => /did not draw the open display after the fold; restarting SpringBoard/.test(line)), lines.join('\n'));
}
// Without springboard.restart (an older serve-sim), a black panel is reported at once.
const older = await fixture(t, { devicePose: 'open', blackAfterFold: 1 });
await assert.rejects(runCiMap({ ...older.options, sleep: () => {} }), error => JSON.stringify(error).includes('CONTROLLER_FOLD_UNVERIFIED'));
});
test('a local simulator capture creates its own iOS simulator, installs the repacked app there, and deletes the simulator', async t => {
+6 -2
View File
@@ -639,8 +639,12 @@ test("doctor checks each target where it runs: local tools for local targets, EA
targets: { phone: { platform: "ios" }, cloud: { platform: "ios", device: "iPhone 17 Pro", simulator: "eas", controller: "argent" } } });
assert.deepEqual(devices(mixed), ["iPhone 17"]);
assert.equal(check(mixed, "eas-simulator")[0].status, "pass");
// The target's Argent is reported as a top-level one would be.
assert.equal(check(mixed, "controller")[0].code, "CONTROLLER_APPEARANCE_FIXED");
// The target's Argent is reported as a top-level one would be: on an iOS EAS session the host switches its appearance.
assert.equal(check(mixed, "controller")[0].status, "pass");
// Only Argent on an Android EAS session records a single appearance.
const android = await doctor({ ...baseConfig, targets: { phone: { platform: "ios" },
droid: { platform: "android", device: "pixel_7", bundleId: "com.example.app", easProfile: "explore-android", controller: "argent" } } });
assert.equal(check(android, "controller")[0].code, "CONTROLLER_APPEARANCE_FIXED");
// --simulator and --controller decide for every target, as they do in a capture.
const forced = await doctor({ ...baseConfig, targets: { phone: { platform: "ios", simulator: "local", controller: "argent" } } }, { simulator: "eas", controller: "agent-device" });
assert.deepEqual(devices(forced), []);
+1 -1
View File
@@ -130,7 +130,7 @@ function runtimeFor(side, map, expectedSamples = 3, capturedSamples = expectedSa
observationId: observation.id,
expectedSampleCount: expectedSamples,
controllerPackageVersion: "0.20.2",
easCliVersion: "25.0.0",
easCliVersion: "25.2.0",
},
runtime: {
kind: "eas-agent-device-raw",
+15 -1
View File
@@ -66,7 +66,7 @@ async function exportFixture(t, options) {
}
/** A fake EAS CLI plus a fake deployment: `deploy` captures the sealed report and .env, then serves them like the Worker would. */
function easFixture({ origin = "https://acme-explore--1lcbdcpwn3.expo.app", aliasOrigin = "https://acme-explore--bluesky.expo.app", accounts = ["brent-org"], failDeploy = false, aliasServes = true, existingComment } = {}) {
function easFixture({ origin = "https://acme-explore--1lcbdcpwn3.expo.app", aliasOrigin = "https://acme-explore--bluesky.expo.app", accounts = ["brent-org"], failDeploy = false, aliasServes = true, aliasListing, existingComment } = {}) {
let deploys = 0;
let latestComment = existingComment;
const calls = []; const captured = {};
@@ -107,6 +107,8 @@ function easFixture({ origin = "https://acme-explore--1lcbdcpwn3.expo.app", alia
? new Response("<!doctype html>", { status: 200, headers: { "content-type": "text/html; charset=utf-8" } })
: new Response("# Expo Explore report", { status: 200, headers: { "content-type": "text/markdown; charset=utf-8" } });
if (match[2] === "api/v1") return new Response(JSON.stringify({ kind: "pr-review" }), { status: 200, headers: { "content-type": "application/json; charset=utf-8" } });
// aliasListing: the alias still points at an earlier deployment of the same token and reports, listed the old way.
if (match[2] === "reports.json" && aliasListing && url.origin === aliasOrigin) return new Response(aliasListing, { status: 200, headers: { "content-type": "application/json; charset=utf-8" } });
if (match[2] === "reports.json") return new Response(JSON.stringify(captured.listing.map(({ path: _path, ...rest }) => rest)), { status: 200, headers: { "content-type": "application/json; charset=utf-8" } });
// Selection as the Worker does it: ?target= by id, ?platform= by id and then by platform, else the first.
const target = url.searchParams.get("target"), platform = url.searchParams.get("platform");
@@ -474,6 +476,18 @@ test("a fixture preview seals each platform's ZIP as is behind one alias and lis
assert.equal(logged.filter(line => /^::warning::The alias https:\/\/explore-viewer-pr--pr-12\.expo\.app still answers HTTP 404 \d+ s after eas deploy returned\. The pull request links the deployment https:\/\/acme-explore--1lcbdcpwn3\.expo\.app instead\./.test(line)).length, 1);
assert.ok(behind.requests.some(request => request.url.origin === "https://explore-viewer-pr--pr-12.expo.app"), "the alias was polled");
// The example report keeps one token and the same fixtures, so an alias still on the previous deployment serves the
// token page and the same report: only its listing (an older Viewer's) gives it away. That is an alias behind too.
const stale = easFixture({ aliasOrigin: "https://explore-viewer-pr--pr-12.expo.app", aliasListing: JSON.stringify([{ platform: "ios" }]) });
clock = now; logged.length = 0;
process.stderr.write = chunk => { logged.push(String(chunk)); return true; };
try {
linked = await deployFixturePreview({ reports: [{ platform: "ios", zipPath: join(root, "ios.zip") }], project: "explore-viewer-pr", owner: "brent-org", alias: "pr-12", token,
exportPath, environment: deployEnvironment, transport: stale.transport, run: stale.run, now: ticking, verifyTimeoutMs: 60_000 });
} finally { process.stderr.write = quiet; }
assert.equal(linked.previewUrl, `https://acme-explore--1lcbdcpwn3.expo.app/p/${token}`);
assert.equal(logged.filter(line => /^::warning::The alias https:\/\/explore-viewer-pr--pr-12\.expo\.app still serves an earlier deployment \d+ s after eas deploy returned\./.test(line)).length, 1);
await assert.rejects(deployFixturePreview({ reports: [{ platform: "ios", zipPath: join(root, "ios.zip") }, { platform: "ios", zipPath: join(root, "ios.zip") }],
project: "explore-viewer-pr", alias: "pr-12", exportPath, environment: deployEnvironment, transport: eas.transport, run: eas.run, verifyTimeoutMs: 1 }),
error => error.code === "PREVIEW_REPORTS_INVALID");
+1 -1
View File
@@ -60,7 +60,7 @@ function state(overrides = {}) {
phase: 'ready', pullRequest, mode: 'changes', executionMode: 'deterministic', configPath: '.expo-explore/config.yaml', links,
startedAt: Date.parse('2026-09-11T03:00:48Z'), updatedAt: Date.parse('2026-09-11T03:07:00Z'),
build: { appName: 'Example', appVersion: '1.4.0', appBuildNumber: '27', platform: 'ios', easProfile: 'explore', easBuildId: 'eas-build', reusedEasBuild: true },
runtime: { provider: 'eas-simulator', controller: 'agent-device', controllerPackageVersion: '0.20.2', easCliVersion: '25.0.0', platform: 'ios', deviceModel: 'iPhone 17', osVersion: '26.5', locale: 'en-US', orientation: 'portrait', colorScheme: 'light', sessionLifecycle: 'stopped' },
runtime: { provider: 'eas-simulator', controller: 'agent-device', controllerPackageVersion: '0.20.2', easCliVersion: '25.2.0', platform: 'ios', deviceModel: 'iPhone 17', osVersion: '26.5', locale: 'en-US', orientation: 'portrait', colorScheme: 'light', sessionLifecycle: 'stopped' },
capture: { planned: { base: 3, head: 3 }, done: { base: 3, head: 3 }, baseFromCache: true },
review: evidenceReview(),
evidence: {
+1 -1
View File
@@ -13,7 +13,7 @@ const BASE_SHA = "a".repeat(40);
const HEAD_SHA = "b".repeat(40);
const PNG = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=", "base64");
const EXECUTION = {
provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION, easCliVersion: "25.0.0",
provider: "eas-simulator", controller: "agent-device", controllerPackageVersion: AGENT_DEVICE_VERSION, easCliVersion: "25.2.0",
platform: "ios", deviceModel: "iPhone 17", osVersion: "26.0", locale: "en-US", orientation: "portrait",
colorScheme: "light", sessionLifecycle: "stopped",
};
+2 -2
View File
@@ -16,7 +16,7 @@ function execution(overrides = {}) {
provider: "eas-simulator",
controller: "agent-device",
controllerPackageVersion: AGENT_DEVICE_VERSION,
easCliVersion: "25.0.0",
easCliVersion: "25.2.0",
platform: "ios",
deviceModel: "iPhone 17",
osVersion: "26.0",
@@ -189,7 +189,7 @@ test("projects one map surface into the five runtime evidence groups", () => {
assert.equal(result.groups.interaction.transitionCount.value, 1);
assert.equal(result.groups.ui.landmarks.value.length, 0);
assert.equal(result.groups.environment.controllerPackageVersion?.value, AGENT_DEVICE_VERSION);
assert.equal(result.groups.environment.easCliVersion?.value, "25.0.0");
assert.equal(result.groups.environment.easCliVersion?.value, "25.2.0");
});
test("normalizes multi-line labels and treats only open parser gaps as truncation", () => {
+40
View File
@@ -0,0 +1,40 @@
import assert from "node:assert/strict";
import test from "node:test";
import { tsImport } from "tsx/esm/api";
const { approveSessionUrlSchemes, simulatorControl, simulatorControlActions } = await tsImport("../../src/capture/simulator-control.ts", import.meta.url);
function easFake(listed) {
const calls = [];
const eas = (args, options) => {
calls.push({ args, options });
if (args.includes("--list")) { if (listed instanceof Error) throw listed; return { stdout: listed }; }
return { stdout: "{}" };
};
return { calls, eas };
}
test("a session's control actions come from --list, by session id; an older session or CLI has none", () => {
const { calls, eas } = easFake(JSON.stringify({ "appearance.set": {}, "springboard.restart": {} }));
assert.deepEqual([...simulatorControlActions(eas, "session-1")], ["appearance.set", "springboard.restart"]);
assert.deepEqual(calls[0].args, ["simulator:control", "--list", "--id", "session-1", "--json", "--non-interactive"]);
assert.equal(calls[0].options.allowFailure, true);
assert.equal(simulatorControlActions(easFake("Unknown command simulator:control").eas, "session-1").size, 0);
assert.equal(simulatorControlActions(easFake(new Error("eas exited 1")).eas, "session-1").size, 0);
});
test("an action's values follow --, so one that starts with a dash is never read as a flag", () => {
const { calls, eas } = easFake("{}");
simulatorControl(eas, "session-1", "clipboard.write", ["--not-a-flag"]);
assert.deepEqual(calls[0].args, ["simulator:control", "clipboard.write", "--id", "session-1", "--json", "--non-interactive", "--", "--not-a-flag"]);
});
test("link schemes are approved once each, lowercased, never http or https, and only when the session offers it", () => {
const { calls, eas } = easFake("{}");
const approved = approveSessionUrlSchemes(eas, "session-1", new Set(["app.approveUrlScheme"]), "dev.example.app", ["Example", "example", "https", "exp+example", "not a scheme"]);
assert.deepEqual(approved, ["example", "exp+example"]);
assert.deepEqual(calls.map(call => call.args.slice(-2)), [["dev.example.app", "example"], ["dev.example.app", "exp+example"]]);
const none = easFake("{}");
assert.deepEqual(approveSessionUrlSchemes(none.eas, "session-1", new Set(), "dev.example.app", ["example"]), []);
assert.equal(none.calls.length, 0);
});