refactor: add ios runner lifecycle protocol

Author: thymikee

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -26,6 +26,19 @@ extension RunnerTests {
   }
 
   func execute(command: Command) throws -> Response {
+    commandJournal.accept(command: command)
+    commandJournal.start(command: command)
+    do {
+      let response = try executeDispatched(command: command)
+      commandJournal.finish(command: command, response: response)
+      return response
+    } catch {
+      commandJournal.fail(command: command, error: error)
+      throw error
+    }
+  }
+
+  private func executeDispatched(command: Command) throws -> Response {
     if Thread.isMainThread {
       return try executeOnMainSafely(command: command)
     }
@@ -183,6 +196,15 @@ extension RunnerTests {
     }
 
     switch command.command {
+    case .status:
+      guard
+        let statusCommandId = command.statusCommandId?
+          .trimmingCharacters(in: .whitespacesAndNewlines),
+        !statusCommandId.isEmpty
+      else {
+        return Response(ok: false, error: ErrorPayload(message: "status requires statusCommandId"))
+      }
+      return Response(ok: true, data: commandJournal.status(commandId: statusCommandId))
     case .shutdown:
       stopRecordingIfNeeded()
       return Response(ok: true, data: DataPayload(message: "shutdown"))

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift

@@ -0,0 +1,135 @@
+import Foundation
+
+enum RunnerCommandLifecycleState: String {
+  case accepted
+  case started
+  case completed
+  case failed
+}
+
+struct RunnerCommandJournalEntry {
+  let commandId: String
+  let command: String
+  var state: RunnerCommandLifecycleState
+  var response: Response?
+  var error: ErrorPayload?
+  var updatedAtMs: Double
+}
+
+final class RunnerCommandJournal {
+  private let lock = NSLock()
+  private let maxEntries = 64
+  private var entries: [String: RunnerCommandJournalEntry] = [:]
+  private var order: [String] = []
+
+  func accept(command: Command) {
+    guard let commandId = normalizedCommandId(command.commandId) else { return }
+    lock.lock()
+    defer { lock.unlock() }
+    entries[commandId] = RunnerCommandJournalEntry(
+      commandId: commandId,
+      command: command.command.rawValue,
+      state: .accepted,
+      response: nil,
+      error: nil,
+      updatedAtMs: currentTimeMs()
+    )
+    order.removeAll { $0 == commandId }
+    order.append(commandId)
+    pruneIfNeeded()
+  }
+
+  func start(command: Command) {
+    update(command: command, state: .started, response: nil, error: nil)
+  }
+
+  func finish(command: Command, response: Response) {
+    update(
+      command: command,
+      state: response.ok ? .completed : .failed,
+      response: response,
+      error: response.error
+    )
+  }
+
+  func fail(command: Command, error: Error) {
+    update(
+      command: command,
+      state: .failed,
+      response: nil,
+      error: ErrorPayload(message: error.localizedDescription)
+    )
+  }
+
+  func status(commandId: String) -> DataPayload {
+    guard let normalized = normalizedCommandId(commandId) else {
+      return DataPayload(lifecycleState: "notAccepted")
+    }
+    lock.lock()
+    let entry = entries[normalized]
+    lock.unlock()
+    guard let entry else {
+      return DataPayload(commandId: normalized, lifecycleState: "notAccepted")
+    }
+    return DataPayload(
+      commandId: entry.commandId,
+      lifecycleState: entry.state.rawValue,
+      lifecycleCommand: entry.command,
+      lifecycleResponseOk: entry.response?.ok,
+      lifecycleResponseJson: encodeResponseJson(entry.response),
+      lifecycleErrorCode: entry.error?.code,
+      lifecycleErrorMessage: entry.error?.message,
+      lifecycleErrorHint: entry.error?.hint
+    )
+  }
+
+  private func update(
+    command: Command,
+    state: RunnerCommandLifecycleState,
+    response: Response?,
+    error: ErrorPayload?
+  ) {
+    guard let commandId = normalizedCommandId(command.commandId) else { return }
+    lock.lock()
+    defer { lock.unlock() }
+    var entry = entries[commandId] ?? RunnerCommandJournalEntry(
+      commandId: commandId,
+      command: command.command.rawValue,
+      state: .accepted,
+      response: nil,
+      error: nil,
+      updatedAtMs: currentTimeMs()
+    )
+    entry.state = state
+    entry.response = response
+    entry.error = error
+    entry.updatedAtMs = currentTimeMs()
+    entries[commandId] = entry
+    order.removeAll { $0 == commandId }
+    order.append(commandId)
+    pruneIfNeeded()
+  }
+
+  private func pruneIfNeeded() {
+    while order.count > maxEntries {
+      let removed = order.removeFirst()
+      entries.removeValue(forKey: removed)
+    }
+  }
+
+  private func normalizedCommandId(_ value: String?) -> String? {
+    guard let value else { return nil }
+    let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+    return trimmed.isEmpty ? nil : trimmed
+  }
+
+  private func currentTimeMs() -> Double {
+    Date().timeIntervalSince1970 * 1000
+  }
+
+  private func encodeResponseJson(_ response: Response?) -> String? {
+    guard let response else { return nil }
+    guard let data = try? JSONEncoder().encode(response) else { return nil }
+    return String(data: data, encoding: .utf8)
+  }
+}

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

@@ -30,6 +30,7 @@ enum CommandType: String, Codable {
   case transformGesture
   case recordStart
   case recordStop
+  case status
   case uptime
   case shutdown
 }
@@ -91,6 +92,9 @@ extension CommandType {
     case .recordStop, .uptime, .shutdown:
       return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: true)
 
+    case .status:
+      return CommandTraits(isInteraction: false, readOnly: .always, isLifecycle: true)
+
     // Normal preflight, not retried.
     // NOTE: mouseClick stays non-interaction for now — it is macOS-only and the foreground
     // guard interacts with bespoke macOS activation, so classifying it needs a macOS smoke
@@ -104,6 +108,8 @@ extension CommandType {
 
 struct Command: Codable {
   let command: CommandType
+  let commandId: String?
+  let statusCommandId: String?
   let appBundleId: String?
   let text: String?
   let selectorKey: String?
@@ -171,6 +177,14 @@ struct DataPayload: Codable {
   let referenceWidth: Double?
   let referenceHeight: Double?
   let currentUptimeMs: Double?
+  let commandId: String?
+  let lifecycleState: String?
+  let lifecycleCommand: String?
+  let lifecycleResponseOk: Bool?
+  let lifecycleResponseJson: String?
+  let lifecycleErrorCode: String?
+  let lifecycleErrorMessage: String?
+  let lifecycleErrorHint: String?
   let visible: Bool?
   let wasVisible: Bool?
   let dismissed: Bool?
@@ -192,6 +206,14 @@ struct DataPayload: Codable {
     referenceWidth: Double? = nil,
     referenceHeight: Double? = nil,
     currentUptimeMs: Double? = nil,
+    commandId: String? = nil,
+    lifecycleState: String? = nil,
+    lifecycleCommand: String? = nil,
+    lifecycleResponseOk: Bool? = nil,
+    lifecycleResponseJson: String? = nil,
+    lifecycleErrorCode: String? = nil,
+    lifecycleErrorMessage: String? = nil,
+    lifecycleErrorHint: String? = nil,
     visible: Bool? = nil,
     wasVisible: Bool? = nil,
     dismissed: Bool? = nil,
@@ -212,6 +234,14 @@ struct DataPayload: Codable {
     self.referenceWidth = referenceWidth
     self.referenceHeight = referenceHeight
     self.currentUptimeMs = currentUptimeMs
+    self.commandId = commandId
+    self.lifecycleState = lifecycleState
+    self.lifecycleCommand = lifecycleCommand
+    self.lifecycleResponseOk = lifecycleResponseOk
+    self.lifecycleResponseJson = lifecycleResponseJson
+    self.lifecycleErrorCode = lifecycleErrorCode
+    self.lifecycleErrorMessage = lifecycleErrorMessage
+    self.lifecycleErrorHint = lifecycleErrorHint
     self.visible = visible
     self.wasVisible = wasVisible
     self.dismissed = dismissed

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift

@@ -53,6 +53,7 @@ final class RunnerTests: XCTestCase {
   var needsPostSnapshotInteractionDelay = false
   var needsFirstInteractionDelay = false
   var activeRecording: ScreenRecorder?
+  let commandJournal = RunnerCommandJournal()
   let interactiveTypes: Set<XCUIElement.ElementType> = [
     .button,
     .cell,

src/platforms/ios/__tests__/runner-client.test.ts

@@ -159,6 +159,7 @@ const runnerProtocolCommandFixtures: Record<RunnerCommand['command'], RunnerComm
     quality: 7,
   },
   recordStop: { command: 'recordStop' },
+  status: { command: 'status', statusCommandId: 'runner-command-1' },
   uptime: { command: 'uptime' },
   shutdown: { command: 'shutdown' },
 };
@@ -359,6 +360,7 @@ test('runner protocol fixtures cover every runner command with JSON-safe samples
     'screenshot',
     'shutdown',
     'snapshot',
+    'status',
     'swipe',
     'tap',
     'tapSeries',

src/platforms/ios/__tests__/runner-session.test.ts

@@ -128,13 +128,44 @@ test('runner session executes read-only commands without uptime preflight', asyn
   assert.deepEqual(result, { nodes: [], truncated: false });
   assert.equal(session.ready, true);
   assert.equal(mockWaitForRunner.mock.calls.length, 1);
-  assert.deepEqual(mockWaitForRunner.mock.calls[0]?.[2], {
+  assertRunnerCommand(mockWaitForRunner.mock.calls[0]?.[2], {
     command: 'snapshot',
     appBundleId: 'com.example.demo',
   });
   assert.equal(mockSendRunnerCommandOnce.mock.calls.length, 0);
 });
 
+test('runner session executes status command as read-only lifecycle command', async () => {
+  const session = makeRunnerSession({ ready: true });
+  mockWaitForRunner.mockResolvedValueOnce(
+    runnerResponse({
+      commandId: 'runner-command-1',
+      lifecycleState: 'completed',
+      lifecycleResponseOk: true,
+    }),
+  );
+
+  const result = await executeRunnerCommandWithSession(
+    IOS_SIMULATOR,
+    session,
+    { command: 'status', statusCommandId: 'runner-command-1' },
+    '/tmp/runner.log',
+    30_000,
+  );
+
+  assert.deepEqual(result, {
+    commandId: 'runner-command-1',
+    lifecycleState: 'completed',
+    lifecycleResponseOk: true,
+  });
+  assert.equal(mockWaitForRunner.mock.calls.length, 1);
+  assertRunnerCommand(mockWaitForRunner.mock.calls[0]?.[2], {
+    command: 'status',
+    statusCommandId: 'runner-command-1',
+  });
+  assert.equal(mockSendRunnerCommandOnce.mock.calls.length, 0);
+});
+
 test('runner session probes readiness before mutating commands', async () => {
   const session = makeRunnerSession({ ready: false });
   mockWaitForRunner.mockResolvedValueOnce(runnerResponse({ uptimeMs: 42 }));
@@ -151,9 +182,9 @@ test('runner session probes readiness before mutating commands', async () => {
   assert.deepEqual(result, { tapped: true });
   assert.equal(session.ready, true);
   assert.equal(mockWaitForRunner.mock.calls.length, 1);
-  assert.deepEqual(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
+  assertRunnerCommand(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
   assert.equal(mockSendRunnerCommandOnce.mock.calls.length, 1);
-  assert.deepEqual(mockSendRunnerCommandOnce.mock.calls[0]?.[2], {
+  assertRunnerCommand(mockSendRunnerCommandOnce.mock.calls[0]?.[2], {
     command: 'tap',
     x: 120,
     y: 240,
@@ -239,7 +270,7 @@ test('runner session keeps readiness preflight for tap commands when ready but n
 
   assert.deepEqual(result, { tapped: true });
   assert.equal(mockWaitForRunner.mock.calls.length, 1);
-  assert.deepEqual(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
+  assertRunnerCommand(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
   assert.equal(mockSendRunnerCommandOnce.mock.calls.length, 1);
 });
 
@@ -261,7 +292,7 @@ test('runner session keeps readiness preflight for tap commands when marked read
 
   assert.deepEqual(result, { tapped: true });
   assert.equal(mockWaitForRunner.mock.calls.length, 1);
-  assert.deepEqual(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
+  assertRunnerCommand(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
   assert.equal(mockSendRunnerCommandOnce.mock.calls.length, 1);
 });
 
@@ -280,7 +311,7 @@ test('runner session keeps readiness preflight for non-tap mutating commands whe
 
   assert.deepEqual(result, { pressed: true });
   assert.equal(mockWaitForRunner.mock.calls.length, 1);
-  assert.deepEqual(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
+  assertRunnerCommand(mockWaitForRunner.mock.calls[0]?.[2], { command: 'uptime' });
   assert.equal(mockSendRunnerCommandOnce.mock.calls.length, 1);
 });
 
@@ -371,7 +402,7 @@ test('runner session stop sends shutdown, cleans temporary runner files, and rel
   mockIsProcessAlive.mockReturnValue(false);
   await stopRunnerSession(session);
 
-  assert.deepEqual(mockWaitForRunner.mock.calls.at(-1)?.[2], { command: 'shutdown' });
+  assertRunnerCommand(mockWaitForRunner.mock.calls.at(-1)?.[2], { command: 'shutdown' });
   assert.deepEqual(mockCleanupTempFile.mock.calls, [
     ['/tmp/session-runner.xctestrun'],
     ['/tmp/session-runner.json'],
@@ -453,3 +484,18 @@ function runnerResponse(data: Record<string, unknown>): Response {
 function runnerError(error: { code: string; message: string }): Response {
   return new Response(JSON.stringify({ ok: false, error }));
 }
+
+function assertRunnerCommand(
+  actual: unknown,
+  expected: Record<string, unknown>,
+): asserts actual is Record<string, unknown> {
+  assert.equal(typeof actual, 'object');
+  assert.notEqual(actual, null);
+  const command = actual as Record<string, unknown>;
+  const commandId = command.commandId;
+  if (typeof commandId !== 'string') {
+    assert.fail('expected runner commandId');
+  }
+  assert.match(commandId, /^runner-/);
+  assert.deepEqual({ ...command, commandId: undefined }, { ...expected, commandId: undefined });
+}