agent-device 0.20.10 → 0.21.1

package/README.md

@@ -141,11 +141,11 @@ The same session and evidence model works at every step: the agent explores the
 
 ## How it works
 
-`agent-device` keeps device state in sessions. It sends commands to XCTest on 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.
+`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.
 
-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. 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. 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).
 
 `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.1.apk.sha256

@@ -0,0 +1 @@
+65454a4663596adfc7fccd9a30e42f02b5ecde17eb1514fa115ef3036171b995  agent-device-android-ime-helper-0.21.1.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.10.manifest.json → agent-device-android-ime-helper-0.21.1.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.20.10",
-  "assetName": "agent-device-android-ime-helper-0.20.10.apk",
-  "sha256": "37cfdc9733315068659a6a4c1da8e65cd403e382401194f989f510fb0f320ba5",
+  "version": "0.21.1",
+  "assetName": "agent-device-android-ime-helper-0.21.1.apk",
+  "sha256": "65454a4663596adfc7fccd9a30e42f02b5ecde17eb1514fa115ef3036171b995",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20010,
+  "versionCode": 21001,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

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

@@ -0,0 +1 @@
+6ee75909ac499eca439d3663717d8fc1928ada3fec71bf2ae85fb567967a3793  agent-device-android-snapshot-helper-0.21.1.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.10.manifest.json → agent-device-android-snapshot-helper-0.21.1.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.20.10",
-  "releaseTag": "v0.20.10",
-  "assetName": "agent-device-android-snapshot-helper-0.20.10.apk",
+  "version": "0.21.1",
+  "releaseTag": "v0.21.1",
+  "assetName": "agent-device-android-snapshot-helper-0.21.1.apk",
   "apkUrl": null,
-  "sha256": "a5e8c39ef8dc5ca6fc1959dfcd52b00bd7845ce584abc0930f8d4a517bd784cc",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.10.apk.sha256",
+  "sha256": "6ee75909ac499eca439d3663717d8fc1928ada3fec71bf2ae85fb567967a3793",
+  "checksumName": "agent-device-android-snapshot-helper-0.21.1.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20010,
+  "versionCode": 21001,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

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

@@ -211,43 +211,28 @@ extension AudioProbeBucket {
   }
 }
 
+// This one-shot helper keeps ScreenCaptureKit callbacks and bucket cadence synchronous.
 func runAudioProbe(durationMs: Int, bucketMs: Int, outPath: String) throws -> AudioProbeResponse {
   guard #available(macOS 13.0, *) else {
     throw HelperError.commandFailed("audio probe requires macOS 13 or newer")
   }
-  let semaphore = DispatchSemaphore(value: 0)
-  var response: AudioProbeResponse?
-  var runError: Error?
-  Task {
-    do {
-      response = try await runAudioProbeAsync(durationMs: durationMs, bucketMs: bucketMs, outPath: outPath)
-    } catch {
-      runError = error
-    }
-    semaphore.signal()
-  }
-  semaphore.wait()
-  if let runError {
-    throw runError
-  }
-  guard let response else {
-    throw HelperError.commandFailed("audio probe failed")
-  }
-  return response
-}
 
