@swmansion/argent 0.30.2-next.0 → 0.30.2-next.10

package/dist/mcp-server.mjs

@@ -24566,6 +24566,7 @@ function spawnToolsServer(paths, port, options = {}) {
       stdio: ["ignore", "pipe", logFd],
       env: buildToolsServerEnv(paths, port, process.env, options)
     });
+    fs.closeSync(logFd);
     child.unref();
     const pid = child.pid;
     if (!pid) {
@@ -25155,6 +25156,21 @@ var FAILURE_CODES = {
   VEGA_ALREADY_RUNNING: "VEGA_ALREADY_RUNNING",
   VEGA_SCREENSHOT_FAILED: "VEGA_SCREENSHOT_FAILED",
   VEGA_TEXT_INVALID: "VEGA_TEXT_INVALID",
+  HARMONY_DISABLED: "HARMONY_DISABLED",
+  HARMONY_HDC_NOT_FOUND: "HARMONY_HDC_NOT_FOUND",
+  HARMONY_EMULATOR_NOT_FOUND: "HARMONY_EMULATOR_NOT_FOUND",
+  HARMONY_EMULATOR_COMMAND_FAILED: "HARMONY_EMULATOR_COMMAND_FAILED",
+  HARMONY_HDC_COMMAND_FAILED: "HARMONY_HDC_COMMAND_FAILED",
+  HARMONY_DEVICE_ID_INVALID: "HARMONY_DEVICE_ID_INVALID",
+  HARMONY_DEVICE_UNREACHABLE: "HARMONY_DEVICE_UNREACHABLE",
+  HARMONY_SHELL_NO_STATUS: "HARMONY_SHELL_NO_STATUS",
+  HARMONY_FILE_TRANSFER_FAILED: "HARMONY_FILE_TRANSFER_FAILED",
+  HARMONY_UITEST_FAILED: "HARMONY_UITEST_FAILED",
+  HARMONY_DISPLAY_UNREADABLE: "HARMONY_DISPLAY_UNREADABLE",
+  HARMONY_SCREEN_OFF: "HARMONY_SCREEN_OFF",
+  HARMONY_ABILITY_START_FAILED: "HARMONY_ABILITY_START_FAILED",
+  HARMONY_ABILITY_STOP_FAILED: "HARMONY_ABILITY_STOP_FAILED",
+  HARMONY_REINSTALL_FAILED: "HARMONY_REINSTALL_FAILED",
   ANDROID_ADB_NOT_FOUND: "ANDROID_ADB_NOT_FOUND",
   ANDROID_EMULATOR_NOT_FOUND: "ANDROID_EMULATOR_NOT_FOUND",
   ANDROID_ADB_COMMAND_FAILED: "ANDROID_ADB_COMMAND_FAILED",
@@ -25392,6 +25408,12 @@ var FAILURE_CODES = {
   BOOT_ANDROID_FIRST_FRAME_TIMEOUT: "BOOT_ANDROID_FIRST_FRAME_TIMEOUT",
   BOOT_ANDROID_PACKAGE_MANAGER_UNAVAILABLE: "BOOT_ANDROID_PACKAGE_MANAGER_UNAVAILABLE",
   BOOT_ANDROID_COLD_BOOT_FAILED: "BOOT_ANDROID_COLD_BOOT_FAILED",
+  BOOT_HARMONY_INSTANCE_NOT_FOUND: "BOOT_HARMONY_INSTANCE_NOT_FOUND",
+  BOOT_HARMONY_TARGET_LIST_FAILED: "BOOT_HARMONY_TARGET_LIST_FAILED",
+  BOOT_HARMONY_STOP_FAILED: "BOOT_HARMONY_STOP_FAILED",
+  BOOT_HARMONY_STOP_TIMEOUT: "BOOT_HARMONY_STOP_TIMEOUT",
+  BOOT_HARMONY_MANAGER_EXITED: "BOOT_HARMONY_MANAGER_EXITED",
+  BOOT_HARMONY_START_FAILED: "BOOT_HARMONY_START_FAILED",
   /**
    * External device providers
    * @see [external-devices.ts](../../tool-server/src/utils/external-devices.ts)
@@ -25421,6 +25443,8 @@ var FAILURE_COMMANDS = [
   "adb",
   "emulator",
   "vega",
+  "hdc",
+  "deveco_emulator",
   "xcrun_simctl",
   "xctrace",
   "native_devtools",
@@ -25554,7 +25578,7 @@ async function getResolvedToolsUrl() {
     const link2 = await readLinkConfig();
     const envToken = process.env[AUTH_TOKEN_ENV];
     return {
-      url: envUrl,
+      url: envUrl.replace(/\/+$/, ""),
       source: "env",
       ...envToken ? { token: envToken } : {},
       ...link2 ? { shadowedLink: link2 } : {}
@@ -27406,6 +27430,7 @@ var PLATFORMS = [
   "android",
   "chromium",
   "vega",
+  "harmony",
   "tvos",
   "android-tv"
 ];
@@ -28461,7 +28486,9 @@ var AUTO_SCREENSHOT_TOOLS = /* @__PURE__ */ new Set([
   "restart-app",
   "open-url",
   "describe",
-  "run-sequence"
+  "run-sequence",
+  // A wait is almost always followed by a look at the screen it waited for.
+  "await-ui-element"
 ]);
 var AUTO_SCREENSHOT_DELAY_MS_BY_TOOL = {
   "launch-app": 3e3,
@@ -28482,7 +28509,10 @@ var AUTO_SCREENSHOT_DELAY_MS_BY_TOOL = {
   "fold": 1500,
   "keyboard": 300,
   "paste": 300,
-  "describe": 100
+  "describe": 100,
+  // The wait returns on the first match, often mid-transition; the cap must
+  // leave `await-screen-idle` room to see two identical reads.
+  "await-ui-element": 1500
 };
 var DEFAULT_DELAY_MS = 1400;
 function autoScreenshotEnabled(options) {
@@ -28504,7 +28534,8 @@ var AUTO_DESCRIBE_TOOLS = /* @__PURE__ */ new Set([
   "launch-app",
   "restart-app",
   "open-url",
-  "run-sequence"
+  "run-sequence",
+  "await-ui-element"
 ]);
 function autoDescribeEnabled(options) {
   return !isFlagEnabled("disable-auto-describe", options);
@@ -28734,11 +28765,69 @@ async function startMcpServer(options) {
     reconnect,
     extraHeaders: aiClientHeaders
   });
+  async function awaitScreenSettled(udid, toolName) {
+    const maxWaitMs = getAutoScreenshotDelayMs(toolName);
+    if (maxWaitMs === 0) return true;
+    try {
+      const idle = await callTool("await-screen-idle", { udid, timeoutMs: maxWaitMs });
+      await spyLog({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        event: "auto_screenshot_readiness",
+        name: toolName,
+        maxWaitMs,
+        ...idle.result
+      });
+      return idle.result?.settled === true;
+    } catch {
+      await new Promise((r) => setTimeout(r, maxWaitMs));
+      return false;
+    }
+  }
+  async function captureScreenshotBlocks(udid) {
+    try {
+      const { result } = await callTool("screenshot", { udid });
+      const blocks = await toMcpContent(result, "image", {
+        toolsUrl: TOOLS_URL,
+        authToken: AUTH_TOKEN,
+        deviceId: udid
+      });
+      if (!blocks.some((b) => b.type === "image")) return [];
+      return [{ type: "text", text: "--- Screen after action ---" }, ...blocks];
+    } catch {
+      return [];
+    }
+  }
+  async function captureTreeBlocks(udid, toolName) {
+    const t1 = Date.now();
+    try {
+      const d = await callTool("describe", { udid });
+      const desc = d.result?.description;
+      await spyLog({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        event: "auto_describe",
+        name: toolName,
+        durationMs: Date.now() - t1,
+        chars: typeof desc === "string" ? desc.length : 0
+      });
+      if (typeof desc !== "string" || desc.length === 0) return [];
+      return [{ type: "text", text: `${AUTO_DESCRIBE_HEADER}
+${desc}` }];
+    } catch (e) {
+      await spyLog({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        event: "auto_describe",
+        name: toolName,
+        durationMs: Date.now() - t1,
+        error: String(e instanceof Error ? e.message : e)
+      });
+      return [];
+    }
+  }
   const server = new Server(
     { name: "argent", version: getInstalledVersion() },
     {
       capabilities: { tools: {} },
-      instructions: "Argent \u2014 iOS Simulator, Android Emulator, and Chromium app control for interacting, testing, profiling and debugging mobile and Chromium applications. Interaction tools return the screen after the action: a screenshot plus the accessibility element tree with normalized tap frames. Take coordinates from that tree; call describe (or debugger-component-tree) only when no fresh tree is available \u2014 never guess coordinates from pixels. On session end: call stop-all-simulator-servers with devices: [...] naming the devices this session used, and perform any necessary cleanup. One tool-server is shared by every agent using this argent install, so an unscoped call tears down their devices too \u2014 reserve it for a deliberate machine-wide cleanup. Full guidance is in the argent rule loaded from .claude/rules/argent.md."
+      instructions: "Argent \u2014 iOS Simulator, Android Emulator, and Chromium app control for interacting, testing, profiling and debugging mobile and Chromium applications. Interaction tools return the screen after the action: a screenshot plus the accessibility element tree with normalized tap frames. Take coordinates from that tree; call describe (or debugger-component-tree) only when no fresh tree is available \u2014 never guess coordinates from pixels. Do not stop simulator servers when a task finishes: the next task reuses them. Call stop-all-simulator-servers when the user asks to clean up or ends the session, or when a skill tells you to recycle a device's services, always with devices: [...] naming the devices this session used. Never stop a Metro the user started unless they ask. One tool-server is shared by every agent using this argent install, so an unscoped call tears down their devices too \u2014 reserve it for a deliberate machine-wide cleanup. Full guidance is in the argent rule loaded from .claude/rules/argent.md."
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -28801,72 +28890,11 @@ async function startMcpServer(options) {
           }
         ];
       } else if (udid && (wantScreenshot || wantTree)) {
-        const maxWaitMs = getAutoScreenshotDelayMs(params.name);
-        if (maxWaitMs > 0) {
-          try {
-            const idle = await callTool("await-screen-idle", { udid, timeoutMs: maxWaitMs });
-            await spyLog({
-              ts: (/* @__PURE__ */ new Date()).toISOString(),
-              event: "auto_screenshot_readiness",
-              name: params.name,
-              maxWaitMs,
-              ...idle.result
-            });
-          } catch {
-            await new Promise((r) => setTimeout(r, maxWaitMs));
-          }
-        }
-        if (wantScreenshot) {
-          try {
-            const screenshotResult = await callTool("screenshot", { udid });
-            const screenshotContent = await toMcpContent(screenshotResult.result, "image", {
-              toolsUrl: TOOLS_URL,
-              authToken: AUTH_TOKEN,
-              deviceId: udid
-            });
-            const hasImage = screenshotContent.some((b) => b.type === "image");
-            if (hasImage) {
-              content = [
-                ...content,
-                {
-                  type: "text",
-                  text: "--- Screen after action ---"
-                },
-                ...screenshotContent
-              ];
-            }
-          } catch {
-          }
-        }
-        if (wantTree) {
-          const t1 = Date.now();
-          try {
-            const d = await callTool("describe", { udid });
-            const desc = d.result?.description;
-            if (typeof desc === "string" && desc.length > 0) {
-              content = [
-                ...content,
-                { type: "text", text: `${AUTO_DESCRIBE_HEADER}
-${desc}` }
-              ];
-            }
-            await spyLog({
-              ts: (/* @__PURE__ */ new Date()).toISOString(),
-              event: "auto_describe",
-              name: params.name,
-              durationMs: Date.now() - t1,
-              chars: typeof desc === "string" ? desc.length : 0
-            });
-          } catch (e) {
-            await spyLog({
-              ts: (/* @__PURE__ */ new Date()).toISOString(),
-              event: "auto_describe",
-              name: params.name,
-              durationMs: Date.now() - t1,
-              error: String(e instanceof Error ? e.message : e)
-            });
-          }
-        }
+        const screenSettled = await awaitScreenSettled(udid, params.name);
+        const screenshot = wantScreenshot ? captureScreenshotBlocks(udid) : Promise.resolve([]);
+        if (!screenSettled) await screenshot;
+        const tree = wantTree ? captureTreeBlocks(udid, params.name) : Promise.resolve([]);
+        content = [...content, ...await screenshot, ...await tree];
       }
       if (note) {
         content = [{ type: "text", text: note }, ...content];

package/dist/tool-args.generated.d.ts

@@ -1,6 +1,6 @@
 export interface ArgentToolArgs {
     "await-screen-idle": {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, HarmonyOS id, or Chromium id). */
         udid: string;
         /** Max time to wait for the screen to settle before giving up (default 3000). */
         timeoutMs?: number;
@@ -10,7 +10,7 @@ export interface ArgentToolArgs {
         minStableMs?: number;
     };
     "await-ui-element": {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, HarmonyOS id, or Chromium id). */
         udid: string;
         /** What to wait for. `exists`: selector is anywhere in the tree. `visible`: selector is present with a non-zero on-screen frame. `hidden`: selector is absent or zero-area. `text`: the first visible match in reading order (topmost), falling back to the first match overall if none is visible, contains (or, with textMatch `equals`, exactly matches) expectedText. If a loose selector hits several elements, only that one is checked, so narrow it to target the intended element. */
         condition: "exists" | "visible" | "hidden" | "text";
@@ -27,7 +27,7 @@ export interface ArgentToolArgs {
         expectedText?: string;
         /** For condition `text`: how expectedText is compared. `contains` (default) is a case-insensitive substring; `equals` is a case-insensitive full-string match. */
         textMatch?: "contains" | "equals";
-        /** Optional iOS app bundle id, passed to the describe fallback (see `describe`). Ignored on Android / Chromium, and on physical iOS. */
+        /** Optional iOS app bundle id, passed to the describe fallback (see `describe`). Ignored on every other platform, including physical iOS. */
         bundleId?: string;
         /** Max time to wait for the condition before giving up (default 5000). */
         timeoutMs?: number;
@@ -39,21 +39,23 @@ export interface ArgentToolArgs {
         timeoutSeconds?: number;
     };
     "boot-device": {
-        /** iOS: simulator UDID to boot (from `list-devices`). Provide exactly one of `udid`, `avdName`, `vvdImage`, or `electronAppPath`. */
+        /** iOS: simulator UDID to boot (from `list-devices`). Provide exactly one of `udid`, `avdName`, `vvdImage`, `harmonyInstance`, or `electronAppPath`. */
         udid?: string;
-        /** Android: AVD name to launch a new emulator from (from `list-devices` → `avds[].name`). Provide exactly one of `udid`, `avdName`, `vvdImage`, or `electronAppPath`. */
+        /** Android: AVD name to launch a new emulator from (from `list-devices` → `avds[].name`). Provide exactly one of `udid`, `avdName`, `vvdImage`, `harmonyInstance`, or `electronAppPath`. */
         avdName?: string;
-        /** Vega (Fire TV): VVD image to boot: the `vvdImage` of a Vega device from `list-devices` (e.g. `tv`). Starts the single SDK-managed Vega Virtual Device. Provide exactly one of `udid`, `avdName`, `vvdImage`, or `electronAppPath`. */
+        /** Vega (Fire TV): VVD image to boot: the `vvdImage` of a Vega device from `list-devices` (e.g. `tv`). Starts the single SDK-managed Vega Virtual Device. Provide exactly one of `udid`, `avdName`, `vvdImage`, `harmonyInstance`, or `electronAppPath`. */
         vvdImage?: string;
-        /** Android/Vega: overall budget for the boot sequence. Default 480000 (8 min) on Android, 120000 (2 min) on Vega. Clamped to [30s, 15min]. Ignored on iOS. */
+        /** HarmonyOS: emulator instance to start: the `name` of a `kind: "emulator"` device from `list-devices` (e.g. `Phone_1`); the `harmony-emulator-<name>` id that entry reports as its `udid` is accepted too. Provide exactly one of `udid`, `avdName`, `vvdImage`, `harmonyInstance`, or `electronAppPath`. */
+        harmonyInstance?: string;
+        /** Android/Vega/HarmonyOS: overall budget for the boot sequence. Default 480000 (8 min) on Android, 120000 (2 min) on Vega, 180000 (3 min) on HarmonyOS, where with `force` it spans the shutdown as well as the boot. Clamped to [30s, 15min]. Ignored on iOS. */
         bootTimeoutMs?: number;
-        /** Shut down and re-boot the device even if already running. */
+        /** Shut down and re-boot the device even if already running. On HarmonyOS it is also what ties an already-running instance to the `hdc` connect key it registered under, since the emulator manager never reports one: without it the instance is left alone and the payload names the instance rather than a key (`list-devices` lists the keys, but not which instance each belongs to). Ignored for Electron, which always spawns a fresh process. */
         force?: boolean;
-        /** Android only: boot the emulator with audio output enabled. Defaults to false: argent boots emulators MUTED so several agent-driven devices don't all play sound on the host machine; pass `true` when the task involves playing, hearing, or testing audio. Takes effect at boot: if the emulator is already running muted, add `force: true` to reboot it with sound. A boot snapshot saved in the other audio mode can't be reused, so the first boot after toggling is a slower cold boot. The `boot-sound` argent flag flips this default to true. Ignored on iOS/Vega/Electron, which argent never mutes. */
+        /** Android only: boot the emulator with audio output enabled. Defaults to false: argent boots emulators MUTED so several agent-driven devices don't all play sound on the host machine; pass `true` when the task involves playing, hearing, or testing audio. Takes effect at boot: if the emulator is already running muted, add `force: true` to reboot it with sound. A boot snapshot saved in the other audio mode can't be reused, so the first boot after toggling is a slower cold boot. The `boot-sound` argent flag flips this default to true. Ignored on iOS/Vega/HarmonyOS/Electron, which argent never mutes. */
         sound?: boolean;
-        /** iOS only: boot the simulator core WITHOUT opening its GUI window (Simulator.app, or Device Hub on Xcode 27+). The device still streams via simulator-server; used by Argent Lens. Set the `ARGENT_SIMULATOR_NO_WINDOW` env var (1/true/yes) to force this host-wide without passing the flag per call (the iOS analog of `ARGENT_EMULATOR_NO_WINDOW`). Ignored on Android/Vega/Electron, which have no equivalent GUI step. */
+        /** iOS only: boot the simulator core WITHOUT opening its GUI window (Simulator.app, or Device Hub on Xcode 27+). The device still streams via simulator-server; used by Argent Lens. Set the `ARGENT_SIMULATOR_NO_WINDOW` env var (1/true/yes) to force this host-wide without passing the flag per call (the iOS analog of `ARGENT_EMULATOR_NO_WINDOW`). Ignored on Android/Vega/HarmonyOS/Electron, which have no equivalent GUI step. */
         headless?: boolean;
-        /** Electron: path to the Electron app to launch. Either a packaged .app bundle / executable, or a project directory whose package.json points the Electron binary at the entry script. Mutually exclusive with udid/avdName. */
+        /** Electron: path to the Electron app to launch. Either a packaged .app bundle / executable, or a project directory whose package.json points the Electron binary at the entry script. Provide exactly one of `udid`, `avdName`, `vvdImage`, `harmonyInstance`, or `electronAppPath`. */
         electronAppPath?: string;
         /** Electron-only: CDP remote-debugging port to expose. Defaults to a free port; the resulting device id is `chromium-cdp-<port>`. */
         electronPort?: number;
@@ -61,7 +63,7 @@ export interface ArgentToolArgs {
         electronArgs?: Array<string>;
     };
     button: {
-        /** Target device id from `list-devices` (iOS UDID or Android serial). */
+        /** Target device id from `list-devices` (iOS UDID, HarmonyOS id, or Android serial). */
         udid: string;
         /** Hardware button to press */
         button: "home" | "back" | "power" | "volumeUp" | "volumeDown" | "appSwitch" | "actionButton";
@@ -179,9 +181,9 @@ export interface ArgentToolArgs {
         device_id: string;
     };
     describe: {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, HarmonyOS id, or Chromium id). */
         udid: string;
-        /** 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, and on a physical iOS device. */
+        /** 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 every other platform, including a physical iOS device. */
         bundleId?: string;
     };
     "dismiss-update": {
@@ -320,7 +322,7 @@ export interface ArgentToolArgs {
         momentum?: boolean;
     };
     "gesture-pinch": {
-        /** Target device id from `list-devices` (iOS UDID or Android serial). */
+        /** Target device id from `list-devices` (iOS UDID, HarmonyOS id, or Android serial). */
         udid: string;
         /** Center of pinch, horizontal: normalized 0.0–1.0 (fraction of screen width, not pixels) */
         centerX: number;
@@ -336,7 +338,7 @@ export interface ArgentToolArgs {
         endCenterY?: number;
         /** Axis angle in degrees along which the fingers are placed (default 0 = horizontal). */
         angle?: number;
-        /** Total gesture duration in milliseconds (default 300) */
+        /** Total gesture duration in milliseconds (default 300). On HarmonyOS the device runs the whole move itself and takes this as wall-clock time, clamped to the 1–15000ms range `uinput` accepts. */
         durationMs?: number;
     };
     "gesture-rotate": {
@@ -374,7 +376,7 @@ export interface ArgentToolArgs {
         durationMs?: number;
     };
     "gesture-swipe": {
-        /** Target device id from `list-devices` (iOS UDID or Android serial). */
+        /** Target device id from `list-devices` (iOS UDID, HarmonyOS id, or Android serial). */
         udid: string;
         /** Start x: normalized 0.0–1.0 (not pixels; same as tap) */
         fromX: number;
@@ -390,31 +392,31 @@ export interface ArgentToolArgs {
         momentum?: boolean;
     };
     "gesture-tap": {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, HarmonyOS id, or Chromium id). */
         udid: string;
         /** Normalized horizontal position 0.0–1.0 (left=0, right=1), not pixels */
         x: number;
         /** Normalized vertical position 0.0–1.0 (top=0, bottom=1), not pixels */
         y: number;
-        /** Number of taps/clicks dispatched as ONE multi-tap gesture (2 = double-tap / double-click). The taps land inside the OS double-tap window; on Chromium each click carries an escalating CDP clickCount so dblclick actually fires; on physical iOS 2 is the native double-tap and higher counts land as separate taps. Default 1. */
+        /** Number of taps/clicks dispatched as ONE multi-tap gesture (2 = double-tap / double-click). The taps land inside the OS double-tap window; on Chromium each click carries an escalating CDP clickCount so dblclick actually fires; on physical iOS 2 is the native double-tap and higher counts land as separate taps. On HarmonyOS only 2 is one gesture; 3 or more are separate injections a device round trip apart, which the OS reads as single taps. Default 1. */
         clickCount?: number;
     };
     keyboard: {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, HarmonyOS id, or Chromium id). */
         udid: string;
         /** Text to type character by character. Cannot be combined with `key` in one call (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>}}`, 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; 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?: string;
-        /** Named key to press: enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1-f12. Cannot be combined with `text` in one call: one call per action; to type and then press a key, put two `keyboard` steps in one `run-sequence`. Not supported on TV targets; move focus with `tv-remote` (up/down/left/right) instead. Physical iOS: only `enter` and `backspace`. */
+        /** Named key to press: enter, escape, backspace, tab, space, arrow-up, arrow-down, arrow-left, arrow-right, f1-f12. Cannot be combined with `text` in one call: one call per action; to type and then press a key, put two `keyboard` steps in one `run-sequence`. Not supported on TV targets; move focus with `tv-remote` (up/down/left/right) instead. Physical iOS: only `enter` and `backspace`. HarmonyOS: only enter (return), backspace (delete), space, arrow-left and arrow-right; any other key fails with 400 KEYBOARD_KEY_UNSUPPORTED. */
         key?: string;
-        /** 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), on TV targets (Apple TV / Android TV type the whole string at the daemon's own cadence), and on physical iOS. */
+        /** 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 HarmonyOS (`uitest uiInput text` types the whole string in one shot), on Vega (text/keys injected in a single shot), on TV targets (Apple TV / Android TV type the whole string at the daemon's own cadence), and on physical iOS. */
         delayMs?: number;
     };
     "launch-app": {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, HarmonyOS id, or Chromium id). */
         udid: string;
-        /** App identifier. iOS: bundle id (e.g. com.apple.MobileSMS). Android: package name from build.gradle `applicationId` (e.g. com.android.settings). Chromium: any tag matching the same alphabet (letters, digits, '.', '_' and '-'); the call is a no-op since the renderer is already running. */
+        /** App identifier. iOS: bundle id (e.g. com.apple.MobileSMS). Android: package name from build.gradle `applicationId` (e.g. com.android.settings). HarmonyOS: bundle name as listed by `bm dump -a` (e.g. com.huawei.hmos.calculator). Chromium: any tag matching the same alphabet (letters, digits, '.', '_' and '-'); the call is a no-op since the renderer is already running. */
         bundleId: string;
-        /** Android-only: fully-qualified Activity name (e.g. `.MainActivity` or `com.example/com.example.MainActivity`). If omitted on Android, the app's default launcher activity is used. Ignored on iOS / Chromium. */
+        /** Android-only: fully-qualified Activity name (e.g. `.MainActivity` or `com.example/com.example.MainActivity`). If omitted on Android, the app's default launcher activity is used. Ignored on iOS / Chromium / HarmonyOS (a HarmonyOS ability is resolved from the bundle's own `abilityInfos`). */
         activity?: string;
         /** Apple simulators and physical iPhones: arguments passed to the app process at launch, e.g. `["-FeatureFlag", "YES"]` to override UserDefaults. A running app is relaunched to apply them. Ignored on other targets. */
         launchArgs?: Array<string>;
@@ -545,7 +547,7 @@ export interface ArgentToolArgs {
         maxDepth?: number;
     };
     "open-url": {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, HarmonyOS id, or Chromium id). */
         udid: string;
         /** URL or scheme to open (e.g. https://example.com, messages://, tel:555, geo:37.0,-122.0). For Chromium this navigates the renderer. */
         url: string;
@@ -745,19 +747,19 @@ export interface ArgentToolArgs {
         device_id: string;
     };
     "reinstall-app": {
-        /** Target device id from `list-devices` (iOS UDID or Android serial). */
+        /** Target device id from `list-devices` (iOS UDID, HarmonyOS id, or Android serial). */
         udid: string;
-        /** App identifier that matches the bundle at `appPath`. iOS: bundle id (used to uninstall first). Android: package name (used to uninstall first; the install itself identifies the app from the APK). Vega: interactive component app id (e.g. com.example.app.main), used to uninstall first. */
+        /** App identifier that matches the bundle at `appPath`. iOS: bundle id (used to uninstall first). Android: package name (used to uninstall first; the install itself identifies the app from the APK). Vega: interactive component app id (e.g. com.example.app.main), used to uninstall first. HarmonyOS: bundle name, which must match `app.bundleName` in the `.hap`. */
         bundleId: string;
-        /** Path to the app bundle. iOS: `.app` directory (e.g. ./build/.../MyApp.app). Android: `.apk` file (e.g. android/app/build/outputs/apk/debug/app-debug.apk). Vega: `.vpkg` file. Relative paths are resolved from the current working directory. */
+        /** Path to the app bundle. iOS: `.app` directory (e.g. ./build/.../MyApp.app). Android: `.apk` file (e.g. android/app/build/outputs/apk/debug/app-debug.apk). Vega: `.vpkg` file. HarmonyOS: `.hap` file. Relative paths are resolved from the current working directory. */
         appPath: string;
     };
     "restart-app": {
-        /** Target device id from `list-devices` (iOS UDID or Android serial). */
+        /** Target device id from `list-devices` (iOS UDID, HarmonyOS id, or Android serial). */
         udid: string;
-        /** App identifier. iOS: bundle id. Android: package name. */
+        /** App identifier. iOS: bundle id. Android: package name. HarmonyOS: bundle name. */
         bundleId: string;
-        /** Android-only: relaunch a non-launcher Activity (e.g. `.SettingsActivity` or `com.example/com.example.SettingsActivity`). If omitted, the app's default launcher activity is used. Ignored on iOS. */
+        /** Android-only: relaunch a non-launcher Activity (e.g. `.SettingsActivity` or `com.example/com.example.SettingsActivity`). If omitted, the app's default launcher activity is used. Ignored on iOS / HarmonyOS. */
         activity?: string;
         /** Apple simulators and physical iPhones: arguments passed to the app process at launch, e.g. `["-FeatureFlag", "YES"]` to override UserDefaults. Ignored on other targets. */
         launchArgs?: Array<string>;
@@ -769,7 +771,7 @@ export interface ArgentToolArgs {
         orientation: "Portrait" | "LandscapeLeft" | "LandscapeRight" | "PortraitUpsideDown";
     };
     "run-sequence": {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, or Chromium id), shared across all steps. */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, HarmonyOS id, or Chromium id), shared across all steps. */
         udid: string;
         /** Ordered list of interaction steps to execute sequentially */
         steps: Array<{
@@ -798,11 +800,11 @@ export interface ArgentToolArgs {
         udid: string;
     };
     screenshot: {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, Apple TV UDID, Vega serial, or Chromium id). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, Apple TV UDID, Vega serial, HarmonyOS id, or Chromium id). */
         udid: string;
-        /** Orientation override for the screenshot (rotates the captured image after Page.captureScreenshot on Chromium). On Android the capture already follows the device's rotation. Ignored on physical iPhones. */
+        /** Orientation override for the screenshot (rotates the captured image after Page.captureScreenshot on Chromium). On Android the capture already follows the device's rotation. Rejected on HarmonyOS, which captures the display in its current orientation and has no override. Ignored on physical iPhones. */
         rotation?: "Portrait" | "LandscapeLeft" | "LandscapeRight" | "PortraitUpsideDown";
-        /** Scale factor (0.01-1.0). Defaults to ARGENT_SCREENSHOT_SCALE env var, or 0.25 if unset for iOS/Android. On a local Apple TV simulator, an Android TV or Vega, with neither set, the capture is downscaled to a 576 px long side (0.15 of a 4K capture); an Android TV whose form factor or display size cannot be read in time keeps 0.25. On Chromium the default is 1.0 (no downscale); pass <1 to opt in. Downscaling on Chromium requires the optional `sharp` dependency. */
+        /** Scale factor (0.01-1.0). Defaults to ARGENT_SCREENSHOT_SCALE env var, or 0.25 if unset for iOS/Android/HarmonyOS. On a local Apple TV simulator, an Android TV or Vega, with neither set, the capture is downscaled to a 576 px long side (0.15 of a 4K capture); an Android TV whose form factor or display size cannot be read in time keeps 0.25. On Chromium the default is 1.0 (no downscale); pass <1 to opt in. Downscaling on Chromium requires the optional `sharp` dependency. */
         scale?: number;
         /** Default true. Set false only when capturing a full-resolution PNG (scale: 1.0) to save as a baseline/current for screenshot-diff. The file is still written, but the image bytes are not attached to the agent context. */
         includeImageInContext?: boolean;
@@ -814,13 +816,13 @@ export interface ArgentToolArgs {
         baselinePath?: string;
         /** Path to the current PNG file. Required unless captureCurrent is true. */
         currentPath?: string;
-        /** Target device id from `list-devices` (iOS UDID or Android serial). */
+        /** Target device id from `list-devices` (iOS UDID, HarmonyOS id, or Android serial). */
         udid: string;
         /** Capture the baseline screenshot live at full resolution before diffing. Cannot be combined with captureCurrent. */
         captureBaseline?: boolean;
         /** Capture the current screenshot live at full resolution before diffing. Cannot be combined with captureBaseline. */
         captureCurrent?: boolean;
-        /** Orientation override for live baseline/current captures. Ignored on physical iPhones. */
+        /** Orientation override for live baseline/current captures. Rejected on HarmonyOS, which captures the display in its current orientation and has no override. Ignored on physical iPhones. */
         rotation?: "Portrait" | "LandscapeLeft" | "LandscapeRight" | "PortraitUpsideDown";
         /** Directory where diff artifacts should be written. Optional: defaults to a temp directory; the diff images are returned in the result either way. */
         outputDir?: string;