agent-device 0.12.4 → 0.12.6

package/dist/src/testing/conformance.js

@@ -0,0 +1 @@
+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/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -183,16 +183,25 @@ extension RunnerTests {
       if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
         return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
       }
+      if let requestedQuality = command.quality, (requestedQuality < minRecordingQuality || requestedQuality > maxRecordingQuality) {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart quality must be between \(minRecordingQuality) and \(maxRecordingQuality)"))
+      }
       do {
         let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
         let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
+        let qualityLabel = command.quality.map(String.init) ?? "native"
         NSLog(
-          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@ quality=%@",
           requestedOutPath,
           resolvedOutPath,
-          fpsLabel
+          fpsLabel,
+          qualityLabel
+        )
+        let recorder = ScreenRecorder(
+          outputPath: resolvedOutPath,
+          fps: command.fps.map { Int32($0) },
+          quality: command.quality
         )
-        let recorder = ScreenRecorder(outputPath: resolvedOutPath, fps: command.fps.map { Int32($0) })
         try recorder.start { [weak self] in
           return self?.captureRunnerFrame()
         }

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -52,6 +52,7 @@ struct Command: Codable {
   let scale: Double?
   let outPath: String?
   let fps: Int?
+  let quality: Int?
   let interactiveOnly: Bool?
   let compact: Bool?
   let depth: Int?

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift

@@ -7,6 +7,7 @@ extension RunnerTests {
   final class ScreenRecorder {
     private let outputPath: String
     private let fps: Int32?
+    private let quality: Int?
     private var effectiveFps: Int32 {
       max(1, fps ?? RunnerTests.defaultRecordingFps)
     }
@@ -25,9 +26,10 @@ extension RunnerTests {
     private var startedSession = false
     private var startError: Error?
 
-    init(outputPath: String, fps: Int32?) {
+    init(outputPath: String, fps: Int32?, quality: Int?) {
       self.outputPath = outputPath
       self.fps = fps
+      self.quality = quality
     }
 
     func start(captureFrame: @escaping () -> RunnerImage?) throws {
@@ -48,7 +50,7 @@ extension RunnerTests {
       while Date() < bootstrapDeadline {
         if let image = captureFrame(), let cgImage = runnerCGImage(from: image) {
           bootstrapImage = image
-          dimensions = CGSize(width: cgImage.width, height: cgImage.height)
+          dimensions = scaledDimensions(width: cgImage.width, height: cgImage.height)
           break
         }
         Thread.sleep(forTimeInterval: 0.05)
@@ -240,11 +242,13 @@ extension RunnerTests {
 
       CVPixelBufferLockBaseAddress(pixelBuffer, [])
       defer { CVPixelBufferUnlockBaseAddress(pixelBuffer, []) }
+      let width = CVPixelBufferGetWidth(pixelBuffer)
+      let height = CVPixelBufferGetHeight(pixelBuffer)
       guard
         let context = CGContext(
           data: CVPixelBufferGetBaseAddress(pixelBuffer),
-          width: image.width,
-          height: image.height,
+          width: width,
+          height: height,
           bitsPerComponent: 8,
           bytesPerRow: CVPixelBufferGetBytesPerRow(pixelBuffer),
           space: CGColorSpaceCreateDeviceRGB(),
@@ -253,8 +257,23 @@ extension RunnerTests {
       else {
         return nil
       }
-      context.draw(image, in: CGRect(x: 0, y: 0, width: image.width, height: image.height))
+      context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
       return pixelBuffer
     }
+
+    private func scaledDimensions(width: Int, height: Int) -> CGSize {
+      guard let quality, quality < 10 else {
+        return CGSize(width: width, height: height)
+      }
+      let scale = Double(quality) / 10.0
+      return CGSize(
+        width: scaledEvenDimension(width, scale: scale),
+        height: scaledEvenDimension(height, scale: scale)
+      )
+    }
+
+    private func scaledEvenDimension(_ value: Int, scale: Double) -> Int {
+      max(2, Int((Double(value) * scale / 2.0).rounded()) * 2)
+    }
   }
 }

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -48,6 +48,8 @@ final class RunnerTests: XCTestCase {
   let tvRemoteDoublePressDelayDefault: TimeInterval = 0.0
   let minRecordingFps = 1
   let maxRecordingFps = 120
+  let minRecordingQuality = 5
+  let maxRecordingQuality = 10
   var needsPostSnapshotInteractionDelay = false
   var needsFirstInteractionDelay = false
   var activeRecording: ScreenRecorder?

package/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift

@@ -0,0 +1,182 @@
+import AVFoundation
+import Foundation
+
+enum ResizeError: Error, CustomStringConvertible {
+  case invalidArgs(String)
+  case missingVideoTrack
+  case exportFailed(String)
+
+  var description: String {
+    switch self {
+    case .invalidArgs(let message):
+      return message
+    case .missingVideoTrack:
+      return "Input video does not contain a video track."
+    case .exportFailed(let message):
+      return message
+    }
+  }
+}
+
+do {
+  try run()
+} catch {
+  fputs("recording-resize: \(error)\n", stderr)
+  exit(1)
+}
+
+func run() throws {
+  let arguments = Array(CommandLine.arguments.dropFirst())
+  let parsedArgs = try parseArguments(arguments)
+  let inputURL = URL(fileURLWithPath: parsedArgs.inputPath)
+  let outputURL = URL(fileURLWithPath: parsedArgs.outputPath)
+
+  if FileManager.default.fileExists(atPath: outputURL.path) {
+    try FileManager.default.removeItem(at: outputURL)
+  }
+
+  let asset = AVURLAsset(url: inputURL)
+  guard let sourceVideoTrack = asset.tracks(withMediaType: .video).first else {
+    throw ResizeError.missingVideoTrack
+  }
+
+  let renderSize = scaledRenderSize(for: sourceVideoTrack, quality: parsedArgs.quality)
+  let composition = AVMutableComposition()
+  let fullRange = CMTimeRange(start: .zero, duration: asset.duration)
+
+  guard let compositionVideoTrack = composition.addMutableTrack(
+    withMediaType: .video,
+    preferredTrackID: kCMPersistentTrackID_Invalid
+  ) else {
+    throw ResizeError.exportFailed("Failed to create composition video track.")
+  }
+  try compositionVideoTrack.insertTimeRange(fullRange, of: sourceVideoTrack, at: .zero)
+
+  if let sourceAudioTrack = asset.tracks(withMediaType: .audio).first,
+     let compositionAudioTrack = composition.addMutableTrack(
+       withMediaType: .audio,
+       preferredTrackID: kCMPersistentTrackID_Invalid
+     ) {
+    try? compositionAudioTrack.insertTimeRange(fullRange, of: sourceAudioTrack, at: .zero)
+  }
+
+  let scale = CGFloat(parsedArgs.quality) / 10.0
+  let videoComposition = AVMutableVideoComposition()
+  videoComposition.renderSize = renderSize
+  videoComposition.frameDuration = resolvedFrameDuration(for: sourceVideoTrack)
+
+  let instruction = AVMutableVideoCompositionInstruction()
+  instruction.timeRange = fullRange
+  let layerInstruction = AVMutableVideoCompositionLayerInstruction(assetTrack: compositionVideoTrack)
+  // Scale the full preferred transform (including translation) to match the smaller render canvas.
+  let scaledTransform = scaledPreferredTransform(sourceVideoTrack.preferredTransform, scale: scale)
+  layerInstruction.setTransform(scaledTransform, at: .zero)
+  instruction.layerInstructions = [layerInstruction]
+  videoComposition.instructions = [instruction]
+
+  guard let exporter = AVAssetExportSession(asset: composition, presetName: AVAssetExportPresetHighestQuality) else {
+    throw ResizeError.exportFailed("Failed to create export session.")
+  }
+
+  exporter.outputURL = outputURL
+  exporter.outputFileType = .mp4
+  exporter.videoComposition = videoComposition
+  exporter.shouldOptimizeForNetworkUse = true
+
+  let semaphore = DispatchSemaphore(value: 0)
+  exporter.exportAsynchronously {
+    semaphore.signal()
+  }
+  if semaphore.wait(timeout: .now() + 120) == .timedOut {
+    exporter.cancelExport()
+    throw ResizeError.exportFailed("Resize export timed out.")
+  }
+
+  if exporter.status != .completed {
+    throw ResizeError.exportFailed(exporter.error?.localizedDescription ?? "Resize export failed.")
+  }
+}
+
+func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, quality: Int) {
+  var inputPath: String?
+  var outputPath: String?
+  var quality: Int?
+  var index = 0
+
+  while index < arguments.count {
+    let argument = arguments[index]
+    let nextIndex = index + 1
+    switch argument {
+    case "--input":
+      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--input requires a value") }
+      inputPath = arguments[nextIndex]
+      index += 2
+    case "--output":
+      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--output requires a value") }
+      outputPath = arguments[nextIndex]
+      index += 2
+    case "--quality":
+      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--quality requires a value") }
+      guard let parsed = Int(arguments[nextIndex]), parsed >= 5, parsed <= 10 else {
+        throw ResizeError.invalidArgs("--quality must be an integer between 5 and 10")
+      }
+      quality = parsed
+      index += 2
+    default:
+      throw ResizeError.invalidArgs("Unknown argument: \(argument)")
+    }
+  }
+
+  guard let inputPath, let outputPath, let quality else {
+    throw ResizeError.invalidArgs(
+      "Usage: recording-resize.swift --input <video> --output <video> --quality <5-10>"
+    )
+  }
+  return (inputPath, outputPath, quality)
+}
+
+func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
+  let transformed = track.naturalSize.applying(track.preferredTransform)
+  return CGSize(width: abs(transformed.width), height: abs(transformed.height))
+}
+
+func scaledRenderSize(for track: AVAssetTrack, quality: Int) -> CGSize {
+  let renderSize = resolvedRenderSize(for: track)
+  guard quality < 10 else { return renderSize }
+  let scale = CGFloat(quality) / 10.0
+  return CGSize(
+    width: scaledDimension(renderSize.width, scale: scale),
+    height: scaledDimension(renderSize.height, scale: scale)
+  )
+}
+
+func scaledDimension(_ value: CGFloat, scale: CGFloat) -> CGFloat {
+  let evenValue = Int((Double(value * scale) / 2.0).rounded()) * 2
+  return CGFloat(max(2, evenValue))
+}
+
+func resolvedFrameDuration(for track: AVAssetTrack) -> CMTime {
+  let minFrameDuration = track.minFrameDuration
+  if minFrameDuration.isValid && !minFrameDuration.isIndefinite && minFrameDuration.seconds > 0 {
+    return minFrameDuration
+  }
+
+  let nominalFrameRate = track.nominalFrameRate
+  if nominalFrameRate > 0 {
+    let timescale = Int32(max(1, round(nominalFrameRate)))
+    return CMTime(value: 1, timescale: timescale)
+  }
+
+  return CMTime(value: 1, timescale: 60)
+}
+
+func scaledPreferredTransform(_ transform: CGAffineTransform, scale: CGFloat) -> CGAffineTransform {
+  CGAffineTransform(
+    a: transform.a * scale,
+    b: transform.b * scale,
+    c: transform.c * scale,
+    d: transform.d * scale,
+    tx: transform.tx * scale,
+    ty: transform.ty * scale
+  )
+}

package/ios-runner/RUNNER_PROTOCOL.md

@@ -33,7 +33,7 @@ Examples:
 ```
 
 ```json
-{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30 }
+{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30, "quality": 7 }
 ```
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
@@ -12,6 +12,22 @@
       "import": "./dist/src/index.js",
       "types": "./dist/src/index.d.ts"
     },
+    "./commands": {
+      "import": "./dist/src/commands/index.js",
+      "types": "./dist/src/commands/index.d.ts"
+    },
+    "./backend": {
+      "import": "./dist/src/backend.js",
+      "types": "./dist/src/backend.d.ts"
+    },
+    "./io": {
+      "import": "./dist/src/io.js",
+      "types": "./dist/src/io.d.ts"
+    },
+    "./testing/conformance": {
+      "import": "./dist/src/testing/conformance.js",
+      "types": "./dist/src/testing/conformance.d.ts"
+    },
     "./artifacts": {
       "import": "./dist/src/artifacts.js",
       "types": "./dist/src/artifacts.d.ts"

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

@@ -17,6 +17,7 @@ Use this exact order when you are not sure about the installed app identifier. O
 ## Install path
 
 - `install` or `reinstall`
+- `install-from-source` when the artifact already exists at a URL the daemon can reach
 
 ## Most common mistake to avoid
 
@@ -60,14 +61,26 @@ agent-device install com.example.app ./build/app.apk --platform android --serial
 agent-device install com.example.app ./build/MyApp.app --platform ios --device "iPhone 17 Pro"
 ```
 
+```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"
+```
+
 ## 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.
+- 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.
 - Supported binary formats:
   - Android: `.apk` and `.aab`
   - iOS: `.app` and `.ipa`
+- Android URL sources can be direct `.apk` or `.aab` files.
+- Trusted artifact service URLs, currently GitHub Actions and EAS, may point at archive-backed downloads that contain one installable artifact. This includes GitHub Actions artifact ZIPs whose URL path does not end in `.zip` and ZIPs containing one nested `.apk`, `.aab`, `.ipa`, or iOS `.app` tar archive.
+- If a trusted artifact archive contains multiple installables, stop and ask for the intended artifact instead of guessing.
+- `.aab` still requires `bundletool` in `PATH`, or `AGENT_DEVICE_BUNDLETOOL_JAR=<absolute-path-to-bundletool-all.jar>` with `java` in `PATH`, when the daemon installs the materialized artifact.
 - For iOS `.ipa` files, `<app>` is used as the bundle id or bundle name hint when the archive contains multiple app bundles.
 - After install or reinstall, later use `open <app>` with the exact discovered or known package/bundle identifier, not the artifact path.
 

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
 
@@ -27,13 +27,28 @@ 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
 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.
+`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.
+
+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"
+```
+
+- 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.
+- 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.
 
@@ -48,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.

package/skills/agent-device/references/verification.md

@@ -82,6 +82,7 @@ agent-device record stop
 - On iOS, recording is a wrapper around `simctl` for simulators and the corresponding device capture path for physical devices.
 - On Android, recording is a wrapper around `adb`.
 - Recording writes a video artifact and a gesture-telemetry sidecar JSON.
+- Use `record start <path> --quality 5` when a smaller video is easier to inspect or share. The scale is 5-10, where 10 is native resolution; omit it to preserve native/current resolution.
 - On macOS hosts, touch overlay burn-in is available for supported recordings.
 - On non-macOS hosts, recording still succeeds but the video stays raw and `record stop` can return an `overlayWarning`.
 - If the agent already knows the interaction sequence and wants a more lifelike, uninterrupted recording, drive the flow with `batch` while recording instead of replanning between each step.