runcloud 0.1.108 → 0.1.110

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,341 @@ 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 simulatorRecordingBase(platform, sessionId) {
+    return `/run-cloud/${platform}/${encodeURIComponent(sessionId)}/recordings`;
+}
+function recordingIdempotencyKey(value) {
+    if (value === undefined)
+        return undefined;
+    const key = value.trim();
+    const hasControlCharacter = [...key].some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31 || code === 127;
+    });
+    if (!key || key.length > 200 || hasControlCharacter) {
+        throw new Error('--idempotency-key must contain 1-200 printable characters');
+    }
+    return key;
+}
+async function downloadSimulatorRecording(platform, sessionId, recordingId, opts) {
+    const bytes = await client().getBinary(`${simulatorRecordingBase(platform, sessionId)}/${encodeURIComponent(recordingId)}/download`);
+    if (bytes.length < 8 || bytes.subarray(4, 8).toString('ascii') !== 'ftyp') {
+        throw new Error('Simulator recording response was not a valid MP4 file');
+    }
+    const output = resolve(opts.output);
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, bytes);
+    const result = {
+        ok: true,
+        sessionId,
+        recordingId,
+        platform,
+        action: 'recording.download',
+        status: 'completed',
+        output,
+        contentType: 'video/mp4',
+        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 recording to ${output} (${bytes.byteLength} bytes)`);
+}
 function fileBlob(path) {
     const resolved = resolve(path);
     if (!existsSync(resolved))
@@ -319,7 +736,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 +791,188 @@ 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));
+    const recording = simulator
+        .command('recording')
+        .alias('recordings')
+        .description(`Record the display of ${article} ${label} session`);
+    recording
+        .command('start')
+        .description(`Start an MP4 screen recording for ${article} active ${label} session`)
+        .argument('<id>', 'session id')
+        .option('--idempotency-key <key>', 'retry-safe key; reuse it to receive the same recording')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        const key = recordingIdempotencyKey(opts.idempotencyKey);
+        const headers = key ? { 'Idempotency-Key': key } : {};
+        print(await client().postWithHeaders(simulatorRecordingBase(platform, id), {}, headers), opts);
+    }, opts));
+    recording
+        .command('list')
+        .description(`List retained screen recordings for ${article} ${label} session`)
+        .argument('<id>', 'session id')
+        .option('--json', 'output JSON', false)
+        .action((id, opts) => action(async () => {
+        print(await client().get(simulatorRecordingBase(platform, id)), opts);
+    }, opts));
+    recording
+        .command('status')
+        .alias('get')
+        .description(`Show lifecycle state, failures, events, and retrieval metadata for a recording`)
+        .argument('<id>', 'session id')
+        .argument('<recording-id>', 'recording id')
+        .option('--json', 'output JSON', false)
+        .action((id, recordingId, opts) => action(async () => {
+        print(await client().get(`${simulatorRecordingBase(platform, id)}/${encodeURIComponent(recordingId)}`), opts);
+    }, opts));
+    recording
+        .command('stop')
+        .description(`Stop and finalize a screen recording as an MP4`)
+        .argument('<id>', 'session id')
+        .argument('<recording-id>', 'recording id')
+        .option('--json', 'output JSON', false)
+        .action((id, recordingId, opts) => action(async () => {
+        print(await client().post(`${simulatorRecordingBase(platform, id)}/${encodeURIComponent(recordingId)}/stop`), opts);
+    }, opts));
+    recording
+        .command('download')
+        .description(`Download a ready screen recording through the authenticated API`)
+        .argument('<id>', 'session id')
+        .argument('<recording-id>', 'recording id')
+        .requiredOption('-o, --output <path>', 'MP4 output path')
+        .option('--json', 'output file metadata as JSON', false)
+        .action((id, recordingId, opts) => action(() => downloadSimulatorRecording(platform, id, recordingId, opts), opts));
     simulator
         .command('logs')
         .description(`Read or follow logs from ${article} active ${label} session`)
@@ -414,16 +1015,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')