@swmansion/argent 0.21.1-next.16 → 0.21.1-next.18

package/dist/cli-cmds.mjs

@@ -2309,6 +2309,8 @@ var FAILURE_CODES = {
   IOS_SETTINGS_PERMISSION_FAILED: "IOS_SETTINGS_PERMISSION_FAILED",
   IOS_SHAKE_FAILED: "IOS_SHAKE_FAILED",
   ANDROID_SHAKE_FAILED: "ANDROID_SHAKE_FAILED",
+  PASTE_CLIPBOARD_SET_FAILED: "PASTE_CLIPBOARD_SET_FAILED",
+  PASTE_CLIPBOARD_UNSUPPORTED: "PASTE_CLIPBOARD_UNSUPPORTED",
   SETTINGS_PERMISSION_UNSUPPORTED: "SETTINGS_PERMISSION_UNSUPPORTED",
   NATIVE_DEVTOOLS_DESCRIBE_ERROR: "NATIVE_DEVTOOLS_DESCRIBE_ERROR",
   NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR: "NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR",
@@ -7214,7 +7216,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.21.1-next.16";
+    return "0.21.1-next.18";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -15468,6 +15468,8 @@ var FAILURE_CODES = {
   IOS_SETTINGS_PERMISSION_FAILED: "IOS_SETTINGS_PERMISSION_FAILED",
   IOS_SHAKE_FAILED: "IOS_SHAKE_FAILED",
   ANDROID_SHAKE_FAILED: "ANDROID_SHAKE_FAILED",
+  PASTE_CLIPBOARD_SET_FAILED: "PASTE_CLIPBOARD_SET_FAILED",
+  PASTE_CLIPBOARD_UNSUPPORTED: "PASTE_CLIPBOARD_UNSUPPORTED",
   SETTINGS_PERMISSION_UNSUPPORTED: "SETTINGS_PERMISSION_UNSUPPORTED",
   NATIVE_DEVTOOLS_DESCRIBE_ERROR: "NATIVE_DEVTOOLS_DESCRIBE_ERROR",
   NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR: "NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR",
@@ -16434,7 +16436,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.21.1-next.16";
+    return "0.21.1-next.18";
   }
   return "0.0.0";
 }

package/dist/mcp-server.mjs

@@ -16493,6 +16493,8 @@ var FAILURE_CODES = {
   IOS_SETTINGS_PERMISSION_FAILED: "IOS_SETTINGS_PERMISSION_FAILED",
   IOS_SHAKE_FAILED: "IOS_SHAKE_FAILED",
   ANDROID_SHAKE_FAILED: "ANDROID_SHAKE_FAILED",
+  PASTE_CLIPBOARD_SET_FAILED: "PASTE_CLIPBOARD_SET_FAILED",
+  PASTE_CLIPBOARD_UNSUPPORTED: "PASTE_CLIPBOARD_UNSUPPORTED",
   SETTINGS_PERMISSION_UNSUPPORTED: "SETTINGS_PERMISSION_UNSUPPORTED",
   NATIVE_DEVTOOLS_DESCRIBE_ERROR: "NATIVE_DEVTOOLS_DESCRIBE_ERROR",
   NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR: "NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR",
@@ -18491,6 +18493,7 @@ var AUTO_SCREENSHOT_TOOLS = /* @__PURE__ */ new Set([
   "gesture-rotate",
   "button",
   "keyboard",
+  "paste",
   "rotate",
   "launch-app",
   "restart-app",
@@ -18513,6 +18516,7 @@ var AUTO_SCREENSHOT_DELAY_MS_BY_TOOL = {
   "button": 1500,
   "rotate": 1e3,
   "keyboard": 300,
+  "paste": 300,
   "describe": 100
 };
 var DEFAULT_DELAY_MS = 1400;

package/dist/tool-server.cjs

@@ -610,6 +610,8 @@ var init_failure_codes = __esm({
       IOS_SETTINGS_PERMISSION_FAILED: "IOS_SETTINGS_PERMISSION_FAILED",
       IOS_SHAKE_FAILED: "IOS_SHAKE_FAILED",
       ANDROID_SHAKE_FAILED: "ANDROID_SHAKE_FAILED",
+      PASTE_CLIPBOARD_SET_FAILED: "PASTE_CLIPBOARD_SET_FAILED",
+      PASTE_CLIPBOARD_UNSUPPORTED: "PASTE_CLIPBOARD_UNSUPPORTED",
       SETTINGS_PERMISSION_UNSUPPORTED: "SETTINGS_PERMISSION_UNSUPPORTED",
       NATIVE_DEVTOOLS_DESCRIBE_ERROR: "NATIVE_DEVTOOLS_DESCRIBE_ERROR",
       NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR: "NATIVE_DEVTOOLS_VIEW_AT_POINT_ERROR",
@@ -95690,7 +95692,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.21.1-next.16";
+    return "0.21.1-next.18";
   }
   return "0.0.0";
 }
@@ -98281,23 +98283,23 @@ var InvalidToolInputError = class extends Error {
     });
   }
 };
