@revyl/verify 0.2.0 → 0.3.1

package/dist/cli/login.js

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmod, lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { appUrl, RevylClient } from '../api/client.js';
+import { missingCredentialsMessage, resolveCredentials } from '../auth.js';
+import { isVerifyError, VerifyError } from '../errors.js';
+const AUTH_PATH = '/api/v1/entity/users/cli-device-authorizations';
+export async function signIn(options = {}) {
+    const existing = options.force ? undefined : await resolveCredentials();
+    if (existing)
+        return existing;
+    if (!process.stdin.isTTY || !process.stderr.isTTY || process.env.CI)
+        throw new VerifyError('AUTH_MISSING', `${missingCredentialsMessage()} Set the REVYL_API_KEY secret for non-interactive runs.`);
+    const backendUrl = new RevylClient({ token: '', backendUrl: options.backendUrl }).backendUrl;
+    const viewerOrigin = new URL(appUrl(options.appUrl)).origin;
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(600_000)]);
+    try {
+        const authorization = await post(backendUrl, AUTH_PATH, { client_instance_id: await clientInstanceId(), device_label: hostname().trim().replace(/\s+/g, ' ').slice(0, 80) || 'Revyl CLI' }, signal);
+        const deviceCode = requiredString(authorization, 'device_code');
+        const userCode = requiredString(authorization, 'user_code');
+        const rawUrl = requiredString(authorization, 'verification_uri_complete');
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            throw invalidResponse();
+        }
+        if (url.origin !== viewerOrigin || url.pathname !== '/cli/device' || url.username || url.password)
+            throw invalidResponse();
+        const expiresIn = authorization.expires_in;
+        const firstInterval = authorization.interval;
+        if (!Number.isInteger(expiresIn) || typeof expiresIn !== 'number' || expiresIn <= 0 || !Number.isInteger(firstInterval) || typeof firstInterval !== 'number' || firstInterval < 0)
+            throw invalidResponse();
+        const deadline = Date.now() + Math.min(expiresIn * 1000, 600_000);
+        let intervalMs = firstInterval > 0 ? firstInterval * 1000 : 5000;
+        process.stderr.write(`Open this URL to approve, then confirm the code below:\n${url.href}\nCode: ${userCode}\nWaiting for approval (Ctrl+C to cancel)...\n`);
+        openBrowser(url.href);
+        while (Date.now() < deadline) {
+            await delay(Math.min(intervalMs, deadline - Date.now()), undefined, { signal });
+            if (Date.now() >= deadline)
+                break;
+            const credential = await post(backendUrl, `${AUTH_PATH}/credentials`, { device_code: deviceCode }, signal);
+            if (credential.state === 'pending') {
+                intervalMs = Math.min(intervalMs * 1.5, 15_000);
+                continue;
+            }
+            if (credential.state === 'denied')
+                throw new VerifyError('AUTH_REJECTED', 'The Revyl login request was denied. Run your script again to sign in, or use revyl auth login.');
+            if (credential.state !== 'approved')
+                throw invalidResponse();
+            const token = requiredString(credential, 'api_key_token');
+            const who = await new RevylClient({ token, backendUrl }).whoAmI();
+            const concurrent = await resolveCredentials();
+            if (concurrent) {
+                try {
+                    await new RevylClient({ token: concurrent.token, backendUrl }).whoAmI();
+                    return concurrent;
+                }
+                catch (error) {
+                    if (!isVerifyError(error) || error.code !== 'AUTH_REJECTED')
+                        throw error;
+                }
+            }
+            const keyId = optionalString(credential, 'api_key_id');
+            const stored = {
+                ...(keyId ? { api_key: token, api_key_id: keyId, auth_method: 'browser_api_key' } : { access_token: token, expires_at: tokenExpiry(token), auth_method: 'browser' }),
+                ...(who.email || optionalString(credential, 'email') ? { email: who.email || optionalString(credential, 'email') } : {}),
+                ...(who.org_id || optionalString(credential, 'org_id') ? { org_id: who.org_id || optionalString(credential, 'org_id') } : {}),
+                ...(who.user_id || optionalString(credential, 'user_id') ? { user_id: who.user_id || optionalString(credential, 'user_id') } : {}),
+                ...(process.env.REVYL_API_KEY?.trim() ? { local_auth_override: true } : {}),
+            };
+            await writePrivateState('credentials.json', stored);
+            return { token, source: 'revyl-cli-login' };
+        }
+        throw new VerifyError('AUTH_MISSING', 'The Revyl login request expired. Run your script again to sign in, or use revyl auth login.');
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw new VerifyError('AUTH_MISSING', 'Revyl sign-in was cancelled or timed out. Run your script again to sign in, or use revyl auth login.');
+        throw error;
+    }
+    finally {
+        process.removeListener('SIGINT', cancel);
+        process.removeListener('SIGTERM', cancel);
+    }
+}
+async function post(backendUrl, path, body, signal) {
+    let response;
+    try {
+        response = await fetch(new URL(path, backendUrl), { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body), redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(15_000)]) });
+    }
+    catch {
+        throw new VerifyError('AUTH_MISSING', 'Could not reach Revyl to sign in. Run your script again, use revyl auth login, or set REVYL_API_KEY.');
+    }
+    if (response.status === 404)
+        throw new VerifyError('AUTH_MISSING', 'The Revyl login request is unavailable or expired. Run your script again, or use revyl auth login.');
+    if (!response.ok)
+        throw new VerifyError('AUTH_REJECTED', `Revyl sign-in failed (HTTP ${response.status}). Run your script again, use revyl auth login, or set REVYL_API_KEY.`);
+    let value;
+    try {
+        value = await response.json();
+    }
+    catch {
+        throw invalidResponse();
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw invalidResponse();
+    return value;
+}
+function requiredString(value, key) {
+    const text = optionalString(value, key);
+    if (!text)
+        throw invalidResponse();
+    return text;
+}
+function optionalString(value, key) {
+    const text = value[key];
+    if (text === null || text === undefined)
+        return undefined;
+    if (typeof text !== 'string' || text.length > 8192 || /[\x00-\x1f\x7f]/.test(text))
+        throw invalidResponse();
+    return text || undefined;
+}
+function invalidResponse() {
+    return new VerifyError('AUTH_REJECTED', 'Revyl returned an invalid sign-in response. Run your script again, use revyl auth login, or set REVYL_API_KEY.');
+}
+function tokenExpiry(token) {
+    try {
+        const payload = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8'));
+        if (typeof payload.exp === 'number' && Number.isFinite(payload.exp) && payload.exp > 0)
+            return new Date(Math.trunc(payload.exp) * 1000).toISOString();
+    }
+    catch { }
+    return new Date(Date.now() + 30 * 60_000).toISOString();
+}
+async function clientInstanceId() {
+    const path = join(homedir(), '.revyl', 'client-identity.json');
+    try {
+        const identity = JSON.parse(await readFile(path, 'utf8'));
+        if (identity && typeof identity === 'object' && 'client_instance_id' in identity && typeof identity.client_instance_id === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(identity.client_instance_id))
+            return identity.client_instance_id;
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError) && error.code !== 'ENOENT')
+            throw new VerifyError('AUTH_MISSING', 'Could not read the Revyl client identity. Check ~/.revyl permissions.');
+    }
+    const id = randomBytes(16).toString('hex');
+    await writePrivateState('client-identity.json', { client_instance_id: id });
+    return id;
+}
+async function writePrivateState(name, value) {
+    const directory = join(homedir(), '.revyl');
+    const destination = join(directory, name);
+    const temporary = join(directory, `.${name}.${randomBytes(16).toString('hex')}`);
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        if (!(await lstat(directory)).isDirectory() || (await lstat(directory)).isSymbolicLink())
+            throw new Error();
+        if (process.platform !== 'win32')
+            await chmod(directory, 0o700);
+        try {
+            if (!(await lstat(destination)).isFile())
+                throw new Error();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(`${JSON.stringify(value, null, 2)}\n`);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, destination);
+    }
+    catch {
+        throw new VerifyError('AUTH_MISSING', 'Could not save Revyl sign-in state. Use a writable, owner-only ~/.revyl directory.');
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+    const child = spawn(command, args, { stdio: 'ignore', timeout: 10_000 });
+    child.once('error', () => process.stderr.write('Open the URL above in your browser to finish signing in.\n'));
+    child.unref();
+}

