agent-device 0.20.9 → 0.21.0

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.0.apk.sha256

@@ -0,0 +1 @@
+2f486edc5788d34f3ba8afd551f33e59a4823a6f358d2a3e883e93b3f2a0d7e8  agent-device-android-ime-helper-0.21.0.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.9.manifest.json → agent-device-android-ime-helper-0.21.0.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.20.9",
-  "assetName": "agent-device-android-ime-helper-0.20.9.apk",
-  "sha256": "f98ded51f104c10268a75b7eb77f2e479461b844e49f238593d44b821d13e294",
+  "version": "0.21.0",
+  "assetName": "agent-device-android-ime-helper-0.21.0.apk",
+  "sha256": "2f486edc5788d34f3ba8afd551f33e59a4823a6f358d2a3e883e93b3f2a0d7e8",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20009,
+  "versionCode": 21000,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

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

@@ -0,0 +1 @@
+536b4096b0bfd7e224a6ebbeeff1daaca0a8df4dc56abd3e410541ad1733048f  agent-device-android-snapshot-helper-0.21.0.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.9.manifest.json → agent-device-android-snapshot-helper-0.21.0.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.20.9",
-  "releaseTag": "v0.20.9",
-  "assetName": "agent-device-android-snapshot-helper-0.20.9.apk",
+  "version": "0.21.0",
+  "releaseTag": "v0.21.0",
+  "assetName": "agent-device-android-snapshot-helper-0.21.0.apk",
   "apkUrl": null,
-  "sha256": "a5169f62fb38bb1980cf7c7963542f2bc5bbaafd4d9dc7b5b23d3e41ee782725",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.9.apk.sha256",
+  "sha256": "536b4096b0bfd7e224a6ebbeeff1daaca0a8df4dc56abd3e410541ad1733048f",
+  "checksumName": "agent-device-android-snapshot-helper-0.21.0.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20009,
+  "versionCode": 21000,
   "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,49 @@
+# 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:`
+single-fetch 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.

package/apple/snapshot-bridge/SnapshotBridge.m

@@ -0,0 +1,280 @@
+/*
+ * 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");
+  }
+
+  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
+                                             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/SnapshotBridgeRuntime.h

@@ -0,0 +1,33 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+extern NSString *const kProtocolVersionKey;
+extern NSString *const kSourceVersionKey;
+extern NSString *const kRequestIdKey;
+extern NSString *const kSourceVersion;
+extern const NSUInteger kProtocolVersion;
+extern const uint32_t kMaximumFrameBytes;
+extern const NSUInteger kMaximumDepth;
+extern const NSUInteger kMaximumNodes;
+extern const NSUInteger kMaximumDurationMs;
+
+NSDictionary *failureResponse(NSString *requestId,
+                              NSString *kind,
+                              NSString *code,
+                              NSString *message);
+
+@interface BridgeRuntime : NSObject
+- (nullable instancetype)initWithError:(NSString *_Nullable *_Nullable)error;
+- (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
+                                    maxDepth:(NSUInteger)maxDepth
+                                    maxNodes:(NSUInteger)maxNodes
+                                  requestId:(NSString *)requestId
+                                generation:(NSString *)generation
+                              maxDurationMs:(NSUInteger)maxDurationMs
+                                    error:(NSDictionary *_Nullable *_Nonnull)error;
+@end
+
+BridgeRuntime *_Nullable sharedRuntime(NSString *_Nullable *_Nullable error);
+
+NS_ASSUME_NONNULL_END