-function platformMatrix(platform, capability33) {
+function platformMatrix(platform, capability34) {
   switch (platform) {
     case "ios":
-      return capability33.apple;
+      return capability34.apple;
     case "ios-remote":
-      return capability33.appleRemote;
+      return capability34.appleRemote;
     case "android":
-      return capability33.android;
+      return capability34.android;
     case "chromium":
-      return capability33.chromium;
+      return capability34.chromium;
     case "vega":
-      return capability33.vega;
+      return capability34.vega;
   }
 }
-function assertSupported(toolId, capability33, device) {
-  if (!capability33) return;
-  const matrix = platformMatrix(device.platform, capability33);
+function assertSupported(toolId, capability34, device) {
+  if (!capability34) return;
+  const matrix = platformMatrix(device.platform, capability34);
   if (!matrix) {
     throw new UnsupportedOperationError(toolId, device, `no ${device.platform} support declared`);
   }
@@ -98305,7 +98307,7 @@ function assertSupported(toolId, capability33, device) {
   if (!supported) {
     throw new UnsupportedOperationError(toolId, device, `kind '${device.kind}' not supported`);
   }
-  if (capability33.supports && !capability33.supports(device)) {
+  if (capability34.supports && !capability34.supports(device)) {
     throw new UnsupportedOperationError(toolId, device, "supports() refiner rejected device");
   }
 }
@@ -108130,6 +108132,42 @@ async function pointerPost(api, body, signal) {
     return false;
   }
 }
+async function setSimulatorClipboardText(api, text, signal) {
+  let res;
+  try {
+    res = await fetch(`${api.apiUrl}/api/clipboard/text`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text }),
+      signal
+    });
+  } catch (err) {
+    throw toSimulatorNetworkError("Paste", err, api.apiUrl);
+  }
+  if (res.status === 404) {
+    throw new FailureError(
+      "Paste failed: this simulator-server build has no clipboard endpoint. Update argent so its bundled simulator-server includes clipboard support, or type the text with the keyboard tool instead.",
+      {
+        error_code: FAILURE_CODES.PASTE_CLIPBOARD_UNSUPPORTED,
+        failure_stage: "simulator_clipboard_endpoint_missing",
+        failure_area: "tool_server",
+        error_kind: "unsupported"
+      }
+    );
+  }
+  const body = await res.json().catch(() => null);
+  if (!res.ok || body?.status !== "ok") {
+    throw new FailureError(
+      `Paste failed: could not set the device clipboard (${body?.error ?? `HTTP ${res.status}`}).`,
+      {
+        error_code: FAILURE_CODES.PASTE_CLIPBOARD_SET_FAILED,
+        failure_stage: "simulator_clipboard_set",
+        failure_area: "tool_server",
+        error_kind: "unknown"
+      }
+    );
+  }
+}
 async function simulatorPost(toolLabel, api, endpoint, reqBody, signal, fallbackHint) {
   let res;
   try {
@@ -108245,10 +108283,6 @@ function routeViaTransport(transport, cmd) {
     case "rotate":
       transport.rotate(cmd.direction);
       return;
-    case "paste": {
-      void Promise.resolve(transport.paste(cmd.text));
-      return;
-    }
     default:
       throw new Error(`MoQ transport does not implement sendCommand cmd '${String(cmd.cmd)}'`);
   }
@@ -122346,13 +122380,176 @@ One call does one action: pass text OR key, never both. To type and then press a
   };
 }
 
