@revyl/verify 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,8 +1,28 @@
 # Changelog
 
+## Unreleased
+
+- Add a standard-library-only Go SDK for web, iOS, Android, and early-access Mac and Linux computers. Computer commands, binary files, process handles, screenshots, recording metadata, and confirmed-release cleanup require an enabled staging organization and are not yet available in production. Capacity refusals have a distinct `COMPUTER_LIMIT` code; no start or operation is automatically replayed.
+
+## 0.2.0
+
+Prepared for release; see npm for publication status.
+
+- Enable Linux named and inline computer targets with the shared Mac command, file, process, screenshot, and confirmed-release cleanup surface. Both operating systems remain early access on staging for enabled organizations/OSes, not yet available in production.
+- Add `COMPUTER_LIMIT` for queued work (including iOS) or concurrency admission refusals, without retrying or stopping a definitely refused start. Preserve `SESSION_BUSY` for operation limits.
+- Explain the 120-second unclaimed-start failure without shortening the default 10-minute start timeout.
+- Expose optional `expiresAt` and bound operation/screenshot observation by the hard 60-minute lifetime from create, while keeping explicit close possible.
+- Add computer `recording()` metadata retrieval after terminal state and confirmed release, including after close. Missing recordings return null; signed URLs remain private, with no automatic waiting or download.
+- Keep Linux CLI init intentionally unavailable; use inline targets or config entries. Computer instruction/validation remain locally unavailable.
+- Observe mobile first-screen content best-effort for up to 10 seconds after connection/launch, without pretending the runtime provides rendered-readiness guarantees. Generated mobile examples begin with an instruction to wait for the first screen before validation.
+- Retry structured computer screen-not-ready responses with bounded backoff during the fixed startup window; do not replay mutations or unrelated failures.
+- Skip CI publication when the exact version is already on npm, require explicit administrator opt-in for new CI publications, fail closed on registry lookup errors, and document manual Mac publication, optional trusted publishing, and independent Go module tags.
+
+Regression validation uses fake API responses. The [end-to-end record](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/end-to-end.md) distinguishes baseline live runs from startup fixes still awaiting live re-verification.
+
 ## 0.1.0
 
-Initial release preparation; this entry does not mean the package has been published.
+Published manually from a maintainer's Mac without provenance.
 
 - Open Revyl cloud web browsers, iOS simulators, and Android emulators from TypeScript.
 - Run natural-language instruction and validation steps, with typed failures and optional soft validation results.

package/README.md

@@ -1,101 +1,138 @@
-# Verify
+<h1 align="center">Verify</h1>
 
-**Open cloud browsers and mobile devices for Revyl's agent, or a Mac computer for commands and files, from TypeScript.**
+<p align="center">
+  <em>Cloud browsers, mobile devices and computers from TypeScript and Go.</em>
+</p>
 