-@available(macOS 13.0, *)
-private func runAudioProbeAsync(durationMs: Int, bucketMs: Int, outPath: String) async throws -> AudioProbeResponse {
-  let content: SCShareableContent
-  do {
-    content = try await SCShareableContent.current
-  } catch {
+  let contentSemaphore = DispatchSemaphore(value: 0)
+  var contentResult: SCShareableContent?
+  var contentError: Error?
+  SCShareableContent.getWithCompletionHandler { content, error in
+    contentResult = content
+    contentError = error
+    contentSemaphore.signal()
+  }
+  contentSemaphore.wait()
+  if let contentError {
     throw HelperError.commandFailed(
       "audio probe requires Screen Recording permission on macOS",
-      details: ["permission": "screen-recording", "error": error.localizedDescription]
+      details: ["permission": "screen-recording", "error": contentError.localizedDescription]
     )
   }
-  guard let display = content.displays.first else {
+  guard let display = contentResult?.displays.first else {
     throw HelperError.commandFailed("audio probe could not resolve a macOS display")
   }
 
@@ -267,18 +252,35 @@ private func runAudioProbeAsync(durationMs: Int, bucketMs: Int, outPath: String)
   let stream = SCStream(filter: filter, configuration: configuration, delegate: nil)
   let queue = DispatchQueue(label: "com.callstack.agent-device.audio-probe")
   try stream.addStreamOutput(output, type: .audio, sampleHandlerQueue: queue)
-  try await stream.startCapture()
+
+  let startSemaphore = DispatchSemaphore(value: 0)
+  var startError: Error?
+  stream.startCapture { error in
+    startError = error
+    startSemaphore.signal()
+  }
+  startSemaphore.wait()
+  if let startError {
+    throw HelperError.commandFailed(
+      "audio probe could not start the ScreenCaptureKit stream",
+      details: ["error": startError.localizedDescription]
+    )
+  }
   try writer.flushRunning()
 
   let deadline = Date().addingTimeInterval(Double(durationMs) / 1000)
   while Date() < deadline {
-    let remainingMs = Int(deadline.timeIntervalSinceNow * 1000)
-    let sleepMs = max(1, min(bucketMs, remainingMs))
-    try await Task.sleep(nanoseconds: UInt64(sleepMs) * 1_000_000)
+    let remainingMs = deadline.timeIntervalSinceNow * 1000
+    let sleepMs = max(1, min(Double(bucketMs), remainingMs))
+    Thread.sleep(forTimeInterval: sleepMs / 1000)
     try writer.flushRunning()
   }
 
-  try await stream.stopCapture()
+  let stopSemaphore = DispatchSemaphore(value: 0)
+  stream.stopCapture { _ in
+    stopSemaphore.signal()
+  }
+  stopSemaphore.wait()
   try writer.finish(reason: "completed")
   let data = try Data(contentsOf: URL(fileURLWithPath: outPath))
   return try JSONDecoder().decode(AudioProbeResponse.self, from: data)

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

@@ -287,9 +287,14 @@ struct AgentDeviceMacOSHelper {
     let surface = optionValue(arguments: Array(arguments.dropFirst()), name: "--surface")
     let app = try resolveTargetApplication(bundleId: bundleId, surface: surface)
     guard let alertElement = findAlertElement(appElement: AXUIElementCreateApplication(app.processIdentifier)) else {
+      // `reason` is the typed channel the host retries on; the message is for humans only.
       throw HelperError.commandFailed(
         "alert not found",
-        details: ["bundleId": app.bundleIdentifier ?? "", "appName": app.localizedName ?? ""]
+        details: [
+          "reason": "alert-not-found",
+          "bundleId": app.bundleIdentifier ?? "",
+          "appName": app.localizedName ?? "",
+        ]
       )
     }
     let buttons = collectButtons(root: alertElement)

package/apple/snapshot-bridge/LICENSE.idb

@@ -0,0 +1,23 @@
+The Simulator AX bridge contains code adapted from Meta Platforms, Inc. idb
+v1.5.2, specifically SimulatorFrameworkBridge/AccessibilityService.m and
+SimulatorFrameworkBridge/AccessibilityRuntime.m.
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/apple/snapshot-bridge/README.md

@@ -0,0 +1,106 @@
+# Simulator AX bridge
+
+This directory contains the small private accessibility reader used by the
+Apple platform acquisition facet. The framed server and request validation
+live in `SnapshotBridge.m`; private runtime binding lives in
+`SnapshotBridgeRuntime.m`. It is compiled for the iOS Simulator on first use
+and is never downloaded, pre-signed, or built by npm installation.
+
+The guest process uses the `XCTAccessibilityFramework` remote-access client
+from the simulator runtime and the `userTestingSnapshotForElement:options:error:`
+snapshot API. Requests and responses are length-prefixed JSON frames:
+
+```text
+uint32 big-endian byte length
+UTF-8 JSON object
+```
+
+The host owns all target identity, bounds, deadlines, and lifecycle decisions.
+The guest returns only a bounded raw tree, the target pid, truncation, and
+protocol/source versions. It does not expose an HTTP route or a public CLI
+surface.
+
+The private API is intentionally pinned to the idb v1.5.2-compatible shape.
+See `LICENSE.idb` for attribution.
+
+## Why Objective-C
+
+The selected #2192 mechanism was idb v1.5.2's Objective-C
+`SimulatorFrameworkBridge`; the Python used during the spike was only a client
+for exercising that guest reader. This bridge keeps the proven native boundary
+and removes the Python/idb client dependency.
+
+Objective-C is the narrowest implementation for this private runtime adapter:
+it resolves unavailable classes and functions with `dlopen`, `dlsym`, and the
+Objective-C runtime, invokes dynamically discovered selectors, and contains
+`NSException` failures. A Swift implementation would still require an
+Objective-C shim for those operations, adding another native boundary. Keeping
+the guest in Objective-C also allows direct lazy compilation with `clang`
+without an Xcode project or Swift module for private headers.
+
+## Foreground ownership
+
+The reader checks AXRuntime's primary foreground application before and after
+acquisition. If the target is covered by system UI, ownership is unavailable,
+or the owner changes during capture, it returns a typed failure without the
+app tree. The existing route then uses XCTest, which owns system-modal
+resolution. Secondary owners such as the return-to-app status-bar control do
+not replace the native primary owner. The route's generation circuit remains
+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.
+
+## Bounded depth recovery
+
+A healthy capture uses one native request. If native acquisition rejects it,
+`SnapshotBridgeCapture.m` retries supported native failure codes at lower depths
+and fetches withheld children from their accessibility elements. The completed
+tree keeps the original depth and node limits; partial trees disclose truncation.
+The traversal depth counts edges below the root; native requests count the root
+as one level. Each acquisition allows two lower-depth retries, and recovery
+allows at most 32 native requests within the existing capture deadline,
+checks foreground ownership on every request, and returns a failure when it
+cannot complete a continuation. Budget exhaustion and malformed continuations
+use non-launch failure codes, so the route falls back without launch re-polling.
+At each native fragment boundary, an absent or invalid child count means unknown
+completeness and fails closed. Natural leaves above that boundary need no
+continuation evidence. Unchanged native dictionaries and child arrays are reused.
+
+## Accepted-depth hints
+
+The host source (`packages/platform-apple/src/snapshot-source/depth-hints.ts`)
+remembers the native levels a finished recovery accepted, keyed by the resolved
+target id, its app generation, and this producer. The next capture of that
+generation sends `nativeLevelsHint`, so the guest's first request asks for the
+accepted levels instead of re-paying the known rejection. A hint changes the
+request strategy only: the delivered depth, node bounds, and completeness rules
+are unchanged. Hints are learned only from a recovery that observed a rejection
+and then finished (a tree bounded by the requested depth or node budget still
+teaches), never cross apps, generations, or producers, and expire after eight
+hinted captures so the next capture probes the full depth again; a capture that
+merely succeeds at the hinted depth does not renew it. Explicit raw-depth
+requests neither use nor teach hints. Every response carries `recovery`
+(`requests`, `rejected`, `continuations`, `acceptedLevels`), which the host
+emits as the `ios_snapshot_source_recovery` diagnostic.
+
+## Recovery conformance
+
+`contracts/fixtures/ios-ax-recovery-conformance.json` is the shared, executable
+recovery contract for this bridge and the XCTest runner's private AX bridge.
+`packages/platform-apple/src/snapshot-source/fixtures/recovery-conformance.m`
+replays each case through `captureSnapshotTree`; the runner replays the same
+cases through its own bridge in
+`RunnerTests+AXRecoveryConformanceTests.swift`. Each expectation names the
+outcome, the native request accounting, and the delivered tree as a canonical
+preorder signature with its retained node count, so a producer that drops,
+duplicates, reorders, or re-parents nodes cannot pass as complete. The fixture
+records each producer's expectation and documents the intentional differences
+(depth vocabulary, ladders, completeness evidence, budgets, hint lifetime).

package/apple/snapshot-bridge/SnapshotBridge.m

@@ -0,0 +1,286 @@
+/*
+ * The framed server and request validation for the private Simulator AX reader.
+ * The runtime binding is isolated in SnapshotBridgeRuntime.m.
+ */
+
+#import "SnapshotBridgeRuntime.h"
+
+#import <Foundation/Foundation.h>
+
+#import <arpa/inet.h>
+#import <errno.h>
+#import <limits.h>
+#import <math.h>
+#import <poll.h>
+#import <sys/socket.h>
+#import <sys/stat.h>
+#import <sys/types.h>
+#import <sys/un.h>
+#import <unistd.h>
+
+static const int kDefaultIdleTimeoutSeconds = 60;
+
+static void bridgeLog(NSString *message)
+{
+  fprintf(stderr, "[agent-device-snapshot-bridge] %s\n", message.UTF8String ?: "(no message)");
+  fflush(stderr);
+}
+
+NSDictionary *failureResponse(NSString *requestId,
+                              NSString *kind,
+                              NSString *code,
+                              NSString *message)
+{
+  return @{
+    kProtocolVersionKey : @(kProtocolVersion),
+    kSourceVersionKey : kSourceVersion,
+    kRequestIdKey : requestId ?: @"",
+    @"ok" : @NO,
+    @"error_kind" : kind ?: @"reader_unavailable",
+    @"error_code" : code ?: @"unknown",
+    @"error" : message ?: @"snapshot bridge request failed",
+  };
+}
+
+static BOOL validBoundInteger(id value, NSUInteger minimum, NSUInteger maximum, NSUInteger *output)
+{
+  if (![value isKindOfClass:NSNumber.class]) return NO;
+  NSNumber *number = value;
+  if (number.doubleValue != floor(number.doubleValue)) return NO;
+  if (number.unsignedIntegerValue < minimum || number.unsignedIntegerValue > maximum) return NO;
+  if (output) *output = number.unsignedIntegerValue;
+  return YES;
+}
+
+static NSDictionary *handleRequest(NSDictionary *request)
+{
+  NSString *requestId = [request[kRequestIdKey] isKindOfClass:NSString.class] ? request[kRequestIdKey] : @"";
+  id verb = request[@"verb"];
+  if (![verb isKindOfClass:NSString.class] || ![verb isEqualToString:@"describe"]) {
+    return failureResponse(requestId, @"bad_request", @"verb-not-supported", @"snapshot bridge accepts describe requests only");
+  }
+  NSNumber *pidValue = request[@"pid"];
+  if (!validBoundInteger(pidValue, 1, INT_MAX, NULL)) {
+    return failureResponse(requestId, @"bad_request", @"pid-required", @"describe requires a positive target pid");
+  }
+  NSString *generation = [request[@"generation"] isKindOfClass:NSString.class] ? request[@"generation"] : @"";
+  if (generation.length == 0) {
+    return failureResponse(requestId, @"bad_request", @"generation-required", @"describe requires an opaque target generation");
+  }
+  id snapshotTree = request[@"snapshotTree"];
+  if (![snapshotTree isKindOfClass:NSNumber.class] || ![snapshotTree boolValue]) {
+    return failureResponse(requestId, @"bad_request", @"snapshot-tree-required", @"snapshotTree must be enabled");
+  }
+  id automationMode = request[@"automationMode"];
+  if (![automationMode isKindOfClass:NSNumber.class] || ![automationMode boolValue]) {
+    return failureResponse(requestId, @"bad_request", @"automation-mode-required", @"automationMode must be enabled");
+  }
+  NSUInteger maxDepth = 0;
+  NSUInteger maxNodes = 0;
+  NSUInteger maxDurationMs = 0;
+  NSUInteger maxResponseBytes = 0;
+  if (!validBoundInteger(request[@"maxDepth"], 0, kMaximumDepth, &maxDepth) ||
+      !validBoundInteger(request[@"maxNodes"], 1, kMaximumNodes, &maxNodes) ||
+      !validBoundInteger(request[@"maxDurationMs"], 1, kMaximumDurationMs, &maxDurationMs) ||
+      !validBoundInteger(request[@"maxResponseBytes"], 1024, kMaximumFrameBytes, &maxResponseBytes)) {
+    return failureResponse(requestId, @"bad_request", @"bounds-invalid", @"snapshot bridge request bounds are outside the bridge limits");
+  }
+  NSUInteger nativeLevelsHint = 0;
+  if (request[@"nativeLevelsHint"] != nil &&
+      !validBoundInteger(request[@"nativeLevelsHint"], 1, kMaximumDepth + 1, &nativeLevelsHint)) {
+    return failureResponse(requestId, @"bad_request", @"bounds-invalid", @"nativeLevelsHint is outside the bridge depth limits");
+  }
+
+  NSString *setupError = nil;
+  BridgeRuntime *runtime = sharedRuntime(&setupError);
+  if (!runtime) {
+    NSMutableDictionary *unavailable = [failureResponse(requestId, @"unsupported", @"runtime-unavailable", setupError) mutableCopy];
+    unavailable[@"pid"] = pidValue;
+    unavailable[@"generation"] = generation;
+    return unavailable;
+  }
+  NSDictionary *error = nil;
+  NSDictionary *response = [runtime snapshotForProcess:pidValue.intValue
+                                               maxDepth:maxDepth
+                                               maxNodes:maxNodes
+                                       nativeLevelsHint:nativeLevelsHint
+                                             requestId:requestId
+                                           generation:generation
+                                         maxDurationMs:maxDurationMs
+                                                 error:&error];
+  if (response) return response;
+  if (error) {
+    NSMutableDictionary *annotated = [error mutableCopy];
+    annotated[@"pid"] = pidValue;
+    annotated[@"generation"] = generation;
+    return annotated;
+  }
+  return failureResponse(requestId, @"reader_unavailable", @"empty-response", @"AX bridge returned no response");
+}
+
+static BOOL readFully(int fd, void *buffer, size_t length)
+{
+  size_t offset = 0;
+  while (offset < length) {
+    ssize_t count = recv(fd, (char *)buffer + offset, length - offset, 0);
+    if (count > 0) {
+      offset += (size_t)count;
+      continue;
+    }
+    if (count < 0 && errno == EINTR) continue;
+    return NO;
+  }
+  return YES;
+}
+
+static BOOL writeFully(int fd, const void *buffer, size_t length)
+{
+  size_t offset = 0;
+  while (offset < length) {
+    ssize_t count = send(fd, (const char *)buffer + offset, length - offset, MSG_NOSIGNAL);
+    if (count > 0) {
+      offset += (size_t)count;
+      continue;
+    }
+    if (count < 0 && errno == EINTR) continue;
+    return NO;
+  }
+  return YES;
+}
+
+static NSData *serializedResponse(NSDictionary *response, NSUInteger maxResponseBytes)
+{
+  NSError *error = nil;
+  NSData *data = nil;
+  @try {
+    data = [NSJSONSerialization dataWithJSONObject:response options:0 error:&error];
+    if (data && data.length + sizeof(uint32_t) <= maxResponseBytes) return data;
+  } @catch (NSException *exception) {
+    bridgeLog(exception.reason ?: @"response serialization raised an exception");
+  }
+  NSMutableDictionary *fallback = [failureResponse(
+      response[kRequestIdKey],
+      data ? @"response_limit_exceeded" : @"malformed_tree",
+      data ? @"response-too-large" : @"response-not-json-safe",
+      data ? @"snapshot response exceeds the per-request response bound" : (error.localizedDescription ?: @"response was not JSON serializable")) mutableCopy];
+  if (response[@"pid"] != nil) fallback[@"pid"] = response[@"pid"];
+  if (response[@"generation"] != nil) fallback[@"generation"] = response[@"generation"];
+  return [NSJSONSerialization dataWithJSONObject:fallback options:0 error:NULL];
+}
+
+static NSUInteger responseLimitForRequest(id request)
+{
+  if (![request isKindOfClass:NSDictionary.class]) return kMaximumFrameBytes;
+  NSNumber *value = request[@"maxResponseBytes"];
+  if (![value isKindOfClass:NSNumber.class]) return kMaximumFrameBytes;
+  NSUInteger result = value.unsignedIntegerValue;
+  return result >= 1024 && result <= kMaximumFrameBytes ? result : kMaximumFrameBytes;
+}
+
+static int serve(NSString *socketPath, int idleTimeoutSeconds, BOOL exitOnDisconnect)
+{
+  if (socketPath.length == 0 || socketPath.length >= sizeof(((struct sockaddr_un *)0)->sun_path)) {
+    bridgeLog(@"socket path is empty or too long");
+    return 1;
+  }
+
+  int listener = socket(AF_UNIX, SOCK_STREAM, 0);
+  if (listener < 0) {
+    bridgeLog([NSString stringWithFormat:@"socket failed: %s", strerror(errno)]);
+    return 1;
+  }
+  struct sockaddr_un address = {0};
+  address.sun_family = AF_UNIX;
+  strlcpy(address.sun_path, socketPath.fileSystemRepresentation, sizeof(address.sun_path));
+  unlink(address.sun_path);
+  if (bind(listener, (struct sockaddr *)&address, sizeof(address)) != 0 || listen(listener, 4) != 0) {
+    bridgeLog([NSString stringWithFormat:@"bind/listen failed for %@: %s", socketPath, strerror(errno)]);
+    close(listener);
+    return 1;
+  }
+  chmod(address.sun_path, S_IRUSR | S_IWUSR);
+  bridgeLog([NSString stringWithFormat:@"serving protocol %lu on %@", (unsigned long)kProtocolVersion, socketPath]);
+
+  BOOL done = NO;
+  while (!done) {
+    struct pollfd waitForClient = {.fd = listener, .events = POLLIN, .revents = 0};
+    int ready = poll(&waitForClient, 1, idleTimeoutSeconds * 1000);
+    if (ready == 0) break;
+    if (ready < 0) {
+      if (errno == EINTR) continue;
+      break;
+    }
+    int connection = accept(listener, NULL, NULL);
+    if (connection < 0) {
+      if (errno == EINTR) continue;
+      break;
+    }
+    struct timeval timeout = {.tv_sec = idleTimeoutSeconds, .tv_usec = 0};
+    setsockopt(connection, SOL_SOCKET, SO_RCVTIMEO, &timeout, sizeof(timeout));
+    setsockopt(connection, SOL_SOCKET, SO_SNDTIMEO, &timeout, sizeof(timeout));
+    while (YES) {
+      @autoreleasepool {
+        uint32_t networkLength = 0;
+        if (!readFully(connection, &networkLength, sizeof(networkLength))) break;
+        uint32_t length = ntohl(networkLength);
+        if (length == 0 || length > kMaximumFrameBytes) break;
+        NSMutableData *body = [NSMutableData dataWithLength:length];
+        if (!readFully(connection, body.mutableBytes, length)) break;
+        id parsed = [NSJSONSerialization JSONObjectWithData:body options:0 error:NULL];
+        NSDictionary *response = [parsed isKindOfClass:NSDictionary.class]
+            ? handleRequest(parsed)
+            : failureResponse(@"", @"bad_request", @"json-object-required", @"request frame must be a JSON object");
+        NSData *encoded = serializedResponse(response, responseLimitForRequest(parsed));
+        if (encoded.length > kMaximumFrameBytes) break;
+        uint32_t responseLength = htonl((uint32_t)encoded.length);
+        if (!writeFully(connection, &responseLength, sizeof(responseLength)) ||
+            !writeFully(connection, encoded.bytes, encoded.length)) break;
+      }
+    }
+    close(connection);
+    if (exitOnDisconnect) done = YES;
+  }
+
+  close(listener);
+  unlink(address.sun_path);
+  return 0;
+}
+
+static int integerArgument(NSArray<NSString *> *arguments, NSString *flag, int fallback)
+{
+  for (NSUInteger index = 0; index + 1 < arguments.count; index += 1) {
+    if (![arguments[index] isEqualToString:flag]) continue;
+    NSInteger value = arguments[index + 1].integerValue;
+    if (value > 0 && value <= INT_MAX) return (int)value;
+  }
+  return fallback;
+}
+
+static BOOL boolArgument(NSArray<NSString *> *arguments, NSString *flag, BOOL fallback)
+{
+  for (NSUInteger index = 0; index + 1 < arguments.count; index += 1) {
+    if ([arguments[index] isEqualToString:flag]) return [arguments[index + 1] boolValue];
+  }
+  return fallback;
+}
+
+int main(int argc, const char *argv[])
+{
+  @autoreleasepool {
+    if (argc < 3 || strcmp(argv[1], "serve") != 0) {
+      fprintf(stderr, "Usage: %s serve <socket> [--idle-timeout <seconds>] [--exit-on-disconnect <bool>]\n", argv[0]);
+      return 2;
+    }
+    NSMutableArray<NSString *> *arguments = [NSMutableArray array];
+    for (int index = 2; index < argc; index += 1) {
+      NSString *value = [NSString stringWithUTF8String:argv[index]];
+      if (value) [arguments addObject:value];
+    }
+    NSString *socketPath = arguments.firstObject;
+    if (socketPath.length == 0) return 2;
+    NSArray<NSString *> *flags = [arguments subarrayWithRange:NSMakeRange(1, arguments.count - 1)];
+    return serve(socketPath,
+                 integerArgument(flags, @"--idle-timeout", kDefaultIdleTimeoutSeconds),
+                 boolArgument(flags, @"--exit-on-disconnect", YES));
+  }
+}

package/apple/snapshot-bridge/SnapshotBridgeCapture.h

@@ -0,0 +1,25 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+typedef id _Nullable (^SnapshotElementReader)(id element, NSUInteger depth, NSUInteger nodes, NSError **error);
+
+/// Native request accounting for one acquisition: requests issued, requests the accessibility
+/// server rejected at their depth, continuations (requests that reached the reader beyond the
+/// root's accepted one), and the native levels of the last accepted request.
+typedef struct {
+  NSUInteger requests;
+  NSUInteger rejected;
+  NSUInteger continuations;
+  NSUInteger acceptedLevels;
+} SnapshotCaptureRecovery;
+
+/// Materializes one bounded tree; retries bounded native acquisition failures and re-roots withheld
+/// children. `nativeLevelsHint` (0 for none) caps only the first request's native levels; the
+/// delivered depth, node bounds, and completeness rules are unchanged.
+NSDictionary *_Nullable captureSnapshotTree(id element, NSUInteger maxDepth, NSUInteger maxNodes,
+                                           NSUInteger nativeLevelsHint, SnapshotElementReader reader,
+                                           BOOL *truncated, SnapshotCaptureRecovery *_Nullable recovery,
+                                           NSError **error);
+
+NS_ASSUME_NONNULL_END