agent-device 0.8.3 → 0.8.5

package/dist/src/platforms/android/index.d.ts

@@ -4,4 +4,5 @@ export { pressAndroid, swipeAndroid, backAndroid, homeAndroid, appSwitcherAndroi
 export { type AndroidKeyboardState, getAndroidKeyboardState, dismissAndroidKeyboard, readAndroidClipboardText, writeAndroidClipboardText, } from './device-input-state.ts';
 export { setAndroidSetting } from './settings.ts';
 export { pushAndroidNotification } from './notifications.ts';
-export { snapshotAndroid, screenshotAndroid } from './snapshot.ts';
+export { snapshotAndroid } from './snapshot.ts';
+export { screenshotAndroid } from './screenshot.ts';

package/dist/src/platforms/android/screenshot.d.ts

@@ -0,0 +1,16 @@
+import type { DeviceInfo } from '../../utils/device.ts';
+type ScreenshotAndroidDeps = {
+    enableDemoMode: (device: DeviceInfo) => Promise<void>;
+    settle: (ms: number) => Promise<void>;
+    capture: (device: DeviceInfo, outPath: string) => Promise<void>;
+    disableDemoMode: (device: DeviceInfo) => Promise<void>;
+};
+export declare function screenshotAndroid(device: DeviceInfo, outPath: string, deps?: ScreenshotAndroidDeps): Promise<void>;
+/**
+ * Enable Android demo mode and set deterministic time in status bar
+ * for consistent screenshots.
+ */
+export declare function enableAndroidDemoMode(device: DeviceInfo): Promise<void>;
+/** Disable demo mode and restore the live status bar. */
+export declare function disableAndroidDemoMode(device: DeviceInfo): Promise<void>;
+export {};

package/dist/src/platforms/android/snapshot.d.ts

@@ -4,5 +4,4 @@ export declare function snapshotAndroid(device: DeviceInfo, options?: SnapshotOp
     nodes: RawSnapshotNode[];
     truncated?: boolean;
 }>;
-export declare function screenshotAndroid(device: DeviceInfo, outPath: string): Promise<void>;
 export declare function dumpUiHierarchy(device: DeviceInfo): Promise<string>;

package/dist/src/platforms/ios/config.d.ts

@@ -2,6 +2,7 @@ export declare const IOS_BOOT_TIMEOUT_MS: number;
 export declare const IOS_SIMCTL_LIST_TIMEOUT_MS: number;
 export declare const IOS_APP_LAUNCH_TIMEOUT_MS: number;
 export declare const IOS_DEVICECTL_TIMEOUT_MS: number;
+export declare const IOS_SIMULATOR_FOCUS_TIMEOUT_MS: number;
 export declare const IOS_SIMULATOR_SCREENSHOT_TIMEOUT_MS: number;
 export declare const IOS_RUNNER_SCREENSHOT_COPY_TIMEOUT_MS: number;
 export declare const IOS_SIMULATOR_SCREENSHOT_RETRY_MAX_ATTEMPTS = 5;

package/dist/src/platforms/ios/index.d.ts

@@ -1,3 +1,3 @@
 export { closeIosApp, installIosApp, installIosInstallablePath, listIosApps, listSimulatorApps, openIosApp, openIosDevice, pushIosNotification, readIosClipboardText, reinstallIosApp, resolveIosApp, screenshotIos, setIosSetting, uninstallIosApp, writeIosClipboardText, } from './apps.ts';
 export { ensureBootedSimulator } from './simulator.ts';
-export { parseIosDeviceAppsPayload, type IosAppInfo, } from './devicectl.ts';
+export { parseIosDeviceAppsPayload, type IosAppInfo } from './devicectl.ts';

package/dist/src/platforms/ios/screenshot-status-bar.d.ts

@@ -0,0 +1,2 @@
+import type { DeviceInfo } from '../../utils/device.ts';
+export declare function prepareSimulatorStatusBarForScreenshot(device: DeviceInfo): Promise<() => Promise<void>>;

package/dist/src/platforms/ios/screenshot.d.ts

@@ -1,6 +1,7 @@
 import type { DeviceInfo } from '../../utils/device.ts';
 type SimulatorScreenshotFlowDeps = {
     ensureBooted: (device: DeviceInfo) => Promise<void>;
+    prepareStatusBarForScreenshot: (device: DeviceInfo) => Promise<() => Promise<void>>;
     captureWithRetry: (device: DeviceInfo, outPath: string) => Promise<void>;
     captureWithRunner: (device: DeviceInfo, outPath: string, appBundleId?: string) => Promise<void>;
     shouldFallbackToRunner: (error: unknown) => boolean;
@@ -10,4 +11,4 @@ export declare function captureSimulatorScreenshotWithFallback(device: DeviceInf
 export declare function resolveSimulatorRunnerScreenshotCandidatePaths(containerPath: string, remoteFileName: string): string[];
 export declare function shouldFallbackToRunnerForIosScreenshot(error: unknown): boolean;
 export declare function shouldRetryIosSimulatorScreenshot(error: unknown): boolean;
-export {};
+export { prepareSimulatorStatusBarForScreenshot } from './screenshot-status-bar.ts';

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

@@ -35,6 +35,8 @@ export type CliFlags = {
     snapshotDepth?: number;
     snapshotScope?: string;
     snapshotRaw?: boolean;
+    baseline?: string;
+    threshold?: string;
     appsFilter?: 'user-installed' | 'all';
     count?: number;
     fps?: number;
@@ -45,12 +47,15 @@ export type CliFlags = {
     pauseMs?: number;
     pattern?: 'one-way' | 'ping-pong';
     activity?: string;
+    header?: string[];
     saveScript?: boolean | string;
     shutdown?: boolean;
     relaunch?: boolean;
     headless?: boolean;
     restart?: boolean;
     noRecord?: boolean;
+    retainPaths?: boolean;
+    retentionMs?: number;
     replayUpdate?: boolean;
     steps?: string;
     stepsFile?: string;
@@ -70,6 +75,7 @@ export type FlagDefinition = {
     key: FlagKey;
     names: readonly string[];
     type: FlagType;
+    multiple?: boolean;
     enumValues?: readonly string[];
     min?: number;
     max?: number;

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

@@ -23,5 +23,5 @@ type DeviceSelectionContext = {
 };
 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 declare function resolveDevice(devices: DeviceInfo[], selector: DeviceSelector, context?: DeviceSelectionContext): Promise<DeviceInfo>;
 export {};

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

@@ -1,4 +1,5 @@
 import type { DeviceInfo } from './device.ts';
+import type { PermissionSettingOptions } from '../platforms/permission-utils.ts';
 export type RunnerContext = {
     requestId?: string;
     appBundleId?: string;
@@ -26,6 +27,12 @@ type Interactor = {
         attempts?: number;
     } | void>;
     screenshot(outPath: string, appBundleId?: string): Promise<void>;
+    back(): Promise<void>;
+    home(): Promise<void>;
+    appSwitcher(): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
+    setSetting(setting: string, state: string, appId?: string, options?: PermissionSettingOptions): Promise<void>;
 };
 export declare function getInteractor(device: DeviceInfo, runnerContext: RunnerContext): Interactor;
 export {};

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

@@ -1,7 +1,8 @@
 import { AppError, type NormalizedError } from './errors.ts';
+import type { ScreenshotDiffResult } from './screenshot-diff.ts';
 type JsonResult = {
     success: true;
-    data?: Record<string, unknown>;
+    data?: unknown;
 } | {
     success: false;
     error: {
@@ -22,4 +23,5 @@ export declare function formatSnapshotText(data: Record<string, unknown>, option
     flatten?: boolean;
 }): string;
 export declare function formatSnapshotDiffText(data: Record<string, unknown>): string;
+export declare function formatScreenshotDiffText(data: ScreenshotDiffResult): string;
 export {};

package/dist/src/utils/path-resolution.d.ts

@@ -0,0 +1,8 @@
+type EnvMap = Record<string, string | undefined>;
+type PathResolutionOptions = {
+    cwd?: string;
+    env?: EnvMap;
+};
+export declare function expandUserHomePath(inputPath: string, options?: PathResolutionOptions): string;
+export declare function resolveUserPath(inputPath: string, options?: PathResolutionOptions): string;
+export {};

package/dist/src/utils/screenshot-diff.d.ts

@@ -0,0 +1,23 @@
+export type ScreenshotDimensionMismatch = {
+    expected: {
+        width: number;
+        height: number;
+    };
+    actual: {
+        width: number;
+        height: number;
+    };
+};
+export type ScreenshotDiffResult = {
+    diffPath?: string;
+    totalPixels: number;
+    differentPixels: number;
+    mismatchPercentage: number;
+    match: boolean;
+    dimensionMismatch?: ScreenshotDimensionMismatch;
+};
+export type ScreenshotDiffOptions = {
+    threshold?: number;
+    outputPath?: string;
+};
+export declare function compareScreenshots(baselinePath: string, currentPath: string, options?: ScreenshotDiffOptions): Promise<ScreenshotDiffResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
@@ -20,7 +20,6 @@
     "agent-device": "bin/agent-device.mjs"
   },
   "scripts": {
-    "lint": "node --eval \"console.log('no lint')\"",
     "build": "rslib build",
     "clean:daemon": "rm -f ~/.agent-device/daemon.json && rm -f ~/.agent-device/daemon.lock",
     "build:node": "pnpm build && pnpm clean:daemon",
@@ -29,7 +28,7 @@
     "build:xcuitest:tvos": "rm -rf ~/.agent-device/ios-runner/derived/tvos && xcodebuild build-for-testing -project ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj -scheme AgentDeviceRunner -destination \"generic/platform=tvOS Simulator\" -derivedDataPath ~/.agent-device/ios-runner/derived/tvos",
     "build:all": "pnpm build:node && pnpm build:xcuitest",
     "ad": "node bin/agent-device.mjs",
-    "format": "prettier --write .",
+    "format": "prettier --write src test skills",
     "prepublishOnly": "pnpm build:all",
     "prepack": "pnpm build:all",
     "typecheck": "tsc -p tsconfig.json",
@@ -67,11 +66,12 @@
     "printWidth": 100
   },
   "dependencies": {
-    "@clack/prompts": "^1.0.0"
+    "pngjs": "^7.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
     "@rslib/core": "0.19.4",
+    "@types/node": "^22.0.0",
+    "@types/pngjs": "^6.0.5",
     "prettier": "^3.3.3",
     "typescript": "^5.9.3"
   }

package/skills/agent-device/SKILL.md

@@ -155,6 +155,7 @@ curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
 ```
 
 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.
@@ -173,6 +174,7 @@ agent-device open [app|url] [url]
 agent-device open [app] --relaunch
 agent-device close [app]
 agent-device install <app> <path-to-binary>
+agent-device install-from-source <url> [--header "name:value"]
 agent-device reinstall <app> <path-to-binary>
 agent-device session list
 ```
@@ -189,6 +191,7 @@ For local iOS QA in mixed simulator/device environments, use `ensure-simulator`
 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`.
@@ -196,12 +199,14 @@ Isolation scoping quick reference:
 - 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.
 - `--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).
 - tvOS: runner-driven interactions and snapshots are supported (`snapshot`, `wait`, `press`, `fill`, `get`, `scroll`, `back`, `home`, `app-switcher`, `record` and related selector flows).

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

@@ -62,6 +62,7 @@ agent-device diff snapshot -i           # Shows +/− structural lines vs prior
 ```
 
 Efficient pattern:
+
 - Initialize once at a stable point.
 - Mutate UI (`press`, `fill`, `swipe`).
 - Run `diff snapshot` after interactions to confirm expected change shape with bounded output.

package/skills/dogfood/SKILL.md

@@ -12,14 +12,14 @@ Systematically explore a mobile app, find issues, and produce a report with full
 
 Only the **Target app** is required. Everything else has sensible defaults.
 
-| Parameter | Default | Example override |
-|-----------|---------|-----------------|
-| **Target app** | _(required)_ | `Settings`, `com.example.app`, deep link URL |
-| **Platform** | Infer from user context; otherwise ask (`ios` or `android`) | `--platform ios` |
-| **Session name** | Slugified app/platform (for example `settings-ios`) | `--session my-session` |
-| **Output directory** | `./dogfood-output/` | `Output directory: /tmp/mobile-qa` |
-| **Scope** | Full app | `Focus on onboarding and profile` |
-| **Authentication** | None | `Sign in to user@example.com` |
+| Parameter            | Default                                                     | Example override                             |
+| -------------------- | ----------------------------------------------------------- | -------------------------------------------- |
+| **Target app**       | _(required)_                                                | `Settings`, `com.example.app`, deep link URL |
+| **Platform**         | Infer from user context; otherwise ask (`ios` or `android`) | `--platform ios`                             |
+| **Session name**     | Slugified app/platform (for example `settings-ios`)         | `--session my-session`                       |
+| **Output directory** | `./dogfood-output/`                                         | `Output directory: /tmp/mobile-qa`           |
+| **Scope**            | Full app                                                    | `Focus on onboarding and profile`            |
+| **Authentication**   | None                                                        | `Sign in to user@example.com`                |
 
 If the user gives enough context to start, begin immediately with defaults. Ask follow-up only when a required detail is missing (for example platform or credentials).
 
@@ -172,12 +172,12 @@ agent-device --session {SESSION} close
 
 ## References
 
-| Reference | When to Read |
-|-----------|--------------|
+| Reference                                                    | When to Read                                    |
+| ------------------------------------------------------------ | ----------------------------------------------- |
 | [references/issue-taxonomy.md](references/issue-taxonomy.md) | Start of session; severity/categories/checklist |
 
 ## Templates
 
-| Template | Purpose |
-|----------|---------|
+| Template                                                                     | Purpose                                       |
+| ---------------------------------------------------------------------------- | --------------------------------------------- |
 | [templates/dogfood-report-template.md](templates/dogfood-report-template.md) | Copy into output directory as the report file |

package/skills/dogfood/references/issue-taxonomy.md

@@ -4,12 +4,12 @@ Reference for categorizing issues found during mobile dogfooding.
 
 ## Severity Levels
 
-| Severity | Definition |
-|----------|------------|
+| Severity     | Definition                                                                |
+| ------------ | ------------------------------------------------------------------------- |
 | **critical** | Blocks a core workflow, causes data loss, or crashes/freeze loops the app |
-| **high** | Major feature broken or unusable, no practical workaround |
-| **medium** | Feature works with notable friction or partial failure; workaround exists |
-| **low** | Minor cosmetic or polish issue |
+| **high**     | Major feature broken or unusable, no practical workaround                 |
+| **medium**   | Feature works with notable friction or partial failure; workaround exists |
+| **low**      | Minor cosmetic or polish issue                                            |
 
 ## Categories
 

package/skills/dogfood/templates/dogfood-report-template.md

@@ -1,21 +1,21 @@
 # Dogfood Report: {APP_NAME}
 
-| Field | Value |
-|-------|-------|
-| **Date** | {DATE} |
-| **Platform** | {PLATFORM} |
-| **Target App** | {TARGET_APP} |
-| **Session** | {SESSION_NAME} |
-| **Scope** | {SCOPE} |
+| Field          | Value          |
+| -------------- | -------------- |
+| **Date**       | {DATE}         |
+| **Platform**   | {PLATFORM}     |
+| **Target App** | {TARGET_APP}   |
+| **Session**    | {SESSION_NAME} |
+| **Scope**      | {SCOPE}        |
 
 ## Summary
 
-| Severity | Count |
-|----------|-------|
-| Critical | 0 |
-| High | 0 |
-| Medium | 0 |
-| Low | 0 |
+| Severity  | Count |
+| --------- | ----- |
+| Critical  | 0     |
+| High      | 0     |
+| Medium    | 0     |
+| Low       | 0     |
 | **Total** | **0** |
 
 ## Issues
@@ -24,12 +24,12 @@
 
 ### ISSUE-001: {Short title}
 
-| Field | Value |
-|-------|-------|
-| **Severity** | critical / high / medium / low |
-| **Category** | visual / functional / ux / content / performance / diagnostics / permissions / accessibility |
-| **Screen / Route** | {screen where issue was found} |
-| **Repro Video** | {path to video, or N/A for static issues} |
+| Field              | Value                                                                                        |
+| ------------------ | -------------------------------------------------------------------------------------------- |
+| **Severity**       | critical / high / medium / low                                                               |
+| **Category**       | visual / functional / ux / content / performance / diagnostics / permissions / accessibility |
+| **Screen / Route** | {screen where issue was found}                                                               |
+| **Repro Video**    | {path to video, or N/A for static issues}                                                    |
 
 **Description**
 

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

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