agent-device 0.12.3 → 0.12.5

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.3",
+  "version": "0.12.5",
   "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/remote-tenancy.md

@@ -27,6 +27,7 @@ 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"
@@ -35,6 +36,20 @@ 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 `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.
 
 ## Remote config shape

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.