runcloud 0.1.115 → 0.1.117

package/README.md

@@ -66,6 +66,7 @@ runcloud ios get <id>                                      # inspect a session (
 runcloud ios open-url myapp://path --id <id>               # open a URL or deep link
 runcloud ios tap <id> 0.5 0.75                             # normalized top-left display coordinates
 runcloud ios type-text <id> "Hello from iOS!"              # printable US ASCII, tab, and line feed
+runcloud ios accessibility-tree <id> --json                # read the current typed accessibility hierarchy
 runcloud ios screenshot <id> --output ios.png              # save a PNG without exposing the viewer URL
 runcloud ios recording start <id> --json                   # start an idempotent MP4 screen recording
 runcloud ios recording stop <id> <recording-id> --json     # stop and finalize it
@@ -79,9 +80,27 @@ runcloud ios delete <id>                                   # release the session
 runcloud android create --model pixel
 runcloud android swipe <id> 0.5 0.8 0.5 0.2 --duration 250
 runcloud android press-key <id> enter
+runcloud android accessibility-tree <id> --json
 runcloud android screenshot <id> --output android.png --json
 ```
 
+`open-url` accepts HTTPS URLs and application deep links on both platforms. Keep
+the complete target quoted so its URI delimiters stay in one argument:
+
+```bash
+runcloud ios open-url \
+  'runcloudproof://open/items%2F42?message=hello%20world&return=https%3A%2F%2Fexample.com%2Fdone%3Fx%3D1%26y%3Dtwo#proof' \
+  --id <id> \
+  --json
+```
+
+Success returns `ok`, `platform`, `sessionId`, `device`, `leaseId`, and the
+exact input `url`. Replace `ios` with `android` for an emulator. See
+[Open URLs and Deep Links](https://docs.run.cloud/platform/open-urls) for SDK
+and REST examples, platform behavior, validation, and troubleshooting.
+On iOS, a first custom-scheme handoff can still require confirming the system's
+**Open in “App”?** prompt after the success acknowledgement.
+
 Useful `create` flags: `--region`, `--display-name`, `--inactivity-timeout 3m`,
 `--hard-timeout 1h`, `--install-asset <name-or-id>`, `--rm` (release when the
 command exits), `--json`.
@@ -100,6 +119,12 @@ report `capsLock`, `numLock`, and `scrollLock` as unsupported keys.
 Coordinates are inclusive normalized display coordinates: `(0, 0)` is the
 top-left and `(1, 1)` is the bottom-right.
 
+`accessibility-tree` (`accessibility` alias) returns an indented terminal tree
+or a versioned JSON hierarchy with cross-platform roles, labels, values,
+states, bounds, identifiers, and nested children. Secure field values are
+always redacted. The command reads only the authenticated active session and
+never releases it; use `--timeout` to change the 20-second client wait.
+
 The `recording` group is shared by iOS and Android. It provides `start`,
 `list`, `status` (`get` alias), `stop`, and `download`. Pass a stable
 `--idempotency-key` to retry `start` without creating a second recording.

package/dist/api.js

@@ -10,6 +10,7 @@ export class ApiError extends Error {
     sessionId;
     platform;
     action;
+    suggestedAction;
     interactionStatus;
     acceptedAt;
     completedAt;
@@ -65,6 +66,7 @@ function parsedError(body) {
             ...(typeof parsed.sessionId === 'string' ? { sessionId: parsed.sessionId } : {}),
             ...(platform ? { platform } : {}),
             ...(typeof parsed.action === 'string' ? { action: parsed.action } : {}),
+            ...(typeof nested?.action === 'string' ? { suggestedAction: nested.action } : {}),
             ...(interactionStatus ? { interactionStatus } : {}),
             ...(typeof parsed.acceptedAt === 'string' ? { acceptedAt: parsed.acceptedAt } : {}),
             ...(typeof parsed.completedAt === 'string' ? { completedAt: parsed.completedAt } : {}),
@@ -114,8 +116,8 @@ export class ApiClient {
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
     }
-    get(path) {
-        return this.request('GET', path);
+    get(path, options = {}) {
+        return this.request('GET', path, undefined, options);
     }
     async getText(path) {
         const response = await this.request('GET', path);

package/dist/commands/run-cloud.js

@@ -53,8 +53,19 @@ export const SIMULATOR_SCREENSHOT_ERROR_CODES = [
     'screenshot_invalid_response',
     'screenshot_failed',
 ];
+export const SIMULATOR_ACCESSIBILITY_ERROR_CODES = [
+    'active_session_not_found',
+    'simulator_capacity_unavailable',
+    'simulator_session_ended',
+    'accessibility_unavailable',
+    'accessibility_cancelled',
+    'accessibility_timeout',
+    'accessibility_transport_error',
+    'accessibility_invalid_response',
+];
 const simulatorInteractionErrorCodeSet = new Set(SIMULATOR_INTERACTION_ERROR_CODES);
 const simulatorScreenshotErrorCodeSet = new Set(SIMULATOR_SCREENSHOT_ERROR_CODES);
+const simulatorAccessibilityErrorCodeSet = new Set(SIMULATOR_ACCESSIBILITY_ERROR_CODES);
 function normalizedInteractionErrorCode(value) {
     if (typeof value === 'string' && simulatorInteractionErrorCodeSet.has(value)) {
         return value;
@@ -85,7 +96,13 @@ function normalizedScreenshotErrorCode(value) {
         ? value
         : 'screenshot_failed';
 }
+function normalizedAccessibilityErrorCode(value) {
+    return typeof value === 'string' && simulatorAccessibilityErrorCodeSet.has(value)
+        ? value
+        : 'accessibility_unavailable';
+}
 const DEFAULT_INTERACTION_TIMEOUT_MS = 15_000;
+const DEFAULT_ACCESSIBILITY_TIMEOUT_MS = 20_000;
 const INTERACTION_RESPONSE_MARGIN_MS = 250;
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 export const RUN_CLOUD_SKILL_NAMES = [
@@ -392,10 +409,21 @@ class CliInteractionError extends Error {
     }
 }
 async function withInteractionCancellation(timeoutMs, requestId, actionName, sessionId, platform, operation, run) {
+    const operationLabel = operation === 'interaction' ? 'interaction' : operation;
+    const cancelledCode = operation === 'screenshot'
+        ? 'screenshot_cancelled'
+        : operation === 'accessibility'
+            ? 'accessibility_cancelled'
+            : 'interaction_cancelled';
+    const timeoutCode = operation === 'screenshot'
+        ? 'screenshot_timeout'
+        : operation === 'accessibility'
+            ? 'accessibility_timeout'
+            : 'interaction_timeout';
     const controller = new AbortController();
-    const onSigint = () => controller.abort(new CliInteractionError(`Simulator ${operation === 'screenshot' ? 'screenshot' : 'interaction'} cancelled by SIGINT`, operation === 'screenshot' ? 'screenshot_cancelled' : 'interaction_cancelled', requestId, actionName, sessionId, platform));
+    const onSigint = () => controller.abort(new CliInteractionError(`Simulator ${operationLabel} cancelled by SIGINT`, cancelledCode, requestId, actionName, sessionId, platform));
     process.once('SIGINT', onSigint);
-    const timer = setTimeout(() => controller.abort(new CliInteractionError(`Simulator ${actionName} did not complete within ${timeoutMs} ms`, operation === 'screenshot' ? 'screenshot_timeout' : 'interaction_timeout', requestId, actionName, sessionId, platform)), timeoutMs + INTERACTION_RESPONSE_MARGIN_MS);
+    const timer = setTimeout(() => controller.abort(new CliInteractionError(`Simulator ${actionName} did not complete within ${timeoutMs} ms`, timeoutCode, requestId, actionName, sessionId, platform)), timeoutMs + INTERACTION_RESPONSE_MARGIN_MS);
     try {
         return await run(controller.signal);
     }
@@ -485,6 +513,143 @@ async function captureSimulatorScreenshot(platform, id, opts) {
     else
         console.log(`Saved ${platform} simulator screenshot to ${output} (${bytes.byteLength} bytes)`);
 }
+function validatedAccessibilitySnapshot(value, platform) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('accessibility response must be an object');
+    }
+    const snapshot = value;
+    if (snapshot.schemaVersion !== 1 || snapshot.platform !== platform) {
+        throw new Error('accessibility schema or platform did not match the request');
+    }
+    if (!Array.isArray(snapshot.roots))
+        throw new Error('accessibility roots must be an array');
+    if (typeof snapshot.nodeCount !== 'number'
+        || !Number.isInteger(snapshot.nodeCount)
+        || snapshot.nodeCount < 0
+        || snapshot.nodeCount > 500) {
+        throw new Error('accessibility nodeCount must be an integer from 0 to 500');
+    }
+    if (!snapshot.screen || typeof snapshot.screen !== 'object' || Array.isArray(snapshot.screen)) {
+        throw new Error('accessibility screen must be an object');
+    }
+    const screen = snapshot.screen;
+    if (screen.unit !== (platform === 'ios' ? 'points' : 'pixels')) {
+        throw new Error('accessibility screen unit did not match the platform');
+    }
+    const ids = new Set();
+    let count = 0;
+    const visit = (candidate, path, depth) => {
+        if (depth > 80 || count >= 500 || !candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+            throw new Error('accessibility tree exceeded its schema bounds');
+        }
+        const node = candidate;
+        if (typeof node.id !== 'string' || !node.id || ids.has(node.id)) {
+            throw new Error('accessibility node identifiers must be non-empty and unique');
+        }
+        if (node.path !== path || typeof node.role !== 'string' || !Array.isArray(node.children)) {
+            throw new Error('accessibility node structure is invalid');
+        }
+        const states = node.states && typeof node.states === 'object' && !Array.isArray(node.states)
+            ? node.states
+            : null;
+        const native = node.native && typeof node.native === 'object' && !Array.isArray(node.native)
+            ? node.native
+            : null;
+        if (!states || !native || native.platform !== platform) {
+            throw new Error('accessibility node state or platform detail is invalid');
+        }
+        const secure = states.secure === true
+            || native.password === true
+            || (platform === 'ios' && /(?:secure|password)/iu.test([
+                native.type,
+                native.roleDescription,
+                native.subrole,
+            ].filter((part) => typeof part === 'string').join(' ')));
+        if (secure) {
+            states.secure = true;
+            node.value = null;
+        }
+        ids.add(node.id);
+        count += 1;
+        node.children.forEach((child, index) => visit(child, `${path}.${index}`, depth + 1));
+    };
+    snapshot.roots.forEach((root, index) => visit(root, String(index), 0));
+    if (count !== snapshot.nodeCount)
+        throw new Error('accessibility nodeCount did not match the tree');
+    return snapshot;
+}
+function printAccessibilitySnapshot(snapshot) {
+    const platform = String(snapshot.platform);
+    const screen = snapshot.screen;
+    console.log(`${platform} accessibility tree: ${String(snapshot.nodeCount)} nodes, `
+        + `${String(screen.width)}x${String(screen.height)} ${String(screen.unit)}`
+        + `${snapshot.truncated === true ? ' (truncated)' : ''}`);
+    const visit = (candidate, depth) => {
+        const node = candidate;
+        const states = node.states;
+        const bounds = node.bounds && typeof node.bounds === 'object'
+            ? node.bounds
+            : null;
+        const stateLabels = [
+            states.enabled === false ? 'disabled' : null,
+            states.focused === true ? 'focused' : null,
+            states.selected === true ? 'selected' : null,
+            states.checked === true ? 'checked' : states.checked === 'mixed' ? 'mixed' : null,
+            states.expanded === true ? 'expanded' : states.expanded === false ? 'collapsed' : null,
+            states.secure === true ? 'secure' : null,
+        ].filter(Boolean);
+        const label = typeof node.label === 'string' && node.label ? ` "${node.label}"` : '';
+        const identifier = typeof node.identifier === 'string' && node.identifier
+            ? ` #${node.identifier}`
+            : '';
+        const value = typeof node.value === 'string' && node.value
+            ? ` = ${JSON.stringify(node.value.slice(0, 120))}`
+            : '';
+        const frame = bounds
+            ? ` @ ${String(bounds.x)},${String(bounds.y)} ${String(bounds.width)}x${String(bounds.height)}`
+            : '';
+        const state = stateLabels.length ? ` [${stateLabels.join(', ')}]` : '';
+        console.log(`${'  '.repeat(depth)}${String(node.role)}${label}${identifier}${value}${state}${frame}`);
+        for (const child of node.children)
+            visit(child, depth + 1);
+    };
+    for (const root of snapshot.roots)
+        visit(root, 0);
+}
+async function captureSimulatorAccessibilityTree(platform, id, opts) {
+    const timeoutMs = integerInRange(opts.timeout, '--timeout', 100, 60_000, DEFAULT_ACCESSIBILITY_TIMEOUT_MS);
+    const requestId = `cli_${randomUUID()}`;
+    let value;
+    try {
+        value = await withInteractionCancellation(timeoutMs, requestId, 'accessibility', id, platform, 'accessibility', async (signal) => await client().get(`/run-cloud/${platform}/${encodeURIComponent(id)}/accessibility`, { signal }));
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            Object.assign(error, {
+                code: normalizedAccessibilityErrorCode(error.code),
+                requestId: error.requestId ?? requestId,
+                sessionId: error.sessionId ?? id,
+                platform: error.platform ?? platform,
+                action: error.action ?? 'accessibility',
+            });
+        }
+        if (error instanceof ApiTransportError) {
+            throw new CliInteractionError('Simulator accessibility could not reach the run.cloud API', 'accessibility_transport_error', requestId, 'accessibility', id, platform);
+        }
+        throw error;
+    }
+    let snapshot;
+    try {
+        snapshot = validatedAccessibilitySnapshot(value, platform);
+    }
+    catch {
+        throw new CliInteractionError('Simulator accessibility returned an invalid tree', 'accessibility_invalid_response', requestId, 'accessibility', id, platform);
+    }
+    if (opts.json)
+        console.log(JSON.stringify(snapshot, null, 2));
+    else
+        printAccessibilitySnapshot(snapshot);
+}
 function simulatorRecordingBase(platform, sessionId) {
     return `/run-cloud/${platform}/${encodeURIComponent(sessionId)}/recordings`;
 }
