3 Commits

Author	SHA1	Message	Date
Sebastian Flajszer	1e69c90981	feat(ios-device): add physical iOS support (#944) ... # Physical iOS device support Try it now (cabled iPhone, unlocked, Developer Mode on): ```bash argent run list-devices # copy the 25-char UDID argent run launch-app --udid <UDID> --bundleId com.apple.Preferences ``` First launch builds and signs the on-device runner: 3 to 5 minutes, keep the phone unlocked. Every later start: seconds, from cache. No signing setup needed if an Apple ID is signed into Xcode; the team is detected from the keychain. ## What this adds - Physical iPhone support, on by default: a cabled iPhone simply appears in `list-devices`. iPhone-only: physical iPads are skipped at discovery. - 15 tools ported to hardware. Flows replay on device. - Zero-config signing from the keychain; `ARGENT_IOS_TEAM_ID` is an override, nothing is persisted. - Self-contained npm install: the runner's Swift sources ship in the package. New package `@argent/ios-device-runner` (an XCUITest bundle hosting an HTTP command server on the device), new tool-server backend under `src/utils/ios-device/`. - The one always-on cost: `list-devices` on macOS now runs physical discovery in parallel with the other platform probes, under the existing 8s devicectl timeout; off-macOS it early-returns. ## Suggested review order Rough estimate: half a day for the full pass. 1. `packages/ios-device-runner/PROTOCOL.md`, then `README.md` (wire contract and reliability model, ~15 min) 2. `packages/tool-server/src/utils/ios-device/` (devicectl, usbmux, team-detect, runner-build, runner-commands: the core) 3. `packages/tool-server/src/blueprints/ios-device-runner.ts` (service lifecycle, crash recovery) 4. Per-tool device arms and the capability gates (`ios-physical-device-classification.test.ts` is the ratchet) 5. Docs page, the two new skills, the Swift runner sources ## Requirements 1. macOS host with full Xcode (iOS platform installed); uses `xcrun devicectl` and `xcodebuild`. 2. An Apple ID signed into Xcode; automatic signing mints the runner's provisioning profile. 3. USB cable only. Wi-Fi is deliberately unsupported: the transport is usbmux, and a Wi-Fi-only device lists as `paired`, not `connected`. 4. iPhone paired with and trusting the Mac, Developer Mode on, A12/2018 or newer (modern 8+16-hex UDID, the CoreDevice floor). Legacy 40-hex UDIDs are not classified as iOS. 5. Signing resolves as: `ARGENT_IOS_TEAM_ID` in the tool-server's environment (explicit override, CI) -> keychain detection (newest identity first, memoized per server run, never persisted). One certificate: nothing to do. Several teams: newest wins; the first tool result names the pick, the runner-ups, and the override. No certificate: the error walks through Xcode > Settings > Accounts and Manage Certificates > + > Apple Development, then retry; it never names the env var, since a team id alone cannot sign. Bundle ids derive per team (`com.argent.runner.t<teamid>`). `ARGENT_IOS_RUNNER_PROJECT` overrides the project path for unusual layouts. Build artifacts cache under `~/.argent/ios-device-runner`, keyed by runner sources, Xcode/SDK version, and signing. A team with no registered devices self-heals: the failed generic build retries against the connected phone, which registers it. ## How it works 1. `xcrun devicectl` (CoreDevice) is the control plane: discovery, readiness, app lifecycle. Readiness gates on the wired transport, so an unplugged phone is refused before any build starts. 2. A signed XCUITest runner is built lazily with the resolved team, started via `xcodebuild test-without-building`, and parks as an HTTP command server for 24h. On an npm install the Xcode project is the copy shipped inside the package. 3. The listener binds to the device's loopback interface; the host reaches it over usbmuxd with a dependency-free `node:net` client. 4. Mutating commands are journaled by `commandId`; a lost reply is resolved by asking `status` for the journaled fate, never by replay (at-most-once delivery). 5. Routing hangs off `resolveDevice` UDID-shape classification plus a per-tool capability allowlist. CLI and MCP layers are untouched; outside tool-server, docs, and the runner package the diff is failure-code constants (registry), two agent skills plus rule updates (skills), the pack step (packages/argent), and the e2e smoke script. ## Supported tools | Tool | Status | Notes | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | launch-app | Supported | Plain `devicectl` launch. System UI (SpringBoard/Spotlight) registers a session only; no launch attempt. Carries a note when signing is not resolvable yet. | | restart-app | Supported | System UI bundle ids rejected before any device contact. | | reinstall-app | Supported | Same system UI pre-flight. | | screenshot | Supported | Served through the runner; device-wide, needs no registered app. (No host-side devicectl screenshot exists on any toolchain; that dead route was removed.) | | describe | Supported | AX tree snapshot via the runner. Snapshots the session app's process, so another process's dialogs are not in the tree. A backgrounded session app fails with an actionable error instead of being silently re-fronted. Focus polling is off for this source; typing uses a fixed settle. | | keyboard | Supported | Types into the focused element; typing with nothing focused is refused with "tap the text field first". `enter` and `backspace` are the named keys (both exist as software-keyboard characters; there is no per-keycode HID surface on hardware). Whitespace-only keys rejected, not silently "typed". | | gesture-tap | Supported | `clickCount > 1` dispatches as one native multi-tap gesture, not separate taps. | | gesture-swipe | Supported | Single-finger drag between two points. | | gesture-custom | Supported | Two shapes only: press-hold and straight single-finger drag. Second finger or `Move` waypoints rejected with authoring guidance, before any runner starts. | | button | Supported | `home`, `volumeUp`, `volumeDown`, `actionButton` (volume buttons are simulator-unavailable in the SDK, not device-unavailable). `power`/`appSwitch` have no public XCUIDevice API and reject before device contact; a button the model lacks gets a typed refusal via `hasHardwareButton`. | | await-ui-element | Supported | Polls the same runner snapshot describe returns; waits and taps see identical frames. Degrades to `cause: "unreadable"` with a note on a backgrounded app, never a raw throw. | | await-screen-idle | Supported | Same describe path; resolves not-settled instead of throwing, so a follow-up screenshot still runs. | | run-sequence | Supported | Outer gate only; each step pre-flights its own capability. | | open-url | Supported | devicectl launches the receiving app with the URL as its launch payload. http(s) defaults to Safari; any other scheme needs the new optional `bundleId` param (hardware cannot resolve a scheme's handler system-wide). | | screenshot-diff | Supported | Live captures through the runner (full-resolution, device-wide, no registered app needed); the diff itself runs on the host. Baselines are per device model/resolution; `rotation` is ignored on hardware. | Flows run through these tools; the device flow tree gets the same `subtreeText` hoisting as every other platform, so container-scoped `text` asserts work. ## Not supported (400 at the capability gate) 1. gesture-pinch, gesture-rotate: no two-finger coordinate API on hardware. Pinch/rotate flow directives also fail upfront with a clear error. 2. screen-recording-start/stop (video): simulator-only capture pipeline. 3. rotate, paste, shake, settings-permissions: simulator-only backends, not ported (paste also hits the iOS 16+ cross-app paste permission prompt). 4. native-devtools, debugger, profiler families: simulator-side instrumentation (DYLD injection does not exist on hardware). 5. Physical iPads: filtered at discovery for now. A test ratchet (`ios-physical-device-classification.test.ts`) keeps `apple.device` declarations in sync with the ported list. ## Core contracts 1. Observation never mutates the screen: a backgrounded session app makes `describe`/`await-*` fail with an error naming the three ways out (screenshot, launch-app, or launch-app com.apple.springboard). Mutating commands do re-front, and their result carries `reactivated: true`. 2. The runner listener is unauthenticated; mitigation is the loopback-only bind. 3. `list-devices` states: `connected` (cabled now, usable) vs `paired` (unreachable, never auto-bound). Wired transport alone decides; a Wi-Fi-migrated CoreDevice tunnel does not count. 4. The multi-team signing pick rides the first affected tool result as a one-shot note (the pre-existing notes channel). The `list-devices` result shape is unchanged from main: devices and avds, nothing else. 5. Rejections are typed 400 validation errors end to end, so a batch flow run skips one failing flow instead of aborting. Also: the runner is a first-class device-owned service (`stop-simulator-server` and `stop-all-simulator-servers` reap it, detached xcodebuild child included; a crashed runner respawns on the next call). A passcode-locked phone refuses launches; the devicectl 10002 hint also covers a pending system prompt on an unlocked phone. Build failures surface xcodebuild's own `error:` lines with signing hints (no registered devices, free-team app-id cap, missing provisioning, the `errSecInternalComponent` partition-list fix). An app XCTest reports as `.unknown` (a swipe-killed foreign app) is refused with launch-app guidance. Status-bar pinning is skipped on hardware; pixel-settle masks the top band. ## Testing - Unit coverage, hardware-independent: UDID classification and capability routing; usbmux framing and transport; devicectl list/hints parsing incl. the silent iPhone-only filter; keychain detection against real certificate fixtures; runner build/cache self-heals (poisoned cache, concurrent checkout, fresh-team retry); crash/journal recovery; the backgrounded-observation and reactivated contracts; keyboard guards incl. the not-focused refusal; system-UI pre-flight; per-tool device arms. - Manual smoke on a real device: `scripts/e2e-ios-physical-device.mjs`. ## Docs and skills 1. `features/physical-ios-devices.mdx`: the user-facing walkthrough (zero-config signing with the sign-in fallback, prerequisites, app-scoped model, troubleshooting). 2. `fundamentals/supported-platforms.mdx`: physical iPhones in the platform matrix (iPads not supported yet). 3. `reference/tools.mdx` and `reference/configuration.mdx`: list-devices states and the `ARGENT_IOS_TEAM_ID` override. 4. Two skills ship with the package via `argent init`: `argent-ios-device-setup` (setup ladder plus a troubleshooting table keyed to real error texts) and `argent-ios-device-interact` (the app-scoped hardware contract, supported subset with alternatives, gesture recipes, pitfalls). The agent rule and sibling skills route to them. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added experimental USB-connected physical iPhone support. * Physical iPhones now support discovery, app lifecycle actions, URL opening, accessibility snapshots, screenshots, taps, swipes, custom gestures, keyboard input, waits, flows, and screenshot comparisons. * Added automatic signing-team detection with optional `ARGENT_IOS_TEAM_ID` configuration. * Added clear handling for paired or unavailable devices and unsupported hardware actions. * **Documentation** * Added setup, troubleshooting, capability, and physical-device usage guidance. * Clarified that physical iPads and several simulator-only tools and gestures remain unsupported. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-03 14:33:11 +02:00
Ignacy Łątka	44b38d490e	fix(tool-server): inject Android keyboard/button over adb input (#449) (#455) ... ## What & why `keyboard` and `button` drive Android through the simulator-server's USB-HID transport (`pressKey` / `cmd:"button"`). The guest only receives those HID events when the AVD exposes a hardware keyboard (`hw.keyboard = yes`) — the default, but CI / headless AVDs are routinely created with `hw.keyboard = no` (and `hw.mainKeys = no`), where the guest **silently drops** them. Because that transport is fire-and-forget, both tools returned `{ typed }` / `{ pressed }` **success while injecting nothing**. This still affects current `main`: after the keyboard refactor, `makeAndroidImpl` routes Android **TV** to `adb input` but Android **phones/tablets** still to `typeSimulatorServer` (the HID path). Fixes #449 (found during 0.13.0 RC E2E testing on a `hw.keyboard=no` AVD — `argent-test-ci-repro`, the config CI uses). ## Change Route Android **phone/tablet** key / text / button injection through `adb shell input text` and `input keyevent` (new `utils/android-input.ts`), the same on-device transport Android TV and Vega already use: - **`keyboard`** — `platforms/android.ts` now sends the non-TV branch to a `typeAndroidPhone` helper (adb `input`); the Android-TV and iOS branches are untouched. - **`button`** — the Android branch presses via `injectAndroidKeycode`; iOS keeps the simulator-server HID path. `adb input` lands regardless of `hw.keyboard`, on emulators (any config) and physical devices alike, and a non-zero exit surfaces as a **thrown error** instead of a silent no-op — directly addressing the fire-and-forget concern already called out in the `button` tool. Touch gestures are unchanged. ## Verification - **Unit tests — 11/11 pass** (rebased on current `main`): new `keyboard-android.test.ts` (vocabulary parity vs `NAMED_KEYS`, `input text` shell-quoting incl. spaces, `input keyevent` mapping, empty-text no-op, newline rejection) + updated `button.test.ts` (Android `back` now asserts `KEYCODE_BACK` over adb). - **eslint** on the changed files: clean. - **Live tool-server** on a `hw.keyboard=no` AVD: the `keyboard` tool now issues `adb … shell input text '…'` (vs the RC's HID `pressKey`), and a failed inject **raises an error** rather than a fake success. The `adb input` path was independently observed typing/deleting on this exact AVD during RC testing (where the HID path silently no-op'd). - Note: a full `tsc --build` / whole-suite run couldn't be completed in my environment (the `argent-private` submodule isn't checked out, which breaks the npm workspace install, and `main` added upstream deps my base lacked). `platforms/android.ts` mirrors the existing `platforms/ios.ts` branch structure one-for-one, and the pre-rebase revision of this change passed `tsc --build` + eslint. CI here is authoritative for the full typecheck. ## Reviewer notes - `input text` receives the string as one shell-quoted argv token, so spaces are preserved verbatim; newlines are rejected (they'd truncate the `input` line) — callers use `key: "enter"`. - `keys` counts by codepoint, matching the tv/vega/simulator-server backends.	2026-07-10 12:51:24 +02:00
Ignacy Łątka	869f341735	fix(tool-server): reject platform-absent hardware buttons in the button tool (#283) ... ## Problem The `button` tool's description states that buttons not present on the target platform "are rejected with a clear error", but the implementation accepts any button in the enum on any device. On iOS, `button: "back"` (there is no hardware back key) returns `{ pressed: "back" }` — a **silent no-op reported as success**, so an automated caller believes a back-navigation happened when nothing did. Reproduced live on an iOS 18.5 simulator. ## Root cause `execute` (`tools/button/index.ts`) calls `sendCommand` and returns `{ pressed }` unconditionally, with no per-platform validation. The "rejected … from the backend" promise is also architecturally impossible: `sendCommand` (`utils/simulator-client.ts`) is fire-and-forget — it pushes a WebSocket frame and never reads a reply, so a backend rejection cannot surface to the caller. ## Fix Validate the requested button against a per-platform set in the tool layer (the platform is known synchronously from the UDID via `resolveDevice`), throwing the existing `UnsupportedOperationError` (→ HTTP 400) for buttons that don't exist on the device: - **iOS:** `home`, `power`, `volumeUp`, `volumeDown`, `appSwitch`, `actionButton` (no `back`) - **Android:** `home`, `back`, `power`, `volumeUp`, `volumeDown`, `appSwitch` (no `actionButton`) Cross-platform correctness is preserved — `back` still works on Android. The zod enum stays the union of both platforms' buttons (a flat enum can't express the dependency); the per-platform `Set` enforces the refinement. The description is reworded to match (validation lives in the tool, not "the backend"). ## Testing Adds `test/button.test.ts` — the tool previously had no test. ``` vitest run test/button.test.ts → 4 passed ``` Verified fail-before/pass-after: with `src/tools/button/index.ts` reverted to `main`, the two rejection tests fail (old code resolves `{ pressed: "back" }` / `{ pressed: "actionButton" }`); with the fix, all four pass. --------- Co-authored-by: Filip131311 <contact@filipkaminski.com>	2026-06-09 17:25:01 +02:00