@swmansion/argent 0.25.1-next.9 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.25.1-next.9",
+  "version": "0.25.1",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/skills/argent-android-emulator-setup/SKILL.md

@@ -15,7 +15,7 @@ Verify with `adb version` and `emulator -list-avds`.
 
 1. **Find a ready device** — call `list-devices`. Filter for entries with `platform: "android"`. Ready devices (`state: "device"`) come first. Pick the first `serial` (e.g. `emulator-5554`) unless the user specified one.
 2. **Boot if needed** — if nothing Android is ready, call `boot-device` with `avdName: <name>` from the same call's `avds` list. The tool transparently picks hot vs cold boot: it probes the AVD's `default_boot` snapshot, restores it under a tight deadline when usable, and falls back to a full cold boot otherwise. Hot path is typically ~30s; cold path takes 2–10 min. On any stage failure the tool kills the emulator process it started so your next call starts from a clean state.
-3. **Metro (for React Native)** — once a device is up, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the device can reach Metro on your host. Repeat if the device restarts. See the `argent-metro-debugger` skill.
+3. **Metro (for React Native)** — once a device is up, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the device can reach Metro on your host. Repeat if the device restarts.
 
 ## 3. Using the device
 

package/skills/argent-create-flow/references/flow-yaml.md

@@ -111,7 +111,7 @@ Scopes can combine and nest, with at most six scope keys. Use strict selectors f
 
 Directives stop the flow on failure and skip later steps. The available directives are `launch`, `tap`, `long-press`, `swipe`, `type`, `scroll-to`, `pinch`, `rotate`, `await`, `assert`, `wait`, `snapshot`, `run`, `script`, `when`, `echo`, and `tool`.
 
-Use the launch map for cross-platform flows. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. A launch that declares no id for the run's platform is an error, not a cue to switch platforms. On iOS, a successful launch also pins later tree reads to that app until the next raw `tool:` step, so read [The runner tree is not the discovery tree](#the-runner-tree-is-not-the-discovery-tree) when a read describes the wrong screen.
+Use the launch map for cross-platform flows. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. A launch that declares no id for the run's platform is an error, not a cue to switch platforms. A run on a remote simulator uses the `ios:` id, or the `native:` id when the map has no `ios:` key, so no flow needs a key for a remote run. On iOS, a successful launch also pins later tree reads to that app until the next raw `tool:` step, so read [The runner tree is not the discovery tree](#the-runner-tree-is-not-the-discovery-tree) when a read describes the wrong screen.
 
 ```yaml
 - launch: { native: com.acme.app, chromium: ../../app }
@@ -219,7 +219,7 @@ Use `when:` only for optional setup or an interstitial that reconverges:
     - tap: { text: Got it }
 ```
 
-The guard accepts one `exists`, `visible`, `hidden`, or `text` condition, or `{ platform: ios|android|chromium|vega }`. UI guards use the short assert grace and reject `timeout`. There is no `else` or per-step `optional`. Put separate behavioral paths in separate flows. Never place a required acceptance check inside `when:`.
+The guard accepts one `exists`, `visible`, `hidden`, or `text` condition, or `{ platform: ios|android|chromium|vega }`. A run on a remote simulator matches `ios`. UI guards use the short assert grace and reject `timeout`. There is no `else` or per-step `optional`. Put separate behavioral paths in separate flows. Never place a required acceptance check inside `when:`.
 
 ## Composition and platform limits
 
@@ -249,13 +249,13 @@ If a script fails, check its changes before you retry.
 
 ## Snapshots and standalone runs
 
-`argent flow run <name> [--device <id>] [--platform ios|android|chromium|vega] [--update-baselines] [--output <dir>] [--json]` runs without an LLM and exits non-zero on failure.
+`argent flow run <name> [--device <id>] [--platform ios|android|chromium|vega|ios-remote] [--update-baselines] [--output <dir>] [--json]` runs without an LLM and exits non-zero on failure.
 
 A screenshot is human evidence. A `snapshot:` is executable visual verification. A missing baseline or excessive mismatch fails. A `cropOn` size change also fails. Use snapshots for color, layout, size, spacing, typography, clipping, overflow, images, icons, or stable component appearance. Use full screen for global changes and `cropOn` for one component.
 
 Do not use a snapshot as the only proof of navigation, persistence, data, accessibility state, logs, or network behavior. Avoid unstable timestamps, live data, ads, animation, and device drift. First establish deterministic state, identity, and readiness.
 
