@revyl/verify 0.2.0 → 0.3.1

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' | '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 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, ComputerRecording } 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 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,9 +1,40 @@
 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 computer. Mobile first-screen readiness is best-effort.
  * Pass a target name from verify.config.ts, such as open('web'), or a target object.
@@ -22,12 +53,10 @@ export async function open(target, options = {}) {
     else {
         resolved = validateTarget(target);
     }
-    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 });
+    const client = new RevylClient({ token: credentials.token, backendUrl: options.backendUrl });
     if (resolved.platform === 'mac' || resolved.platform === 'linux')
-        return ComputerSession.start(client, resolved, { stepTimeout, log });
-    return DeviceSession.start(client, resolved, { stepTimeout, log });
+        return ComputerSession.start(client, resolved, { stepTimeout, log, appUrl: options.appUrl });
+    return DeviceSession.start(client, resolved, { stepTimeout, log, appUrl: options.appUrl });
 }

package/dist/session.d.ts

@@ -1,6 +1,6 @@
 import { RevylClient } from './api/client.js';
 import type { LiveStepType, Platform } from './api/types.js';
-import type { ResolvedDeviceTarget } from './config.js';
+import type { HostedTargetConfig, ResolvedDeviceTarget } from './config.js';
 export type StepType = LiveStepType;
 /** The outcome of one instruction or validation, as Revyl's agent reported it. */
 export interface StepResult {
@@ -91,9 +91,21 @@ export interface Session {
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }
+export interface OpenedSession extends Session {
+    report(): Promise<Record<string, unknown>>;
+    navigate(url: string): Promise<void>;
+    open(target: HostedTargetConfig): Promise<OpenedSession>;
+}
 export interface SessionOptions {
     stepTimeout: number;
     log: ((line: string) => void) | undefined;
+    appUrl?: string;
+}
+export interface HostingParent {
+    id: string;
+    signal: AbortSignal;
+    expiresAt?: Date;
+    register(session: Session): void;
 }
 /** A Revyl cloud browser or iOS or Android device. */
 export declare class DeviceSession implements Session {
@@ -111,8 +123,12 @@ export declare class DeviceSession implements Session {
     private workflowRunId;
     private closePromise;
     private stepRunning;
+    private parent?;
+    private readySignal?;
+    get expiresAt(): Date | undefined;
     private constructor();
-    static start(client: RevylClient, target: ResolvedDeviceTarget, options: SessionOptions): Promise<DeviceSession>;
+    static start(client: RevylClient, target: ResolvedDeviceTarget, options: SessionOptions, parent?: HostingParent): Promise<DeviceSession>;
+    private static startHosted;
     get closed(): boolean;
     /** Asks Revyl's agent to do something on the app, such as "add the first product to the cart". Throws INSTRUCTION_FAILED when it cannot. */
     instruction(text: string, options?: StepOptions): Promise<StepResult>;
@@ -125,7 +141,10 @@ export declare class DeviceSession implements Session {
     screenshot(options?: {
         path?: string;
     }): Promise<Uint8Array>;
+    report(): Promise<Record<string, unknown>>;
+    navigate(url: string): Promise<void>;
     exec(): Promise<ExecResult>;
+    open(): Promise<never>;
     recording(): Promise<never>;
     readFile(): Promise<Buffer>;
     writeFile(): Promise<void>;

package/dist/session.js

@@ -2,7 +2,7 @@ import { 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 { apiError, parseJson, responseDetail, responseErrorCode, sessionViewerUrl, } from './api/client.js';
+import { apiError, edgeBlockedError, parseJson, responseDetail, responseErrorCode, responseRefusalReason, sessionViewerUrl, } from './api/client.js';
 import { trackSession, untrackSession } from './cleanup.js';
 import { VerifyError, errorMessage, isVerifyError } from './errors.js';
 import { screenHasContent } from './screen-readiness.js';
@@ -32,6 +32,11 @@ export class DeviceSession {
     workflowRunId;
     closePromise;
     stepRunning = false;
+    parent;
+    readySignal;
+    get expiresAt() {
+        return this.parent?.expiresAt;
+    }
     constructor(client, target, id, workflowRunId, options) {
         this.client = client;
         this.options = options;
@@ -39,10 +44,12 @@ export class DeviceSession {
         this.target = target.name;
         this.id = id;
         this.workflowRunId = workflowRunId;
-        this.viewerUrl = sessionViewerUrl(id);
+        this.viewerUrl = sessionViewerUrl(id, undefined, options.appUrl);
     }
-    static async start(client, target, options) {
-        const deadline = Date.now() + target.startTimeout;
+    static async start(client, target, options, parent) {
+        const deadline = Math.min(Date.now() + target.startTimeout, parent?.expiresAt?.getTime() ?? Infinity);
+        if (parent)
+            return DeviceSession.startHosted(client, target, options, parent, deadline);
         if (target.platform === 'web') {
             const buildId = await resolveWebBuildId(client, target);
             const sessionId = randomUUID();
@@ -99,6 +106,73 @@ export class DeviceSession {
         });
         return session;
     }
+    static async startHosted(client, target, options, parent, deadline) {
+        const id = randomUUID();
+        const session = new DeviceSession(client, target, id, '', options);
+        session.parent = parent;
+        session.readySignal = AbortSignal.any([parent.signal, AbortSignal.timeout(Math.max(0, deadline - Date.now()))]);
+        const request = {
+            platform: target.platform,
+            session_id: id,
+            computer_session_id: parent.id,
+            app_id: target.app.appId,
+            build_id: target.app.buildId,
+            idle_timeout_seconds: target.idleTimeoutSeconds,
+            ...(target.platform === 'web' ? { web: {
+                    ...(target.viewport ? { viewport: { width: target.viewport.width, height: target.viewport.height, device_scale_factor: target.viewport.deviceScaleFactor } } : {}),
+                    ...(target.signIn ? { sign_in: { path: target.signIn.path, secret_name: target.signIn.secret, persona: target.signIn.persona } } : {}),
+                } } : { is_simulation: true }),
+        };
+        let submitted = false;
+        let refused = false;
+        try {
+            session.readySignal.throwIfAborted();
+            submitted = true;
+            const response = await client.send('POST', '/api/v1/execution/start_device', { body: request, retry: false, signal: session.readySignal, timeoutMs: 120_000 });
+            if (response.status < 200 || response.status >= 300) {
+                const reason = responseRefusalReason(response);
+                refused = [400, 401, 403, 404, 405, 409, 422, 429].includes(response.status) || (response.status === 503 && reason !== undefined && reason !== 'request_timeout' && reason !== 'protocol_error');
+                const blocked = edgeBlockedError(response);
+                if (blocked)
+                    throw blocked;
+                const code = response.status === 401 || response.status === 403 ? 'AUTH_REJECTED'
+                    : reason === 'computer_not_found' || response.status === 404 ? 'NOT_FOUND'
+                        : reason === 'computer_not_running' ? 'SESSION_ENDED'
+                            : reason === 'computer_cannot_host_platform' || reason === 'computer_runtime_unavailable' || reason === 'web_runtime_unavailable' || reason === 'web_runtime_not_configured' || reason === 'runtime_unavailable' || reason === 'not_available_on_platform' ? 'NOT_AVAILABLE_ON_PLATFORM'
+                                : reason === 'computer_at_capacity' || reason === 'computer_limit' ? 'COMPUTER_LIMIT'
+                                    : response.status === 422 || response.status === 400 ? 'INVALID_ARGUMENT'
+                                        : response.status === 409 ? 'SESSION_BUSY'
+                                            : response.status === 408 || response.status >= 500 ? 'ACTION_UNCERTAIN' : 'API_ERROR';
+                throw new VerifyError(code, `Revyl refused the hosted session start (${reason ?? `HTTP ${response.status}`}).`, { reason, httpStatus: response.status });
+            }
+            const start = parseJson(response, 'hosted session start');
+            if (!start || typeof start !== 'object' || Array.isArray(start))
+                throw new VerifyError('API_ERROR', 'Revyl returned an invalid hosted session response.');
+            if (start.session_id !== id || typeof start.workflow_run_id !== 'string' || !/^[A-Za-z0-9_-]{1,255}$/.test(start.workflow_run_id) || (start.platform !== undefined && start.platform !== target.platform))
+                throw new VerifyError('SESSION_START_FAILED', 'Revyl did not acknowledge the hosted session identity.');
+            session.workflowRunId = start.workflow_run_id;
+            parent.register(session);
+            await session.untilReady(async () => {
+                if (target.platform === 'web')
+                    await session.waitForWebReady(deadline);
+                else {
+                    await session.waitForDeviceReady(deadline);
+                    await session.waitForScreenContent(deadline);
+                }
+            });
+            session.readySignal.throwIfAborted();
+            return session;
+        }
+        catch (error) {
+            if (submitted && !refused) {
+                parent.register(session);
+                await session.close().catch(() => undefined);
+            }
+            if (session.readySignal.aborted)
+                throw new VerifyError('TIMEOUT', `Hosted startup was cancelled or exceeded its deadline. See ${session.viewerUrl}`, { cause: error });
+            throw error;
+        }
+    }
     get closed() {
         return this.closePromise !== undefined;
     }
@@ -133,9 +207,41 @@ export class DeviceSession {
         }
         return response.body;
     }
+    async report() {
+        if (!this.id)
+            throw new VerifyError('NOT_FOUND', 'Cannot report a session without a known session ID.');
+        const report = await this.client.getDeviceSession(this.id);
+        if (!report || typeof report !== 'object' || Array.isArray(report))
+            throw new VerifyError('API_ERROR', 'Revyl returned an invalid session report.');
+        return report;
+    }
+    async navigate(url) {
+        if (this.platform !== 'web')
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'navigate() is available only on web sessions.');
+        if (typeof url !== 'string' || url.length > 2048 || /[\x00-\x20\x7f-\x9f\s\\]/.test(url))
+            throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires an http(s) URL without credentials, whitespace, or backslashes.');
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires a valid http(s) URL.');
+        }
+        if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password)
+            throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires an http(s) URL without credentials.');
+        const response = await this.worker('POST', 'open_url', { body: { url }, retry: false });
+        const result = parseJson(response, 'open_url');
+        if (!result || typeof result !== 'object' || typeof result.success !== 'boolean' || (result.action !== undefined && result.action !== 'navigate') || (result.status_code !== undefined && (!Number.isInteger(result.status_code) || result.status_code < 100 || result.status_code > 599)))
+            throw new VerifyError('API_ERROR', 'Revyl returned an invalid navigation response.');
+        if (!result.success)
+            throw new VerifyError('ACTION_FAILED', `Revyl did not confirm navigation. See ${this.viewerUrl}`);
+    }
     exec() {
         return this.computerOnly('exec');
     }
+    open() {
+        return this.computerOnly('open');
+    }
     recording() {
         return this.computerOnly('recording');
     }
@@ -159,7 +265,7 @@ export class DeviceSession {
         this.closePromise ??= (async () => {
             try {
                 if (this.id)
-                    await this.client.stopDeviceSession(this.id);
+                    await this.client.stopDeviceSession(this.id, this.parent === undefined);
                 else
                     await this.client.cancelDevice(this.workflowRunId);
                 this.log('closed');
@@ -271,7 +377,7 @@ export class DeviceSession {
         while (Date.now() < deadline) {
             try {
                 const response = await this.client.worker(this.workflowRunId, 'screenshot', {
-                    method: 'GET', retry: false, signal: AbortSignal.timeout(Math.max(1, deadline - Date.now())),
+                    method: 'GET', retry: false, signal: AbortSignal.any([AbortSignal.timeout(Math.max(1, deadline - Date.now())), ...(this.readySignal ? [this.readySignal] : [])]),
                 });
                 if (response.status === 200) {
                     const content = screenHasContent(response.body);
@@ -300,11 +406,24 @@ export class DeviceSession {
         return Promise.reject(new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `${call}() runs on computer targets (platform 'mac' or 'linux'), not on ${this.platform} sessions.`));
     }
     async worker(method, action, options) {
-        if (this.closePromise)
-            throw new VerifyError('SESSION_ENDED', `The ${this.target} session was closed.`);
-        const response = await this.client.worker(this.workflowRunId, action, { method, ...options });
+        if (this.closePromise || this.parent?.signal.aborted || (this.parent?.expiresAt && Date.now() >= this.parent.expiresAt.getTime()))
+            throw new VerifyError('SESSION_ENDED', `The ${this.target} session was closed or its parent expired.`);
+        const signal = this.parent ? AbortSignal.any([
+            this.parent.signal,
+            ...(this.parent.expiresAt ? [AbortSignal.timeout(Math.max(0, this.parent.expiresAt.getTime() - Date.now()))] : []),
+            ...(options.signal ? [options.signal] : []),
+        ]) : options.signal;
+        const response = await this.client.worker(this.workflowRunId, action, { method, ...options, signal });
         if (response.status >= 200 && response.status < 300)
             return response;
+        if (action === 'open_url') {
+            const error = this.workerError(method, action, response);
+            const reason = responseRefusalReason(response);
+            const message = error.code === 'ACTION_UNCERTAIN' && reason === 'request_timeout'
+                ? `Web navigation did not confirm within the action budget and may still complete. The session is still open; Verify did not replay the request. See ${this.viewerUrl}`
+                : `Web navigation failed (HTTP ${response.status}). See ${this.viewerUrl}`;
+            throw new VerifyError(error.code, message, { reason, httpStatus: response.status });
+        }
         throw this.workerError(method, action, response);
     }
     workerError(method, action, response) {
@@ -348,13 +467,14 @@ export class DeviceSession {
     }
     async waitForWebReady(deadline) {
         for (;;) {
-            const detail = await this.client.getDeviceSession(this.id);
+            this.readySignal?.throwIfAborted();
+            const detail = await this.client.getDeviceSession(this.id, this.readySignal);
             if (ENDED_STATUSES.has(detail.status)) {
                 throw new VerifyError('SESSION_START_FAILED', `The ${this.target} web session ended before it was ready (${detail.status}): ${detail.error_message ?? 'no reason given'}. See ${this.viewerUrl}`);
             }
             if (detail.status === 'running' && detail.workflow_run_id) {
                 this.workflowRunId = detail.workflow_run_id;
-                const response = await this.client.worker(this.workflowRunId, 'screenshot', { method: 'GET' });
+                const response = await this.client.worker(this.workflowRunId, 'screenshot', { method: 'GET', signal: this.readySignal });
                 if (response.status === 200 && pngSize(response.body))
                     return;
                 if (response.status !== 503 && response.status !== 409 && responseErrorCode(response) !== 'not_ready') {
@@ -366,7 +486,8 @@ export class DeviceSession {
     }
     async waitForDeviceReady(deadline) {
         for (;;) {
-            const connection = await this.client.getWorkerConnection(this.workflowRunId);
+            this.readySignal?.throwIfAborted();
+            const connection = await this.client.getWorkerConnection(this.workflowRunId, this.readySignal);
             if (connection.status === 'ready' && connection.worker_ws_url)
                 break;
             if (connection.status === 'cancelled' || connection.status === 'stopped' || connection.status === 'failed') {
@@ -376,7 +497,7 @@ export class DeviceSession {
         }
         const connectDeadline = Math.min(deadline, Date.now() + DEVICE_CONNECT_TIMEOUT_MS);
         for (;;) {
-            const response = await this.client.worker(this.workflowRunId, 'health', { method: 'GET', retry: true });
+            const response = await this.client.worker(this.workflowRunId, 'health', { method: 'GET', retry: true, signal: this.readySignal });
             if (response.status === 200 && parseJson(response, 'health').device_connected)
                 return;
             if (response.status !== 200 && response.status !== 503)

package/docs/README.md

@@ -11,7 +11,6 @@ These files ship inside the npm package at `node_modules/@revyl/verify/docs/`, s
 | [web.md](web.md) | Open a web app in a Revyl cloud browser |
 | [mobile.md](mobile.md) | Open an iOS or Android app on a Revyl cloud device |
 | [computers.md](computers.md) | Open a Mac or Linux computer for commands, files, processes, screenshots, and optional recording metadata |
-| [linux-computers-contract.md](linux-computers-contract.md) | Read the implemented shared Linux computer contract |
 | [ci.md](ci.md) | Call Verify from CI or from a test runner you already use |
 | [errors.md](errors.md) | Understand an error code and fix it |
 | [agents.md](agents.md) | Use Verify as a coding agent |

package/docs/agents.md

@@ -24,9 +24,9 @@ This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that
 
 ## Rules
 
-Mac and Linux computers are early access and not yet available in Revyl production. They work only on Revyl staging for organizations enabled for the requested OS through the optional `REVYL_BACKEND_URL` override with matching staging credentials. Read [availability and errors](computers.md#availability-and-errors) before starting a computer; do not try production or repeat an uncertain start/stop to probe availability.
+Mac and Linux computers are early access. Ask support@revyl.ai about access before starting a computer; do not repeat an uncertain start/stop to probe availability.
 
-For computer work, use structured `exec(['program', 'arg'])`, `readFile`, `writeFile`, `stat`, and run-owned handles from `processes()`/`terminate(id)`. Check command output with ordinary assertions and close in `finally`; screenshots are supported, but instruction/validation are not. Do not fall back to agent steps on computers or shell/file methods on mobile/web. See [computers.md](computers.md) for limits and staging setup. Linux uses inline targets or config entries; Linux init is intentionally unavailable. Starting a computer is a paid external action and needs the same approval as starting a device.
+For computer work, use structured `exec(['program', 'arg'])`, `readFile`, `writeFile`, `stat`, and run-owned handles from `processes()`/`terminate(id)`. Check command output with ordinary assertions and close in `finally`; screenshots are supported, but instruction/validation are not. Do not fall back to agent steps on computers or shell/file methods on mobile/web. See [computers.md](computers.md) for limits. Linux uses inline targets or config entries; Linux init is intentionally unavailable. Starting a computer is a paid external action and needs the same approval as starting a device.
 
 Computers have a hard 60-minute lifetime from create, not from readiness or activity. `expiresAt` is optional on older APIs; expiry does not prevent close. After terminal state and confirmed release, `recording()` can return private signed metadata or null, including after close. Never log or share its signed URL/query. Do not automatically wait for recordings or retry `COMPUTER_LIMIT` starts: queued work (including iOS) or the concurrency limit may be responsible.
 

package/docs/api.md

@@ -1,7 +1,7 @@
 # API
 
 ```ts
-import { open, defineConfig, VerifyError, isVerifyError } from '@revyl/verify';
+import { attach, open, defineConfig, VerifyError, isVerifyError } from '@revyl/verify';
 ```
 
 ## open(target, options?)
@@ -10,7 +10,7 @@ Linux targets are supported **since 0.2.0**; 0.1.0 includes the target type but
 
 Starts a Revyl cloud browser, device, or Mac or Linux computer. Mobile first-screen readiness is [best-effort](mobile.md#steps), not a foreground/rendered-readiness guarantee. Computer starts retain a 10-minute default timeout; an unclaimed start may fail after 120 seconds with no-host context.
 
-Both computer operating systems are early access on staging only for organizations enabled for the requested OS, not yet available in Revyl production. Use the optional `REVYL_BACKEND_URL` override and staging credentials described in [computer availability](computers.md#availability-and-errors).
+Both computer operating systems are early access. Ask support@revyl.ai about access.
 
 ```ts
 const web = await open('web');                                       // a target named in verify.config.ts
@@ -25,6 +25,68 @@ const linux = await open({ platform: 'linux' });                    // same comp
 
 `open` needs credentials: `REVYL_API_KEY` or a Revyl CLI login. It throws `AUTH_MISSING` without them, `CONFIG_NOT_FOUND` or `CONFIG_INVALID` for config problems, and `SESSION_START_FAILED` or `TIMEOUT` when the browser or device does not start.
 
+## Inside a revyl-macos GitHub Actions job
+
+`currentComputer(options?)` attaches to `REVYL_COMPUTER_ID` using normal credential resolution. It is non-owning by default: close cleans up hosted children, while the job's owner releases the computer. It never creates a computer and throws `COMPUTER_ID_MISSING` when the ID is unset or blank. Invalid IDs fail with `INVALID_ARGUMENT`.
+
+This helper is included in the TypeScript 0.3.1 release and requires a runner configured to inject `REVYL_COMPUTER_ID` and a short-lived `REVYL_API_KEY`. A workflow can supply its own `REVYL_API_KEY` instead. After installing the project dependencies and selecting Node.js ≥22.18, add this step to a job with `runs-on: revyl-macos`:
+
+```yaml
+- name: Run Verify
+  run: |
+    node --input-type=module <<'JS'
+    import { currentComputer } from '@revyl/verify';
+    const computer = await currentComputer();
+    try {
+      await computer.screenshot({ path: 'computer.png' });
+    } finally {
+      await computer.close();
+    }
+    JS
+```
+
+The helper accepts the same options as `attach`, including explicit `backendUrl` and `appUrl`; it does not read URL environment variables. `stopOnClose: true` explicitly takes ownership and can end the job's computer when closed. Use `computer.open(target)` with an exact app/build pair for hosted app sessions.
+
+## attach(computerId, options?)
+
+The attachment, hosted-child and navigation APIs below are included in the TypeScript 0.3.1 release.
+
+`open()` and `computer.open()` return the extended `OpenedSession` interface. The original `Session` interface keeps its existing required members, so applications implementing or mocking it do not need to add the new methods. Use `OpenedSession` when explicitly annotating a value that calls `report`, `navigate` or `open`.
+
+Attaches to an active Mac or Linux computer in your organization without creating a new one. `options.log` controls progress. The returned computer owns cleanup by default: `close()` stops it, and automatic cleanup also applies. Attaching requires a valid expiry and does not extend the lifetime. Invalid, inaccessible, inactive or expired computers fail without sending a stop request.
+
+When attaching to a computer you do not own, such as a CI runner, pass `attach(computerId, { stopOnClose: false })`. The attachment is not registered for automatic cleanup. Its `close()` still cancels pending child starts and gives hosted children the same five-second cleanup phase, but never stops the computer; its owner must release it. Child cleanup failures remain observable. This option is explicit and is never inferred from the environment.
+
+## computer.open(target)
+
+Starts a child app session inside this computer, returning the normal session API. It inherits the parent's authenticated client, logging and step timeout; callers cannot route a child to another backend. Both `target.app.appId` and `target.app.buildId` are required. Web accepts an existing external HTTPS build, plus optional viewport/sign-in settings; native builds use the computer's fixed device profile and accept no bundle, artifact or device override. Named targets and initial URL overrides are not supported here.
+
+Mac supports Web and iOS children. Linux supports Android and may support Web when its runtime advertises that capability; Linux Web currently has a runtime limitation, so do not rely on it without confirming availability. The server remains authoritative for access, capability and capacity. Children require and share the parent's known deadline. Closing a child leaves the parent running; closing the parent cancels pending starts and gives child cleanup at most five seconds total before requesting confirmed computer release. The parent stop also stops any remaining children, so a slow child cannot prevent that request. A failed child start never closes the parent.
+
+```ts
+const computer = await attach(existingComputerId, { log: false });
+try {
+  const web = await computer.open({
+    platform: 'web',
+    app: { appId: webAppId, buildId: externalBuildId },
+  });
+  await web.navigate('http://localhost:3000');
+  await web.validation('The home page is visible');
+} finally {
+  await computer.close();
+}
+```
+
+This requires an already-running service on the computer. The initial Web build still uses HTTPS; navigation after start can reach the computer's localhost. No localhost-start option is implied.
+
+## session.navigate(url)
+
+Web only, hosted or normal. Sends one deterministic `open_url` action and checks the returned navigation outcome. Accepts an HTTP(S) URL without credentials, whitespace, control characters or backslashes. Loopback addresses are accepted on every Web session: a hosted browser can reach its parent computer's loopback address; a normal cloud browser's localhost is its own runtime, not your machine. A cold development server may need a warm-up request before navigation succeeds; after an uncertain timeout, re-navigating is the caller's choice because the original request may still commit. The runtime is responsible for enforcing its navigation network policy. Navigation is not replayed by Verify and does not run an agent step. It resolves with no value, or throws a typed error. Computer and native sessions reject it locally.
+
+## session.report()
+
+Returns authenticated JSON metadata: `/execution/device-sessions/{id}` for normal and hosted app sessions, or the computer report for computers. It works after close, but fails locally with `NOT_FOUND` when no session ID is known. It does not download recordings or turn a device stop acknowledgment into proof of physical release. Treat returned metadata as private.
+
 ## session.instruction(text, options?)
 
 Available on web/iOS/Android only. Computers throw `NOT_AVAILABLE_ON_PLATFORM` without sending an agent request.
@@ -71,7 +133,7 @@ Resolves with a PNG of the screen as a `Uint8Array`. With `options.path`, also w
 
 Requests that Revyl stop the session. For web/mobile, success acknowledges the stop request rather than proving physical release. It is safe to call more than once, and steps after it throw `SESSION_ENDED`. A `Session` also works with `await using`, which closes it at the end of the block.
 
-For computers, cleanup must be confirmed; a terminal state alone does not prove physical release. Uncertain release throws `ACTION_UNCERTAIN`.
+For owning computers, cleanup must be confirmed; a terminal state alone does not prove physical release. Uncertain release throws `ACTION_UNCERTAIN`. A non-owning attachment closes its children and local handle without requesting computer release.
 
 ## Computer commands, files, and processes
 

package/docs/ci.md

@@ -1,6 +1,6 @@
 # CI and test runners
 
-Verify is a library, so it runs wherever your code runs. Browsers, devices, and computers run in Revyl's cloud, so the runner needs nothing but Node.js and an API key. Both Mac and Linux computer targets work from a Linux runner; no local guest runtime is needed. Use the same staging URL overrides and organization/OS enablement as [computers.md](computers.md).
+Verify is a library, so it runs wherever your code runs. Browsers, devices, and computers run in Revyl's cloud, so the runner needs Node.js and an API key. Install it with `npm install @revyl/verify`; in CI, `npm ci` and a `REVYL_API_KEY` secret are enough.
 
 ## A script in GitHub Actions