runcloud 0.1.116 → 0.1.118

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,6 +80,7 @@ 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
 ```
 
@@ -117,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

@@ -116,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`;
 }
@@ -973,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`)

package/dist/diagnose.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { GoogleAuth, Impersonated } from 'google-auth-library';
+import { GoogleAuth } from 'google-auth-library';
 import { renderSessionDiagnosticTerminal, writeSessionDiagnosticBundle, } from './sessionDiagnostics.js';
 const execFileAsync = promisify(execFile);
 const AUTH_ATTEMPT_TIMEOUT_MS = 10_000;
@@ -87,10 +87,8 @@ function extractAuthorization(headers) {
     const h = headers;
     return h?.Authorization ?? h?.authorization;
 }
-async function gcloudIdentityToken(audience, serviceAccount) {
-    const args = ['auth', 'print-identity-token', `--audiences=${audience}`];
-    if (serviceAccount)
-        args.push(`--impersonate-service-account=${serviceAccount}`);
+async function gcloudIdentityToken(audience) {
+    const args = ['auth', 'print-identity-token', '--audiences=' + audience];
     const { stdout } = await execFileAsync('gcloud', args, { timeout: 15_000, maxBuffer: 1024 * 1024 });
     const token = stdout.trim();
     if (!token)
@@ -123,22 +121,32 @@ function exactAudienceAuthorization(authorization, audience) {
     }
     return authorization;
 }
-async function impersonatedIdentityToken(audience, serviceAccount) {
-    return withDeadline('service-account impersonation', async (signal) => {
+async function serviceAccountIdentityToken(audience, serviceAccount) {
+    return withDeadline('service-account ID-token minting', async (signal) => {
         const sourceClient = await new GoogleAuth({
             projectId: AUTH_DISCOVERY_PROJECT_ID,
             scopes: ['https://www.googleapis.com/auth/cloud-platform'],
             clientOptions: { transporterOptions: { signal, timeout: AUTH_ATTEMPT_TIMEOUT_MS } },
         }).getClient();
-        const impersonated = new Impersonated({
-            sourceClient,
-            targetPrincipal: serviceAccount,
-            targetScopes: ['https://www.googleapis.com/auth/cloud-platform'],
-            lifetime: 600,
-            transporterOptions: { signal, timeout: AUTH_ATTEMPT_TIMEOUT_MS },
+        const sourceToken = await sourceClient.getAccessToken();
+        const authorization = typeof sourceToken === 'string' ? sourceToken : sourceToken.token;
+        if (!authorization)
+            throw new Error('ADC returned an empty source access token');
+        const response = await fetch('https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/' +
+            encodeURIComponent(serviceAccount) + ':generateIdToken', {
+            method: "POST",
+            headers: {
+                Authorization: 'Bearer ' + authorization,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ audience, includeEmail: true }),
+            signal,
         });
-        const token = await impersonated.fetchIdToken(audience, { includeEmail: true });
-        return exactAudienceAuthorization(`Bearer ${token}`, audience);
+        const body = await response.json().catch(() => ({}));
+        if (!response.ok || typeof body.token !== 'string') {
+            throw new Error("generateIdToken failed (" + response.status + "): " + JSON.stringify(body.error ?? body));
+        }
+        return exactAudienceAuthorization('Bearer ' + body.token, audience);
     });
 }
 export async function resolveOpsAuthHeader(env = process.env, requestedAudience, requestedServiceAccount) {
@@ -158,13 +166,13 @@ export async function resolveOpsAuthHeader(env = process.env, requestedAudience,
     catch (error) {
         adcError = error instanceof Error ? error.message : String(error);
     }
-    let impersonationError = 'not configured';
+    let serviceAccountError = 'not configured';
     if (serviceAccount && env.DIAGNOSE_DISABLE_IMPERSONATION !== '1') {
         try {
-            return await impersonatedIdentityToken(audience, serviceAccount);
+            return await serviceAccountIdentityToken(audience, serviceAccount);
         }
         catch (error) {
-            impersonationError = error instanceof Error ? error.message : String(error);
+            serviceAccountError = error instanceof Error ? error.message : String(error);
         }
     }
     const token = env.DIAGNOSE_OPS_TOKEN;
@@ -173,13 +181,13 @@ export async function resolveOpsAuthHeader(env = process.env, requestedAudience,
     }
     if (env.DIAGNOSE_DISABLE_GCLOUD !== '1') {
         try {
-            return exactAudienceAuthorization(`Bearer ${await gcloudIdentityToken(audience, serviceAccount)}`, audience);
+            return exactAudienceAuthorization(`Bearer ${await gcloudIdentityToken(audience)}`, audience);
         }
         catch (error) {
             const gcloudError = error instanceof Error ? error.message : String(error);
             throw new Error(`No usable ops credential for audience ${audience}.\n` +
                 `ADC failed: ${truncate(adcError, 500)}\n` +
-                `Service-account impersonation failed: ${truncate(impersonationError, 500)}\n` +
+                `Service-account ID-token minting failed: ${truncate(serviceAccountError, 500)}\n` +
                 `gcloud failed: ${truncate(gcloudError, 500)}\n\n` +
                 'Repair access by adding the Google identity to control-plane `operators`, applying Terraform, ' +
                 'and running `gcloud auth application-default login`, then rerun. ' +
@@ -188,7 +196,7 @@ export async function resolveOpsAuthHeader(env = process.env, requestedAudience,
     }
     throw new Error(`No ops credential available for audience ${audience}. ` +
         `ADC failed: ${truncate(adcError, 300)}. ` +
-        `Service-account impersonation failed: ${truncate(impersonationError, 300)}. ` +
+        `Service-account ID-token minting failed: ${truncate(serviceAccountError, 300)}. ` +
         'Run `gcloud auth application-default login` after the operator Terraform has been applied, or export DIAGNOSE_OPS_TOKEN.');
 }
 function truncate(value, max = 200) {

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.116';
+export const CLI_VERSION = '0.1.118';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.116",
+  "version": "0.1.118",
   "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