@@ -733,6 +898,58 @@ async function createSimulatorSession(platform, opts) {
         ...(opts.devHost ? { devHost: opts.devHost } : {}),
     });
 }
+async function openSimulatorSessionUrl(platform, sessionId, url) {
+    const path = `/run-cloud/${platform}/${encodeURIComponent(sessionId)}/open-url`;
+    try {
+        const response = await client().post(path, { url });
+        const result = typeof response === 'object' && response !== null && !Array.isArray(response)
+            ? response
+            : {};
+        if (result.ok !== true
+            || result.platform !== platform
+            || result.sessionId !== sessionId
+            || typeof result.device !== 'string'
+            || result.device.length === 0
+            || typeof result.leaseId !== 'string'
+            || result.leaseId.length === 0
+            || result.url !== url) {
+            throw new ApiError(0, 'Simulator open URL returned an invalid acknowledgement', path, {
+                code: 'open_url_invalid_response',
+                retryable: true,
+                sessionId,
+                platform,
+                action: 'open-url',
+            });
+        }
+        return {
+            ok: true,
+            platform,
+            sessionId,
+            device: result.device,
+            leaseId: result.leaseId,
+            url,
+        };
+    }
+    catch (error) {
+        if (error instanceof ApiTransportError) {
+            throw new ApiError(0, 'Simulator open URL could not reach the run.cloud API', path, {
+                code: 'open_url_transport_error',
+                retryable: true,
+                sessionId,
+                platform,
+                action: 'open-url',
+            });
+        }
+        if (error instanceof ApiError) {
+            Object.assign(error, {
+                sessionId: error.sessionId ?? sessionId,
+                platform: error.platform ?? platform,
+                action: error.action ?? 'open-url',
+            });
+        }
+        throw error;
+    }
+}
 function registerSimulatorCommands(program, platform) {
     const label = platform === 'android' ? 'Android emulator' : 'iOS simulator';
     const article = platform === 'android' ? 'an' : 'an';
@@ -792,7 +1009,7 @@ function registerSimulatorCommands(program, platform) {
         .requiredOption('--id <id>', 'session id')
         .option('--json', 'output JSON', false)
         .action((url, opts) => action(async () => {
-        print(await client().post(`/run-cloud/${platform}/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
+        print(await openSimulatorSessionUrl(platform, opts.id, url), opts);
     }, opts));
     addInteractionOptions(simulator
         .command('tap')
@@ -921,6 +1138,14 @@ function registerSimulatorCommands(program, platform) {
         option: renderDebugOption(rawOption),
         enabled: booleanArgument(rawEnabled, 'enabled'),
     }, opts), opts));
+    simulator
+        .command('accessibility-tree')
+        .alias('accessibility')
+        .description(`Read the current accessibility hierarchy from ${article} active ${label} session`)
+        .argument('<id>', 'session id')
+        .option('--timeout <milliseconds>', 'capture timeout in milliseconds (100-60000)', String(DEFAULT_ACCESSIBILITY_TIMEOUT_MS))
+        .option('--json', 'output the stable typed tree as JSON', false)
+        .action((id, opts) => action(() => captureSimulatorAccessibilityTree(platform, id, opts), opts));
     addInteractionOptions(simulator
         .command('screenshot')
         .description(`Capture the current display from ${article} ${label} session`)
@@ -1036,6 +1261,7 @@ function jsonErrorEnvelope(error) {
                 retryable: error.retryable ?? (error.status === 408 || error.status === 429 || error.status >= 500),
                 httpStatus: error.status,
                 ...(error.details === undefined ? {} : { details: error.details }),
+                ...(error.suggestedAction ? { action: error.suggestedAction } : {}),
             },
         };
     }

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.115';
+export const CLI_VERSION = '0.1.117';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [

package/skills/run-cloud-ios-simulator/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: run-cloud-ios-simulator
-description: Operate run.cloud iOS simulator and Android emulator sessions with the CLI or TypeScript SDK. Use for creating, installing, inspecting, reading logs, controlling, embedding, smoke-testing, connecting local Metro, taking screenshots or screen recordings, injecting iOS media, or releasing remote mobile sessions.
+description: Operate run.cloud iOS simulator and Android emulator sessions with the CLI or TypeScript SDK. Use for creating, installing, inspecting accessibility or logs, controlling, embedding, smoke-testing, connecting local Metro, taking screenshots or screen recordings, injecting iOS media, or releasing remote mobile sessions.
 ---
 
 # Operate run.cloud Mobile Sessions
 
 Use the `runcloud` CLI for terminal workflows, `@run-cloud/sdk` for TypeScript,
-and `@run-cloud/ui` for React embeds.
+and `@runcloud/ui` for React embeds.
 
 ## Authenticate
 
@@ -58,6 +58,7 @@ runcloud ios swipe "$SESSION_ID" 0.5 0.8 0.5 0.2 --duration 300 --json
 runcloud ios type-text "$SESSION_ID" 'hello' --json
 runcloud ios press-key "$SESSION_ID" enter --json
 runcloud ios press-button "$SESSION_ID" home --json
+runcloud ios accessibility-tree "$SESSION_ID" --json
 runcloud ios screenshot "$SESSION_ID" --output ios.png --json
 ```
 
@@ -83,6 +84,15 @@ Android and returns a non-retryable `unsupported_action` on iOS.
 An acknowledgement means input dispatch completed. Confirm visible app effects
 with a screenshot or the signed viewer when the outcome matters.
 
+## Inspect Accessibility
+
+Use `runcloud ios|android accessibility-tree <id> --json` to read the current
+nested role, label, value, state, bounds, identifier, and child hierarchy. Read
+again after a control when the task depends on a state or navigation change.
+Check `truncated` before asserting that an element is absent. Prefer app-owned
+identifiers when available; generated node ids and paths can change with the
+hierarchy. Secure field values are always `null`.
+
 ## Record the Screen
 
 Both platforms expose the same session-scoped recording lifecycle:
@@ -137,6 +147,7 @@ typed acknowledgements. Use `RunCloudError` fields such as `code`, `retryable`,
 
 The lifecycle surface also includes `create`, `list`, `get`, `openUrl`, `logs`,
 `followLogs`, and `delete`. Both platforms expose `screenshot`,
+`accessibilityTree`,
 `startRecording`, `listRecordings`, `getRecording`, `stopRecording`, and
 `downloadRecording`; iOS additionally supports `uploadVideo` and
 `uploadMicrophoneAudio`. Inspect the installed types for complete create,
@@ -170,9 +181,10 @@ unavailable, report that requirement instead of guessing a public URL.
 
 ## Embed a Session
 
-- Use `RemoteControl` from `@run-cloud/ui` with the signed session URL.
+- Use `RemoteControl` from `@runcloud/ui` with the signed session URL.
 - Its ref exposes promise-based `interact` and convenience methods matching the
-  SDK controls. Handle `onInteractionResult` for inspectable acknowledgements.
+  SDK controls, plus `accessibilityTree`. Handle `onInteractionResult` for
+  inspectable acknowledgements and `onAccessibilityResult` for tree reads.
 - Add `embed=1` to raw iframe URLs. Add `loadingGuard=1` when interaction should
   wait for streaming and app readiness.
 - Raw iframe requests use `run-cloud:interaction`; acknowledgements use