runcloud 0.1.104 → 0.1.106

package/README.md

@@ -64,6 +64,8 @@ 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 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 …`
@@ -74,6 +76,10 @@ Useful `create` flags: `--region`, `--display-name`, `--inactivity-timeout 3m`,
 `--hard-timeout 1h`, `--install-asset <name-or-id>`, `--rm` (release when the
 command exits), `--json`.
 
+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.
+
 ### Tunnel a local dev server into a simulator
 
 ```bash

package/dist/commands/run-cloud.js

@@ -65,6 +65,40 @@ function formatRecord(value) {
         .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : String(v)}`)
         .join('\n');
 }
+export function consumeSimulatorLogSse(raw) {
+    const entries = [];
+    let offset = 0;
+    let separator = /\r?\n\r?\n/.exec(raw.slice(offset));
+    while (separator) {
+        const frameEnd = offset + separator.index;
+        const frame = raw.slice(offset, frameEnd);
+        offset = frameEnd + separator[0].length;
+        const data = frame
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith('data:'))
+            .map((line) => line.slice('data:'.length).trimStart())
+            .join('\n');
+        if (data) {
+            let value;
+            try {
+                value = JSON.parse(data);
+            }
+            catch {
+                throw new Error('Simulator log stream returned invalid JSON');
+            }
+            const entry = value;
+            if (!entry || typeof entry.timestamp !== 'string' || typeof entry.message !== 'string') {
+                throw new Error('Simulator log stream returned an invalid entry');
+            }
+            entries.push({ timestamp: entry.timestamp, message: entry.message });
+        }
+        separator = /\r?\n\r?\n/.exec(raw.slice(offset));
+    }
+    return { entries, remainder: raw.slice(offset) };
+}
+function writeSimulatorLogEntry(entry, json) {
+    console.log(json ? JSON.stringify(entry) : entry.message);
+}
 function parseLabels(labels) {
     const out = {};
     for (const raw of labels ?? []) {
@@ -338,6 +372,46 @@ function registerSimulatorCommands(program, platform) {
         .action((url, opts) => action(async () => {
         print(await client().post(`/run-cloud/${platform}/${encodeURIComponent(opts.id)}/open-url`, { url }), opts);
     }));
+    simulator
+        .command('logs')
+        .description(`Read or follow logs from ${article} active ${label} session`)
+        .argument('<id>')
+        .option('--tail <lines>', 'number of retained lines to return (1-1000)')
+        .option('-f, --follow', 'follow new log entries', false)
+        .option('--json', 'output JSON; follow mode emits one object per line', false)
+        .action((id, opts) => action(async () => {
+        if (opts.follow && opts.tail !== undefined) {
+            throw new Error('--tail cannot be combined with --follow');
+        }
+        const path = `/run-cloud/${platform}/${encodeURIComponent(id)}/logs`;
+        if (!opts.follow) {
+            const tail = opts.tail === undefined ? 200 : Number(opts.tail);
+            if (!Number.isInteger(tail) || tail < 1 || tail > 1_000) {
+                throw new Error('--tail must be an integer from 1 to 1000');
+            }
+            const snapshot = await client().get(`${path}?tail=${tail}`);
+            if (opts.json) {
+                print(snapshot, opts);
+                return;
+            }
+            const entries = Array.isArray(snapshot.entries) ? snapshot.entries : [];
+            for (const entry of entries)
+                writeSimulatorLogEntry(entry, false);
+            if (entries.length === 0)
+                console.error('No simulator logs captured for this lease.');
+            return;
+        }
+        let pending = '';
+        for await (const chunk of client().stream(`${path}?follow=1`)) {
+            const parsed = consumeSimulatorLogSse(`${pending}${chunk}`);
+            pending = parsed.remainder;
+            if (pending.length > 1024 * 1024) {
+                throw new Error('Simulator log stream returned an oversized incomplete event');
+            }
+            for (const entry of parsed.entries)
+                writeSimulatorLogEntry(entry, opts.json === true);
+        }
+    }));
     return simulator;
 }
 async function action(fn) {

package/dist/diagnose.js

@@ -3,6 +3,28 @@ import { promisify } from 'node:util';
 import { GoogleAuth, Impersonated } from 'google-auth-library';
 import { renderSessionDiagnosticTerminal, writeSessionDiagnosticBundle, } from './sessionDiagnostics.js';
 const execFileAsync = promisify(execFile);
+const AUTH_ATTEMPT_TIMEOUT_MS = 10_000;
+const AUTH_DISCOVERY_PROJECT_ID = 'newly-diagnostics';
+async function withDeadline(label, operation) {
+    const controller = new AbortController();
+    let timer;
+    try {
+        return await Promise.race([
+            operation(controller.signal),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`${label} timed out after ${AUTH_ATTEMPT_TIMEOUT_MS}ms`));
+                }, AUTH_ATTEMPT_TIMEOUT_MS);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 const DEFAULT_URLS = {
     dev: {
         apiOps: 'https://cp-api-ops-dev-97683904813.us-east4.run.app',
@@ -102,26 +124,36 @@ function exactAudienceAuthorization(authorization, audience) {
     return authorization;
 }
 async function impersonatedIdentityToken(audience, serviceAccount) {
-    const sourceClient = await new GoogleAuth({
-        scopes: ['https://www.googleapis.com/auth/cloud-platform'],
-    }).getClient();
-    const impersonated = new Impersonated({
-        sourceClient,
-        targetPrincipal: serviceAccount,
-        targetScopes: ['https://www.googleapis.com/auth/cloud-platform'],
-        lifetime: 600,
+    return withDeadline('service-account impersonation', 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 token = await impersonated.fetchIdToken(audience, { includeEmail: true });
+        return exactAudienceAuthorization(`Bearer ${token}`, audience);
     });
-    const token = await impersonated.fetchIdToken(audience, { includeEmail: true });
-    return exactAudienceAuthorization(`Bearer ${token}`, audience);
 }
 export async function resolveOpsAuthHeader(env = process.env, requestedAudience, requestedServiceAccount) {
     const audience = requestedAudience ?? env.DIAGNOSE_OIDC_AUDIENCE ?? 'newly-diagnose-ops';
     const serviceAccount = env.DIAGNOSE_OPS_IMPERSONATE_SERVICE_ACCOUNT ?? requestedServiceAccount;
     let adcError = 'unknown ADC error';
     try {
-        const auth = new GoogleAuth();
-        const client = await auth.getIdTokenClient(audience);
-        return exactAudienceAuthorization(extractAuthorization(await client.getRequestHeaders()), audience);
+        return await withDeadline('ADC ID-token resolution', async (signal) => {
+            const auth = new GoogleAuth({
+                projectId: AUTH_DISCOVERY_PROJECT_ID,
+                clientOptions: { transporterOptions: { signal, timeout: AUTH_ATTEMPT_TIMEOUT_MS } },
+            });
+            const client = await auth.getIdTokenClient(audience);
+            return exactAudienceAuthorization(extractAuthorization(await client.getRequestHeaders()), audience);
+        });
     }
     catch (error) {
         adcError = error instanceof Error ? error.message : String(error);
@@ -251,6 +283,8 @@ export async function fetchSessionDiagnosticReport(input) {
         params.set('session', input.session);
     if (input.project)
         params.set('project', projectIdFromInput(input.project));
+    if (input.user)
+        params.set('user', input.user);
     if (input.at)
         params.set('at', input.at);
     const res = await fetch(`${input.target.url}/diagnose/session?${params}`, {
@@ -293,17 +327,18 @@ export function registerDiagnose(program) {
         .option('--env <env>', 'dev, prod, or pr-<number>', 'dev')
         .option('--session <id>', 'diagnose this exact session')
         .option('--project <id-or-url>', 'diagnose the latest/nearest session for a project')
-        .option('--at <iso-time>', 'select the project session nearest this incident time')
+        .option('--user <email>', 'diagnose the latest/nearest session started by this user')
+        .option('--at <iso-time>', 'select the project/user session nearest this incident time')
         .option('--out <dir>', 'write evidence, report, diagram, and agent repro/fix prompt')
         .option('--json', 'emit the merged JSON document instead of the human rollup')
         .action(async (opts) => {
         try {
-            if (opts.session || opts.project) {
-                if (Boolean(opts.session) === Boolean(opts.project)) {
-                    throw new Error('Provide exactly one of --session or --project');
+            if (opts.session || opts.project || opts.user) {
+                if ([opts.session, opts.project, opts.user].filter(Boolean).length !== 1) {
+                    throw new Error('Provide exactly one of --session, --project, or --user');
                 }
-                if (opts.at && !opts.project) {
-                    throw new Error('--at requires --project because an exact --session needs no time selection');
+                if (opts.at && opts.session) {
+                    throw new Error('--at requires --project or --user because an exact --session needs no time selection');
                 }
                 if (opts.at && Number.isNaN(Date.parse(opts.at))) {
                     throw new Error('--at must be an ISO timestamp');
@@ -315,6 +350,7 @@ export function registerDiagnose(program) {
                     authHeader,
                     ...(opts.session ? { session: opts.session } : {}),
                     ...(opts.project ? { project: opts.project } : {}),
+                    ...(opts.user ? { user: opts.user } : {}),
                     ...(opts.at ? { at: opts.at } : {}),
                 });
                 if (opts.out) {
@@ -326,7 +362,7 @@ export function registerDiagnose(program) {
                 return;
             }
             if (opts.at || opts.out) {
-                throw new Error('--at and --out require --session or --project');
+                throw new Error('--at and --out require --session, --project, or --user');
             }
             if (opts.env !== 'dev' && opts.env !== 'prod') {
                 throw new Error('Global health diagnosis supports only --env dev or prod');

package/dist/sessionDiagnostics.js

@@ -24,7 +24,16 @@ function nodeLabel(report, id) {
     return `[${STATUS_TEXT[item.status]} ${item.label}]`;
 }
 export function renderAsciiDiagram(report) {
-    const main = ['session', 'venue', 'runner', 'command', 'metro', 'preview'];
+    const main = [
+        'session',
+        'venue',
+        'runner',
+        'command',
+        'metro',
+        'simulator_lease',
+        'simulator_app',
+        'preview',
+    ];
     const mainLine = main.map((id) => nodeLabel(report, id)).join(' -> ');
     const runnerOffset = main.slice(0, 3).map((id) => nodeLabel(report, id)).join(' -> ').length;
     const editor = nodeLabel(report, 'code_server');
@@ -42,7 +51,7 @@ function mermaidEscape(value) {
 export function renderMermaidDiagram(report) {
     const lines = [
         'flowchart LR',
-        '  session --> venue --> runner --> command --> metro --> preview',
+        '  session --> venue --> runner --> command --> metro --> simulator_lease --> simulator_app --> preview',
         '  runner --> code_server',
     ];
     for (const item of report.stages) {
@@ -172,6 +181,8 @@ Use the adjacent \`bundle.json\` as evidence, not as a conclusion to repeat blin
 
 If the diagnosis is \`evidence_missing\`, repair evidence collection first: verify the \`session_diagnostic_events\` migration is applied, API/worker/launcher provenance matches, and the controlled PR preview smoke persists its full correlated timeline. Do not infer a product cause from absent telemetry.
 
+For \`simulator_app_failed\`, inspect the persisted \`simulator.app.failed\` event first. In a live newly-desktop cloud session, call \`get_mobile_preview_logs\` to retrieve the retained native startup tail, Metro output, debugger status, and React Native log registry. Treat application exceptions as userland code to reproduce and fix in the project; do not relabel a successful \`simctl\`/\`adb\` launch as a healthy app.
+
 1. Identify the first boundary whose recorded output does not match its required input.
 2. Add or extend the smallest regression test that reproduces that exact failure. For cross-service delivery, use the normal PR environment smoke/e2e path instead of mocks alone.
 3. Fix the production path durably in \`control-plane/\`, \`newly-desktop/\`, or \`newly-cli/\`. Do not add work to the frozen legacy Modal backend or Neon stack.

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.104';
+export const CLI_VERSION = '0.1.106';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.104",
+  "version": "0.1.106",
   "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,6 +1,6 @@
 ---
 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, 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 device logs, embedding, smoke-testing, connecting local Metro, capturing iOS screenshots, injecting iOS media, or releasing remote mobile sessions.
 ---
 
 # Operate run.cloud Mobile Sessions
@@ -61,6 +61,7 @@ The shared mobile lifecycle is:
 - `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`,
@@ -84,6 +85,21 @@ 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.
 
+## Diagnose App Failures
+
+Read up to 1,000 retained entries from the current lease:
+
+```bash
+runcloud ios logs "$SESSION_ID" --tail 1000
+runcloud android logs "$SESSION_ID" --tail 1000
+```
+
+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:
@@ -136,9 +152,9 @@ try {
 The mobile SDK surface is:
 
 - `cloud.account()` and `cloud.usage({ orgId? })`
-- `cloud.ios`: `create`, `list`, `get`, `openUrl`, `screenshot`,
+- `cloud.ios`: `create`, `list`, `get`, `openUrl`, `logs`, `followLogs`, `screenshot`,
   `uploadVideo`, `uploadMicrophoneAudio`, `delete`
-- `cloud.android`: `create`, `list`, `get`, `openUrl`, `delete`
+- `cloud.android`: `create`, `list`, `get`, `openUrl`, `logs`, `followLogs`, `delete`
 - `cloud.simulators`: runtime-platform `create`, `list`, `get`, `openUrl`,
   `delete`
 - `cloud.assets`: `upload`, `list`, `delete`