@swmansion/argent 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {
@@ -20,6 +20,7 @@
     "prepack": "node scripts/sync-readme.cjs",
     "test": "vitest run",
     "test:watch": "vitest",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json",
     "observe": "node scripts/observe.cjs",
     "benchmark": "node scripts/benchmark.cjs",
     "postinstall": "node scripts/postinstall.cjs"
@@ -47,14 +48,14 @@
     "@argent/mcp": "file:../argent-mcp",
     "@argent/tools-client": "file:../argent-tools-client",
     "@clack/prompts": "^1.1.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.9.0",
     "@types/semver": "^7.7.1",
-    "esbuild": "^0.27.3",
+    "esbuild": "^0.28.0",
     "picocolors": "^1.1.1",
     "semver": "^7.7.4",
     "smol-toml": "^1.6.1",
-    "typescript": "^5.5.0",
-    "vitest": "^4.0.18",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
     "yaml": "^2.8.3"
   }
 }

package/rules/argent.md

@@ -36,6 +36,16 @@ If `describe` fails, **read the exact error before reacting**, follow the recove
 Before starting to interact with the app, read the `argent-device-interact` skill first.
 </tapping_rule>
 
+<device_selection_rule>
+Before booting, running, or interacting with any app, call `list-devices` first - prefer running devices.
+
+Decision order:
+
+1. **Explicit user intent** - choose the user named platform or device. Look for words "simulator" and "emulator".
+2. **Prefer a running device.** iOS simulators - state `Booted` and Android devices - `state: "device"` come first in `list-devices`.
+3. **Single-platform project:** (per `argent-environment-inspector` flags `is_native_ios`/`is_native_android`, or RN with only one platform configured) → boot that platform.
+   </device_selection_rule>
+
 <skill_reading_rule>
 <important>Always read relevant skills for guidance before executing argent-mcp tool - read skill_routing reference</important>
 </skill_reading_rule>
@@ -48,10 +58,10 @@ Before starting to interact with the app, read the `argent-device-interact` skil
 - Interaction tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`, `launch-app`, etc.) return a screenshot automatically.
   Call `screenshot` separately only for a baseline before any action or after a delay.
 - Always open apps with `launch-app` or `open-url` — never tap home screen icons.
-- Always use `run-sequence` when performing multiple sequential simulator actions where you don't need to observe the screen between steps. More in `argent-device-interact` skill.
+- Always use `run-sequence` when performing multiple sequential device actions where you don't need to observe the screen between steps. More in `argent-device-interact` skill.
 - When the session ends or the user says they are done: call `stop-all-simulator-servers`.
   If the user started Metro separately, ask whether to call `stop-metro` (specify the port if not 8081).
-- If tools provided by mcp-server are not sufficient and action can be done using `xcrun` or other commands, use the command. Examples: changing simulator options, performing simulator action such as lock, shake, etc.
+- If tools provided by mcp-server are not sufficient and action can be done using `xcrun`, `adb`, or other commands, use the command. Examples: changing device options, performing a device action such as lock, shake, etc.
 - When waiting for an action, do not call `screenshot` repeatedly without a proper wait mechanism. For example, six consecutive `screenshot` calls with no adequate delay between them will cause context bloat.
   </general_rules>
 
@@ -69,6 +79,9 @@ When `is_react_native` is true: load `argent-react-native-app-workflow` skill. U
 Load the matching skill before starting work and executing tools from argent-mcp — skills contain the full step-by-step
 procedure and edge-case handling for each workflow.
 
+PLATFORM DETECTION
+If the user did not specify a platform, call `list-devices` first and pick the booted target — do not default to iOS.
+
 iOS SIMULATOR SETUP
 Skill: `argent-ios-simulator-setup`
 When: Beginning a task that involves the iOS simulator, no simulator booted yet, need UDID or simulator-server.

package/scripts/postinstall.cjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-check
 "use strict";
 
 // Runs automatically after `npm install @swmansion/argent`.

package/skills/argent-create-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: argent-create-flow
-description: Record a reusable flow (scripted sequence of MCP tool calls) that can be replayed later with a single command. Use when the user asks to create, record, or build a flow, or to script a sequence of simulator actions.
+description: Record a reusable flow (scripted sequence of MCP tool calls) that can be replayed later with a single command. Use when the user asks to create, record, or build a flow, or to script a sequence of device actions.
 ---
 
 ## 1. Overview

package/skills/argent-device-interact/SKILL.md

@@ -24,7 +24,7 @@ Use `list-devices` to get a target id. Results are tagged with `platform` (`ios`
 3. **Use `gesture-swipe` for lists/scrolling**, not `gesture-custom`, unless you need non-linear movement. Consider whether you need multiple swipes, if yes - use `run-sequence`.
 4. **Tap a text field before typing** — on iOS try `paste` first then fall back to `keyboard`; on Android use `keyboard` directly (`paste` is iOS-only).
 5. **Coordinates are normalized** — always 0.0–1.0, not pixels.
-6. **For native iOS app navigation, prefer `describe` first.** It works on any screen without app restart. Do not navigate from screenshots on regular in-app screens unless `describe` failed to expose a reliable target. Use `native-describe-screen` only when you need app-scoped UIKit properties.
+6. **For app navigation, prefer `describe` first.** It works on any screen without app restart. Do not navigate from screenshots on regular in-app screens unless `describe` failed to expose a reliable target. Use `native-describe-screen` only when you need app-scoped UIKit properties.
 
 ## 3. Opening Apps
 

package/skills/argent-ios-simulator-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: argent-ios-simulator-setup
-description: Set up and connect to an iOS simulator using argent MCP tools. Use when starting a new session, booting a simulator, getting a simulator UDID, or before any simulator interaction task.
+description: Set up and connect to an iOS simulator using argent MCP tools. Use when starting a new session, booting an iOS simulator, getting an iOS UDID, or before any iOS simulator interaction task.
 ---
 
 ## 1. Setup Steps

package/skills/argent-metro-debugger/SKILL.md

@@ -32,10 +32,10 @@ One Metro port can serve multiple connected devices (e.g. two simulators on `loc
 
 ### Reload & recovery
 