-Baselines live under `.argent/flows/__baselines__/<flow>/` and are keyed by platform and full-capture geometry; `cropOn` also contributes its selector. Seed from a known-good state with `--update-baselines`. Inspect every baseline and require user review. Do not commit it yourself. Baseline creation or update is not a test pass. Never update a baseline only to make a diff pass. The default `maxMismatch` is 0.5 percent.
+Baselines live under `.argent/flows/__baselines__/<flow>/` and are keyed by platform and full-capture geometry; `cropOn` also contributes its selector. A run on a remote simulator uses `ios` in the key, so it uses the same baseline as a local iOS run with the same capture geometry. Seed from a known-good state with `--update-baselines`. A run on a remote simulator with `--update-baselines` rewrites the same baseline file that a local run uses, and its step reason says that a remote simulator wrote it. Inspect every baseline and require user review. Do not commit it yourself. Baseline creation or update is not a test pass. Never update a baseline only to make a diff pass. The default `maxMismatch` is 0.5 percent.
 
 Pin `--platform` and `--device` for iOS, Android, or Vega. For Chromium the device class is the window's own pixel size, which the app sets and no launch argument changes: pass `--platform chromium` and omit `--device` so the runner boots the declared app path instead of attaching to a running window of another size. A window sized from host or session state produces a key CI cannot reproduce, and the step fails for a missing baseline. The runner pins mobile status bars during visual runs. `--output <dir>` writes failed baseline, current, and diff images under `<dir>/<flow>/` for CI artifact upload.
 

package/skills/argent-create-flow/references/reliability-and-recovery.md

@@ -74,11 +74,11 @@ A normally injectable app that is broken in the environment gets the same coordi
 
 While the required source is down, selector failures and raw-point capture are void. Restore the source and re-record affected taps.
 
-| Platform | Symptom                          | Recovery                                               |
-| -------- | -------------------------------- | ------------------------------------------------------ |
-| Android  | Cannot reach the devtools helper | Unlock the device, allow `adb install -t`, and rerun   |
-| Chromium | No reachable CDP session         | Boot again with `electronAppPath` and remote debugging |
-| Vega     | Toolkit returns no page source   | Relaunch an app built with automation support          |
+| Platform | Symptom                                | Recovery                                                                         |
+| -------- | -------------------------------------- | -------------------------------------------------------------------------------- |
+| Android  | Cannot reach the argent android helper | Argent reinstalls it once; if it persists, read the device's reason in the error |
+| Chromium | No reachable CDP session               | Boot again with `electronAppPath` and remote debugging                           |
+| Vega     | Toolkit returns no page source         | Relaunch an app built with automation support                                    |
 
 On Android, healthy `describe` output does not prove the flow tree is available. It can fall back to legacy `uiautomator`, while the runner refuses that trimmed fallback.
 

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

@@ -5,7 +5,7 @@ description: Debug a JS runtime via CDP using argent debugger tools. Primary pat
 
 ## 1. Prerequisites
 
-Physical iPhone: not supported; every `debugger-*` tool rejects `kind: "device"`. Use a simulator.
+Physical iPhone: not supported; every `debugger-*` tool rejects `kind: "device"`.
 
 For **React Native (iOS / Android)**: requires **Metro dev server running** (default `localhost:8081`) and **a React Native app connected to Metro** (at least one CDP target). Verify via `debugger-status` — it returns `status: "connected"` or `status: "not_connected"` with a `reason` and `guidance` (it does not fail when the debugger is unreachable).
 
@@ -15,17 +15,17 @@ For **Chromium (CDP)**: requires a Chromium/CDP app already available — an Ele
 
 ### Android: reverse port for Metro
 
