@ishlabs/cli 0.24.0 → 0.25.0

package/dist/lib/docs.js

@@ -339,7 +339,7 @@ pick was wrong.
 - \`guides/slicing-results\` — filter / project \`study results\` by frame,
   segment, turn, sentiment, assignment, step.
 - \`reference/billing-limits\` — \`maxStudiesPerProduct\` cap on study creation.
-- \`reference/credits\` — per-run credit cost & how to preview before dispatch.
+- \`reference/credits\` — per-run credit draw & how to preview before dispatch.
 `;
 const CONCEPT_ITERATION = `# concept: iteration
 
@@ -806,7 +806,7 @@ Treat this as actionable, not transient — re-running won't change anything.
 - \`concepts/run-verbs\` — how \`ish study run\` selects the iteration.
 - \`concepts/people\` — how participants are picked for a run.
 - \`reference/billing-limits\` — \`maxIterationsPerStudy\` cap on iteration creation.
-- \`reference/credits\` — per-iteration-run credit cost & preview shape (\`pair_preview.credit_estimate\` for participant-pair, top-level \`credit_estimate\` otherwise).
+- \`reference/credits\` — per-iteration-run credit draw & preview shape (\`pair_preview.credit_estimate\` for participant-pair, top-level \`credit_estimate\` otherwise).
 `;
 const CONCEPT_ASSIGNMENT = `# concept: assignment
 
@@ -987,7 +987,7 @@ ish ask results a-6ec --json | jq '.rounds[0].aggregates'
 
 Asks carry a top-level \`status\`:
 
-- \`draft\` — created but not dispatched yet. No credits charged. Created
+- \`draft\` — created but not dispatched yet. No credits drawn. Created
   by \`ish ask create --no-dispatch\`.
 - \`running\` — dispatched; the round is executing or queued.
 - \`completed\` — round 1 (or the most recent round) finished.
@@ -1000,10 +1000,10 @@ intact — no \`--verbose\` needed to see it.
 ## Stage-then-dispatch (draft asks)
 
 When you want a human to review the people and prompt **before** any
-credits are spent, separate creation from dispatch:
+credits are drawn, separate creation from dispatch:
 
 \`\`\`
-# 1. Stage — materializes participants, no worker enqueue, no bill yet
+# 1. Stage — materializes participants, no worker enqueue, no credits drawn yet
 ish ask create --workspace w-6ec --name "tagline AB" \\
     --prompt "Which sounds better?" \\
     --variant text:"Short and punchy." \\
@@ -1013,18 +1013,20 @@ ish ask create --workspace w-6ec --name "tagline AB" \\
 
 # Returns an ask with status="draft". Hand the alias back to the user.
 
-# 2. Dispatch — flips DRAFT → RUNNING and enqueues the round (BILLABLE)
+# 2. Dispatch — flips DRAFT → RUNNING and enqueues the round (draws credits)
 ish ask dispatch a-6ec --wait
 \`\`\`
 
 \`--no-dispatch\` requires people flags (participants are still materialized
-at create time — only the worker enqueue and billing are deferred). It
-is incompatible with \`--wait\` since there is nothing to wait for.
+at create time — only the worker enqueue and the credit draw are
+deferred). It is incompatible with \`--wait\` since there is nothing to
+wait for.
 
 \`ish ask dispatch\` is idempotent on the server: a non-DRAFT ask returns
 HTTP 409 (\`already dispatched\`) which the CLI maps to a usage error, so
 re-running the command is safe. The user who calls \`dispatch\` is the
-billing principal — keep that in mind for shared workspaces.
+principal whose credits are drawn — keep that in mind for shared
+workspaces.
 
 ## Reading the verdict
 
@@ -1170,7 +1172,7 @@ deleted ask was the active one.
 - \`concepts/round\` — what a round is and how it executes.
 - \`concepts/people\` — how participants are chosen at ask creation.
 - \`concepts/run-verbs\` — \`ish ask run\` vs \`ish study run\`.
-- \`reference/credits\` — ask rounds bill **one credit per successful participant per round**, regardless of how many \`questions\` were included. The backend's asks worker bills \`amount=succeeded\` once per round dispatch; questions and round-summary synthesis don't trigger separate debits. A 3-person panel with 2 follow-up questions costs \`3\` credits when all complete, the same as a no-questions run. Failed participant responses (pre-flight errors, refusals) don't bill.
+- \`reference/credits\` — ask rounds draw **one credit per successful participant per round**, regardless of how many \`questions\` were included. The backend's asks worker draws \`amount=succeeded\` once per round dispatch; questions and round-summary synthesis don't draw separately. A 3-person panel with 2 follow-up questions draws \`3\` credits when all complete, the same as a no-questions run. Failed participant responses (pre-flight errors, refusals) draw nothing.
 `;
 const CONCEPT_ROUND = `# concept: round
 
@@ -1197,7 +1199,7 @@ ish ask results a-6ec --round 1
 
 Appending questions to a completed round preserves prior data — variant
 comments, picks, ratings, and earlier-question answers all stay. Only
-the new question(s) get dispatched to the existing participants. Cost is
+the new question(s) get dispatched to the existing participants. Usage is
 roughly N phase-2 LLM calls instead of 2N (no phase-1 re-run). Errored
 responses are skipped entirely; completed responses flip to PENDING and
 re-finalize after the new question is answered.
@@ -1902,16 +1904,16 @@ load-bearing return value — same exception \`study run\` makes.
 | Source not terminal (RUNNING / QUEUED) | \`Participant is still running — cancel it first or wait for completion.\` | 2 |
 | Source participant not found | \`Participant not found: <id>\` | 4 |
 | \`additional_steps\` out of range | Client-side parser rejects before the network call | 2 |
-| Insufficient credits | Bubbles the server message; retry only after topping up | 5 |
+| Insufficient credits | Bubbles the server message; retry only after the balance is replenished | 5 |
 | Wait timed out (\`--wait\` only) | \`WaitTimeoutError\` envelope with current status under \`progress.rows[0]\` — the run keeps going server-side; resume with \`study wait <new-participant>\` | 5 |
 
-## Cost model
+## Credit model
 
-\`extend\` charges credits for **only \`additional_steps\`**, not for
+\`extend\` draws credits for **only \`additional_steps\`**, not for
 the source's original \`max_interactions\` cap. The formula is the same
 as \`study run\` for interactive runs: \`max(1, round(N / 10))\` per
-participant. So \`--add-steps 10\` costs **1 credit**; \`--add-steps 50\`
-costs **5 credits**. See \`reference/credits\` for the full table.
+participant. So \`--add-steps 10\` draws **1 credit**; \`--add-steps 50\`
+draws **5 credits**. See \`reference/credits\` for the full table.
 
 ## Worked example — push past the step cap
 
@@ -1945,7 +1947,7 @@ ish study extend pt-072 \\
 
 - \`concepts/run-verbs\` — the top-level decision rule (\`study run\` vs
   \`ask run\`); extend is a lifecycle verb downstream of either.
-- \`reference/credits\` — per-modality cost formulas. \`extend\` follows
+- \`reference/credits\` — per-modality credit-draw formulas. \`extend\` follows
   the interactive formula scaled to \`additional_steps\`.
 - \`reference/aliases\` — the \`t-…\` prefix and how aliases resolve.
 - \`reference/json-mode\` — capture-mode (\`--get participant_alias\`) for
@@ -2366,7 +2368,7 @@ The CLI guarantees these contracts so agents can chain safely:
   \`study update <id> --modality text\` before adding iterations.
 - **\`ask add-questions\` is additive by default.** Appending questions
   preserves variant comments / picks / ratings / prior-question
-  answers; only the new question(s) get dispatched. Cost: roughly N
+  answers; only the new question(s) get dispatched. Usage: roughly N
   phase-2 LLM calls instead of 2N. Pass \`--redispatch-all\` for the
   legacy reset behavior when you want fresh first impressions.
 - **\`ask results --json\` includes \`cross_round_summary\` for 2+
@@ -2990,49 +2992,62 @@ of scope: \`workspace\`, \`config\`, \`docs\`, \`init\`, \`login\`,
   including \`--get workspace.alias\` to capture the active workspace
   without piping \`ish status --json\` through \`jq\`.
 `;
