agent-device 0.21.23 → 0.21.25

package/README.md

@@ -31,7 +31,7 @@ agent-device doctor
 agent-device help workflow
 ```
 
-Run `doctor` yourself before handing the CLI to an agent; `help workflow` links to the guides for debugging, replay, and profiling, and the installed help always matches the installed version.
+Run `doctor` yourself before you hand the CLI to an agent. `help workflow` links to the guides for debugging, replay, and profiling.
 
 ### Drive an app from the CLI
 
@@ -61,7 +61,7 @@ agent-device screenshot ./contact-form.png
 agent-device close
 ```
 
-Refs are only valid from the latest output: after a `--settle` command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.
+Refs are valid only in the latest output: after a `--settle` command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.
 
 ![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](./website/docs/public/agent-device-contacts.gif)
 
@@ -126,7 +126,7 @@ With the CLI installed, prompts like these work end to end:
 ## Next steps
 
 - [AI Agent Setup](https://oss.callstack.com/agent-device/docs/agent-setup): skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others.
-- [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start): a guided run on the bundled Expo test app with screenshots, replay, and performance data.
+- [Quick Start](https://oss.callstack.com/agent-device/docs/quick-start): open an app, read its UI, and interact with it from the command line.
 - [Replay & E2E](https://oss.callstack.com/agent-device/docs/replay-e2e) and [Debugging & Profiling](https://oss.callstack.com/agent-device/docs/debugging-profiling): repeatable tests and bug hunting.
 
 ## Where to run agent-device
@@ -137,15 +137,15 @@ The same session and evidence model works at every step: the agent explores the
 | --- | --- | --- |
 | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. |
 | CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). |
-| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://oss.callstack.com/agent-device/docs/remote-proxy), connect a [device cloud](https://oss.callstack.com/agent-device/docs/device-clouds) (BrowserStack, AWS Device Farm, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
+| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://oss.callstack.com/agent-device/docs/remote-proxy), connect a [device cloud](https://oss.callstack.com/agent-device/docs/device-clouds) (BrowserStack, AWS Device Farm, TestMu AI, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
 
 ## How it works
 
 `agent-device` keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android; HDC and ArkUI `uitest` on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS; and AT-SPI on Linux.
 
-Support depth varies by target. Newer backends such as HarmonyOS and Vega OS cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports.
+Support depth varies by target. Some backends, such as HarmonyOS and Vega OS, cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports.
 
-Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Inspect ownership without a daemon via `agent-device device status`, and settle provably dead owners with `agent-device device release --stale`. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds).
+Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Run `agent-device device status` to inspect ownership without a daemon, and `agent-device device release --stale` to release claims whose owner is provably no longer running. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, TestMu AI, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds).
 
 `agent-device` uses the inspect-act-verify process from Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) for mobile, TV, and desktop apps. Basic `--platform web` support runs `agent-browser` in the same session and replay system.
 

package/android/ime-helper/dist/agent-device-android-ime-helper-0.21.25.apk.sha256

@@ -0,0 +1 @@
+2b1c6a028b28e426c4bed80449b6dd1eff69985f1741a58d033e30f8b9fa5bf1  agent-device-android-ime-helper-0.21.25.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.21.23.manifest.json → agent-device-android-ime-helper-0.21.25.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.21.23",
-  "assetName": "agent-device-android-ime-helper-0.21.23.apk",
-  "sha256": "0268a637de0047d0c8d2e6af9dc0603f96a308dda4369b3f0c2e52a76e67c517",
+  "version": "0.21.25",
+  "assetName": "agent-device-android-ime-helper-0.21.25.apk",
+  "sha256": "2b1c6a028b28e426c4bed80449b6dd1eff69985f1741a58d033e30f8b9fa5bf1",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 21023,
+  "versionCode": 21025,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.21.25.apk.sha256

@@ -0,0 +1 @@
+79175080eb71f444224c844a599e75e839d6456790eb96d175fc887f85237a12  agent-device-android-snapshot-helper-0.21.25.apk

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.21.25.manifest.json

