@swmansion/argent 0.20.1-next.9 → 0.21.0

package/dist/cli-cmds.mjs

@@ -1435,6 +1435,7 @@ var FAILURE_CODES = {
   CHROMIUM_ELECTRON_EXITED_BEFORE_READY: "CHROMIUM_ELECTRON_EXITED_BEFORE_READY",
   KEYBOARD_KEY_UNSUPPORTED: "KEYBOARD_KEY_UNSUPPORTED",
   KEYBOARD_CHARACTER_UNSUPPORTED: "KEYBOARD_CHARACTER_UNSUPPORTED",
+  KEYBOARD_TEXT_AND_KEY_COMBINED: "KEYBOARD_TEXT_AND_KEY_COMBINED",
   SECRET_PLACEHOLDER_UNKNOWN: "SECRET_PLACEHOLDER_UNKNOWN",
   SCREENSHOT_DIFF_INPUT_INVALID: "SCREENSHOT_DIFF_INPUT_INVALID",
   BOOT_DEVICE_TARGET_SELECTION_INVALID: "BOOT_DEVICE_TARGET_SELECTION_INVALID",
@@ -1801,6 +1802,10 @@ var FLAG_REGISTRY = [
     name: "tool-server-event-log",
     description: "Write structured tool-server lifecycle events to a JSONL file."
   },
+  {
+    name: "microinteractions",
+    description: "Amplify device actions with matching animations of the host window, so what happens on the guest is also visible on the desktop. Purely cosmetic, macOS only, and never affects whether the underlying action succeeds. Off by default."
+  },
   {
     name: "video-watermark",
     description: "Overlay the argent corner watermark on recorded screen videos. On by default; turn it off with `argent disable video-watermark`.",
@@ -8320,7 +8325,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.20.0";
+    return "0.21.0";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -16584,6 +16584,7 @@ var FAILURE_CODES = {
   CHROMIUM_ELECTRON_EXITED_BEFORE_READY: "CHROMIUM_ELECTRON_EXITED_BEFORE_READY",
   KEYBOARD_KEY_UNSUPPORTED: "KEYBOARD_KEY_UNSUPPORTED",
   KEYBOARD_CHARACTER_UNSUPPORTED: "KEYBOARD_CHARACTER_UNSUPPORTED",
+  KEYBOARD_TEXT_AND_KEY_COMBINED: "KEYBOARD_TEXT_AND_KEY_COMBINED",
   SECRET_PLACEHOLDER_UNKNOWN: "SECRET_PLACEHOLDER_UNKNOWN",
   SCREENSHOT_DIFF_INPUT_INVALID: "SCREENSHOT_DIFF_INPUT_INVALID",
   BOOT_DEVICE_TARGET_SELECTION_INVALID: "BOOT_DEVICE_TARGET_SELECTION_INVALID",
@@ -17401,7 +17402,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID3();
 function readCliVersion() {
   if (true) {
-    return "0.20.0";
+    return "0.21.0";
   }
   return "0.0.0";
 }

package/dist/mcp-server.mjs

@@ -16641,6 +16641,7 @@ var FAILURE_CODES = {
   CHROMIUM_ELECTRON_EXITED_BEFORE_READY: "CHROMIUM_ELECTRON_EXITED_BEFORE_READY",
   KEYBOARD_KEY_UNSUPPORTED: "KEYBOARD_KEY_UNSUPPORTED",
   KEYBOARD_CHARACTER_UNSUPPORTED: "KEYBOARD_CHARACTER_UNSUPPORTED",
+  KEYBOARD_TEXT_AND_KEY_COMBINED: "KEYBOARD_TEXT_AND_KEY_COMBINED",
   SECRET_PLACEHOLDER_UNKNOWN: "SECRET_PLACEHOLDER_UNKNOWN",
   SCREENSHOT_DIFF_INPUT_INVALID: "SCREENSHOT_DIFF_INPUT_INVALID",
   BOOT_DEVICE_TARGET_SELECTION_INVALID: "BOOT_DEVICE_TARGET_SELECTION_INVALID",
@@ -19973,7 +19974,7 @@ async function startMcpServer(options) {
           ...content,
           {
             type: "text",
-            text: "Auto-screenshot skipped: the input contains a {{secret:\u2026}} placeholder, and a screenshot of this screen could reveal the typed secret. Submit or navigate away first, then verify the resulting screen as usual."
+            text: "Auto-screenshot skipped: the input contains a {{secret:\u2026}} placeholder, and a screenshot of this screen could reveal the typed secret. The secret is already typed \u2014 do not send the typing step again, or the field will hold two copies of it. Submit or navigate away, then verify the resulting screen as usual. Only this call is covered: the next call is screenshotted normally, and captures the secret if the field is still on screen. To cover the submit as well, put the typing and the submit in ONE `run-sequence` the next time you type a secret."
           }
         ];
       } else if (autoScreenshotOn && udid && shouldAutoScreenshot(params.name)) {

package/dist/tool-server.cjs

@@ -758,6 +758,7 @@ var init_failure_codes = __esm({
       CHROMIUM_ELECTRON_EXITED_BEFORE_READY: "CHROMIUM_ELECTRON_EXITED_BEFORE_READY",
       KEYBOARD_KEY_UNSUPPORTED: "KEYBOARD_KEY_UNSUPPORTED",
       KEYBOARD_CHARACTER_UNSUPPORTED: "KEYBOARD_CHARACTER_UNSUPPORTED",
+      KEYBOARD_TEXT_AND_KEY_COMBINED: "KEYBOARD_TEXT_AND_KEY_COMBINED",
       SECRET_PLACEHOLDER_UNKNOWN: "SECRET_PLACEHOLDER_UNKNOWN",
       SCREENSHOT_DIFF_INPUT_INVALID: "SCREENSHOT_DIFF_INPUT_INVALID",
       BOOT_DEVICE_TARGET_SELECTION_INVALID: "BOOT_DEVICE_TARGET_SELECTION_INVALID",
@@ -85070,7 +85071,7 @@ var require_log = __commonJS({
       if (logLevel === "debug")
         console.log(...messages);
     }
-    function warn(logLevel, warning) {
+    function warn2(logLevel, warning) {
       if (logLevel === "debug" || logLevel === "warn") {
         if (typeof node_process.emitWarning === "function")
           node_process.emitWarning(warning);
@@ -85079,7 +85080,7 @@ var require_log = __commonJS({
       }
     }
     exports2.debug = debug;
-    exports2.warn = warn;
+    exports2.warn = warn2;
   }
 });
 
@@ -90785,6 +90786,10 @@ var FLAG_REGISTRY = [
     name: "tool-server-event-log",
     description: "Write structured tool-server lifecycle events to a JSONL file."
   },
+  {
+    name: "microinteractions",
+    description: "Amplify device actions with matching animations of the host window, so what happens on the guest is also visible on the desktop. Purely cosmetic, macOS only, and never affects whether the underlying action succeeds. Off by default."
+  },
   {
     name: "video-watermark",
     description: "Overlay the argent corner watermark on recorded screen videos. On by default; turn it off with `argent disable video-watermark`.",
@@ -96800,7 +96805,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.20.0";
+    return "0.21.0";
   }
   return "0.0.0";
 }
@@ -98188,7 +98193,7 @@ var import_node_path5 = __toESM(require("node:path"));
 var import_semver = __toESM(require_semver2());
 
 // ../tool-server/package.json
-var version3 = "0.20.0";
+var version3 = "0.21.0";
 
 // ../tool-server/src/utils/update-checker.ts
 var import_update_core = __toESM(require_dist4());
@@ -99604,9 +99609,9 @@ ${debugInfo}`);
     this.#dispose.length = 0;
     if (this.#async.length > 0) {
       try {
-        let warn;
+        let warn2;
         const timeout = new Promise((resolve11) => {
-          warn = setTimeout(() => {
+          warn2 = setTimeout(() => {
             if (DEV) {
               console.warn("spawn is still running after 5s; continuing anyway", this.#stack);
             }
@@ -99614,8 +99619,8 @@ ${debugInfo}`);
           }, 5e3);
         });
         await Promise.race([Promise.all(this.#async), timeout]);
-        if (warn)
-          clearTimeout(warn);
+        if (warn2)
+          clearTimeout(warn2);
         this.#async.length = 0;
       } catch (error52) {
         console.error("async effect error", error52);
@@ -119222,6 +119227,18 @@ function readMb(config2, key2) {
   return (m[2] || "M").toLowerCase().startsWith("g") ? n * 1024 : n;
 }
 
+// ../tool-server/src/utils/no-window-env.ts
+var TRUTHY = /* @__PURE__ */ new Set(["1", "true", "yes"]);
+function truthyEnv(name) {
+  return TRUTHY.has((process.env[name] ?? "").trim().toLowerCase());
+}
+function iosHeadlessFromEnv() {
+  return truthyEnv("ARGENT_SIMULATOR_NO_WINDOW");
+}
+function androidHeadlessFromEnv() {
+  return truthyEnv("ARGENT_EMULATOR_NO_WINDOW");
+}
+
 // ../tool-server/src/utils/vega-vvd.ts
 init_src();
 init_adb();
@@ -119764,14 +119781,6 @@ function selectGpuMode() {
   }
   return process.platform === "linux" ? "swiftshader" : "auto";
 }
-function selectExtraEmulatorArgs() {
-  const trimmed = (process.env.ARGENT_EMULATOR_NO_WINDOW ?? "").trim().toLowerCase();
-  return ["1", "true", "yes"].includes(trimmed) ? ["-no-window"] : [];
-}
-function iosHeadlessFromEnv() {
-  const trimmed = (process.env.ARGENT_SIMULATOR_NO_WINDOW ?? "").trim().toLowerCase();
-  return ["1", "true", "yes"].includes(trimmed);
-}
 var BOOT_POLL_INTERVALS_MS = {
   serialByAvd: 1500,
   // findSerialByAvdName: re-scan when >1 new emulator appeared
@@ -120155,7 +120164,7 @@ async function bootAndroidImpl(params) {
   await ensureDep("adb");
   await ensureDep("emulator");
   const gpuMode = selectGpuMode();
-  const extraEmulatorArgs = selectExtraEmulatorArgs();
+  const extraEmulatorArgs = androidHeadlessFromEnv() ? ["-no-window"] : [];
   for (const msg of linuxBootDiagnostics(params.avdName) ?? []) {
     console.warn(`[boot-device:linux] ${msg}`);
   }
@@ -122653,6 +122662,7 @@ Fails if the device backend is not reachable \u2014 the simulator-server for iOS
 
 // ../tool-server/src/tools/keyboard/index.ts
 init_zod();
+init_src();
 
 // ../tool-server/src/utils/secrets.ts
 init_src();
@@ -122813,21 +122823,6 @@ async function typeSimulatorServer(registry2, device, params) {
     }
     keysPressed++;
   };
-  let namedKeyCode;
-  if (params.key) {
-    const lower = params.key.toLowerCase();
-    namedKeyCode = Object.hasOwn(NAMED_KEYS, lower) ? NAMED_KEYS[lower] : void 0;
-    if (namedKeyCode == null) {
-      throw new InvalidToolInputError(
-        `Unknown key "${params.key}". Supported: ${Object.keys(NAMED_KEYS).join(", ")}`,
-        {
-          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
-          failure_stage: "keyboard_named_key_simulator",
-          error_kind: "unsupported"
-        }
-      );
-    }
-  }
   if (params.text) {
     for (const char of params.text) {
       const press = charToKeyPress(char);
@@ -122841,7 +122836,19 @@ async function typeSimulatorServer(registry2, device, params) {
       await sleep8(delay2);
     }
   }
-  if (namedKeyCode != null) {
+  if (params.key) {
+    const lower = params.key.toLowerCase();
+    const namedKeyCode = Object.hasOwn(NAMED_KEYS, lower) ? NAMED_KEYS[lower] : void 0;
+    if (namedKeyCode == null) {
+      throw new InvalidToolInputError(
+        `Unknown key "${params.key}". Supported: ${Object.keys(NAMED_KEYS).join(", ")}`,
+        {
+          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
+          failure_stage: "keyboard_named_key_simulator",
+          error_kind: "unsupported"
+        }
+      );
+    }
     await pressKeyCode(namedKeyCode);
   }
   return { typed: params.text ?? params.key ?? "", keys: keysPressed };
@@ -122890,15 +122897,14 @@ function makeIosRemoteImpl(registry2) {
 init_adb();
 async function typeAndroidPhone(device, params) {
   let keysPressed = 0;
-  if (params.text) assertTypeableAndroidText(params.text);
-  if (params.key) {
-    await injectAndroidNamedKey(device.id, params.key);
-    keysPressed++;
-  }
   if (params.text) {
     await injectAndroidText(device.id, params.text);
     keysPressed += params.text.length;
   }
+  if (params.key) {
+    await injectAndroidNamedKey(device.id, params.key);
+    keysPressed++;
+  }
   return { typed: params.text ?? params.key ?? "", keys: keysPressed };
 }
 function makeAndroidImpl(registry2) {
@@ -122987,21 +122993,6 @@ var sleep9 = (ms) => new Promise((r) => setTimeout(r, ms));
 async function runChromium(api, params) {
   const delay2 = params.delayMs ?? 50;
   let keysPressed = 0;
-  let named;
-  if (params.key) {
-    const lower = params.key.toLowerCase();
-    named = Object.hasOwn(CHROMIUM_NAMED_KEYS, lower) ? CHROMIUM_NAMED_KEYS[lower] : void 0;
-    if (!named) {
-      throw new InvalidToolInputError(
-        `Unknown key "${params.key}". Supported: ${Object.keys(CHROMIUM_NAMED_KEYS).join(", ")}`,
-        {
-          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
-          failure_stage: "keyboard_named_key_chromium",
-          error_kind: "unsupported"
-        }
-      );
-    }
-  }
   if (params.text) {
     for (const char of params.text) {
       const desc = charToChromiumKey(char);
@@ -123029,7 +123020,19 @@ async function runChromium(api, params) {
       await sleep9(delay2);
     }
   }
-  if (named) {
+  if (params.key) {
+    const lower = params.key.toLowerCase();
+    const named = Object.hasOwn(CHROMIUM_NAMED_KEYS, lower) ? CHROMIUM_NAMED_KEYS[lower] : void 0;
+    if (!named) {
+      throw new InvalidToolInputError(
+        `Unknown key "${params.key}". Supported: ${Object.keys(CHROMIUM_NAMED_KEYS).join(", ")}`,
+        {
+          error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
+          failure_stage: "keyboard_named_key_chromium",
+          error_kind: "unsupported"
+        }
+      );
+    }
     await api.dispatchKeyEvent({
       type: "keyDown",
       key: named.key,
@@ -123128,7 +123131,7 @@ async function injectViaInputd(subcommands) {
 async function injectVegaButtons(buttons) {
   await injectViaInputd(remoteButtonsToKeycodes(buttons).map((code) => `button_press ${code}`));
 }
-function resolveVegaNamedKeycode(name) {
+async function injectVegaNamedKey(name) {
   const lower = name.toLowerCase();
   const code = Object.hasOwn(NAMED_KEYCODES, lower) ? NAMED_KEYCODES[lower] : void 0;
   if (!code) {
@@ -123141,10 +123144,7 @@ function resolveVegaNamedKeycode(name) {
       }
     );
   }
-  return code;
-}
-async function injectVegaNamedKey(name) {
-  await injectViaInputd([`button_press ${resolveVegaNamedKeycode(name)}`]);
+  await injectViaInputd([`button_press ${code}`]);
 }
 async function injectVegaText(text) {
   if (/[\n\r]/.test(text)) {
@@ -123160,7 +123160,6 @@ async function injectVegaText(text) {
 // ../tool-server/src/tools/keyboard/platforms/vega.ts
 async function runVega2(params) {
   let keysPressed = 0;
-  if (params.key) resolveVegaNamedKeycode(params.key);
   if (params.text) {
     await injectVegaText(params.text);
     keysPressed += [...params.text].length;
@@ -123182,10 +123181,10 @@ var zodSchema24 = external_exports.object({
     "Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, or Chromium id)."
   ),
   text: external_exports.string().optional().describe(
-    'Text to type character by character. Handles uppercase and common punctuation. To type a credential without its plaintext ever entering your context, use a secret placeholder: `{{secret:<NAME>}}` \u2014 e.g. text: "{{secret:APP_PASSWORD}}". The value is resolved on the machine running the tool-server, from the first source that defines the name: the `ARGENT_SECRET_<NAME>` environment variable, `.argent/secrets.env` in the project, the project\'s `.env.local` / `.env` (only their `ARGENT_SECRET_`-prefixed keys), then `~/.argent/secrets.env`. Nothing else on the host is reachable. Placeholders can be embedded in longer text and are never echoed back resolved. If the secret you need is not set, the failure lists the available names and every source it looked in \u2014 ask the user to add it to one of them (a secrets file applies immediately; an env var needs a restart), NEVER ask the user to paste the secret value into the conversation.'
+    'Text to type character by character. Cannot be combined with `key` in one call \u2014 one call per action; to type and then press a key, put two `keyboard` steps in one `run-sequence`. Handles uppercase and common punctuation. To type a credential without its plaintext ever entering your context, use a secret placeholder: `{{secret:<NAME>}}` \u2014 e.g. text: "{{secret:APP_PASSWORD}}". The value is resolved on the machine running the tool-server, from the first source that defines the name: the `ARGENT_SECRET_<NAME>` environment variable, `.argent/secrets.env` in the project, the project\'s `.env.local` / `.env` (only their `ARGENT_SECRET_`-prefixed keys), then `~/.argent/secrets.env`. Nothing else on the host is reachable. Placeholders can be embedded in longer text and are never echoed back resolved. If the secret you need is not set, the failure lists the available names and every source it looked in \u2014 ask the user to add it to one of them (a secrets file applies immediately; an env var needs a restart), NEVER ask the user to paste the secret value into the conversation.'
   ),
   key: external_exports.string().optional().describe(
-    "Named key to press: enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1\u2013f12. When combined with `text`, the key is pressed AFTER the text is typed (so text + enter types and submits). Not supported on TV targets \u2014 move focus with `tv-remote` (up/down/left/right) instead."
+    "Named key to press: enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1\u2013f12. Cannot be combined with `text` in one call \u2014 one call per action; to type and then press a key, put two `keyboard` steps in one `run-sequence`. Not supported on TV targets \u2014 move focus with `tv-remote` (up/down/left/right) instead."
   ),
   delayMs: external_exports.number().optional().describe(
     "Delay in ms between key presses (default 50). Ignored on Android phones/tablets (typed via `adb input text`, which has no per-key cadence), on Vega (text/keys injected in a single shot), and on TV targets (Apple TV / Android TV type the whole string at the daemon's own cadence)."
@@ -123214,25 +123213,29 @@ function createKeyboardTool(registry2) {
       // 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` still words a text+key request because it renders BEFORE
+      // `execute` rejects the combination — and likewise words `{ key: "" }` as
+      // a key press, which `execute` also rejects. `completedMsg` runs only
+      // after a call that succeeded, so it sees neither. Each formatter
+      // therefore has to word a different set of shapes, and the empty
+      // request — neither parameter, a documented no-op — reaches both.
       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";
-      },
+      completedMsg: ({ params }) => params.text === void 0 ? "Pressed a key" : "Entered text",
       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.
-- text: types a string (supports uppercase, digits, common punctuation). To type a credential, use \`{{secret:<NAME>}}\` \u2014 resolved server-side from the \`ARGENT_SECRET_<NAME>\` env var or an argent secrets file (\`.argent/secrets.env\` in the project, \`~/.argent/secrets.env\`, or an \`ARGENT_SECRET_\`-prefixed key in the project's \`.env\`/\`.env.local\`), so the plaintext never enters agent context; the result echoes the placeholder, not the value, and the after-typing auto-screenshot is skipped.
+Returns { typed: string, keys: number }. Fails if text and key are both given in one call (rejected before anything is typed), if an unsupported key name is provided, or if the device's input backend is not reachable.
+A failure is not rolled back. An unsupported key name is always rejected before anything is sent. Un-typeable text is not: the iOS simulator and Chromium reject it mid-string and leave the characters before it in the field (Android, Vega and TV targets check the whole string up front). A transport failure partway also leaves the text already sent. On a retry, read the field's actual contents \u2014 do not assume it is unchanged.
+- text: types a string (supports uppercase, digits, common punctuation). To type a credential, use \`{{secret:<NAME>}}\` \u2014 resolved server-side from the \`ARGENT_SECRET_<NAME>\` env var or an argent secrets file (\`.argent/secrets.env\` in the project, \`~/.argent/secrets.env\`, or an \`ARGENT_SECRET_\`-prefixed key in the project's \`.env\`/\`.env.local\`), so the plaintext never enters agent context; the result echoes the placeholder, not the value, and the after-typing auto-screenshot is skipped. To submit after typing a secret, put both steps in ONE \`run-sequence\` \u2014 that keeps the skip covering the Enter, which a second bare \`keyboard\` call would not.
 - key: presses a single named key (enter, escape, backspace, tab, arrow-up/down/left/right, f1\u2013f12) \u2014 NOT supported on TV targets; move focus with \`tv-remote\` instead.
 On a TV target (runtimeKind 'tv') only \`text\` applies \u2014 focus a text field first (with \`tv-remote\`), then type into it (injected HID keyboard on Apple TV, \`adb input text\` on Android TV).
-Provide text, key, or both \u2014 when both are given, the text is typed first and the key is pressed after it (text + key:"enter" types and submits).`,
+One call does one action: pass text OR key, never both. To type and then press a key, send two \`keyboard\` steps in one \`run-sequence\` \u2014 { text: "hello" } then { key: "enter" } \u2014 which also keeps it to a single round-trip.`,
     zodSchema: zodSchema24,
     capability: capability16,
     searchHint: "type text keyboard input named key enter escape arrow tv vega fire tv search field hid leanback",
@@ -123241,6 +123244,46 @@ Provide text, key, or both \u2014 when both are given, the text is typed first a
     // async and a tvOS udid must never resolve simulator-server.
     services: () => ({}),
     execute: async (services, params, options) => {
+      if (params.text !== void 0 && params.key !== void 0) {
+        throw new InvalidToolInputError(
+          // Says what did NOT happen, so the caller retries instead of first
+          // inspecting the field — and spells the retry out with a literal
+          // example rather than an ellipsis the Android backend can't type.
+          //
+          // The TV caveat is carried statically rather than by probing the
+          // target: this guard runs above the dispatch precisely so a combined
+          // request reaches no device, and distinguishing a TV kind is an async
+          // probe. Without it the prescribed `{ key: "enter" }` is a retry that
+          // cannot succeed on a TV, where `key` is rejected outright
+          // (platforms/tv.ts) — which is the diagnosis this guard would
+          // otherwise pre-empt.
+          'keyboard takes `text` or `key`, not both \u2014 nothing was typed. To type and then press a key, send two `keyboard` steps in one `run-sequence`: { text: "hello" } followed by { key: "enter" }. On a TV target (Apple TV / Android TV) `key` is not supported at all \u2014 type with `text` and move focus with `tv-remote` (up/down/left/right/select).' + // The one-`run-sequence` form and two bare calls are NOT equivalent
+          // once the text carries a placeholder, and this message is where an
+          // agent converts a combined secret call — the tool description's
+          // caveat is read long before that moment, if at all. The check is
+          // syntactic (the same `.includes` flow-utils.ts uses), so the guard
+          // still resolves nothing.
+          (params.text.includes(SECRET_PLACEHOLDER_MARKER) ? " This `text` carries a `" + SECRET_PLACEHOLDER_MARKER + '...}}` placeholder, so keep both steps in that ONE `run-sequence` rather than splitting them into two bare calls: the auto-screenshot skip is decided per tool call from the whole request, and a separate { key: "enter" } call carries no placeholder \u2014 its screenshot is taken after the key lands and can capture the still-visible secret.' : ""),
+          {
+            error_code: FAILURE_CODES.KEYBOARD_TEXT_AND_KEY_COMBINED,
+            failure_stage: "keyboard_text_and_key_combined"
+          }
+        );
+      }
+      if (params.key === "") {
+        throw new InvalidToolInputError(
+          // Names the omission as the alternative, because a caller that sent an
+          // empty string usually built the value from something absent.
+          "`key` is an empty string, which names no key \u2014 nothing was pressed. Pass a named key (enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1\u2013f12), or omit `key` if there is nothing to press.",
+          {
+            // The same code an unknown name gets, because that is what this is:
+            // one telemetry bucket for every unusable `key` value.
+            error_code: FAILURE_CODES.KEYBOARD_KEY_UNSUPPORTED,
+            failure_stage: "keyboard_named_key_empty",
+            error_kind: "unsupported"
+          }
+        );
+      }
       if (params.text === void 0) return dispatch(services, params, options);
       const { text, secrets } = resolveSecretPlaceholders(params.text);
       if (secrets.length === 0) return dispatch(services, params, options);
@@ -123300,10 +123343,211 @@ var shakeZodSchema = external_exports.object({
 });
 
 // ../tool-server/src/tools/shake/platforms/ios.ts
-var import_node_child_process26 = require("node:child_process");
+var import_node_child_process27 = require("node:child_process");
 var import_node_util20 = require("node:util");
 init_src();
-var execFileAsync20 = (0, import_node_util20.promisify)(import_node_child_process26.execFile);
+
+// ../tool-server/src/utils/window-shake.ts
+var import_node_child_process26 = require("node:child_process");
+var MICROINTERACTIONS_FLAG = "microinteractions";
+var AMPLITUDE = 22;
+var STEPS = 60;
+var OSASCRIPT_TIMEOUT_MS = 5e3;
+var ORIGIN_MARKER = "ARGENT_WINDOW_ORIGIN:";
+function warn(detail) {
+  process.stderr.write(`[shake:window] skipped the window animation: ${detail}
+`);
+}
+function asStringLiteral(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function titleMatchLookup(procNamesExpr, needles) {
+  return `
+	set win to missing value
+	set needles to {${needles.map(asStringLiteral).join(", ")}}
+	set procNames to ${procNamesExpr}
+	repeat with procRef in procNames
+		set procName to contents of procRef
+		set winTitles to {}
+		try
+			tell process procName to set winTitles to name of every window
+		end try
+		repeat with idx from 1 to (count of winTitles)
+			set winTitle to item idx of winTitles
+			-- A GUI app can carry an unnamed helper window alongside the real one.
+			if winTitle is not missing value then
+				repeat with needle in needles
+					if winTitle contains (contents of needle) then
+						set win to window idx of process procName
+						exit repeat
+					end if
+				end repeat
+			end if
+			if win is not missing value then exit repeat
+		end repeat
+		if win is not missing value then exit repeat
+	end repeat`;
+}
+function windowLookup(needles) {
+  if (needles.length === 0) {
+    return `
+	set win to missing value
+	repeat with procRef in {"Simulator", "Device Hub"}
+		-- A repeat variable is a reference into the list and "process <ref>"
+		-- will not coerce one, so without "contents of" the lookup misses.
+		set procName to contents of procRef
+		if exists (process procName) then
+			tell process procName
+				if (count of windows) > 0 then set win to window 1
+			end tell
+		end if
+		if win is not missing value then exit repeat
+	end repeat`;
+  }
+  return titleMatchLookup(
+    `name of every process whose name is "Simulator" or name is "Device Hub"`,
+    needles
+  );
+}
+var WOBBLE_OFFSETS = Array.from(
+  { length: STEPS + 1 },
+  (_, i) => {
+    const t = i / STEPS;
+    const decay = Math.exp(-4 * t);
+    const phase = 2 * Math.PI * 3.5 * t;
+    return [
+      Math.round(AMPLITUDE * decay * Math.sin(phase)),
+      Math.round(AMPLITUDE / 3 * decay * Math.sin(2 * phase))
+    ];
+  }
+);
+var OFFSETS_LITERAL = WOBBLE_OFFSETS.map(([dx, dy]) => `{${dx}, ${dy}}`).join(", ");
+function animationScript(needles) {
+  return `on run
+	tell application "System Events"${windowLookup(needles)}
+		if win is missing value then error "no matching window"
+		set origin to position of win
+		set ox to item 1 of origin
+		set oy to item 2 of origin
+		log "${ORIGIN_MARKER}" & ox & "," & oy
+
+		set offsets to {${OFFSETS_LITERAL}}
+		repeat with pair in offsets
+			set position of win to {ox + (item 1 of pair), oy + (item 2 of pair)}
+		end repeat
+
+		set position of win to {ox, oy}
+		delay 0.05
+		set position of win to {ox, oy}
+	end tell
+end run
+`;
+}
+function restoreScript(needles, ox, oy) {
+  return `on run
+	tell application "System Events"${windowLookup(needles)}
+		if win is missing value then error "no matching window"
+		set position of win to {${ox}, ${oy}}
+	end tell
+end run
+`;
+}
+function runOsascript(script) {
+  return new Promise((resolve11, reject) => {
+    const child = (0, import_node_child_process26.execFile)(
+      "/usr/bin/osascript",
+      ["-"],
+      { timeout: OSASCRIPT_TIMEOUT_MS },
+      (err, _stdout, stderr) => {
+        if (err) {
+          const raw = String(stderr ?? "");
+          const detail = raw.split("\n").filter((line) => !line.includes(ORIGIN_MARKER)).join("\n").trim() || err.message || "osascript failed";
+          const failure = new Error(detail);
+          failure.wasKilled = Boolean(
+            err.killed || err.signal
+          );
+          failure.rawStderr = raw;
+          reject(failure);
+          return;
+        }
+        resolve11();
+      }
+    );
+    child.on("error", (err) => reject(err));
+    child.stdin?.on("error", () => {
+    });
+    child.stdin?.end(script);
+  });
+}
+async function restoreOriginAfterKill(needles, rawStderr) {
+  const match = rawStderr.match(new RegExp(`${ORIGIN_MARKER}\\s*(-?\\d+)\\s*,\\s*(-?\\d+)`));
+  if (!match) return;
+  try {
+    await runOsascript(restoreScript(needles, Number(match[1]), Number(match[2])));
+  } catch {
+  }
+}
+async function prepareHostWindowShake(target) {
+  const inert = { begin: () => {
+  }, settle: () => Promise.resolve() };
+  try {
+    if (!isFeatureEnabled(MICROINTERACTIONS_FLAG)) return inert;
+    if (process.platform !== "darwin") return inert;
+    if (iosHeadlessFromEnv()) return inert;
+    let deviceSet = null;
+    try {
+      deviceSet = await deviceSetForUdid(target.udid);
+    } catch {
+    }
+    if (deviceSet !== null) return inert;
+    const needles = target.name ? [target.name] : [];
+    const script = animationScript(needles);
+    let inFlight = null;
+    let dead = false;
+    let warned2 = false;
+    const warnOnce = (detail) => {
+      if (warned2) return;
+      warned2 = true;
+      warn(detail);
+    };
+    return {
+      begin() {
+        if (dead || inFlight !== null) return;
+        let run2;
+        try {
+          run2 = runOsascript(script);
+        } catch (err) {
+          dead = true;
+          warnOnce(err instanceof Error ? err.message : String(err));
+          return;
+        }
+        inFlight = run2.then(
+          () => {
+            inFlight = null;
+          },
+          async (err) => {
+            dead = true;
+            const failure = err;
+            if (failure.wasKilled && typeof failure.rawStderr === "string") {
+              await restoreOriginAfterKill(needles, failure.rawStderr);
+            }
+            warnOnce(err instanceof Error ? err.message : String(err));
+            inFlight = null;
+          }
+        );
+      },
+      settle() {
+        return inFlight ?? Promise.resolve();
+      }
+    };
+  } catch (err) {
+    warn(err instanceof Error ? err.message : String(err));
+    return inert;
+  }
+}
+
+// ../tool-server/src/tools/shake/platforms/ios.ts
+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));
@@ -123339,8 +123583,10 @@ var iosImpl4 = {
     const count2 = params.count ?? 1;
     if (await isTvOsSimulator(udid)) rejectTv("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);
+      shaker.begin();
       try {
         await execFileAsync20("xcrun", args, { timeout: 15e3 });
       } catch (err) {
@@ -123348,6 +123594,7 @@ var iosImpl4 = {
         throw shakeFailure(udid, error52.message, error52);
       }
     }
+    await shaker.settle();
     return { shaken: true, count: count2 };
   }
 };
@@ -130065,7 +130312,8 @@ function createRunSequenceTool(registry2) {
 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).
 Returns { completed, total, steps } with per-step results. Fails if an unrecognised tool name is used in a step (error returned at that step, execution stops).
-No screenshot is captured automatically \u2014 call screenshot separately after the sequence if needed.
+One screenshot is captured automatically after the whole sequence (not per step) \u2014 call screenshot separately only for a baseline BEFORE it, or to observe an intermediate step.
+That single capture is also why a secret belongs in this call rather than in two bare ones: the skip is decided from the whole request, so a \`{{secret:...}}\` in any step suppresses the capture that would otherwise follow the submit.
 
 ONLY use this when every step is known in advance. If any step depends on the
 result of a previous one (e.g. tapping a menu item that only appears after
@@ -130081,7 +130329,7 @@ Allowed tools and their args (udid is auto-injected, do NOT include it in args):
   gesture-pinch:  { centerX: number, centerY: number, startDistance: number, endDistance: number, endCenterX?: number, endCenterY?: number, angle?: number, durationMs?: number }  [ios/android]
   gesture-rotate: { centerX: number, centerY: number, radius?: number, radiusX?: number, radiusY?: number, startAngle: number, endAngle: number, durationMs?: number }  [ios/android]
   button:         { button: "home"|"back"|"power"|"volumeUp"|"volumeDown"|"appSwitch"|"actionButton" }                  [ios/android]
-  keyboard:       { text?: string, key?: string, delayMs?: number }  (key pressed after text; TV: text only)            [ios/android/chromium/vega/tv]
+  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
   rotate:         { orientation: "Portrait"|"LandscapeLeft"|"LandscapeRight"|"PortraitUpsideDown" }                     [ios/android]
   shake:          { count?: number }                                                                                    [ios sim/android emu]
@@ -130096,9 +130344,10 @@ Example \u2014 scroll down three times (use gesture-scroll with positive deltaY
     { "tool": "gesture-swipe", "args": { "fromX": 0.5, "fromY": 0.7, "toX": 0.5, "toY": 0.3 } }
   ]}
 
-Example \u2014 type text and submit (one step: the key is pressed after the text is typed):
+Example \u2014 type text and submit (two keyboard steps; one call cannot carry both):
   { "udid": "<UDID>", "steps": [
-    { "tool": "keyboard", "args": { "text": "hello world", "key": "enter" } }
+    { "tool": "keyboard", "args": { "text": "hello world" } },
+    { "tool": "keyboard", "args": { "key": "enter" } }
   ]}
 
 Example \u2014 TV: move focus right twice then activate (one tv-remote step with a path is cheaper):
@@ -142733,7 +142982,7 @@ Returns { stopped } - the URNs of the services that were actually live and got s
 
 // ../tool-server/src/tools/simulator/stop-metro.ts
 init_zod();
-var import_node_child_process27 = require("node:child_process");
+var import_node_child_process28 = require("node:child_process");
 function parseNetstatListeningPids(netstatOutput, port) {
   const pids = /* @__PURE__ */ new Set();
   for (const line of netstatOutput.split(/\r?\n/)) {
@@ -142749,7 +142998,7 @@ function parseNetstatListeningPids(netstatOutput, port) {
 }
 function listeningPids(port) {
   if (process.platform === "win32") {
-    const output2 = (0, import_node_child_process27.execFileSync)("netstat", ["-ano"], {
+    const output2 = (0, import_node_child_process28.execFileSync)("netstat", ["-ano"], {
       encoding: "utf-8",
       timeout: 5e3,
       // `netstat -ano` dumps every socket on the host; a busy box easily
@@ -142759,7 +143008,7 @@ function listeningPids(port) {
     });
     return parseNetstatListeningPids(output2, port);
   }
-  const output = (0, import_node_child_process27.execFileSync)("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
+  const output = (0, import_node_child_process28.execFileSync)("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
     encoding: "utf-8",
     timeout: 5e3
   }).trim();
@@ -148760,10 +149009,10 @@ async function runSnapshot(env, opts) {
 }
 
 // ../tool-server/src/utils/status-bar.ts
-var import_node_child_process28 = require("node:child_process");
+var import_node_child_process29 = require("node:child_process");
 var import_node_util21 = require("node:util");
 init_adb();
-var execFileAsync23 = (0, import_node_util21.promisify)(import_node_child_process28.execFile);
+var execFileAsync23 = (0, import_node_util21.promisify)(import_node_child_process29.execFile);
 var DEMO_BROADCAST = "am broadcast -a com.android.systemui.demo";
 async function pinStatusBar(device) {
   try {
@@ -150115,7 +150364,7 @@ init_zod();
 // ../tool-server/src/utils/workspace-reader.ts
 var import_promises12 = require("node:fs/promises");
 var import_node_path21 = require("node:path");
-var import_node_child_process29 = require("node:child_process");
+var import_node_child_process30 = require("node:child_process");
 var import_dotenv2 = __toESM(require_main());
 async function exists(path40) {
   try {
@@ -150159,7 +150408,7 @@ async function listDir(path40) {
 var COMMAND_TIMEOUT_MS = 3e3;
 function runVersionCommand(cmd, args, cwd) {
   return new Promise((resolve11) => {
-    const child = (0, import_node_child_process29.execFile)(cmd, args, { cwd, timeout: COMMAND_TIMEOUT_MS }, (err, stdout) => {
+    const child = (0, import_node_child_process30.execFile)(cmd, args, { cwd, timeout: COMMAND_TIMEOUT_MS }, (err, stdout) => {
       if (err) {
         resolve11(null);
         return;
@@ -150448,7 +150697,7 @@ Fails if the workspacePath is not an absolute path or the directory cannot be ac
 };
 
 // ../tool-server/src/tools/system/update-argent.ts
-var import_node_child_process30 = require("node:child_process");
+var import_node_child_process31 = require("node:child_process");
 var fs51 = __toESM(require("node:fs"));
 var path36 = __toESM(require("node:path"));
 init_zod();
@@ -150583,7 +150832,7 @@ var updateArgentTool = {
       if (spawnRoot) updateArgs.push("--project-root", spawnRoot);
       const cmd = cliEntry ? process.execPath : "argent";
       const args = cliEntry ? [cliEntry, ...updateArgs] : updateArgs;
-      const child = (0, import_node_child_process30.spawn)(cmd, args, {
+      const child = (0, import_node_child_process31.spawn)(cmd, args, {
         detached: true,
         stdio: "ignore",
         env: { ...process.env, ARGENT_UPDATE_TRIGGER: "mcp_update" }
@@ -150723,6 +150972,14 @@ async function resolveOutputDir(params, options) {
   if (params.outputDir && (probe3 === void 0 || probe3.presentOnHost)) {
     return params.outputDir;
   }
+  if (params.outputDir) {
+    try {
+      await import_promises13.default.mkdir(params.outputDir);
+      return params.outputDir;
+    } catch (err) {
+      if (err.code === "EEXIST") return params.outputDir;
+    }
+  }
   const dir = import_path10.default.join(
     import_node_os13.default.tmpdir(),
     "argent-screenshot-diff",
@@ -151501,9 +151758,9 @@ function probeArgentToolServer(host, port, timeoutMs = 500) {
 
 // ../tool-server/src/utils/simulator-watcher.ts
 var fs53 = __toESM(require("node:fs"));
-var import_node_child_process31 = require("node:child_process");
+var import_node_child_process32 = require("node:child_process");
 var import_node_util22 = require("node:util");
-var execFileAsync24 = (0, import_node_util22.promisify)(import_node_child_process31.execFile);
+var execFileAsync24 = (0, import_node_util22.promisify)(import_node_child_process32.execFile);
 var POLL_INTERVAL_MS2 = 1e4;
 async function getBootedUdidsInSet(deviceSet) {
   const { stdout } = await execFileAsync24("xcrun", [
@@ -151579,7 +151836,7 @@ function startSimulatorWatcher(registry2) {
 }
 
 // ../tool-server/src/utils/preview-window.ts
-var import_node_child_process32 = require("node:child_process");
+var import_node_child_process33 = require("node:child_process");
 var fs54 = __toESM(require("node:fs"));
 var os14 = __toESM(require("node:os"));
 var path38 = __toESM(require("node:path"));
@@ -151611,10 +151868,10 @@ function ensureLensAppBundle(electronBin) {
     fs54.copyFileSync(path38.join(realContents, "Info.plist"), plist);
     const setPlist = (entry, value) => {
       try {
-        (0, import_node_child_process32.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Set :${entry} ${value}`, plist]);
+        (0, import_node_child_process33.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Set :${entry} ${value}`, plist]);
       } catch {
         try {
-          (0, import_node_child_process32.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Add :${entry} string ${value}`, plist]);
+          (0, import_node_child_process33.execFileSync)("/usr/libexec/PlistBuddy", ["-c", `Add :${entry} string ${value}`, plist]);
         } catch {
         }
       }
@@ -151673,7 +151930,7 @@ function createPreviewWindowManager(opts = {}) {
     const wrapperBin = ensureLensAppBundle(electronBin);
     const launchBin = wrapperBin ?? electronBin;
     const launchArgs = wrapperBin ? ["--no-sandbox", mainScript] : [mainScript];
-    const next = (0, import_node_child_process32.spawn)(launchBin, launchArgs, {
+    const next = (0, import_node_child_process33.spawn)(launchBin, launchArgs, {
       // Strip ELECTRON_RUN_AS_NODE so the child boots as a GUI Electron app, not
       // a bare Node runtime (see electronGuiChildEnv). An Electron-based MCP
       // host puts it in our env, and inheriting it makes main.cjs crash at

package/package.json

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

package/skills/argent-create-flow/references/flow-yaml.md

@@ -110,7 +110,7 @@ An Android app that needs a non-launcher activity has no `launch:` form. Record
 
 In a `scroll-to` map, put the selector under `target:`. The map supports `up`, `down`, `left`, and `right` directions. The default is `down`; set it explicitly to reach a target above the viewport or along a horizontal carousel. If the target is already visible, the step is a safe no-op. `tap`, `type`, and `long-press` do not auto-scroll. Add `scroll-to` when the target can be off-screen. Use `within` for a nested scroller.
 
-`type` presses Enter unless `submit: false`. A polished focus tap plus keyboard call usually needs `submit: false`. Store external values as `{{secret:NAME}}`. The runner uses the first source that defines the name: environment `ARGENT_SECRET_NAME`; project `.argent/secrets.env`; project `.env.local`, then `.env`; then `~/.argent/secrets.env`. The two `secrets.env` files accept the bare `NAME`, but the shared dotenv files expose only `ARGENT_SECRET_`-prefixed keys, so a bare `NAME=…` in `.env` or `.env.local` stays unresolved. The runner redacts every resolved value, so do not use a placeholder for content a report must show.
+`type` presses Enter in a second `keyboard` call unless `submit: false`. A polished focus tap plus one text-only `keyboard` call usually needs `submit: false`. Store external values as `{{secret:NAME}}`. The runner uses the first source that defines the name: environment `ARGENT_SECRET_NAME`; project `.argent/secrets.env`; project `.env.local`, then `.env`; then `~/.argent/secrets.env`. The two `secrets.env` files accept the bare `NAME`, but the shared dotenv files expose only `ARGENT_SECRET_`-prefixed keys, so a bare `NAME=…` in `.env` or `.env.local` stays unresolved. The runner redacts every resolved value, so do not use a placeholder for content a report must show.
 
 A **selector-less gesture** — a coordinate `tap`/`long-press`, or a `pinch`/`rotate` with no `on:` — resolves no frame, so a tree source it cannot read does not fail it. It settles best effort, dispatches anyway, and the step **passes carrying a warning** that quotes the source's own error. That green says the gesture was sent, not that it landed: one aimed at a moving element can miss it entirely. Restore the tree source, usually by relaunching the app so the instrumentation loads. Accept the warning only where the app serves no tree at all, and put an explicit `wait:` before a gesture that follows a transition. The first such gesture proves the outage and later ones spend that verdict without paying the settle window again. A tree read that comes back, or a relaunch, retires that verdict — which only makes the next gesture pay a fresh window, and it warns again if the source is still down.
 

package/skills/argent-create-flow/references/live-authoring.md

@@ -111,7 +111,7 @@ Never tap the on-screen keyboard through the recorder. Some platforms expose it
 
 ### Typing
 
-Record the focus tap, then record `keyboard`. Verify the complete value with `describe` or an app validation marker.
+Record the focus tap, then record `keyboard` with `text`. A `keyboard` call carries `text` or `key`, never both. To submit, record a second `keyboard` step with `key: "enter"`. Verify the complete value with `describe` or an app validation marker.
 
 **Never `describe` or `screenshot` a non-secure field you just filled from `{{secret:…}}`.** Only a password field is redacted; a plain text input hands the resolved value back into your context, and an API key or token typed into one is the ordinary case. Submit or navigate away first, then verify the resulting screen.
 
@@ -144,16 +144,16 @@ Stop immediately. Restore the last valid screen with direct MCP calls, not `flow
 
 Call `flow-finish-recording`, then read the saved YAML. Apply only meaning-preserving conversions:
 
-| Recorded form                | Finished form                                                      |
-| ---------------------------- | ------------------------------------------------------------------ |
-| focus tap + `tool: keyboard` | `type:`                                                            |
-| keyboard ending in Enter     | submitted `type:` without Enter in its text                        |
-| `tool: await-ui-element`     | `await:` or `assert:`                                              |
-| element-seeking movement     | `scroll-to:`                                                       |
-| coordinate tap or long-press | strict selector after the fallback gate                            |
-| `tool: gesture-pinch`        | selector-based `pinch:` with `scale = endDistance / startDistance` |
-| `tool: gesture-rotate`       | selector-based `rotate:` with `by = endAngle - startAngle`         |
-| sibling `tool: flow-execute` | recorder-captured `run:`                                           |
+| Recorded form                             | Finished form                                                      |
+| ----------------------------------------- | ------------------------------------------------------------------ |
+| focus tap + `tool: keyboard`              | `type:`                                                            |
+| text `keyboard` + `key: enter` `keyboard` | submitted `type:` without Enter in its text                        |
+| `tool: await-ui-element`                  | `await:` or `assert:`                                              |
+| element-seeking movement                  | `scroll-to:`                                                       |
+| coordinate tap or long-press              | strict selector after the fallback gate                            |
+| `tool: gesture-pinch`                     | selector-based `pinch:` with `scale = endDistance / startDistance` |
+| `tool: gesture-rotate`                    | selector-based `rotate:` with `by = endAngle - startAngle`         |
+| sibling `tool: flow-execute`              | recorder-captured `run:`                                           |
 
 Only these unrecorded insertions are allowed, at states observed live:
 

package/skills/argent-create-flow/references/reliability-and-recovery.md

@@ -59,7 +59,7 @@ Apple system apps cannot load the instrumentation, and nothing in the launch pat
 
 - Raw `tool: await-ui-element` accessibility checks.
 - Point taps or long-presses derived from `describe`, each named by an echo.
-- A point focus tap plus raw keyboard with `delayMs: 500`.
+- A point focus tap plus a raw text-only `keyboard` with `delayMs: 500`, and a second raw `keyboard` with `key: "enter"` to submit.
 - Raw swipes with `settle: true` because `scroll-to` needs the missing flow tree. Momentum-free scrolling keeps later coordinate taps valid.
 
 Every point tap or long-press in such a flow passes **carrying a warning**. The app loads no instrumentation, so every tree read fails and each [selector-less gesture](flow-yaml.md#directives) dispatches unsettled. Nothing here repairs it. Accept the warnings, read each green as "the gesture was sent, not that it landed", and put an explicit `wait:` or a raw `tool: await-ui-element` before a gesture that follows a transition. Raw `tool:` steps never take that settle, so they never warn.

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

@@ -72,7 +72,7 @@ Common schemes: `messages://`, `settings://`, `maps://?q=<query>`, `tel://<numbe
 | 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. Supports Enter, Escape, arrows (not on TV)       |
+| 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    |
@@ -168,15 +168,17 @@ Values: `home`, `back`, `power`, `volumeUp`, `volumeDown`, `appSwitch`, `actionB
 ### keyboard — Type text or press special keys
 
 ```json
-{ "udid": "<UDID>", "text": "search query", "key": "enter" }
+{ "udid": "<UDID>", "text": "search query" }
 ```
 
+One call does one action. `text` and `key` are mutually exclusive, and a call that carries both is rejected with nothing typed. To type and then submit, send two `keyboard` steps in one `run-sequence` (§ 8) — `{ "text": "search query" }`, then `{ "key": "enter" }`. Two separate calls do the same work, but cost an extra round-trip.
+
 Special keys: `enter`, `escape`, `backspace`, `tab`, `space`, `arrow-up`, `arrow-down`, `arrow-left`, `arrow-right`, `f1`–`f12`. Optional: `"delayMs": 100` between keystrokes (default 50ms) — applies to the iOS simulator and Chromium; it is ignored on Android phones/tablets (typed via `adb input text`, no per-key cadence), on Vega, and on TV targets.
 
 **Typing secrets.** To enter a credential without its plaintext ever entering your context, transcript, or logs, use a secret placeholder in `text` (works in `keyboard`, `paste`, `run-sequence` keyboard steps, and flow `type` steps):
 
 ```json
-{ "udid": "<UDID>", "text": "{{secret:APP_PASSWORD}}", "key": "enter" }
+{ "udid": "<UDID>", "text": "{{secret:APP_PASSWORD}}" }
 ```
 
 The placeholder is resolved on the machine running the tool-server, from the first of these that defines the name:
@@ -191,7 +193,7 @@ The placeholder is resolved on the machine running the tool-server, from the fir
 Rules:
 
 - The result echoes the placeholder, never the value. An unknown name fails with the list of available secret _names_ and every source it looked in, with paths — read that list before asking the user anything.
-- The auto-screenshot after the call is skipped so the typed value cannot re-enter your context as pixels. Do **not** `describe` or `screenshot` a non-secure field you just filled with a secret — submit or navigate away first, then verify the resulting screen.
+- The auto-screenshot after the call is skipped so the typed value cannot re-enter your context as pixels. Do **not** `describe` or `screenshot` a non-secure field you just filled with a secret — submit or navigate away first, then verify the resulting screen. To submit, put the text step and the Enter step in **one `run-sequence`**. The skip covers a whole batch that contains the placeholder, but a second bare `keyboard` call gets its own screenshot of the filled field.
 - 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.
 
@@ -316,7 +318,7 @@ Scroll down three times:
 }
 ```
 
-Type into a focused field and submit:
+Type into a focused field and submit. This is the only way to mix text and a key, because one `keyboard` call cannot carry both:
 
 ```json
 {

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

@@ -21,7 +21,7 @@ description: Control and inspect TV apps via argent — Apple TV (tvOS), Android
 
 - `describe {udid}` — focus view: the focused / `[selected]` element + focusable elements with labels and normalized frames. The discovery tool — call before and after navigating. Empty tree → see the per-platform notes.
 - `tv-remote {udid, button}` — D-pad / remote. `button` is one key **or a whole path** (run in one call). Keys: `up`/`down`/`left`/`right`, `select`, `back`, `menu`, `home`, `playPause`, plus media keys `rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`. Single: `{button:"down"}`; repeat: `{button:"down", repeat:3}`; path: `{button:["up","right","select"]}`.
-- `keyboard {udid, text}` — type into the focused field (focus it with `tv-remote` first). Named `key` presses (e.g. `{key:"enter"}`) work on Vega; on Apple TV / Android TV move focus with `tv-remote` instead.
+- `keyboard {udid, text}` — type into the focused field (focus it with `tv-remote` first). One call carries `text` or `key`, never both — to type and then press a key, send two `keyboard` steps in one `run-sequence`. Named `key` presses (e.g. `{key:"enter"}`) work on Vega; on Apple TV / Android TV move focus with `tv-remote` instead.
 - `launch-app` / `restart-app` / `reinstall-app {udid, bundleId}` — `bundleId` from the app manifest. Vega `reinstall-app` takes `appPath` = a `.vpkg`.
 - `screenshot {udid, scale?}` — Apple TV via `xcrun simctl io` (downscaled); Android TV / Vega host-side via `adb` / `screencap`.