@revyl/verify 0.1.0 → 0.3.0

package/dist/computer-session.js

@@ -2,54 +2,69 @@ 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, 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 MAC_AVAILABILITY = 'Mac computers are not yet available in Revyl production. Early access works only on Revyl staging for enabled organizations. 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;
-    platform = 'mac';
+    stopOnClose;
+    platform;
     target;
-    id = randomUUID();
+    id;
     viewerUrl;
     steps = [];
     lifetime = new AbortController();
     closePromise;
-    constructor(client, target, options) {
+    expiresAtMs;
+    screenReadyUntilMs = 0;
+    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.viewerUrl = sessionViewerUrl(this.id, 'computer');
+        this.platform = target.platform;
+        this.viewerUrl = sessionViewerUrl(this.id, 'computer', options.appUrl);
     }
     static async start(client, target, options) {
-        if (target.platform !== 'mac')
-            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'Linux computers are planned, but are not available in Verify yet.');
         const session = new ComputerSession(client, target, options);
         const signal = AbortSignal.any([AbortSignal.timeout(target.startTimeout), session.lifetime.signal]);
+        let createAcknowledged = false;
         trackSession(session);
         try {
-            session.log(`starting mac computer ${session.viewerUrl}. ${MAC_AVAILABILITY}`);
-            let report = session.report(await session.request('POST', '', { computer_session_id: session.id, os: 'macos' }, signal));
+            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.parseReport(response);
             for (;;) {
                 if (report.state === 'active')
                     break;
-                if (report.state !== 'starting')
-                    throw new VerifyError('SESSION_START_FAILED', `The ${session.target} computer ended before it was ready (${report.state}). See ${session.viewerUrl}`);
+                if (report.state !== 'starting') {
+                    const reason = report.failure_reason === 'no_host' ? ' No host claimed the start within the 120-second unclaimed-start window.' : report.failure_reason === 'device_limit' ? ` ${COMPUTER_CAPACITY}` : '';
+                    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');
             return session;
         }
         catch (error) {
             const timedOut = signal.aborted;
-            if (isVerifyError(error) && ['AUTH_REJECTED', 'NOT_AVAILABLE_ON_PLATFORM', 'INVALID_ARGUMENT'].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);
             }
@@ -57,13 +72,84 @@ 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 Mac computer could be assigned. ${MAC_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.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}`);
+        }
+        const response = await this.request('GET', '/recording', undefined, signal);
+        if (response.status === 404 && responseErrorCode(response) === 'recording_unavailable')
+            return null;
+        const raw = parseComputerJson(response);
+        if (!raw || typeof raw.url !== 'string' || !/^https:\/\//i.test(raw.url) || /[\x00-\x20\x7f]/.test(raw.url))
+            throw invalidResponse();
+        let url;
+        try {
+            url = new URL(raw.url);
+        }
+        catch {
+            throw invalidResponse();
+        }
+        if (url.protocol !== 'https:' || url.username || url.password || url.hash || (raw.duration_seconds != null && (typeof raw.duration_seconds !== 'number' || !Number.isFinite(raw.duration_seconds) || raw.duration_seconds < 0)))
+            throw invalidResponse();
+        const startedAt = raw.started_at == null ? undefined : parseTimestamp(raw.started_at);
+        return { url: raw.url, ...(raw.duration_seconds != null ? { durationSeconds: raw.duration_seconds } : {}), ...(startedAt ? { startedAt } : {}) };
+    }
     instruction() {
         return this.unavailable('instruction');
     }
@@ -72,7 +158,38 @@ export class ComputerSession {
     }
     async screenshot(options = {}) {
         this.assertOpen();
-        const response = await this.request('GET', '/screen/screenshot', undefined, this.lifetime.signal);
+        const signal = this.observationSignal(30_000);
+        let retrySignal = signal;
+        let response;
+        let transient = false;
+        let backoffMs = 500;
+        const notReady = () => new VerifyError('SESSION_BUSY', `The computer desktop is not ready for screenshots after its 30-second startup window. Try again later. See ${this.viewerUrl}`);
+        try {
+            for (;;) {
+                this.assertOpen();
+                response = await this.request('GET', '/screen/screenshot', undefined, retrySignal);
+                if (response.status >= 200 && response.status < 300)
+                    break;
+                const remainingMs = this.screenReadyUntilMs - Date.now();
+                if (remainingMs <= 0)
+                    throw notReady();
+                if (!transient)
+                    retrySignal = AbortSignal.any([signal, AbortSignal.timeout(remainingMs)]);
+                transient = true;
+                await delay(Math.min(backoffMs, remainingMs), undefined, { signal: retrySignal });
+                if (Date.now() >= this.screenReadyUntilMs)
+                    throw notReady();
+                backoffMs = Math.min(backoffMs * 2, 2_000);
+            }
+        }
+        catch (error) {
+            if (transient && !this.lifetime.signal.aborted && (this.expiresAtMs === undefined || Date.now() < this.expiresAtMs) && retrySignal.aborted && Date.now() >= this.screenReadyUntilMs)
+                throw notReady();
+            if (retrySignal.aborted)
+                throw new VerifyError('TIMEOUT', `Computer screenshot observation was cancelled or exceeded its deadline. See ${this.viewerUrl}`);
+            throw error;
+        }
+        this.assertOpen();
         const raw = parseComputerJson(response);
         const bytes = decodeBytes(raw?.png, 128 * MAX_OUTPUT_BYTES);
         const size = pngSize(bytes);
@@ -140,19 +257,35 @@ 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') {
-                    const message = `${error.message} A possible cause is that no Mac computer could be assigned. ${MAC_AVAILABILITY}`;
+                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 });
                 }
@@ -172,10 +305,21 @@ export class ComputerSession {
         this.assertOpen();
         const requestId = randomUUID();
         const operationId = computerOperationId(this.id, requestId);
-        const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(310_000)]);
+        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;
                 if (response.status !== 202) {
                     const body = parseComputerJson(response);
                     if (body?.computer_session_id !== this.id || body.operation_id !== operationId || !['recorded', 'pending', 'failed'].includes(body.evidence) || !body.execution)
@@ -224,7 +368,7 @@ export class ComputerSession {
         const path = `/api/v1/computer-runs${suffix === '' ? '' : `/${this.id}${suffix}`}`;
         let response;
         try {
-            response = await this.client.send(method, path, { body, signal, timeoutMs: suffix === '/stop' || suffix.startsWith('/operations') ? 310_000 : 30_000, retry: method === 'GET', headers: suffix === '/operations' ? { Prefer: 'respond-async' } : undefined });
+            response = await this.client.send(method, path, { body, signal, timeoutMs: suffix === '/stop' || suffix.startsWith('/operations') ? 310_000 : 30_000, retry: method === 'GET' && suffix !== '/screen/screenshot', headers: suffix === '/operations' ? { Prefer: 'respond-async' } : undefined });
         }
         catch (error) {
             if (method === 'POST' || suffix.startsWith('/operations/'))
@@ -235,12 +379,32 @@ export class ComputerSession {
         }
         if (response.status >= 200 && response.status < 300)
             return response;
-        const detail = responseDetail(response);
-        if (detail === 'computer_not_enabled' || (method === 'POST' && suffix === '' && response.status === 503 && detail === 'runtime_unavailable')) {
-            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `Revyl refused the computer request (${detail}). ${MAC_AVAILABILITY}. Ask support@revyl.ai about staging organization enablement. See ${this.viewerUrl}`);
+        const blocked = edgeBlockedError(response);
+        if (blocked)
+            throw blocked;
+        if (suffix === '/recording' && response.status === 404 && responseErrorCode(response) === 'recording_unavailable')
+            return response;
+        const detail = responseRefusalReason(response) ?? responseDetail(response);
+        const refusal = { reason: responseRefusalReason(response), httpStatus: response.status };
+        if (suffix === '/screen/screenshot') {
+            let raw = null;
+            try {
+                raw = JSON.parse(new TextDecoder().decode(response.body));
+            }
+            catch { }
+            const code = raw?.detail ?? raw?.message ?? raw?.error;
+            if ((code === 'screen_unavailable' && (response.status === 409 || response.status === 503)) || (code === 'screen_starting' && response.status === 409))
+                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} See ${this.viewerUrl}`, refusal);
+        }
+        if (response.status === 429 && detail === 'computer_limit')
+            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';
@@ -248,9 +412,7 @@ 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 === 'runtime_unavailable' || detail === 'start_failed' || detail === 'computer_limit')
+        else if (detail === 'start_failed')
             code = 'SESSION_START_FAILED';
         else if (response.status === 409 || detail === 'operation_limit')
             code = 'SESSION_BUSY';