@@ -0,0 +1,16 @@
+{
+  "name": "android-snapshot-helper",
+  "version": "0.21.25",
+  "releaseTag": "v0.21.25",
+  "assetName": "agent-device-android-snapshot-helper-0.21.25.apk",
+  "apkUrl": "https://github.com/callstack/agent-device/releases/download/v0.21.25/agent-device-android-snapshot-helper-0.21.25.apk",
+  "sha256": "79175080eb71f444224c844a599e75e839d6456790eb96d175fc887f85237a12",
+  "checksumName": "agent-device-android-snapshot-helper-0.21.25.apk.sha256",
+  "packageName": "com.callstack.agentdevice.snapshothelper",
+  "versionCode": 21025,
+  "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
+  "minSdk": 23,
+  "targetSdk": 36,
+  "outputFormat": "uiautomator-xml",
+  "statusProtocol": "android-snapshot-helper-v1"
+}

package/apple/macos-helper/Sources/AgentDeviceMacOSHelper/SnapshotTraversal.swift

@@ -795,12 +795,18 @@ func rectAttribute(_ element: AXUIElement) -> RectResponse? {
     return nil
   }
 
-  return RectResponse(
-    x: Double(position.x),
-    y: Double(position.y),
-    width: Double(size.width),
-    height: Double(size.height)
-  )
+  return finiteRectResponse(position: position, size: size)
+}
+
+/// JSONEncoder throws on inf/NaN, which fails the whole snapshot. SwiftUI reports lazy
+/// containers scrolled out of view as an AXOpaqueProviderGroup at (inf, inf, 0, 0).
+func finiteRectResponse(position: CGPoint, size: CGSize) -> RectResponse? {
+  let x = Double(position.x)
+  let y = Double(position.y)
+  let width = Double(size.width)
+  let height = Double(size.height)
+  guard x.isFinite, y.isFinite, width.isFinite, height.isFinite else { return nil }
+  return RectResponse(x: x, y: y, width: width, height: height)
 }
 
 private func accessibilityAxValue(_ value: CFTypeRef?) -> AXValue? {

package/apple/macos-helper/Tests/AgentDeviceMacOSHelperTests/RectResponseTests.swift

@@ -0,0 +1,21 @@
+import XCTest
+
+@testable import AgentDeviceMacOSHelper
+
+final class RectResponseTests: XCTestCase {
+  func testFiniteRectKeepsItsValues() throws {
+    let rect = try XCTUnwrap(
+      finiteRectResponse(position: CGPoint(x: 1, y: 2), size: CGSize(width: 3, height: 4)))
+    XCTAssertEqual([rect.x, rect.y, rect.width, rect.height], [1, 2, 3, 4])
+  }
+
+  func testNonFiniteComponentYieldsNoRect() {
+    let nonFinite: [CGFloat] = [.infinity, -.infinity, .nan]
+    for value in nonFinite {
+      XCTAssertNil(finiteRectResponse(position: CGPoint(x: value, y: 0), size: .zero))
+      XCTAssertNil(finiteRectResponse(position: CGPoint(x: 0, y: value), size: .zero))
+      XCTAssertNil(finiteRectResponse(position: .zero, size: CGSize(width: value, height: 0)))
+      XCTAssertNil(finiteRectResponse(position: .zero, size: CGSize(width: 0, height: value)))
+    }
+  }
+}

package/apple/snapshot-bridge/README.md

@@ -50,13 +50,15 @@ disabled after fallback until that app relaunches.
 
 ## Remote content
 
-The reader snapshots one process. A WebKit page — Safari's or a `WKWebView`'s —
-lives in a WebContent process and appears in that tree as an `AXRemoteElement`
-leaf under the web view. The guest returns the leaf as delivered; the host
-refuses a tree in which such a leaf sits under a web view and reaches the
-viewport, or reports no frame (`remote-content-boundary`), and routes that app
-generation to XCTest, which resolves remote elements (#2484). A zero-area or
-off-screen leaf is published: it hosts nothing the capture can miss.
+The reader snapshots one process. Two hosts put another process's UI into that
+tree as an `AXRemoteElement` leaf: a WebKit page — Safari's or a `WKWebView`'s —
+lives in a WebContent process under the web view, and a scene-hosted remote view
+controller, such as a share extension presented over the app, lives in the
+extension's process under a `_UISceneHostingView`. The guest returns the leaf as
+delivered; the host refuses a tree in which such a leaf sits under either host
+and reaches the viewport, or reports no frame (`remote-content-boundary`), and
+routes that app generation to XCTest, which resolves remote elements (#2484). A
+zero-area or off-screen leaf is published: it hosts nothing the capture can miss.
 
 ## Bounded depth recovery
 

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m

@@ -71,6 +71,7 @@ int main(int argc, const char *argv[]) {
 // took focus from an input that has stopped answering the accessibility query that found it.
 @property(nonatomic, strong) UILabel *textEntryFocusWitness;
 @property(nonatomic, assign) NSUInteger textEntryWriteBacks;
+@property(nonatomic, assign) NSUInteger textEntryTotalEdits;
 @property(nonatomic, copy, nullable) NSString *textEntryRenderedValue;
 @property(nonatomic, assign) NSTimeInterval textEntryLastEditTime;
 @property(nonatomic, assign) NSTimeInterval textEntryBurstStartTime;
@@ -97,6 +98,122 @@ int main(int argc, const char *argv[]) {
   return [NSString stringWithFormat:@"%lu of 6 digits", (unsigned long)self.text.length];
 }
 @end
+
+// A field that reformats its own text on every edit into `## ### ## ##` digit groups, the way a
+// digit-grouping formatter in a Flutter or React Native input does. The accessibility value is
+// what the user sees — the formatted string — so it never equals the digits a `fill` sent (#2634).
+// The field owns the delegate it installs, keeping the formatter out of the view controller's
+// own delegate callbacks.
+@interface AgentDeviceDigitGroupingTextField : UITextField <UITextFieldDelegate>
+@end
+
+@interface AgentDeviceCurrencyTextField : UITextField <UITextFieldDelegate>
+@property(nonatomic, strong) UILabel *entryStatus;
+@property(nonatomic, assign) NSUInteger insertedDigits;
+@end
+
+@interface AgentDeviceSubmitClearingTextField : UITextField <UITextFieldDelegate>
+@property(nonatomic, strong) UILabel *entryStatus;
+@property(nonatomic, assign) NSUInteger submits;
+@end
+
+static NSString *AgentDeviceFormatGroupedDigits(NSString *raw) {
+  NSMutableString *digits = [NSMutableString string];
+  NSCharacterSet *nonDigits = [[NSCharacterSet decimalDigitCharacterSet] invertedSet];
+  for (NSString *chunk in [raw componentsSeparatedByCharactersInSet:nonDigits]) {
+    [digits appendString:chunk];
+  }
+  NSMutableArray<NSNumber *> *groupWidths = [NSMutableArray arrayWithArray:@[@2, @3, @2, @2]];
+  NSMutableString *formatted = [NSMutableString string];
+  NSUInteger cursor = 0;
+  for (NSNumber *width in groupWidths) {
+    if (cursor >= digits.length) {
+      break;
+    }
+    if (formatted.length > 0) {
+      [formatted appendString:@" "];
+    }
+    NSUInteger end = MIN(cursor + width.unsignedIntegerValue, digits.length);
+    [formatted appendString:[digits substringWithRange:NSMakeRange(cursor, end - cursor)]];
+    cursor = end;
+  }
+  // Digits past the last group keep grouping by threes rather than vanishing from the field.
+  while (cursor < digits.length) {
+    NSUInteger end = MIN(cursor + 3, digits.length);
+    [formatted appendString:[NSString stringWithFormat:@" %@", [digits substringWithRange:NSMakeRange(cursor, end - cursor)]]];
+    cursor = end;
+  }
+  return formatted;
+}
+
+static NSUInteger AgentDeviceDigitCount(NSString *text, NSUInteger limit) {
+  NSUInteger count = 0;
+  for (NSUInteger index = 0; index < limit && index < text.length; index++) {
+    if ([NSCharacterSet.decimalDigitCharacterSet characterIsMember:[text characterAtIndex:index]]) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+@implementation AgentDeviceDigitGroupingTextField
+- (BOOL)textField:(UITextField *)textField
+      shouldChangeCharactersInRange:(NSRange)range
+               replacementString:(NSString *)string {
+  NSString *combined = [textField.text stringByReplacingCharactersInRange:range withString:string];
+  NSString *formatted = AgentDeviceFormatGroupedDigits(combined);
+  textField.text = formatted;
+  // Assigning `text` drops the caret at the end, which a real grouping formatter does not do:
+  // a mid-string edit must keep editing where the user put the caret. The digits before the
+  // caret survive the reformat unchanged, so the caret belongs before the digit that follows
+  // them — past the separators the grouping inserted behind them — and at the end when it
+  // followed all of them. Typed digits count as before the caret; a delete does not move it.
+  NSUInteger digitsBeforeCaret =
+      AgentDeviceDigitCount(textField.text, range.location) + AgentDeviceDigitCount(string, string.length);
+  NSUInteger caretOffset = formatted.length;
+  NSUInteger seen = 0;
+  for (NSUInteger index = 0; index < formatted.length; index++) {
+    if (![NSCharacterSet.decimalDigitCharacterSet characterIsMember:[formatted characterAtIndex:index]]) {
+      continue;
+    }
+    seen += 1;
+    if (seen == digitsBeforeCaret + 1) {
+      caretOffset = index;
+      break;
+    }
+  }
+  textField.selectedTextRange = [textField textRangeFromPosition:[textField positionFromPosition:textField.beginningOfDocument offset:caretOffset]
+                                                      toPosition:[textField positionFromPosition:textField.beginningOfDocument offset:caretOffset]];
+  return NO;
+}
+@end
+
+@implementation AgentDeviceCurrencyTextField
+- (BOOL)textField:(UITextField *)textField
+      shouldChangeCharactersInRange:(NSRange)range
+               replacementString:(NSString *)string {
+  NSString *combined = [textField.text stringByReplacingCharactersInRange:range withString:string];
+  NSMutableString *digits = [NSMutableString string];
+  for (NSString *part in [combined componentsSeparatedByCharactersInSet:NSCharacterSet.decimalDigitCharacterSet.invertedSet]) {
+    [digits appendString:part];
+  }
+  unsigned long long cents = digits.longLongValue;
+  textField.text = [NSString stringWithFormat:@"$%llu.%02llu", cents / 100, cents % 100];
+  self.insertedDigits += AgentDeviceDigitCount(string, string.length);
+  self.entryStatus.text = [NSString stringWithFormat:@"%lu", (unsigned long)self.insertedDigits];
+  textField.selectedTextRange = [textField textRangeFromPosition:textField.endOfDocument toPosition:textField.endOfDocument];
+  return NO;
+}
+@end
+
+@implementation AgentDeviceSubmitClearingTextField
+- (BOOL)textFieldShouldReturn:(UITextField *)textField {
+  self.submits += 1;
+  self.entryStatus.text = [NSString stringWithFormat:@"%lu", (unsigned long)self.submits];
+  textField.text = @"";
+  return YES;
+}
+@end
 #endif
 
 @implementation AgentDeviceRunnerViewController
@@ -202,11 +319,12 @@ static NSTimeInterval AgentDeviceAlertActivationBusyWindow(void) {
 - (void)updateTextEntryWriteBackStatus {
   NSTimeInterval burstSpan = self.textEntryLastEditTime - self.textEntryBurstStartTime;
   self.textEntryWriteBackStatus.text = [NSString
-    stringWithFormat:@"write-backs=%lu burst-edits=%lu burst-ms=%lu min-gap-ms=%lu",
+    stringWithFormat:@"write-backs=%lu burst-edits=%lu burst-ms=%lu min-gap-ms=%lu total-edits=%lu",
                      (unsigned long)self.textEntryWriteBacks,
                      (unsigned long)self.textEntryBurstEdits,
                      (unsigned long)llround(burstSpan * 1000),
-                     (unsigned long)llround(self.textEntryBurstMinGap * 1000)];
+                     (unsigned long)llround(self.textEntryBurstMinGap * 1000),
+                     (unsigned long)self.textEntryTotalEdits];
 }
 
 - (void)presentAlertFixtureReplacement:(BOOL)replacement {
@@ -292,6 +410,7 @@ static const CGFloat AgentDeviceTextEntryNeighbourGap = 16;
   // typed faster than the app renders loses the characters that arrived while a render was in
   // flight, and the field settles stable short of the request.
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-app-owned-value"]) {
+    self.textEntryTotalEdits += 1;
     NSTimeInterval now = NSProcessInfo.processInfo.systemUptime;
     NSTimeInterval gap = now - self.textEntryLastEditTime;
     BOOL overtookARender = self.textEntryRenderedValue != nil && gap < self.textEntryAcknowledgeWindowSeconds;
@@ -408,8 +527,28 @@ static const CGFloat AgentDeviceTextEntryNeighbourGap = 16;
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-regression"]) {
     BOOL digitCountValue =
         [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-digit-count-value"];
-    UITextField *textField =
-        digitCountValue ? [[AgentDeviceDigitCountTextField alloc] init] : [[UITextField alloc] init];
+    BOOL digitGroupingValue =
+        [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-digit-grouping-value"];
+    BOOL currencyValue =
+        [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-currency-value"];
+    BOOL submitClears =
+        [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-submit-clears"];
+    UITextField *textField;
+    if (digitCountValue) {
+      textField = [[AgentDeviceDigitCountTextField alloc] init];
+    } else if (digitGroupingValue) {
+      textField = [[AgentDeviceDigitGroupingTextField alloc] init];
+    } else if (currencyValue) {
+      textField = [[AgentDeviceCurrencyTextField alloc] init];
+      textField.text = @"$0.00";
+    } else if (submitClears) {
+      textField = [[AgentDeviceSubmitClearingTextField alloc] init];
+    } else {
+      textField = [[UITextField alloc] init];
+    }
+    if (digitGroupingValue || currencyValue || submitClears) {
+      textField.delegate = (id<UITextFieldDelegate>)textField;
+    }
     if (![NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-unnamed-input"]) {
       textField.accessibilityIdentifier = @"agent-device-hardware-keyboard-input";
     }
@@ -434,6 +573,22 @@ static const CGFloat AgentDeviceTextEntryNeighbourGap = 16;
       [textField.widthAnchor constraintEqualToConstant:240],
       [textField.heightAnchor constraintEqualToConstant:AgentDeviceTextEntryFieldHeight],
     ]];
+    if (currencyValue || submitClears) {
+      UILabel *entryStatus = [[UILabel alloc] init];
+      entryStatus.accessibilityIdentifier = @"agent-device-text-entry-events";
+      entryStatus.text = @"0";
+      entryStatus.translatesAutoresizingMaskIntoConstraints = NO;
+      [self.view addSubview:entryStatus];
+      [NSLayoutConstraint activateConstraints:@[
+        [entryStatus.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
+        [entryStatus.topAnchor constraintEqualToAnchor:textField.bottomAnchor constant:12],
+      ]];
+      if (currencyValue) {
+        ((AgentDeviceCurrencyTextField *)textField).entryStatus = entryStatus;
+      } else {
+        ((AgentDeviceSubmitClearingTextField *)textField).entryStatus = entryStatus;
+      }
+    }
     if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-unqueryable-on-focus"]) {
       self.textEntryFocusWitness = [[UILabel alloc] init];
       self.textEntryFocusWitness.accessibilityIdentifier = @"agent-device-text-entry-focus";

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerHttpRequestFraming.swift

@@ -0,0 +1,139 @@
+import Foundation
+
+
+
+enum RunnerHttpRequestRejection: Equatable {
+  case malformed(String)
+  case headTooLarge
+  case unauthorized
+  case transferEncodingUnsupported
+  case lengthRequired
+  case bodyTooLarge
+  case methodNotAllowed
+  case notFound
+  case timedOut
+
+  var status: Int {
+    switch self {
+    case .malformed, .transferEncodingUnsupported: return 400
+    case .unauthorized: return 401
+    case .notFound: return 404
+    case .methodNotAllowed: return 405
+    case .timedOut: return 408
+    case .lengthRequired: return 411
+    case .bodyTooLarge: return 413
+    case .headTooLarge: return 431
+    }
+  }
+
+  var code: String {
+    self == .unauthorized ? "UNAUTHORIZED" : "INVALID_ARGS"
+  }
+
+  var message: String {
+    switch self {
+    case .malformed(let part): return "runner request is malformed: \(part)"
+    case .headTooLarge:
+      return "runner request head exceeds \(RunnerHttpRequestFraming.maxHeadBytes) bytes"
+    case .unauthorized: return "runner request is missing a valid listener token"
+    case .transferEncodingUnsupported: return "runner requests must not use Transfer-Encoding"
+    case .lengthRequired: return "runner requests must declare one Content-Length"
+    case .bodyTooLarge:
+      return "runner request body exceeds \(RunnerHttpRequestFraming.maxBodyBytes) bytes"
+    case .methodNotAllowed: return "runner accepts only POST"
+    case .notFound: return "runner serves only \(RunnerHttpRequestFraming.commandPath)"
+    case .timedOut: return "runner request did not arrive before its deadline"
+    }
+  }
+}
+
+
+struct RunnerHttpAdmittedHead: Equatable {
+  let bodyOffset: Int
+  let contentLength: Int
+}
+
+enum RunnerHttpHeadVerdict: Equatable {
+  case incomplete
+  case admitted(RunnerHttpAdmittedHead)
+  case rejected(RunnerHttpRequestRejection)
+}
+
+
+
+enum RunnerHttpRequestFraming {
+  static let commandPath = "/command"
+  static let maxHeadBytes = 16 * 1024
+  static let maxBodyBytes = 2 * 1024 * 1024
+  private static let headTerminator = Data("\r\n\r\n".utf8)
+
+
+
+  static func admitHead(
+    _ buffer: Data,
+    token: RunnerListenerToken,
+    alreadyScanned: Int = 0
+  ) -> RunnerHttpHeadVerdict {
+    let searchStart = buffer.startIndex + max(0, alreadyScanned - (headTerminator.count - 1))
+    guard let terminator = buffer.range(of: headTerminator, in: searchStart..<buffer.endIndex) else {
+      return buffer.count > maxHeadBytes ? .rejected(.headTooLarge) : .incomplete
+    }
+    if terminator.lowerBound - buffer.startIndex > maxHeadBytes { return .rejected(.headTooLarge) }
+    guard
+      let head = String(data: buffer[buffer.startIndex..<terminator.lowerBound], encoding: .utf8)
+    else {
+      return .rejected(.malformed("head is not UTF-8"))
+    }
+    var lines = head.components(separatedBy: "\r\n")
+    let requestLine = lines.removeFirst().split(separator: " ", omittingEmptySubsequences: false)
+    guard requestLine.count == 3, requestLine[2] == "HTTP/1.1" || requestLine[2] == "HTTP/1.0" else {
+      return .rejected(.malformed("request line"))
+    }
+    var headers: [String: [String]] = [:]
+    for line in lines {
+      guard let colon = line.firstIndex(of: ":") else {
+        return .rejected(.malformed("header line"))
+      }
+      let name = line[line.startIndex..<colon]
+      guard !name.isEmpty, name.allSatisfy(isHeaderNameCharacter) else {
+        return .rejected(.malformed("header name"))
+      }
+      let value = line[line.index(after: colon)...].trimmingCharacters(in: CharacterSet(charactersIn: " \t"))
+      headers[name.lowercased(), default: []].append(value)
+    }
+
+    guard let presented = headers[RunnerListenerToken.requestHeaderName], presented.count == 1,
+      token.matches(presented[0])
+    else {
+      return .rejected(.unauthorized)
+    }
+    guard requestLine[0] == "POST" else { return .rejected(.methodNotAllowed) }
+    guard requestLine[1] == Substring(commandPath) else { return .rejected(.notFound) }
+    if headers["transfer-encoding"] != nil { return .rejected(.transferEncodingUnsupported) }
+    guard let lengths = headers["content-length"], lengths.count == 1 else {
+      return .rejected(.lengthRequired)
+    }
+    let declared = lengths[0]
+    guard !declared.isEmpty, declared.utf8.allSatisfy({ $0 >= 0x30 && $0 <= 0x39 }) else {
+      return .rejected(.malformed("Content-Length"))
+    }
+    guard declared.utf8.count <= 10, let contentLength = Int(declared), contentLength <= maxBodyBytes
+    else {
+      return .rejected(.bodyTooLarge)
+    }
+    return .admitted(
+      RunnerHttpAdmittedHead(
+        bodyOffset: terminator.upperBound - buffer.startIndex,
+        contentLength: contentLength
+      )
+    )
+  }
+
+  private static func isHeaderNameCharacter(_ character: Character) -> Bool {
+    guard let ascii = character.asciiValue else { return false }
+    switch ascii {
+    case 0x30...0x39, 0x41...0x5A, 0x61...0x7A: return true
+    default: return "!#$%&'*+-.^_`|~".utf8.contains(ascii)
+    }
+  }
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerListenerPeer.swift

@@ -0,0 +1,41 @@
+import Network
+
+
+
+
+
+
+enum RunnerListenerPeer: Equatable {
+
+
+  case loopback
+  case tunnel
+  case directNetwork
+
+  static func of(_ connection: NWConnection) -> RunnerListenerPeer {
+    classify(
+      isLoopbackAddress: isLoopback(connection.endpoint),
+      interfaceTypes: connection.currentPath?.availableInterfaces.map(\.type) ?? []
+    )
+  }
+
+  static func classify(
+    isLoopbackAddress: Bool,
+    interfaceTypes: [NWInterface.InterfaceType]
+  ) -> RunnerListenerPeer {
+    if isLoopbackAddress { return .loopback }
+
+
+    if !interfaceTypes.isEmpty && interfaceTypes.allSatisfy({ $0 == .other }) { return .tunnel }
+    return .directNetwork
+  }
+
+  static func isLoopback(_ endpoint: NWEndpoint) -> Bool {
+    guard case .hostPort(let host, _) = endpoint else { return false }
+    switch host {
+    case .ipv4(let address): return address.isLoopback
+    case .ipv6(let address): return address.isLoopback || (address.asIPv4?.isLoopback ?? false)
+    default: return false
+    }
+  }
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerListenerToken.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+
+struct RunnerListenerToken {
+  static let requestHeaderName = "x-agent-device-runner-token"
+  static let minimumByteCount = 32
+
+  private let expected: [UInt8]
+
+  init?(_ token: String?) {
+    guard let token, token.utf8.count >= Self.minimumByteCount else { return nil }
+    expected = Array(token.utf8)
+  }
+
+
+  func matches(_ presented: String) -> Bool {
+    let candidate = Array(presented.utf8)
+    var difference = candidate.count ^ expected.count
+    for index in 0..<expected.count {
+      let byte = index < candidate.count ? candidate[index] : 0
+      difference |= Int(byte ^ expected[index])
+    }
+    return difference == 0
+  }
+}