-| Tool                    | Purpose                                                                                  |
-| ----------------------- | ---------------------------------------------------------------------------------------- |
-| `debugger-reload-metro` | Reload all connected apps (like pressing "r" in Metro terminal). Needs a CDP target.     |
-| `restart-app`           | Terminate and relaunch the app by UDID and bundleId. Use when app lost Metro connection. |
+| Tool                    | Purpose                                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------------------- |
+| `debugger-reload-metro` | Reload all connected apps (like pressing "r" in Metro terminal). Needs a CDP target.          |
+| `restart-app`           | Terminate and relaunch the app by device id and bundleId. Use when app lost Metro connection. |
 
 ### Inspection & console
 
@@ -70,7 +70,7 @@ Applies to both `debugger-component-tree` and `debugger-inspect-element`. Set to
 ## 4. Golden Rules
 
 1. **`debugger-status` first when something fails** — it runs discovery, connection, and returns diagnostics.
-2. **"No CDP targets" → get the app to connect to Metro** — use `restart-app` on simulator, then retry `debugger-status`.
+2. **"No CDP targets" → get the app to connect to Metro** — use `restart-app` on the device, then retry `debugger-status`.
 3. **Never assume one failure is permanent** — follow recovery steps before asking the user. For starting Metro and full failure recovery, see `argent-react-native-app-workflow` and `references/failure-scenarios.md`.
 
 ---
@@ -120,7 +120,7 @@ When reading from the log file:
 | Diagnose / check connection   | `debugger-status`                                                   |
 | Connect to Metro CDP          | `debugger-connect`                                                  |
 | Reload JS (already connected) | `debugger-reload-metro`                                             |
-| Relaunch app on simulator     | `restart-app`                                                       |
+| Relaunch app on device        | `restart-app`                                                       |
 | Inspect component at point    | `debugger-inspect-element`                                          |
 | Full component tree           | `debugger-component-tree`                                           |
 | Console log overview          | `debugger-log-registry` (summary + log file path for `Grep`/`Read`) |

package/skills/argent-metro-debugger/references/failure-scenarios.md

