agent-device 0.7.1 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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,6 +25,8 @@ 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
+- Device-scope isolation run: set iOS simulator set / Android allowlist -> run selectors within scope only
 
 ## Canonical Flows
 
@@ -57,12 +59,42 @@ Logging is off by default. Enable only for debugging windows.
 agent-device replay -u ./session.ad
 ```
 
+### 4) Remote Tenant Lease Flow (HTTP JSON-RPC)
+
+```bash
+# Allocate lease
+curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/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 \
+  --tenant acme \
+  --session-isolation tenant \
+  --run-id run-123 \
+  --lease-id <lease-id> \
+  session list --json
+
+# Heartbeat and release
+curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/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 \
+  -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>"}}'
+```
+
 ## Command Skeleton (Minimal)
 
 ### Session and navigation
 
 ```bash
 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 open [app|url] [url]
 agent-device open [app] --relaunch
 agent-device close [app]
@@ -70,8 +102,16 @@ agent-device session list
 ```
 
 Use `boot` only as fallback when `open` cannot find/connect to a ready target.
+For Android emulators by AVD name, use `boot --platform android --device <avd-name>`.
+For Android emulators without GUI, add `--headless`.
 Use `--target mobile|tv` with `--platform` (required) to pick phone/tablet vs TV targets (AndroidTV/tvOS).
 
+Isolation scoping quick reference:
+- `--ios-simulator-device-set <path>` scopes iOS simulator discovery + command execution to one simulator set.
+- `--android-device-allowlist <serials>` scopes Android discovery/selection to comma/space separated serials.
+- 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.
+
 TV quick reference:
 - AndroidTV: `open`/`apps` use TV launcher discovery automatically.
 - TV target selection works on emulators/simulators and connected physical devices (AndroidTV + AppleTV).
@@ -101,6 +141,7 @@ agent-device clipboard write "token"
 agent-device perf --json
 agent-device network dump [limit] [summary|headers|body|all]
 agent-device push <bundle|package> <payload.json|inline-json>
+agent-device trigger-app-event screenshot_taken '{"source":"qa"}'
 agent-device get text @e1
 agent-device screenshot out.png
 agent-device settings permission grant notifications
@@ -134,11 +175,18 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - `push` simulates notification delivery:
   - iOS simulator uses APNs-style payload JSON.
   - Android uses broadcast action + typed extras (string/boolean/number).
+- `trigger-app-event` requires app-defined deep-link hooks and URL template configuration (`AGENT_DEVICE_APP_EVENT_URL_TEMPLATE` or platform-specific variants).
+- `trigger-app-event` requires an active session or explicit selectors (`--platform`, `--device`, `--udid`, `--serial`); on iOS physical devices, custom-scheme triggers require active app context.
+- 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]`
 - `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`).
+- For tenant-isolated remote runs, always pass `--tenant`, `--session-isolation tenant`, `--run-id`, and `--lease-id` together.
+- 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`).
 
 ## Security and Trust Notes
 
@@ -146,6 +194,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.
 - Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.
 
 ## Common Mistakes
@@ -165,3 +214,4 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - [references/coordinate-system.md](references/coordinate-system.md)
 - [references/batching.md](references/batching.md)
 - [references/perf-metrics.md](references/perf-metrics.md)
+- [references/remote-tenancy.md](references/remote-tenancy.md)

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

@@ -0,0 +1,77 @@
+# Remote Tenancy and Lease Admission
+
+Use this reference for remote daemon HTTP flows that require explicit
+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>`.
+- Prefer an auth hook (`AGENT_DEVICE_HTTP_AUTH_HOOK`) for caller validation and
+  tenant injection.
+
+## Lease lifecycle (JSON-RPC)
+
+Use `POST /rpc` with JSON-RPC 2.0 methods:
+
+- `agent_device.lease.allocate`
+- `agent_device.lease.heartbeat`
+- `agent_device.lease.release`
+
+Example allocate:
+
+```bash
+curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/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}}'
+```
+
+Example heartbeat:
+
+```bash
+curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/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}}'
+```
+
+Example release:
+
+```bash
+curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/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>"}}'
+```
+
+## Command admission contract
+
+For tenant-isolated command execution, pass all four flags:
+
+```bash
+agent-device --daemon-transport http \
+  --tenant acme \
+  --session-isolation tenant \
+  --run-id run-123 \
+  --lease-id <lease-id> \
+  session list --json
+```
+
+Admission checks require tenant/run/lease scope alignment.
+
+## Failure semantics
+
+- Missing tenant/run/lease fields in tenant isolation mode: `INVALID_ARGS`
+- Lease not active or wrong scope: `UNAUTHORIZED`
+- Method mismatch: JSON-RPC `-32601` (HTTP 404)
+
+## Operational guidance
+
+- Keep TTL short and heartbeat only while a run is active.
+- Release lease immediately on run completion/error paths.
+- For bounded hosts, configure:
+  - `AGENT_DEVICE_MAX_SIMULATOR_LEASES`
+  - `AGENT_DEVICE_LEASE_TTL_MS`
+  - `AGENT_DEVICE_LEASE_MIN_TTL_MS`
+  - `AGENT_DEVICE_LEASE_MAX_TTL_MS`

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

@@ -14,6 +14,8 @@ Sessions isolate device context. A device can only be held by one session at a t
 - Name sessions semantically.
 - Close sessions when done.
 - Use separate sessions for parallel work.
+- For remote tenant-scoped automation, run commands with:
+  `--tenant <id> --session-isolation tenant --run-id <id> --lease-id <id>`
 - In iOS sessions, use `open <app>`. `open <url>` opens deep links; on devices `http(s)://` opens Safari when no app is active, and custom schemes require an active app in the session.
 - In iOS sessions, `open <app> <url>` opens a deep link.
 - On iOS, `appstate` is session-scoped and requires a matching active session on the target device.
@@ -23,6 +25,22 @@ Sessions isolate device context. A device can only be held by one session at a t
 - For deterministic replay scripts, prefer selector-based actions and assertions.
 - Use `replay -u` to update selector drift during maintenance.
 
+## Scoped device isolation
+
+Use scoped discovery when sessions must not see host-global device lists.
+
+```bash
+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
+```
+
+- Scope is applied before selectors (`--device`, `--udid`, `--serial`).
+- If selector target is outside scope, resolution fails with `DEVICE_NOT_FOUND`.
+- 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`)
+  - `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST` (compat: `ANDROID_DEVICE_ALLOWLIST`)
+
 ## Listing sessions
 
 ```bash
@@ -35,3 +53,9 @@ agent-device session list
 agent-device replay ./session.ad --session auth
 agent-device replay -u ./session.ad --session auth
 ```
+
+## Tenant isolation note
+
+When session isolation is set to tenant mode, session namespace is scoped as
+`<tenant>:<session>`. For remote runs, allocate and maintain an active lease
+for the same tenant/run scope before executing tenant-isolated commands.