-Android emulators and physical devices do not resolve the host's `localhost` by default. Before the RN app can reach Metro, forward port 8081 (or whichever port Metro is on) from the device back to the host:
+Android emulators and physical devices do not resolve the host's `localhost` by default and the RN app fails to reach Metro server. To prevent this issue, forward port 8081 (or whichever port Metro is on) from the device back to the host:
 
 ```bash
 adb -s <serial> reverse tcp:8081 tcp:8081
 ```
 
-`<serial>` is the Android `serial` from `list-devices`. Once reversed, the app on the device connects to Metro just like an iOS simulator does, and all `debugger-*` / `network-*` / `react-profiler-*` tools work unchanged. If the device restarts or adb drops, re-run the command. A failing Metro connection on Android almost always means `adb reverse` has not been done or has been lost.
+`<serial>` is the Android `serial` from `list-devices`. If the device restarts or adb drops, re-run the command. A failing Metro connection on Android almost always means `adb reverse` has not been done or has been lost.
 
 ## 2. Tool Overview
 
-All tools accept `port` (default 8081) AND `device_id` (the iOS Simulator UDID, Android serial, or Vega serial — a.k.a. `logicalDeviceId`, the CDP-reported id that matches the device). Vega's legacy inspector reports no `logicalDeviceId`, so there keep passing the serial. Always make sure you target the correct app on the correct device.
+All tools accept `port` (default 8081) AND `device_id` (the iOS Simulator UDID, Android serial, or Vega serial — a.k.a. `logicalDeviceId`, the CDP-reported id that matches the device). Vega's legacy inspector reports no `logicalDeviceId`, so there keep passing the serial.
 
 One Metro port can serve multiple connected devices (e.g. two simulators on `localhost:8081`, or an iOS simulator alongside an Android emulator with `adb reverse` set up). `device_id` pins every debugger/network/profiler call to a specific device so sessions do not collide.
 
@@ -65,11 +65,9 @@ With two or more devices on one Metro, `debugger-connect` refuses a udid/serial
 | Best for | Layout overview; finding tap targets; user-defined component hierarchy | Identifying a visible element and tracing it to its source file |
 | Use when | "What's on screen and where?"                                          | "What component is this and where is it defined?"               |
 
-Both can point to source files, but `inspect-element` is purpose-built for source tracing. `component-tree` is for orientation and tap-target discovery.
-
 ### `includeSkipped` guidance
 
-Applies to both `debugger-component-tree` and `debugger-inspect-element`. Set to `true` only when debugging filter behavior — e.g., an expected component is missing from output, or you need to inspect a very specific branch of the tree (not just an overview).
+Set to `true` only when debugging filter behavior — e.g., an expected component is missing from output, or you need to inspect a very specific branch of the tree (not just an overview).
 
 > **Warning:** Output can be very large. Always combine with `maxNodes` (component-tree) or `maxItems` (inspect-element) and increase it incrementally (e.g., start at 50, then grow). Do not use `includeSkipped` without a limit on large apps.
 
@@ -99,13 +97,13 @@ Logs are written to a flat log file on disk. Use the **log-registry → grep** p
 
 One entry per line — fields (whitespace-separated, `|` delimiter before message)
 
-| Field         | Example                     | Notes                                               |
-| ------------- | --------------------------- | --------------------------------------------------- |
-| `[L:<id>]`    | `[L:42]`                    | Unique anchor; search it literally (see below)      |
-| `<timestamp>` | `2026-03-17T14:30:00.000Z`  | ISO 8601                                            |
-| `<LEVEL>`     | `ERROR`, `WARN `, `LOG  `   | Uppercase, padded to 5 chars                        |
-| `<source>`    | `src/api/user.ts:42` or `-` | Relative path from source map; `-` if unavailable   |
-| `<message>`   | `Failed login attempt`      | Full message; embedded newlines replaced with space |
+| Field         | Example                                                 | Notes                                                             |
+| ------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
+| `[L:<id>]`    | `[L:42]`                                                | Unique anchor; search it literally (see below)                    |
+| `<timestamp>` | `2026-03-17T14:30:00.000Z`                              | ISO 8601                                                          |
+| `<LEVEL>`     | `ERROR`, `WARNING`, `LOG  `, `INFO `, `DEBUG`, `ASSERT` | Uppercased CDP level, padded to at least 5 chars, never truncated |
+| `<source>`    | `src/api/user.ts:42` or `-`                             | Relative path from source map; `-` if unavailable                 |
+| `<message>`   | `Failed login attempt`                                  | Full message; embedded newlines replaced with space               |
 
 Source attribution (file + line) is also available in `clusters` returned by `debugger-log-registry`.
 
