agent-device 0.7.21 → 0.8.0

package/dist/src/utils/cli-options.d.ts

@@ -0,0 +1,13 @@
+import type { CliFlags } from './command-schema.ts';
+type EnvMap = Record<string, string | undefined>;
+export declare function resolveCliOptions(argv: string[], options?: {
+    cwd?: string;
+    env?: EnvMap;
+    strictFlags?: boolean;
+}): {
+    command: string | null;
+    positionals: string[];
+    flags: CliFlags;
+    warnings: string[];
+};
+export {};

package/dist/src/utils/command-schema.d.ts

@@ -0,0 +1,98 @@
+export type CliFlags = {
+    json: boolean;
+    config?: string;
+    stateDir?: string;
+    daemonBaseUrl?: string;
+    daemonAuthToken?: string;
+    daemonTransport?: 'auto' | 'socket' | 'http';
+    daemonServerMode?: 'socket' | 'http' | 'dual';
+    tenant?: string;
+    sessionIsolation?: 'none' | 'tenant';
+    runId?: string;
+    leaseId?: string;
+    sessionLock?: 'reject' | 'strip';
+    sessionLocked?: boolean;
+    sessionLockConflicts?: 'reject' | 'strip';
+    platform?: 'ios' | 'android' | 'apple';
+    target?: 'mobile' | 'tv';
+    device?: string;
+    udid?: string;
+    serial?: string;
+    iosSimulatorDeviceSet?: string;
+    androidDeviceAllowlist?: string;
+    out?: string;
+    session?: string;
+    runtime?: string;
+    metroHost?: string;
+    metroPort?: number;
+    bundleUrl?: string;
+    launchUrl?: string;
+    boot?: boolean;
+    reuseExisting?: boolean;
+    verbose?: boolean;
+    snapshotInteractiveOnly?: boolean;
+    snapshotCompact?: boolean;
+    snapshotDepth?: number;
+    snapshotScope?: string;
+    snapshotRaw?: boolean;
+    appsFilter?: 'user-installed' | 'all';
+    count?: number;
+    fps?: number;
+    intervalMs?: number;
+    holdMs?: number;
+    jitterPx?: number;
+    doubleTap?: boolean;
+    pauseMs?: number;
+    pattern?: 'one-way' | 'ping-pong';
+    activity?: string;
+    saveScript?: boolean | string;
+    shutdown?: boolean;
+    relaunch?: boolean;
+    headless?: boolean;
+    restart?: boolean;
+    noRecord?: boolean;
+    replayUpdate?: boolean;
+    steps?: string;
+    stepsFile?: string;
+    batchOnError?: 'stop';
+    batchMaxSteps?: number;
+    batchSteps?: Array<{
+        command: string;
+        positionals?: string[];
+        flags?: Record<string, unknown>;
+    }>;
+    help: boolean;
+    version: boolean;
+};
+export type FlagKey = keyof CliFlags;
+type FlagType = 'boolean' | 'int' | 'enum' | 'string' | 'booleanOrString';
+export type FlagDefinition = {
+    key: FlagKey;
+    names: readonly string[];
+    type: FlagType;
+    enumValues?: readonly string[];
+    min?: number;
+    max?: number;
+    setValue?: CliFlags[FlagKey];
+    usageLabel?: string;
+    usageDescription?: string;
+};
+type CommandSchema = {
+    description: string;
+    positionalArgs: readonly string[];
+    allowsExtraPositionals?: boolean;
+    allowedFlags: readonly FlagKey[];
+    defaults?: Partial<CliFlags>;
+    skipCapabilityCheck?: boolean;
+    usageOverride?: string;
+};
+export declare const GLOBAL_FLAG_KEYS: Set<keyof CliFlags>;
+export declare function getFlagDefinition(token: string): FlagDefinition | undefined;
+export declare function getFlagDefinitions(): readonly FlagDefinition[];
+export declare function getCommandSchema(command: string | null): CommandSchema | undefined;
+export declare function getCliCommandNames(): string[];
+export declare function getSchemaCapabilityKeys(): string[];
+export declare function isStrictFlagModeEnabled(value: string | undefined): boolean;
+export declare function buildUsageText(): string;
+export declare function buildCommandUsageText(commandName: string): string | null;
+export {};

