runcloud 0.1.108 → 0.1.109

package/README.md

@@ -64,12 +64,18 @@ runcloud ios create --model iphone --install ./MyApp.app   # boot a simulator an
 runcloud ios list                                          # list active sessions
 runcloud ios get <id>                                      # inspect a session (viewer URL, status)
 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 screenshot <id> --output ios.png              # save a PNG without exposing the viewer URL
 runcloud ios logs <id> --tail 200                          # read logs from this lease
 runcloud ios logs <id> --follow                            # follow new log entries
 runcloud ios delete <id>                                   # release the session
 
 # Android works the same under `runcloud android …`
 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 screenshot <id> --output android.png --json
 ```
 
 Useful `create` flags: `--region`, `--display-name`, `--inactivity-timeout 3m`,
@@ -80,6 +86,23 @@ The same `logs` commands work for Android. Snapshots are limited to the active
 lease and accept 1 to 1,000 lines. In follow mode, `--json` emits one JSON object
 per line.
 
+Both platforms also expose `gesture`, `press-button`, `rotate`, `reload`,
+`scroll`, `toggle-software-keyboard`, `simulate-memory-warning`,
+`rotate-digital-crown`, and `set-render-debug`. Run `runcloud ios --help` or
+`runcloud android --help` for the full surface and per-command input choices.
+Current mobile sessions return an unsupported-action error for Digital Crown
+input; render-debug controls are iOS-only. Android Emulator sessions also
+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.
+
+Interaction commands wait for a correlated simulator acknowledgement. They
+accept `--timeout <milliseconds>` (15 seconds by default), `--request-id <id>`,
+and `--json`. Successful JSON is the API's typed completion envelope. Failures
+write a stable `{ ok: false, error: { code, message, retryable } }` envelope to
+stderr and exit non-zero. Ctrl-C cancels only the in-flight command, leaves the
+session active, and exits with code 130.
+
 ### Tunnel a local dev server into a simulator
 
 ```bash

package/dist/api.js