@@ -115,8 +113,7 @@ When reading from the log file:
 
 - Never `Read` the log file directly. Use `grep` or shell commands with limits using the above file format tips.
 - Default to `-m 50` unless you need more.
-- Use `tail -N` recent entries.
-- `clusters[].message` is a truncated, grouped prefix - grep a short fragment of it, not the whole string.
+- `clusters[].message` gives you the exact text which you may look for
 - Search bracketed text such as `[L:42]` or `[object Object]` with `grep -F`, or escape the brackets (`\[L:42\]`). Unescaped, `[...]` is a character class: `grep '[L:42]'` matches every line in the file.
 
 > **If the file is too large** Delegate to an `Explore` subagent with the file path, the format spec above, the specific patterns you need, and Golden Rule 4's untrusted-data caveat.

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

@@ -1,6 +1,6 @@
 # Failure Scenarios: Recovery Steps
 
-When a debugger tool fails, use **`debugger-status`** first to diagnose. Note: `debugger-status` and `debugger-log-registry` do **not** fail when the debugger is simply unreachable — they return `{ status: "not_connected", reason, detail, guidance }` (the `detail` field carries the same error text other tools throw). Match the error, `reason`, or situation below and act as specified. Do not retry the same failing tool repeatedly without following the recovery steps.
+When a debugger tool fails, use **`debugger-status`** first to diagnose. Note: `debugger-status` and `debugger-log-registry` do **not** fail when the debugger is simply unreachable — they return `{ status: "not_connected", reason, detail, guidance }` (the `detail` field carries the same error text other tools throw). Do not retry the same failing tool repeatedly without following the recovery steps.
 
 | Scenario                           | Error or situation                                                                                                                                 | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/skills/argent-metro-debugger/references/source-maps.md

@@ -24,4 +24,4 @@ module.exports = function (api) {
 };
 ```
 
-After adding the plugin, restart Metro (`npx react-native start --reset-cache` or `npx expo start --clear`) and reload the app. The tool will then automatically pick up `_debugSource` and resolve components to their source files. No extra `npm install` needed — the plugin ships with `babel-preset-expo` and `@babel/preset-env`.
+After adding the plugin, restart Metro (`npx react-native start --reset-cache` or `npx expo start --clear`) and reload the app. No extra `npm install` needed — the plugin ships with `babel-preset-expo` and `@babel/preset-env`.

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

@@ -19,7 +19,7 @@ description: Control and inspect TV apps via argent — Apple TV (tvOS), Android
 
 ## Tools
 
-- `describe {udid}` — focus view: the focused / `[selected]` element + focusable elements with labels and normalized frames. The discovery tool — call before and after navigating. Empty tree → see the per-platform notes.
+- `describe {udid}` — focus view: the focused / `[selected]` element + focusable elements with labels and normalized frames. Call before and after navigating. Empty tree → see the per-platform notes.
 - `tv-remote {udid, button}` — D-pad / remote. `button` is one key **or a whole path** (run in one call). Keys: `up`/`down`/`left`/`right`, `select`, `back`, `menu`, `home`, `playPause`, plus media keys `rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`. Single: `{button:"down"}`; repeat: `{button:"down", repeat:3}`; path: `{button:["up","right","select"]}`.
 - `keyboard {udid, text}` — type into the focused field (focus it with `tv-remote` first). One call carries `text` or `key`, never both — to type and then press a key, send two `keyboard` steps in one `run-sequence`. Named `key` presses (e.g. `{key:"enter"}`) work on Vega; on Apple TV / Android TV move focus with `tv-remote` instead.
 - `launch-app` / `restart-app` / `reinstall-app {udid, bundleId}` — `bundleId` from the app manifest. Vega `reinstall-app` takes `appPath` = a `.vpkg`.