@swmansion/argent 0.17.1-next.2 → 0.17.1-next.4

package/dist/tool-server.cjs

@@ -116365,6 +116365,15 @@ async function withDeadline(p, fallback, label) {
 var zodSchema = external_exports.object({});
 var listDevicesTool = {
   id: "list-devices",
+  interaction: {
+    startedMsg: () => "Listing devices",
+    completedMsg: ({ result }) => {
+      const deviceLabel = result.devices.length === 1 ? "device" : "devices";
+      const avdLabel = result.avds.length === 1 ? "AVD" : "AVDs";
+      return `Listed ${result.devices.length} ${deviceLabel} and ${result.avds.length} ${avdLabel}`;
+    },
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to list devices: ${failureSignal2.error_code}`
+  },
   description: `List iOS simulators, Android emulators, connected physical Android devices, running Chromium apps, and Vega (Fire TV) devices in one place.
 Use at the start of a session to pick a target id ('udid' for iOS entries, 'serial' for Android/Vega entries, 'id' for Chromium) to pass to interaction tools, and to see which targets are already running.
 Returns { devices, avds } where each device carries a 'platform' discriminator ('ios', 'android', 'chromium', or 'vega'); 'avds' lists Android AVDs bootable via boot-device. A Vega VVD is listed under 'devices' whether running or stopped (state 'running'/'stopped'); start a stopped one with boot-device using its 'vvdImage'.
@@ -121817,6 +121826,11 @@ var zodSchema2 = external_exports.object({
 });
 var nativeDevtoolsStatusTool = {
   id: "native-devtools-status",
+  interaction: {
+    startedMsg: ({ params }) => `Checking native inspection for ${params.bundleId}`,
+    completedMsg: ({ params }) => `Checked native inspection for ${params.bundleId}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to check native inspection for ${params.bundleId}: ${failureSignal2.error_code}`
+  },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   // The "injectable is false" recovery sentence inlines NON_INJECTABLE_RECOVERY
   // verbatim: the description must stay a plain literal so scripts/extract-tools.mjs
@@ -121895,6 +121909,11 @@ var zodSchema3 = external_exports.object({
 });
 var nativeNetworkLogsTool = {
   id: "native-network-logs",
+  interaction: {
+    startedMsg: ({ params }) => `Reading native network activity for ${params.bundleId}`,
+    completedMsg: ({ params }) => `Read native network activity for ${params.bundleId}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to read native network activity for ${params.bundleId}: ${failureSignal2.error_code}`
+  },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   description: `Retrieve network requests captured at the native NSURLProtocol level. 
 Unlike the JS-level network inspector (view-network-logs), this captures ALL network traffic from the app including native modules, Swift/Objective-C networking, and background transfers that bypass JS fetch. 
@@ -121937,6 +121956,14 @@ var zodSchema4 = external_exports.object({
 });
 var nativeFindViewsTool = {
   id: "native-find-views",
+  interaction: {
+    startedMsg: ({ params }) => `Searching native views in ${params.bundleId}`,
+    completedMsg: ({ params, result }) => {
+      const count = result.status === "ok" ? result.matches.length : 0;
+      return `Found ${count} native ${count === 1 ? "view" : "views"} in ${params.bundleId}`;
+    },
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to search native views in ${params.bundleId}: ${failureSignal2.error_code}`
+  },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   description: `Search for specific UIViews in the running app by class name, accessibility identifier, label, tag, or React Native nativeID.
 Use when you need to locate a specific view by its properties without dumping the entire hierarchy.
@@ -121999,6 +122026,11 @@ var zodSchema5 = external_exports.object({
 });
 var nativeFullHierarchyTool = {
   id: "native-full-hierarchy",
+  interaction: {
+    startedMsg: ({ params }) => `Reading native view hierarchy for ${params.bundleId}`,
+    completedMsg: ({ params }) => `Read native view hierarchy for ${params.bundleId}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to read native view hierarchy for ${params.bundleId}: ${failureSignal2.error_code}`
+  },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   description: `Get the complete UIKit view tree for the running app.
 WARNING: Output can be extremely large (100KB\u2013500KB+) for complex apps, especially those built with SwiftUI. Prefer native-find-views for targeted queries.
@@ -122046,6 +122078,11 @@ var zodSchema6 = external_exports.object({
 });
 var nativeDescribeScreenTool = {
   id: "native-describe-screen",
+  interaction: {
+    startedMsg: ({ params }) => `Reading native screen for ${params.bundleId}`,
+    completedMsg: ({ params }) => `Read native screen for ${params.bundleId}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to read native screen for ${params.bundleId}: ${failureSignal2.error_code}`
+  },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   description: `Read the running app's native accessibility screen description via injected native devtools.
 
@@ -122116,6 +122153,11 @@ var zodSchema7 = external_exports.object({
 });
 var nativeViewAtPointTool = {
   id: "native-view-at-point",
+  interaction: {
+    startedMsg: ({ params }) => `Inspecting native view at (${params.x}, ${params.y})`,
+    completedMsg: ({ params }) => `Inspected native view at (${params.x}, ${params.y})`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to inspect native view at (${params.x}, ${params.y}): ${failureSignal2.error_code}`
+  },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   description: `Inspect the deepest visible UIView at a raw native window point.
 
@@ -122187,6 +122229,11 @@ var zodSchema8 = external_exports.object({
 });
 var nativeUserInteractableViewAtPointTool = {
   id: "native-user-interactable-view-at-point",
+  interaction: {
+    startedMsg: ({ params }) => `Finding interactive view at (${params.x}, ${params.y})`,
+    completedMsg: ({ params }) => `Found interactive view at (${params.x}, ${params.y})`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to find interactive view at (${params.x}, ${params.y}): ${failureSignal2.error_code}`
+  },
   capability: { apple: { simulator: true, device: true }, appleRemote: { simulator: true } },
   description: `Inspect the deepest UIView at a raw native window point that would actually receive touch input.
 
@@ -124235,6 +124282,9 @@ var zodSchema9 = external_exports.object({
     "Electron-only: extra CLI arguments forwarded to the Electron binary after the app path."
   )
 });
+function bootTarget(params) {
+  return params.udid ?? params.avdName ?? params.vvdImage ?? params.electronAppPath ?? "device";
+}
 var LAUNCH_HARDENING_ARGS = [
   "-noaudio",
   "-no-boot-anim",
@@ -124969,6 +125019,11 @@ var capability = {
 function createBootDeviceTool(registry2) {
   return {
     id: "boot-device",
+    interaction: {
+      startedMsg: ({ params }) => `Starting ${bootTarget(params)}`,
+      completedMsg: ({ params }) => `Started ${bootTarget(params)}`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to start ${bootTarget(params)}: ${failureSignal2.error_code}`
+    },
     description: `Start an iOS simulator, launch an Android emulator, start a Vega (Fire TV) Virtual Device, or spawn an Electron app and wait until it is ready to accept interactions.
 Pick the platform by which argument you pass: 'udid' for an iOS simulator from list-devices, 'avdName' for an Android AVD (a serial is assigned automatically), 'vvdImage' for a Vega VVD (the 'vvdImage' of a vega device from list-devices, e.g. 'tv'), or 'electronAppPath' for an Electron app (a CDP remote-debugging port is picked automatically, or pass 'electronPort' to fix one).
 Use at the start of a session once you have picked a target.
@@ -125293,6 +125348,11 @@ var capability2 = {
 function createLaunchAppTool(registry2) {
   return {
     id: "launch-app",
+    interaction: {
+      startedMsg: ({ params }) => `Launching ${params.bundleId}`,
+      completedMsg: ({ params }) => `Launched ${params.bundleId}`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to launch ${params.bundleId}: ${failureSignal2.error_code}`
+    },
     description: `Open an app by its bundle id (iOS) or package name (Android), or confirm the running renderer (Chromium).
 Use when starting any app \u2014 prefer this over tapping home-screen / launcher icons. Also prepares the native-devtools injection before the app starts (the iOS slice on iOS, the tvOS slice on Apple TV); on tvOS, interaction is focus-driven \u2014 use the tv-* tools rather than coordinate taps.
 Returns { launched, bundleId }. Fails if the app is not installed on the target device (iOS / Android).
@@ -125478,6 +125538,11 @@ var capability3 = {
 function createRestartAppTool(registry2) {
   return {
     id: "restart-app",
+    interaction: {
+      startedMsg: ({ params }) => `Restarting ${params.bundleId}`,
+      completedMsg: ({ params }) => `Restarted ${params.bundleId}`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to restart ${params.bundleId}: ${failureSignal2.error_code}`
+    },
     description: `Terminate then relaunch an app by bundle id / package name.
 Use when you need a clean in-memory state without a full reinstall. Also refreshes the native-devtools injection before the relaunch (the iOS slice on iOS, the tvOS slice on Apple TV); on tvOS, interaction is focus-driven \u2014 use the tv-* tools rather than coordinate taps.
 Returns { restarted, bundleId }. Fails if the app is not installed.`,
@@ -125639,6 +125704,11 @@ var capability4 = {
 };
 var reinstallAppTool = {
   id: "reinstall-app",
+  interaction: {
+    startedMsg: ({ params }) => `Reinstalling ${params.bundleId}`,
+    completedMsg: ({ params }) => `Reinstalled ${params.bundleId}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to reinstall ${params.bundleId}: ${failureSignal2.error_code}`
+  },
   description: `Install or reinstall an app on the device. The previous installation (if any) is uninstalled first so app data and runtime permissions are cleared.
 Use for a full reinstall after rebuilding, or to start from a clean app state.
 Returns { reinstalled, bundleId }. Fails if the app path does not exist or the package does not match the platform (.app for iOS, .apk for Android, .vpkg for Vega).`,
@@ -125947,6 +126017,11 @@ var zodSchema13 = external_exports.object({
     "App to change the permission for \u2014 required for every action. iOS: bundle id (e.g. com.example.app). Android: package name. `reset` is per-app too: simctl's device-wide reset (no bundleId) silently leaves existing per-app grants untouched on recent iOS, so the permission is always reset for this one app."
   )
 });