@@ -6,5 +6,5 @@ When a debugger tool fails, use **`debugger-status`** first to diagnose. Then ma
 | ---------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Metro not running**              | Error contains: `Metro at port 8081 is not running (got: ...)`                             | **Start Metro yourself** unless the user asked you not to: scan the workspace configuration and run the appropriate command to start Metro in the background (by default `npx react-native start` or `npx expo start`). Wait for Metro to be ready, then retry `debugger-connect` or `debugger-status`. If you cannot determine the project root, ask the user. |
 | **Metro not standard**             | Error contains: `Metro at port 8081 did not return X-React-Native-Project-Root header`     | Something on that port is not the standard React Native Metro server. Try starting Metro yourself from the app's project root using the command resolution above. If you cannot determine the correct root or the problem persists, inform the user what you found and what you tried.                                                                          |
-| **App not connected**              | Error contains: `Metro at port 8081 has no CDP targets — is a React Native app connected?` | 1) Confirm the app is running on simulator or device. 2) If simulator: use `restart-app` with the app's UDID and bundleId to relaunch so it connects to Metro. 3) Wait a few seconds for the bundle to load. 4) Retry `debugger-status`. Do **not** use `debugger-reload-metro` to fix this — it also requires at least one target.                             |
-| **Was connected, then tool fails** | Any debugger tool fails with a connection or disconnect error after it was working         | The app may have crashed or been closed. Use `restart-app` (simulator) to relaunch the app, then call `debugger-connect` again to pick up the fresh `logicalDeviceId` (UDID may change for booted-fresh simulators), and use that new `device_id` on all subsequent calls.                                                                                      |
+| **App not connected**              | Error contains: `Metro at port 8081 has no CDP targets — is a React Native app connected?` | 1) Confirm the app is running on the device. 2) Use `restart-app` with the app's device id and bundleId to relaunch so it connects to Metro. 3) Wait a few seconds for the bundle to load. 4) Retry `debugger-status`. Do **not** use `debugger-reload-metro` to fix this — it also requires at least one target.                                               |
+| **Was connected, then tool fails** | Any debugger tool fails with a connection or disconnect error after it was working         | The app may have crashed or been closed. Use `restart-app` to relaunch the app, then call `debugger-connect` again to pick up the fresh `logicalDeviceId` (may change for booted-fresh simulators), and use that new `device_id` on all subsequent calls.                                                                                                       |

package/skills/argent-react-native-app-workflow/SKILL.md

@@ -43,22 +43,22 @@ Do NOT default to `npx react-native start` or `npx react-native run-ios` without
 
 In a **separate** terminal (Metro keeps running in the first):
 
-**Use the project's custom build/run script if one exists** (e.g. `npm run ios`, `npm run android`, `yarn ios:debug`). Only fall back to the default if no custom scripts are defined:
+**Use the project's custom build/run script if one exists** (e.g. `npm run ios`, `npm run android`, `yarn ios:debug`). Only fall back to the defaults below if no custom scripts are defined.
+
+**Pass the target device explicitly** — derive it from `list-devices` (see `<device_selection_rule>`):
 
 ```bash
-npx react-native run-ios       # iOS
-npx react-native run-android   # Android
+npx react-native run-ios --simulator="<name>"        # iOS (or --udid <UDID>)
+npx react-native run-android --deviceId=<adb-serial> # Android
 ```
 
-Optional: specify the target device, e.g. `npx react-native run-ios --simulator="iPhone 16"` or `npx react-native run-android --deviceId=<serial>`.
-
 **Android only**: after install, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops.
 
 **Agent checklist:**
 
 - [ ] Metro is already running and shows "ready"
 - [ ] Command run from project root
-- [ ] If the device isn't booted: use `boot-device` with the iOS `udid` or Android `avdName`. Refer to the `argent-ios-simulator-setup` / `argent-android-emulator-setup` skill.
+- [ ] If the device isn't booted yet: use `boot-device` with the iOS `udid` or Android `avdName`. Refer to the `argent-ios-simulator-setup` / `argent-android-emulator-setup` skill.
 - [ ] Android: `adb -s <serial> reverse tcp:8081 tcp:8081` done.
 
 ---