+// ../tool-server/src/tools/paste/schema.ts
+init_zod();
+var pasteZodSchema = external_exports.object({
+  udid: external_exports.string().min(1).describe(
+    "Target device id from `list-devices` (iOS simulator UDID or Android emulator serial)."
+  ),
+  text: external_exports.string().min(1).describe(
+    "Text to put on the device clipboard and paste into the focused field. Supports `{{secret:<NAME>}}` placeholders, resolved on the tool-server from the `ARGENT_SECRET_<NAME>` environment variable or an argent secrets file \u2014 the same sources as `keyboard` \u2014 so a credential never enters your context. If the secret is not set, the failure lists the available names and every source it looked in; ask the user to add it there, NEVER ask for the value in the conversation."
+  )
+});
+
+// ../tool-server/src/tools/paste/platforms/ios.ts
+var LEFT_GUI_KEYCODE = 227;
+var V_KEYCODE = charToKeyPress("v").keyCode;
+var CHORD_STEP_MS = 50;
+var sleep10 = (ms) => new Promise((r) => setTimeout(r, ms));
+function rejectTv(device) {
+  throw new UnsupportedOperationError(
+    "paste",
+    device,
+    "tvOS has no pasteboard to paste from \u2014 type into the focused field with keyboard instead"
+  );
+}
+async function pasteSimulator(api, text) {
+  await setSimulatorClipboardText(api, text);
+  api.pressKey("Down", LEFT_GUI_KEYCODE);
+  await sleep10(CHORD_STEP_MS);
+  api.pressKey("Down", V_KEYCODE);
+  await sleep10(CHORD_STEP_MS);
+  api.pressKey("Up", V_KEYCODE);
+  await sleep10(CHORD_STEP_MS);
+  api.pressKey("Up", LEFT_GUI_KEYCODE);
+  await sleep10(CHORD_STEP_MS);
+  return { pasted: true };
+}
+function makeIosImpl4(registry2) {
+  return {
+    // `isTvOsSimulator` shells out to `simctl`; the simulator-server itself is
+    // resolved through the blueprint.
+    requires: ["xcrun"],
+    async handler(_services, params, device) {
+      if (await isTvOsSimulator(device.id)) rejectTv(device);
+      const ref = simulatorServerRef(device);
+      const api = await registry2.resolveService(ref.urn, ref.options);
+      return pasteSimulator(api, params.text);
+    }
+  };
+}
+function makeIosRemoteImpl2(registry2) {
+  return {
+    requires: ["sim-remote"],
+    async handler(_services, params, device) {
+      if (await isRemoteTvOsSimulator(device.id)) rejectTv(device);
+      const ref = simulatorServerRef(device);
+      const api = await registry2.resolveService(ref.urn, ref.options);
+      if (!api.transport) {
+        throw new Error(
+          `Tool 'paste' resolved an ios-remote simulator-server without a transport for ${device.id}.`
+        );
+      }
+      await api.transport.paste(params.text);
+      return { pasted: true };
+    }
+  };
+}
+
+// ../tool-server/src/tools/paste/platforms/android.ts
+init_adb();
+var KEYCODE_PASTE = 279;
+function makeAndroidImpl2(registry2) {
+  return {
+    requires: ["adb"],
+    async handler(_services, params, device) {
+      if (await isAndroidTv(device.id)) {
+        throw new UnsupportedOperationError(
+          "paste",
+          device,
+          "Android TV is focus-driven \u2014 type into the focused field with keyboard instead"
+        );
+      }
+      const ref = simulatorServerRef(device);
+      const api = await registry2.resolveService(ref.urn, ref.options);
+      await setSimulatorClipboardText(api, params.text);
+      await injectAndroidKeycode(device.id, KEYCODE_PASTE);
+      return { pasted: true };
+    }
+  };
+}
+
+// ../tool-server/src/tools/paste/index.ts
+var capability17 = {
+  // Simulators only. A physical iPhone's pasteboard is reachable through the
+  // same simulator-server endpoint, but the paste keystroke is not verified
+  // over the CoreDevice HID path, so `device` stays off until it is.
+  apple: { simulator: true },
+  // A remote simulator pastes through the MoQ transport's existing paste
+  // primitive (device pasteboard + ⌘V on the remote host).
+  appleRemote: { simulator: true },
+  // Emulators only: the clipboard is set through the emulator's gRPC
+  // endpoint, which a physical phone does not have. `unknown` is admitted
+  // because an unresolved serial may still be an emulator — the
+  // simulator-server refuses a phone either way.
+  android: { emulator: true, unknown: true }
+  // No `chromium`: the renderer can only reach the HOST clipboard, so a paste
+  // there would overwrite whatever the user has copied. No `vega`: no
+  // clipboard API is exposed by the VVD tooling.
+  //
+  // TV targets are not separate platforms (an Apple TV simulator is
+  // `ios`/`simulator`, an Android TV emulator `android`/`emulator`), so each
+  // handler probes the runtime kind and rejects a TV itself.
+};
+var pasteQueues = /* @__PURE__ */ new Map();
+function serializedPerDevice(deviceId, task) {
+  const previous = pasteQueues.get(deviceId) ?? Promise.resolve();
+  const next = previous.then(task, task);
+  pasteQueues.set(deviceId, next);
+  void next.then(
+    () => {
+      if (pasteQueues.get(deviceId) === next) pasteQueues.delete(deviceId);
+    },
+    () => {
+      if (pasteQueues.get(deviceId) === next) pasteQueues.delete(deviceId);
+    }
+  );
+  return next;
+}
+function createPasteTool(registry2) {
+  const dispatch = dispatchByPlatform({
+    toolId: "paste",
+    capability: capability17,
+    ios: makeIosImpl4(registry2),
+    iosRemote: makeIosRemoteImpl2(registry2),
+    android: makeAndroidImpl2(registry2)
+  });
+  return {
+    id: "paste",
+    interaction: {
+      startedMsg: () => "Pasting text",
+      completedMsg: () => "Pasted text",
+      failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to paste text: ${failureSignal2.error_code}`
+    },
+    description: `Paste text into the focused field: puts \`text\` on the DEVICE clipboard (the host clipboard is untouched), then triggers the platform's paste shortcut (iOS simulator, Android emulator).
+Do NOT use this in place of \`keyboard\`. \`keyboard\` types as a user would and is the default for all text entry; use \`paste\` only where a real user would paste \u2014 a 2FA/OTP code copied from another app, a long link or token, or when testing the app's own paste handling.
+Tap the field first so it has focus. Returns { pasted: true }. Fails on a TV target, when the device clipboard cannot be set, or when the simulator-server build lacks clipboard support.
+Supports \`{{secret:<NAME>}}\` placeholders like \`keyboard\`; the value is never echoed back.`,
+    searchHint: "paste clipboard pasteboard otp 2fa code fill field",
+    zodSchema: pasteZodSchema,
+    capability: capability17,
+    services: () => ({}),
+    execute: async (services, params, options) => {
+      const { text, secrets } = resolveSecretPlaceholders(params.text);
+      return serializedPerDevice(params.udid, async () => {
+        if (secrets.length === 0) return dispatch(services, params, options);
+        try {
+          return await dispatch(services, { ...params, text }, options);
+        } catch (err) {
+          throw redactSecretsFromError(err, secrets);
+        }
+      });
+    }
+  };
+}
+
 // ../tool-server/src/tools/rotate/index.ts
 init_zod();
 var zodSchema25 = external_exports.object({
   udid: external_exports.string().describe("Target device id from `list-devices` (iOS UDID or Android serial)."),
   orientation: external_exports.enum(["Portrait", "LandscapeLeft", "LandscapeRight", "PortraitUpsideDown"]).describe("Target orientation")
 });
-var capability17 = {
+var capability18 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
   android: { emulator: true, device: true, unknown: true }
@@ -122368,7 +122565,7 @@ var rotateTool = {
 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.`,
   zodSchema: zodSchema25,
-  capability: capability17,
+  capability: capability18,
   services: (params) => ({
     simulatorServer: simulatorServerRef(resolveDevice(params.udid))
   }),
@@ -122599,9 +122796,9 @@ async function prepareHostWindowShake(target) {
 var execFileAsync20 = (0, import_node_util20.promisify)(import_node_child_process27.execFile);
 var SHAKE_NOTIFICATION = "com.apple.UIKit.SimulatorShake";
 var SHAKE_INTERVAL_MS = 400;
-var sleep10 = (ms) => new Promise((r) => setTimeout(r, ms));
+var sleep11 = (ms) => new Promise((r) => setTimeout(r, ms));
 var NOTIFYUTIL_ARGV = ["notifyutil", "-p", SHAKE_NOTIFICATION];
-function rejectTv(toolId, device) {
+function rejectTv2(toolId, device) {
   throw new UnsupportedOperationError(
     toolId,
     device,
@@ -122630,11 +122827,11 @@ var iosImpl4 = {
   async handler(_services, params, device) {
     const { udid } = params;
     const count2 = params.count ?? 1;
-    if (await isTvOsSimulator(udid)) rejectTv("shake", device);
+    if (await isTvOsSimulator(udid)) rejectTv2("shake", device);
     const args = await simctlArgsForUdid(udid, ["spawn", udid, ...NOTIFYUTIL_ARGV]);
     const shaker = await prepareHostWindowShake({ kind: "ios", udid, name: device.name });
     for (let i = 0; i < count2; i++) {
-      if (i > 0) await sleep10(SHAKE_INTERVAL_MS);
+      if (i > 0) await sleep11(SHAKE_INTERVAL_MS);
       shaker.begin();
       try {
         await execFileAsync20("xcrun", args, { timeout: 15e3 });
@@ -122652,9 +122849,9 @@ var iosRemoteImpl6 = {
   async handler(_services, params, device) {
     const { udid } = params;
     const count2 = params.count ?? 1;
-    if (await isRemoteTvOsSimulator(udid)) rejectTv("shake", device);
+    if (await isRemoteTvOsSimulator(udid)) rejectTv2("shake", device);
     for (let i = 0; i < count2; i++) {
-      if (i > 0) await sleep10(SHAKE_INTERVAL_MS);
+      if (i > 0) await sleep11(SHAKE_INTERVAL_MS);
       let result;
       try {
         result = await simctlSpawn(udid, { args: NOTIFYUTIL_ARGV });
@@ -122701,7 +122898,7 @@ function restingVectorFrom(stdout) {
   return read;
 }
 var fmt = (v) => `${v.x.toFixed(4)}:${v.y.toFixed(4)}:${v.z.toFixed(4)}`;
-var sleep11 = (ms) => new Promise((r) => setTimeout(r, ms));
+var sleep12 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function emuConsole(serial, args) {
   const { stdout } = await runAdb(["-s", serial, "emu", ...args], { timeoutMs: 1e4 });
   const lines = stdout.split("\n").map((line) => line.trim()).filter(Boolean);
@@ -122775,7 +122972,7 @@ var androidImpl6 = {
               y: rest.y,
               z: rest.z
             });
-            await sleep11(SWING_INTERVAL_MS);
+            await sleep12(SWING_INTERVAL_MS);
           }
         }
       } catch (err) {
@@ -122800,7 +122997,7 @@ var androidImpl6 = {
 };
 
 // ../tool-server/src/tools/shake/index.ts
-var capability18 = {
+var capability19 = {
   // Simulator only. A physical iPhone's motion comes from real hardware; there
   // is no host-side hook to fake it, so `device` stays false and a paired phone
   // gets a clean 400 instead of a silent no-op.
@@ -122838,13 +123035,13 @@ Works on local and remote (sim-remote) iOS simulators.
 Only phone/tablet simulators and emulators are supported.`,
   searchHint: "shake motion accelerometer undo typing dev menu gesture",
   zodSchema: shakeZodSchema,
-  capability: capability18,
+  capability: capability19,
   // Talks to `simctl` / `adb` directly, so no simulator-server is resolved —
   // avoids spawning one (and its ready-wait) for a tool that never uses it.
   services: () => ({}),
   execute: dispatchByPlatform({
     toolId: "shake",
-    capability: capability18,
+    capability: capability19,
     ios: iosImpl4,
     iosRemote: iosRemoteImpl6,
     android: androidImpl6
@@ -122894,14 +123091,14 @@ var APPLE_TV_UNSUPPORTED = /* @__PURE__ */ new Set([
   "volumeDown",
   "mute"
 ]);
-function makeIosImpl4(registry2) {
+function makeIosImpl5(registry2) {
   return {
     handler: (_services, params, device, options) => pressFocusRemote(registry2, device, params, APPLE_TV_UNSUPPORTED, options)
   };
 }
 
 // ../tool-server/src/tools/tv-remote/platforms/android.ts
-function makeAndroidImpl2(registry2) {
+function makeAndroidImpl3(registry2) {
   return {
     requires: ["adb"],
     handler: (_services, params, device, options) => pressFocusRemote(registry2, device, params, void 0, options)
@@ -122947,7 +123144,7 @@ var zodSchema26 = external_exports.object({
     'Repeat the whole `button` value this many times (default 1). Compact for long same-button runs, e.g. { button: "down", repeat: 12 }.'
   )
 });
-var capability19 = {
+var capability20 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true },
   vega: { vvd: true }
@@ -122974,13 +123171,13 @@ Returns { pressed, count }.`,
     longRunning: true,
     searchHint: "tv remote dpad d-pad navigate focus up down left right select ok back home menu play pause rewind fast forward sequence path apple tv tvos android tv leanback vega fire tv",
     zodSchema: zodSchema26,
-    capability: capability19,
+    capability: capability20,
     services: () => ({}),
     execute: dispatchByPlatform({
       toolId: "tv-remote",
-      capability: capability19,
-      ios: makeIosImpl4(registry2),
-      android: makeAndroidImpl2(registry2),
+      capability: capability20,
+      ios: makeIosImpl5(registry2),
+      android: makeAndroidImpl3(registry2),
       vega: vegaImpl5
     })
   };
@@ -129152,7 +129349,7 @@ var conditionCompleted = {
   hidden: "UI element became hidden",
   text: "UI element matched expected text"
 };
-var capability20 = {
+var capability21 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true },
   chromium: { app: true },
@@ -129244,7 +129441,7 @@ or before tapping an element that appears asynchronously.`,
     searchHint: "wait await poll until visible hidden exists text appears disappears timeout element condition settle",
     longRunning: true,
     zodSchema: zodSchema27,
-    capability: capability20,
+    capability: capability21,
     services: (params) => {
       const device = resolveDevice(params.udid);
       if (device.platform === "chromium") {
@@ -129255,7 +129452,7 @@ or before tapping an element that appears asynchronously.`,
     async execute(services, params, ctx) {
       const signal = ctx?.signal;
       const device = resolveDevice(params.udid);
-      assertSupported(AWAIT_UI_ELEMENT_TOOL_ID, capability20, device);
+      assertSupported(AWAIT_UI_ELEMENT_TOOL_ID, capability21, device);
       if (device.platform === "ios") await ensureDeps(iosRequires);
       else if (device.platform === "android") await ensureDeps(androidRequires);
       else if (device.platform === "vega") await ensureDeps(vegaRequires);
@@ -129312,6 +129509,9 @@ var ALLOWED_TOOLS = /* @__PURE__ */ new Set([
   "gesture-rotate",
   "button",
   "keyboard",
+  // `paste` belongs in a sequence for the same reason `keyboard` does: the
+  // focus tap, the paste and the submit are one user action.
+  "paste",
   "rotate",
   // Sequencing matters for shake: the interesting cases are races (shake while
   // a sheet is dismissing, shake right after typing), which need the steps
@@ -129329,7 +129529,7 @@ var zodSchema28 = external_exports.object({
   steps: external_exports.array(
     external_exports.object({
       tool: external_exports.string().describe(
-        "Tool name \u2014 one of: gesture-tap, gesture-swipe, gesture-scroll, gesture-drag, gesture-custom, gesture-pinch, gesture-rotate, button, keyboard, rotate, shake, tv-remote, await-ui-element. On a TV target (Apple TV / Android TV / Vega) use tv-remote (remote presses) and keyboard (text)."
+        "Tool name \u2014 one of: gesture-tap, gesture-swipe, gesture-scroll, gesture-drag, gesture-custom, gesture-pinch, gesture-rotate, button, keyboard, paste, rotate, shake, tv-remote, await-ui-element. On a TV target (Apple TV / Android TV / Vega) use tv-remote (remote presses) and keyboard (text)."
       ),
       args: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Tool arguments (excluding udid, which is injected automatically)"),
       delayMs: external_exports.number().optional().describe(
@@ -129338,7 +129538,7 @@ var zodSchema28 = external_exports.object({
     })
   ).min(1).describe("Ordered list of interaction steps to execute sequentially")
 });
-var capability21 = {
+var capability22 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
   android: { emulator: true, device: true, unknown: true },
@@ -129380,6 +129580,7 @@ Allowed tools and their args (udid is auto-injected, do NOT include it in args):
   button:         { button: "home"|"back"|"power"|"volumeUp"|"volumeDown"|"appSwitch"|"actionButton" }                  [ios/android]
   keyboard:       { text?: string, key?: string, delayMs?: number }  (text OR key per step, never both; TV: text only)  [ios/android/chromium/vega/tv]
                   text supports {{secret:<NAME>}} placeholders, resolved server-side from ARGENT_SECRET_<NAME> env vars or an argent secrets file \u2014 credentials never enter agent context
+  paste:          { text: string }  (device clipboard + paste shortcut; only where a user would paste, e.g. an OTP \u2014 keyboard otherwise)   [ios sim/android emu]
   rotate:         { orientation: "Portrait"|"LandscapeLeft"|"LandscapeRight"|"PortraitUpsideDown" }                     [ios/android]
   shake:          { count?: number }                                                                                    [ios sim/android emu]
   tv-remote:      { button: <remote button | array of them>, repeat?: number }                                          [apple tv/android tv/vega]
@@ -129418,7 +129619,7 @@ Stops on the first error (or unmet await-ui-element condition) and returns parti
     longRunning: true,
     searchHint: "batch sequence multiple gesture steps sequentially",
     zodSchema: zodSchema28,
-    capability: capability21,
+    capability: capability22,
     // No eagerly-declared service: each step resolves its own services through
     // `invokeSubTool` below (simulator-server for iOS/Android, CDP for
     // Chromium), so run-sequence itself needs none. An eager resolver can't be
@@ -131696,7 +131897,7 @@ function formatDescribeTree(root, opts) {
 }
 
 // ../tool-server/src/tools/describe/platforms/tv.ts
-var sleep12 = (ms) => new Promise((r) => setTimeout(r, ms));
+var sleep13 = (ms) => new Promise((r) => setTimeout(r, ms));
 var EMPTY_RETRY_ATTEMPTS = 3;
 var EMPTY_RETRY_DELAY_MS = 600;
 var EMPTY_HINT = "No focusable elements after retrying and recycling the read path. The app is most likely still launching (splash / loading screen) or mid-transition \u2014 this is normal right after launch-app / restart-app. Wait ~2-3s and call describe again; a React Native app only exposes focus once its JS bundle has loaded. If it stays empty, take a screenshot to confirm what's actually on screen.";
@@ -131737,7 +131938,7 @@ async function describeTv(registry2, device) {
   let res = await api.describe();
   if (device.platform !== "android") {
     for (let attempt = 1; attempt < EMPTY_RETRY_ATTEMPTS && isEmpty(res); attempt++) {
-      await sleep12(EMPTY_RETRY_DELAY_MS);
+      await sleep13(EMPTY_RETRY_DELAY_MS);
       res = await api.describe();
     }
   }
@@ -131787,7 +131988,7 @@ var zodSchema38 = external_exports.object({
     "Optional app bundle ID. Used as a target hint on iOS when the AX-service returns no elements and the describe tool falls back to native-devtools inspection. If omitted, the fallback auto-detects the frontmost connected app. Ignored on Android / Chromium."
   )
 });
-var capability22 = {
+var capability23 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
   android: { emulator: true, device: true, unknown: true },
@@ -131797,7 +131998,7 @@ var capability22 = {
 function makeDescribeExecute(registry2) {
   return dispatchByPlatform({
     toolId: "describe",
-    capability: capability22,
+    capability: capability23,
     ios: {
       requires: iosRequires,
       handler: async (_services, params, device) => (
@@ -131882,7 +132083,7 @@ back/menu/home), then call describe again to confirm where focus landed.`,
     alwaysLoad: true,
     searchHint: "accessibility element tree ui hierarchy tap coordinates ios android chromium vega dom tv tvos apple tv android tv fire tv focus focusable remote dpad",
     zodSchema: zodSchema38,
-    capability: capability22,
+    capability: capability23,
     services: (params) => {
       const device = resolveDevice(params.udid);
       if (device.platform === "chromium") {
@@ -131911,7 +132112,7 @@ var zodSchema39 = external_exports.object({
     `The screen must hold the same content for at least this long to count as settled (default ${DEFAULT_MIN_STABLE_MS}).`
   )
 });
-var capability23 = {
+var capability24 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true },
   chromium: { app: true }
@@ -131955,7 +132156,7 @@ still before the timeout. Use after a launch/navigation to wait for the UI to re
     searchHint: "wait until screen settles idle stable stops changing animation transition rendered ready before screenshot",
     longRunning: true,
     zodSchema: zodSchema39,
-    capability: capability23,
+    capability: capability24,
     services: (params) => {
       const device = resolveDevice(params.udid);
       if (device.platform === "chromium") {
@@ -131965,7 +132166,7 @@ still before the timeout. Use after a launch/navigation to wait for the UI to re
     },
     async execute(services, params, ctx) {
       const device = resolveDevice(params.udid);
-      assertSupported(AWAIT_SCREEN_IDLE_TOOL_ID, capability23, device);
+      assertSupported(AWAIT_SCREEN_IDLE_TOOL_ID, capability24, device);
       if (device.platform === "ios") await ensureDeps(iosRequires);
       else if (device.platform === "android") await ensureDeps(androidRequires);
       const isTvOs = device.platform === "ios" && await isTvOsSimulator(device.id);
@@ -138728,7 +138929,7 @@ var zodSchema48 = external_exports.object({
     "iOS-only. When true, cold-launches the app under the profiler with Malloc Stack Logging enabled so memory leaks carry an allocation backtrace (responsible frame + library). Without it, leaks are still detected but unattributable \u2014 Instruments reports '<Call stack limit reached>'. Trade-offs: this RESTARTS the app (current state is lost), adds memory/CPU overhead, and makes the app noticeably slow to launch (every startup allocation records a backtrace), so leave it off for pure CPU/hang profiling. Requires a non-degraded Xcode: on Xcode 26.4 and later the cold-launch path is broken, so the call is rejected up front (re-run without the flag, or set ARGENT_IOS_CAPTURE=device to override if the device path works on your host). ARGENT_IOS_CAPTURE=all-processes \u2014 e.g. exported globally for the normal capture path \u2014 also rejects this flag up front, since that fallback cannot cold-launch; unset it (or set it to device) first. Ignored on Android."
   )
 });
-var capability24 = {
+var capability25 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true }
 };
@@ -138739,7 +138940,7 @@ var nativeProfilerStartTool = {
     completedMsg: () => "Started native profiler",
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to start native profiler: ${failureSignal2.error_code}`
   },
-  capability: capability24,
+  capability: capability25,
   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.
 After starting, let the user interact with the app, then call native-profiler-stop.
@@ -138753,7 +138954,7 @@ Fails if no app is running on the device, or the profiler cannot attach to the p
   async execute(services, params) {
     const api = services.session;
     const device = resolveDevice(params.device_id);
-    assertSupported("native-profiler-start", capability24, device);
+    assertSupported("native-profiler-start", capability25, device);
     if (api.platform === "ios") {
       await ensureDeps(["xcrun"]);
       return startNativeProfilerIos(api, params);
@@ -138770,7 +138971,7 @@ var zodSchema49 = external_exports.object({
     "Target device id from `list-devices` (iOS UDID or Android serial)."
   )
 });
-var capability25 = {
+var capability26 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true }
 };
@@ -138791,7 +138992,7 @@ var nativeProfilerStopTool = {
     completedMsg: ({ result }) => `Saved native profile ${result.traceFile.filename}`,
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to stop native profiler: ${failureSignal2.error_code}`
   },
-  capability: capability25,
+  capability: capability26,
   // Packaging plus the export passes routinely exceed the 30s fetch timeout.
   longRunning: true,
   description: `Stop native profiling and export trace data.
@@ -138808,7 +139009,7 @@ Fails if no active native-profiler-start session exists for the given device_id.
   async execute(services, params, ctx) {
     const api = services.session;
     const device = resolveDevice(params.device_id);
-    assertSupported("native-profiler-stop", capability25, device);
+    assertSupported("native-profiler-stop", capability26, device);
     if (api.platform === "ios") {
       await ensureDeps(["xcrun"]);
       const ios = await stopNativeProfilerIos(api);
@@ -138840,7 +139041,7 @@ var zodSchema50 = external_exports.object({
     "Target device id from `list-devices` (iOS UDID or Android serial)."
   )
 });
-var capability26 = {
+var capability27 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true }
 };
@@ -138851,7 +139052,7 @@ var nativeProfilerAnalyzeTool = {
     completedMsg: () => "Analyzed native profile",
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to analyze native profile: ${failureSignal2.error_code}`
   },
-  capability: capability26,
+  capability: capability27,
   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.
 Android: queries the Perfetto .pftrace via the in-process Perfetto trace-processor engine for CPU hotspots, UI hangs with jank reason + main-thread state breakdown, GC annotation, and an RSS-growth weak signal.
@@ -138868,7 +139069,7 @@ Fails if native-profiler-stop has not been called first to export trace data.`,
   async execute(services, params, ctx) {
     const api = services.session;
     const device = resolveDevice(params.device_id);
-    assertSupported("native-profiler-analyze", capability26, device);
+    assertSupported("native-profiler-analyze", capability27, device);
     let result;
     if (api.platform === "ios") {
       await ensureDeps(["xcrun"]);
@@ -139847,7 +140048,7 @@ var zodSchema51 = external_exports.object({
     "Default true. Draw simulator-server's touch visualizer into the recording: a pulse marks each tap, a comet trail follows swipes and drags, and paired markers show two-finger pinch/rotate, so the video makes clear where every interaction landed. Set false to record the raw screen with no overlay."
   )
 });
-var capability27 = {
+var capability28 = {
   apple: { simulator: true },
   android: { emulator: true, device: true, unknown: true }
 };
@@ -139859,7 +140060,7 @@ function createScreenRecordingStartTool(registry2) {
       completedMsg: () => "Started screen recording",
       failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to start screen recording: ${failureSignal2.error_code}`
     },
-    capability: capability27,
+    capability: capability28,
     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.
 By default every tap, swipe, drag, pinch and rotate is drawn into the video as an on-screen touch marker (see showTouches), so the recording shows where each interaction landed.
@@ -139879,7 +140080,7 @@ Fails if a recording is already running on the device, the device is not booted,
     async execute(services, params) {
       const api = services.session;
       const device = resolveDevice(params.udid);
-      assertSupported("screen-recording-start", capability27, device);
+      assertSupported("screen-recording-start", capability28, device);
       if (device.platform === "ios" && await isTvOsSimulator(params.udid)) {
         throw new FailureError(
           `Screen recording is not supported on tvOS simulators (device ${params.udid}).`,
@@ -139954,7 +140155,7 @@ var zodSchema52 = external_exports.object({
   udid: external_exports.string().describe("Target device id from `list-devices` (iOS Simulator UDID or Android serial).")
 });
 var RECORDINGS_DIR = ".argent/recordings";
-var capability28 = {
+var capability29 = {
   apple: { simulator: true },
   android: { emulator: true, device: true, unknown: true }
 };
@@ -139965,7 +140166,7 @@ var screenRecordingStopTool = {
     completedMsg: ({ result }) => `Saved screen recording ${result.video.filename}`,
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to stop screen recording: ${failureSignal2.error_code}`
   },
-  capability: capability28,
+  capability: capability29,
   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.
 Use when the interaction being captured is finished, or a tool-result note reminds you a recording is still running.
@@ -139979,7 +140180,7 @@ Fails if no recording (running or finished-but-unretrieved) exists for the given
   async execute(services, params, ctx) {
     const api = services.session;
     const device = resolveDevice(params.udid);
-    assertSupported("screen-recording-stop", capability28, device);
+    assertSupported("screen-recording-stop", capability29, device);
     const stopped = await stopCapture(api);
     const artifacts = requireArtifacts(ctx);
     const video = await artifacts.register(stopped.outputFile, {
@@ -150048,7 +150249,7 @@ var zodSchema70 = external_exports.object({
     "Directory where diff artifacts should be written. Optional \u2014 defaults to a temp directory; the diff images are returned in the result either way."
   )
 }).strict();
-var capability29 = {
+var capability30 = {
   apple: { simulator: true, device: true },
   android: { emulator: true, device: true, unknown: true }
 };
@@ -150073,7 +150274,7 @@ Ignores the fixed top status-bar band for both pixel and OCR text comparisons.
 Fails if the input sources are invalid, PNG files cannot be read, outputDir cannot be written, or the simulator-server / emulator backend is not reachable.`,
   searchHint: "compare screenshots png diff visual UI changes UI regression visual regression screenshot diff changed regions text ocr live capture",
   zodSchema: zodSchema70,
-  capability: capability29,
+  capability: capability30,
   fileInputs: fileInputs6,
   services: (params) => {
     if (params.captureBaseline || params.captureCurrent) {
@@ -150472,7 +150673,7 @@ var tabAction = {
     failure: "close"
   }
 };
-var capability30 = {
+var capability31 = {
   chromium: { app: true }
 };
 var chromiumTabsTool = {
@@ -150491,7 +150692,7 @@ Use when an app exposes multiple windows or tabs and you need to inspect or driv
 Returns { tabs: [{ tabId, targetId, title, url, active, label? }] }. Fails if the device is not a Chromium (CDP) device, or the requested tabId/label no longer matches a live tab. Chromium-only.`,
   searchHint: "tab tabs window windows switch select close new open multi-tab chromium electron",
   zodSchema: zodSchema73,
-  capability: capability30,
+  capability: capability31,
   services: (params) => {
     const device = resolveDevice(params.udid);
     if (device.platform === "chromium") {
@@ -150614,7 +150815,7 @@ var cookieAction = {
   delete: { started: "Deleting", completed: "Deleted", failure: "delete" },
   clear: { started: "Clearing", completed: "Cleared", failure: "clear" }
 };
-var capability31 = {
+var capability32 = {
   chromium: { app: true }
 };
 var chromiumCookiesTool = {
@@ -150633,7 +150834,7 @@ Use when seeding an authenticated session before a flow (set the session cookie,
 Returns { cookies, count } for get, or a small status object ({ set } / { deleted } / { cleared }) otherwise. Fails if the device is not a Chromium (CDP) device, or set is missing name/value. Chromium-only.`,
   searchHint: "cookies cookie get set delete clear httponly samesite session auth chromium",
   zodSchema: zodSchema74,
-  capability: capability31,
+  capability: capability32,
   services: (params) => {
     const device = resolveDevice(params.udid);
     if (device.platform === "chromium") {
@@ -150712,7 +150913,7 @@ var storageAction = {
   remove: { started: "Removing from", completed: "Removed from", failure: "remove from" },
   clear: { started: "Clearing", completed: "Cleared", failure: "clear" }
 };
-var capability32 = {
+var capability33 = {
   chromium: { app: true }
 };
 var chromiumStorageTool = {
@@ -150732,7 +150933,7 @@ Use when seeding feature flags / auth tokens before a flow or asserting persiste
 Returns { value } for a single key, { entries, count } for all, or a status object ({ set } / { removed } / { cleared }) otherwise. Fails if the device is not a Chromium (CDP) device, or set is missing key/value. Chromium-only.`,
   searchHint: "storage localstorage sessionstorage local session get set remove clear key value chromium",
   zodSchema: zodSchema75,
-  capability: capability32,
+  capability: capability33,
   services: (params) => {
     const device = resolveDevice(params.udid);
     if (device.platform === "chromium") {
@@ -150820,6 +151021,7 @@ function createRegistry() {
   registry2.registerTool(gestureRotateTool);
   registry2.registerTool(buttonTool);
   registry2.registerTool(createKeyboardTool(registry2));
+  registry2.registerTool(createPasteTool(registry2));
   registry2.registerTool(rotateTool);
   registry2.registerTool(shakeTool);
   registry2.registerTool(createTvRemoteTool(registry2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.21.1-next.16",
+  "version": "0.21.1-next.18",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/skills/argent-device-interact/SKILL.md

@@ -56,27 +56,28 @@ Common schemes: `messages://`, `settings://`, `maps://?q=<query>`, `tel://<numbe
 
 ## 4. Choosing the Right Tool
 
-| Action            | Tool                | Notes                                                            |
-| ----------------- | ------------------- | ---------------------------------------------------------------- |
-| Multiple actions  | `run-sequence`      | Batch steps in one call (no intermediate screenshots)            |
-| Open an app       | `launch-app`        | **Always — never tap home-screen icons**                         |
-| Restart an app    | `restart-app`       | Terminate and relaunch by bundle ID                              |
-| Open URL/scheme   | `open-url`          | Web pages, deep links, URL schemes                               |
-| Single tap        | `gesture-tap`       | Buttons, links, checkboxes                                       |
-| Scroll/swipe      | `gesture-swipe`     | Straight-line scroll or swipe                                    |
-| Scroll (Chromium) | `gesture-scroll`    | Wheel-based; deltas are window fractions, positive deltaY = down |
-| Drag (Chromium)   | `gesture-drag`      | Sliders, drag-and-drop, text selection                           |
-| Long press        | `gesture-custom`    | Context menus, drag start                                        |
-| Drag & drop       | `gesture-custom`    | Complex drag interactions                                        |
-| Pinch/zoom        | `gesture-pinch`     | Two-finger pinch with auto-interpolation                         |
-| Rotation          | `gesture-rotate`    | Two-finger rotation with auto-interpolation                      |
-| Custom gesture    | `gesture-custom`    | Arbitrary touch sequences, optional interpolation                |
-| Hardware key      | `button`            | Home, back, power, volume, appSwitch, actionButton               |
-| Type text         | `keyboard`          | Every platform. Text or one named key per call, never both       |
-| Rotate device     | `rotate`            | Orientation changes                                              |
-| Shake device      | `shake`             | Shake handlers (sim/emu only), Undo-typing prompt, RN dev menu   |
-| Wait for UI       | `await-ui-element`  | Block until an element is visible/hidden/exists/contains text    |
-| Wait for idle     | `await-screen-idle` | Block until a non-empty screen tree stops changing               |
+| Action            | Tool                | Notes                                                             |
+| ----------------- | ------------------- | ----------------------------------------------------------------- |
+| Multiple actions  | `run-sequence`      | Batch steps in one call (no intermediate screenshots)             |
+| Open an app       | `launch-app`        | **Always — never tap home-screen icons**                          |
+| Restart an app    | `restart-app`       | Terminate and relaunch by bundle ID                               |
+| Open URL/scheme   | `open-url`          | Web pages, deep links, URL schemes                                |
+| Single tap        | `gesture-tap`       | Buttons, links, checkboxes                                        |
+| Scroll/swipe      | `gesture-swipe`     | Straight-line scroll or swipe                                     |
+| Scroll (Chromium) | `gesture-scroll`    | Wheel-based; deltas are window fractions, positive deltaY = down  |
+| Drag (Chromium)   | `gesture-drag`      | Sliders, drag-and-drop, text selection                            |
+| Long press        | `gesture-custom`    | Context menus, drag start                                         |
+| Drag & drop       | `gesture-custom`    | Complex drag interactions                                         |
+| Pinch/zoom        | `gesture-pinch`     | Two-finger pinch with auto-interpolation                          |
+| Rotation          | `gesture-rotate`    | Two-finger rotation with auto-interpolation                       |
+| Custom gesture    | `gesture-custom`    | Arbitrary touch sequences, optional interpolation                 |
+| Hardware key      | `button`            | Home, back, power, volume, appSwitch, actionButton                |
+| Type text         | `keyboard`          | Every platform. Text or one named key per call, never both        |
+| Paste text        | `paste`             | Only where a user would paste (OTP code, long link). Sim/emu only |
+| Rotate device     | `rotate`            | Orientation changes                                               |
+| Shake device      | `shake`             | Shake handlers (sim/emu only), Undo-typing prompt, RN dev menu    |
+| Wait for UI       | `await-ui-element`  | Block until an element is visible/hidden/exists/contains text     |
+| Wait for idle     | `await-screen-idle` | Block until a non-empty screen tree stops changing                |
 
 ## 5. Finding Tap Targets
 
@@ -197,6 +198,18 @@ Rules:
 - Nothing outside those sources is reachable; never ask the user to paste a secret value into the conversation. Ask them to put it in a secrets file instead — a file edit applies to the next call, while an exported env var only reaches a tool-server started afterwards.
 - The project sources are found by walking up from the tool-server's working directory. If a project file is not being picked up, the failure's source list shows the paths actually consulted; `~/.argent/secrets.env` needs no project and always applies.
 
+### paste — Paste text into the focused field
+
+```json
+{ "udid": "<UDID>", "text": "482913" }
+```
+
+Puts `text` on the **device** clipboard (the host clipboard is untouched) and triggers the platform's paste shortcut. iOS simulator and Android emulator only; a TV target, a physical device, Chromium and Vega are rejected.
+
+`paste` is **not** a faster `keyboard`. `keyboard` types the way a user types and stays the default for every text entry — a search query, a login, a form field. Reach for `paste` only where a real user would paste: a 2FA / OTP code copied from another app, a long link or token, or to test how the app handles pasted input. It also carries what `keyboard` can't type on a given platform (multi-line text, non-ASCII on Android), but that alone is not a reason to paste — ask whether the user would.
+
+Tap the field first so it has focus; pasting with no focused field is a silent no-op, as with `keyboard`. `text` accepts the same `{{secret:<NAME>}}` placeholders as `keyboard`, with the same auto-screenshot skip.
+
 ### rotate — Change orientation
 
 ```json
@@ -297,7 +310,7 @@ Use the sequencing when:
 
 ### Allowed tools inside `run-sequence`
 
-`gesture-tap`, `gesture-swipe`, `gesture-scroll`, `gesture-drag`, `gesture-custom`, `gesture-pinch`, `gesture-rotate`, `button`, `keyboard`, `rotate`, `await-ui-element`
+`gesture-tap`, `gesture-swipe`, `gesture-scroll`, `gesture-drag`, `gesture-custom`, `gesture-pinch`, `gesture-rotate`, `button`, `keyboard`, `paste`, `rotate`, `shake`, `tv-remote`, `await-ui-element`
 
 The `udid` is shared — do **not** include it in each step's `args`. Optional `delayMs` per step (default 100ms).