-```ts
-import { open } from '@revyl/verify';
+<p align="center">
+  <a href="https://github.com/RevylAI/verify/blob/v0.2.0/CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.2.0-9D61FF" alt="Source version" /></a>
+  <a href="https://github.com/RevylAI/verify/blob/v0.2.0/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0" /></a>
+  <a href="https://www.npmjs.com/package/@revyl/verify"><img src="https://img.shields.io/npm/v/@revyl/verify?color=9D61FF" alt="npm" /></a>
+  <a href="https://pkg.go.dev/github.com/RevylAI/verify/go"><img src="https://img.shields.io/badge/Go-reference-00ADD8?logo=go&logoColor=white" alt="Go reference" /></a>
+  <a href="https://github.com/RevylAI/verify/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/RevylAI/verify/ci.yml?branch=main&label=CI" alt="CI" /></a>
+</p>
 
-const session = await open('ios');
-await session.instruction('Add the first product to the cart and open the cart');
-await session.validation('The cart lists one item with a price');
-await session.close();
-```
+---
+
+Verify is a TypeScript and Go library for [Revyl](https://revyl.com). Open a cloud browser, iOS simulator or Android emulator for natural-language instructions and validations, or an early-access Mac/Linux computer for commands, files, processes and screenshots. Call it from a script, coding agent or your existing test runner.
+
+## For coding agents
+
+Run these from the project's directory with Node.js ≥22.18. The authentication command requires the [Revyl CLI](https://github.com/RevylAI/revyl-cli#install); if `REVYL_API_KEY` is already supplied securely, skip login.
 
 ```bash
-npx @revyl/verify init       # writes verify.config.ts and verify/example.ts
-node verify/example.ts       # opens the session, prints a link to watch it live, runs the steps
+npm install --save-dev @revyl/verify
+npx @revyl/verify init --platform ios
+revyl auth login
+npx @revyl/verify whoami
 ```
 
-Verify is a small TypeScript library on top of [Revyl](https://revyl.com). Open a browser or mobile device for **instruction** and **validation** steps, or a Mac computer for commands, files, processes, and screenshots. It has no test framework of its own, so you call it from wherever you already write code:
+If login prints an approval URL, share it privately with the user so they can approve it in their browser. For unattended runs, supply `REVYL_API_KEY` through a secret manager; never put credentials in argv, source or logs. Configure the generated `verify.config.ts` before running `node verify/example.ts`. Starting a cloud session requires an authorized account and workload.
 
-- **A plain script.** A failed validation throws, the script exits non-zero, and Verify closes the session on the way out.
-- **A coding agent.** An agent can check its own change on a real device in five lines, then read a one-line outcome per step and a link to the recording.
-- **CI.** Run the script in a job. The browsers and devices run in Revyl's cloud, so the runner needs nothing but Node and an API key.
-- **Your test runner.** Call it inside node:test, Vitest, Jest, or Playwright Test, next to the tests you already have.
+## Install
 
-## Quick start
+### npm
 
-You need Node.js 22.18 or later and a Revyl account.
+Use Node.js ≥22.18:
 
 ```bash
-npx @revyl/verify init
 npm install --save-dev @revyl/verify
-export REVYL_API_KEY=...          # or sign in with the Revyl CLI: revyl auth login
-node verify/example.ts
 ```
 
-Full walkthrough: [getting started](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/getting-started.md).
+### Go
+
+Use Go ≥1.26.9 in an existing Go module:
+
+```bash
+go get github.com/RevylAI/verify/go@main
+```
+
+There is no Go release tag yet. `@main` resolves to a pseudo-version; keep the generated `go.mod` and `go.sum` to pin it. Go tags are independent of npm versions. The SDK uses only the standard library.
+
+## Authenticate
+
+Both SDKs use this credential order:
 
-## The API
+1. A usable stored CLI login marked `local_auth_override`.
+2. `REVYL_API_KEY` from the environment.
+3. Another usable CLI login stored by `revyl auth login`.
 
-| Call | What it does |
-| --- | --- |
-| `open(target)` | Starts a Revyl cloud browser, device, or Mac computer, from a target name in `verify.config.ts` or a target object, and waits until it is ready |
-| `session.exec(argv, options?)` | Runs structured argv on a Mac computer; returns `{ exitCode, stdout, stderr }` |
-| `session.readFile(path)`, `writeFile(path, data)`, `stat(path)` | Reads a `Buffer`, writes a string or bytes, or returns `{ kind, size }` on a computer |
-| `session.processes()`, `terminate(id)` | Lists run-owned process handles or terminates one on a computer |
-| `session.instruction(text)` | Revyl's agent does what the text says. Throws `INSTRUCTION_FAILED` if it cannot. |
-| `session.validation(text)` | Revyl's agent checks that the text holds on screen. Throws `VALIDATION_FAILED` if it does not, or returns the result with `{ soft: true }`. |
-| `session.screenshot({ path })` | A PNG of the screen |
-| `session.viewerUrl` | The session in Revyl: live while it runs, its recording after |
-| `session.close()` | Stops the session. Verify also closes open sessions on Ctrl+C, on an uncaught error, and when a script ends without closing. |
+An expired access token can fall back to its stored API key. Set environment keys through a secret manager, or sign in interactively:
 
-Revyl failures are `VerifyError`s with a stable code, a safe reason, and the session link when one exists.
+```bash
+revyl auth login
+```
 
-## Platforms
+See [configuration](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/configuration.md) for credential and endpoint options.
 
-| | Web | iOS | Android | Mac | Linux |
-| --- | --- | --- | --- | --- | --- |
-| Runs on | Revyl cloud browser | Revyl iOS simulator | Revyl Android emulator | Revyl macOS computer | Contract only; open unavailable |
-| Opens | A public URL, or a web build in Revyl | A build in Revyl, a build URL, or an installed app | A build in Revyl, a build URL, or an installed app | A workspace, no app id | Nothing in this release |
-| `instruction`, `validation` | Yes | Yes | Yes | Unavailable | Unavailable |
-| Commands, files, processes | Unavailable | Unavailable | Unavailable | Early access on staging only for enabled organizations; not yet available in Revyl production | Contract only |
-| `screenshot`, `viewerUrl` | Yes | Yes | Yes | Yes | Unconfirmed |
+## Quick Start
 
-Steps on web go through the same Revyl API as on mobile. Production is the default; optional environment overrides are documented in [web.md](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/web.md). A backend without web-step support returns `NOT_AVAILABLE_ON_PLATFORM`.
+### TypeScript
 
-Each step runs Revyl's agent on the live session every time. Verify does not cache or replay steps, and Revyl does not carry values from one step to the next.
+Run `npx @revyl/verify init --platform ios`. For this Settings example, replace the generated `app` block with `app: { bundleId: 'com.apple.Preferences' }`. Save the following as `verify/example.ts` and run `node verify/example.ts`. For your own uploaded app, set `app.appId` and adapt the steps.
 
-For a Mac workspace, run `npx @revyl/verify init --platform mac`; it generates a command and file-round-trip script with no app id or agent steps. Mac computers are early access and not yet available in Revyl production. They work only on Revyl staging for enabled organizations using the optional `REVYL_BACKEND_URL` override and matching credentials. Linux targets are typed but `open()` rejects them with `NOT_AVAILABLE_ON_PLATFORM` before credentials or network access. See [computers](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#availability-and-errors) and the [Linux contract](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/linux-computers-contract.md).
+```ts
+import { open } from '@revyl/verify';
+const session = await open('ios');
+try {
+  await session.instruction('Open General, then About');
+  await session.validation('The screen shows the operating system version');
+} finally {
+  await session.close();
+}
+```
 
-## Docs
+For web, use `init --platform web` with a Revyl web app ID and public HTTPS URL. See [getting started](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/getting-started.md).
+
+### Go
+
+Inside a function returning `error`, with a bounded `ctx` and imports for `context`, `time`, and `verify "github.com/RevylAI/verify/go"`:
+
+```go
+session, err := verify.Open(ctx, verify.Target{Platform: verify.IOS, BundleID: "com.apple.Preferences"})
+if err != nil {
+    return err
+}
+defer func() {
+    cleanup, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+    _ = session.Close(cleanup)
+}()
+if _, err := session.Instruction(ctx, "Open General, then About"); err != nil {
+    return err
+}
+_, err = session.Validation(ctx, "The screen shows the operating system version")
+return err
+```
 
-- [Getting started](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/getting-started.md) and [API](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/api.md)
-- [Configuration and CLI](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/configuration.md)
-- [Web](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/web.md) and [iOS and Android](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/mobile.md)
-- [Mac computers](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md) and the [deferred Linux contract](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/linux-computers-contract.md)
-- [CI and test runners](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/ci.md) and [error codes](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/errors.md)
-- [For coding agents](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/agents.md)
+This sketch ignores cleanup errors; the [complete Go examples](https://github.com/RevylAI/verify/blob/v0.2.0/go/README.md) handle them. Go has no process-exit handlers. TypeScript's automatic cleanup is best effort, bounded to 15 seconds, and skips signal/error handlers that already have listeners. Always close explicitly: device close acknowledges a stop request; computer close requires terminal state and confirmed release.
 
-Examples: [web store](https://github.com/RevylAI/verify/tree/main/examples/web-store), [mobile settings](https://github.com/RevylAI/verify/tree/main/examples/mobile-settings), and [Mac workspace](https://github.com/RevylAI/verify/tree/main/examples/mac-workspace).
+### Platforms
 
-## How it works
+| Platform | Instructions / validations | Commands / files / processes | PNG screenshot | Availability |
+| --- | :---: | :---: | :---: | --- |
+| Web | Yes | — | Yes | Production; selected backend must support web steps |
+| iOS simulator | Yes | — | Yes | Production |
+| Android emulator | Yes | — | Yes | Production |
+| Mac computer | — | Yes | Yes | Staging-only early access; not in production |
+| Linux computer | — | Yes | Yes | Staging-only early access; not in production |
 
-Verify is a client for [Revyl's public API](https://docs.revyl.com). `open()` starts a device session (registering a web URL as a build first when needed) and waits until it is ready. Each instruction or validation runs as a live step on the session: Verify submits it, polls its status until Revyl reports a result, and cancels it on Revyl if it runs past its timeout. `close()` stops the session. Requests identify themselves with `X-Revyl-Client: verify` and a `revyl-verify/<version>` user agent.
+Computers require enablement for your organization and requested OS, plus approved `REVYL_BACKEND_URL`, matching `REVYL_APP_URL` and credentials. They have a hard 60-minute lifetime from create. Mac supports `init --platform mac`; Linux init is unavailable, so use `open({ platform: 'linux' })` or a config target. See [computers](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/computers.md).
 
-For computers, `open()` creates a computer run and waits for its report to become active. Commands use request UUIDs and async operation polling without resubmitting mutations; `close()` stops the run. See [the computer transport](https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#lifecycle-and-transport).
+## Documentation
 
-## Develop
+- [Documentation index](https://github.com/RevylAI/verify/tree/v0.2.0/packages/verify/docs/) · [API](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/api.md) · [CI](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/ci.md) · [Coding agents](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/agents.md)
+- [End-to-end results and limitations](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/end-to-end.md)
+- [Examples](https://github.com/RevylAI/verify/tree/v0.2.0/examples/): [Web store](https://github.com/RevylAI/verify/tree/v0.2.0/examples/web-store/) · [Mobile Settings](https://github.com/RevylAI/verify/tree/v0.2.0/examples/mobile-settings/) · [Mac workspace](https://github.com/RevylAI/verify/tree/v0.2.0/examples/mac-workspace/) · [Go](https://github.com/RevylAI/verify/blob/v0.2.0/go/README.md)
+- [Contributing](https://github.com/RevylAI/verify/blob/v0.2.0/CONTRIBUTING.md) · [Security](https://github.com/RevylAI/verify/blob/v0.2.0/SECURITY.md) · [Releasing](https://github.com/RevylAI/verify/blob/v0.2.0/RELEASING.md)
 
-```bash
-npm install
-npm run build
-npm test          # unit tests against a mocked Revyl API; no account needed
-npm run typecheck
-```
+## Troubleshooting
 
-The library lives in [`packages/verify`](https://github.com/RevylAI/verify/tree/main/packages/verify) and the examples in [`examples/`](https://github.com/RevylAI/verify/tree/main/examples). Read [Contributing](https://github.com/RevylAI/verify/blob/main/CONTRIBUTING.md), [Security](https://github.com/RevylAI/verify/blob/main/SECURITY.md), and [Releasing](https://github.com/RevylAI/verify/blob/main/RELEASING.md) before changing or publishing the package.
+- **`NOT_AVAILABLE_ON_PLATFORM`:** computer agent steps and device command/file methods are unavailable. Computers also need staging enablement; web steps need backend support. Check the [platform contract](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/errors.md).
+- **`COMPUTER_LIMIT`:** admission was refused because of queued work or a concurrency limit. Wait for capacity; Verify does not retry creation or stop a definitely refused start.
+- **Blank first screen:** mobile startup makes a bounded, best-effort blank-frame observation, not a rendered/foreground-readiness guarantee. Begin with an instruction that reaches the screen you need. Computer capture retries structured startup screen-not-ready responses for a fixed 30-second window; Linux screenshot retry is tests-only, not proven live.
+- **A report's counters look successful but validation failed:** inspect `effective_status`, `validation_result` and `validations_passed` against `total_validations`, not transport counts. Failed SDK validations throw by default. See [reading the verdict](https://github.com/RevylAI/verify/blob/v0.2.0/packages/verify/docs/end-to-end.md#reading-the-verdict).
 
 ## License
 
-[Apache 2.0](https://github.com/RevylAI/verify/blob/main/LICENSE)
+[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.2.0/LICENSE).

package/dist/api/types.d.ts

@@ -130,6 +130,12 @@ export interface ComputerReport {
     state: ComputerState;
     release: 'pending' | 'confirmed' | 'unknown';
     failure_reason?: string | null;
+    expires_at?: string | null;
+}
+export interface ComputerRecordingResponse {
+    url: string;
+    duration_seconds?: number | null;
+    started_at?: string | null;
 }
 export interface ComputerProcessHandle {
     computer_session_id: string;

package/dist/cli/init.js

@@ -8,7 +8,7 @@ const CONFIG_FILE = 'verify.config.ts';
 const EXAMPLE_SCRIPT = join('verify', 'example.ts');
 export function validateInitAnswers(answers) {
     if (!['web', 'ios', 'android', 'mac'].includes(answers.platform)) {
-        throw new VerifyError('INVALID_ARGUMENT', "--platform must be 'web', 'ios', 'android', or 'mac'. Linux computers are not available yet.");
+        throw new VerifyError('INVALID_ARGUMENT', "--platform must be 'web', 'ios', 'android', or 'mac'. Linux init is unavailable; use open({ platform: 'linux' }) or a Linux config target.");
     }
     if (answers.platform === 'mac' && answers.appId !== undefined) {
         throw new VerifyError('INVALID_ARGUMENT', '--app-id does not apply to Mac computers.');
@@ -101,8 +101,7 @@ try {
     const steps = platform === 'web'
         ? `await session.instruction('Follow the link on the page');
 await session.validation('A page about domains reserved for documentation is shown');`
-        : `// Describe what a person would do and see, for example:
-// await session.instruction('Sign in as the demo user and open Settings');
+        : `await session.instruction('Wait for the app to finish opening and show its first screen');
 await session.validation('The app has opened and shows its first screen without an error');`;
     return `import { open } from '${PACKAGE_NAME}';
 

package/dist/cli/main.js

@@ -6,18 +6,18 @@ import { missingCredentialsMessage, resolveCredentials } from '../auth.js';
 import { VerifyError, errorMessage, isVerifyError } from '../errors.js';
 import { PACKAGE_NAME, VERSION } from '../version.js';
 import { initProject, validateInitAnswers } from './init.js';
-const HELP = `verify ${VERSION}: open Revyl cloud browsers, devices, and Mac computers from your code
+const HELP = `verify ${VERSION}: open Revyl cloud browsers, devices, and computers from your code
 
 Usage
-  verify init [--platform web|ios|android|mac] [--app-id <id>] [--url <https-url>] [--force]
+  npx ${PACKAGE_NAME} init [--platform web|ios|android|mac] [--app-id <id>] [--url <https-url>] [--force]
       Write verify.config.ts and an example script, verify/example.ts
-  verify whoami
+  npx ${PACKAGE_NAME} whoami
       Check which Revyl account your credentials belong to
 
 Authentication
   REVYL_API_KEY, or a login from the Revyl CLI ('revyl auth login').
 
-Docs: https://github.com/RevylAI/verify/tree/main/packages/verify/docs
+Docs: https://github.com/RevylAI/verify/tree/v${VERSION}/packages/verify/docs
 `;
 const USAGE_CODES = new Set(['INVALID_ARGUMENT', 'AUTH_MISSING', 'AUTH_REJECTED']);
 export async function main(argv) {
@@ -70,7 +70,7 @@ async function initCommand(args) {
     const steps = [
         `npm install --save-dev ${PACKAGE_NAME}`,
         "Authenticate: export REVYL_API_KEY=<key from Revyl settings>, or run 'revyl auth login'",
-        ...(answers.platform === 'mac' ? ['Mac computers are not yet available in Revyl production. Early access works only on Revyl staging for enabled organizations; use the optional REVYL_BACKEND_URL override with staging credentials. Ask support@revyl.ai for access. See https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#availability-and-errors'] : []),
+        ...(answers.platform === 'mac' ? [`Mac computers are not yet available in Revyl production. Early access works only on Revyl staging for enabled organizations; use the optional REVYL_BACKEND_URL override with staging credentials. Ask support@revyl.ai for access. See https://github.com/RevylAI/verify/blob/v${VERSION}/packages/verify/docs/computers.md#availability-and-errors`] : []),
         ...(answers.platform === 'mac' || answers.appId ? [] : ['Put your Revyl app id in verify.config.ts (or set REVYL_APP_ID)']),
         'node verify/example.ts',
     ];

package/dist/computer-session.d.ts

@@ -1,19 +1,24 @@
 import { RevylClient } from './api/client.js';
+import type { ComputerPlatform } from './api/types.js';
 import type { ResolvedComputerTarget } from './config.js';
-import { type ComputerProcess, type ExecOptions, type ExecResult, type FileStat, type OperationOptions, type Session, type SessionOptions, type StepResult } from './session.js';
+import { type ComputerProcess, type ComputerRecording, type ExecOptions, type ExecResult, type FileStat, type OperationOptions, type Session, type SessionOptions, type StepResult } from './session.js';
 export declare class ComputerSession implements Session {
     private readonly client;
     private readonly options;
-    readonly platform: "mac";
+    readonly platform: ComputerPlatform;
     readonly target: string;
     readonly id: `${string}-${string}-${string}-${string}-${string}`;
     readonly viewerUrl: string;
     readonly steps: StepResult[];
     private readonly lifetime;
     private closePromise;
+    private expiresAtMs;
+    private screenReadyUntilMs;
     private constructor();
     static start(client: RevylClient, target: ResolvedComputerTarget, options: SessionOptions): Promise<ComputerSession>;
     get closed(): boolean;
+    get expiresAt(): Date | undefined;
+    recording(): Promise<ComputerRecording | null>;
     instruction(): Promise<never>;
     validation(): Promise<never>;
     screenshot(options?: {
@@ -31,6 +36,7 @@ export declare class ComputerSession implements Session {
     private request;
     private report;
     private assertOpen;
+    private observationSignal;
     private unavailable;
     private log;
 }

package/dist/computer-session.js

@@ -2,54 +2,62 @@ 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 { responseDetail, responseErrorCode, sessionViewerUrl } from './api/client.js';
 import { trackSession, untrackSession } from './cleanup.js';
 import { VerifyError, isVerifyError } from './errors.js';
 import { 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 not yet available in Revyl production. Early access works only on Revyl staging for enabled organizations and operating systems. See https://github.com/RevylAI/verify/blob/main/packages/verify/docs/computers.md#availability-and-errors';
+const COMPUTER_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';
+    platform;
     target;
     id = randomUUID();
     viewerUrl;
     steps = [];
     lifetime = new AbortController();
     closePromise;
+    expiresAtMs;
+    screenReadyUntilMs = 0;
     constructor(client, target, options) {
         this.client = client;
         this.options = options;
         this.target = target.name;
+        this.platform = target.platform;
         this.viewerUrl = sessionViewerUrl(this.id, 'computer');
     }
     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.report(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));
             }
+            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', 'NOT_AVAILABLE_ON_PLATFORM', 'INVALID_ARGUMENT', 'COMPUTER_LIMIT'].includes(error.code)) {
                 session.lifetime.abort();
                 untrackSession(session);
             }
@@ -57,13 +65,40 @@ 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;
     }
+    get expiresAt() {
+        return this.expiresAtMs === undefined ? undefined : new Date(this.expiresAtMs);
+    }
+    async recording() {
+        const signal = AbortSignal.timeout(30_000);
+        const report = this.report(await this.request('GET', '/report', undefined, signal));
+        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 +107,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);
@@ -152,7 +218,7 @@ export class ComputerSession {
             }
             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}`;
+                    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 +238,12 @@ 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);
         try {
             let response = await this.request('POST', '/operations', { computer_session_id: this.id, request_id: requestId, command }, 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 +292,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,10 +303,24 @@ export class ComputerSession {
         }
         if (response.status >= 200 && response.status < 300)
             return response;
+        if (suffix === '/recording' && response.status === 404 && responseErrorCode(response) === 'recording_unavailable')
+            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}`);
+        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}. Ask support@revyl.ai about staging organization enablement. See ${this.viewerUrl}`);
+        }
+        if (response.status === 429 && detail === 'computer_limit')
+            throw new VerifyError('COMPUTER_LIMIT', `${COMPUTER_CAPACITY} See ${this.viewerUrl}`);
         let code = 'API_ERROR';
         if (detail === 'run_closed')
             code = 'SESSION_ENDED';
@@ -250,7 +332,7 @@ export class ComputerSession {
             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';
@@ -265,14 +347,20 @@ export class ComputerSession {
         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.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}`);
@@ -312,6 +400,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,7 +46,7 @@ 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;