@@ -233,12 +233,13 @@ If the user's intent is ambiguous (run existing tests, write new tests, or find
 
 ## Related Skills
 
-| Skill                          | When to use                                                                     |
-| ------------------------------ | ------------------------------------------------------------------------------- |
-| `argent-ios-simulator-setup`   | Initial simulator boot and connection setup                                     |
-| `argent-device-interact`       | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator  |
-| `argent-metro-debugger`        | Full Metro CDP debugging: component inspection, console logs, JS evaluation     |
-| `argent-react-native-profiler` | Profiling performance, finding re-render issues, CPU hotspots                   |
-| `argent-test-ui-flow`          | Interactive UI testing with automatic screenshot verification after each action |
+| Skill                           | When to use                                                                     |
+| ------------------------------- | ------------------------------------------------------------------------------- |
+| `argent-ios-simulator-setup`    | Initial iOS simulator boot and connection setup                                 |
+| `argent-android-emulator-setup` | Initial Android emulator boot and connection setup                              |
+| `argent-device-interact`        | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator  |
+| `argent-metro-debugger`         | Full Metro CDP debugging: component inspection, console logs, JS evaluation     |
+| `argent-react-native-profiler`  | Profiling performance, finding re-render issues, CPU hotspots                   |
+| `argent-test-ui-flow`           | Interactive UI testing with automatic screenshot verification after each action |
 
 Ask the user before running tests: confirm which test suite (unit, E2E, or both), whether to use existing CI commands, and whether they want you to run existing tests, write new ones, or explore test cases yourself.

package/skills/argent-react-native-optimization/SKILL.md

@@ -13,9 +13,9 @@ description: Optimizes a React Native app by profiling first to find real bottle
 - **Fix** — apply one fix. Validate with `debugger-evaluate` before committing.
 - **Re-measure** — report whether the target metric improved, regressed, or stayed flat. Check for regressions in other areas. If no net benefit or unacceptable tradeoffs, revert.
 - **Profile for discovery, not only verification.** Use the profiler to find issues static analysis missed, not only to confirm fixes.
-- **One fix per cycle for architectural changes.** Mechanical batch fixes (inline styles, index keys) can be grouped — re-profile once after the batch. When the measurement involves simulator interaction, record it as a flow (`argent-create-flow` skill) before the first run so all subsequent cycles replay identical steps.
+- **One fix per cycle for architectural changes.** Mechanical batch fixes (inline styles, index keys) can be grouped — re-profile once after the batch. When the measurement involves device interaction, record it as a flow (`argent-create-flow` skill) before the first run so all subsequent cycles replay identical steps.
 - **React Compiler**: if `react-profiler-analyze` reports `reactCompilerEnabled: true`, do NOT propose `useCallback`/`useMemo`/`React.memo` unless you confirmed compiler bail-out via `react-profiler-fiber-tree` (absent `useMemoCache`).
-- **Sub-agents**: Phases 1–2 dispatch sub-agents — one per file for lint results, one per checklist item for semantic. Sub-agents CANNOT touch the simulator - all profiling and E2E verification must happen in the main agent.
+- **Sub-agents**: Phases 1–2 dispatch sub-agents — one per file for lint results, one per checklist item for semantic. Sub-agents CANNOT touch the device - all profiling and E2E verification must happen in the main agent.
 
 ## Pipeline
 

package/skills/argent-test-ui-flow/SKILL.md

@@ -7,7 +7,9 @@ description: Autonomously test an app UI (iOS or Android) by running interact-sc
 
 The interaction tool names are identical on iOS and Android — `gesture-tap`, `gesture-swipe`, `describe`, `screenshot`, `launch-app`, etc. — and the tool-server auto-dispatches based on the `udid` you pass (UUID-shape → iOS, adb serial → Android).
 
-Get a `udid` via:
+**Before testing, resolve which device to test on.** Call `list-devices` and follow `<device_selection_rule>`: prefer a running device on any platform;
+
+Once a platform is chosen, the per-platform setup skill takes over:
 
 | Platform | Setup skill                     | Find devices with                                           |
 | -------- | ------------------------------- | ----------------------------------------------------------- |