agent-device 0.7.6 → 0.7.10

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -310,7 +310,7 @@ extension RunnerTests {
         compact: command.compact ?? false,
         depth: command.depth,
         scope: command.scope,
-        raw: command.raw ?? false,
+        raw: command.raw ?? false
       )
       if options.raw {
         needsPostSnapshotInteractionDelay = true

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift

@@ -68,14 +68,14 @@ extension RunnerTests {
       let outputSettings: [String: Any] = [
         AVVideoCodecKey: AVVideoCodecType.h264,
         AVVideoWidthKey: Int(dimensions.width),
-        AVVideoHeightKey: Int(dimensions.height),
+        AVVideoHeightKey: Int(dimensions.height)
       ]
       let input = AVAssetWriterInput(mediaType: .video, outputSettings: outputSettings)
       input.expectsMediaDataInRealTime = true
       let attributes: [String: Any] = [
         kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32ARGB,
         kCVPixelBufferWidthKey as String: Int(dimensions.width),
-        kCVPixelBufferHeightKey as String: Int(dimensions.height),
+        kCVPixelBufferHeightKey as String: Int(dimensions.height)
       ]
       let adaptor = AVAssetWriterInputPixelBufferAdaptor(
         assetWriterInput: input,

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift

@@ -82,11 +82,11 @@ extension RunnerTests {
           x: Double(rootSnapshot.frame.origin.x),
           y: Double(rootSnapshot.frame.origin.y),
           width: Double(rootSnapshot.frame.size.width),
-          height: Double(rootSnapshot.frame.size.height),
+          height: Double(rootSnapshot.frame.size.height)
         ),
         enabled: rootSnapshot.isEnabled,
         hittable: rootHittable,
-        depth: 0,
+        depth: 0
       )
     )
 
@@ -149,11 +149,11 @@ extension RunnerTests {
             x: Double(snapshot.frame.origin.x),
             y: Double(snapshot.frame.origin.y),
             width: Double(snapshot.frame.size.width),
-            height: Double(snapshot.frame.size.height),
+            height: Double(snapshot.frame.size.height)
           ),
           enabled: snapshot.isEnabled,
           hittable: hittable,
-          depth: min(maxDepth, visibleDepth),
+          depth: min(maxDepth, visibleDepth)
         )
       )
 
@@ -216,7 +216,7 @@ extension RunnerTests {
             rect: snapshotRect(from: snapshot.frame),
             enabled: snapshot.isEnabled,
             hittable: hittable,
-            depth: depth,
+            depth: depth
           )
         )
       }

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift

@@ -19,7 +19,7 @@ extension RunnerTests {
       if buffer.count + data.count > self.maxRequestBytes {
         let response = self.jsonResponse(
           status: 413,
-          response: Response(ok: false, error: ErrorPayload(message: "request too large")),
+          response: Response(ok: false, error: ErrorPayload(message: "request too large"))
         )
         connection.send(content: response, completion: .contentProcessed { [weak self] _ in
           connection.cancel()
@@ -111,7 +111,7 @@ extension RunnerTests {
       "Content-Length: \(body.utf8.count)",
       "Connection: close",
       "",
-      body,
+      body
     ].joined(separator: "\r\n")
     return Data(headers.utf8)
   }

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -59,7 +59,7 @@ final class RunnerTests: XCTestCase {
     .tabBar,
     .textField,
     .secureTextField,
-    .textView,
+    .textView
   ]
   // Keep blocker actions narrow to avoid false positives from generic hittable containers.
   let actionableTypes: Set<XCUIElement.ElementType> = [
@@ -68,7 +68,7 @@ final class RunnerTests: XCTestCase {
     .link,
     .menuItem,
     .checkBox,
-    .switch,
+    .switch
   ]
 
   // MARK: - XCTest Entry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.7.6",
+  "version": "0.7.10",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",

package/skills/agent-device/SKILL.md

@@ -25,7 +25,7 @@ Use this skill as a router, not a full manual.
 - Normal UI task: `open` -> `snapshot -i` -> `press/fill` -> `diff snapshot -i` -> `close`
 - Debug/crash: `open <app>` -> `logs clear --restart` -> reproduce -> `network dump` -> `logs path` -> targeted `grep`
 - Replay drift: `replay -u <path>` -> verify updated selectors
-- Remote multi-tenant run: allocate lease -> run commands with tenant isolation flags -> heartbeat/release lease
+- Remote multi-tenant run: allocate lease -> point client at remote daemon base URL -> run commands with tenant isolation flags -> heartbeat/release lease
 - Device-scope isolation run: set iOS simulator set / Android allowlist -> run selectors within scope only
 
 ## Canonical Flows
@@ -62,14 +62,18 @@ agent-device replay -u ./session.ad
 ### 4) Remote Tenant Lease Flow (HTTP JSON-RPC)
 
 ```bash
+# Client points directly at the remote daemon HTTP base URL.
+export AGENT_DEVICE_DAEMON_BASE_URL=http://mac-host.example:4310
+export AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>
+
 # Allocate lease
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"runId":"run-123","tenantId":"acme","ttlMs":60000}}'
 
 # Use lease in tenant-isolated command execution
-agent-device --daemon-transport http \
+agent-device \
   --tenant acme \
   --session-isolation tenant \
   --run-id run-123 \
@@ -77,16 +81,21 @@ agent-device --daemon-transport http \
   session list --json
 
 # Heartbeat and release
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
 ```
 
+Notes:
+- `AGENT_DEVICE_DAEMON_BASE_URL` makes the CLI skip local daemon discovery/startup and call the remote HTTP daemon directly.
+- `AGENT_DEVICE_DAEMON_AUTH_TOKEN` is sent in both the JSON-RPC request token and HTTP auth headers.
+- In remote daemon mode, `--debug` does not tail a local `daemon.log`; inspect logs on the remote host instead.
+
 ## Command Skeleton (Minimal)
 
 ### Session and navigation
@@ -95,6 +104,8 @@ curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
 agent-device devices
 agent-device devices --platform ios --ios-simulator-device-set /tmp/tenant-a/simulators
 agent-device devices --platform android --android-device-allowlist emulator-5554,device-1234
+agent-device ensure-simulator --device "iPhone 16" --ios-simulator-device-set /tmp/tenant-a/simulators
+agent-device ensure-simulator --device "iPhone 16" --runtime com.apple.CoreSimulator.SimRuntime.iOS-18-4 --ios-simulator-device-set /tmp/tenant-a/simulators --boot
 agent-device open [app|url] [url]
 agent-device open [app] --relaunch
 agent-device close [app]
@@ -114,6 +125,12 @@ Isolation scoping quick reference:
 - Scope is applied before selectors (`--device`, `--udid`, `--serial`); out-of-scope selectors fail with `DEVICE_NOT_FOUND`.
 - With iOS simulator-set scope enabled, iOS physical devices are not enumerated.
 
+Simulator provisioning quick reference:
+- Use `ensure-simulator` to create or reuse a named iOS simulator inside a device set before starting a session.
+- `--device <name>` is required (e.g. `"iPhone 16 Pro"`). `--runtime <id>` pins the runtime; omit to use the newest compatible one.
+- `--boot` boots it immediately. Returns `udid`, `device`, `runtime`, `ios_simulator_device_set`, `created`, `booted`.
+- Idempotent: safe to call repeatedly; reuses an existing matching simulator by default.
+
 TV quick reference:
 - AndroidTV: `open`/`apps` use TV launcher discovery automatically.
 - TV target selection works on emulators/simulators and connected physical devices (AndroidTV + AppleTV).
@@ -170,13 +187,15 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - Re-snapshot after UI mutations (navigation/modal/list changes).
 - Prefer `snapshot -i`; scope/depth only when needed.
 - Use refs for discovery, selectors for replay/assertions.
+- `find "<query>" click --json` returns `{ ref, locator, query, x, y }` — all derived from the matched snapshot node. Do not rely on these fields from raw `press`/`click` responses for observability; use `find` instead.
 - Use `fill` for clear-then-type semantics; use `type` for focused append typing.
 - Use `install` for in-place app upgrades (keep app data when platform permits), and `reinstall` for deterministic fresh-state runs.
 - App binary format support for `install`/`reinstall`: Android `.apk`/`.aab`, iOS `.app`/`.ipa`.
 - Android `.aab` requires `bundletool` in `PATH`, or `AGENT_DEVICE_BUNDLETOOL_JAR=<path-to-bundletool-all.jar>` with `java` in `PATH`.
 - Android `.aab` optional: set `AGENT_DEVICE_ANDROID_BUNDLETOOL_MODE=<mode>` to control bundletool `build-apks --mode` (default: `universal`).
 - iOS `.ipa`: extract/install from `Payload/*.app`; when multiple app bundles are present, `<app>` is used as a bundle id/name hint.
-- iOS `appstate` is session-scoped; Android `appstate` is live foreground state.
+- iOS `appstate` is session-scoped; Android `appstate` is live foreground state. iOS responses include `device_udid` and `ios_simulator_device_set` for isolation verification.
+- iOS `open` responses include `device_udid` and `ios_simulator_device_set` to confirm which simulator handled the session.
 - Clipboard helpers: `clipboard read` / `clipboard write <text>` are supported on Android and iOS simulators; iOS physical devices are not supported yet.
 - Android keyboard helpers: `keyboard status|get|dismiss` report keyboard visibility/type and dismiss via keyevent when visible.
 - `network dump` is best-effort and parses HTTP(s) entries from the session app log file.
@@ -190,6 +209,7 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - Canonical trigger behavior and caveats are documented in [`website/docs/docs/commands.md`](../../website/docs/docs/commands.md) under **App event triggers**.
 - Permission settings are app-scoped and require an active session app:
   `settings permission <grant|deny|reset> <camera|microphone|photos|contacts|notifications> [full|limited]`
+- iOS simulator permission alerts: use `alert wait` then `alert accept/dismiss` — `accept`/`dismiss` retry internally for up to 2 s so you do not need manual sleeps. See [references/permissions.md](references/permissions.md).
 - `full|limited` mode applies only to iOS `photos`; other targets reject mode.
 - On Android, non-ASCII `fill/type` may require an ADB keyboard IME on some system images; only install IME APKs from trusted sources and verify checksum/signature.
 - If using `--save-script`, prefer explicit path syntax (`--save-script=flow.ad` or `./flow.ad`).
@@ -197,6 +217,7 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - Use short lease TTLs and heartbeat only while work is active; release leases immediately after run completion/failure.
 - Env equivalents for scoped runs: `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET` (compat `IOS_SIMULATOR_DEVICE_SET`) and
   `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST` (compat `ANDROID_DEVICE_ALLOWLIST`).
+- For explicit remote client mode, prefer `AGENT_DEVICE_DAEMON_BASE_URL` / `--daemon-base-url` instead of relying on local daemon metadata or loopback-only ports.
 
 ## Security and Trust Notes
 
@@ -204,7 +225,7 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - If install is required, pin an exact version (for example: `npx --yes agent-device@<exact-version> --help`).
 - Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup.
 - Logs/artifacts are written under `~/.agent-device`; replay scripts write to explicit paths you provide.
-- For remote daemon mode, prefer `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual` with `AGENT_DEVICE_HTTP_AUTH_HOOK` and tenant-scoped lease admission.
+- For remote daemon mode, prefer `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual` on the host plus client-side `AGENT_DEVICE_DAEMON_BASE_URL`, with `AGENT_DEVICE_HTTP_AUTH_HOOK` and tenant-scoped lease admission where needed.
 - Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.
 
 ## Common Mistakes

package/skills/agent-device/references/permissions.md

@@ -34,6 +34,33 @@ If daemon startup fails with stale metadata hints, clean stale files and retry:
 - `~/.agent-device/daemon.json`
 - `~/.agent-device/daemon.lock`
 
+## iOS permission alerts (simulator only)
+
+iOS apps trigger system permission dialogs (camera, location, notifications, etc.) on first use.
+Use `alert` to handle them without tapping coordinates:
+
+```bash
+agent-device alert wait          # block until an alert appears (default 10 s timeout)
+agent-device alert accept        # accept the frontmost alert
+agent-device alert dismiss       # dismiss the frontmost alert
+agent-device alert get           # read alert title/message without acting
+```
+
+**Timing note:** `alert accept` and `alert dismiss` include a built-in 2 s retry window.
+If the alert is present in the UI hierarchy but not yet interactive, the command retries every 300 ms
+rather than failing immediately. You do not need to add manual sleeps between triggering the alert
+and accepting it.
+
+**Preferred pattern for clean simulator sessions:**
+
+```bash
+agent-device open MyApp --platform ios
+agent-device alert wait 5000     # wait up to 5 s for the permission prompt
+agent-device alert accept        # accept; retries internally if not yet actionable
+```
+
+`alert` is only supported on iOS simulators; iOS physical devices are not supported.
+
 ## iOS: "Allow Paste" dialog
 
 iOS 16+ shows an "Allow Paste" prompt when an app reads the system pasteboard. Under XCUITest (which `agent-device` uses), this prompt is suppressed by the testing runtime. Use `xcrun simctl pbcopy booted` to set clipboard content directly on the simulator instead.

package/skills/agent-device/references/remote-tenancy.md

@@ -6,7 +6,12 @@ tenant/run admission control.
 ## Transport prerequisites
 
 - Start daemon in HTTP mode (`AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual`).
-- Use a token from daemon metadata or `Authorization: Bearer <token>`.
+- Point remote clients at the host with `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]`
+  or `--daemon-base-url <url>` so the CLI skips local daemon discovery/startup.
+- Use `AGENT_DEVICE_DAEMON_AUTH_TOKEN` / `--daemon-auth-token` when the client should send the
+  shared daemon token automatically.
+- Direct JSON-RPC callers can use a token in params, `Authorization: Bearer <token>`, or
+  `x-agent-device-token`.
 - Prefer an auth hook (`AGENT_DEVICE_HTTP_AUTH_HOOK`) for caller validation and
   tenant injection.
 
@@ -21,7 +26,7 @@ Use `POST /rpc` with JSON-RPC 2.0 methods:
 Example allocate:
 
 ```bash
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"tenantId":"acme","runId":"run-123","ttlMs":60000}}'
@@ -30,7 +35,7 @@ curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
 Example heartbeat:
 
 ```bash
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
@@ -39,7 +44,7 @@ curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
 Example release:
 
 ```bash
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
@@ -50,7 +55,7 @@ curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
 For tenant-isolated command execution, pass all four flags:
 
 ```bash
-agent-device --daemon-transport http \
+agent-device \
   --tenant acme \
   --session-isolation tenant \
   --run-id run-123 \
@@ -60,6 +65,9 @@ agent-device --daemon-transport http \
 
 Admission checks require tenant/run/lease scope alignment.
 
+The CLI sends `AGENT_DEVICE_DAEMON_AUTH_TOKEN` in both the JSON-RPC request token field and HTTP
+auth headers so existing daemon auth paths continue to work.
+
 ## Failure semantics
 
 - Missing tenant/run/lease fields in tenant isolation mode: `INVALID_ARGS`
@@ -70,6 +78,8 @@ Admission checks require tenant/run/lease scope alignment.
 
 - Keep TTL short and heartbeat only while a run is active.
 - Release lease immediately on run completion/error paths.
+- For remote debug sessions, inspect logs on the remote host; client-side `--debug` no longer tails
+  a local daemon log when `AGENT_DEVICE_DAEMON_BASE_URL` is set.
 - For bounded hosts, configure:
   - `AGENT_DEVICE_MAX_SIMULATOR_LEASES`
   - `AGENT_DEVICE_LEASE_TTL_MS`

package/skills/agent-device/references/session-management.md

@@ -21,6 +21,7 @@ Sessions isolate device context. A device can only be held by one session at a t
 - On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
 - For dev loops where runtime state can persist (for example React Native Fast Refresh), use `open <app> --relaunch` to restart the app process in the same session.
 - Use `--save-script [path]` to record replay scripts on `close`; path is a file path and parent directories are created automatically.
+- Use `close --shutdown` (iOS simulator only) to shut down the simulator as part of session teardown, preventing resource leakage in multi-tenant or CI workloads.
 - For ambiguous bare `--save-script` values, prefer `--save-script=workflow.ad` or `./workflow.ad`.
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
@@ -36,6 +37,7 @@ agent-device devices --platform android --android-device-allowlist emulator-5554
 
 - Scope is applied before selectors (`--device`, `--udid`, `--serial`).
 - If selector target is outside scope, resolution fails with `DEVICE_NOT_FOUND`.
+- If the scoped iOS simulator set is empty (first-run), the error includes the set path and a suggested `xcrun simctl --set <path> create ...` command.
 - With iOS simulator-set scope enabled, iOS physical devices are not enumerated.
 - Environment equivalents:
   - `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET` (compat: `IOS_SIMULATOR_DEVICE_SET`)
@@ -47,6 +49,8 @@ agent-device devices --platform android --android-device-allowlist emulator-5554
 agent-device session list
 ```
 
+iOS session entries include `device_udid` and `ios_simulator_device_set` (null when using the default set). Use these fields to confirm device routing in concurrent multi-session runs without additional `simctl` calls.
+
 ## Replay within sessions
 
 ```bash

package/skills/agent-device/references/snapshot-refs.md

@@ -76,6 +76,16 @@ Efficient pattern:
 
 - If refs are unstable after UI transitions, switch to selector-based targeting and stop investing in ref-only flows.
 
+## find click response
+
+`find "<query>" click --json` returns deterministic matched-target metadata:
+
+```json
+{ "ref": "@e3", "locator": "any", "query": "Increment", "x": 195, "y": 422 }
+```
+
+Fields come from the matched snapshot node, not the platform runner. Use these for observability and replay quality — they are stable across runs for the same UI state.
+
 ## Replay note
 
 - Prefer selector-based actions in recorded `.ad` replays.