agent-device 0.7.22 → 0.8.1

package/dist/src/platforms/install-source.d.ts

@@ -13,6 +13,7 @@ type MaterializeInstallableOptions = {
         isDirectory(): boolean;
     }) => boolean;
     installableLabel: string;
+    allowArchiveExtraction?: boolean;
     signal?: AbortSignal;
     downloadTimeoutMs?: number;
 };
@@ -23,4 +24,6 @@ export type MaterializedInstallable = {
 };
 export declare function materializeInstallablePath(options: MaterializeInstallableOptions): Promise<MaterializedInstallable>;
 export declare function expandSourcePath(inputPath: string): string;
+export declare function validateDownloadSourceUrl(parsedUrl: URL): Promise<void>;
+export declare function isTrustedInstallSourceUrl(sourceUrl: string | URL): boolean;
 export {};

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

@@ -1,4 +1,4 @@
-import { type CliFlags } from './command-schema.ts';
+import { type CliFlags, type FlagKey } from './command-schema.ts';
 type ParsedArgs = {
     command: string | null;
     positionals: string[];
@@ -8,8 +8,20 @@ type ParsedArgs = {
 type ParseArgsOptions = {
     strictFlags?: boolean;
 };
-export declare function parseArgs(argv: string[], options?: ParseArgsOptions): ParsedArgs;
-export declare function toDaemonFlags(flags: CliFlags): Omit<CliFlags, 'json' | 'help' | 'version'>;
+type ParsedFlagRecord = {
+    key: FlagKey;
+    token: string;
+};
+type RawParsedArgs = ParsedArgs & {
+    providedFlags: ParsedFlagRecord[];
+};
+type FinalizeArgsOptions = ParseArgsOptions & {
+    defaultFlags?: Partial<CliFlags>;
+};
+export declare function parseArgs(argv: string[], options?: FinalizeArgsOptions): ParsedArgs;
+export declare function parseRawArgs(argv: string[]): RawParsedArgs;
+export declare function finalizeParsedArgs(parsed: RawParsedArgs, options?: FinalizeArgsOptions): ParsedArgs;
+export declare function toDaemonFlags(flags: CliFlags): Omit<CliFlags, 'json' | 'config' | 'help' | 'version'>;
 export declare function usage(): string;
 export declare function usageForCommand(command: string): string | null;
 export {};

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

@@ -0,0 +1,9 @@
+import { type CliFlags } from './command-schema.ts';
+type EnvMap = Record<string, string | undefined>;
+export declare function resolveConfigBackedFlagDefaults(options: {
+    command: string | null;
+    cwd: string;
+    cliFlags: CliFlags;
+    env?: EnvMap;
+}): Partial<CliFlags>;
+export {};

package/dist/src/utils/cli-option-schema.d.ts

@@ -0,0 +1,19 @@
+import { type FlagDefinition, type FlagKey } from './command-schema.ts';
+export type OptionSpec = {
+    key: FlagKey;
+    flagDefinitions: readonly FlagDefinition[];
+    config: {
+        enabled: boolean;
+        key: string;
+    };
+    env: {
+        names: readonly string[];
+    };
+    supportsCommand(command: string | null): boolean;
+};
+export declare function getOptionSpecs(): readonly OptionSpec[];
+export declare function getOptionSpec(key: FlagKey): OptionSpec | undefined;
+export declare function getOptionSpecForToken(token: string): OptionSpec | undefined;
+export declare function getConfigurableOptionSpecs(command: string | null): OptionSpec[];
+export declare function isFlagSupportedForCommand(key: FlagKey, command: string | null): boolean;
+export declare function parseOptionValueFromSource(spec: OptionSpec, value: unknown, sourceLabel: string, rawKey: string): unknown;

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

@@ -1,5 +1,6 @@
 export type CliFlags = {
     json: boolean;
+    config?: string;
     stateDir?: string;
     daemonBaseUrl?: string;
     daemonAuthToken?: string;
@@ -9,6 +10,9 @@ export type CliFlags = {
     sessionIsolation?: 'none' | 'tenant';
     runId?: string;
     leaseId?: string;
+    sessionLock?: 'reject' | 'strip';
+    sessionLocked?: boolean;
+    sessionLockConflicts?: 'reject' | 'strip';
     platform?: 'ios' | 'android' | 'apple';
     target?: 'mobile' | 'tv';
     device?: string;
@@ -84,6 +88,7 @@ type CommandSchema = {
 };
 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[];

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/package.json

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

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.
@@ -26,6 +27,41 @@ 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.
 
+## 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.