+var permissionAction = {
+  grant: { started: "Granting", completed: "Granted" },
+  deny: { started: "Denying", completed: "Denied" },
+  reset: { started: "Resetting", completed: "Reset" }
+};
 var capability5 = {
   // `simctl privacy` edits the simulator's TCC store — physical iPhones have no
   // equivalent host-side switch, so no `device: true` on apple.
@@ -125959,6 +126034,11 @@ var capability5 = {
 };
 var settingsPermissionsTool = {
   id: "settings-permissions",
+  interaction: {
+    startedMsg: ({ params }) => `${permissionAction[params.action].started} ${params.permission} permission for ${params.bundleId}`,
+    completedMsg: ({ params }) => `${permissionAction[params.action].completed} ${params.permission} permission for ${params.bundleId}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to ${params.action} ${params.permission} permission for ${params.bundleId}: ${failureSignal2.error_code}`
+  },
   description: `Grant, deny, or reset a runtime permission for an app without navigating the system Settings UI. Use during test setup to pre-authorize (or explicitly deny) a service before the app asks, or \`reset\` so the permission dialog appears again on next use. Always per-app: bundleId is required.
 Permissions: camera, microphone, photos, contacts, notifications, calendar, location, location-always, media-library, motion, reminders.
 iOS simulator: edits the simulator's TCC store, always per-app. \`notifications\` is not supported (no iOS equivalent). \`reset\` is per-app \u2014 a device-wide reset is a no-op for existing grants on recent iOS, so it is not offered. \`grant location\`/\`location-always\` needs the app already installed (location auth isn't stored in TCC and isn't applied to a bundle id until the app exists) \u2014 enforced on local simulators; a remote simulator can't be probed for install state, so ensure the app is installed there first. Other services can be granted before install.
@@ -126065,6 +126145,14 @@ var zodSchema14 = external_exports.object({
     "URL or scheme to open (e.g. https://example.com, messages://, tel:555, geo:37.0,-122.0). For Chromium this navigates the renderer."
   )
 });
+function safeDestination(value) {
+  try {
+    const url2 = new URL(value);
+    return url2.protocol === "http:" || url2.protocol === "https:" ? url2.hostname : url2.protocol.replace(/:$/, "");
+  } catch {
+    return "URL";
+  }
+}
 var capability6 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
@@ -126073,6 +126161,11 @@ var capability6 = {
 };
 var openUrlTool = {
   id: "open-url",
+  interaction: {
+    startedMsg: ({ params }) => `Opening ${safeDestination(params.url)}`,
+    completedMsg: ({ params }) => `Opened ${safeDestination(params.url)}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to open ${safeDestination(params.url)}: ${failureSignal2.error_code}`
+  },
   description: `Open a URL or URL scheme on the device.
 Use to navigate to a web page or deep-link into an app. On Chromium, this navigates the primary renderer to the given URL.
 Cross-platform schemes: https://, tel:, mailto:. iOS also: messages://, settings://, maps://. Android also: geo:, plus any app-specific deep link.
@@ -126369,6 +126462,11 @@ async function tvTargetLongSide(file2, scale) {
 function createScreenshotTool(registry2) {
   return {
     id: "screenshot",
+    interaction: {
+      startedMsg: () => "Capturing screenshot",
+      completedMsg: ({ result }) => `Captured screenshot ${result.image.filename}`,
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to capture screenshot: ${failureSignal2.error_code}`
+    },
     description: `Capture a screenshot of the device screen (iOS simulator, Android emulator, Apple TV simulator, Vega, or Chromium app). Returns { image }; the MCP adapter renders it as a visible image unless the caller passed includeImageInContext: false.
 Use when you need a baseline image before an interaction or to inspect the current screen state after a delay.
 Fails if the simulator-server / emulator backend / Chromium CDP is not reachable for the given device.`,
@@ -126431,6 +126529,11 @@ var zodSchema16 = external_exports.object({
     "Number of taps/clicks dispatched as ONE multi-tap gesture (2 = double-tap / double-click). The taps land inside the OS double-tap window; on Chromium each click carries an escalating CDP clickCount so dblclick actually fires. Default 1."
   )
 });
+function tapDescription(params, tense) {
+  const count = params.clickCount ?? 1;
+  const action = count === 1 ? tense === "present" ? "Tapping" : "Tapped" : count === 2 ? tense === "present" ? "Double-tapping" : "Double-tapped" : `${tense === "present" ? "Tapping" : "Tapped"} ${count} times`;
+  return `${action} at (${Math.round(params.x * 100)}%, ${Math.round(params.y * 100)}%)`;
+}
 var capability8 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
@@ -126453,6 +126556,11 @@ async function tapChromium(api, x, y, clickCount) {
 }
 var gestureTapTool = {
   id: "gesture-tap",
+  interaction: {
+    startedMsg: ({ params }) => tapDescription(params, "present"),
+    completedMsg: ({ params }) => tapDescription(params, "past"),
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to tap at (${Math.round(params.x * 100)}%, ${Math.round(params.y * 100)}%): ${failureSignal2.error_code}`
+  },
   description: `Press the device screen (iOS simulator, Android emulator, or Chromium app) at normalized coordinates: x and y are fractions of screen width and height in 0.0\u20131.0 (not pixels).
 Sends a Down event followed by an Up event at the same point. For Chromium, this dispatches a CDP mouse-press/release on the renderer.
 Set clickCount: 2 for a double-tap / double-click \u2014 the taps are dispatched as one gesture with proper click counting, which two separate tap calls cannot guarantee.
@@ -126526,6 +126634,11 @@ var capability9 = {
 };
 var gestureSwipeTool = {
   id: "gesture-swipe",
+  interaction: {
+    startedMsg: ({ params }) => `Swiping from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
+    completedMsg: ({ params }) => `Swiped from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to swipe: ${failureSignal2.error_code}`
+  },
   description: `Execute a smooth swipe / drag touch gesture between two points on the device (iOS simulator or Android emulator). All from/to positions are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels), same as gesture-tap.
 Generates interpolated Move events for a natural feel (~60fps).
 Swipe up (fromY > toY) to scroll content down.
@@ -126608,11 +126721,23 @@ var zodSchema18 = external_exports.object({
 }).refine((p) => (p.deltaX ?? 0) !== 0 || (p.deltaY ?? 0) !== 0, {
   message: "Pass a non-zero deltaX and/or deltaY \u2014 a scroll with no delta is a no-op."
 });
+function scrollDirection(params) {
+  const horizontal = (params.deltaX ?? 0) > 0 ? "right" : "left";
+  const vertical = (params.deltaY ?? 0) > 0 ? "down" : "up";
+  if ((params.deltaX ?? 0) === 0) return vertical;
+  if ((params.deltaY ?? 0) === 0) return horizontal;
+  return `${vertical} and ${horizontal}`;
+}
 var capability10 = {
   chromium: { app: true }
 };
 var gestureScrollTool = {
   id: "gesture-scroll",
+  interaction: {
+    startedMsg: ({ params }) => `Scrolling ${scrollDirection(params)}`,
+    completedMsg: ({ params }) => `Scrolled ${scrollDirection(params)}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to scroll: ${failureSignal2.error_code}`
+  },
   description: `Scroll content in a Chromium app by dispatching mouse-wheel events at a point. Anchor x/y are normalized 0.0\u20131.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe. Deltas are fractions of the window too: deltaY 0.5 scrolls down half a window; negative scrolls back up.
 Use when content is below/above the fold (describe shows off-screen elements with zero height) or a list needs scrolling. Chromium only \u2014 on iOS/Android use gesture-swipe.
 Returns { scrolled: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.`,
@@ -126657,6 +126782,11 @@ var capability11 = {
 };
 var gestureDragTool = {
   id: "gesture-drag",
+  interaction: {
+    startedMsg: ({ params }) => `Dragging from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
+    completedMsg: ({ params }) => `Dragged from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to drag: ${failureSignal2.error_code}`
+  },
   description: `Press the left mouse button at a start point, move to an end point, and release \u2014 a desktop mouse drag in a Chromium app. All positions are normalized 0.0\u20131.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe. Interpolates mouse-move events at ~60fps over durationMs for a natural drag.
 Use for slider thumbs, drag-and-drop, text selection, or draggable UI elements. Dragging never scrolls content on desktop \u2014 use gesture-scroll for lists/pages. Chromium only \u2014 on iOS/Android use gesture-swipe.
 Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.`,
@@ -126777,6 +126907,11 @@ var capability12 = {
 };
 var gestureCustomTool = {
   id: "gesture-custom",
+  interaction: {
+    startedMsg: () => "Performing custom gesture",
+    completedMsg: () => "Performed custom gesture",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to perform custom gesture: ${failureSignal2.error_code}`
+  },
   description: `Send a sequence of touch events for complex gestures.
 Use for: long press, drag-and-drop, custom scroll, pinch (second touch point).
 For simple taps use the gesture-tap tool. For straight-line scrolling use the gesture-swipe tool.
@@ -126852,6 +126987,11 @@ var capability13 = {
 };
 var gesturePinchTool = {
   id: "gesture-pinch",
+  interaction: {
+    startedMsg: ({ params }) => `Pinching ${params.endDistance > params.startDistance ? "out" : "in"} at (${Math.round(params.centerX * 100)}%, ${Math.round(params.centerY * 100)}%)`,
+    completedMsg: ({ params }) => `Pinched ${params.endDistance > params.startDistance ? "out" : "in"} at (${Math.round(params.centerX * 100)}%, ${Math.round(params.centerY * 100)}%)`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to pinch: ${failureSignal2.error_code}`
+  },
   description: `Execute a pinch-to-zoom gesture by moving two fingers toward or away from a center point to change the scale of on-screen content. All positions and distances are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels)\u2014same coordinate space as gesture-tap and gesture-swipe.
 startDistance > endDistance = pinch in (zoom out). startDistance < endDistance = pinch out (zoom in).
 Typical values: startDistance 0.2, endDistance 0.6 for a zoom-in pinch at screen center.
@@ -126937,6 +127077,19 @@ var capability14 = {
 };
 var gestureRotateTool = {
   id: "gesture-rotate",
+  interaction: {
+    startedMsg: ({ params }) => {
+      const degrees = Math.abs(params.endAngle - params.startAngle);
+      const direction = params.endAngle > params.startAngle ? "clockwise" : "counterclockwise";
+      return `Rotating gesture ${degrees}\xB0 ${direction}`;
+    },
+    completedMsg: ({ params }) => {
+      const degrees = Math.abs(params.endAngle - params.startAngle);
+      const direction = params.endAngle > params.startAngle ? "clockwise" : "counterclockwise";
+      return `Rotated gesture ${degrees}\xB0 ${direction}`;
+    },
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to rotate gesture: ${failureSignal2.error_code}`
+  },
   description: `Send a two-finger circular arc gesture to rotate on-screen content by a specified angle. Two fingers are placed opposite each other at a fixed radius from the center, then swept from startAngle to endAngle degrees. All positions and radii are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels)\u2014same coordinate space as gesture-tap and gesture-swipe.
 endAngle > startAngle = clockwise rotation. Typical values: radius 0.15, startAngle 0, endAngle 90 for a 90\xB0 clockwise turn. A single radius applies to both axes, so on a non-square screen it traces a physical ellipse (finger separation varies through the turn); pass radiusX+radiusY (fractions of width/height with radiusX\xB7width = radiusY\xB7height) for a physically circular orbit instead.
 Auto-generates interpolated frames at ~60fps.
@@ -127015,6 +127168,11 @@ var capability15 = {
 };
 var buttonTool = {
   id: "button",
+  interaction: {
+    startedMsg: ({ params }) => `Pressing ${params.button} button`,
+    completedMsg: ({ params }) => `Pressed ${params.button} button`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to press ${params.button} button: ${failureSignal2.error_code}`
+  },
   description: `Press a device hardware button (iOS simulator, Android emulator or device). iOS sends a Down then Up event automatically; Android injects a single \`adb\` key event.
 Supported buttons depend on the platform: home, back, power, volumeUp, volumeDown, appSwitch, actionButton \u2014 buttons not present on the target platform (e.g. 'back' on iOS, 'actionButton' on Android) are rejected with a clear error.
 Use when you need to trigger hardware button events.
@@ -127616,6 +127774,22 @@ function createKeyboardTool(registry2) {
   });
   return {
     id: "keyboard",
+    interaction: {
+      // Treat both text and key as sensitive. `key` is an unrestricted string at
+      // this boundary, so a value must not reach the event log before execution
+      // validates whether it is a supported named key.
+      startedMsg: ({ params }) => {
+        if (params.text === void 0) return "Pressing a key";
+        if (params.key === void 0) return "Entering text";
+        return "Entering text and pressing a key";
+      },
+      completedMsg: ({ params }) => {
+        if (params.text === void 0) return "Pressed a key";
+        if (params.key === void 0) return "Entered text";
+        return "Entered text and pressed a key";
+      },
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to use keyboard: ${failureSignal2.error_code}`
+    },
     description: `Type text or press special keys on the device (iOS simulator, Android emulator or device, Chromium app, Vega Virtual Device, or Apple TV / Android TV) using keyboard events.
 Use when you need to enter text or trigger a named key such as enter, escape, or arrow keys. On Vega and Apple TV / Android TV, prefer the remote tools for D-pad navigation; use keyboard to type into a focused text field (e.g. a search or login box).
 Returns { typed: string, keys: number }. Fails if an unsupported key name is provided or the device's input backend is not reachable.
@@ -127657,6 +127831,11 @@ var capability17 = {
 };
 var rotateTool = {
   id: "rotate",
+  interaction: {
+    startedMsg: ({ params }) => `Rotating device to ${params.orientation}`,
+    completedMsg: ({ params }) => `Rotated device to ${params.orientation}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to rotate device: ${failureSignal2.error_code}`
+  },
   description: `Set the device orientation to Portrait, LandscapeLeft, LandscapeRight, or PortraitUpsideDown.
 Use to test layout in a different orientation. Re-run \`describe\` afterwards \u2014 frame coordinates change with the orientation.
 Returns { orientation }. Fails if the target device is not booted.`,
@@ -127776,6 +127955,11 @@ var capability18 = {
 function createTvRemoteTool(registry2) {
   return {
     id: "tv-remote",
+    interaction: {
+      startedMsg: ({ params }) => `Pressing ${params.button} on TV remote${(params.repeat ?? 1) > 1 ? ` ${params.repeat} times` : ""}`,
+      completedMsg: ({ params }) => `Pressed ${params.button} on TV remote${(params.repeat ?? 1) > 1 ? ` ${params.repeat} times` : ""}`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to press ${params.button} on TV remote: ${failureSignal2.error_code}`
+    },
     description: `Press a TV remote / D-pad button (or a whole path of them) on a TV device \u2014 Apple TV (tvOS), Android TV (leanback), or Vega (Fire TV).
 A TV is navigated with a directional remote, not touch \u2014 use this instead of gesture-tap/swipe (which do not apply on a TV). Move focus with up/down/left/right, confirm with select, go back with back/menu, exit with home, and use playPause/rewind/fastForward/next/previous/volumeUp/volumeDown/mute for the corresponding remote keys. (On the Apple TV simulator the media-transport and volume keys are rejected \u2014 its HID stack ignores them; they work on Android TV and Vega.)
 Single press: { button: "down" }. Repeat the same button: { button: "down", repeat: 3 }.
@@ -133654,6 +133838,9 @@ function textMatches(actual, expected, mode) {
   }
   return mode === "equals" ? equalsCI(actual, expected) : includesCI(actual, expected);
 }
+function hasOwnConstraint(selector) {
+  return selector.text !== void 0 || selector.textMatches !== void 0 || selector.identifier !== void 0 || selector.role !== void 0;
+}
 function matchNodeWithRegex(node, selector, textRegex) {
   if (selector.text !== void 0) {
     if (!includesCI(node.label, selector.text) && !includesCI(node.value, selector.text)) {
@@ -133676,15 +133863,111 @@ function matchNodeWithRegex(node, selector, textRegex) {
 function selectorTextRegex(selector) {
   return selector.textMatches === void 0 ? void 0 : uiTreeMatchInternals.createRegExp(selector.textMatches);
 }
-function collectMatches(node, selector, textRegex, acc) {
-  if (matchNodeWithRegex(node, selector, textRegex)) acc.push(node);
-  for (const child of node.children) collectMatches(child, selector, textRegex, acc);
+var WITHIN_EPS = 5e-3;
+function frameWithin(inner, outer) {
+  return inner.x >= outer.x - WITHIN_EPS && inner.y >= outer.y - WITHIN_EPS && inner.x + inner.width <= outer.x + outer.width + WITHIN_EPS && inner.y + inner.height <= outer.y + outer.height + WITHIN_EPS;
+}
+var CONTAINMENT_GRID_N = 16;
+var CONTAINMENT_GRID_MIN = 32;
+function gridCell(coord) {
+  const c = Math.floor(coord * CONTAINMENT_GRID_N);
+  return c < 0 ? 0 : c >= CONTAINMENT_GRID_N ? CONTAINMENT_GRID_N - 1 : c;
+}
+function containmentTester(containers) {
+  if (containers.length < CONTAINMENT_GRID_MIN) {
+    return (node) => containers.some((c) => c !== node && frameWithin(node.frame, c.frame));
+  }
+  const cells = /* @__PURE__ */ new Map();
+  for (const c of containers) {
+    const f = c.frame;
+    const colEnd = gridCell(f.x + f.width + WITHIN_EPS);
+    const rowEnd = gridCell(f.y + f.height + WITHIN_EPS);
+    for (let row = gridCell(f.y - WITHIN_EPS); row <= rowEnd; row++) {
+      for (let col = gridCell(f.x - WITHIN_EPS); col <= colEnd; col++) {
+        const key = row * CONTAINMENT_GRID_N + col;
+        const bucket = cells.get(key);
+        if (bucket) bucket.push(c);
+        else cells.set(key, [c]);
+      }
+    }
+  }
+  return (node) => {
+    const bucket = cells.get(gridCell(node.frame.y) * CONTAINMENT_GRID_N + gridCell(node.frame.x));
+    return bucket !== void 0 && bucket.some((c) => c !== node && frameWithin(node.frame, c.frame));
+  };
+}
+function frameAbove(a, b) {
+  return a.y + a.height <= b.y + WITHIN_EPS;
+}
+function followKind(node, anchor) {
+  const below = frameAbove(anchor, node);
+  const above = frameAbove(node, anchor);
+  if (below !== above) return below ? "below" : "no";
+  const right = anchor.x + anchor.width <= node.x + WITHIN_EPS;
+  const left = node.x + node.width <= anchor.x + WITHIN_EPS;
+  return right !== left && right ? "band" : "no";
+}
+function frameAfter(node, anchor) {
+  return followKind(node, anchor) !== "no";
+}
+function afterTester(anchors) {
+  return (node) => anchors.some((a) => a !== node && frameAfter(node.frame, a.frame));
+}
+function comparePick(a, b) {
+  return frameArea(a) - frameArea(b) || a.width - b.width || a.height - b.height;
+}
+function compareBandPick(a, b) {
+  return a.x - b.x || a.y - b.y || comparePick(a, b);
+}
+function compareBelowPick(a, b) {
+  return a.y - b.y || a.x - b.x || comparePick(a, b);
+}
+function nearestAfter(candidates, anchors) {
+  if (candidates.length === 0 || anchors.length === 0) return [];
+  const picked = /* @__PURE__ */ new Set();
+  for (const anchor of anchors) {
+    const af = anchor.frame;
+    let band;
+    let below;
+    for (const c of candidates) {
+      if (c === anchor) continue;
+      const f = c.frame;
+      const kind = followKind(f, af);
+      if (kind === "band") {
+        if (band === void 0 || compareBandPick(f, band.frame) < 0) band = c;
+      } else if (kind === "below") {
+        if (below === void 0 || compareBelowPick(f, below.frame) < 0) below = c;
+      }
+    }
+    const best = band ?? below;
+    if (best !== void 0) picked.add(best);
+  }
+  return candidates.filter((c) => picked.has(c));
 }
 function findAll(root2, selector) {
-  const acc = [];
-  const textRegex = selectorTextRegex(selector);
-  for (const child of root2.children) collectMatches(child, selector, textRegex, acc);
-  return acc;
+  const all = [];
+  const collect = (node) => {
+    all.push(node);
+    for (const child of node.children) collect(child);
+  };
+  for (const child of root2.children) collect(child);
+  return resolveSelector(all, selector);
+}
+var SELECTOR_RELATIONS = ["within", "after", "next"];
+var RELATION_RESOLVERS = {
+  within: (matches2, scope) => matches2.filter(containmentTester(scope)),
+  after: (matches2, scope) => matches2.filter(afterTester(scope)),
+  next: (matches2, scope) => nearestAfter(matches2, scope)
+};
+function resolveSelector(all, selector) {
+  const regex = selectorTextRegex(selector);
+  let matches2 = all.filter((n) => matchNodeWithRegex(n, selector, regex));
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = selector[relation];
+    if (scope === void 0) continue;
+    matches2 = RELATION_RESOLVERS[relation](matches2, resolveSelector(all, scope));
+  }
+  return matches2;
 }
 function isVisible(node) {
   return node.frame.width > 0 && node.frame.height > 0;
@@ -133765,6 +134048,13 @@ function exactFieldCount(node, selector, fullTextRegex) {
 function selectorToFrame(root2, selector) {
   const visible = findAll(root2, selector).filter(isVisible);
   if (visible.length === 0) return void 0;
+  if (!hasOwnConstraint(selector)) {
+    let first;
+    for (const n of visible) {
+      if (first === void 0 || compareBelowPick(n.frame, first.frame) < 0) first = n;
+    }
+    return first?.frame;
+  }
   const fullTextRegex = fullConsumptionRegex(selector);
   let best;
   let bestExact = -1;
@@ -133850,6 +134140,18 @@ var zodSchema27 = external_exports.object({
   message: "condition `text` requires expectedText",
   path: ["expectedText"]
 });
+var conditionDescription = {
+  exists: "appear",
+  visible: "become visible",
+  hidden: "become hidden",
+  text: "match expected text"
+};
+var conditionCompleted = {
+  exists: "UI element appeared",
+  visible: "UI element became visible",
+  hidden: "UI element became hidden",
+  text: "UI element matched expected text"
+};
 var capability19 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true },
@@ -133911,6 +134213,11 @@ function createAwaitUiElementTool(registry2) {
   }
   return {
     id: AWAIT_UI_ELEMENT_TOOL_ID,
+    interaction: {
+      startedMsg: ({ params }) => `Waiting for UI element to ${conditionDescription[params.condition]}`,
+      completedMsg: ({ params }) => conditionCompleted[params.condition],
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed while waiting for UI element: ${failureSignal2.error_code}`
+    },
     description: `Block until a UI element reaches an expected state or a timeout elapses, so you don't have to poll screenshot/describe yourself.
 
 Conditions:
@@ -134041,6 +134348,11 @@ var capability20 = {
 function createRunSequenceTool(registry2) {
   return {
     id: "run-sequence",
+    interaction: {
+      startedMsg: ({ params }) => `Running ${params.steps.length}-step interaction sequence`,
+      completedMsg: ({ params }) => `Ran ${params.steps.length}-step interaction sequence`,
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to run interaction sequence: ${failureSignal2.error_code}`
+    },
     description: `Execute multiple device interaction steps in a single call (iOS simulator, Android emulator, Apple TV / Android TV, or Chromium app).
 Use when you need sequential actions and do NOT need to observe the screen between them
 (e.g. scrolling multiple times, typing then pressing enter, rotating back and forth).
@@ -134201,6 +134513,11 @@ var zodSchema29 = external_exports.object({
 });
 var debuggerConnectTool = {
   id: "debugger-connect",
+  interaction: {
+    startedMsg: () => "Connecting JavaScript debugger",
+    completedMsg: ({ result }) => `Connected JavaScript debugger to ${result.appName || result.deviceName}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to connect JavaScript debugger: ${failureSignal2.error_code}`
+  },
   description: `Connect to a JS runtime CDP debugger.
 iOS / Android / Vega: connects to Metro's CDP endpoint on the given port. Chromium: re-uses the page CDP session opened by boot-device \u2014 port is ignored.
 Returns connection info including port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), and isNewDebugger. If already connected, returns the existing connection.
@@ -134234,6 +134551,11 @@ var zodSchema30 = external_exports.object({
 });
 var debuggerStatusTool = {
   id: "debugger-status",
+  interaction: {
+    startedMsg: () => "Checking JavaScript debugger",
+    completedMsg: () => "Checked JavaScript debugger",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to check JavaScript debugger: ${failureSignal2.error_code}`
+  },
   description: `Get JS runtime debugger connection status and diagnostic info.
 Use when you need to verify connectivity before using other debugger tools. Returns port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), isNewDebugger (false on the legacy inspector), connected flag, loadedScripts count, and sourceMapReady (always true \u2014 waits for pending source maps before returning; no-op on Chromium). Fails if the runtime is unreachable.`,
   zodSchema: zodSchema30,
@@ -134270,6 +134592,11 @@ var zodSchema31 = external_exports.object({
 });
 var debuggerEvaluateTool = {
   id: "debugger-evaluate",
+  interaction: {
+    startedMsg: () => "Running JavaScript in the app",
+    completedMsg: () => "Ran JavaScript in the app",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to run JavaScript in the app: ${failureSignal2.error_code}`
+  },
   description: `Execute arbitrary JavaScript in the app's JS runtime via CDP \u2014 Hermes on iOS / Android / Vega, V8 on Chromium.
 Returns the evaluation result as a JSON-serializable value, along with deviceName, appName, and logicalDeviceId for context. Use when you need to read app state, call app functions, or test logic at runtime. The result is serialized by value, so cyclic objects (many RN runtime values \u2014 fiber nodes, navigation refs, global \u2014 are cyclic) fail with a serialization error rather than returning silently. Fails if the expression throws or the runtime is not connected.`,
   zodSchema: zodSchema31,
@@ -134300,6 +134627,11 @@ var zodSchema32 = external_exports.object({
 });
 var debuggerReloadMetroTool = {
   id: "debugger-reload-metro",
+  interaction: {
+    startedMsg: () => "Reloading the app through Metro",
+    completedMsg: () => "Reloaded the app through Metro",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to reload the app through Metro: ${failureSignal2.error_code}`
+  },
   description: `Restart the Metro JS bundle in the connected React Native app without restarting the native process.
 Use when you want to apply code changes or reset JS state. Returns { reloaded, port, method, deviceName, appName, logicalDeviceId } indicating which reload path was used and which device/app was targeted. Fails if Metro is not running on the given port.`,
   zodSchema: zodSchema32,
@@ -135127,6 +135459,11 @@ var zodSchema33 = external_exports.object({
 });
 var debuggerComponentTreeTool = {
   id: "debugger-component-tree",
+  interaction: {
+    startedMsg: () => "Reading React component tree",
+    completedMsg: () => "Read React component tree",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read React component tree: ${failureSignal2.error_code}`
+  },
   description: `Fetch the current screen of a running React Native app as a compact component text tree.
 Only shows on-screen components with unique positions \u2014 off-screen (scrolled) content,
 full-screen transparent wrappers, and implementation-detail components are pruned.
@@ -135637,6 +135974,11 @@ var zodSchema34 = external_exports.object({
 });
 var debuggerInspectElementTool = {
   id: "debugger-inspect-element",
+  interaction: {
+    startedMsg: ({ params }) => `Inspecting element at (${params.x}, ${params.y})`,
+    completedMsg: ({ params }) => `Inspected element at (${params.x}, ${params.y})`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to inspect element at (${params.x}, ${params.y}): ${failureSignal2.error_code}`
+  },
   description: `Inspect the React component hierarchy at a screen coordinate (x, y).
 Returns components from the tapped element upward through its parent hierarchy,
 each with its source file:line and a code fragment.
@@ -135759,6 +136101,11 @@ var zodSchema35 = external_exports.object({
 });
 var debuggerLogRegistryTool = {
   id: "debugger-log-registry",
+  interaction: {
+    startedMsg: () => "Reading app logs",
+    completedMsg: () => "Read app logs",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read app logs: ${failureSignal2.error_code}`
+  },
   description: `Get a summary of all console logs captured from the app's JS runtime.
 Returns the log file path, entry counts by level, and message clusters (grouped by similarity). Works against Hermes (iOS / Android / Vega) and V8 (Chromium).
 Use when investigating warnings, errors, or unexpected output \u2014 call this first for an overview, then read the returned file for details. Returns empty stats if no log data has been captured yet.`,
@@ -135851,6 +136198,11 @@ var zodSchema36 = external_exports.object({
 });
 var networkLogsTool = {
   id: "view-network-logs",
+  interaction: {
+    startedMsg: () => "Reading network activity",
+    completedMsg: () => "Read network activity",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read network activity: ${failureSignal2.error_code}`
+  },
   description: `Retrieve captured network (HTTP) requests from the running app.
 Returns a paginated list of requests with method, URL, status, resource type, size, and duration.
 Each entry includes a requestId that can be passed to view-network-request-details for full details.
@@ -135938,6 +136290,11 @@ var zodSchema37 = external_exports.object({
 });
 var networkRequestTool = {
   id: "view-network-request-details",
+  interaction: {
+    startedMsg: ({ params }) => `Reading network request ${params.requestId}`,
+    completedMsg: ({ params }) => `Read network request ${params.requestId}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to read network request ${params.requestId}: ${failureSignal2.error_code}`
+  },
   description: `Get full details of a specific network request by its requestId (from view-network-logs).
 Returns request/response headers (sensitive headers redacted), status, timing, and optionally the response body.
 Large response bodies are truncated. Use when you need headers, body, or timing for a specific request after listing logs.
@@ -136310,6 +136667,11 @@ function makeDescribeExecute(registry2) {
 function createDescribeTool(registry2) {
   return {
     id: "describe",
+    interaction: {
+      startedMsg: () => "Reading screen",
+      completedMsg: () => "Read screen",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read screen: ${failureSignal2.error_code}`
+    },
     description: `Get the accessibility / DOM element tree for the current screen.
 On iOS, uses the AXRuntime accessibility service to inspect whatever is currently visible \u2014 including
 system dialogs, permission prompts, and any foreground app content. On Android, runs \`uiautomator dump\`.
@@ -136402,6 +136764,11 @@ function createAwaitScreenIdleTool(registry2) {
   }
   return {
     id: AWAIT_SCREEN_IDLE_TOOL_ID,
+    interaction: {
+      startedMsg: () => "Waiting for screen to settle",
+      completedMsg: ({ result }) => result.settled ? "Screen settled" : "Screen did not settle before timeout",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed while waiting for screen to settle: ${failureSignal2.error_code}`
+    },
     description: `Block until the screen has rendered content and stopped changing, or a timeout elapses.
 
 Polls the same accessibility / DOM tree as \`describe\` every pollIntervalMs (default ${DEFAULT_POLL_INTERVAL_MS2}ms) until it
@@ -136527,6 +136894,11 @@ function safeGetState(registry2, urn) {
 function createReactProfilerStartTool(registry2) {
   return {
     id: "react-profiler-start",
+    interaction: {
+      startedMsg: () => "Starting React profiler",
+      completedMsg: ({ result }) => result.already_running ? "React profiler was already running" : "Started React profiler",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to start React profiler: ${failureSignal2.error_code}`
+    },
     description: `Start CPU profiling + React commit capture on the connected Hermes runtime.
 Delegates React commit capture to the in-app React DevTools backend (ri.startProfiling).
 If another tool-server already owns the session, returns { already_running: true, owner, stale, how_to_reclaim } without clobbering their data. Pass { force: true } to reclaim a fresh owner's session, but BEFORE OVERTAKING - ask the user for approval first, see relevant skill for guidance.
@@ -136884,6 +137256,11 @@ function flattenProfilingData(merged, displayNameById, fiberMeta) {
 function createReactProfilerStopTool(registry2) {
   return {
     id: "react-profiler-stop",
+    interaction: {
+      startedMsg: () => "Stopping React profiler",
+      completedMsg: () => "Stopped React profiler",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to stop React profiler: ${failureSignal2.error_code}`
+    },
     description: `Stop CPU profiling and collect the cpuProfile + React commit tree.
 Reads commit data from the in-app React DevTools backend.
 Stores results in the ReactProfilerSession for later use by react-profiler-analyze or react-profiler-cpu-summary.
@@ -137128,6 +137505,11 @@ var zodSchema42 = external_exports.object({
 function createReactProfilerStatusTool(registry2) {
   return {
     id: "react-profiler-status",
+    interaction: {
+      startedMsg: () => "Checking React profiler",
+      completedMsg: ({ result }) => result.is_running ? "React profiler is running" : "React profiler is stopped",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to check React profiler: ${failureSignal2.error_code}`
+    },
     description: `Check the state of the React profiler session without side effects. Use after an interruption (debugger disconnect, unexpected error, agent pause) to decide whether to continue with react-profiler-stop, start a new session, or reconnect the debugger. Ownership is verified server-side against this tool-server's in-memory session \u2014 no token-threading is required. Returns { session_status, is_running, current_owner, \u2026 }. If this tool-server process restarted after react-profiler-start, status will report 'taken_over'; use react-profiler-start { force: true } to reclaim.`,
     zodSchema: zodSchema42,
     // RN-only: companion to react-profiler-start.
@@ -138638,6 +139020,11 @@ var zodSchema43 = external_exports.object({
 });
 var reactProfilerAnalyzeTool = {
   id: "react-profiler-analyze",
+  interaction: {
+    startedMsg: () => "Analyzing React profile",
+    completedMsg: () => "Analyzed React profile",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to analyze React profile: ${failureSignal2.error_code}`
+  },
   description: `Analyze stored profiling data and return a markdown performance report.
 Returns { report, reportFile, hotCommitsTotal, hotCommitsShown, sessionFiles }.
 The report is structured around hot React commits (\u226516ms absolute floor) with per-commit
@@ -138798,6 +139185,11 @@ var fileInputs = [
 ];
 var reactProfilerComponentSourceTool = {
   id: "react-profiler-component-source",
+  interaction: {
+    startedMsg: ({ params }) => `Finding source for ${params.component_name}`,
+    completedMsg: ({ params, result }) => `${result.found ? "Found" : "Could not find"} source for ${params.component_name}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to find source for ${params.component_name}: ${failureSignal2.error_code}`
+  },
   description: `Find a React component's source via tree-sitter AST lookup: returns file path, line number, memoization status (isMemoized, hasUseCallback, hasUseMemo), and 50 lines of source for a named React component.
 Call this per-finding after react-profiler-analyze to inspect source before proposing a fix.
 Returns found: false if the component is not found in user-owned code (e.g. lives in node_modules).
@@ -138926,6 +139318,11 @@ function renderMarkdownTable(entries) {
 }
 var reactProfilerCpuSummaryTool = {
   id: "react-profiler-cpu-summary",
+  interaction: {
+    startedMsg: () => "Summarizing React CPU profile",
+    completedMsg: () => "Summarized React CPU profile",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to summarize React CPU profile: ${failureSignal2.error_code}`
+  },
   description: `Return a raw Hermes CPU flamegraph summary (top hotspot functions by self-time).
 FOR DEDICATED CPU INVESTIGATION ONLY \u2014 do NOT call this as part of a normal profiling session.
 Use react-profiler-analyze instead; it covers all React rendering performance analysis.
@@ -139040,6 +139437,11 @@ var zodSchema46 = external_exports.object({
 });
 var reactProfilerRendersTool = {
   id: "react-profiler-renders",
+  interaction: {
+    startedMsg: () => "Reading React render activity",
+    completedMsg: () => "Read React render activity",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read React render activity: ${failureSignal2.error_code}`
+  },
   description: `Scan the live React fiber tree to collect component render counts and durations.
 Returns a markdown table of the top re-rendering components. No profiling session required \u2014 works on a live connected app.
 Use when you want a quick snapshot of render counts without a full profiling session.
@@ -139211,6 +139613,11 @@ var zodSchema47 = external_exports.object({
 });
 var reactProfilerFiberTreeTool = {
   id: "react-profiler-fiber-tree",
+  interaction: {
+    startedMsg: () => "Reading React fiber tree",
+    completedMsg: () => "Read React fiber tree",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read React fiber tree: ${failureSignal2.error_code}`
+  },
   description: `Inspect the React fiber tree and return a JSON representation of the component hierarchy.
 Use when tracing ancestry of a library component or checking for useMemoCache hook (confirms React Compiler is active on a component).
 Returns a nested JSON tree of fiber nodes with name, tag, actualDuration, selfBaseDuration, and children.
@@ -142899,6 +143306,11 @@ var capability23 = {
 };
 var nativeProfilerStartTool = {
   id: "native-profiler-start",
+  interaction: {
+    startedMsg: () => "Starting native profiler",
+    completedMsg: () => "Started native profiler",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to start native profiler: ${failureSignal2.error_code}`
+  },
   capability: capability23,
   description: `Start native profiling on a booted device. iOS: Instruments via xctrace (CPU, hangs, memory). Android: Perfetto (CPU, jank, RSS-growth weak signal).
 Auto-detects the running app process unless app_process is explicitly provided.
@@ -142944,6 +143356,11 @@ function registerTrace(store, traceFile) {
 }
 var nativeProfilerStopTool = {
   id: "native-profiler-stop",
+  interaction: {
+    startedMsg: () => "Stopping native profiler",
+    completedMsg: ({ result }) => `Saved native profile ${result.traceFile.filename}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to stop native profiler: ${failureSignal2.error_code}`
+  },
   capability: capability24,
   // Packaging plus the export passes routinely exceed the 30s fetch timeout.
   longRunning: true,
@@ -142997,6 +143414,11 @@ var capability25 = {
 };
 var nativeProfilerAnalyzeTool = {
   id: "native-profiler-analyze",
+  interaction: {
+    startedMsg: () => "Analyzing native profile",
+    completedMsg: () => "Analyzed native profile",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to analyze native profile: ${failureSignal2.error_code}`
+  },
   capability: capability25,
   description: `Analyze exported native trace data and return an LLM-optimized markdown report.
 iOS: parses CPU time profile, UI hangs, and memory leaks from the exported XML files.
@@ -143989,6 +144411,11 @@ var capability26 = {
 function createScreenRecordingStartTool(registry2) {
   return {
     id: "screen-recording-start",
+    interaction: {
+      startedMsg: () => "Starting screen recording",
+      completedMsg: () => "Started screen recording",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to start screen recording: ${failureSignal2.error_code}`
+    },
     capability: capability26,
     description: `Start recording the device screen to a video file (h264 mp4, 30fps at the device's native resolution).
 By default stretches where the screen does not change are trimmed out (see trimStatic), so a long session with only brief activity comes back as a short clip instead of minutes of dead air.
@@ -144090,6 +144517,11 @@ var capability27 = {
 };
 var screenRecordingStopTool = {
   id: "screen-recording-stop",
+  interaction: {
+    startedMsg: () => "Stopping screen recording",
+    completedMsg: ({ result }) => `Saved screen recording ${result.video.filename}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to stop screen recording: ${failureSignal2.error_code}`
+  },
   capability: capability27,
   description: `Stop the screen recording started by \`screen-recording-start\` and retrieve the video: frame capture ends and ffmpeg finalizes the mp4.
 Also retrieves the video when the recording already ended on its own (time limit reached, capture process died) \u2014 call it even after the cap fired.
@@ -144356,6 +144788,11 @@ function shortenUrl(url2) {
 }
 var profilerCpuQueryTool = {
   id: "profiler-cpu-query",
+  interaction: {
+    startedMsg: ({ params }) => `Querying CPU profile by ${params.mode.replaceAll("_", " ")}`,
+    completedMsg: ({ params }) => `Queried CPU profile by ${params.mode.replaceAll("_", " ")}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to query CPU profile: ${failureSignal2.error_code}`
+  },
   description: `Query Hermes CPU profile data with targeted modes for iterative investigation.
 Requires react-profiler-stop (and ideally react-profiler-analyze) to have been called first.
 Modes:
@@ -144684,6 +145121,11 @@ function getTopComponents(entries, topN2) {
 }
 var profilerCommitQueryTool = {
   id: "profiler-commit-query",
+  interaction: {
+    startedMsg: ({ params }) => `Querying React commits ${params.mode.replace(/^by_/, "by ").replaceAll("_", " ")}`,
+    completedMsg: ({ params }) => `Queried React commits ${params.mode.replace(/^by_/, "by ").replaceAll("_", " ")}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to query React commits: ${failureSignal2.error_code}`
+  },
   description: `Query React commit data for iterative investigation of render performance.
 Requires react-profiler-stop to have been called first.
 Modes:
@@ -144777,6 +145219,12 @@ var zodSchema55 = external_exports.object({
   object_type: external_exports.string().optional().describe("Object type filter for leak_stacks mode"),
   top_n: external_exports.coerce.number().int().positive().default(15).describe("Max results to return (default 15)")
 });
+var stackQueryMode = {
+  hang_stacks: "hang stacks",
+  function_callers: "function callers",
+  thread_breakdown: "thread breakdown",
+  leak_stacks: "leak stacks"
+};
 function getIosParsedData(api) {
   if (!api.parsedData) {
     throw new FailureError(
@@ -145061,6 +145509,11 @@ async function executeAndroid(api, params) {
 }
 var profilerStackQueryTool = {
   id: "profiler-stack-query",
+  interaction: {
+    startedMsg: ({ params }) => `Querying native stacks by ${stackQueryMode[params.mode]}`,
+    completedMsg: ({ params }) => `Queried native stacks by ${stackQueryMode[params.mode]}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to query native stacks: ${failureSignal2.error_code}`
+  },
   description: `Query native profiler trace data for iterative investigation of native performance.
 Requires native-profiler-stop \u2192 native-profiler-analyze to have been called first.
 Modes:
@@ -145133,6 +145586,11 @@ var zodSchema56 = external_exports.object({
 });
 var profilerCombinedReportTool = {
   id: "profiler-combined-report",
+  interaction: {
+    startedMsg: () => "Building combined performance report",
+    completedMsg: () => "Built combined performance report",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to build combined performance report: ${failureSignal2.error_code}`
+  },
   description: `Generate a cross-correlated report combining React Profiler and native profiler data.
 Maps native hangs to React commits using wall-clock time alignment.
 Requires both react-profiler-analyze and native-profiler-analyze to have been called first.
@@ -145779,8 +146237,30 @@ async function loadNativeSession(debugDir, sessionId, api, appProcessOverride) {
   ];
   return lines.join("\n");
 }
+var profilerLoadAction = {
+  list: {
+    started: () => "Listing saved profiles",
+    completed: () => "Listed saved profiles",
+    failure: "list"
+  },
+  load_react: {
+    started: (params) => `Loading React profile ${params.session_id}`,
+    completed: (params) => `Loaded React profile ${params.session_id}`,
+    failure: "load"
+  },
+  load_native: {
+    started: (params) => `Loading native profile ${params.session_id}`,
+    completed: (params) => `Loaded native profile ${params.session_id}`,
+    failure: "load"
+  }
+};
 var profilerLoadTool = {
   id: "profiler-load",
+  interaction: {
+    startedMsg: ({ params }) => profilerLoadAction[params.mode].started(params),
+    completedMsg: ({ params }) => profilerLoadAction[params.mode].completed(params),
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to ${profilerLoadAction[params.mode].failure} saved profiles: ${failureSignal2.error_code}`
+  },
   description: `Fetch and restore a previously captured profiling session from disk into memory so query tools can operate on it.
 This is the disk-restore counterpart to react-profiler-stop/native-profiler-stop, which write data, and to the query tools (profiler-cpu-query, profiler-commit-query, profiler-stack-query), which read it.
 Use when you need to revisit past session data without capturing a new recording.
@@ -145859,6 +146339,11 @@ var zodSchema58 = external_exports.object({
 function createStopSimulatorServerTool(registry2) {
   return {
     id: "stop-simulator-server",
+    interaction: {
+      startedMsg: ({ params }) => `Stopping simulator server for ${params.udid}`,
+      completedMsg: ({ params }) => `Stopped simulator server for ${params.udid}`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to stop simulator server for ${params.udid}: ${failureSignal2.error_code}`
+    },
     description: `Stop the transport session for a specific device (iOS / Android: simulator-server process; Chromium: CDP WebSocket) and free its resources. Use when you are done interacting with one device but want to keep others running. Returns { stopped, udid }. Fails silently if no session is open for the given id.`,
     zodSchema: zodSchema58,
     services: () => ({}),
@@ -145899,6 +146384,11 @@ var PREFIXES = [
 function createStopAllSimulatorServersTool(registry2) {
   return {
     id: "stop-all-simulator-servers",
+    interaction: {
+      startedMsg: () => "Stopping all simulator servers",
+      completedMsg: ({ result }) => `Stopped ${result.stopped.length} simulator ${result.stopped.length === 1 ? "server" : "servers"}`,
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to stop simulator servers: ${failureSignal2.error_code}`
+    },
     description: `Stop all running simulator-server processes (iOS + Android), native devtools services, and Chromium CDP sessions, freeing their resources. Call this when your session ends or the user says they are done. Returns { stopped } \u2014 an array of URNs that were shut down. Fails silently if no servers are running.`,
     services: () => ({}),
     async execute() {
@@ -145956,6 +146446,11 @@ var zodSchema59 = external_exports.object({
 });
 var stopMetroTool = {
   id: "stop-metro",
+  interaction: {
+    startedMsg: ({ params }) => `Stopping Metro on port ${params.port}`,
+    completedMsg: ({ params }) => `Stopped Metro on port ${params.port}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to stop Metro on port ${params.port}: ${failureSignal2.error_code}`
+  },
   description: `Stop the Metro bundler process listening on a given port (default 8081). Use when ending a React Native session or when Metro must be restarted. Returns { stopped, port, pids }; stopped=false if no process is found on the port. Fails if the port lookup command times out or the process cannot be killed. This is DESTRUCTIVE \u2014 always ask the user for confirmation before calling this tool.`,
   zodSchema: zodSchema59,
   services: () => ({}),
@@ -146213,6 +146708,18 @@ function clearActiveFlow() {
   activeFlowName = null;
   recordingSession = null;
 }
+function selectorTree(sel) {
+  const out = [];
+  const walk = (s) => {
+    out.push(s);
+    for (const relation of SELECTOR_RELATIONS) {
+      const nested = s[relation];
+      if (nested !== void 0) walk(nested);
+    }
+  };
+  walk(sel);
+  return out;
+}
 function isE2eFlow(flow) {
   const first = flow.steps.find((s) => s.kind !== "echo");
   return first?.kind === "launch";
@@ -146246,11 +146753,35 @@ function selectorToYaml(sel) {
       "Cannot serialize flow selector: `text` must contain at least one visible character (icon-font/private-use and zero-width characters render as nothing). Select by identifier or role, or use a coordinate tap."
     );
   }
-  if (sel.loose && (sel.text === void 0 || sel.textMatches !== void 0 || sel.identifier !== void 0 || sel.role !== void 0)) {
+  const scopeCount = SELECTOR_RELATIONS.filter((relation) => sel[relation] !== void 0).length;
+  if (sel.any !== void 0) {
+    if (sel.any !== true) {
+      throw new Error(
+        "Cannot serialize flow selector: `any` is the universal selector and takes only `true` \u2014 omit it to select by text/id/role."
+      );
+    }
+    if (sel.text !== void 0 || sel.textMatches !== void 0 || sel.identifier || sel.role) {
+      throw new Error(
+        "Cannot serialize flow selector: `any` already matches every element, so it cannot be combined with text/id/role \u2014 keep one or the other."
+      );
+    }
+    if (scopeCount === 0) {
+      throw new Error(
+        `Cannot serialize flow selector: \`any\` matches every element on screen, so it needs a scope (${SELECTOR_RELATIONS.join("/")}) to narrow what it selects.`
+      );
+    }
+  } else if (scopeCount > 0 && sel.text === void 0 && sel.textMatches === void 0 && !sel.identifier && !sel.role) {
+    throw new Error(
+      `Cannot serialize flow selector: a scope (${SELECTOR_RELATIONS.join("/")}) only narrows where to look \u2014 the selector still needs its own text/id/role naming what to find there, or \`any: true\` for any element.`
+    );
+  }
+  if (sel.loose && (sel.text === void 0 || sel.textMatches !== void 0 || sel.identifier !== void 0 || sel.role !== void 0 || sel.any !== void 0 || SELECTOR_RELATIONS.some((relation) => sel[relation] !== void 0))) {
     const incompatible = [
       sel.textMatches !== void 0 ? "textMatches" : void 0,
       sel.identifier !== void 0 ? "identifier" : void 0,
-      sel.role !== void 0 ? "role" : void 0
+      sel.role !== void 0 ? "role" : void 0,
+      sel.any !== void 0 ? "any" : void 0,
+      ...SELECTOR_RELATIONS.map((relation) => sel[relation] !== void 0 ? relation : void 0)
     ].filter((field) => field !== void 0);
     throw new Error(
       "Cannot serialize loose flow selector without changing its meaning: bare-string YAML can represent only a loose text-only selector" + (incompatible.length > 0 ? `; incompatible fields: ${incompatible.join(", ")}` : "") + "."
@@ -146259,16 +146790,30 @@ function selectorToYaml(sel) {
   if (sel.loose && sel.text !== void 0 && sel.identifier === void 0 && sel.role === void 0) {
     return sel.text;
   }
-  const { loose: _loose, identifier, textMatches: textMatches2, ...rest } = sel;
+  const { loose: _loose, any: any2, identifier, textMatches: textMatches2, within, after, next, ...rest } = sel;
+  const scopes = { within, after, next };
   const out = { ...rest };
+  if (any2) out.any = true;
   if (textMatches2 !== void 0) out.text = { matches: textMatches2 };
   if (identifier !== void 0) out.id = identifier;
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = scopes[relation];
+    if (scope !== void 0) out[relation] = selectorToYaml(scope);
+  }
   return out;
 }
 function describeSelector(s) {
-  return Object.entries(s).filter(([k]) => k !== "loose").map(
+  const { loose: _loose, any: any2, within, after, next, ...rest } = s;
+  const scopes = { within, after, next };
+  const fields = Object.entries(rest).map(
     ([k, v]) => k === "textMatches" ? `text=/${v}/` : `${k === "identifier" ? "id" : k}="${v}"`
   ).join(" ");
+  const parts = [any2 ? "*" : void 0, fields || void 0].filter((p) => p !== void 0);
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = scopes[relation];
+    if (scope !== void 0) parts.push(`${relation} (${describeSelector(scope)})`);
+  }
+  return parts.join(" ");
 }
 function describeTextExpectation(expectedText, textMatch, verbForm = "mode") {
   const expected = expectedText ?? "";
@@ -146510,8 +147055,22 @@ function rejectUnknownKeys(raw, body, allowed, where) {
     `${where} has ${describeUnknownKeys(unknown2, allowed)} \u2014 allowed keys: ${allowed.join(", ")}`
   );
 }
-var SELECTOR_KEYS = ["text", "id", "identifier", "role"];
-function parseSelector(raw, where) {
+var SELECTOR_KEYS = [
+  "text",
+  "id",
+  "identifier",
+  "role",
+  "any",
+  ...SELECTOR_RELATIONS
+];
+var MAX_SELECTOR_SCOPES = 6;
+function parseSelector(raw, where, budget = { scopes: MAX_SELECTOR_SCOPES }) {
+  if (budget.scopes < 0) {
+    badEntry(
+      raw,
+      `${where}: a selector carries more than ${MAX_SELECTOR_SCOPES} scopes (${SELECTOR_RELATIONS.join("/")}) in total \u2014 check for a cyclic YAML alias (\`&s { \u2026, within: *s }\`)`
+    );
+  }
   if (typeof raw === "string") {
     const r2 = selectorSchema.safeParse({ text: raw });
     if (!r2.success) badEntry(raw, `${where}: ${r2.error.issues[0]?.message ?? "invalid selector"}`);
@@ -146520,9 +147079,55 @@ function parseSelector(raw, where) {
   if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
     rejectUnknownKeys(raw, raw, SELECTOR_KEYS, `${where}: selector`);
   }
-  let normalized = raw;
-  if (raw !== null && typeof raw === "object" && "id" in raw) {
-    const { id, ...rest } = raw;
+  const scopes = {};
+  let universal = false;
+  let fieldsRaw = raw;
+  if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+    const restRaw = { ...raw };
+    const present = SELECTOR_RELATIONS.filter((relation) => relation in restRaw);
+    for (const relation of present) {
+      budget.scopes--;
+      scopes[relation] = parseSelector(restRaw[relation], `${where}.${relation}`, budget);
+      delete restRaw[relation];
+    }
+    if ("any" in restRaw) {
+      if (restRaw.any !== true) {
+        badEntry(
+          raw,
+          `${where}: \`any\` takes only \`true\` \u2014 it is the CSS \`*\` universal selector (drop the key to select by text/id/role instead)`
+        );
+      }
+      delete restRaw.any;
+      if (Object.keys(restRaw).length > 0) {
+        badEntry(
+          raw,
+          `${where}: \`any: true\` already matches every element \u2014 drop it, or drop the ${Object.keys(
+            restRaw
+          ).map((k) => `\`${k}\``).join("/")} it makes redundant`
+        );
+      }
+      if (present.length === 0) {
+        badEntry(
+          raw,
+          `${where}: \`any: true\` matches every element on screen \u2014 pair it with a scope (${SELECTOR_RELATIONS.join(
+            "/"
+          )}) so it selects something specific`
+        );
+      }
+      universal = true;
+    } else if (present.length > 0 && Object.keys(restRaw).length === 0) {
+      badEntry(
+        raw,
+        `${where}: a selector's \`${present.join("`/`")}\` only scopes where to look \u2014 the selector still needs its own text/id/role naming what to find there (or \`any: true\` for any element)`
+      );
+    }
+    fieldsRaw = restRaw;
+  }
+  const attachScopes = (sel) => ({ ...sel, ...scopes });
+  if (universal) return attachScopes({ any: true });
+  let normalized = fieldsRaw;
+  if (fieldsRaw !== null && typeof fieldsRaw === "object" && "id" in fieldsRaw) {
+    const { id, ...rest } = fieldsRaw;
     if ("identifier" in rest) {
       badEntry(raw, `${where}: selector takes \`id\` or \`identifier\` (its alias), not both`);
     }
@@ -146555,12 +147160,12 @@ function parseSelector(raw, where) {
       if (!fields.success) {
         badEntry(raw, `${where}: ${fields.error.issues[0]?.message ?? "invalid selector"}`);
       }
-      return { ...fields.data, textMatches: pattern };
+      return attachScopes({ ...fields.data, textMatches: pattern });
     }
   }
   const r = selectorSchema.safeParse(normalized);
   if (!r.success) badEntry(raw, `${where}: ${r.error.issues[0]?.message ?? "invalid selector"}`);
-  return r.data;
+  return attachScopes(r.data);
 }
 var WAIT_CONDITIONS = ["exists", "visible", "hidden", "text"];
 var TEXT_MATCH_MODES = Object.keys({
@@ -146711,11 +147316,14 @@ function parseTapTimes(raw, entry) {
   }
   return raw === 1 ? void 0 : raw;
 }
+function hasSelectorField(obj) {
+  return obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0 || obj.any !== void 0 || SELECTOR_RELATIONS.some((relation) => obj[relation] !== void 0);
+}
 function parseTarget(raw, where) {
   if (raw !== null && typeof raw === "object") {
     const obj = raw;
     if (obj.x !== void 0 || obj.y !== void 0) {
-      if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+      if (hasSelectorField(obj)) {
         badEntry(raw, `${where} takes a selector or x/y coordinates, not both`);
       }
       if (typeof obj.x !== "number" || typeof obj.y !== "number") {
@@ -146738,7 +147346,7 @@ function parseTarget(raw, where) {
 function parseTap(body, entry) {
   const obj = body !== null && typeof body === "object" ? body : {};
   if (obj.on !== void 0 || obj.times !== void 0) {
-    if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+    if (hasSelectorField(obj)) {
       badEntry(
         entry,
         'the tap options form takes a nested selector \u2014 e.g. tap: { on: { text: "Photo" }, times: 2 }'
@@ -146766,7 +147374,7 @@ function parseTap(body, entry) {
 function parseLongPress(body, entry) {
   const obj = body !== null && typeof body === "object" ? body : {};
   if (obj.on !== void 0 || obj.duration !== void 0) {
-    if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+    if (hasSelectorField(obj)) {
       badEntry(
         entry,
         'the long-press options form takes a nested selector \u2014 e.g. long-press: { on: { text: "Row" }, duration: 1200 }'
@@ -146806,7 +147414,7 @@ function parsePinch(body, entry) {
     );
   }
   const obj = body;
-  if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+  if (hasSelectorField(obj)) {
     badEntry(entry, 'pinch takes a nested selector \u2014 e.g. pinch: { on: "Map", scale: 3 }');
   }
   rejectUnknownKeys(entry, obj, ["on", "scale"], "pinch");
@@ -146873,13 +147481,11 @@ function parseWhenCondition(raw) {
   }
   const { timeout: _timeout, ...cond } = parseWaitFields(raw, "when");
   const { selector, expectedText } = cond;
-  for (const s of [
-    expectedText,
-    selector.text,
-    selector.textMatches,
-    selector.identifier,
-    selector.role
-  ]) {
+  const guardStrings = [expectedText];
+  for (const s of selectorTree(selector)) {
+    guardStrings.push(s.text, s.textMatches, s.identifier, s.role);
+  }
+  for (const s of guardStrings) {
     if (s !== void 0 && s.includes(SECRET_PLACEHOLDER_MARKER)) {
       badEntry(
         { when: raw },
@@ -147004,6 +147610,12 @@ function fromYamlStep(raw, whenDepth = 0) {
     if (b.direction !== void 0 && (typeof b.direction !== "string" || !SCROLL_DIRECTIONS.includes(b.direction))) {
       badEntry(raw, `scroll-to direction must be one of ${SCROLL_DIRECTIONS.join(", ")}`);
     }
+    if (b.target === void 0) {
+      badEntry(
+        raw,
+        `scroll-to needs a \`target\` \u2014 its own \`within\` only anchors the gesture to a scroll container, e.g. scroll-to: { target: <selector>, within: { id: list } }. A selector scope (${SELECTOR_RELATIONS.join("/")}) goes inside \`target\`.`
+      );
+    }
     const step = {
       kind: "scroll-to",
       target: parseSelector(b.target, "scroll-to.target"),
@@ -147159,6 +147771,11 @@ var fileInputs2 = [
 ];
 var flowStartRecordingTool = {
   id: "flow-start-recording",
+  interaction: {
+    startedMsg: () => "Starting flow recording",
+    completedMsg: () => "Started flow recording",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to start flow recording: ${failureSignal2.error_code}`
+  },
   description: `Start recording a new flow. Creates a .yaml file in the .argent/flows/ directory.
 Use when you want to capture a reusable sequence of device interactions for later replay.
 Returns { message, flowFile, savedTo } and optionally { previousFlow } if a prior recording was abandoned.
@@ -147780,6 +148397,11 @@ async function captureRunTarget(session, args) {
 function createFlowAddStepTool(registry2) {
   return {
     id: "flow-add-step",
+    interaction: {
+      startedMsg: ({ params }) => `Adding ${params.command} step to recorded flow`,
+      completedMsg: ({ params }) => `Added ${params.command} step to recorded flow`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add ${params.command} step to recorded flow: ${failureSignal2.error_code}`
+    },
     description: `Execute a tool call and record it as a step in the active flow. Use when recording a flow with flow-start-recording and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow). Returns { message, toolResult, flowFile } on success. If it fails an error is returned and nothing is recorded.
 If a step was recorded by mistake, edit the .yaml file directly to remove it.`,
     zodSchema: zodSchema61,
@@ -147841,6 +148463,11 @@ var zodSchema62 = external_exports.object({
 });
 var flowInsertEchoTool = {
   id: "flow-add-echo",
+  interaction: {
+    startedMsg: () => "Adding note to recorded flow",
+    completedMsg: () => "Added note to recorded flow",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to add note to recorded flow: ${failureSignal2.error_code}`
+  },
   description: `Record an echo step in the active flow. Echo steps print a message when the flow is replayed \u2014 useful as labels between tool calls.
 Use when you want to annotate a recorded flow with a human-readable label or checkpoint message.
 Returns { message, flowFile }. Fails if no active flow recording is in progress.`,
@@ -147874,6 +148501,14 @@ function textConditionLabel(sel, expectedText, textMatch) {
 var zodSchema63 = external_exports.object({});
 var flowFinishRecordingTool = {
   id: "flow-finish-recording",
+  interaction: {
+    startedMsg: () => "Finishing flow recording",
+    completedMsg: ({ result }) => {
+      const flowName = result.path.split(/[\\/]/).pop()?.replace(/\.ya?ml$/, "") ?? "flow";
+      return `Saved recorded flow ${flowName}`;
+    },
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to finish flow recording: ${failureSignal2.error_code}`
+  },
   description: `Finish recording the active flow. Returns a summary of all recorded steps and the final YAML content. Use when you have added all desired steps and want to finalize the flow file. Fails if no active flow recording is in progress.
 You can still edit the .yaml file directly afterwards to remove or reorder steps.`,
   zodSchema: zodSchema63,
@@ -148002,7 +148637,16 @@ function probeWhenCondition(env, cond) {
   return waitForCondition(env, cond, DEFAULT_ASSERT_TIMEOUT_MS);
 }
 function selectorAlternatives(sel) {
-  return sel.loose && sel.text !== void 0 ? [{ identifier: sel.text }, { text: sel.text }] : [sel];
+  const { loose, any: _any2, within, after, next, ...own } = sel;
+  const scopes = { within, after, next };
+  let alts = loose && own.text !== void 0 ? [{ identifier: own.text }, { text: own.text }] : [own];
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = scopes[relation];
+    if (scope === void 0) continue;
+    const scopeAlts = selectorAlternatives(scope);
+    alts = alts.flatMap((o) => scopeAlts.map((s) => ({ ...o, [relation]: s })));
+  }
+  return alts;
 }
 function flowFindAll(tree, sel) {
   let fallback = [];
@@ -150889,11 +151533,22 @@ async function runLaunch(state3, app) {
 function createRunFlowTool(registry2) {
   return {
     id: "flow-execute",
+    interaction: {
+      startedMsg: ({ params }) => `Running flow ${params.name}`,
+      completedMsg: ({ params }) => `Ran flow ${params.name}`,
+      failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to run flow ${params.name}: ${failureSignal2.error_code}`
+    },
     description: `Run a saved flow from the .argent/flows/ directory.
 Steps run in order: \`launch\` starts an app from scratch (terminate + relaunch) and waits until it is
 ready; \`tool\` calls dispatch through the registry; \`tap\`/\`long-press\`/\`type\` resolve a selector to an
 element and act on it (\`tap: { on, times: 2 }\` double-taps; \`long-press: { on, duration }\` presses and
-holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 bare \`{ x, y }\` or \`on: { x, y }\`);
+holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 bare \`{ x, y }\` or \`on: { x, y }\`;
+any selector may scope its matches geometrically, the CSS combinators read off frames: \`within: <selector>\`
+(descendant \u2014 inside that container's frame), \`after: <selector>\` (CSS \`~\` \u2014 following it in reading
+order), \`next: <selector>\` (CSS \`+\` \u2014 the nearest such follower, which unlike CSS reaches past a
+non-matching neighbour rather than failing), plus \`any: true\` (CSS \`*\` \u2014 legal only WITH a scope and
+never beside text/id/role). Scopes nest to disambiguate \u2014 \`within: { id: card, within: { id: list } }\`
+reads "inside card inside list", each container's frame inside the next);
 \`scroll-to\` scrolls (momentum-free) until a target is visible; \`pinch\` zooms
 (\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`rotate\` is the
 two-finger rotation gesture (\`rotate: { on?, by }\` \u2014 degrees, + clockwise, within \xB13000\xB0; screen center
@@ -151052,10 +151707,15 @@ function pushReport(state3, report) {
 }
 function selectorLabel2(sel) {
   const parts = [];
+  if (sel.any) parts.push("*");
   if (sel.text !== void 0) parts.push(`"${sel.text}"`);
   if (sel.textMatches !== void 0) parts.push(`/${sel.textMatches}/`);
   if (sel.identifier) parts.push(`id=${sel.identifier}`);
   if (sel.role) parts.push(`role=${sel.role}`);
+  for (const relation of SELECTOR_RELATIONS) {
+    const scope = sel[relation];
+    if (scope !== void 0) parts.push(`${relation} (${selectorLabel2(scope)})`);
+  }
   return parts.join(" ");
 }
 function conditionLabel(cond, renderSelector) {
@@ -151376,6 +152036,11 @@ var fileInputs4 = [
 ];
 var flowReadPrerequisiteTool = {
   id: "flow-read-prerequisite",
+  interaction: {
+    startedMsg: () => "Reading flow prerequisite",
+    completedMsg: () => "Read flow prerequisite",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read flow prerequisite: ${failureSignal2.error_code}`
+  },
   description: `Read the execution prerequisite of a saved flow without running it.
 Returns the prerequisite description so you can verify the required state is met before calling flow-execute.
 Use when you need to check what app/simulator state is required before executing a flow.
@@ -151701,6 +152366,11 @@ var fileInputs5 = [
 ];
 var gatherWorkspaceDataTool = {
   id: "gather-workspace-data",
+  interaction: {
+    startedMsg: () => "Gathering workspace data",
+    completedMsg: () => "Gathered workspace data",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to gather workspace data: ${failureSignal2.error_code}`
+  },
   description: `Fetch a structured snapshot of a mobile app project's workspace.
 
 Returns package.json contents, metro/babel config text, app.json, eas.json, tsconfig,
@@ -151801,6 +152471,11 @@ var zodSchema67 = external_exports.object({
 var updateScheduled = false;
 var updateArgentTool = {
   id: "update-argent",
+  interaction: {
+    startedMsg: () => `Updating Argent to ${getUpdateState().installableVersion ?? "latest"}`,
+    completedMsg: () => `Updated Argent to ${getUpdateState().installableVersion ?? "latest"}`,
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to update Argent: ${failureSignal2.error_code}`
+  },
   description: "Apply a pending Argent update. Only call this tool when the user has explicitly consented to updating Argent in this conversation. Use when an update notification indicates a new version is available and the user agrees to update. By default updates the install serving this session; pass `target` to choose global/local/both. Returns { message } with the update status and version info. The tool server will restart automatically after the update. Fails if no update is available or an update is already in progress.",
   zodSchema: zodSchema67,
   services: () => ({}),
@@ -151892,6 +152567,11 @@ var zodSchema68 = external_exports.object({
 });
 var dismissUpdateTool = {
   id: "dismiss-update",
+  interaction: {
+    startedMsg: () => "Dismissing Argent update",
+    completedMsg: () => "Dismissed Argent update",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to dismiss Argent update: ${failureSignal2.error_code}`
+  },
   description: "Clear the Argent update notification for the given number of hours. Use when the user asks to postpone or silence update reminders. Returns { message } confirming the suppression duration. Fails if the hours value is negative or the suppression state cannot be persisted.",
   zodSchema: zodSchema68,
   services: () => ({}),
@@ -151937,6 +152617,11 @@ var fileInputs6 = [
 ];
 var screenshotDiffTool = {
   id: "screenshot-diff",
+  interaction: {
+    startedMsg: () => "Comparing screenshots",
+    completedMsg: () => "Compared screenshots",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to compare screenshots: ${failureSignal2.error_code}`
+  },
   description: `Compare two PNG screenshots and return a compact visual-diff summary.
 Accepts saved baseline/current PNG paths, or one saved PNG plus one live full-resolution capture from a device. Always provide udid so the simulator-server dependency can be resolved.
 Use when stable before/after screenshots exist and the expected result is pixel-visible: layout, spacing, color, typography, image/icon rendering, clipping, overflow, or text rendering.
@@ -152200,6 +152885,11 @@ var zodSchema70 = external_exports.object({
 function createProposeVariantTool(registry2) {
   return {
     id: "propose_variant",
+    interaction: {
+      startedMsg: () => "Presenting variant options",
+      completedMsg: () => "Presented variant options",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to present variant options: ${failureSignal2.error_code}`
+    },
     featureFlag: "argent-lens",
     description: `Stage ONE design variant for ONE on-screen element, then return immediately (non-blocking).
 
@@ -152250,6 +152940,11 @@ var zodSchema71 = external_exports.object({
 });
 var awaitUserSelectionTool = {
   id: "await_user_selection",
+  interaction: {
+    startedMsg: () => "Waiting for variant selection",
+    completedMsg: () => "Received variant selection",
+    failedMsg: ({ failureSignal: failureSignal2 }) => `Failed while waiting for variant selection: ${failureSignal2.error_code}`
+  },
   featureFlag: "argent-lens",
   // Hidden entirely while an `argent lens` CLI session owns the preview window:
   // there, the user's picks are relayed into the agent's terminal as a normal
@@ -152305,11 +153000,38 @@ var zodSchema72 = external_exports.object({
   url: external_exports.string().optional().describe("`new` only: URL to open (defaults to about:blank)."),
   label: external_exports.string().optional().describe("`new` only: a memorable label usable interchangeably with the tabId.")
 });
+var tabAction = {
+  list: {
+    started: () => "Listing tabs",
+    completed: (_params, result) => `Listed ${result.tabs.length} ${result.tabs.length === 1 ? "tab" : "tabs"}`,
+    failure: "list"
+  },
+  select: {
+    started: (params) => `Selecting tab ${params.tab}`,
+    completed: (params) => `Selected tab ${params.tab}`,
+    failure: "select"
+  },
+  new: {
+    started: () => "Opening a new tab",
+    completed: () => "Opened a new tab",
+    failure: "open"
+  },
+  close: {
+    started: (params) => `Closing ${params.tab ? `tab ${params.tab}` : "active tab"}`,
+    completed: (params) => `Closed ${params.tab ? `tab ${params.tab}` : "active tab"}`,
+    failure: "close"
+  }
+};
 var capability29 = {
   chromium: { app: true }
 };
 var chromiumTabsTool = {
   id: "chromium-tabs",
+  interaction: {
+    startedMsg: ({ params }) => tabAction[params.action].started(params),
+    completedMsg: ({ params, result }) => tabAction[params.action].completed(params, result),
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to ${tabAction[params.action].failure} browser tabs: ${failureSignal2.error_code}`
+  },
   description: `List and switch the tabs / windows of a Chromium (CDP) app (an Electron app's BrowserWindows or a Chromium browser's tabs), and open or close them.
 - action="list": enumerate page targets with stable ids (\`t1\`, \`t2\`, \u2026), title, url, and which is active.
 - action="select" (tab=<tabId|label>): make that tab the active one. The active tab is what describe / gesture-tap / screenshot / debugger-evaluate / open-url all operate on, so switch before driving a different tab.
@@ -152436,11 +153158,22 @@ var zodSchema73 = external_exports.object({
   sameSite: external_exports.enum(["Strict", "Lax", "None"]).optional().describe("set: SameSite policy."),
   expires: external_exports.number().optional().describe("set: expiry as a Unix timestamp (seconds). Omit for a session cookie.")
 });
+var cookieAction = {
+  get: { started: "Reading", completed: "Read", failure: "read" },
+  set: { started: "Setting", completed: "Set", failure: "set" },
+  delete: { started: "Deleting", completed: "Deleted", failure: "delete" },
+  clear: { started: "Clearing", completed: "Cleared", failure: "clear" }
+};
 var capability30 = {
   chromium: { app: true }
 };
 var chromiumCookiesTool = {
   id: "chromium-cookies",
+  interaction: {
+    startedMsg: ({ params }) => `${cookieAction[params.action].started} browser cookies`,
+    completedMsg: ({ params }) => `${cookieAction[params.action].completed} browser cookies`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to ${cookieAction[params.action].failure} browser cookies: ${failureSignal2.error_code}`
+  },
   description: `Read and write cookies of a Chromium (CDP) app (via the Network domain, so HttpOnly cookies are included).
 - action="get" (url?): list cookies, optionally restricted to given URLs (defaults to the active page).
 - action="set" (name, value, + url OR domain, optional path/secure/httpOnly/sameSite/expires): create or update a cookie.
@@ -152523,11 +153256,22 @@ var zodSchema74 = external_exports.object({
   key: external_exports.string().optional().describe("get (optional) / set / remove: the storage key."),
   value: external_exports.string().optional().describe("set: the value to store.")
 });
+var storageAction = {
+  get: { started: "Reading", completed: "Read", failure: "read" },
+  set: { started: "Updating", completed: "Updated", failure: "update" },
+  remove: { started: "Removing from", completed: "Removed from", failure: "remove from" },
+  clear: { started: "Clearing", completed: "Cleared", failure: "clear" }
+};
 var capability31 = {
   chromium: { app: true }
 };
 var chromiumStorageTool = {
   id: "chromium-storage",
+  interaction: {
+    startedMsg: ({ params }) => `${storageAction[params.action].started} ${params.store} storage`,
+    completedMsg: ({ params }) => `${storageAction[params.action].completed} ${params.store} storage`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to ${storageAction[params.action].failure} ${params.store} storage: ${failureSignal2.error_code}`
+  },
   description: `Read and write localStorage / sessionStorage of a Chromium (CDP) app's active page.
 - action="get": with \`key\`, returns that value; without \`key\`, returns all entries.
 - action="set" (key, value): write an entry.