@revyl/verify 0.0.0-stage → 0.2.0

package/dist/session.js

@@ -0,0 +1,443 @@
+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 { trackSession, untrackSession } from './cleanup.js';
+import { VerifyError, errorMessage, isVerifyError } from './errors.js';
+import { screenHasContent } from './screen-readiness.js';
+const POLL_INTERVAL_MS = 2_000;
+const DEVICE_CONNECT_TIMEOUT_MS = 90_000;
+const STEP_POLL_BASE_MS = 500;
+const STEP_POLL_MAX_MS = 5_000;
+const STEP_CANCEL_TIMEOUT_MS = 5_000;
+const MAX_STEP_TEXT_LENGTH = 4_000;
+const ENDED_STATUSES = new Set(['completed', 'failed', 'cancelled', 'timeout', 'stopping']);
+const STEP_TERMINAL_STATUSES = new Set(['completed', 'failed']);
+const SESSION_NOT_RUNNING = /session is (not running|not active|stopping)/i;
+const UNCERTAIN_ERROR_CODES = new Set(['request_timeout', 'connection_closed', 'protocol_error']);
+/** A Revyl cloud browser or iOS or Android device. */
+export class DeviceSession {
+    client;
+    options;
+    platform;
+    /** The target name: its key in verify.config.ts, or the platform for a target passed inline. */
+    target;
+    /** Revyl's session id. */
+    id;
+    /** The live view of the session in Revyl, and its recording and report once it ends. */
+    viewerUrl;
+    /** Every instruction and validation run on this session, in order. */
+    steps = [];
+    workflowRunId;
+    closePromise;
+    stepRunning = false;
+    constructor(client, target, id, workflowRunId, options) {
+        this.client = client;
+        this.options = options;
+        this.platform = target.platform;
+        this.target = target.name;
+        this.id = id;
+        this.workflowRunId = workflowRunId;
+        this.viewerUrl = sessionViewerUrl(id);
+    }
+    static async start(client, target, options) {
+        const deadline = Date.now() + target.startTimeout;
+        if (target.platform === 'web') {
+            const buildId = await resolveWebBuildId(client, target);
+            const sessionId = randomUUID();
+            const request = {
+                platform: 'web',
+                session_id: sessionId,
+                app_id: target.app.appId,
+                build_id: buildId,
+                idle_timeout_seconds: target.idleTimeoutSeconds,
+                web: {
+                    ...(target.viewport
+                        ? {
+                            viewport: {
+                                width: target.viewport.width,
+                                height: target.viewport.height,
+                                ...(target.viewport.deviceScaleFactor ? { device_scale_factor: target.viewport.deviceScaleFactor } : {}),
+                            },
+                        }
+                        : {}),
+                    ...(target.signIn
+                        ? { sign_in: { path: target.signIn.path, secret_name: target.signIn.secret, ...(target.signIn.persona ? { persona: target.signIn.persona } : {}) } }
+                        : {}),
+                },
+            };
+            const response = await client.startDevice(request);
+            if (response.session_id !== sessionId) {
+                throw new VerifyError('SESSION_START_FAILED', `Revyl did not start the ${target.name} web session: ${response.error ?? response.message ?? 'the start was not acknowledged'}`);
+            }
+            const session = new DeviceSession(client, target, sessionId, response.workflow_run_id ?? '', options);
+            await session.untilReady(() => session.waitForWebReady(deadline));
+            return session;
+        }
+        const { app } = target;
+        const request = {
+            platform: target.platform,
+            is_simulation: true,
+            idle_timeout_seconds: target.idleTimeoutSeconds,
+            ...(app.appId ? { app_id: app.appId } : {}),
+            ...(app.buildId ? { build_id: app.buildId } : {}),
+            ...(app.artifactUrl ? { app_url: app.artifactUrl } : {}),
+            ...(target.device?.model ? { device_model: target.device.model } : {}),
+            ...(target.device?.osVersion ? { os_version: target.device.osVersion } : {}),
+        };
+        const response = await client.startDevice(request);
+        if (!response.workflow_run_id) {
+            throw new VerifyError('SESSION_START_FAILED', `Revyl did not start the ${target.name} device: ${response.error ?? response.message ?? 'no workflow run was returned'}`);
+        }
+        const session = new DeviceSession(client, target, response.session_id ?? '', response.workflow_run_id, options);
+        await session.untilReady(async () => {
+            await session.waitForDeviceReady(deadline);
+            if (app.bundleId)
+                await session.launch(app.bundleId);
+            await session.waitForScreenContent(deadline);
+        });
+        return session;
+    }
+    get closed() {
+        return this.closePromise !== undefined;
+    }
+    /** 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. */
+    async instruction(text, options = {}) {
+        const result = await this.step('instruction', text, options.timeout);
+        if (!result.passed) {
+            throw new VerifyError('INSTRUCTION_FAILED', `Instruction failed: "${result.text}". ${sentence(result.reason)} See ${this.viewerUrl}`);
+        }
+        return result;
+    }
+    /**
+     * Asks Revyl's agent whether something holds on screen, such as "the cart shows 2 items". Throws VALIDATION_FAILED when it does not,
+     * unless soft is set, and STEP_FAILED when Revyl could not reach a verdict.
+     */
+    async validation(text, options = {}) {
+        const result = await this.step('validation', text, options.timeout);
+        if (!result.passed && !options.soft) {
+            throw new VerifyError('VALIDATION_FAILED', `Validation failed: "${result.text}". ${sentence(result.reason)} See ${this.viewerUrl}`);
+        }
+        return result;
+    }
+    /** A PNG of the screen right now, also written to path when given. */
+    async screenshot(options = {}) {
+        const response = await this.worker('GET', 'screenshot', { retry: true });
+        if (!pngSize(response.body))
+            throw new VerifyError('ACTION_FAILED', 'Revyl returned a screenshot that is not a PNG image.');
+        if (options.path) {
+            const path = resolve(options.path);
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, response.body);
+        }
+        return response.body;
+    }
+    exec() {
+        return this.computerOnly('exec');
+    }
+    recording() {
+        return this.computerOnly('recording');
+    }
+    readFile() {
+        return this.computerOnly('readFile');
+    }
+    writeFile() {
+        return this.computerOnly('writeFile');
+    }
+    stat() {
+        return this.computerOnly('stat');
+    }
+    processes() {
+        return this.computerOnly('processes');
+    }
+    terminate() {
+        return this.computerOnly('terminate');
+    }
+    /** Stops the session on Revyl. Safe to call more than once. */
+    close() {
+        this.closePromise ??= (async () => {
+            try {
+                if (this.id)
+                    await this.client.stopDeviceSession(this.id);
+                else
+                    await this.client.cancelDevice(this.workflowRunId);
+                this.log('closed');
+            }
+            finally {
+                untrackSession(this);
+            }
+        })();
+        return this.closePromise;
+    }
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+    async step(type, text, timeout) {
+        if (typeof text !== 'string' || text.trim() === '' || text.length > MAX_STEP_TEXT_LENGTH) {
+            throw new VerifyError('INVALID_ARGUMENT', `${type}() takes a description of 1 to ${MAX_STEP_TEXT_LENGTH} characters.`);
+        }
+        const timeoutMs = timeout ?? this.options.stepTimeout;
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000) {
+            throw new VerifyError('INVALID_ARGUMENT', `${type}() takes a timeout of at least 1000 ms.`);
+        }
+        if (this.stepRunning) {
+            throw new VerifyError('INVALID_ARGUMENT', 'Run one step at a time on a session: await each instruction or validation before starting the next.');
+        }
+        this.stepRunning = true;
+        const description = text.trim();
+        const startedAt = Date.now();
+        try {
+            const outcome = await this.runStep(type, description, timeoutMs);
+            const output = outcome.step_output ?? {};
+            const reason = output.status_reason ?? output.reasoning ?? undefined;
+            if (type === 'validation' && (outcome.success !== true || typeof output.validation_result !== 'boolean')) {
+                const why = outcome.success === true ? 'Revyl returned no verdict.' : sentence(reason);
+                throw new VerifyError('STEP_FAILED', `Validation did not reach a verdict: "${description}". ${why} See ${this.viewerUrl}`);
+            }
+            const passed = type === 'validation' ? output.validation_result === true : outcome.success === true && output.status !== 'failed';
+            const result = { type, text: description, passed, ...(reason ? { reason } : {}), durationMs: Date.now() - startedAt };
+            this.steps.push(result);
+            this.log(`${passed ? '✓' : '✗'} ${type} "${description}" (${formatDuration(result.durationMs)})${!passed && reason ? `: ${reason}` : ''}`);
+            return result;
+        }
+        catch (error) {
+            this.log(`✗ ${type} "${description}": ${isVerifyError(error) ? error.code : errorMessage(error)}`);
+            throw error;
+        }
+        finally {
+            this.stepRunning = false;
+        }
+    }
+    async runStep(type, description, timeoutMs) {
+        const signal = AbortSignal.timeout(timeoutMs);
+        let stepId;
+        try {
+            const response = await this.worker('POST', 'execute_step', {
+                body: {
+                    step_type: type,
+                    step_description: description,
+                    ...(this.id ? { session_id: this.id } : {}),
+                    workflow_run_id: this.workflowRunId,
+                },
+                signal,
+                timeoutMs,
+            });
+            const body = parseJson(response, 'execute_step');
+            if ('success' in body)
+                return body;
+            if (body.status !== 'accepted' || !body.step_id) {
+                throw new VerifyError('API_ERROR', 'Revyl answered execute_step without a result or an accepted step id.');
+            }
+            stepId = body.step_id;
+            for (let wait = STEP_POLL_BASE_MS;; wait = Math.min(wait * 2, STEP_POLL_MAX_MS)) {
+                await delay(wait, undefined, { signal });
+                const status = parseJson(await this.worker('GET', `step_status/${encodeURIComponent(stepId)}`, { signal, retry: true }), 'step_status');
+                if (status.status === 'running')
+                    continue;
+                if (status.status === 'cancelled') {
+                    throw new VerifyError('STEP_FAILED', `The ${type} was cancelled on Revyl before it finished: "${description}". See ${this.viewerUrl}`);
+                }
+                if (!STEP_TERMINAL_STATUSES.has(status.status) || !status.result) {
+                    throw new VerifyError('API_ERROR', `Step ${stepId} reported status ${status.status} without a result Verify can read.`);
+                }
+                return status.result;
+            }
+        }
+        catch (error) {
+            if (!signal.aborted)
+                throw error;
+            if (stepId) {
+                await this.client
+                    .worker(this.workflowRunId, `step_cancel/${encodeURIComponent(stepId)}`, {
+                    method: 'POST',
+                    body: {},
+                    signal: AbortSignal.timeout(STEP_CANCEL_TIMEOUT_MS),
+                })
+                    .catch(() => undefined);
+            }
+            throw new VerifyError('TIMEOUT', `The ${type} did not finish within ${timeoutMs} ms and was cancelled: "${description}". See ${this.viewerUrl}`);
+        }
+    }
+    async launch(bundleId) {
+        const response = await this.worker('POST', 'launch', { body: { bundle_id: bundleId } });
+        const result = parseJson(response, 'launch');
+        if (result.success !== true) {
+            throw new VerifyError('SESSION_START_FAILED', `Could not launch ${bundleId} on the ${this.target} device: ${result.error ?? 'no reason given'}`);
+        }
+    }
+    async waitForScreenContent(startDeadline) {
+        const deadline = Math.min(startDeadline, Date.now() + 10_000);
+        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())),
+                });
+                if (response.status === 200) {
+                    const content = screenHasContent(response.body);
+                    if (content === true)
+                        return;
+                    if (content === undefined)
+                        break;
+                }
+                else if (response.status !== 409 && response.status !== 503) {
+                    break;
+                }
+            }
+            catch {
+                break;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining > 0)
+                await delay(Math.min(500, remaining));
+        }
+        this.log('debug: best-effort first-screen wait ended without non-blank content; the runtime has no rendered-readiness signal');
+    }
+    log(line) {
+        this.options.log?.(`${this.target}: ${line}`);
+    }
+    computerOnly(call) {
+        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 (response.status >= 200 && response.status < 300)
+            return response;
+        throw this.workerError(method, action, response);
+    }
+    workerError(method, action, response) {
+        const baseAction = action.split('/')[0] ?? action;
+        const code = responseErrorCode(response);
+        const detail = responseDetail(response);
+        const reason = detail ?? code ?? `HTTP ${response.status}`;
+        if (response.status === 401 || response.status === 403)
+            return apiError(method, `device-proxy/${baseAction}`, response);
+        if (response.status === 501 || code === 'not_available_on_platform' || code === 'step_output_not_available') {
+            if (baseAction === 'execute_step' || baseAction === 'step_status') {
+                return new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `The Revyl backend at ${this.client.backendUrl} does not run instruction and validation steps on ${this.platform} sessions (${code ?? 'HTTP 501'}).`);
+            }
+            return new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `${baseAction} is not available on ${this.platform} sessions (${reason}).`);
+        }
+        if (response.status === 404 || response.status === 410) {
+            return new VerifyError('SESSION_ENDED', `The ${this.target} session is no longer reachable (${reason}). See ${this.viewerUrl}`);
+        }
+        if (response.status === 409) {
+            if (SESSION_NOT_RUNNING.test(reason)) {
+                return new VerifyError('SESSION_ENDED', `The ${this.target} session is no longer running (${reason}). See ${this.viewerUrl}`);
+            }
+            return new VerifyError('SESSION_BUSY', `The ${this.target} session is busy and refused ${baseAction}: ${reason}`);
+        }
+        if (method === 'POST' && (isExecutionUncertain(response) || (code && UNCERTAIN_ERROR_CODES.has(code)))) {
+            return new VerifyError('ACTION_UNCERTAIN', `${baseAction} may or may not have been applied (${reason}); Verify does not repeat it. Check the session at ${this.viewerUrl}`);
+        }
+        return new VerifyError('ACTION_FAILED', `${baseAction} failed on the ${this.target} session (HTTP ${response.status}): ${reason}`);
+    }
+    async untilReady(waitForReady) {
+        trackSession(this);
+        this.log(`starting ${this.platform} session ${this.viewerUrl}`);
+        try {
+            await waitForReady();
+        }
+        catch (error) {
+            await this.close().catch(() => undefined);
+            throw error;
+        }
+        this.log('ready');
+    }
+    async waitForWebReady(deadline) {
+        for (;;) {
+            const detail = await this.client.getDeviceSession(this.id);
+            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' });
+                if (response.status === 200 && pngSize(response.body))
+                    return;
+                if (response.status !== 503 && response.status !== 409 && responseErrorCode(response) !== 'not_ready') {
+                    throw this.workerError('GET', 'screenshot', response);
+                }
+            }
+            await waitBeforeDeadline(deadline, `The ${this.target} web session was not ready in time. See ${this.viewerUrl}`);
+        }
+    }
+    async waitForDeviceReady(deadline) {
+        for (;;) {
+            const connection = await this.client.getWorkerConnection(this.workflowRunId);
+            if (connection.status === 'ready' && connection.worker_ws_url)
+                break;
+            if (connection.status === 'cancelled' || connection.status === 'stopped' || connection.status === 'failed') {
+                throw new VerifyError('SESSION_START_FAILED', `The ${this.target} device did not start (${connection.status}): ${connection.message ?? 'no reason given'}`);
+            }
+            await waitBeforeDeadline(deadline, `The ${this.target} device was not assigned in time.`);
+        }
+        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 });
+            if (response.status === 200 && parseJson(response, 'health').device_connected)
+                return;
+            if (response.status !== 200 && response.status !== 503)
+                throw this.workerError('GET', 'health', response);
+            await waitBeforeDeadline(connectDeadline, `The ${this.target} device did not connect in time.`);
+        }
+    }
+}
+async function resolveWebBuildId(client, target) {
+    const { app } = target;
+    if (app.buildId)
+        return app.buildId;
+    if (app.url) {
+        const build = await client.registerWebUrlBuild(app.appId, { url: app.url, ...(app.branch ? { branch_name: app.branch } : {}) });
+        if (!build.id)
+            throw new VerifyError('API_ERROR', `Revyl registered ${app.url} without returning a build id.`);
+        return build.id;
+    }
+    let branchId;
+    if (!app.branch) {
+        const detail = await client.getApp(app.appId);
+        if (detail.platform && detail.platform.toLowerCase() !== 'web') {
+            throw new VerifyError('CONFIG_INVALID', `Target ${target.name}: Revyl app ${app.appId} is a ${detail.platform} app, not a web app.`);
+        }
+        branchId = detail.default_branch_id ?? undefined;
+    }
+    const latest = await client.latestWebBuild(app.appId, { branchId, branchName: app.branch });
+    if (!latest?.id) {
+        throw new VerifyError('SESSION_START_FAILED', `Target ${target.name}: Revyl app ${app.appId} has no web build${app.branch ? ` on branch ${app.branch}` : ''}. ` +
+            "Set app.url to a deployed HTTPS URL, or build one with 'revyl build --platform web'.");
+    }
+    return latest.id;
+}
+async function waitBeforeDeadline(deadline, timeoutMessage) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new VerifyError('TIMEOUT', timeoutMessage);
+    await delay(Math.min(POLL_INTERVAL_MS, remaining));
+}
+function isExecutionUncertain(response) {
+    try {
+        return JSON.parse(new TextDecoder().decode(response.body)).execution_uncertain === true;
+    }
+    catch {
+        return false;
+    }
+}
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+export function pngSize(bytes) {
+    if (bytes.length < 24 || PNG_SIGNATURE.some((value, index) => bytes[index] !== value))
+        return undefined;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const width = view.getUint32(16);
+    const height = view.getUint32(20);
+    return width > 0 && height > 0 ? { width, height } : undefined;
+}
+function formatDuration(ms) {
+    return ms < 60_000 ? `${(ms / 1_000).toFixed(1)}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1_000)}s`;
+}
+function sentence(reason) {
+    if (!reason)
+        return 'Revyl gave no reason.';
+    return /[.!?]$/.test(reason.trim()) ? reason.trim() : `${reason.trim()}.`;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+export declare const PACKAGE_NAME: string;

package/dist/version.js

@@ -0,0 +1,6 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const manifestPath = fileURLToPath(new URL('../package.json', import.meta.url));
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+export const VERSION = manifest.version;
+export const PACKAGE_NAME = manifest.name;

package/docs/README.md

@@ -0,0 +1,19 @@
+# Verify documentation
+
+These files ship inside the npm package at `node_modules/@revyl/verify/docs/`, so a coding agent working in your project can read the docs for the exact version you installed.
+
+| File | Read it when you want to |
+| --- | --- |
+| [end-to-end.md](end-to-end.md) | Review live verification scope, observed outcomes, and evidence limits |
+| [getting-started.md](getting-started.md) | Install Verify, authenticate, and run a first script |
+| [api.md](api.md) | Look up session lifecycle, agent steps, screenshots, commands, files, and processes |
+| [configuration.md](configuration.md) | Look up every option in `verify.config.ts`, the environment variables, and the CLI |
+| [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 |
+
+[llms.txt](llms.txt) lists the same files in the llms.txt format.

package/docs/agents.md

@@ -0,0 +1,43 @@
+# For coding agents
+
+This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that use Verify to check an app on a cloud browser/device or run commands and files on a Mac or Linux computer. The rest of this folder describes the API in full; this page is the workflow.
+
+## Workflow
+
+1. Read `verify.config.ts` to learn the target names and their platforms. If there is none, run `npx @revyl/verify init --platform <web|ios|android> --app-id <id>`, or `npx @revyl/verify init --platform mac` without an app id. You can also pass a target object to `open()`.
+2. Check the credentials once with `npx @revyl/verify whoami`. It starts no session.
+3. Write a short script, or extend an existing one, that opens one target, runs the steps you need, and closes:
+   ```ts
+   import { open } from '@revyl/verify';
+
+   const session = await open('ios');
+   try {
+     await session.instruction('Sign in as the demo user');
+     await session.validation('The dashboard shows at least one project card');
+     await session.screenshot({ path: '.verify/dashboard.png' });
+   } finally {
+     await session.close();
+   }
+   ```
+4. Run it with `node path/to/script.ts`. Share the session link from the first `[verify]` line with the user, so they can watch.
+5. Read the outcome from the exit code and stderr. Each step prints `✓` or `✗` with its text; a failure prints `CODE: message`, ending with the session link. Look at any screenshot you saved before changing the script or the app.
+
+## 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.
+
+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.
+
+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.
+
+- Write steps the way you would brief a person: what to do, or what should be true, in one sentence. Name visible things ("the blue Save button in the footer"), not implementation details.
+- Use `instruction` for doing and `validation` for checking. Do not ask an instruction to check something, or a validation to change anything.
+- Prefer several small steps to one long one. Small steps fail with clearer reasons and time out less.
+- Each step stands alone: Revyl does not carry values from one step to the next. Put everything a step needs into its text.
+- Every step runs Revyl's agent again; nothing is cached or replayed. Do not rerun a whole script to probe one step.
+- Await each step. Two steps at once on one session throw `INVALID_ARGUMENT`.
+- Do not catch `VerifyError` to make a check pass. A `NOT_AVAILABLE_ON_PLATFORM` error means the call is not offered on that platform; see [web.md](web.md) and [computers.md](computers.md). A `STEP_FAILED` error means the step did not run to an outcome, not that the app is wrong.
+- Never automatically repeat a computer mutation after `ACTION_UNCERTAIN` or a timeout: the command may have run, and timeout does not prove termination or rollback. Do not log argv, stdin, file contents, or credentials.
+- Always close what you open in `try/finally`. Each open session is paid. Automatic cleanup is best effort with a 15-second bound and skips signal/error events that already have listeners. Device close acknowledges stop, while computer close requires confirmed terminal release.
+- Never put secrets in scripts or config. Credentials come from `REVYL_API_KEY` or a Revyl CLI login; web sign-in uses the **name** of a Revyl organization secret.
+- Step descriptions are sent to Revyl and logged to stderr by default. Do not include private credentials or customer data in instruction or validation text; use test-only sign-in and synthetic data instead. `log: false` suppresses local progress, not remote processing or reports.

package/docs/api.md

@@ -0,0 +1,120 @@
+# API
+
+```ts
+import { open, defineConfig, VerifyError, isVerifyError } from '@revyl/verify';
+```
+
+## open(target, options?)
+
+Linux targets are supported **since 0.2.0**; 0.1.0 includes the target type but rejects Linux locally.
+
+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).
+
+```ts
+const web = await open('web');                                       // a target named in verify.config.ts
+const ios = await open({ platform: 'ios', app: { appId: '…' } });    // or a target object, no config needed
+const mac = await open({ platform: 'mac' });                        // computer, no app needed
+const linux = await open({ platform: 'linux' });                    // same computer surface
+```
+
+- `target`: a target name from `verify.config.ts`, or a target object with the same shape as a config entry (see [configuration.md](configuration.md)). Verify reads the nearest `verify.config.ts` at or above the current folder.
+- `options.config`: the path of a config file to read instead.
+- `options.log`: where progress lines go. By default Verify writes the session link and each step's outcome to stderr, prefixed with `[verify]`. Pass a function to receive the lines yourself, or `false` to turn them off.
+
+`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.
+
+## session.instruction(text, options?)
+
+Available on web/iOS/Android only. Computers throw `NOT_AVAILABLE_ON_PLATFORM` without sending an agent request.
+
+Asks Revyl's agent to do something in the app, described the way you would tell a person: `'Sign in as the demo user and open Settings'`. The agent looks at the screen and acts until it is done or decides it cannot.
+
+- Resolves with a `StepResult` when the agent finishes.
+- Throws `INSTRUCTION_FAILED`, with Revyl's reason and the session link, when it cannot, and `STEP_FAILED` when the step is cancelled on Revyl.
+- `options.timeout`: milliseconds before the step is cancelled on Revyl (`TIMEOUT`). Defaults to `stepTimeout` in the config, or 180000.
+
+## session.validation(text, options?)
+
+Available on web/iOS/Android only, not computers.
+
+Asks Revyl's agent whether something holds on screen right now: `'The cart shows 2 items and a total of $40'`.
+
+- Resolves with a `StepResult` whose `passed` is `true` when it holds.
+- Throws `VALIDATION_FAILED`, with Revyl's reason and the session link, when it does not. This is what makes a plain script exit non-zero.
+- Throws `STEP_FAILED` when Revyl cannot reach a verdict, for example because the step errored or was cancelled on Revyl.
+- `options.soft: true` returns a failed result instead of throwing `VALIDATION_FAILED`, for scripts that want to collect several outcomes. It does not turn `STEP_FAILED` into a result.
+- `options.timeout`: as for `instruction`.
+
+## StepResult
+
+```ts
+interface StepResult {
+  type: 'instruction' | 'validation';
+  text: string;          // the step as sent, trimmed
+  passed: boolean;
+  reason?: string;       // Revyl's explanation, when it gave one
+  durationMs: number;
+}
+```
+
+`session.steps` lists every step run on the session, in order.
+
+When inspecting `revyl device report --session-id <id>`, read validation verdicts from the step's `effective_status` and `validation_result`, with `validations_passed` / `total_validations` for the validation summary. `passed_steps` / `failed_steps` and transport `status` are not enough: a successfully executed validation can have a false verdict. The SDK's `StepResult.passed` reflects that verdict, not just transport success.
+
+## session.screenshot(options?)
+
+Resolves with a PNG of the screen as a `Uint8Array`. With `options.path`, also writes it there, creating folders as needed.
+
+## session.close()
+
+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`.
+
+## Computer commands, files, and processes
+
+Mac and Linux sessions provide `exec(argv: string[], options?)`, `readFile(path, options?)` returning `Buffer`, `writeFile(path, string | Uint8Array, options?)`, `stat(path, options?)` returning `{ kind, size }`, `processes(options?)` returning `{ id, state, exitCode? }[]`, and `terminate(id, options?)`. They throw `NOT_AVAILABLE_ON_PLATFORM` on web/iOS/Android. See [computers.md](computers.md) for complete signatures, limits, timeouts, and examples. Both support `screenshot()`; instruction/validation do not run on computers.
+
+### `session.recording(): Promise<ComputerRecording | null>`
+
+**Since 0.2.0.** This method is not available in 0.1.0.
+
+Computers only. First reads the report and requires terminal state plus confirmed release, otherwise throws `SESSION_BUSY`. Returns `{ url: string, durationSeconds?: number, startedAt?: Date }` or null for an unavailable recording. Nullable optional wire fields are omitted. This method works after `close()`, does not wait for upload, and does not download or fetch the URL. Keep the signed HTTPS URL and its query private. Request fresh metadata when the URL expires. The normal report has no recording URL. Devices reject this call locally with `NOT_AVAILABLE_ON_PLATFORM`.
+
+## Other session properties
+
+| Property | Meaning |
+| --- | --- |
+| `viewerUrl` | The session in Revyl: a live view while it runs, its recording/report after. Use `revyl device report --session-id <id>` for web/mobile, or `revyl computer report <id>` for computers. |
+| `id` | Revyl's session id |
+| `platform` | `'web'`, `'ios'`, `'android'`, `'mac'`, or `'linux'` |
+| `expiresAt` | **Since 0.2.0.** Validated API expiry as a `Date`, or undefined for devices and older APIs. Computers have a hard 60-minute lifetime from create. Operations/screenshot observation are bounded by expiry; close and recording remain possible. |
+| `target` | The target name, or the platform for a target object |
+| `closed` | Whether `close()` was called |
+
+## Rules worth knowing
+
+- **One step at a time.** Await each step before starting the next on the same session; a second concurrent step throws `INVALID_ARGUMENT`. Separate sessions can run in parallel.
+- **No hidden retries.** Verify never repeats a step or a device action. A step whose outcome is unknown because the connection failed mid-request throws `ACTION_UNCERTAIN`.
+- **No memory between steps.** Each step is independent: Revyl does not carry values from one step to the next. Put everything a step needs into its text.
+- **No replay or cache.** Every step runs Revyl's agent again, every time.
+
+## Cleanup
+
+While a session is open, Verify attempts best-effort cleanup with a 15-second budget:
+
+- on Ctrl+C or SIGTERM: it attempts to close open sessions, then exits with 130 or 143 (a second Ctrl+C exits at once);
+- on an uncaught error, such as a failed validation that nothing catches: it prints the error, attempts cleanup, then exits with 1;
+- when the script finishes without calling `close()`: it attempts cleanup and prints a reminder.
+
+Verify skips installing a signal or error handler when that event already has listeners, so test runners and apps that manage their own shutdown keep control of it. Always close in `try/finally` or an `after` hook; automatic cleanup cannot guarantee success. A process that is killed outright, or calls `process.exit()` with sessions open, leaves browser/mobile sessions running until their idle timeout (10 minutes by default). Computers have a server-bounded one-hour lifetime instead; no idle timeout is configurable.
+
+## defineConfig(config)
+
+Returns the config unchanged; it exists for type checking in `verify.config.ts`. See [configuration.md](configuration.md).
+
+## Errors
+
+Everything Verify throws on purpose is a `VerifyError` with a stable `code`; `isVerifyError(error)` narrows to it. See [errors.md](errors.md).