docs: add agent skill guidance for remote tenant leases (#137)

Author: thymikee

skills/agent-device/SKILL.md

@@ -25,6 +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
 
 ## Canonical Flows
 
@@ -57,6 +58,34 @@ 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
@@ -139,13 +168,16 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - `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.
 
 ## Security and Trust Notes
 
 - Prefer a preinstalled `agent-device` binary over on-demand package execution.
 - 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 +197,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)

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`

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.
@@ -35,3 +37,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.