agent-device 0.14.8 → 0.15.0

package/dist/src/remote-config.d.ts

@@ -1,4 +1,20 @@
-export declare type RemoteConfigProfile = {
+declare type RemoteConfigMetroOptions = {
+    metroProjectRoot?: string;
+    metroKind?: 'auto' | 'react-native' | 'expo';
+    metroPublicBaseUrl?: string;
+    metroProxyBaseUrl?: string;
+    metroBearerToken?: string;
+    metroPreparePort?: number;
+    metroListenHost?: string;
+    metroStatusHost?: string;
+    metroStartupTimeoutMs?: number;
+    metroProbeTimeoutMs?: number;
+    metroRuntimeFile?: string;
+    metroNoReuseExisting?: boolean;
+    metroNoInstallDeps?: boolean;
+};
+
+export declare type RemoteConfigProfile = RemoteConfigMetroOptions & {
     stateDir?: string;
     daemonBaseUrl?: string;
     daemonAuthToken?: string;
@@ -17,19 +33,6 @@ export declare type RemoteConfigProfile = {
     iosSimulatorDeviceSet?: string;
     androidDeviceAllowlist?: string;
     session?: string;
-    metroProjectRoot?: string;
-    metroKind?: 'auto' | 'react-native' | 'expo';
-    metroPublicBaseUrl?: string;
-    metroProxyBaseUrl?: string;
-    metroBearerToken?: string;
-    metroPreparePort?: number;
-    metroListenHost?: string;
-    metroStatusHost?: string;
-    metroStartupTimeoutMs?: number;
-    metroProbeTimeoutMs?: number;
-    metroRuntimeFile?: string;
-    metroNoReuseExisting?: boolean;
-    metroNoInstallDeps?: boolean;
 };
 
 export declare type RemoteConfigProfileOptions = {

package/dist/src/selectors.d.ts

@@ -35,6 +35,7 @@ declare type RawSnapshotNode = {
     rect?: Rect;
     enabled?: boolean;
     selected?: boolean;
+    focused?: boolean;
     hittable?: boolean;
     depth?: number;
     parentIndex?: number;
@@ -45,6 +46,7 @@ declare type RawSnapshotNode = {
     surface?: string;
     hiddenContentAbove?: boolean;
     hiddenContentBelow?: boolean;
+    presentationHints?: string[];
 };
 
 declare type Rect = {
@@ -103,6 +105,7 @@ declare type SnapshotState = {
     truncated?: boolean;
     backend?: SnapshotBackend;
     comparisonSafe?: boolean;
+    presentationKey?: string;
 };
 
 export declare function tryParseSelectorChain(expression: string): SelectorChain | null;

package/dist/src/server.js

@@ -1,20 +1,2 @@
-import{buildCommandUsageText as e,buildUsageText as t}from"./command-schema.js";import{readVersion as r}from"./9671.js";let n="agent-device",o=["workflow","debugging","react-devtools","remote","macos","dogfood"];function i(e={}){let t=!1===e.global?"npx -y agent-device mcp":"agent-device mcp",r=!1===e.global?"No global install required.":"npm install -g agent-device",n=e.client?`
-Client hint: ${e.client}`:"";return`${r}
-
-MCP server command:
-  ${t}
-
-Generic MCP JSON:
-  {
-    "mcpServers": {
-      "agent-device": {
-        "command": "${!1===e.global?"npx":"agent-device"}",
-        "args": ${JSON.stringify(!1===e.global?["-y","agent-device","mcp"]:["mcp"])}
-      }
-    }
-  }
-
-Use this server for discovery and routing only. For device actions, call the CLI commands returned by the help tool, starting with:
-  agent-device help workflow${n}
-`}function a(r={}){if(r.topic&&r.command)throw Error("Provide either topic or command, not both.");let n=r.topic??r.command;if(!n)return t();if(r.topic&&!d(r.topic))throw Error(`Unknown help topic: ${r.topic}. Expected one of: ${o.join(", ")}`);let i=e(n);if(!i)throw Error(`Unknown command or help topic: ${n}`);return i}function s(){return[{uri:"agent-device://install",name:"agent-device MCP install",description:"Install and client configuration snippets.",mimeType:"text/markdown"},{uri:"agent-device://help",name:"agent-device command list",description:"Version-matched command list and global flags.",mimeType:"text/plain"},...o.map(e=>({uri:`agent-device://help/${e}`,name:`agent-device help ${e}`,description:`Version-matched ${e} workflow guidance.`,mimeType:"text/plain"}))]}function c(){return[l("agent-device-workflow","Plan a normal app automation loop."),l("agent-device-debugging","Collect focused debugging evidence."),l("agent-device-dogfood","Run exploratory QA with reproducible evidence."),l("agent-device-react-native-performance","Inspect React Native renders."),l("agent-device-macos","Inspect a macOS app or surface.")]}function l(e,t){return{name:e,description:t,arguments:[{name:"target",description:"Optional app, device, or task target.",required:!1}]}}function d(e){return o.includes(e)}function p(e){if("2.0"!==e.jsonrpc||"string"!=typeof e.method)return g(e.id??null,-32600,"Invalid JSON-RPC request.");if(void 0===e.id)return null;try{var l,p;return l=e.id,p=function(e,l){switch(e){case"initialize":return{protocolVersion:"2025-11-25",capabilities:{tools:{},resources:{},prompts:{}},serverInfo:{name:n,version:r()}};case"ping":return{};case"tools/list":return{tools:[{name:"status",description:"Report the installed agent-device MCP router and CLI metadata.",inputSchema:{type:"object",properties:{},additionalProperties:!1}},{name:"install",description:"Return install and MCP client configuration snippets for agent-device.",inputSchema:{type:"object",properties:{client:{type:"string",description:"Optional client name for labeling the returned guidance."},global:{type:"boolean",description:"Use a global agent-device binary when true; use npx when false."}},additionalProperties:!1}},{name:"help",description:"Return version-matched CLI help for a workflow topic or command.",inputSchema:{type:"object",properties:{topic:{type:"string",enum:o,description:"Agent workflow topic."},command:{type:"string",description:"CLI command name such as snapshot, open, logs, or react-devtools."}},additionalProperties:!1}}]};case"tools/call":var p,g,w,y=l;let b=m(y),$=h(b,"name"),k=f(b.arguments);try{if("status"===$)return u(JSON.stringify({name:n,registryName:"io.github.callstackincubator/agent-device",version:r(),transport:"stdio",command:"agent-device mcp",node:process.version,capabilities:{tools:["status","install","help"],resources:s().map(e=>e.uri),prompts:c().map(e=>e.name)},note:"This MCP server routes agents to the agent-device CLI. It does not expose device automation or shell execution tools."},null,2));if("install"===$)return u(i(k));if("help"===$)return u(a(k));throw Error(`Unknown tool: ${$}`)}catch(e){return u(e instanceof Error?e.message:String(e),!0)}return;case"resources/list":return{resources:s()};case"resources/read":let x;return p=l,{contents:[{uri:x=h(m(p),"uri"),mimeType:"agent-device://install"===x?"text/markdown":"text/plain",text:function(e){if("agent-device://install"===e)return i();if("agent-device://help"===e)return t();let r=e.startsWith("agent-device://help/")?e.slice(20):"";if(d(r))return a({topic:r});throw Error(`Unknown resource: ${e}`)}(x)}]};case"prompts/list":return{prompts:c()};case"prompts/get":let C;return g=l,C=m(g),function(e,t={}){let r={"agent-device-workflow":"workflow","agent-device-debugging":"debugging","agent-device-dogfood":"dogfood","agent-device-react-native-performance":"react-devtools","agent-device-macos":"macos"}[e];if(!r)throw Error(`Unknown prompt: ${e}`);let n=t.target?` Target: ${t.target}.`:"";return{description:`Use agent-device help ${r} before planning commands.${n}`,messages:[{role:"user",content:{type:"text",text:`Read the agent-device ${r} guidance through the MCP help tool, then produce a concise command plan using agent-device CLI commands only.${n}`}}]}}(h(C,"name"),(w=C.arguments,Object.fromEntries(Object.entries(f(w)).filter(e=>"string"==typeof e[1]))));default:throw new v(`Unsupported MCP method: ${e}`)}}(e.method,e.params),{jsonrpc:"2.0",id:l,result:p}}catch(t){if(t instanceof v)return g(e.id,-32601,t.message);return g(e.id,-32602,t instanceof Error?t.message:String(t))}}function u(e,t=!1){return{isError:t,content:[{type:"text",text:e}]}}function g(e,t,r){return{jsonrpc:"2.0",id:e,error:{code:t,message:r}}}function m(e){if(!e||"object"!=typeof e||Array.isArray(e))throw Error("Expected object parameters.");return e}function f(e){return void 0===e?{}:m(e)}function h(e,t){let r=e[t];if("string"!=typeof r||0===r.length)throw Error(`Expected ${t} to be a non-empty string.`);return r}class v extends Error{}async function w(){let e=new y(e=>{let t=function(e){if(Array.isArray(e)){let t=e.flatMap(e=>{var t;return(t=p(e))?[t]:[]});return t.length>0?t:null}return p(e)}(e);t&&b(t)});process.stdin.setEncoding("utf8"),process.stdin.on("data",t=>{try{e.push(t)}catch(e){b({jsonrpc:"2.0",id:null,error:{code:-32700,message:e instanceof Error?e.message:String(e)}})}}),await new Promise(e=>{process.stdin.on("end",e),process.stdin.on("close",e),process.stdin.resume()})}class y{buffer="";sink;constructor(e){this.sink=e}push(e){for(this.buffer+=e;;){let e=this.tryReadLineMessage();if(void 0!==e){this.emit(e);continue}break}}tryReadLineMessage(){let e=this.buffer.indexOf("\n");if(-1===e)return;let t=this.buffer.slice(0,e).trim();return this.buffer=this.buffer.slice(e+1),t.length>0?t:void 0}emit(e){let t=JSON.parse(e);Array.isArray(t),this.sink(t)}}function b(e){process.stdout.write(`${JSON.stringify(e)}
-`)}export{w as runAgentDeviceMcpServer};
+import{readVersion as e}from"./9671.js";function t(t){if("2.0"!==t.jsonrpc||"string"!=typeof t.method)return r(t.id??null,-32600,"Invalid JSON-RPC request.");if(void 0===t.id)return null;try{var i,s;return i=t.id,s=function(t,r){switch(t){case"initialize":return{protocolVersion:"2025-11-25",capabilities:{tools:{}},serverInfo:{name:"agent-device",version:e()}};case"ping":return{};case"tools/list":return{tools:[{name:"status",description:"Return discovery-only handoff metadata for installing, verifying, and using the agent-device CLI.",inputSchema:{type:"object",properties:{},additionalProperties:!1},outputSchema:{type:"object",properties:{packageName:{type:"string"},installedPackageVersion:{type:"string"},cliCommandName:{type:"string"},installCommand:{type:"string"},verifyCommand:{type:"string"},startingHelpCommand:{type:"string"},supportedTargets:{type:"array",items:{type:"string"}},capabilities:{type:"array",items:{type:"string"}},prerequisites:{type:"array",items:{type:"string"}},docsUrl:{type:"string"},agentDocsUrl:{type:"string"},firstCommands:{type:"array",items:{type:"string"}},automationInterface:{type:"string",const:"cli"},automationNote:{type:"string"},installRequiresHumanApproval:{type:"boolean",const:!0},installSafetyNote:{type:"string"}},required:["packageName","installedPackageVersion","cliCommandName","installCommand","verifyCommand","startingHelpCommand","supportedTargets","capabilities","prerequisites","docsUrl","agentDocsUrl","firstCommands","automationInterface","automationNote","installRequiresHumanApproval","installSafetyNote"],additionalProperties:!1}}]};case"tools/call":var i=r;let s=function(e,t){let r=e[t];if("string"!=typeof r||0===r.length)throw Error(`Expected ${t} to be a non-empty string.`);return r}(function(e){if(!e||"object"!=typeof e||Array.isArray(e))throw Error("Expected object parameters.");return e}(i),"name");try{if("status"===s){let t;return t={packageName:"agent-device",installedPackageVersion:e(),cliCommandName:"agent-device",installCommand:"npm install -g agent-device@latest",verifyCommand:"agent-device --version",startingHelpCommand:"agent-device help workflow",supportedTargets:["ios-simulator","android-emulator","ios-device","android-device","tvos-simulator","macos","linux"],capabilities:["inspect-ui","interact-with-elements","open-apps","install-app","capture-screenshot","accessibility-snapshot","collect-logs","collect-network","collect-performance","record-replay","react-native","expo","android-adb","ios-xcuitest"],prerequisites:["node>=22","xcode-for-ios","android-sdk-adb-for-android","macos-accessibility-permission-for-desktop"],docsUrl:"https://agent-device.dev/",agentDocsUrl:"https://incubator.callstack.com/agent-device/llms-full.txt",firstCommands:["agent-device help workflow","agent-device apps --platform ios","agent-device apps --platform android"],automationInterface:"cli",automationNote:"Device automation happens through the agent-device CLI. This MCP server is discovery-only and does not expose device automation tools.",installRequiresHumanApproval:!0,installSafetyNote:"Agents should not install or update the package unless the human has approved the environment change. If the CLI is missing, ask the human to run the install command, then run the verify command."},{isError:!1,structuredContent:t,content:[{type:"text",text:JSON.stringify(t,null,2)}]}}throw Error(`Unknown tool: ${s}`)}catch(e){return function(e,t=!1){return{isError:t,content:[{type:"text",text:e}]}}(e instanceof Error?e.message:String(e),!0)}return;default:throw new n(`Unsupported MCP method: ${t}`)}}(t.method,t.params),{jsonrpc:"2.0",id:i,result:s}}catch(e){if(e instanceof n)return r(t.id,-32601,e.message);return r(t.id,-32602,e instanceof Error?e.message:String(e))}}function r(e,t,r){return{jsonrpc:"2.0",id:e,error:{code:t,message:r}}}class n extends Error{}async function i(){let e=new s(e=>{let r=function(e){if(Array.isArray(e)){let r=e.flatMap(e=>{var r;return(r=t(e))?[r]:[]});return r.length>0?r:null}return t(e)}(e);r&&a(r)});process.stdin.setEncoding("utf8"),process.stdin.on("data",t=>{try{e.push(t)}catch(e){a({jsonrpc:"2.0",id:null,error:{code:-32700,message:e instanceof Error?e.message:String(e)}})}}),await new Promise(e=>{process.stdin.on("end",e),process.stdin.on("close",e),process.stdin.resume()})}class s{buffer="";sink;constructor(e){this.sink=e}push(e){for(this.buffer+=e;;){let e=this.tryReadLineMessage();if(void 0!==e){this.emit(e);continue}break}}tryReadLineMessage(){let e=this.buffer.indexOf("\n");if(-1===e)return;let t=this.buffer.slice(0,e).trim();return this.buffer=this.buffer.slice(e+1),t.length>0?t:void 0}emit(e){let t=JSON.parse(e);Array.isArray(t),this.sink(t)}}function a(e){process.stdout.write(`${JSON.stringify(e)}
+`)}export{i as runAgentDeviceMcpServer};

package/ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj/xcshareddata/xcschemes/AgentDeviceRunner.xcscheme

@@ -28,7 +28,13 @@
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
       shouldUseLaunchSchemeArgsEnv = "YES"
-      shouldAutocreateTestPlan = "YES">
+      shouldAutocreateTestPlan = "NO">
+      <TestPlans>
+         <TestPlanReference
+            reference = "container:AgentDeviceRunnerUITests.xctestplan"
+            default = "YES">
+         </TestPlanReference>
+      </TestPlans>
       <Testables>
          <TestableReference
             skipped = "NO"

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

@@ -13,6 +13,18 @@ extension RunnerTests {
     return (gestureStartUptimeMs, currentUptimeMs())
   }
 
+  private func unsupportedResponse(for outcome: RunnerInteractionOutcome) -> Response? {
+    switch outcome {
+    case .performed:
+      return nil
+    case .unsupported(let message):
+      return Response(
+        ok: false,
+        error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message)
+      )
+    }
+  }
+
   func execute(command: Command) throws -> Response {
     if Thread.isMainThread {
       return try executeOnMainSafely(command: command)
@@ -128,11 +140,16 @@ extension RunnerTests {
       if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
         activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
       } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
-        app.activate()
+        ensureRunnerHostAppActive(reason: "missing_app_bundle")
         activeApp = app
       }
 
-      if !activeApp.waitForExistence(timeout: appExistenceTimeout) {
+      let skipExistenceWait = canUseFastForegroundAppGuard(
+        activeApp: activeApp,
+        requestedBundleId: requestedBundleId,
+        command: command.command
+      )
+      if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
         if let bundleId = requestedBundleId {
           activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
           guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
@@ -147,10 +164,15 @@ extension RunnerTests {
         if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
           activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
         } else if requestedBundleId == nil, activeApp.state != .runningForeground {
-          app.activate()
+          ensureRunnerHostAppActive(reason: "interaction_missing_app_bundle")
           activeApp = app
         }
-        if !activeApp.waitForExistence(timeout: 2) {
+        let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
+          activeApp: activeApp,
+          requestedBundleId: requestedBundleId,
+          command: command.command
+        )
+        if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
           if let bundleId = requestedBundleId {
             return Response(ok: false, error: ErrorPayload(message: "app '\(bundleId)' is not available"))
           }
@@ -229,13 +251,51 @@ extension RunnerTests {
         data: DataPayload(currentUptimeMs: currentUptimeMs())
       )
     case .tap:
+      if let selectorKey = command.selectorKey, let selectorValue = command.selectorValue {
+        let match = findElement(app: activeApp, selectorKey: selectorKey, selectorValue: selectorValue)
+        if match.isAmbiguous {
+          return Response(ok: false, error: ErrorPayload(code: "AMBIGUOUS_MATCH", message: "selector matched multiple elements"))
+        }
+        if let element = match.element {
+          let frame = element.frame
+          let touchFrame = frame.isEmpty
+            ? nil
+            : resolvedTouchVisualizationFrame(app: activeApp, x: frame.midX, y: frame.midY)
+          var outcome = RunnerInteractionOutcome.performed
+          let timing = measureGesture {
+            withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+              outcome = activateElement(app: activeApp, element: element, action: "tap by selector")
+            }
+          }
+          if let response = unsupportedResponse(for: outcome) {
+            return response
+          }
+          return Response(
+            ok: true,
+            data: DataPayload(
+              message: "tapped",
+              gestureStartUptimeMs: timing.gestureStartUptimeMs,
+              gestureEndUptimeMs: timing.gestureEndUptimeMs,
+              x: touchFrame?.x,
+              y: touchFrame?.y,
+              referenceWidth: touchFrame?.referenceWidth,
+              referenceHeight: touchFrame?.referenceHeight
+            )
+          )
+        }
+        return Response(ok: false, error: ErrorPayload(code: "ELEMENT_NOT_FOUND", message: "element not found"))
+      }
       if let text = command.text {
         if let element = findElement(app: activeApp, text: text) {
+          var outcome = RunnerInteractionOutcome.performed
           let timing = measureGesture {
             withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-              element.tap()
+              outcome = activateElement(app: activeApp, element: element, action: "tap by text")
             }
           }
+          if let response = unsupportedResponse(for: outcome) {
+            return response
+          }
           return Response(
             ok: true,
             data: DataPayload(
@@ -249,11 +309,15 @@ extension RunnerTests {
       }
       if let x = command.x, let y = command.y {
         let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
+        var outcome = RunnerInteractionOutcome.performed
         let timing = measureGesture {
           withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-            tapAt(app: activeApp, x: x, y: y)
+            outcome = tapAt(app: activeApp, x: x, y: y)
           }
         }
+        if let response = unsupportedResponse(for: outcome) {
+          return response
+        }
         return Response(
           ok: true,
           data: DataPayload(
@@ -309,13 +373,19 @@ extension RunnerTests {
       let doubleTap = command.doubleTap ?? false
       let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
       if doubleTap {
+        var outcome = RunnerInteractionOutcome.performed
         let timing = measureGesture {
           withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
             runSeries(count: count, pauseMs: intervalMs) { _ in
-              doubleTapAt(app: activeApp, x: x, y: y)
+              if case .performed = outcome {
+                outcome = doubleTapAt(app: activeApp, x: x, y: y)
+              }
             }
           }
         }
+        if let response = unsupportedResponse(for: outcome) {
+          return response
+        }
         return Response(
           ok: true,
           data: DataPayload(
@@ -329,13 +399,19 @@ extension RunnerTests {
           )
         )
       }
+      var outcome = RunnerInteractionOutcome.performed
       let timing = measureGesture {
         withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
           runSeries(count: count, pauseMs: intervalMs) { _ in
-            tapAt(app: activeApp, x: x, y: y)
+            if case .performed = outcome {
+              outcome = tapAt(app: activeApp, x: x, y: y)
+            }
           }
         }
       }
+      if let response = unsupportedResponse(for: outcome) {
+        return response
+      }
       return Response(
         ok: true,
         data: DataPayload(
@@ -354,11 +430,15 @@ extension RunnerTests {
       }
       let duration = (command.durationMs ?? 800) / 1000.0
       let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
+      var outcome = RunnerInteractionOutcome.performed
       let timing = measureGesture {
         withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-          longPressAt(app: activeApp, x: x, y: y, duration: duration)
+          outcome = longPressAt(app: activeApp, x: x, y: y, duration: duration)
         }
       }
+      if let response = unsupportedResponse(for: outcome) {
+        return response
+      }
       return Response(
         ok: true,
         data: DataPayload(
@@ -376,12 +456,30 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
       }
       let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
-      let dragFrame = resolvedDragVisualizationFrame(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+      let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+      let dragFrame = resolvedDragVisualizationFrame(
+        app: activeApp,
+        x: dragPoints.x,
+        y: dragPoints.y,
+        x2: dragPoints.x2,
+        y2: dragPoints.y2
+      )
+      var outcome = RunnerInteractionOutcome.performed
       let timing = measureGesture {
         withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
-          dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+          outcome = dragAt(
+            app: activeApp,
+            x: dragPoints.x,
+            y: dragPoints.y,
+            x2: dragPoints.x2,
+            y2: dragPoints.y2,
+            holdDuration: holdDuration
+          )
         }
       }
+      if let response = unsupportedResponse(for: outcome) {
+        return response
+      }
       return Response(
         ok: true,
         data: DataPayload(
@@ -407,18 +505,40 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "dragSeries pattern must be one-way or ping-pong"))
       }
       let holdDuration = min(max((command.durationMs ?? 60) / 1000.0, 0.016), 10.0)
+      let dragPoints = keyboardAvoidingDragPoints(app: activeApp, x: x, y: y, x2: x2, y2: y2)
+      var outcome = RunnerInteractionOutcome.performed
       let timing = measureGesture {
         withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
           runSeries(count: count, pauseMs: pauseMs) { idx in
+            guard case .performed = outcome else {
+              return
+            }
             let reverse = pattern == "ping-pong" && (idx % 2 == 1)
             if reverse {
-              dragAt(app: activeApp, x: x2, y: y2, x2: x, y2: y, holdDuration: holdDuration)
+              outcome = dragAt(
+                app: activeApp,
+                x: dragPoints.x2,
+                y: dragPoints.y2,
+                x2: dragPoints.x,
+                y2: dragPoints.y,
+                holdDuration: holdDuration
+              )
             } else {
-              dragAt(app: activeApp, x: x, y: y, x2: x2, y2: y2, holdDuration: holdDuration)
+              outcome = dragAt(
+                app: activeApp,
+                x: dragPoints.x,
+                y: dragPoints.y,
+                x2: dragPoints.x2,
+                y2: dragPoints.y2,
+                holdDuration: holdDuration
+              )
             }
           }
         }
       }
+      if let response = unsupportedResponse(for: outcome) {
+        return response
+      }
       return Response(
         ok: true,
         data: DataPayload(
@@ -427,46 +547,24 @@ extension RunnerTests {
           gestureEndUptimeMs: timing.gestureEndUptimeMs
         )
       )
-    case .type:
-      guard let text = command.text else {
-        return Response(ok: false, error: ErrorPayload(message: "type requires text"))
+    case .remotePress:
+      guard let button = tvRemoteButton(from: command.remoteButton) else {
+        return Response(ok: false, error: ErrorPayload(message: "remotePress requires remoteButton"))
       }
-      let delaySeconds = Double(max(command.delayMs ?? 0, 0)) / 1000.0
-      let target: XCUIElement?
-      if let x = command.x, let y = command.y {
-        target = textInputAt(app: activeApp, x: x, y: y) ?? focusedTextInput(app: activeApp)
-      } else {
-        target = focusedTextInput(app: activeApp)
-      }
-      func typeIntoTarget(_ value: String) {
-        if let focused = target {
-          focused.typeText(value)
-        } else {
-          activeApp.typeText(value)
-        }
+      let duration = (command.durationMs ?? 0) / 1000.0
+      guard pressTvRemote(button, duration: duration) else {
+        return Response(
+          ok: false,
+          error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: "remotePress is only supported on tvOS")
+        )
       }
-      if command.clearFirst == true {
-        guard let focused = target else {
-          let message =
-            (command.x != nil && command.y != nil)
-            ? "no text input found at the provided coordinates to clear"
-            : "no focused text input to clear"
-          return Response(ok: false, error: ErrorPayload(message: message))
-        }
-        clearTextInput(focused)
-      }
-      if delaySeconds > 0 && text.count > 1 {
-        let chunks = Array(text)
-        for (index, character) in chunks.enumerated() {
-          typeIntoTarget(String(character))
-          if index + 1 < chunks.count {
-            Thread.sleep(forTimeInterval: delaySeconds)
-          }
-        }
-      } else {
-        typeIntoTarget(text)
+      return Response(ok: true, data: DataPayload(message: "remote pressed"))
+    case .type:
+      var response: Response?
+      withTemporaryScrollIdleTimeoutIfSupported(activeApp) {
+        response = executeTypeCommand(activeApp: activeApp, command: command)
       }
-      return Response(ok: true, data: DataPayload(message: "typed"))
+      return response ?? Response(ok: false, error: ErrorPayload(message: "type produced no response"))
     case .interactionFrame:
       let frame = resolvedTouchReferenceFrame(app: activeApp, appFrame: activeApp.frame)
       return Response(
@@ -514,6 +612,11 @@ extension RunnerTests {
       }
       let found = findElement(app: activeApp, text: text) != nil
       return Response(ok: true, data: DataPayload(found: found))
+    case .querySelector:
+      guard let selectorKey = command.selectorKey, let selectorValue = command.selectorValue else {
+        return Response(ok: false, error: ErrorPayload(message: "querySelector requires selectorKey and selectorValue"))
+      }
+      return queryElement(app: activeApp, selectorKey: selectorKey, selectorValue: selectorValue)
     case .readText:
       guard let x = command.x, let y = command.y else {
         return Response(ok: false, error: ErrorPayload(message: "readText requires x and y"))
@@ -545,7 +648,7 @@ extension RunnerTests {
         targetApp.activate()
         activeApp = targetApp
         // Brief wait for the app transition animation to complete
-        Thread.sleep(forTimeInterval: 0.5)
+        sleepFor(0.5)
       }
       if command.fullscreen == true {
         screenshot = XCUIScreen.main.screenshot()
@@ -633,13 +736,23 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "alert not found"))
       }
       if action == "accept" {
-        let button = alert.buttons.allElementsBoundByIndex.first
-        button?.tap()
+        guard let button = alert.buttons.allElementsBoundByIndex.first else {
+          return Response(ok: false, error: ErrorPayload(message: "alert accept button not found"))
+        }
+        let outcome = activateElement(app: activeApp, element: button, action: "alert accept")
+        if let response = unsupportedResponse(for: outcome) {
+          return response
+        }
         return Response(ok: true, data: DataPayload(message: "accepted"))
       }
       if action == "dismiss" {
-        let button = alert.buttons.allElementsBoundByIndex.last
-        button?.tap()
+        guard let button = alert.buttons.allElementsBoundByIndex.last else {
+          return Response(ok: false, error: ErrorPayload(message: "alert dismiss button not found"))
+        }
+        let outcome = activateElement(app: activeApp, element: button, action: "alert dismiss")
+        if let response = unsupportedResponse(for: outcome) {
+          return response
+        }
         return Response(ok: true, data: DataPayload(message: "dismissed"))
       }
       let buttonLabels = alert.buttons.allElementsBoundByIndex.map { $0.label }
@@ -648,8 +761,12 @@ extension RunnerTests {
       guard let scale = command.scale, scale > 0 else {
         return Response(ok: false, error: ErrorPayload(message: "pinch requires scale > 0"))
       }
+      var outcome = RunnerInteractionOutcome.performed
       let timing = measureGesture {
-        pinch(app: activeApp, scale: scale, x: command.x, y: command.y)
+        outcome = pinch(app: activeApp, scale: scale, x: command.x, y: command.y)
+      }
+      if let response = unsupportedResponse(for: outcome) {
+        return response
       }
       return Response(
         ok: true,
@@ -661,4 +778,41 @@ extension RunnerTests {
       )
     }
   }
+
+  private func executeTypeCommand(activeApp: XCUIApplication, command: Command) -> Response {
+    guard let text = command.text else {
+      return Response(ok: false, error: ErrorPayload(message: "type requires text"))
+    }
+    let delaySeconds = Double(max(command.delayMs ?? 0, 0)) / 1000.0
+    let textEntryMode = resolveTextEntryMode(command)
+    let target = focusTextInputForTextEntry(app: activeApp, x: command.x, y: command.y)
+    if textEntryMode == .replacement {
+      guard target.element != nil else {
+        let message =
+          (command.x != nil && command.y != nil)
+          ? "no text input found at the provided coordinates to clear"
+          : "no focused text input to clear"
+        return Response(ok: false, error: ErrorPayload(message: message))
+      }
+    }
+    let textResult = typeTextReliably(
+      app: activeApp,
+      target: target,
+      text: text,
+      delaySeconds: delaySeconds,
+      repairMode: textEntryMode
+    )
+    if textResult.verified == false {
+      let expected = textResult.expectedText ?? ""
+      let observed = textResult.observedText ?? ""
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "TEXT_ENTRY_MISMATCH",
+          message: "text entry verification failed: expected \"\(expected)\", observed \"\(observed)\""
+        )
+      )
+    }
+    return Response(ok: true, data: DataPayload(message: textResult.repaired ? "typed after repair" : "typed"))
+  }
 }