@@ -259,20 +421,26 @@ 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();
+        if (report.expires_at != null)
+            this.expiresAtMs = parseTimestamp(report.expires_at).getTime();
         return report;
     }
     assertOpen() {
-        if (this.closed)
-            throw new VerifyError('SESSION_ENDED', `The ${this.target} computer was closed.`);
+        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) {
+        const remainingMs = this.expiresAtMs === undefined ? timeoutMs : Math.min(timeoutMs, this.expiresAtMs - Date.now());
+        return AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(Math.max(0, remainingMs))]);
     }
     unavailable(method) {
-        return Promise.reject(new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `${method}() is not available on mac computers; use exec() and file operations. See ${this.viewerUrl}`));
+        return Promise.reject(new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `${method}() is not available on computers; use exec() and file operations. See ${this.viewerUrl}`));
     }
     log(line) {
         this.options.log?.(`${this.target}: ${line}`);
@@ -291,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.');
@@ -312,6 +483,14 @@ function decodeBytes(value, maxBytes) {
 function invalidResponse() {
     return new VerifyError('API_ERROR', 'Revyl returned an invalid computer response.');
 }
+function parseTimestamp(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) || !Number.isFinite(Date.parse(value)))
+        throw invalidResponse();
+    const calendarTime = new Date(`${value.slice(0, 19)}Z`);
+    if (!Number.isFinite(calendarTime.getTime()) || calendarTime.toISOString().slice(0, 19) !== value.slice(0, 19))
+        throw invalidResponse();
+    return new Date(value);
+}
 function parseComputerJson(response) {
     try {
         return JSON.parse(new TextDecoder().decode(response.body));

package/dist/config.d.ts

@@ -46,12 +46,18 @@ export interface MobileTargetConfig {
     startTimeout?: number;
     idleTimeoutSeconds?: number;
 }
-/** A Revyl computer: a cloud macOS machine that runs commands and files instead of agent steps. See docs/computers.md. */
+/** A Revyl computer that runs commands and files instead of agent steps. See docs/computers.md. */
 export interface ComputerTargetConfig {
     platform: ComputerPlatform;
     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 {};

package/dist/config.js

@@ -71,7 +71,14 @@ export function validateTarget(raw) {
     const platform = asRecord(raw, 'target', fail).platform;
     return parseTarget(raw, typeof platform === 'string' ? platform : 'target', 'target', fail);
 }
-function parseTarget(raw, name, path, fail) {
+export function validateHostedTarget(raw) {
+    const fail = (path, problem) => { throw new VerifyError('INVALID_ARGUMENT', `computer.open(): ${path} ${problem}`); };
+    const target = parseTarget(raw, raw?.platform ?? 'target', 'target', fail, true);
+    if (target.platform === 'mac' || target.platform === 'linux')
+        fail('target.platform', 'must be web, ios, or android.');
+    return target;
+}
+function parseTarget(raw, name, path, fail, hosted = false) {
     const target = asRecord(raw, path, fail);
     const platform = target.platform;
     if (typeof platform !== 'string' || !PLATFORMS.includes(platform)) {
@@ -88,6 +95,13 @@ function parseTarget(raw, name, path, fail) {
         idleTimeoutSeconds: integer(target.idleTimeoutSeconds, `${path}.idleTimeoutSeconds`, 60, 3_600, 600, fail),
     };
     const app = asRecord(target.app, `${path}.app`, fail);
+    if (hosted) {
+        uuid(app.appId, `${path}.app.appId`, true, fail);
+        uuid(app.buildId, `${path}.app.buildId`, true, fail);
+        rejectUnknownKeys(app, ['appId', 'buildId'], `${path}.app`, fail);
+        if (target.device !== undefined)
+            fail(`${path}.device`, 'is fixed by the hosting computer.');
+    }
     if (platform === 'web') {
         rejectUnknownKeys(target, ['platform', 'app', 'viewport', 'signIn', 'startTimeout', 'idleTimeoutSeconds'], path, fail);
         rejectUnknownKeys(app, ['appId', 'url', 'buildId', 'branch'], `${path}.app`, fail);
@@ -153,7 +167,7 @@ function parseTarget(raw, name, path, fail) {
         fail(`${path}.app.artifactUrl`, 'must be an HTTPS URL.');
     }
     const sources = [app.appId, app.buildId, app.artifactUrl, app.bundleId].filter((value) => value !== undefined).length;
-    if (sources !== 1) {
+    if (!hosted && sources !== 1) {
         fail(`${path}.app`, 'takes exactly one of appId, buildId, or artifactUrl to install an app, or bundleId to open one already on the device.');
     }
     let device;

package/dist/errors.d.ts

@@ -1,8 +1,13 @@
-export type VerifyErrorCode = 'INVALID_ARGUMENT' | 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'AUTH_MISSING' | 'AUTH_REJECTED' | 'API_ERROR' | 'SESSION_START_FAILED' | 'SESSION_ENDED' | 'SESSION_BUSY' | 'NOT_AVAILABLE_ON_PLATFORM' | 'ACTION_FAILED' | 'ACTION_UNCERTAIN' | 'INSTRUCTION_FAILED' | 'VALIDATION_FAILED' | 'STEP_FAILED' | 'COMMAND_FAILED' | 'NOT_FOUND' | 'ACCESS_DENIED' | 'TIMEOUT';
+export type VerifyErrorCode = 'INVALID_ARGUMENT' | 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'AUTH_MISSING' | 'COMPUTER_ID_MISSING' | 'AUTH_REJECTED' | 'EDGE_BLOCKED' | 'API_ERROR' | 'SESSION_START_FAILED' | 'SESSION_ENDED' | 'SESSION_BUSY' | 'COMPUTER_LIMIT' | 'NOT_AVAILABLE_ON_PLATFORM' | 'ACTION_FAILED' | 'ACTION_UNCERTAIN' | 'INSTRUCTION_FAILED' | 'VALIDATION_FAILED' | 'STEP_FAILED' | 'COMMAND_FAILED' | 'NOT_FOUND' | 'ACCESS_DENIED' | 'TIMEOUT';
+export type RefusalReason = 'web_runtime_unavailable' | 'web_runtime_not_configured' | 'computer_limit' | 'runtime_unavailable' | 'computer_runtime_unavailable' | 'computer_at_capacity' | 'computer_not_running' | 'computer_cannot_host_platform' | 'computer_not_found' | 'web_build_required' | 'web_build_not_supported' | 'ios_build_required' | 'ios_build_not_supported' | 'android_build_required' | 'android_build_not_supported' | 'web_session_conflict' | 'ios_session_conflict' | 'android_session_conflict' | 'not_available_on_platform' | 'request_timeout' | 'protocol_error';
 export declare class VerifyError extends Error {
     readonly code: VerifyErrorCode;
+    readonly reason?: RefusalReason;
+    readonly httpStatus?: number;
     constructor(code: VerifyErrorCode, message: string, options?: {
         cause?: unknown;
+        reason?: RefusalReason;
+        httpStatus?: number;
     });
 }
 export declare function isVerifyError(error: unknown): error is VerifyError;

package/dist/errors.js

@@ -1,9 +1,13 @@
 export class VerifyError extends Error {
     code;
+    reason;
+    httpStatus;
     constructor(code, message, options) {
         super(message, options);
         this.name = 'VerifyError';
         this.code = code;
+        this.reason = options?.reason;
+        this.httpStatus = options?.httpStatus;
     }
 }
 export function isVerifyError(error) {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { open } from './open.js';
-export type { OpenOptions } from './open.js';
-export type { Session, StepOptions, StepResult, StepType, ValidationOptions, OperationOptions, ExecOptions, ExecResult, FileStat, ComputerProcess } from './session.js';
+export { attach, currentComputer, open } from './open.js';
+export type { AttachOptions, OpenOptions } from './open.js';
+export type { OpenedSession, Session, StepOptions, StepResult, StepType, ValidationOptions, OperationOptions, ExecOptions, ExecResult, FileStat, ComputerProcess, ComputerRecording } from './session.js';
 export { defineConfig } from './config.js';
-export type { MobileAppConfig, MobileTargetConfig, ComputerTargetConfig, TargetConfig, VerifyConfig, WebAppConfig, WebTargetConfig } from './config.js';
+export type { HostedTargetConfig, MobileAppConfig, MobileTargetConfig, ComputerTargetConfig, TargetConfig, VerifyConfig, WebAppConfig, WebTargetConfig } from './config.js';
 export type { Platform, ComputerPlatform, MobilePlatform } from './api/types.js';
 export { VerifyError, isVerifyError } from './errors.js';
-export type { VerifyErrorCode } from './errors.js';
+export type { RefusalReason, VerifyErrorCode } from './errors.js';

package/dist/index.js

@@ -1,3 +1,3 @@
-export { open } from './open.js';
+export { attach, currentComputer, open } from './open.js';
 export { defineConfig } from './config.js';
 export { VerifyError, isVerifyError } from './errors.js';

package/dist/open.d.ts

@@ -1,13 +1,21 @@
 import { type TargetConfig } from './config.js';
-import { type Session } from './session.js';
+import { type OpenedSession } from './session.js';
+import { ComputerSession } from './computer-session.js';
 export interface OpenOptions {
     /** The config file to read target names from. Defaults to the nearest verify.config.ts at or above the current folder. */
     config?: string;
     /** Where progress lines go: the session link and each step's outcome. Defaults to stderr; false turns them off. */
     log?: false | ((line: string) => void);
+    backendUrl?: string;
+    appUrl?: string;
 }
+export interface AttachOptions extends Pick<OpenOptions, 'log' | 'backendUrl' | 'appUrl'> {
+    stopOnClose?: boolean;
+}
+export declare function attach(computerId: string, options?: AttachOptions): Promise<ComputerSession>;
+export declare function currentComputer(options?: AttachOptions): Promise<ComputerSession>;
 /**
- * Starts a Revyl cloud browser, device, or Mac computer and resolves once it is ready.
+ * Starts a Revyl cloud browser, device, or computer. Mobile first-screen readiness is best-effort.
  * Pass a target name from verify.config.ts, such as open('web'), or a target object.
  */
-export declare function open(target: string | TargetConfig, options?: OpenOptions): Promise<Session>;
+export declare function open(target: string | TargetConfig, options?: OpenOptions): Promise<OpenedSession>;

package/dist/open.js

@@ -1,11 +1,42 @@
 import { RevylClient } from './api/client.js';
 import { missingCredentialsMessage, resolveCredentials } from './auth.js';
+import { signIn } from './cli/login.js';
 import { DEFAULT_STEP_TIMEOUT_MS, loadConfig, validateTarget } from './config.js';
 import { VerifyError } from './errors.js';
 import { DeviceSession } from './session.js';
 import { ComputerSession } from './computer-session.js';
+const signIns = new Map();
+async function credentialsForUse(options) {
+    const credentials = await resolveCredentials();
+    if (credentials)
+        return credentials;
+    if (!process.stdin.isTTY || !process.stderr.isTTY || process.env.CI)
+        throw new VerifyError('AUTH_MISSING', missingCredentialsMessage());
+    const key = JSON.stringify([options.backendUrl, options.appUrl]);
+    let pending = signIns.get(key);
+    if (!pending) {
+        pending = signIn(options).finally(() => signIns.delete(key));
+        signIns.set(key, pending);
+    }
+    return pending;
+}
+export async function attach(computerId, options = {}) {
+    if (typeof computerId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(computerId))
+        throw new VerifyError('INVALID_ARGUMENT', 'attach() requires a computer session UUID.');
+    if (options.stopOnClose !== undefined && typeof options.stopOnClose !== 'boolean')
+        throw new VerifyError('INVALID_ARGUMENT', 'stopOnClose must be a boolean.');
+    const credentials = await credentialsForUse(options);
+    const log = options.log === false ? undefined : (options.log ?? ((line) => void process.stderr.write(`[verify] ${line}\n`)));
+    return ComputerSession.attach(new RevylClient({ token: credentials.token, backendUrl: options.backendUrl }), computerId, { stepTimeout: DEFAULT_STEP_TIMEOUT_MS, log, appUrl: options.appUrl, stopOnClose: options.stopOnClose });
+}
+export async function currentComputer(options = {}) {
+    const computerId = process.env.REVYL_COMPUTER_ID?.trim();
+    if (!computerId)
+        throw new VerifyError('COMPUTER_ID_MISSING', 'No current Revyl computer is available. Run this job on a revyl-macos runner.');
+    return attach(computerId, { ...options, stopOnClose: options.stopOnClose === undefined ? false : options.stopOnClose });
+}
 /**
- * Starts a Revyl cloud browser, device, or Mac computer and resolves once it is ready.
+ * Starts a Revyl cloud browser, device, or computer. Mobile first-screen readiness is best-effort.
  * Pass a target name from verify.config.ts, such as open('web'), or a target object.
  */
 export async function open(target, options = {}) {
@@ -22,15 +53,10 @@ export async function open(target, options = {}) {
     else {
         resolved = validateTarget(target);
     }
-    if (resolved.platform === 'linux') {
-        throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'Linux computers are planned, but are not available in Verify yet. See docs/computers.md.');
-    }
-    const credentials = await resolveCredentials();
-    if (!credentials)
-        throw new VerifyError('AUTH_MISSING', missingCredentialsMessage());
+    const credentials = await credentialsForUse(options);
     const log = options.log === false ? undefined : (options.log ?? ((line) => void process.stderr.write(`[verify] ${line}\n`)));
-    const client = new RevylClient({ token: credentials.token });
-    if (resolved.platform === 'mac')
-        return ComputerSession.start(client, resolved, { stepTimeout, log });
-    return DeviceSession.start(client, resolved, { stepTimeout, log });
+    const client = new RevylClient({ token: credentials.token, backendUrl: options.backendUrl });
+    if (resolved.platform === 'mac' || resolved.platform === 'linux')
+        return ComputerSession.start(client, resolved, { stepTimeout, log, appUrl: options.appUrl });
+    return DeviceSession.start(client, resolved, { stepTimeout, log, appUrl: options.appUrl });
 }

package/dist/screen-readiness.d.ts

@@ -0,0 +1 @@
+export declare function screenHasContent(bytes: Uint8Array): boolean | undefined;

package/dist/screen-readiness.js

@@ -0,0 +1,27 @@
+import { PNG } from 'pngjs';
+export function screenHasContent(bytes) {
+    if (bytes.length < 24 || bytes.length > 16 * 1024 * 1024)
+        return undefined;
+    const header = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const width = header.readUInt32BE(16);
+    const height = header.readUInt32BE(20);
+    if (width === 0 || height === 0 || width * height > 16_000_000)
+        return undefined;
+    try {
+        const { data } = PNG.sync.read(header);
+        const left = Math.floor(width / 10);
+        const top = Math.floor(height / 10);
+        const first = (top * width + left) * 4;
+        for (let y = top; y < Math.ceil(height * 0.9); y += 1) {
+            for (let x = left; x < Math.ceil(width * 0.9); x += 1) {
+                const offset = (y * width + x) * 4;
+                if (data[offset] !== data[first] || data[offset + 1] !== data[first + 1] || data[offset + 2] !== data[first + 2])
+                    return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return undefined;
+    }
+}