-const REFERENCE_CREDITS = `# reference: credits & cost preview
+const REFERENCE_CREDITS = `# reference: credits & usage preview
 
-Every billable run (study, ask, insight) costs **credits**. The CLI
-surfaces a cost upper bound *before* you dispatch so you can budget. The
-backend is the authoritative source — its rejection envelope on
-\`insufficient_credits\` carries the live required/available pair.
+Credits are ish's **usage allowance** — a resource that runs draw, not
+money you pay per call. Each run (study, ask, insight) **draws credits**
+from the account's balance. Drawing credits to run studies and asks is
+the normal, expected way to use ish — an agent should run them without
+hesitation, the same as making any other tool call. The job here is just
+to be *aware* of the balance, not to ration it.
 
-## How costs are shaped
+**Where credits come from:**
+- **Paid plans (Starter / Pro / Enterprise)** get a **monthly credit
+  allowance** that refills each billing cycle.
+- **The free tier** gets a **one-time signup grant** — it is *not*
+  refilled monthly. Once it's drawn down, the user adds more or upgrades.
+
+The CLI surfaces a usage upper bound *before* you dispatch so you can see
+how much a run will draw. The backend is the authoritative source — its
+rejection envelope on \`insufficient_credits\` carries the live
+required/available pair.
+
+## How usage is shaped
 
 The formula has the same shape across modalities — \`max(1, round(N / 10))\`
 per principal — but the inputs differ. **Treat the rates below as the
 current calibration**; they will evolve as we differentiate per-modality
-compute cost. Agents should:
+compute. Agents should:
 
-- For prospective cost preview: read \`credit_estimate\` from \`study run\`'s
+- For prospective usage preview: read \`credit_estimate\` from \`study run\`'s
   JSON envelope (top-level for solo/media runs; under \`pair_preview\` for
   participant-pair chat).
-- For hard budget checks: catch the backend's \`insufficient_credits\`
+- For hard balance checks: catch the backend's \`insufficient_credits\`
   rejection (HTTP 402; envelope shape below) and react to
   \`required\` / \`available\`.
 
-| Surface             | Per-principal cost              | Total formula                                    | Example                              |
+| Surface             | Per-principal draw              | Total formula                                    | Example                              |
 |---------------------|---------------------------------|--------------------------------------------------|--------------------------------------|
 | Interactive (URL)   | \`max(1, round(steps/10))\`       | \`participants × per-participant\`                           | 10 participants × 30 steps → 30 credits   |
 | Text/image/video/audio/document | same                | same                                             | 5 participants × 20 steps → 10 credits    |
 | Chat (external chatbot, solo) | \`max(1, round(turns/10))\` | \`participants × per-participant\`                           | 5 participants × 12 turns → 10 credits    |
 | Chat (participant pair)  | \`max(1, round(turns/10))\` × 2   | \`conv × per-side × 2\`                            | 3 conv × 14 turns → 6 credits        |
 | Ask round           | 1 / successful response         | \`successful_participants\`                             | 50 responses → 50 credits            |
-| Study insights      | first free, then **10 flat**    | n/a                                              | 2nd analysis → 10 credits            |
+| Study insights      | first included, then **10 flat**    | n/a                                              | 2nd analysis → 10 credits            |
 
 All numbers are **upper bounds**. Early termination, refusals, or
-backend trimming can reduce actual charge.
+backend trimming can reduce the actual draw.
 
-## Capping interactive/media spend (\`--max-interactions\`)
+## Capping interactive/media usage (\`--max-interactions\`)
 
 \`ish study run\` always sends \`max_interactions\` to the backend for
 interactive and media runs. Precedence: \`--max-interactions <n>\` flag
 > the iteration's stored \`details.max_interactions\` > **CLI default
-of 20**. The default exists to prevent runaway spend when a participant
-gets stuck on a broken or non-responsive surface — without a cap, one
-stuck participant can rack up 100+ steps before the SDK gives up. Pass
-\`--max-interactions\` to override (e.g. \`--max-interactions 50\` for
-deeper exploration, \`--max-interactions 5\` for a cheap smoke test).
+of 20**. The default exists to prevent runaway credit draw when a
+participant gets stuck on a broken or non-responsive surface — without a
+cap, one stuck participant can rack up 100+ steps before the SDK gives
+up. Pass \`--max-interactions\` to override (e.g. \`--max-interactions 50\`
+for deeper exploration, \`--max-interactions 5\` for a quick smoke test).
 The confirmation block shows the resolved value and where it came
 from (flag / iteration / CLI default). The JSON envelope's
 \`credit_estimate.breakdown\` reflects the dispatched value.
@@ -3121,7 +3136,7 @@ HTTP 402. The CLI surfaces it as a structured error envelope:
 \`\`\`
 
 Exit code \`1\` (non-retryable). Don't poll — the user has to upgrade or
-free credits before re-dispatch.
+free up credits before re-dispatch.
 
 ## Agent recipe
 
@@ -3135,7 +3150,7 @@ free credits before re-dispatch.
 
 ## Caveats
 
-- The CLI's preview uses the **same formula** the backend bills with,
+- The CLI's preview uses the **same formula** the backend draws against,
   but does **not** make a network preflight call — it's pure math
   client-side. If the backend formula changes mid-version, the preview
   will drift until the CLI is updated. The \`insufficient_credits\`
@@ -3238,9 +3253,9 @@ upgrade or delete an existing resource to free up headroom.
 
 ## Related
 
-- \`reference/credits\` — per-run credit cost & preview (separate from
+- \`reference/credits\` — per-run credit draw & preview (separate from
   these entity caps; this page is about *how many things you can have*,
-  that page is about *how much each run costs*).
+  that page is about *how many credits each run draws*).
 - \`concepts/workspace\` — \`maxProducts\` is per-account.
 - \`concepts/study\`     — \`maxStudiesPerProduct\` gates study creation.
 - \`concepts/iteration\` — \`maxIterationsPerStudy\` gates iteration creation.
@@ -4442,8 +4457,8 @@ const PAGES = [
     },
     {
         slug: "reference/credits",
-        title: "reference: credits & cost preview",
-        description: "Per-modality credit cost formulas, where the CLI surfaces cost estimates (Scale line, pair_preview.credit_estimate, top-level credit_estimate), tier allotments, insufficient_credits error shape.",
+        title: "reference: credits & usage preview",
+        description: "Credits as a usage allowance (paid plans refill monthly; free tier is a one-time signup grant), per-modality credit draw formulas, where the CLI surfaces usage estimates (Scale line, pair_preview.credit_estimate, top-level credit_estimate), tier allotments, insufficient_credits error shape.",
         body: REFERENCE_CREDITS,
     },
     {

package/dist/lib/local-sim/actions.d.ts

@@ -1,10 +1,13 @@
 /**
  * Action executor — resolves elements and executes Playwright actions.
  *
- * Resolution strategy:
+ * Element resolution strategy (browser only):
  * 1. CDP node resolution (using node_id from tree data)
  * 2. Playwright locator fallback (using element_name + element_type)
- * 3. Coordinate fallback (if returned by backend)
+ *
+ * Native (Android) targets are vision-located by the backend and tapped via
+ * normalized coordinates in AndroidDevice.executeAction — that coordinate path
+ * lives there, not here.
  */
 import type { Page } from "playwright-core";
 import type { LocalStepAction, ActionResult, ContextValue, TreeData } from "./types.js";
@@ -13,6 +16,11 @@ import type { TabManager } from "./tabs.js";
  * Execute a single action on the page.
  */
 export declare function executeAction(page: Page, action: LocalStepAction, treeData: TreeData, contextValues: ContextValue[], tabs?: TabManager): Promise<ActionResult>;
+/**
+ * Resolve the actual text to type from an action, handling var/secret value types.
+ * Exported so the native (Android) executor can resolve values the same way.
+ */
+export declare function resolveTextValue(action: LocalStepAction, contextValues: ContextValue[]): string;
 /**
  * Compare two base64 screenshots to detect visible change.
  */

package/dist/lib/local-sim/actions.js

@@ -1,10 +1,13 @@
 /**
  * Action executor — resolves elements and executes Playwright actions.
  *
- * Resolution strategy:
+ * Element resolution strategy (browser only):
  * 1. CDP node resolution (using node_id from tree data)
  * 2. Playwright locator fallback (using element_name + element_type)
- * 3. Coordinate fallback (if returned by backend)
+ *
+ * Native (Android) targets are vision-located by the backend and tapped via
+ * normalized coordinates in AndroidDevice.executeAction — that coordinate path
+ * lives there, not here.
  */
 import { resolveNodeToBoundingBox } from "./browser.js";
 import { isDebugEnabled } from "./debug.js";
@@ -78,7 +81,7 @@ export async function executeAction(page, action, treeData, contextValues, tabs)
                 coordinates = await executeTextInput(page, action, treeData, contextValues);
                 break;
             case "scroll":
-                await executeScroll(page, action, treeData);
+                await executeScroll(page, action);
                 break;
             case "swipe":
             case "pull_to_refresh":
@@ -87,9 +90,6 @@ export async function executeAction(page, action, treeData, contextValues, tabs)
             case "wait":
                 await page.waitForTimeout(action.duration_ms ?? 1000);
                 break;
-            case "navigate_back":
-                await page.goBack({ timeout: 10_000 }).catch(() => { });
-                break;
             case "long_press":
                 coordinates = await executeLongPress(page, action, treeData);
                 break;
@@ -162,7 +162,7 @@ async function resolveElement(page, action, treeData) {
 /**
  * Resolve to a Playwright Locator (for fill/type operations that need a Locator).
  */
-async function resolveLocator(page, action, treeData) {
+async function resolveLocator(page, action) {
     return findElement(page, action);
 }
 /**
@@ -237,7 +237,7 @@ async function executeTextInput(page, action, treeData, contextValues) {
     // Resolve the actual text to type
     const text = resolveTextValue(action, contextValues);
     // Try to get a Playwright locator for fill operations
-    const locator = await resolveLocator(page, action, treeData);
+    const locator = await resolveLocator(page, action);
     if (locator) {
         if (action.mode === "click_type") {
             await locator.click({ timeout: 5000 });
@@ -273,7 +273,7 @@ async function executeTextInput(page, action, treeData, contextValues) {
         }
     }
 }
-async function executeScroll(page, action, treeData) {
+async function executeScroll(page, action) {
     const viewport = page.viewportSize() ?? { width: 1440, height: 900 };
     const amountMap = {
         small: 0.5, medium: 0.8, large: 1.5, extra_large: 3.0,
@@ -378,8 +378,9 @@ async function executeKeyboardShortcut(page, action) {
 // --- Helpers ---
 /**
  * Resolve the actual text to type from an action, handling var/secret value types.
+ * Exported so the native (Android) executor can resolve values the same way.
  */
-function resolveTextValue(action, contextValues) {
+export function resolveTextValue(action, contextValues) {
     if (action.value_type === "var" || action.value_type === "secret") {
         const cv = contextValues.find(v => v.name === action.value);
         if (cv?.value)
@@ -433,7 +434,11 @@ export function describeAction(action) {
         case "double_tap":
             return `double_tap on '${element}'${modSuffix}`;
         case "drag":
-            return `drag '${element}'`;
+            return action.drag
+                ? `drag '${element}' (${action.drag.startX},${action.drag.startY}→${action.drag.endX},${action.drag.endY})`
+                : `drag '${element}'`;
+        case "rotate_device":
+            return `rotate_device ${action.orientation ?? "?"}`;
         case "think":
             return `think: "${(action.thoughts ?? "").slice(0, 50)}"`;
         case "pull_to_refresh":

package/dist/lib/local-sim/adb.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Thin async wrappers over the `adb` CLI for the native-Android sim path.
+ *
+ * One emulator/device is assumed (the lead coordinates a single shared
+ * emulator). Every call shells out to a resolved `adb` binary; binary output
+ * (screencap) is captured without a utf-8 round-trip so PNG bytes survive.
+ *
+ * Coordinate space: `adb shell screencap` and `adb shell input tap` share ONE
+ * pixel space — there is NO DPR correction. The native sim de-normalizes the
+ * backend's 0-1000 coordinates against the screencap pixel size and taps
+ * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
+ */
+export declare class AdbError extends Error {
+    constructor(message: string);
+}
+/** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
+export declare function adb(args: string[], timeoutMs?: number): Promise<string>;
+/** Run `adb shell <args>` and return trimmed stdout. */
+export declare function adbShell(args: string[], timeoutMs?: number): Promise<string>;
+/**
+ * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
+ * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
+ * output. Returns the PNG buffer at full device resolution.
+ */
+export declare function screencapPng(): Promise<Buffer>;
+/** Assert exactly one device/emulator is in the `device` state. */
+export declare function requireOneDevice(): Promise<void>;
+export declare function inputTap(x: number, y: number): Promise<void>;
+export declare function inputSwipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
+/**
+ * A drag GRABS an element and drops it elsewhere — press, HOLD to pick up,
+ * move, release. We use `input draganddrop`, NOT a slow `input swipe`: a swipe
+ * never holds at the start, so on the surfaces a drag actually targets
+ * (launcher icons, reorderable list rows — all `long-clickable`) the framework
+ * reads a slow swipe as a directional SWIPE (e.g. it opens the app drawer)
+ * instead of picking the element up. `draganddrop` dwells at the press point
+ * first, triggering the long-press pickup, then moves and releases — verified
+ * on-device to actually rearrange a launcher icon where the slow swipe didn't.
+ * Requires API 30+ (`input draganddrop`); on the dev emulators/sim devices the
+ * native driver targets, that's always present. Coordinates are screencap
+ * pixels (the same space as tap/swipe — no DPR correction).
+ */
+export declare function inputDrag(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
+/** A long-press is a zero-distance swipe held for `durationMs`. */
+export declare function inputLongPress(x: number, y: number, durationMs?: number): Promise<void>;
+export declare function pressKeyEvent(keyevent: string): Promise<void>;
+/**
+ * Force a device orientation. We first disable auto-rotation
+ * (`accelerometer_rotation 0`) — otherwise the sensor immediately overrides
+ * our fixed `user_rotation`. `user_rotation` is 0=portrait, 1=landscape (90°).
+ */
+export declare function setUserRotation(orientation: "portrait" | "landscape"): Promise<void>;
+export declare const ADB_KEYBOARD_PKG = "com.android.adbkeyboard";
+/** True if the ADBKeyboard IME is installed on the device. */
+export declare function isAdbKeyboardInstalled(): Promise<boolean>;
+/** Currently-selected IME id (so we can restore it after the run). */
+export declare function currentIme(): Promise<string | null>;
+/** Select an IME by its component id. */
+export declare function setIme(imeId: string): Promise<void>;
+/** Reset the IME to the system default (used when we had no prior IME to restore). */
+export declare function resetIme(): Promise<void>;
+/** Make ADBKeyboard the active IME. */
+export declare function enableAdbKeyboard(): Promise<void>;
+/**
+ * Type text into the focused field via ADBKeyboard's base64 broadcast.
+ * base64 keeps spaces/unicode/quotes intact across the adb shell boundary.
+ * Note: the text transits as a base64 argv arg, so it's briefly visible in the
+ * device-side process list (`ps`) — fine for sim input, not a secret channel
+ * (context secrets are resolved here but this is local-dev/emulator only).
+ */
+export declare function adbKeyboardType(text: string): Promise<void>;
+/** Clear the focused field (ADBKeyboard ADB_CLEAR_TEXT broadcast). */
+export declare function adbKeyboardClear(): Promise<void>;
+/**
+ * Read width/height from a PNG buffer's IHDR chunk. The IHDR is always the
+ * first chunk: 8-byte signature, 4-byte length, 4-byte "IHDR", then width and
+ * height as big-endian uint32 at byte offsets 16 and 20. Avoids pulling in an
+ * image library just to learn the screencap's pixel size.
+ */
+export declare function pngDimensions(png: Buffer): {
+    width: number;
+    height: number;
+};
+export declare function forceStop(pkg: string): Promise<void>;
+/** Launch the app's default launchable activity via monkey (no activity name needed). */
+export declare function launchApp(pkg: string): Promise<void>;
+export declare function installApk(apkPath: string): Promise<void>;
+export declare function isPackageInstalled(pkg: string): Promise<boolean>;
+/**
+ * Dump the current view hierarchy as uiautomator XML and return it. Mirrors the
+ * oracle's `ui_dump`: uiautomator fails transiently with "window in transition"
+ * (right after a UI change, writes nothing) or "could not get idle state" (a
+ * view animates forever), so we retry a few times, nudging the device awake
+ * between tries since a screen-off device never goes idle-with-content.
+ *
+ * Uses `exec-out uiautomator dump /dev/tty` so the XML comes back on stdout in
+ * one shot (no pull); falls back to dump-to-file + pull if the device writes the
+ * "dumped to" line to a path instead. Throws AdbError if every attempt fails so
+ * the caller can degrade to the vision path.
+ */
+export declare function dumpUiautomatorXml(): Promise<string>;
+/** All installed package names (the set of `package:<name>` lines). */
+export declare function listPackages(): Promise<Set<string>>;