agent-device 0.12.5 → 0.12.6

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.6",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",

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

@@ -13,7 +13,7 @@ Open this file for remote daemon HTTP flows that let an agent running in a Linux
 
 ## 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 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, and session context, then resolves lease and Metro details only when a later command actually needs them.
 
 ## Preferred remote flow
 
@@ -34,7 +34,7 @@ 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.
+`connect` resolves the remote profile, generates a local session name when the profile omits one, stores local non-secret connection state, and defers tenant lease allocation plus Metro preparation until a later command needs them. When a command such as `open`, `install`, `apps`, or `snapshot` needs a lease, the client allocates or refreshes it from the connected scope. When a command needs Metro runtime hints, the client prepares Metro locally at that point and starts the local Metro companion when the bridge needs it, including `batch` runs whose steps open an app. `disconnect` closes the session when possible, stops the Metro companion owned by that connection, releases the lease when one was allocated, and removes local connection state.
 
 After `connect`, normal `agent-device` commands use the active remote connection. Do not repeat `--remote-config` on every command.
 
@@ -63,18 +63,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.