agent-device 0.12.5 → 0.12.7

package/dist/src/testing/conformance.d.ts

@@ -1,3 +1,5 @@
+export declare const adminConformanceSuite: CommandConformanceSuite;
+
 declare type AgentDeviceBackend = {
     platform: AgentDeviceBackendPlatform;
     capabilities?: BackendCapabilitySet;
@@ -11,12 +13,44 @@ declare type AgentDeviceBackend = {
     typeText?(context: BackendCommandContext, text: string, options?: {
         delayMs?: number;
     }): Promise<BackendActionResult>;
+    focus?(context: BackendCommandContext, point: Point): Promise<BackendActionResult>;
+    longPress?(context: BackendCommandContext, point: Point, options?: BackendLongPressOptions): Promise<BackendActionResult>;
+    swipe?(context: BackendCommandContext, from: Point, to: Point, options?: BackendSwipeOptions): Promise<BackendActionResult>;
+    scroll?(context: BackendCommandContext, target: BackendScrollTarget, options: BackendScrollOptions): Promise<BackendActionResult>;
+    pinch?(context: BackendCommandContext, options: BackendPinchOptions): Promise<BackendActionResult>;
     pressKey?(context: BackendCommandContext, key: string, options?: {
         modifiers?: string[];
     }): Promise<BackendActionResult>;
-    openApp?(context: BackendCommandContext, target: BackendOpenTarget): Promise<BackendActionResult>;
+    pressBack?(context: BackendCommandContext, options?: BackendBackOptions): Promise<BackendActionResult>;
+    pressHome?(context: BackendCommandContext): Promise<BackendActionResult>;
+    rotate?(context: BackendCommandContext, orientation: BackendDeviceOrientation): Promise<BackendActionResult>;
+    setKeyboard?(context: BackendCommandContext, options: BackendKeyboardOptions): Promise<BackendKeyboardResult | BackendActionResult>;
+    getClipboard?(context: BackendCommandContext): Promise<string | BackendClipboardTextResult>;
+    setClipboard?(context: BackendCommandContext, text: string): Promise<BackendActionResult>;
+    openSettings?(context: BackendCommandContext, target?: string): Promise<BackendActionResult>;
+    handleAlert?(context: BackendCommandContext, action: BackendAlertAction, options?: {
+        timeoutMs?: number;
+    }): Promise<BackendAlertResult>;
+    openAppSwitcher?(context: BackendCommandContext): Promise<BackendActionResult>;
+    openApp?(context: BackendCommandContext, target: BackendOpenTarget, options?: BackendOpenOptions): Promise<BackendActionResult>;
     closeApp?(context: BackendCommandContext, app?: string): Promise<BackendActionResult>;
-    installApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendActionResult>;
+    listApps?(context: BackendCommandContext, filter?: BackendAppListFilter): Promise<readonly BackendAppInfo[]>;
+    getAppState?(context: BackendCommandContext, app: string): Promise<BackendAppState>;
+    pushFile?(context: BackendCommandContext, input: BackendPushInput, target: string): Promise<BackendActionResult>;
+    triggerAppEvent?(context: BackendCommandContext, event: BackendAppEvent): Promise<BackendActionResult>;
+    listDevices?(context: BackendCommandContext, filter?: BackendDeviceFilter): Promise<readonly BackendDeviceInfo[]>;
+    bootDevice?(context: BackendCommandContext, target?: BackendDeviceTarget): Promise<BackendActionResult>;
+    ensureSimulator?(context: BackendCommandContext, options: BackendEnsureSimulatorOptions): Promise<BackendEnsureSimulatorResult>;
+    resolveInstallSource?(context: BackendCommandContext, source: BackendInstallSource): Promise<BackendInstallSource>;
+    installApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendInstallResult>;
+    reinstallApp?(context: BackendCommandContext, target: BackendInstallTarget): Promise<BackendInstallResult>;
+    startRecording?(context: BackendCommandContext, options?: BackendRecordingOptions): Promise<BackendRecordingResult>;
+    stopRecording?(context: BackendCommandContext, options?: BackendRecordingOptions): Promise<BackendRecordingResult>;
+    startTrace?(context: BackendCommandContext, options?: BackendTraceOptions): Promise<BackendTraceResult>;
+    stopTrace?(context: BackendCommandContext, options?: BackendTraceOptions): Promise<BackendTraceResult>;
+    readLogs?(context: BackendCommandContext, options?: BackendReadLogsOptions): Promise<BackendReadLogsResult>;
+    dumpNetwork?(context: BackendCommandContext, options?: BackendDumpNetworkOptions): Promise<BackendDumpNetworkResult>;
+    measurePerf?(context: BackendCommandContext, options?: BackendMeasurePerfOptions): Promise<BackendMeasurePerfResult>;
 };
 
 declare type AgentDeviceBackendPlatform = 'ios' | 'android' | 'macos' | 'linux';
@@ -31,6 +65,8 @@ declare type AgentDeviceRuntime = {
     signal?: AbortSignal;
 };
 
+export declare const appsConformanceSuite: CommandConformanceSuite;
+
 declare type ArtifactAdapter = {
     resolveInput(ref: FileInputRef, options: ResolveInputOptions): Promise<ResolvedInputFile>;
     reserveOutput(ref: FileOutputRef | undefined, options: ReserveOutputOptions): Promise<ReservedOutputFile>;
@@ -61,10 +97,65 @@ declare const BACKEND_CAPABILITY_NAMES: readonly ["android.shell", "ios.runnerCo
 
 declare type BackendActionResult = Record<string, unknown> | void;
 
+declare type BackendAlertAction = 'get' | 'accept' | 'dismiss' | 'wait';
+
+declare type BackendAlertInfo = {
+    title?: string;
+    message?: string;
+    buttons?: string[];
+};
+
+declare type BackendAlertResult = {
+    kind: 'alertStatus';
+    alert: BackendAlertInfo | null;
+} | {
+    kind: 'alertHandled';
+    handled: boolean;
+    alert?: BackendAlertInfo;
+    button?: string;
+} | {
+    kind: 'alertWait';
+    alert: BackendAlertInfo | null;
+    waitedMs?: number;
+    timedOut?: boolean;
+};
+
+declare type BackendAppEvent = {
+    name: string;
+    payload?: Record<string, unknown>;
+};
+
+declare type BackendAppInfo = {
+    id: string;
+    name?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+};
+
+declare type BackendAppListFilter = 'all' | 'user-installed';
+
+declare type BackendAppState = {
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    activity?: string;
+    state?: 'unknown' | 'notRunning' | 'running' | 'foreground' | 'background';
+    details?: Record<string, unknown>;
+};
+
+declare type BackendBackOptions = {
+    mode?: 'in-app' | 'system';
+};
+
 declare type BackendCapabilityName = (typeof BACKEND_CAPABILITY_NAMES)[number];
 
 declare type BackendCapabilitySet = readonly BackendCapabilityName[];
 
+declare type BackendClipboardTextResult = {
+    text: string;
+};
+
 declare type BackendCommandContext = {
     session?: string;
     requestId?: string;
@@ -74,6 +165,71 @@ declare type BackendCommandContext = {
     metadata?: Record<string, unknown>;
 };
 
+declare type BackendDeviceFilter = {
+    platform?: AgentDeviceBackendPlatform | 'apple';
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+};
+
+declare type BackendDeviceInfo = {
+    id: string;
+    name: string;
+    platform: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    kind?: 'simulator' | 'emulator' | 'device' | 'desktop';
+    booted?: boolean;
+    details?: Record<string, unknown>;
+};
+
+declare type BackendDeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+
+declare type BackendDeviceTarget = {
+    id?: string;
+    name?: string;
+    platform?: AgentDeviceBackendPlatform;
+    target?: 'mobile' | 'tv' | 'desktop';
+    headless?: boolean;
+};
+
+declare type BackendDiagnosticsPageOptions = BackendDiagnosticsTimeWindow & {
+    cursor?: string;
+    limit?: number;
+};
+
+declare type BackendDiagnosticsTimeWindow = {
+    since?: string;
+    until?: string;
+};
+
+declare type BackendDumpNetworkOptions = BackendDiagnosticsPageOptions & {
+    include?: BackendNetworkIncludeMode;
+};
+
+declare type BackendDumpNetworkResult = {
+    entries: readonly BackendNetworkEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+declare type BackendEnsureSimulatorOptions = {
+    device: string;
+    runtime?: string;
+    boot?: boolean;
+    reuseExisting?: boolean;
+};
+
+declare type BackendEnsureSimulatorResult = {
+    udid: string;
+    device: string;
+    runtime: string;
+    created: boolean;
+    booted: boolean;
+    simulatorSetPath?: string | null;
+};
+
 declare type BackendEscapeHatches = {
     androidShell?(context: BackendCommandContext, args: readonly string[]): Promise<BackendShellResult>;
     iosRunnerCommand?(context: BackendCommandContext, command: BackendRunnerCommand): Promise<BackendActionResult>;
@@ -88,21 +244,166 @@ declare type BackendFindTextResult = {
     found: boolean;
 };
 
+declare type BackendInstallResult = Record<string, unknown> & {
+    appId?: string;
+    appName?: string;
+    bundleId?: string;
+    packageName?: string;
+    launchTarget?: string;
+    installablePath?: string;
+    archivePath?: string;
+};
+
+declare type BackendInstallSource = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'uploadedArtifact';
+    id: string;
+} | {
+    kind: 'url';
+    url: string;
+};
+
 declare type BackendInstallTarget = {
-    app: string;
-    artifactPath: string;
+    app?: string;
+    source: BackendInstallSource;
+};
+
+declare type BackendKeyboardOptions = {
+    action: 'status' | 'get' | 'dismiss';
+};
+
+declare type BackendKeyboardResult = {
+    platform?: 'android' | 'ios' | 'macos' | 'linux';
+    action?: BackendKeyboardOptions['action'];
+    visible?: boolean;
+    inputType?: string | null;
+    type?: string | null;
+    wasVisible?: boolean;
+    dismissed?: boolean;
+    attempts?: number;
+};
+
+declare type BackendLogEntry = {
+    timestamp?: string;
+    level?: 'debug' | 'info' | 'warn' | 'error' | string;
+    message: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare type BackendLongPressOptions = {
+    durationMs?: number;
+};
+
+declare type BackendMeasurePerfOptions = BackendDiagnosticsTimeWindow & {
+    sampleMs?: number;
+    metrics?: readonly string[];
+};
+
+declare type BackendMeasurePerfResult = {
+    metrics: readonly BackendPerfMetric[];
+    startedAt?: string;
+    endedAt?: string;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
+declare type BackendNetworkEntry = {
+    timestamp?: string;
+    method?: string;
+    url?: string;
+    status?: number;
+    durationMs?: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: string;
+    responseBody?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare type BackendNetworkIncludeMode = 'summary' | 'headers' | 'body' | 'all';
+
+declare type BackendOpenOptions = {
+    relaunch?: boolean;
 };
 
 declare type BackendOpenTarget = {
+    /**
+     * Generic app identifier accepted by the backend. Hosted adapters should
+     * prefer structured appId, bundleId, or packageName when available.
+     */
     app?: string;
+    appId?: string;
+    bundleId?: string;
+    packageName?: string;
+    /**
+     * URL may be used by itself for a deep link or with an app identifier when
+     * the backend supports opening a URL in a specific app context.
+     */
     url?: string;
+    /**
+     * Platform-specific activity override, primarily for Android app launches.
+     */
     activity?: string;
 };
 
+declare type BackendPerfMetric = {
+    name: string;
+    value?: number;
+    unit?: string;
+    status?: 'ok' | 'unavailable' | 'error';
+    message?: string;
+    metadata?: Record<string, unknown>;
+};
+
+declare type BackendPinchOptions = {
+    scale: number;
+    center?: Point;
+};
+
+declare type BackendPushInput = {
+    kind: 'json';
+    payload: Record<string, unknown>;
+} | {
+    kind: 'file';
+    path: string;
+};
+
+declare type BackendReadLogsOptions = BackendDiagnosticsPageOptions & {
+    levels?: readonly string[];
+    search?: string;
+    source?: string;
+};
+
+declare type BackendReadLogsResult = {
+    entries: readonly BackendLogEntry[];
+    nextCursor?: string;
+    timeWindow?: BackendDiagnosticsTimeWindow;
+    backend?: string;
+    redacted?: boolean;
+    notes?: readonly string[];
+};
+
 declare type BackendReadTextResult = {
     text: string;
 };
 
+declare type BackendRecordingOptions = {
+    outPath?: string;
+    fps?: number;
+    quality?: number;
+    showTouches?: boolean;
+};
+
+declare type BackendRecordingResult = Record<string, unknown> & {
+    path?: string;
+    telemetryPath?: string;
+    warning?: string;
+};
+
 declare type BackendRunnerCommand = {
     command: string;
     args?: readonly string[];
@@ -120,6 +421,19 @@ declare type BackendScreenshotResult = {
     overlayRefs?: ScreenshotOverlayRef[];
 };
 
+declare type BackendScrollOptions = {
+    direction: 'up' | 'down' | 'left' | 'right';
+    amount?: number;
+    pixels?: number;
+};
+
+declare type BackendScrollTarget = {
+    kind: 'viewport';
+} | {
+    kind: 'point';
+    point: Point;
+};
+
 declare type BackendShellResult = {
     exitCode: number;
     stdout: string;
@@ -154,6 +468,10 @@ declare type BackendSnapshotResult = {
     appBundleId?: string;
 };
 
+declare type BackendSwipeOptions = {
+    durationMs?: number;
+};
+
 declare type BackendTapOptions = {
     button?: 'primary' | 'secondary' | 'middle';
     count?: number;
@@ -163,6 +481,14 @@ declare type BackendTapOptions = {
     doubleTap?: boolean;
 };
 
+declare type BackendTraceOptions = {
+    outPath?: string;
+};
+
+declare type BackendTraceResult = Record<string, unknown> & {
+    outPath?: string;
+};
+
 export declare const captureConformanceSuite: CommandConformanceSuite;
 
 declare type CommandClock = {
@@ -191,11 +517,16 @@ export declare type CommandConformanceFailure = {
 
 export declare type CommandConformanceFixtures = {
     session: string;
+    app: string;
+    installSourcePath: string;
+    appEventName: string;
+    appPushPayload: Record<string, unknown>;
     visibleSelector: string;
     visibleText: string;
     editableTarget: InteractionTarget;
     fillText: string;
     point: Point;
+    swipeTo: Point;
 };
 
 export declare type CommandConformanceReport = {
@@ -262,6 +593,8 @@ declare type CreateTempFileOptions = {
 
 export declare const defaultCommandConformanceFixtures: CommandConformanceFixtures;
 
+export declare const diagnosticsConformanceSuite: CommandConformanceSuite;
+
 declare type DiagnosticsSink = {
     emit(event: {
         level: 'debug' | 'info' | 'warn' | 'error';
@@ -329,6 +662,8 @@ declare type RawSnapshotNode = {
     hiddenContentBelow?: boolean;
 };
 
+export declare const recordingConformanceSuite: CommandConformanceSuite;
+
 declare type Rect = {
     x: number;
     y: number;
@@ -407,6 +742,8 @@ declare type SnapshotState = {
     comparisonSafe?: boolean;
 };
 
+export declare const systemConformanceSuite: CommandConformanceSuite;
+
 declare type TemporaryFile = {
     path: string;
     visibility: 'internal';

package/dist/src/testing/conformance.js

@@ -1 +1 @@
-import e from"node:assert/strict";import{commands as t,selector as s}from"../commands/index.js";let a={session:"default",visibleSelector:"label=Continue",visibleText:"Continue",editableTarget:s("label=Email"),fillText:"hello@example.com",point:{x:4,y:8}},n=m({name:"capture",cases:[{name:"captures screenshots through the backend primitive",command:"capture.screenshot",run:async(s,a)=>{let n=await t.capture.screenshot(s,{session:a.session});e.equal(typeof n.path,"string"),e.ok(n.path.length>0)}},{name:"captures snapshots with nodes",command:"capture.snapshot",run:async(s,a)=>{let n=await t.capture.snapshot(s,{session:a.session});e.ok(Array.isArray(n.nodes))}}]}),i=m({name:"selectors",cases:[{name:"finds visible text",command:"selectors.find",run:async(s,a)=>{let n=await t.selectors.find(s,{session:a.session,query:a.visibleText,action:"exists"});e.equal(n.kind,"found"),e.equal(n.found,!0)}},{name:"reads text from a selector",command:"selectors.getText",run:async(a,n)=>{let i=await t.selectors.getText(a,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"text"),e.equal(i.text,n.visibleText)}},{name:"checks selector visibility",command:"selectors.isVisible",run:async(a,n)=>{let i=await t.selectors.isVisible(a,{session:n.session,target:s(n.visibleSelector)});e.equal(i.pass,!0)}},{name:"waits for visible text",command:"selectors.waitForText",run:async(s,a)=>{let n=await t.selectors.waitForText(s,{session:a.session,text:a.visibleText,timeoutMs:1});e.equal(n.kind,"text"),e.equal(n.text,a.visibleText)}}]}),o=m({name:"interactions",cases:[{name:"clicks selector targets",command:"interactions.click",run:async(a,n)=>{let i=await t.interactions.click(a,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"selector")}},{name:"presses explicit points",command:"interactions.press",run:async(s,a)=>{let n=await t.interactions.press(s,{session:a.session,target:{kind:"point",...a.point}});e.deepEqual(n.point,a.point)}},{name:"fills editable targets",command:"interactions.fill",run:async(s,a)=>{let n=await t.interactions.fill(s,{session:a.session,target:a.editableTarget,text:a.fillText});e.equal(n.text,a.fillText)}},{name:"types text without a target",command:"interactions.typeText",run:async(s,a)=>{let n=await t.interactions.typeText(s,{session:a.session,text:a.fillText});e.equal(n.text,a.fillText)}}]}),r=[n,i,o];async function l(e,t={}){let s=t.suites??r,a=[];for(let t of s)a.push(await t.run(e));let n=a.flatMap(e=>e.failures);return{target:e.name,passed:a.reduce((e,t)=>e+t.passed,0),failed:a.reduce((e,t)=>e+t.failed,0),failures:n,suites:a}}async function c(e,t={}){let s=await l(e,t);if(s.failed>0)throw AggregateError(s.failures.map(e=>e.error),`${e.name} failed ${s.failed} agent-device conformance case${1===s.failed?"":"s"}`);return s}function m(e){return{name:e.name,cases:e.cases,run:async t=>{let s={...a,...t.fixtures},n=[],i=0;for(let a of e.cases){let o={suite:e.name,caseName:a.name,fixtures:s};try{await t.beforeEach?.(o);let e=await t.createRuntime();await a.run(e,s),i+=1}catch(t){n.push({suite:e.name,caseName:a.name,command:a.command,error:t})}finally{await t.afterEach?.(o)}}return{suite:e.name,passed:i,failed:n.length,failures:n}}}}export{c as assertCommandConformance,n as captureConformanceSuite,r as commandConformanceSuites,a as defaultCommandConformanceFixtures,o as interactionConformanceSuite,l as runCommandConformance,i as selectorConformanceSuite};
+import e from"node:assert/strict";import{commands as a,selector as s}from"../commands/index.js";let t={session:"default",app:"com.example.app",installSourcePath:"/tmp/example.app",appEventName:"example.ready",appPushPayload:{aps:{alert:"hello"}},visibleSelector:"label=Continue",visibleText:"Continue",editableTarget:s("label=Email"),fillText:"hello@example.com",point:{x:4,y:8},swipeTo:{x:24,y:28}},n=w({name:"capture",cases:[{name:"captures screenshots through the backend primitive",command:"capture.screenshot",run:async(s,t)=>{let n=await a.capture.screenshot(s,{session:t.session});e.equal(typeof n.path,"string"),e.ok(n.path.length>0)}},{name:"captures snapshots with nodes",command:"capture.snapshot",run:async(s,t)=>{let n=await a.capture.snapshot(s,{session:t.session});e.ok(Array.isArray(n.nodes))}}]}),i=w({name:"selectors",cases:[{name:"finds visible text",command:"selectors.find",run:async(s,t)=>{let n=await a.selectors.find(s,{session:t.session,query:t.visibleText,action:"exists"});e.equal(n.kind,"found"),e.equal(n.found,!0)}},{name:"reads text from a selector",command:"selectors.getText",run:async(t,n)=>{let i=await a.selectors.getText(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"text"),e.equal(i.text,n.visibleText)}},{name:"checks selector visibility",command:"selectors.isVisible",run:async(t,n)=>{let i=await a.selectors.isVisible(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.pass,!0)}},{name:"waits for visible text",command:"selectors.waitForText",run:async(s,t)=>{let n=await a.selectors.waitForText(s,{session:t.session,text:t.visibleText,timeoutMs:1});e.equal(n.kind,"text"),e.equal(n.text,t.visibleText)}}]}),o=w({name:"interactions",cases:[{name:"clicks selector targets",command:"interactions.click",run:async(t,n)=>{let i=await a.interactions.click(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"selector")}},{name:"presses explicit points",command:"interactions.press",run:async(s,t)=>{let n=await a.interactions.press(s,{session:t.session,target:{kind:"point",...t.point}});e.deepEqual(n.point,t.point)}},{name:"fills editable targets",command:"interactions.fill",run:async(s,t)=>{let n=await a.interactions.fill(s,{session:t.session,target:t.editableTarget,text:t.fillText});e.equal(n.text,t.fillText)}},{name:"types text without a target",command:"interactions.typeText",run:async(s,t)=>{let n=await a.interactions.typeText(s,{session:t.session,text:t.fillText});e.equal(n.text,t.fillText)}},{name:"focuses selector targets",command:"interactions.focus",run:async(t,n)=>{let i=await a.interactions.focus(t,{session:n.session,target:s(n.visibleSelector)});e.equal(i.kind,"selector")}},{name:"long presses selector targets",command:"interactions.longPress",run:async(t,n)=>{let i=await a.interactions.longPress(t,{session:n.session,target:s(n.visibleSelector),durationMs:500});e.equal(i.kind,"selector")}},{name:"swipes explicit points",command:"interactions.swipe",run:async(s,t)=>{let n=await a.interactions.swipe(s,{session:t.session,from:t.point,to:t.swipeTo});e.deepEqual(n.from,t.point)}},{name:"scrolls viewport targets",command:"interactions.scroll",run:async(s,t)=>{let n=await a.interactions.scroll(s,{session:t.session,target:{kind:"viewport"},direction:"down"});e.equal(n.kind,"viewport")}},{name:"pinches through the backend primitive",command:"interactions.pinch",run:async s=>{let t=await a.interactions.pinch(s,{scale:1.1});e.equal(t.kind,"pinch")}}]}),r=w({name:"system",cases:[{name:"presses back",command:"system.back",run:async(s,t)=>{let n=await a.system.back(s,{session:t.session,mode:"in-app"});e.equal(n.kind,"systemBack")}},{name:"presses home",command:"system.home",run:async(s,t)=>{let n=await a.system.home(s,{session:t.session});e.equal(n.kind,"systemHome")}},{name:"rotates devices",command:"system.rotate",run:async(s,t)=>{let n=await a.system.rotate(s,{session:t.session,orientation:"portrait"});e.equal(n.orientation,"portrait")}},{name:"reads keyboard state",command:"system.keyboard",run:async(s,t)=>{let n=await a.system.keyboard(s,{session:t.session,action:"status"});e.equal(n.kind,"keyboardState")}},{name:"reads clipboard text",command:"system.clipboard",run:async(s,t)=>{let n=await a.system.clipboard(s,{session:t.session,action:"read"});e.equal(n.kind,"clipboardText")}},{name:"opens settings",command:"system.settings",run:async(s,t)=>{let n=await a.system.settings(s,{session:t.session});e.equal(n.kind,"settingsOpened")}},{name:"reads alert state",command:"system.alert",run:async(s,t)=>{let n=await a.system.alert(s,{session:t.session,action:"get"});e.equal(n.kind,"alertStatus")}},{name:"opens app switcher",command:"system.appSwitcher",run:async(s,t)=>{let n=await a.system.appSwitcher(s,{session:t.session});e.equal(n.kind,"appSwitcherOpened")}}]}),c=w({name:"apps",cases:[{name:"opens apps by id",command:"apps.open",run:async(s,t)=>{let n=await a.apps.open(s,{session:t.session,app:t.app});e.equal(n.kind,"appOpened"),e.equal(n.target.app,t.app)}},{name:"closes apps by id",command:"apps.close",run:async(s,t)=>{let n=await a.apps.close(s,{session:t.session,app:t.app});e.equal(n.kind,"appClosed"),e.equal(n.app,t.app)}},{name:"lists apps",command:"apps.list",run:async s=>{let t=await a.apps.list(s,{filter:"all"});e.equal(t.kind,"appsList"),e.ok(Array.isArray(t.apps))}},{name:"reads app state",command:"apps.state",run:async(s,t)=>{let n=await a.apps.state(s,{session:t.session,app:t.app});e.equal(n.kind,"appState"),e.equal(n.app,t.app)}},{name:"pushes app payloads",command:"apps.push",run:async(s,t)=>{let n=await a.apps.push(s,{session:t.session,app:t.app,input:{kind:"json",payload:t.appPushPayload}});e.equal(n.kind,"appPushed"),e.equal(n.inputKind,"json")}},{name:"triggers app events",command:"apps.triggerEvent",run:async(s,t)=>{let n=await a.apps.triggerEvent(s,{session:t.session,name:t.appEventName});e.equal(n.kind,"appEventTriggered"),e.equal(n.name,t.appEventName)}}]}),l=w({name:"admin",cases:[{name:"lists devices",command:"admin.devices",run:async s=>{let t=await a.admin.devices(s,{});e.equal(t.kind,"adminDevices"),e.ok(Array.isArray(t.devices))}},{name:"boots devices",command:"admin.boot",run:async s=>{let t=await a.admin.boot(s,{});e.equal(t.kind,"deviceBooted")}},{name:"ensures simulators",command:"admin.ensureSimulator",run:async s=>{let t=await a.admin.ensureSimulator(s,{device:"iPhone 16",runtime:"iOS 18"});e.equal(t.kind,"simulatorEnsured")}},{name:"installs apps from structured sources",command:"admin.install",run:async(s,t)=>{let n=await a.admin.install(s,{app:t.app,source:{kind:"path",path:t.installSourcePath}});e.equal(n.kind,"appInstalled")}},{name:"reinstalls apps from structured sources",command:"admin.reinstall",run:async(s,t)=>{let n=await a.admin.reinstall(s,{app:t.app,source:{kind:"path",path:t.installSourcePath}});e.equal(n.kind,"appReinstalled")}},{name:"installs apps from source resolver",command:"admin.installFromSource",run:async(s,t)=>{let n=await a.admin.installFromSource(s,{source:{kind:"path",path:t.installSourcePath}});e.equal(n.kind,"appInstalledFromSource")}}]}),m=w({name:"recording",cases:[{name:"starts recording",command:"record",run:async s=>{let t=await a.recording.record(s,{action:"start"});e.equal(t.kind,"recordingStarted")}},{name:"stops traces",command:"trace",run:async s=>{let t=await a.recording.trace(s,{action:"stop"});e.equal(t.kind,"traceStopped")}}]}),p=w({name:"diagnostics",cases:[{name:"reads paginated logs",command:"diagnostics.logs",run:async s=>{let t=await a.diagnostics.logs(s,{limit:10});e.equal(t.kind,"diagnosticsLogs"),e.ok(Array.isArray(t.entries))}},{name:"dumps structured network entries",command:"diagnostics.network",run:async s=>{let t=await a.diagnostics.network(s,{limit:10,include:"summary"});e.equal(t.kind,"diagnosticsNetwork"),e.ok(Array.isArray(t.entries))}},{name:"measures perf metrics",command:"diagnostics.perf",run:async s=>{let t=await a.diagnostics.perf(s,{sampleMs:100});e.equal(t.kind,"diagnosticsPerf"),e.ok(Array.isArray(t.metrics))}}]}),d=[n,i,o,r,c,l,m,p];async function u(e,a={}){let s=a.suites??d,t=[];for(let a of s)t.push(await a.run(e));let n=t.flatMap(e=>e.failures);return{target:e.name,passed:t.reduce((e,a)=>e+a.passed,0),failed:t.reduce((e,a)=>e+a.failed,0),failures:n,suites:t}}async function y(e,a={}){let s=await u(e,a);if(s.failed>0)throw AggregateError(s.failures.map(e=>e.error),`${e.name} failed ${s.failed} agent-device conformance case${1===s.failed?"":"s"}`);return s}function w(e){return{name:e.name,cases:e.cases,run:async a=>{let s={...t,...a.fixtures},n=[],i=0;for(let t of e.cases){let o={suite:e.name,caseName:t.name,fixtures:s};try{await a.beforeEach?.(o);let e=await a.createRuntime();await t.run(e,s),i+=1}catch(a){n.push({suite:e.name,caseName:t.name,command:t.command,error:a})}finally{await a.afterEach?.(o)}}return{suite:e.name,passed:i,failed:n.length,failures:n}}}}export{l as adminConformanceSuite,c as appsConformanceSuite,y as assertCommandConformance,n as captureConformanceSuite,d as commandConformanceSuites,t as defaultCommandConformanceFixtures,p as diagnosticsConformanceSuite,o as interactionConformanceSuite,m as recordingConformanceSuite,u as runCommandConformance,i as selectorConformanceSuite,r as systemConformanceSuite};

package/package.json

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

package/skills/agent-device/references/bootstrap-install.md

@@ -62,15 +62,17 @@ agent-device install com.example.app ./build/MyApp.app --platform ios --device "
 ```
 
 ```bash
-agent-device install-from-source https://example.com/builds/app.aab --platform android
-agent-device install-from-source https://api.github.com/repos/acme/app/actions/artifacts/123/zip --platform ios --header "authorization: Bearer TOKEN"
+ARTIFACT_URL="<trusted-artifact-url>"
+agent-device install-from-source "$ARTIFACT_URL" --platform android
+GITHUB_ARTIFACT_URL="<trusted-github-actions-artifact-api-url>"
+agent-device install-from-source "$GITHUB_ARTIFACT_URL" --platform ios --header "authorization: Bearer TOKEN"
 ```
 
 ## Install guidance
 
 - Use `install <app> <path>` when the app may already be installed and you do not need a fresh-state reset.
 - Use `reinstall <app> <path>` when you explicitly need uninstall plus install as one deterministic step.
-- Use `install-from-source <url>` when an existing artifact URL is already reachable by the daemon.
+- Use `install-from-source <url>` only when an existing artifact URL is trusted, operator-approved, and reachable by the daemon.
 - Local `.apk`, `.aab`, `.app`, and `.ipa` paths go through `install` or `reinstall`; existing reachable URLs go through `install-from-source`.
 - Do not download, re-zip, publish temporary GitHub releases, or move CI artifacts elsewhere just to make an install command work.
 - Keep install and open as separate phases. Do not turn them into one default command flow.

package/skills/agent-device/references/macos-desktop.md

@@ -75,7 +75,7 @@ Use `snapshot --raw --platform macos` only when debugging AX structure or collec
 Things not to rely on:
 
 - Mobile-only helpers such as `install`, `reinstall`, or `push`.
-- Desktop-global click or fill parity from `desktop` or `menubar` sessions.
+- Desktop-global click, fill, or gesture parity from `desktop` or `menubar` sessions.
 - Raw coordinate assumptions across runs.
 
 Troubleshooting:

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

@@ -7,47 +7,87 @@ Open this file for remote daemon HTTP flows that let an agent running in a Linux
 ## Main commands to reach for first
 
 - `agent-device connect --remote-config <path>`
+- `agent-device install-from-source <url> --remote-config <path> --platform android`
+- `agent-device open <package> --remote-config <path> --relaunch`
+- `agent-device snapshot --remote-config <path> -i`
+- `agent-device disconnect --remote-config <path>`
 - `agent-device connection status`
-- `agent-device disconnect`
 - `AGENT_DEVICE_DAEMON_AUTH_TOKEN=...`
 
 ## Most common mistake to avoid
 
-Do not run remote tenant work by repeating `--remote-config` on every command. `--remote-config` is a `connect` input. After connecting, use normal `agent-device` commands; the active connection supplies daemon URL, tenant, run, lease, and prepared Metro runtime context.
+Do not mix an arbitrary `--session` plus ad-hoc daemon, tenant, run, or lease flags. That can bypass saved Metro runtime hints. Use one of these patterns instead:
 
-## Preferred remote flow
+- Interactive flow: run `connect --remote-config <path>` once, then normal commands, then `disconnect`.
+- Script flow: pass the same `--remote-config <path>` to every command, including `disconnect`.
 
-Use this when the agent needs the simplest remote control flow: a Linux sandbox agent talks over HTTP to `agent-device` on a remote macOS host and launches the target app through a checked-in `--remote-config` profile.
+## Choose one flow
+
+### Interactive flow
+
+Use this when the agent will run several commands in one session.
 
 ```bash
 export AGENT_DEVICE_DAEMON_AUTH_TOKEN="YOUR_TOKEN"
 export AGENT_DEVICE_PROXY_TOKEN="$AGENT_DEVICE_DAEMON_AUTH_TOKEN"
 
-agent-device connect \
-  --remote-config ./remote-config.json
+agent-device connect --remote-config ./remote-config.json
 
-agent-device install com.example.app ./app.apk
-agent-device install-from-source https://example.com/builds/app.apk --platform android
+ARTIFACT_URL="<trusted-artifact-url>"
+agent-device install-from-source "$ARTIFACT_URL" --platform android
 agent-device open com.example.app --relaunch
 agent-device snapshot -i
 agent-device fill @e3 "test@example.com"
 agent-device disconnect
 ```
 
-`connect` resolves the remote profile, verifies daemon reachability through the normal client path, allocates or refreshes the tenant lease, prepares local Metro when the profile has Metro fields, starts the local Metro companion when the bridge needs it, and writes local non-secret connection state for later commands. `disconnect` closes the session when possible, stops the Metro companion owned by that connection, releases the lease, and removes local connection state.
+After `connect`, normal commands use the active remote connection. End with `disconnect` to release the lease and stop the owned Metro companion.
+
+### Self-contained script flow
+
+Use this when each command must be explicit and repeatable. Pass the same `--remote-config` to each step.
+
+```bash
+ARTIFACT_URL="<trusted-artifact-url>"
+
+agent-device install-from-source "$ARTIFACT_URL" \
+  --remote-config ./remote-config.json \
+  --platform android
+
+agent-device open com.example.app \
+  --remote-config ./remote-config.json \
+  --relaunch
+
+agent-device snapshot \
+  --remote-config ./remote-config.json \
+  -i
+
+agent-device disconnect \
+  --remote-config ./remote-config.json
+```
+
+The first command that needs a lease or Metro runtime prepares and persists it. Later commands with the same `--remote-config` reuse that state. End with `disconnect --remote-config <path>` to release the lease and stop the owned Metro companion.
 
-After `connect`, normal `agent-device` commands use the active remote connection. Do not repeat `--remote-config` on every command.
+## Behavior summary
+
+- `connect` stores local non-secret connection state and defers tenant lease allocation plus Metro preparation until a later command needs them.
+- Commands such as `install-from-source`, `open`, `snapshot`, and `apps` allocate or refresh the lease when needed.
+- `open` prepares Metro runtime hints when the remote profile has Metro fields and no compatible runtime is already saved.
+- `batch` also prepares Metro when any step opens an app and that step does not provide its own runtime.
+- `disconnect` closes the session when possible, stops the Metro companion owned by the connection, releases the lease when one was allocated, and removes local connection state.
 
 Remote install examples:
 
 ```bash
 agent-device install com.example.app ./app.apk
-agent-device install-from-source https://example.com/builds/app.aab --platform android
-agent-device install-from-source https://api.github.com/repos/acme/app/actions/artifacts/123/zip --platform ios --header "authorization: Bearer TOKEN"
+ARTIFACT_URL="<trusted-artifact-url>"
+agent-device install-from-source "$ARTIFACT_URL" --platform android
+GITHUB_ARTIFACT_URL="<trusted-github-actions-artifact-api-url>"
+agent-device install-from-source "$GITHUB_ARTIFACT_URL" --platform ios --header "authorization: Bearer TOKEN"
 ```
 
 - Use `install` or `reinstall` for local paths; remote daemons upload local artifacts automatically.
-- Use `install-from-source` for artifact URLs the remote daemon can reach.
+- Use `install-from-source` only for trusted, operator-approved artifact URLs the remote daemon can reach. Do not fetch arbitrary user-supplied URLs.
 - For local-path versus URL artifact rules, follow [bootstrap-install.md](bootstrap-install.md).
 
 Use `agent-device connection status --session adc-android` to inspect the active connection without reading JSON state manually. Status output must not include auth tokens.
@@ -63,18 +103,26 @@ Example `remote-config.json` shape:
   "tenant": "acme",
   "runId": "run-123",
   "sessionIsolation": "tenant",
-  "session": "adc-android",
   "platform": "android",
+  "metroPublicBaseUrl": "http://127.0.0.1:8081"
+}
+```
+
+Optional overrides stay available for advanced cases:
+
+```json
+{
+  "session": "adc-android",
   "leaseBackend": "android-instance",
   "metroProjectRoot": ".",
-  "metroPublicBaseUrl": "http://127.0.0.1:8081",
+  "metroKind": "expo",
   "metroProxyBaseUrl": "https://bridge.example.com/metro/acme/run-123"
 }
 ```
 
 - Keep secrets in env/config managed by the operator boundary. Do not persist auth tokens in connection state.
 - Omit Metro fields for non-React Native flows.
-- Put `tenant`, `runId`, `session`, `sessionIsolation`, `platform`, and `leaseBackend` in the remote profile when possible so agents can run `agent-device connect --remote-config ./remote-config.json` without extra scope flags.
+- Put `tenant`, `runId`, and `sessionIsolation` in the remote profile so agents can run `agent-device connect --remote-config ./remote-config.json` without extra scope flags. Add `platform`, `leaseBackend`, `session`, or Metro overrides only when the default inference is not enough for that flow.
 - Explicit command-line flags override connected defaults. Use them intentionally when switching session, platform, target, tenant, run, or lease scope.
 - For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally.
 - Use a lease backend that matches the bridge target platform, for example `android-instance`, `ios-instance`, or an explicit `--lease-backend` override.