package/dist/src/utils/device-isolation.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveIosSimulatorDeviceSetPath(flagValue: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function parseSerialAllowlist(value: string): Set<string>;
+export declare function resolveAndroidSerialAllowlist(flagValue: string | undefined, env?: NodeJS.ProcessEnv): ReadonlySet<string> | undefined;

package/dist/src/utils/device.d.ts

@@ -0,0 +1,27 @@
+export type Platform = 'ios' | 'android';
+export type PlatformSelector = Platform | 'apple';
+export type DeviceKind = 'simulator' | 'emulator' | 'device';
+export type DeviceTarget = 'mobile' | 'tv';
+export type DeviceInfo = {
+    platform: Platform;
+    id: string;
+    name: string;
+    kind: DeviceKind;
+    target?: DeviceTarget;
+    booted?: boolean;
+    simulatorSetPath?: string;
+};
+type DeviceSelector = {
+    platform?: Platform;
+    target?: DeviceTarget;
+    deviceName?: string;
+    udid?: string;
+    serial?: string;
+};
+type DeviceSelectionContext = {
+    simulatorSetPath?: string;
+};
+export declare function normalizePlatformSelector(platform: PlatformSelector | undefined): Platform | undefined;
+export declare function resolveApplePlatformName(target: DeviceTarget | undefined): 'iOS' | 'tvOS';
+export declare function selectDevice(devices: DeviceInfo[], selector: DeviceSelector, context?: DeviceSelectionContext): Promise<DeviceInfo>;
+export {};

package/dist/src/utils/diagnostics.d.ts

@@ -0,0 +1,30 @@
+type DiagnosticLevel = 'info' | 'warn' | 'error' | 'debug';
+type DiagnosticsScopeOptions = {
+    session?: string;
+    requestId?: string;
+    command?: string;
+    debug?: boolean;
+    logPath?: string;
+    traceLogPath?: string;
+};
+export declare function createRequestId(): string;
+export declare function withDiagnosticsScope<T>(options: DiagnosticsScopeOptions, fn: () => Promise<T> | T): Promise<T>;
+export declare function getDiagnosticsMeta(): {
+    diagnosticId?: string;
+    requestId?: string;
+    session?: string;
+    command?: string;
+    debug?: boolean;
+};
+export declare function emitDiagnostic(event: {
+    level?: DiagnosticLevel;
+    phase: string;
+    durationMs?: number;
+    data?: Record<string, unknown>;
+}): void;
+export declare function withDiagnosticTimer<T>(phase: string, fn: () => Promise<T> | T, data?: Record<string, unknown>): Promise<T>;
+export declare function flushDiagnosticsToSessionFile(options?: {
+    force?: boolean;
+}): string | null;
+export declare function redactDiagnosticData<T>(input: T): T;
+export {};

package/dist/src/utils/errors.d.ts

@@ -0,0 +1,26 @@
+type ErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'UNKNOWN';
+type AppErrorDetails = Record<string, unknown> & {
+    hint?: string;
+    diagnosticId?: string;
+    logPath?: string;
+};
+export type NormalizedError = {
+    code: string;
+    message: string;
+    hint?: string;
+    diagnosticId?: string;
+    logPath?: string;
+    details?: Record<string, unknown>;
+};
+export declare class AppError extends Error {
+    code: ErrorCode;
+    details?: AppErrorDetails;
+    cause?: unknown;
+    constructor(code: ErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
+}
+export declare function asAppError(err: unknown): AppError;
+export declare function normalizeError(err: unknown, context?: {
+    diagnosticId?: string;
+    logPath?: string;
+}): NormalizedError;
+export {};

package/dist/src/utils/exec.d.ts

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+export type ExecResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    stdoutBuffer?: Buffer;
+};
+type ExecOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    allowFailure?: boolean;
+    binaryStdout?: boolean;
+    stdin?: string | Buffer;
+    timeoutMs?: number;
+    detached?: boolean;
+};
+type ExecStreamOptions = ExecOptions & {
+    onStdoutChunk?: (chunk: string) => void;
+    onStderrChunk?: (chunk: string) => void;
+    onSpawn?: (child: ReturnType<typeof spawn>) => void;
+};
+export type ExecBackgroundResult = {
+    child: ReturnType<typeof spawn>;
+    wait: Promise<ExecResult>;
+};
+export declare function runCmd(cmd: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+export declare function whichCmd(cmd: string): Promise<boolean>;
+export declare function runCmdSync(cmd: string, args: string[], options?: ExecOptions): ExecResult;
+export declare function runCmdDetached(cmd: string, args: string[], options?: ExecOptions): void;
+export declare function runCmdStreaming(cmd: string, args: string[], options?: ExecStreamOptions): Promise<ExecResult>;
+export declare function runCmdBackground(cmd: string, args: string[], options?: ExecOptions): ExecBackgroundResult;
+export {};

package/dist/src/utils/finders.d.ts

@@ -0,0 +1,12 @@
+import type { SnapshotNode } from './snapshot.ts';
+export type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
+type FindMatchOptions = {
+    requireRect?: boolean;
+};
+type FindBestMatches = {
+    matches: SnapshotNode[];
+    score: number;
+};
+export declare function findNodeByLocator(nodes: SnapshotNode[], locator: FindLocator, query: string, options?: FindMatchOptions): SnapshotNode | null;
+export declare function findBestMatchesByLocator(nodes: SnapshotNode[], locator: FindLocator, query: string, options?: FindMatchOptions): FindBestMatches;
+export {};

package/dist/src/utils/interactive.d.ts

@@ -0,0 +1 @@
+export declare function isInteractive(): boolean;

package/dist/src/utils/interactors.d.ts

@@ -0,0 +1,31 @@
+import type { DeviceInfo } from './device.ts';
+export type RunnerContext = {
+    requestId?: string;
+    appBundleId?: string;
+    verbose?: boolean;
+    logPath?: string;
+    traceLogPath?: string;
+};
+type Interactor = {
+    open(app: string, options?: {
+        activity?: string;
+        appBundleId?: string;
+        url?: string;
+    }): Promise<void>;
+    openDevice(): Promise<void>;
+    close(app: string): Promise<void>;
+    tap(x: number, y: number): Promise<void>;
+    doubleTap(x: number, y: number): Promise<void>;
+    swipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
+    longPress(x: number, y: number, durationMs?: number): Promise<void>;
+    focus(x: number, y: number): Promise<void>;
+    type(text: string): Promise<void>;
+    fill(x: number, y: number, text: string): Promise<void>;
+    scroll(direction: string, amount?: number): Promise<void>;
+    scrollIntoView(text: string): Promise<{
+        attempts?: number;
+    } | void>;
+    screenshot(outPath: string, appBundleId?: string): Promise<void>;
+};
+export declare function getInteractor(device: DeviceInfo, runnerContext: RunnerContext): Interactor;
+export {};

package/dist/src/utils/json-input.d.ts

@@ -0,0 +1 @@
+export declare function looksLikeInlineJson(value: string): boolean;

package/dist/src/utils/keyed-lock.d.ts

@@ -0,0 +1 @@
+export declare function withKeyedLock<T>(locks: Map<string, Promise<unknown>>, key: string, task: () => Promise<T>): Promise<T>;

package/dist/src/utils/output.d.ts

@@ -0,0 +1,25 @@
+import { AppError, type NormalizedError } from './errors.ts';
+type JsonResult = {
+    success: true;
+    data?: Record<string, unknown>;
+} | {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        hint?: string;
+        diagnosticId?: string;
+        logPath?: string;
+        details?: Record<string, unknown>;
+    };
+};
+export declare function printJson(result: JsonResult): void;
+export declare function printHumanError(err: AppError | NormalizedError, options?: {
+    showDetails?: boolean;
+}): void;
+export declare function formatSnapshotText(data: Record<string, unknown>, options?: {
+    raw?: boolean;
+    flatten?: boolean;
+}): string;
+export declare function formatSnapshotDiffText(data: Record<string, unknown>): string;
+export {};