package/dist/cli/main.js

@@ -6,11 +6,13 @@ import { missingCredentialsMessage, resolveCredentials } from '../auth.js';
 import { VerifyError, errorMessage, isVerifyError } from '../errors.js';
 import { PACKAGE_NAME, VERSION } from '../version.js';
 import { initProject, validateInitAnswers } from './init.js';
+import { installVerify, packageHasVerify } from './install.js';
+import { signIn } from './login.js';
 const HELP = `verify ${VERSION}: open Revyl cloud browsers, devices, and computers from your code
 
 Usage
-  npx ${PACKAGE_NAME} init [--platform web|ios|android|mac] [--app-id <id>] [--url <https-url>] [--force]
-      Write verify.config.ts and an example script, verify/example.ts
+  npx ${PACKAGE_NAME} init [--platform web|ios|android|mac] [--app-id <id>] [--url <https-url>] [--force] [--yes] [--no-install]
+      Install Verify, write verify.config.ts and an example script, then check authentication
   npx ${PACKAGE_NAME} whoami
       Check which Revyl account your credentials belong to
 
@@ -50,8 +52,11 @@ async function initCommand(args) {
             'app-id': { type: 'string' },
             url: { type: 'string' },
             force: { type: 'boolean' },
+            yes: { type: 'boolean' },
+            'no-install': { type: 'boolean' },
         },
     });
+    const interactive = Boolean(process.stdin.isTTY) && !process.env.CI;
     let answers;
     if (values.platform) {
         answers = validateInitAnswers({
@@ -60,23 +65,52 @@ async function initCommand(args) {
             ...(values.url ? { url: values.url } : {}),
         });
     }
-    else if (process.stdin.isTTY) {
-        answers = await askInitQuestions(values['app-id'], values.url);
-    }
-    else {
+    else if (!interactive) {
         throw new VerifyError('INVALID_ARGUMENT', 'Pass --platform web, ios, android, or mac when not running in a terminal.');
     }
+    if (!values['no-install'] && !(await packageHasVerify(process.cwd()))) {
+        let installApproved = !interactive || Boolean(values.yes);
+        if (interactive && !values.yes) {
+            const readline = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                const answer = (await readline.question(`Install ${PACKAGE_NAME} as a dev dependency? (Y/n) `)).trim().toLowerCase();
+                installApproved = answer === '' || answer === 'y' || answer === 'yes';
+            }
+            finally {
+                readline.close();
+            }
+        }
+        if (installApproved)
+            await installVerify(process.cwd());
+    }
+    answers ??= await askInitQuestions(values['app-id'], values.url);
     const result = await initProject(process.cwd(), answers, { force: values.force ?? false });
+    process.stdout.write(`Created ${result.created.join(' and ')}${result.gitignoreUpdated ? ', and added .verify/ to .gitignore' : ''}.\n`);
+    const credentials = await resolveCredentials();
+    if (!credentials) {
+        if (interactive) {
+            await signIn();
+        }
+        else {
+            throw new VerifyError('AUTH_MISSING', `${missingCredentialsMessage()} In non-interactive environments, set the REVYL_API_KEY secret.`);
+        }
+    }
+    try {
+        await whoamiCommand();
+    }
+    catch (error) {
+        if (!interactive || !isVerifyError(error) || error.code !== 'AUTH_REJECTED')
+            throw error;
+        await signIn({ force: true });
+        await whoamiCommand();
+    }
     const steps = [
-        `npm install --save-dev ${PACKAGE_NAME}`,
-        "Authenticate: export REVYL_API_KEY=<key from Revyl settings>, or run 'revyl auth login'",
-        ...(answers.platform === 'mac' ? [`Mac computers are not yet available in Revyl production. Early access works only on Revyl staging for enabled organizations; use the optional REVYL_BACKEND_URL override with staging credentials. Ask support@revyl.ai for access. See https://github.com/RevylAI/verify/blob/v${VERSION}/packages/verify/docs/computers.md#availability-and-errors`] : []),
+        'Configure the generated verify.config.ts if needed',
+        ...(answers.platform === 'mac' ? ['Mac computers are early access. Ask support@revyl.ai about access.'] : []),
         ...(answers.platform === 'mac' || answers.appId ? [] : ['Put your Revyl app id in verify.config.ts (or set REVYL_APP_ID)']),
         'node verify/example.ts',
     ];
     process.stdout.write([
-        `Created ${result.created.join(' and ')}${result.gitignoreUpdated ? ', and added .verify/ to .gitignore' : ''}.`,
-        '',
         'Next:',
         ...steps.map((step, index) => `  ${index + 1}. ${step}`),
         '',

package/dist/computer-session.d.ts

@@ -1,22 +1,32 @@
 import { RevylClient } from './api/client.js';
 import type { ComputerPlatform } from './api/types.js';
-import type { ResolvedComputerTarget } from './config.js';
-import { type ComputerProcess, type ComputerRecording, type ExecOptions, type ExecResult, type FileStat, type OperationOptions, type Session, type SessionOptions, type StepResult } from './session.js';
+import { type HostedTargetConfig, type ResolvedComputerTarget } from './config.js';
+import { type ComputerProcess, type ComputerRecording, type ExecOptions, type ExecResult, type FileStat, type OpenedSession, type OperationOptions, type Session, type SessionOptions, type StepResult } from './session.js';
 export declare class ComputerSession implements Session {
     private readonly client;
     private readonly options;
+    private readonly stopOnClose;
     readonly platform: ComputerPlatform;
     readonly target: string;
-    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly id: string;
     readonly viewerUrl: string;
     readonly steps: StepResult[];
     private readonly lifetime;
     private closePromise;
     private expiresAtMs;
     private screenReadyUntilMs;
+    private readonly children;
+    private readonly childStarts;
+    private closing;
     private constructor();
     static start(client: RevylClient, target: ResolvedComputerTarget, options: SessionOptions): Promise<ComputerSession>;
     get closed(): boolean;
+    static attach(client: RevylClient, computerId: string, options: SessionOptions & {
+        stopOnClose?: boolean;
+    }): Promise<ComputerSession>;
+    open(target: HostedTargetConfig): Promise<OpenedSession>;
+    report(): Promise<Record<string, unknown>>;
+    navigate(): Promise<never>;
     get expiresAt(): Date | undefined;
     recording(): Promise<ComputerRecording | null>;
     instruction(): Promise<never>;
@@ -34,7 +44,7 @@ export declare class ComputerSession implements Session {
     [Symbol.asyncDispose](): Promise<void>;
     private operation;
     private request;
-    private report;
+    private parseReport;
     private assertOpen;
     private observationSignal;
     private unavailable;

package/dist/computer-session.js

@@ -2,34 +2,41 @@ import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { responseDetail, responseErrorCode, sessionViewerUrl } from './api/client.js';
+import { edgeBlockedError, responseDetail, responseErrorCode, responseRefusalReason, sessionViewerUrl } from './api/client.js';
 import { trackSession, untrackSession } from './cleanup.js';
+import { validateHostedTarget } from './config.js';
 import { VerifyError, isVerifyError } from './errors.js';
-import { pngSize } from './session.js';
+import { DeviceSession, pngSize } from './session.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const STATES = new Set(['starting', 'active', 'closing', 'stopped', 'failed', 'owner_lost']);
 const MAX_OUTPUT_BYTES = 1_048_576;
-const COMPUTER_AVAILABILITY = 'Computers are not yet available in Revyl production. Early access works only on Revyl staging for enabled organizations and operating systems. See https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#availability-and-errors';
+const COMPUTER_AVAILABILITY = 'Computers are early access. Ask support@revyl.ai about access.';
 const COMPUTER_CAPACITY = 'Computer admission was refused because of queued work (including iOS) or the concurrency limit. Verify will not retry the start.';
 const ERROR_CODES = new Set(['computer_not_enabled', 'run_closed', 'inaccessible', 'invalid_handle', 'operation_not_found', 'owner_unavailable', 'invalid_request', 'unauthenticated', 'forbidden', 'runtime_unavailable', 'start_failed', 'computer_limit', 'request_conflict', 'run_conflict', 'evidence_conflict', 'evidence_unavailable', 'authentication_unavailable', 'operation_limit', 'screen_starting', 'screen_unavailable']);
 export class ComputerSession {
     client;
     options;
+    stopOnClose;
     platform;
     target;
-    id = randomUUID();
+    id;
     viewerUrl;
     steps = [];
     lifetime = new AbortController();
     closePromise;
     expiresAtMs;
     screenReadyUntilMs = 0;
-    constructor(client, target, options) {
+    children = new Set();
+    childStarts = new Set();
+    closing = false;
+    constructor(client, target, options, id = randomUUID(), stopOnClose = true) {
         this.client = client;
         this.options = options;
+        this.stopOnClose = stopOnClose;
+        this.id = id;
         this.target = target.name;
         this.platform = target.platform;
-        this.viewerUrl = sessionViewerUrl(this.id, 'computer');
+        this.viewerUrl = sessionViewerUrl(this.id, 'computer', options.appUrl);
     }
     static async start(client, target, options) {
         const session = new ComputerSession(client, target, options);
@@ -40,7 +47,7 @@ export class ComputerSession {
             session.log(`starting computer ${session.viewerUrl}. ${COMPUTER_AVAILABILITY}`);
             const response = await session.request('POST', '', { computer_session_id: session.id, os: target.platform === 'mac' ? 'macos' : 'linux' }, signal);
             createAcknowledged = true;
-            let report = session.report(response);
+            let report = session.parseReport(response);
             for (;;) {
                 if (report.state === 'active')
                     break;
@@ -49,7 +56,7 @@ export class ComputerSession {
                     throw new VerifyError('SESSION_START_FAILED', `The ${session.target} computer ended before it was ready (${report.state}).${reason} See ${session.viewerUrl}`);
                 }
                 await delay(2_000, undefined, { signal });
-                report = session.report(await session.request('GET', '/report', undefined, signal));
+                report = session.parseReport(await session.request('GET', '/report', undefined, signal));
             }
             session.screenReadyUntilMs = Date.now() + 30_000;
             session.log('ready');
@@ -57,7 +64,7 @@ export class ComputerSession {
         }
         catch (error) {
             const timedOut = signal.aborted;
-            if (!createAcknowledged && isVerifyError(error) && ['AUTH_REJECTED', 'NOT_AVAILABLE_ON_PLATFORM', 'INVALID_ARGUMENT', 'COMPUTER_LIMIT'].includes(error.code)) {
+            if (!createAcknowledged && isVerifyError(error) && ['AUTH_REJECTED', 'EDGE_BLOCKED', 'NOT_AVAILABLE_ON_PLATFORM', 'INVALID_ARGUMENT', 'COMPUTER_LIMIT'].includes(error.code)) {
                 session.lifetime.abort();
                 untrackSession(session);
             }
@@ -65,19 +72,63 @@ export class ComputerSession {
                 await session.close().catch(() => undefined);
             }
             if (timedOut)
-                throw new VerifyError('TIMEOUT', `The ${session.target} computer was not ready within ${target.startTimeout} ms. A possible cause is that no computer could be assigned. ${COMPUTER_AVAILABILITY}. Inspect ${session.viewerUrl}`);
+                throw new VerifyError('TIMEOUT', `The ${session.target} computer was not ready within ${target.startTimeout} ms. A possible cause is that no computer could be assigned. ${COMPUTER_AVAILABILITY} Inspect ${session.viewerUrl}`);
             throw error;
         }
     }
     get closed() {
         return this.closePromise !== undefined;
     }
+    static async attach(client, computerId, options) {
+        if (typeof computerId !== 'string' || !UUID.test(computerId))
+            throw new VerifyError('INVALID_ARGUMENT', 'attach() requires a computer session UUID.');
+        const probe = new ComputerSession(client, { name: 'computer', platform: 'mac', startTimeout: 600_000 }, options, computerId);
+        const response = await probe.request('GET', '/report', undefined, AbortSignal.timeout(30_000));
+        const raw = parseComputerJson(response);
+        if (!raw || raw.computer_session_id !== computerId || !['macos', 'linux'].includes(raw.os ?? '') || raw.expires_at == null)
+            throw invalidResponse();
+        const session = new ComputerSession(client, { name: raw.os === 'macos' ? 'mac' : 'linux', platform: raw.os === 'macos' ? 'mac' : 'linux', startTimeout: 600_000 }, options, computerId, options.stopOnClose ?? true);
+        session.parseReport(response);
+        if (raw.state !== 'active' || (session.expiresAtMs !== undefined && Date.now() >= session.expiresAtMs))
+            throw new VerifyError('SESSION_ENDED', 'The computer is not active or has expired.');
+        if (session.stopOnClose)
+            trackSession(session);
+        return session;
+    }
+    async open(target) {
+        this.assertOpen();
+        if (this.expiresAtMs === undefined)
+            throw new VerifyError('API_ERROR', 'The computer report must include expiry before opening a hosted child.');
+        const resolved = validateHostedTarget(target);
+        if ((this.platform === 'mac' && resolved.platform === 'android') || (this.platform === 'linux' && resolved.platform === 'ios'))
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'This computer cannot host the requested platform.', { reason: 'computer_cannot_host_platform' });
+        const pending = DeviceSession.start(this.client, resolved, this.options, {
+            id: this.id,
+            signal: this.lifetime.signal,
+            expiresAt: this.expiresAt,
+            register: (session) => { this.children.add(session); },
+        });
+        this.childStarts.add(pending);
+        try {
+            return await pending;
+        }
+        finally {
+            this.childStarts.delete(pending);
+        }
+    }
+    async report() {
+        const report = this.parseReport(await this.request('GET', '/report', undefined, AbortSignal.timeout(30_000)));
+        return { ...report };
+    }
+    navigate() {
+        return this.unavailable('navigate');
+    }
     get expiresAt() {
         return this.expiresAtMs === undefined ? undefined : new Date(this.expiresAtMs);
     }
     async recording() {
         const signal = AbortSignal.timeout(30_000);
-        const report = this.report(await this.request('GET', '/report', undefined, signal));
+        const report = this.parseReport(await this.request('GET', '/report', undefined, signal));
         if (!['stopped', 'failed', 'owner_lost'].includes(report.state) || report.release !== 'confirmed') {
             throw new VerifyError('SESSION_BUSY', `The computer recording can be requested only after terminal state and confirmed release. See ${this.viewerUrl}`);
         }
@@ -206,18 +257,34 @@ export class ComputerSession {
     }
     close() {
         this.closePromise ??= (async () => {
+            this.closing = true;
             this.lifetime.abort();
+            const childCleanup = (async () => {
+                await Promise.allSettled([...this.childStarts]);
+                return Promise.allSettled([...this.children].map((child) => child.close()));
+            })();
+            const childDeadline = new AbortController();
+            const childResults = await Promise.race([childCleanup, delay(5_000, undefined, { signal: childDeadline.signal })]);
+            childDeadline.abort();
             try {
-                const report = this.report(await this.request('POST', '/stop', undefined, AbortSignal.timeout(310_000)));
+                if (!this.stopOnClose) {
+                    if (!childResults || childResults.some((result) => result.status === 'rejected'))
+                        throw new VerifyError('ACTION_UNCERTAIN', `Hosted child cleanup is unconfirmed; the attached computer was left running. See ${this.viewerUrl}`);
+                    this.log('detached; computer left running');
+                    return;
+                }
+                const report = this.parseReport(await this.request('POST', '/stop', undefined, AbortSignal.timeout(310_000)));
                 if (report.release !== 'confirmed') {
                     throw new VerifyError('ACTION_UNCERTAIN', `Computer stop was requested, but physical release is unconfirmed. Inspect ${this.viewerUrl}`);
                 }
                 if (!['stopped', 'failed', 'owner_lost'].includes(report.state))
                     throw invalidResponse();
+                if (!childResults || childResults.some((result) => result.status === 'rejected'))
+                    this.log('a child stop was unconfirmed before the parent was released');
                 this.log('closed');
             }
             catch (error) {
-                if (isVerifyError(error) && error.code === 'ACTION_UNCERTAIN') {
+                if (this.stopOnClose && isVerifyError(error) && error.code === 'ACTION_UNCERTAIN') {
                     const message = `${error.message} A possible cause is that no computer could be assigned. ${COMPUTER_AVAILABILITY}`;
                     this.log(`close failed (ACTION_UNCERTAIN); ${message}`);
                     throw new VerifyError('ACTION_UNCERTAIN', message, { cause: error });
@@ -239,8 +306,17 @@ export class ComputerSession {
         const requestId = randomUUID();
         const operationId = computerOperationId(this.id, requestId);
         const signal = this.observationSignal(310_000);
+        let wireCommand = command;
+        if (command.kind === 'exec') {
+            const { argv, ...fields } = command;
+            wireCommand = { ...fields, argv_b64: argv.map(encodeWireText) };
+        }
+        else if (command.kind === 'file_read' || command.kind === 'file_write' || command.kind === 'file_stat') {
+            const { path, ...fields } = command;
+            wireCommand = { ...fields, path_b64: encodeWireText(path) };
+        }
         try {
-            let response = await this.request('POST', '/operations', { computer_session_id: this.id, request_id: requestId, command }, signal);
+            let response = await this.request('POST', '/operations', { computer_session_id: this.id, request_id: requestId, command: wireCommand }, signal);
             for (;;) {
                 if (signal.aborted)
                     throw signal.reason;
@@ -303,9 +379,13 @@ export class ComputerSession {
         }
         if (response.status >= 200 && response.status < 300)
             return response;
+        const blocked = edgeBlockedError(response);
+        if (blocked)
+            throw blocked;
         if (suffix === '/recording' && response.status === 404 && responseErrorCode(response) === 'recording_unavailable')
             return response;
-        const detail = responseDetail(response);
+        const detail = responseRefusalReason(response) ?? responseDetail(response);
+        const refusal = { reason: responseRefusalReason(response), httpStatus: response.status };
         if (suffix === '/screen/screenshot') {
             let raw = null;
             try {
@@ -317,12 +397,14 @@ export class ComputerSession {
                 return response;
         }
         if (detail === 'computer_not_enabled' || (response.status === 503 && detail === 'runtime_unavailable')) {
-            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `Revyl refused the computer request (${detail}). ${COMPUTER_AVAILABILITY}. Ask support@revyl.ai about staging organization enablement. See ${this.viewerUrl}`);
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `Revyl refused the computer request (${detail}). ${COMPUTER_AVAILABILITY} See ${this.viewerUrl}`, refusal);
         }
         if (response.status === 429 && detail === 'computer_limit')
-            throw new VerifyError('COMPUTER_LIMIT', `${COMPUTER_CAPACITY} See ${this.viewerUrl}`);
+            throw new VerifyError('COMPUTER_LIMIT', `${COMPUTER_CAPACITY} See ${this.viewerUrl}`, refusal);
         let code = 'API_ERROR';
-        if (detail === 'run_closed')
+        if (response.status === 401 || response.status === 403)
+            code = 'AUTH_REJECTED';
+        else if (detail === 'run_closed')
             code = 'SESSION_ENDED';
         else if (detail === 'inaccessible' || detail === 'invalid_handle')
             code = 'NOT_FOUND';
@@ -330,8 +412,6 @@ export class ComputerSession {
             code = 'ACTION_UNCERTAIN';
         else if (detail === 'invalid_request' || response.status === 422)
             code = 'INVALID_ARGUMENT';
-        else if (response.status === 401 || response.status === 403)
-            code = 'AUTH_REJECTED';
         else if (detail === 'start_failed')
             code = 'SESSION_START_FAILED';
         else if (response.status === 409 || detail === 'operation_limit')
@@ -341,9 +421,9 @@ export class ComputerSession {
         else if (method === 'POST' && (response.status >= 500 || response.status < 400))
             code = 'ACTION_UNCERTAIN';
         const reason = detail && ERROR_CODES.has(detail) ? detail : `HTTP ${response.status}`;
-        throw new VerifyError(code, `Revyl refused the computer request (${reason}). See ${this.viewerUrl}`);
+        throw new VerifyError(code, `Revyl refused the computer request (${reason}). See ${this.viewerUrl}`, refusal);
     }
-    report(response) {
+    parseReport(response) {
         const report = parseComputerJson(response);
         if (!report || report.computer_session_id !== this.id || !STATES.has(report.state))
             throw invalidResponse();
@@ -352,7 +432,7 @@ export class ComputerSession {
         return report;
     }
     assertOpen() {
-        if (this.closed || (this.expiresAtMs !== undefined && Date.now() >= this.expiresAtMs))
+        if (this.closing || this.closed || (this.expiresAtMs !== undefined && Date.now() >= this.expiresAtMs))
             throw new VerifyError('SESSION_ENDED', `The ${this.target} computer was closed or expired.`);
     }
     observationSignal(timeoutMs) {
@@ -379,6 +459,9 @@ function operationTimeout(options) {
         throw new VerifyError('INVALID_ARGUMENT', 'Computer operation timeout must be an integer from 1 to 300000 ms.');
     return timeout;
 }
+function encodeWireText(value) {
+    return Buffer.from(value, 'utf8').toString('base64').replaceAll('+', '-').replaceAll('/', '_');
+}
 function guestPath(path) {
     if (typeof path !== 'string' || !path || Buffer.byteLength(path) > 1024 || path.split('/').some((part) => ['', '.', '..'].includes(part)) || /[\x00-\x1f\x7f\\:]/.test(path))
         throw new VerifyError('INVALID_ARGUMENT', 'Computer paths must be workspace-relative, without empty, dot, parent, backslash, colon, or control-character components.');

package/dist/config.d.ts

@@ -52,6 +52,12 @@ export interface ComputerTargetConfig {
     startTimeout?: number;
 }
 export type TargetConfig = WebTargetConfig | MobileTargetConfig | ComputerTargetConfig;
+export type HostedTargetConfig = (Omit<WebTargetConfig, 'app'> | Omit<MobileTargetConfig, 'app' | 'device'>) & {
+    app: {
+        appId: string;
+        buildId: string;
+    };
+};
 export interface VerifyConfig {
     /** Named targets that open() takes by name, such as open('web'). */
     targets: Record<string, TargetConfig>;
@@ -85,4 +91,5 @@ export declare function loadConfig(cwd: string, explicitPath?: string): Promise<
 export declare function validateConfig(raw: unknown, configFile: string): ResolvedConfig;
 /** Validates a target passed straight to open(); it is named after its platform. */
 export declare function validateTarget(raw: unknown): ResolvedTarget;
+export declare function validateHostedTarget(raw: HostedTargetConfig): ResolvedDeviceTarget;
 export {};