@@ -3,28 +3,84 @@ export class ApiError extends Error {
     status;
     detail;
     path;
-    constructor(status, detail, path) {
+    code;
+    retryable;
+    details;
+    requestId;
+    sessionId;
+    platform;
+    action;
+    interactionStatus;
+    acceptedAt;
+    completedAt;
+    durationMs;
+    constructor(status, detail, path, context = {}) {
         super(`API ${status}: ${detail}`);
         this.status = status;
         this.detail = detail;
         this.path = path;
+        this.name = 'ApiError';
+        Object.assign(this, context);
     }
 }
-function parsedErrorDetail(body) {
+export class ApiTransportError extends Error {
+    path;
+    originalError;
+    constructor(path, originalError) {
+        super('Could not reach the run.cloud API');
+        this.path = path;
+        this.originalError = originalError;
+        this.name = 'ApiTransportError';
+    }
+}
+function parsedError(body) {
     try {
         const parsed = JSON.parse(body);
-        const detail = parsed.detail ?? parsed.error ?? parsed.message;
-        if (typeof detail === 'string')
-            return detail;
-        if (detail !== undefined)
-            return JSON.stringify(detail);
+        const nested = parsed.error && typeof parsed.error === 'object'
+            ? parsed.error
+            : undefined;
+        const rawDetail = nested?.message ?? parsed.detail ?? parsed.error ?? parsed.message;
+        const detail = typeof rawDetail === 'string'
+            ? rawDetail
+            : rawDetail === undefined ? '' : JSON.stringify(rawDetail);
+        const retryable = nested?.retryable ?? parsed.retryable;
+        const interactionStatus = parsed.status === 'failed'
+            || parsed.status === 'cancelled'
+            || parsed.status === 'timed_out'
+            ? parsed.status
+            : undefined;
+        const platform = parsed.platform === 'ios' || parsed.platform === 'android'
+            ? parsed.platform
+            : undefined;
+        return {
+            detail,
+            ...(typeof (nested?.code ?? parsed.code) === 'string'
+                ? { code: (nested?.code ?? parsed.code) }
+                : {}),
+            ...(typeof retryable === 'boolean' ? { retryable } : {}),
+            ...((nested?.details ?? parsed.details) === undefined
+                ? {}
+                : { details: nested?.details ?? parsed.details }),
+            ...(typeof parsed.requestId === 'string' ? { requestId: parsed.requestId } : {}),
+            ...(typeof parsed.sessionId === 'string' ? { sessionId: parsed.sessionId } : {}),
+            ...(platform ? { platform } : {}),
+            ...(typeof parsed.action === 'string' ? { action: parsed.action } : {}),
+            ...(interactionStatus ? { interactionStatus } : {}),
+            ...(typeof parsed.acceptedAt === 'string' ? { acceptedAt: parsed.acceptedAt } : {}),
+            ...(typeof parsed.completedAt === 'string' ? { completedAt: parsed.completedAt } : {}),
+            ...(typeof parsed.durationMs === 'number' && Number.isFinite(parsed.durationMs)
+                ? { durationMs: parsed.durationMs }
+                : {}),
+        };
     }
     catch {
     }
     if (/<(?:!doctype|html)\b/i.test(body)) {
-        return 'the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer command';
+        return {
+            detail: 'the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer command',
+        };
     }
-    return body;
+    return { detail: body };
 }
 export class ApiClient {
     baseUrl;
@@ -33,18 +89,27 @@ export class ApiClient {
         this.baseUrl = baseUrl;
         this.token = token;
     }
-    async request(method, path, body) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method,
-            headers: {
-                Authorization: `Bearer ${this.token}`,
-                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
-            },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
+    async request(method, path, body, options = {}) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
+            throw new ApiTransportError(path, error);
+        }
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -56,8 +121,8 @@ export class ApiClient {
         const response = await this.request('GET', path);
         return response.text();
     }
-    post(path, body) {
-        return this.request('POST', path, body);
+    post(path, body, options = {}) {
+        return this.request('POST', path, body, options);
     }
     async postWithHeaders(path, body, headers) {
         const res = await fetch(`${this.baseUrl}${path}`, {
@@ -70,8 +135,8 @@ export class ApiClient {
             body: JSON.stringify(body),
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -95,8 +160,8 @@ export class ApiClient {
             body: body,
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType_ = res.headers.get('content-type') ?? '';
         return contentType_.includes('application/json') ? res.json() : res;
@@ -110,20 +175,29 @@ export class ApiClient {
             body: form,
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
     }
-    async getBinary(path) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method: 'GET',
-            headers: { Authorization: `Bearer ${this.token}` },
-        });
+    async getBinary(path, options = {}) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method: 'GET',
+                headers: { Authorization: `Bearer ${this.token}`, ...options.headers },
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
+            throw new ApiTransportError(path, error);
+        }
         if (!res.ok) {
-            const detail = await res.text().catch(() => '');
-            throw new ApiError(res.status, detail || res.statusText, path);
+            const { detail, ...context } = parsedError(await res.text().catch(() => ''));
+            throw new ApiError(res.status, detail || res.statusText, path, context);
         }
         return Buffer.from(await res.arrayBuffer());
     }
@@ -133,8 +207,8 @@ export class ApiClient {
             headers: { Authorization: `Bearer ${this.token}`, Accept: 'text/event-stream' },
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text().catch(() => ''));
-            throw new ApiError(res.status, detail || res.statusText, path);
+            const { detail, ...context } = parsedError(await res.text().catch(() => ''));
+            throw new ApiError(res.status, detail || res.statusText, path, context);
         }
         const decoder = new TextDecoder();
         for await (const chunk of res.body) {

package/dist/commands/run-cloud.js

@@ -3,9 +3,91 @@ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFil
 import { basename, dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { createHash } from 'node:crypto';
-import { ApiClient, friendlyApiError } from '../api.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { ApiClient, ApiError, ApiTransportError, friendlyApiError } from '../api.js';
 import { requireCredentials } from '../config.js';
+export const SIMULATOR_KEYS = [
+    'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
+    'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z',
+    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
+    'enter', 'escape', 'backspace', 'tab', 'space', 'minus', 'equal',
+    'bracketLeft', 'bracketRight', 'backslash', 'semicolon', 'quote', 'backquote',
+    'comma', 'period', 'slash', 'capsLock',
+    'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 'f11', 'f12',
+    'printScreen', 'scrollLock', 'pause', 'insert', 'home', 'pageUp', 'delete', 'end',
+    'pageDown', 'arrowRight', 'arrowLeft', 'arrowDown', 'arrowUp', 'numLock',
+    'numpadDivide', 'numpadMultiply', 'numpadSubtract', 'numpadAdd', 'numpadEnter',
+    'numpad0', 'numpad1', 'numpad2', 'numpad3', 'numpad4', 'numpad5', 'numpad6',
+    'numpad7', 'numpad8', 'numpad9', 'numpadDecimal',
+];
+export const SIMULATOR_BUTTONS = [
+    'home', 'back', 'appSwitcher', 'recents', 'power', 'volumeUp', 'volumeDown',
+    'menu', 'sideButton', 'actionButton', 'digitalCrown',
+];
+export const SIMULATOR_RENDER_DEBUG_OPTIONS = [
+    'colorBlendedLayers',
+    'colorCopiedImages',
+    'colorMisalignedImages',
+    'colorOffscreenRendered',
+    'slowAnimations',
+];
+export const SIMULATOR_INTERACTION_ERROR_CODES = [
+    'invalid_interaction',
+    'active_session_not_found',
+    'simulator_capacity_unavailable',
+    'unsupported_action',
+    'duplicate_request',
+    'interaction_cancelled',
+    'interaction_timeout',
+    'interaction_transport_error',
+    'interaction_invalid_response',
+    'interaction_failed',
+];
+export const SIMULATOR_SCREENSHOT_ERROR_CODES = [
+    'invalid_screenshot_request',
+    'active_session_not_found',
+    'simulator_capacity_unavailable',
+    'screenshot_cancelled',
+    'screenshot_timeout',
+    'screenshot_transport_error',
+    'screenshot_invalid_response',
+    'screenshot_failed',
+];
+const simulatorInteractionErrorCodeSet = new Set(SIMULATOR_INTERACTION_ERROR_CODES);
+const simulatorScreenshotErrorCodeSet = new Set(SIMULATOR_SCREENSHOT_ERROR_CODES);
+function normalizedInteractionErrorCode(value) {
+    if (typeof value === 'string' && simulatorInteractionErrorCodeSet.has(value)) {
+        return value;
+    }
+    switch (value) {
+        case 'timeout':
+        case 'timed_out':
+        case 'interaction_transport_timeout':
+            return 'interaction_timeout';
+        case 'cancelled':
+            return 'interaction_cancelled';
+        case 'invalid_request':
+            return 'invalid_interaction';
+        case 'simulator_session_ended':
+            return 'active_session_not_found';
+        case 'unsupported_on_platform':
+            return 'unsupported_action';
+        case 'invalid_host_response':
+        case 'invalid_interaction_result':
+        case 'interaction_platform_mismatch':
+            return 'interaction_invalid_response';
+        default:
+            return 'interaction_failed';
+    }
+}
+function normalizedScreenshotErrorCode(value) {
+    return typeof value === 'string' && simulatorScreenshotErrorCodeSet.has(value)
+        ? value
+        : 'screenshot_failed';
+}
+const DEFAULT_INTERACTION_TIMEOUT_MS = 15_000;
+const INTERACTION_RESPONSE_MARGIN_MS = 250;
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 export const RUN_CLOUD_SKILL_NAMES = [
     'run-cloud',
     'run-cloud-ios-simulator',
@@ -109,6 +191,300 @@ function parseTags(labels) {
     }
     return out;
 }
+function integerInRange(raw, name, min, max, fallback) {
+    if (raw === undefined && fallback !== undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`${name} must be an integer from ${min} to ${max}`);
+    }
+    return value;
+}
+function finiteInRange(raw, name, min, max) {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < min || value > max) {
+        throw new Error(`${name} must be a number from ${min} to ${max}`);
+    }
+    return value;
+}
+function normalizedPoint(x, y, name) {
+    return {
+        x: finiteInRange(x, `${name} x`, 0, 1),
+        y: finiteInRange(y, `${name} y`, 0, 1),
+    };
+}
+function simulatorKey(raw) {
+    if (SIMULATOR_KEYS.includes(raw))
+        return raw;
+    throw new Error(`Unknown simulator key: ${raw}. Run with --help to see supported semantic keys.`);
+}
+function simulatorButton(raw) {
+    if (SIMULATOR_BUTTONS.includes(raw))
+        return raw;
+    throw new Error(`Unknown simulator button: ${raw}. Choose one of: ${SIMULATOR_BUTTONS.join(', ')}.`);
+}
+function simulatorOrientation(raw) {
+    if (raw === 'portrait' || raw === 'portrait_upside_down' || raw === 'landscape_left' || raw === 'landscape_right') {
+        return raw;
+    }
+    throw new Error(`Unknown orientation: ${raw}. Choose portrait, portrait_upside_down, landscape_left, or landscape_right.`);
+}
+function renderDebugOption(raw) {
+    if (SIMULATOR_RENDER_DEBUG_OPTIONS.includes(raw)) {
+        return raw;
+    }
+    throw new Error(`Unknown render debug option: ${raw}. Choose one of: ${SIMULATOR_RENDER_DEBUG_OPTIONS.join(', ')}.`);
+}
+function booleanArgument(raw, name) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    throw new Error(`${name} must be true or false`);
+}
+function isUsAsciiText(text) {
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code !== 9 && code !== 10 && (code < 32 || code > 126))
+            return false;
+    }
+    return true;
+}
+function assertInteraction(interaction, timeoutMs) {
+    switch (interaction.action) {
+        case 'tap':
+            return;
+        case 'swipe':
+            if (interaction.durationMs !== undefined) {
+                integerInRange(String(interaction.durationMs), '--duration', 50, 30_000);
+            }
+            return;
+        case 'gesture': {
+            if (interaction.steps.length < 2 || interaction.steps.length > 1_000) {
+                throw new Error('--steps must contain from 2 to 1000 gesture steps');
+            }
+            let pointCount;
+            let totalDelayMs = 0;
+            for (const [index, step] of interaction.steps.entries()) {
+                if ((index === 0) !== (step.phase === 'begin')) {
+                    throw new Error('Gesture steps must start with begin and contain no later begin phase');
+                }
+                if ((index === interaction.steps.length - 1) !== (step.phase === 'end')) {
+                    throw new Error('Gesture steps must end with end and contain no earlier end phase');
+                }
+                if (step.points.length !== 1 && step.points.length !== 2) {
+                    throw new Error('Each gesture step must contain one or two points');
+                }
+                if (pointCount === undefined)
+                    pointCount = step.points.length;
+                else if (pointCount !== step.points.length) {
+                    throw new Error('Every gesture step must use the same number of points');
+                }
+                for (const point of step.points) {
+                    finiteInRange(String(point.x), 'gesture x', 0, 1);
+                    finiteInRange(String(point.y), 'gesture y', 0, 1);
+                }
+                if (step.delayMs !== undefined) {
+                    if (index === interaction.steps.length - 1 && step.delayMs !== 0) {
+                        throw new Error('Final gesture end step delayMs must be 0 because there is no next step');
+                    }
+                    totalDelayMs += integerInRange(String(step.delayMs), 'gesture delayMs', 0, 5_000);
+                }
+            }
+            if (totalDelayMs > timeoutMs)
+                throw new Error('Gesture delays cannot exceed --timeout');
+            return;
+        }
+        case 'typeText':
+            if (interaction.text.length < 1 || interaction.text.length > 10_000) {
+                throw new Error('text must contain from 1 to 10000 characters');
+            }
+            if (!isUsAsciiText(interaction.text)) {
+                throw new Error('text must contain only US ASCII characters, tabs, and line feeds');
+            }
+            return;
+        case 'pressKey':
+        case 'pressButton':
+            if (interaction.durationMs !== undefined) {
+                integerInRange(String(interaction.durationMs), '--duration', 20, 30_000);
+            }
+            return;
+        case 'scroll':
+            if (interaction.deltaX === 0 && interaction.deltaY === 0) {
+                throw new Error('At least one scroll delta must be nonzero');
+            }
+            return;
+        case 'rotateDigitalCrown':
+            if (interaction.delta === 0)
+                throw new Error('digital crown delta must be nonzero');
+            return;
+        default:
+            return;
+    }
+}
+export function parseSimulatorGestureSteps(raw, timeoutMs = DEFAULT_INTERACTION_TIMEOUT_MS) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--steps must be a valid JSON array');
+    }
+    if (!Array.isArray(value))
+        throw new Error('--steps must be a JSON array');
+    const steps = value.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            throw new Error(`Gesture step ${index} must be an object`);
+        }
+        const record = item;
+        if (record.phase !== 'begin' && record.phase !== 'move' && record.phase !== 'end') {
+            throw new Error(`Gesture step ${index} phase must be begin, move, or end`);
+        }
+        if (!Array.isArray(record.points) || (record.points.length !== 1 && record.points.length !== 2)) {
+            throw new Error(`Gesture step ${index} must contain one or two points`);
+        }
+        const points = record.points.map((point, pointIndex) => {
+            if (!point || typeof point !== 'object' || Array.isArray(point)) {
+                throw new Error(`Gesture step ${index} point ${pointIndex} must contain x and y`);
+            }
+            const candidate = point;
+            return normalizedPoint(String(candidate.x), String(candidate.y), `gesture step ${index} point ${pointIndex}`);
+        });
+        const tuple = points.length === 1
+            ? [points[0]]
+            : [points[0], points[1]];
+        const delayMs = record.delayMs === undefined
+            ? undefined
+            : integerInRange(String(record.delayMs), `gesture step ${index} delayMs`, 0, 5_000);
+        return {
+            phase: record.phase,
+            points: tuple,
+            ...(delayMs === undefined ? {} : { delayMs }),
+        };
+    });
+    assertInteraction({ action: 'gesture', steps }, timeoutMs);
+    return steps;
+}
+function interactionTimeout(opts) {
+    return integerInRange(opts.timeout, '--timeout', 100, 60_000, DEFAULT_INTERACTION_TIMEOUT_MS);
+}
+function interactionRequestId(opts) {
+    const requestId = opts.requestId?.trim() || `cli_${randomUUID()}`;
+    if (!REQUEST_ID_PATTERN.test(requestId)) {
+        throw new Error('--request-id must match /^[A-Za-z0-9._:-]{1,128}$/');
+    }
+    return requestId;
+}
+class CliInteractionError extends Error {
+    code;
+    requestId;
+    actionName;
+    sessionId;
+    platform;
+    constructor(message, code, requestId, actionName, sessionId, platform) {
+        super(message);
+        this.code = code;
+        this.requestId = requestId;
+        this.actionName = actionName;
+        this.sessionId = sessionId;
+        this.platform = platform;
+        this.name = 'CliInteractionError';
+    }
+}
+async function withInteractionCancellation(timeoutMs, requestId, actionName, sessionId, platform, operation, run) {
+    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));
+    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);
+    try {
+        return await run(controller.signal);
+    }
+    catch (error) {
+        if (controller.signal.aborted && controller.signal.reason instanceof CliInteractionError) {
+            throw controller.signal.reason;
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        process.removeListener('SIGINT', onSigint);
+    }
+}
+function addInteractionOptions(command) {
+    return command
+        .option('--timeout <milliseconds>', 'acknowledgement timeout in milliseconds (100-60000)', String(DEFAULT_INTERACTION_TIMEOUT_MS))
+        .option('--request-id <id>', 'caller-supplied correlation id')
+        .option('--json', 'output a stable JSON result or error envelope', false);
+}
+async function runSimulatorInteraction(platform, id, interaction, opts) {
+    const timeoutMs = interactionTimeout(opts);
+    const requestId = interactionRequestId(opts);
+    assertInteraction(interaction, timeoutMs);
+    let result;
+    try {
+        result = await withInteractionCancellation(timeoutMs, requestId, interaction.action, id, platform, 'interaction', async (signal) => await client().post(`/run-cloud/${platform}/${encodeURIComponent(id)}/interactions`, { ...interaction, requestId, timeoutMs }, { signal }));
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            Object.assign(error, {
+                code: normalizedInteractionErrorCode(error.code),
+                requestId: error.requestId ?? requestId,
+                sessionId: error.sessionId ?? id,
+                platform: error.platform ?? platform,
+                action: error.action ?? interaction.action,
+            });
+        }
+        if (error instanceof ApiTransportError) {
+            throw new CliInteractionError(`Simulator ${interaction.action} could not reach the run.cloud API`, 'interaction_transport_error', requestId, interaction.action, id, platform);
+        }
+        throw error;
+    }
+    print(result, opts);
+}
+async function captureSimulatorScreenshot(platform, id, opts) {
+    const timeoutMs = interactionTimeout(opts);
+    const requestId = interactionRequestId(opts);
+    let bytes;
+    try {
+        bytes = await withInteractionCancellation(timeoutMs, requestId, 'screenshot', id, platform, 'screenshot', async (signal) => await client().getBinary(`/run-cloud/${platform}/${encodeURIComponent(id)}/screenshot`, { signal, headers: { 'X-Run-Cloud-Request-ID': requestId } }));
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            Object.assign(error, {
+                code: normalizedScreenshotErrorCode(error.code),
+                requestId: error.requestId ?? requestId,
+                sessionId: error.sessionId ?? id,
+                platform: error.platform ?? platform,
+                action: error.action ?? 'screenshot',
+            });
+        }
+        if (error instanceof ApiTransportError) {
+            throw new CliInteractionError('Simulator screenshot could not reach the run.cloud API', 'screenshot_transport_error', requestId, 'screenshot', id, platform);
+        }
+        throw error;
+    }
+    if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+        throw new CliInteractionError('Simulator screenshot response was not a valid PNG image', 'screenshot_invalid_response', requestId, 'screenshot', id, platform);
+    }
+    const output = resolve(opts.output);
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, bytes);
+    const result = {
+        ok: true,
+        requestId,
+        sessionId: id,
+        platform,
+        action: 'screenshot',
+        status: 'completed',
+        output,
+        byteSize: bytes.byteLength,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+    };
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(`Saved ${platform} simulator screenshot to ${output} (${bytes.byteLength} bytes)`);
+}
 function fileBlob(path) {
     const resolved = resolve(path);
     if (!existsSync(resolved))
@@ -319,7 +695,9 @@ async function createSimulatorSession(platform, opts) {
 function registerSimulatorCommands(program, platform) {
     const label = platform === 'android' ? 'Android emulator' : 'iOS simulator';
     const article = platform === 'android' ? 'an' : 'an';
-    const simulator = program.command(platform).description(`Create, list, inspect, and delete ${label} sessions`);
+    const simulator = program
+        .command(platform)
+        .description(`Create, inspect, interact with, capture, and release ${label} sessions`);
     simulator
         .command('create')
         .description(`Create a remote ${label} session`)
@@ -372,6 +750,138 @@ function registerSimulatorCommands(program, platform) {
         .action((url, opts) => action(async () => {
         print(await client().post(`/run-cloud/${platform}/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
     }));
+    addInteractionOptions(simulator
+        .command('tap')
+        .description(`Tap normalized display coordinates in ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<x>', 'normalized x coordinate from 0 (left) to 1 (right)')
+        .argument('<y>', 'normalized y coordinate from 0 (top) to 1 (bottom)')).action((id, x, y, opts) => action(() => runSimulatorInteraction(platform, id, { action: 'tap', ...normalizedPoint(x, y, 'tap') }, opts), opts));
+    addInteractionOptions(simulator
+        .command('swipe')
+        .description(`Swipe between normalized display coordinates in ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<from-x>', 'start x from 0 to 1')
+        .argument('<from-y>', 'start y from 0 to 1')
+        .argument('<to-x>', 'end x from 0 to 1')
+        .argument('<to-y>', 'end y from 0 to 1')
+        .option('--duration <milliseconds>', 'swipe duration in milliseconds (50-30000)')).action((id, fromX, fromY, toX, toY, opts) => action(() => runSimulatorInteraction(platform, id, {
+        action: 'swipe',
+        from: normalizedPoint(fromX, fromY, 'swipe start'),
+        to: normalizedPoint(toX, toY, 'swipe end'),
+        ...(opts.duration === undefined
+            ? {}
+            : { durationMs: integerInRange(opts.duration, '--duration', 50, 30_000) }),
+    }, opts), opts));
+    addInteractionOptions(simulator
+        .command('gesture')
+        .description(`Run an ordered one- or two-finger gesture in ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .requiredOption('--steps <json>', 'JSON steps: [{"phase":"begin|move|end","points":[{"x":0.5,"y":0.5}],"delayMs":0}]')).action((id, opts) => action(() => runSimulatorInteraction(platform, id, {
+        action: 'gesture',
+        steps: parseSimulatorGestureSteps(opts.steps, interactionTimeout(opts)),
+    }, opts), opts));
+    addInteractionOptions(simulator
+        .command('type-text')
+        .description(`Type US ASCII text into ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<text>', '1-10000 US ASCII characters; quote text containing spaces')).action((id, text, opts) => action(() => runSimulatorInteraction(platform, id, { action: 'typeText', text }, opts), opts));
+    addInteractionOptions(simulator
+        .command('press-key')
+        .description(`Press a semantic keyboard key in ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<key>', 'semantic key, for example a, enter, arrowUp, or f1')
+        .option('--duration <milliseconds>', 'key hold duration in milliseconds (20-30000)')
+        .option('--shift', 'hold the left Shift modifier', false)
+        .option('--control', 'hold the left Control modifier', false)
+        .option('--alt', 'hold the left Alt modifier', false)
+        .option('--meta', 'hold the left Meta/Command modifier', false)
+        .addHelpText('after', `\nSupported keys:\n  ${SIMULATOR_KEYS.join(', ')}\n`)).action((id, rawKey, opts) => action(() => {
+        const modifiers = ['shift', 'control', 'alt', 'meta']
+            .filter((modifier) => opts[modifier]);
+        return runSimulatorInteraction(platform, id, {
+            action: 'pressKey',
+            key: simulatorKey(rawKey),
+            ...(modifiers.length ? { modifiers } : {}),
+            ...(opts.duration === undefined
+                ? {}
+                : { durationMs: integerInRange(opts.duration, '--duration', 20, 30_000) }),
+        }, opts);
+    }, opts));
+    addInteractionOptions(simulator
+        .command('press-button')
+        .description(`Press a simulator hardware or system button in ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<button>', `one of: ${SIMULATOR_BUTTONS.join(', ')}`)
+        .option('--duration <milliseconds>', 'button hold duration in milliseconds (20-30000)')).action((id, rawButton, opts) => action(() => runSimulatorInteraction(platform, id, {
+        action: 'pressButton',
+        button: simulatorButton(rawButton),
+        ...(opts.duration === undefined
+            ? {}
+            : { durationMs: integerInRange(opts.duration, '--duration', 20, 30_000) }),
+    }, opts), opts));
+    addInteractionOptions(simulator
+        .command('rotate')
+        .description(`Set the absolute display orientation for ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<orientation>', 'portrait, portrait_upside_down, landscape_left, or landscape_right')).action((id, rawOrientation, opts) => action(() => runSimulatorInteraction(platform, id, {
+        action: 'rotate',
+        orientation: simulatorOrientation(rawOrientation),
+    }, opts), opts));
+    addInteractionOptions(simulator
+        .command('reload')
+        .description(`Reload the foreground app in ${article} ${label} session`)
+        .argument('<id>', 'session id')).action((id, opts) => action(() => runSimulatorInteraction(platform, id, { action: 'reload' }, opts), opts));
+    addInteractionOptions(simulator
+        .command('scroll')
+        .description(`Send normalized scroll deltas to ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<delta-x>', 'horizontal delta from -1 to 1')
+        .argument('<delta-y>', 'vertical delta from -1 to 1')
+        .option('--x <coordinate>', 'normalized anchor x; requires --y')
+        .option('--y <coordinate>', 'normalized anchor y; requires --x')).action((id, deltaX, deltaY, opts) => action(() => {
+        if ((opts.x === undefined) !== (opts.y === undefined))
+            throw new Error('--x and --y must be provided together');
+        const anchor = opts.x !== undefined && opts.y !== undefined
+            ? normalizedPoint(opts.x, opts.y, 'scroll anchor')
+            : undefined;
+        return runSimulatorInteraction(platform, id, {
+            action: 'scroll',
+            deltaX: finiteInRange(deltaX, 'delta-x', -1, 1),
+            deltaY: finiteInRange(deltaY, 'delta-y', -1, 1),
+            ...(anchor ?? {}),
+        }, opts);
+    }, opts));
+    addInteractionOptions(simulator
+        .command('toggle-software-keyboard')
+        .description(`Toggle the software keyboard in ${article} ${label} session`)
+        .argument('<id>', 'session id')).action((id, opts) => action(() => runSimulatorInteraction(platform, id, { action: 'toggleSoftwareKeyboard' }, opts), opts));
+    addInteractionOptions(simulator
+        .command('simulate-memory-warning')
+        .description(`Send a memory-warning event to ${article} ${label} session`)
+        .argument('<id>', 'session id')).action((id, opts) => action(() => runSimulatorInteraction(platform, id, { action: 'simulateMemoryWarning' }, opts), opts));
+    addInteractionOptions(simulator
+        .command('rotate-digital-crown')
+        .description(`Request Digital Crown input for ${article} ${label} session (unsupported on current mobile sessions)`)
+        .argument('<id>', 'session id')
+        .argument('<delta>', 'nonzero crown delta from -10000 to 10000')).action((id, delta, opts) => action(() => runSimulatorInteraction(platform, id, {
+        action: 'rotateDigitalCrown',
+        delta: finiteInRange(delta, 'delta', -10_000, 10_000),
+    }, opts), opts));
+    addInteractionOptions(simulator
+        .command('set-render-debug')
+        .description(`Enable or disable a simulator render diagnostic in ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .argument('<option>', `one of: ${SIMULATOR_RENDER_DEBUG_OPTIONS.join(', ')}`)
+        .argument('<enabled>', 'true or false')).action((id, rawOption, rawEnabled, opts) => action(() => runSimulatorInteraction(platform, id, {
+        action: 'setRenderDebug',
+        option: renderDebugOption(rawOption),
+        enabled: booleanArgument(rawEnabled, 'enabled'),
+    }, opts), opts));
+    addInteractionOptions(simulator
+        .command('screenshot')
+        .description(`Capture the current display from ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .requiredOption('-o, --output <path>', 'PNG output path')).action((id, opts) => action(() => captureSimulatorScreenshot(platform, id, opts), opts));
     simulator
         .command('logs')
         .description(`Read or follow logs from ${article} active ${label} session`)
@@ -414,16 +924,89 @@ function registerSimulatorCommands(program, platform) {
     }));
     return simulator;
 }
-async function action(fn) {
+function jsonErrorEnvelope(error) {
+    if (error instanceof ApiError) {
+        return {
+            ok: false,
+            ...(error.requestId ? { requestId: error.requestId } : {}),
+            ...(error.sessionId ? { sessionId: error.sessionId } : {}),
+            ...(error.platform ? { platform: error.platform } : {}),
+            ...(error.action ? { action: error.action } : {}),
+            ...(error.interactionStatus ? { status: error.interactionStatus } : {}),
+            ...(error.acceptedAt ? { acceptedAt: error.acceptedAt } : {}),
+            ...(error.completedAt ? { completedAt: error.completedAt } : {}),
+            ...(error.durationMs === undefined ? {} : { durationMs: error.durationMs }),
+            error: {
+                code: error.code ?? `http_${error.status}`,
+                message: error.detail || friendlyApiError(error),
+                retryable: error.retryable ?? (error.status === 408 || error.status === 429 || error.status >= 500),
+                httpStatus: error.status,
+                ...(error.details === undefined ? {} : { details: error.details }),
+            },
+        };
+    }
+    if (error instanceof CliInteractionError) {
+        const status = error.code.endsWith('_timeout')
+            ? 'timed_out'
+            : error.code.endsWith('_cancelled')
+                ? 'cancelled'
+                : 'failed';
+        return {
+            ok: false,
+            requestId: error.requestId,
+            sessionId: error.sessionId,
+            platform: error.platform,
+            action: error.actionName,
+            status,
+            error: {
+                code: error.code,
+                message: error.message,
+                retryable: !error.code.endsWith('_cancelled'),
+            },
+        };
+    }
+    return {
+        ok: false,
+        error: {
+            code: 'invalid_request',
+            message: error instanceof Error ? error.message : String(error),
+            retryable: false,
+        },
+    };
+}
+async function action(fn, opts = {}) {
     try {
         await fn();
     }
     catch (err) {
-        console.error(friendlyApiError(err));
-        process.exitCode = 1;
+        console.error(opts.json ? JSON.stringify(jsonErrorEnvelope(err), null, 2) : friendlyApiError(err));
+        process.exitCode = err instanceof CliInteractionError && err.code.endsWith('_cancelled') ? 130 : 1;
     }
 }
+function configureMachineReadableParseErrors(program) {
+    const output = program.configureOutput();
+    program.configureOutput({
+        ...output,
+        outputError: (message, write) => {
+            const rawArgs = program.rawArgs ?? [];
+            const argumentsSeen = [...process.argv, ...rawArgs, ...program.args];
+            if (!argumentsSeen.includes('--json')) {
+                (output.outputError ?? ((value, destination) => destination(value)))(message, write);
+                return;
+            }
+            write(`${JSON.stringify({
+                ok: false,
+                error: {
+                    code: 'invalid_request',
+                    message: message.replace(/^error:\s*/i, '').trim(),
+                    retryable: false,
+                },
+            })}\n`);
+        },
+    });
+}
 export function registerRunCloud(program) {
+    configureMachineReadableParseErrors(program);
     const sample = program
         .command('sample')
         .alias('samples')

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.108';
+export const CLI_VERSION = '0.1.109';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.108",
+  "version": "0.1.109",
   "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,44 +1,32 @@
 ---
 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 device logs, embedding, smoke-testing, connecting local Metro, capturing iOS screenshots, 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, reading logs, controlling, embedding, smoke-testing, connecting local Metro, taking screenshots, injecting iOS media, or releasing remote mobile sessions.
 ---
 
 # Operate run.cloud Mobile Sessions
 
-Use run.cloud through the `runcloud` CLI for terminal workflows and
-`@run-cloud/sdk` for application, CI, or agent code.
+Use the `runcloud` CLI for terminal workflows, `@run-cloud/sdk` for TypeScript,
+and `@run-cloud/ui` for React embeds.
 
 ## Authenticate
 
 - Install the CLI with `npm install -g runcloud`.
-- Use `runcloud login` for an interactive browser handoff. Use
-  `runcloud login --manual` when a local callback cannot open.
+- Use `runcloud login`; add `--manual` when a local callback cannot open.
 - In CI, set `RUN_CLOUD_API_KEY`. `RUN_CLOUD_API_TOKEN` is an equivalent alias.
-- Set `RUN_CLOUD_API_URL` only to override the production default
-  `https://api.run.cloud`.
-- Never print, commit, or place credentials in a skill file.
-- Treat signed simulator URLs and tunnel URLs as bearer secrets.
-- Require Node.js 20 or newer for the CLI and TypeScript SDK.
+- Set `RUN_CLOUD_API_URL` only to override `https://api.run.cloud`.
+- Require Node.js 20 or newer.
+- Never print, commit, or place credentials in a skill file. Treat signed session
+  and tunnel URLs as bearer secrets.
 
-Inspect account and organization credit before starting metered work:
+Check access and credit before starting metered work:
 
 ```bash
 runcloud account --json
 ```
 
-Sessions require product access, organization credit below its ceiling, and
-available fleet capacity. A create request may queue while capacity is full.
+The SDK equivalents are `cloud.account()` and `cloud.usage({ orgId? })`.
 
-## Choose the Interface
-
-- Prefer CLI commands with `--json` for shell automation.
-- Prefer `@run-cloud/sdk` for TypeScript applications and CI.
-- Inspect `runcloud <command> --help` or installed SDK types before using a
-  method not documented here.
-
-## Use the CLI
-
-Create an iOS session, capture its ID, open a deep link, and release it:
+## Create and Release Sessions
 
 ```bash
 SESSION_ID=$(runcloud ios create \
@@ -48,79 +36,51 @@ SESSION_ID=$(runcloud ios create \
   --json | jq -r '.id')
 
 trap 'runcloud ios delete "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
-
 runcloud ios get "$SESSION_ID" --json
-runcloud ios open-url myapp://settings --id "$SESSION_ID" --json
 ```
 
-Use the corresponding `runcloud android` commands for Android artifacts.
-
-The shared mobile lifecycle is:
-
-- `runcloud ios|android create`
-- `runcloud ios|android list [--all]`
-- `runcloud ios|android get <id>`
-- `runcloud ios|android open-url <url> --id <id>`
-- `runcloud ios|android logs <id> [--tail N|--follow]`
-- `runcloud ios|android delete <id>`
-
-Create accepts `--model`, `--region`, `--display-name`, repeatable `--label`,
-repeatable `--install`, repeatable `--install-asset`,
-`--inactivity-timeout`, `--hard-timeout`, `--codec`, `--rm`, and `--json`.
-
-Use assets and samples when no local artifact is ready:
-
-```bash
-runcloud sample download ios
-runcloud ios create --install ./run-cloud-sample-ios.app.tar.gz --json
-
-runcloud asset push ./build/MyApp.tar.gz --name my-app --json
-runcloud ios create --install-asset my-app --json
-runcloud asset list --json
-runcloud asset pull <asset-id> --output ./MyApp.tar.gz
-runcloud asset delete <asset-id> --json
-```
+Replace `ios` with `android` for an Android artifact. The shared lifecycle is
+`create`, `list`, `get`, `open-url`, `logs`, and `delete`. Use `--json` whenever
+another program consumes output, and inspect `runcloud ios|android --help` for
+create and log options.
 
 iOS needs an Apple Silicon simulator-compatible `.app`, `.zip`, `.tar.gz`, or
-`.ipa` artifact. A device-signed App Store IPA is not a substitute. Android
-needs an emulator-compatible artifact such as an APK.
+`.ipa`; a device-signed App Store IPA is not a substitute. Android needs an
+emulator-compatible APK.
 
-## Diagnose App Failures
+## Control a Session
 
-Read up to 1,000 retained entries from the current lease:
+Both platform groups expose acknowledged controls:
 
 ```bash
-runcloud ios logs "$SESSION_ID" --tail 1000
-runcloud android logs "$SESSION_ID" --tail 1000
+runcloud ios tap "$SESSION_ID" 0.5 0.3 --json
+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 screenshot "$SESSION_ID" --output ios.png --json
 ```
 
-Use `--follow` while reproducing an issue, and add `--json` when another tool
-will consume the entries. `--tail` and `--follow` are mutually exclusive.
-Before releasing a failed session, always capture a bounded snapshot and keep
-the relevant entries with the test evidence. A follow stream contains only new
-entries and is not a substitute for the retained snapshot.
-
-## Connect Local Development
-
-Connect a local Metro or mock server to an active iOS session:
+The full control set is `tap`, `swipe`, `gesture`, `type-text`, `press-key`,
+`press-button`, `rotate`, `reload`, `scroll`, `toggle-software-keyboard`,
+`simulate-memory-warning`, `rotate-digital-crown`, `set-render-debug`, and
+`screenshot`. Every interaction accepts `--request-id`, `--timeout`, and
+`--json`; use `runcloud <platform> <control> --help` for its typed arguments.
 
-```bash
-runcloud ios tunnel "$SESSION_ID" \
-  --local-port 8081 \
-  --service metro \
-  --json
-
-runcloud ios tunnel-status --json
-```
+Coordinates use the current display orientation: `(0, 0)` is top-left and
+`(1, 1)` is bottom-right. Gesture steps use one or two points with `begin`,
+`move`, and `end` phases. Each `delayMs` is the pause before the next step, so
+the final `end` step must use `0`. Key names are semantic US-keyboard names;
+modifiers are `shift`, `control`, `alt`, and `meta`. Current mobile sessions do
+not support Digital Crown input, and Android does not support iOS render-debug
+controls or the `capsLock`, `numLock`, and `scrollLock` keys. Handle structured
+`unsupported_action` errors instead of retrying them.
 
-Use the run.cloud sidecar flow. Do not install or expose an unauthenticated
-third-party tunnel. If the sidecar is unavailable, report that requirement
-instead of guessing a public URL.
+An acknowledgement means input dispatch completed. Confirm visible app effects
+with a screenshot or the signed viewer when the outcome matters.
 
 ## Use the TypeScript SDK
 
-Install the SDK:
-
 ```bash
 npm install @run-cloud/sdk
 ```
@@ -132,84 +92,96 @@ import { writeFile } from "node:fs/promises";
 import { Client } from "@run-cloud/sdk";
 
 const cloud = new Client();
-const session = await cloud.ios.create({
-  displayName: "Agent smoke",
-  tags: { owner: "agent" },
+const session = await cloud.android.create({
   inactivityTimeout: "60s",
   hardTimeout: "10m",
-  codec: "auto",
+  tags: { owner: "agent" },
 });
 
 try {
-  await cloud.ios.openUrl(session.id, "https://run.cloud");
-  const screenshot = await cloud.ios.screenshot(session.id);
-  await writeFile("run-cloud.png", screenshot);
+  await cloud.android.tap(session.id, { x: 0.5, y: 0.3 });
+  await cloud.android.typeText(session.id, "hello");
+  await cloud.android.pressKey(session.id, "enter");
+  const screenshot = await cloud.android.screenshot(session.id);
+  await writeFile("android.png", screenshot);
 } finally {
-  await cloud.ios.delete(session.id);
+  await cloud.android.delete(session.id);
 }
 ```
 
-The mobile SDK surface is:
+`cloud.ios`, `cloud.android`, and the platform-selectable `cloud.simulators`
+expose `interact` plus convenience methods matching every CLI control above.
+Interaction options accept `requestId`, `timeoutMs`, and `signal`; results are
+typed acknowledgements. Use `RunCloudError` fields such as `code`, `retryable`,
+`requestId`, and `action` when reporting API failures.
 
-- `cloud.account()` and `cloud.usage({ orgId? })`
-- `cloud.ios`: `create`, `list`, `get`, `openUrl`, `logs`, `followLogs`, `screenshot`,
-  `uploadVideo`, `uploadMicrophoneAudio`, `delete`
-- `cloud.android`: `create`, `list`, `get`, `openUrl`, `logs`, `followLogs`, `delete`
-- `cloud.simulators`: runtime-platform `create`, `list`, `get`, `openUrl`,
-  `delete`
-- `cloud.assets`: `upload`, `list`, `delete`
+The lifecycle surface also includes `create`, `list`, `get`, `openUrl`, `logs`,
+`followLogs`, and `delete`. Both platforms expose `screenshot`; iOS additionally
+supports `uploadVideo` and `uploadMicrophoneAudio`. Inspect the installed types
+for complete create, asset, log, and media options.
 
-Create options include `model`, `region`, `displayName`, `tags`,
-`installAssets`, `inactivityTimeout`, `hardTimeout`, and `codec`.
+In compact form, `cloud.ios`: `create`, `list`, `get`, `openUrl`, `logs`, `followLogs`, `screenshot`.
+`cloud.android` provides the same shared lifecycle and control operations.
 
-Do not invent SDK methods for scripted taps, typing, recording, app lifecycle,
-or Android screenshots. Browser-stream interaction and iframe commands are
-separate from the public SDK.
+## Diagnose App Failures
 
-## Inject iOS Media
+```bash
+runcloud ios logs "$SESSION_ID" --tail 1000
+runcloud android logs "$SESSION_ID" --tail 1000
+```
+
+Use `--follow` while reproducing an issue. Before releasing a failed session,
+capture a bounded retained snapshot; a follow stream contains only new entries.
 
-Use `cloud.ios.uploadVideo(id, video, options)` for MP4 or QuickTime video. It
-stores a user-owned asset and imports it into Photos.
+## Connect Local Development
 
-Use `cloud.ios.uploadMicrophoneAudio(id, audio, options)` for AAC, M4A, MP3,
-MP4-audio, or WAV. Pass an optional `bundleId`; otherwise it targets the
-foreground app. The operation relaunches the target app with microphone
-permission and loops the decoded audio through `AVAudioEngine`.
+Connect a local Metro or mock server through the supported sidecar flow:
+
+```bash
+runcloud ios tunnel "$SESSION_ID" --local-port 8081 --service metro --json
+runcloud ios tunnel-status --json
+```
 
-Delete uploaded assets when they are no longer needed.
+Do not expose an unauthenticated third-party tunnel. If the sidecar is
+unavailable, report that requirement instead of guessing a public URL.
 
 ## Embed a Session
 
-- In React, use `RemoteControl` from `@runcloud/ui` with the signed session URL.
-- Add `embed=1` to the signed session URL for the clean iframe UI.
-- Add `loadingGuard=1` when the iframe should block interaction until streaming
-  and app launch are ready.
-- For raw iframes, verify both `event.source` and the exact signed-URL origin
-  before processing messages, and use that exact origin as the command
-  `postMessage` target.
-- Handle `ios-simulator:status`, `ios-simulator:auth-error`,
-  `ios-simulator:session-ended`, and
-  `ios-simulator:session-restart-requested`.
-- Create a new session after a restart request; never reuse an ended URL.
-- Use `ios-simulator:command` for `reload`, `home`, `rotate`, `screenshot`, and
-  `toggleAccessibility`.
-
-## Run Maintained Demos
+- Use `RemoteControl` from `@run-cloud/ui` with the signed session URL.
+- Its ref exposes promise-based `interact` and convenience methods matching the
+  SDK controls. Handle `onInteractionResult` for inspectable acknowledgements.
+- 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
+  `run-cloud:interaction-result`. Correlate them by `requestId`. To stop a
+  pending request, post `run-cloud:interaction-cancel` with the same
+  `requestId` and `action`.
+- Verify `event.source` and the exact signed-URL origin, and use that origin as
+  the `postMessage` target.
+- Legacy `ios-simulator:command` messages remain compatibility-only. Prefer the
+  generic acknowledged interaction channel for new code.
+- Create a new session after an `ios-simulator:session-restart-requested`
+  message; never reuse an ended URL.
+
+## Assets, Samples, and Demos
 
 ```bash
+runcloud sample download ios
+runcloud asset push ./build/MyApp.tar.gz --name my-app --json
+runcloud asset pull <asset-id>
+runcloud ios create --install-asset my-app --json
 runcloud demo run eight-device-mosaic --open
 runcloud demo run live-camera-relay --open
 ```
 
-The bundled demos release their sessions automatically.
+Delete uploaded assets when no longer needed. Bundled demos release their
+sessions automatically.
 
 ## Guardrails
 
-- Release every session created during a task unless the user explicitly asks
-  to keep it open.
+- Release every session created during a task unless asked to keep it open.
 - Use inactivity and hard timeouts for unattended work.
-- Verify platform compatibility before changing application code after an
+- Verify artifact/platform compatibility before changing app code after an
   install failure.
 - Do not expose credentials, signed viewer URLs, tunnel URLs, or simulator
   tokens in logs, screenshots, PR comments, or chat output.
-- Do not claim that browser iframe controls are public SDK methods.