package/dist/src/utils/payload-input.d.ts

@@ -0,0 +1,12 @@
+export type ResolvedPayloadInput = {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'inline';
+    text: string;
+};
+export declare function resolvePayloadInput(value: string, options?: {
+    subject?: string;
+    cwd?: string;
+    expandPath?: (value: string, cwd?: string) => string;
+}): ResolvedPayloadInput;

package/dist/src/utils/process-identity.d.ts

@@ -0,0 +1,11 @@
+export declare function isProcessAlive(pid: number): boolean;
+export declare function readProcessStartTime(pid: number): string | null;
+export declare function readProcessCommand(pid: number): string | null;
+export declare function isAgentDeviceDaemonCommand(command: string): boolean;
+export declare function isAgentDeviceDaemonProcess(pid: number, expectedStartTime?: string): boolean;
+export declare function waitForProcessExit(pid: number, timeoutMs: number): Promise<boolean>;
+export declare function stopProcessForTakeover(pid: number, options: {
+    termTimeoutMs: number;
+    killTimeoutMs: number;
+    expectedStartTime?: string;
+}): Promise<void>;

package/dist/src/utils/retry.d.ts

@@ -0,0 +1,54 @@
+type RetryOptions = {
+    attempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+type RetryPolicy = {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+type RetryAttemptContext = {
+    attempt: number;
+    maxAttempts: number;
+    deadline?: Deadline;
+};
+type TimeoutProfile = {
+    startupMs: number;
+    operationMs: number;
+    totalMs: number;
+};
+type RetryTelemetryEvent = {
+    phase?: string;
+    event: 'attempt_failed' | 'retry_scheduled' | 'succeeded' | 'exhausted';
+    attempt: number;
+    maxAttempts: number;
+    delayMs?: number;
+    elapsedMs?: number;
+    remainingMs?: number;
+    reason?: string;
+};
+export declare function isEnvTruthy(value: string | undefined): boolean;
+export declare const TIMEOUT_PROFILES: Record<string, TimeoutProfile>;
+export declare class Deadline {
+    private readonly startedAtMs;
+    private readonly expiresAtMs;
+    private constructor();
+    static fromTimeoutMs(timeoutMs: number, nowMs?: number): Deadline;
+    remainingMs(nowMs?: number): number;
+    elapsedMs(nowMs?: number): number;
+    isExpired(nowMs?: number): boolean;
+}
+export declare function retryWithPolicy<T>(fn: (context: RetryAttemptContext) => Promise<T>, policy?: Partial<RetryPolicy>, options?: {
+    deadline?: Deadline;
+    phase?: string;
+    signal?: AbortSignal;
+    classifyReason?: (error: unknown) => string | undefined;
+    onEvent?: (event: RetryTelemetryEvent) => void;
+}): Promise<T>;
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+export {};

package/dist/src/utils/session-binding.d.ts

@@ -0,0 +1,18 @@
+import type { CliFlags } from './command-schema.ts';
+import type { DaemonLockPolicy } from '../daemon/types.ts';
+export type BindingSettings = {
+    defaultPlatform?: CliFlags['platform'];
+    lockPolicy?: DaemonLockPolicy;
+};
+type BindingPolicyOverrides = Pick<Partial<CliFlags>, 'sessionLock' | 'sessionLocked' | 'sessionLockConflicts'>;
+type LockableFlags = Pick<Partial<CliFlags>, 'platform' | 'target' | 'device' | 'udid' | 'serial' | 'iosSimulatorDeviceSet' | 'androidDeviceAllowlist'>;
+type BindingOptions = {
+    env?: NodeJS.ProcessEnv;
+    policyOverrides?: BindingPolicyOverrides;
+    configuredPlatform?: CliFlags['platform'];
+    configuredSession?: string;
+    inheritedPlatform?: CliFlags['platform'];
+};
+export declare function applyDefaultPlatformBinding<T extends LockableFlags>(flags: T, options?: BindingOptions): T;
+export declare function resolveBindingSettings(options: BindingOptions): BindingSettings;
+export {};

package/dist/src/utils/snapshot-lines.d.ts

@@ -0,0 +1,12 @@
+import type { SnapshotNode } from './snapshot.ts';
+type SnapshotDisplayLine = {
+    node: SnapshotNode;
+    depth: number;
+    type: string;
+    text: string;
+};
+export declare function buildSnapshotDisplayLines(nodes: SnapshotNode[]): SnapshotDisplayLine[];
+export declare function formatSnapshotLine(node: SnapshotNode, depth: number, hiddenGroup: boolean, normalizedType?: string): string;
+export declare function displayLabel(node: SnapshotNode, type: string): string;
+export declare function formatRole(type: string): string;
+export {};

package/dist/src/utils/snapshot.d.ts

@@ -0,0 +1,42 @@
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type SnapshotOptions = {
+    interactiveOnly?: boolean;
+    compact?: boolean;
+    depth?: number;
+    scope?: string;
+    raw?: boolean;
+};
+export type RawSnapshotNode = {
+    index: number;
+    type?: string;
+    label?: string;
+    value?: string;
+    identifier?: string;
+    rect?: Rect;
+    enabled?: boolean;
+    selected?: boolean;
+    hittable?: boolean;
+    depth?: number;
+    parentIndex?: number;
+};
+export type SnapshotNode = RawSnapshotNode & {
+    ref: string;
+};
+export type SnapshotState = {
+    nodes: SnapshotNode[];
+    createdAt: number;
+    truncated?: boolean;
+    backend?: 'xctest' | 'android';
+};
+export declare function attachRefs(nodes: RawSnapshotNode[]): SnapshotNode[];
+export declare function normalizeRef(input: string): string | null;
+export declare function findNodeByRef(nodes: SnapshotNode[], ref: string): SnapshotNode | null;
+export declare function centerOfRect(rect: Rect): {
+    x: number;
+    y: number;
+};

package/dist/src/utils/timeouts.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveTimeoutMs(raw: string | undefined, fallback: number, min: number): number;
+/** Alias for `resolveTimeoutMs` — semantically marks the caller expects seconds. */
+export declare const resolveTimeoutSeconds: typeof resolveTimeoutMs;

package/dist/src/utils/version.d.ts

@@ -0,0 +1,2 @@
+export declare function readVersion(): string;
+export declare function findProjectRoot(): string;

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "agent-device",
-  "version": "0.7.21",
+  "version": "0.8.0",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
   "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
   "engines": {
     "node": ">=22"
   },

package/skills/agent-device/SKILL.md

@@ -35,6 +35,8 @@ Use this skill as a router, not a full manual.
 - Android local QA: use `install` or `reinstall` for `.apk`/`.aab` files, then relaunch by installed package name.
 - Android React Native + Metro flows: set runtime hints with `runtime set` before `open <package> --relaunch`.
 - In mixed-device environments, always pin the exact target with `--serial`, `--device`, `--udid`, or an isolation scope.
+- For session-bound automation runs, prefer a pre-bound session/platform instead of repeating selectors on every command: set `AGENT_DEVICE_SESSION`, set `AGENT_DEVICE_PLATFORM`, and the daemon will enforce the shared lock policy across CLI, typed client, and RPC entry points.
+- Use `--session-lock reject|strip` (or `AGENT_DEVICE_SESSION_LOCK`) only when you need to override the default reject behavior. Lock mode applies to nested `batch` steps too.
 
 ## Canonical Flows
 
@@ -73,6 +75,35 @@ agent-device close
 
 Do not use `open <apk|aab> --relaunch` on Android. Install/reinstall binaries first, then relaunch by package.
 
+### 1c) Session-Bound Automation Flow
+
+```bash
+export AGENT_DEVICE_SESSION=qa-ios
+export AGENT_DEVICE_PLATFORM=ios
+export AGENT_DEVICE_SESSION_LOCK=strip
+
+agent-device open MyApp --relaunch
+agent-device snapshot -i
+agent-device batch --steps-file /tmp/qa-steps.json --json
+agent-device close
+```
+
+Use this for orchestrators that must preserve one bound session/device across many plain CLI calls without a wrapper script. In `strip` mode, conflicting selectors such as `--target`, `--device`, `--udid`, `--serial`, and isolation-scope overrides are ignored instead of retargeting the run.
+
+### 1d) Android Emulator Session-Bound Flow
+
+```bash
+export AGENT_DEVICE_SESSION=qa-android
+export AGENT_DEVICE_PLATFORM=android
+
+agent-device reinstall MyApp /path/to/app-debug.apk --serial emulator-5554
+agent-device --session-lock reject open com.example.myapp --relaunch
+agent-device snapshot -i
+agent-device close --shutdown
+```
+
+Use this when an Android emulator session must stay pinned while an agent or test runner issues plain CLI commands over time.
+
 ### 2) Debug/Crash Flow
 
 ```bash
@@ -147,17 +178,22 @@ agent-device session list
 ```
 
 Use `boot` only as fallback when `open` cannot find/connect to a ready target.
+If the workspace repeats the same selectors or device/session flags, prefer a checked-in `agent-device.json` or `--config <path>` over repeating them inline.
+Environment-level defaults follow the same fields via `AGENT_DEVICE_*` names, so persistent host-specific values belong there rather than in committed project config.
+That includes bound-session defaults such as `sessionLock` / `AGENT_DEVICE_SESSION_LOCK` when automation should consistently reject or strip conflicting device routing flags.
 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).
 For Android React Native + Metro flows, install or reinstall the APK first, set runtime hints with `runtime set`, then use `open <package> --relaunch`; do not use `open <apk|aab> --relaunch`.
 For local iOS QA in mixed simulator/device environments, use `ensure-simulator` and pass `--device` or `--udid` so automation does not attach to a physical device by accident.
+For session-bound automation, prefer `AGENT_DEVICE_SESSION` + `AGENT_DEVICE_PLATFORM`; that bound-session default now enables lock mode automatically.
 
 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.
+- In bound-session `strip` mode, conflicting per-call scope/selectors are ignored and the configured binding is restored for the request. Batch steps still inherit the parent `--platform` when they do not set their own.
 
 Simulator provisioning quick reference:
 - Use `ensure-simulator` to create or reuse a named iOS simulator inside a device set before starting a session.

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

@@ -50,6 +50,17 @@ curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
 ```
 
+Example session-locked command request:
+
+```bash
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
+  -H "content-type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"jsonrpc":"2.0","id":"cmd-1","method":"agent_device.command","params":{"session":"qa-ios","command":"snapshot","positionals":[],"meta":{"lockPolicy":"reject","lockPlatform":"ios","tenantId":"acme","runId":"run-123","leaseId":"<lease-id>"}}}'
+```
+
+Direct RPC callers can send the same session lock concept as the CLI and typed client through `meta.lockPolicy` and optional `meta.lockPlatform`.
+
 ## Command admission contract
 
 For tenant-isolated command execution, pass all four flags:

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

@@ -14,6 +14,7 @@ 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 orchestrated QA runs, prefer a pre-bound session/platform over repeating per-command selectors.
 - 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.
@@ -21,11 +22,46 @@ 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.
+- Use `close --shutdown` on iOS simulators or Android emulators to shut down the target 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.
 
+## Session-bound automation
+
+Use this when an external orchestrator must keep every CLI call on the same session/device without a wrapper script.
+
+```bash
+export AGENT_DEVICE_SESSION=qa-ios
+export AGENT_DEVICE_PLATFORM=ios
+export AGENT_DEVICE_SESSION_LOCK=strip
+
+agent-device open MyApp --relaunch
+agent-device snapshot -i
+agent-device press @e3
+agent-device close
+```
+
+- `AGENT_DEVICE_SESSION` and `AGENT_DEVICE_PLATFORM` provide the default binding when `--session` and `--platform` are omitted.
+- A configured `AGENT_DEVICE_SESSION` enables lock policy enforcement by convention. The default mode is `reject`.
+- `--session-lock reject|strip` or `AGENT_DEVICE_SESSION_LOCK=reject|strip` controls whether conflicting selectors fail or are ignored.
+- The daemon enforces the same lock policy for CLI requests, typed client calls, and direct RPC commands.
+- Conflicts include explicit retargeting selectors such as `--platform`, `--target`, `--device`, `--udid`, `--serial`, `--ios-simulator-device-set`, and `--android-device-allowlist`.
+- `--session-locked`, `--session-lock-conflicts`, `AGENT_DEVICE_SESSION_LOCKED`, and `AGENT_DEVICE_SESSION_LOCK_CONFLICTS` remain supported as compatibility aliases.
+- Lock policy applies to nested `batch` steps too. If a step omits `platform`, it still inherits the parent batch `--platform` instead of being silently replaced by an environment default.
+
+Android emulator variant:
+
+```bash
+export AGENT_DEVICE_SESSION=qa-android
+export AGENT_DEVICE_PLATFORM=android
+
+agent-device reinstall MyApp /path/to/app-debug.apk --serial emulator-5554
+agent-device --session-lock reject open com.example.myapp --relaunch
+agent-device snapshot -i
+agent-device close --shutdown
+```
+
 ## Scoped device isolation
 
 Use scoped discovery when sessions must not see host-global device lists.