@revyl/verify 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.4.0 (2026-11-11)
+
+- Early access: run `instruction()` and `validation()` on your own model. `open('ios', { model: 'anthropic/claude-sonnet-5-5' })` runs every step on Claude with the key from `ANTHROPIC_API_KEY`; a step's `{ model }` overrides it. Built-in providers: Anthropic, OpenAI, Google, OpenRouter, Groq, Cerebras, xAI and Ollama, each reading its usual key variable; `anthropic/` and `openai/` also honour `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` for proxies and gateways. `{ id, baseURL, apiKey, headers }` reaches any OpenAI-compatible endpoint, with the key taken only from `apiKey`. Your model names elements and Revyl's grounding model finds them. `StepResult.model` reports turns and tokens. Revyl's agent remains the default.
+- Custom agents: `localAgent({ model, grounding, maxTurns, modelTimeout })` with the exported `anthropic()` and `openaiCompatible()` adapters, or your own `ModelAdapter`, passed as `{ agent }`.
+- New errors `MODEL_KEY_MISSING` (thrown before any session starts) and `MODEL_ERROR`, whose messages name the next step for a rejected key, an unknown model, a rate limit, or a model without image input or tool calls.
+- Early access: exact device actions on Web, iOS and Android: `tap`, `type`, `swipe`, `pressKey`, `back` (Web and Android), `openUrl`, `launchApp` (iOS and Android), `locate` and `screenSize`, by device coordinates or a described target. A call a platform doesn't support throws `NOT_AVAILABLE_ON_PLATFORM` naming the alternative. `swipe` directions are finger motion on every platform, so `'up'` scrolls content down; on Web, Verify sends Revyl the matching page direction.
+- Fix healthy sessions failing with `SESSION_ENDED` right after a step was accepted. Revyl can answer the first `step_status` polls with 404 "Live step not found" while it is still listing the step's run; Verify now keeps polling for about 10 seconds. If the step still can't be found, it raises `STEP_FAILED` naming the step and leaves the session open, because the step may still be running. Other 404s still raise `SESSION_ENDED`.
+- `npx @revyl/verify init` writes an example that runs on a brand-new account. When you leave the app id empty for iOS or Android, the config targets the device's built-in Settings app by bundle id (`com.apple.Preferences` or `com.android.settings`), and the example opens About and checks the operating system version. It no longer writes a placeholder app id that failed with `CONFIG_INVALID`, and the generated config no longer reads `REVYL_APP_ID`.
+- `init` asks iOS first and defaults to it instead of web.
+- A Web target needs a Web app id: `init` with web and no `--app-id` writes no files, explains how to create the Web app in the dashboard or with `revyl app create --platform web`, and prints the `init` command to run next.
+- `init`'s "Next" list names only commands that can pass: `node verify/example.mts`, and for Mac only once your organization has access.
+- `init` writes the example as `verify/example.mts`, so `node verify/example.mts` runs as an ES module whether `package.json` says `"type": "commonjs"` (what `npm init -y` writes on npm 11), `"type": "module"`, or nothing. As `verify/example.ts` it failed with `Cannot use import statement outside a module` in a CommonJS project.
+- `init --help` prints init's options instead of `Unknown option '--help'`.
+- Add `verify login`, which signs in through the browser, and `verify logout`, which removes `~/.revyl/credentials.json`, so you don't need the Revyl CLI for either. `verify --help` explains that `init`, `login` and the first `open()` sign you in through the browser.
+- Sign-in and missing-credential errors point to `npx @revyl/verify login` instead of the separately installed Revyl CLI.
+- Classify the hosted refusal `computer_platform_at_capacity` (the computer already runs as many children of that platform as it can, such as a second Web child on a Mac) as `COMPUTER_LIMIT` with that `reason`. Earlier versions report it as `SESSION_BUSY`.
+- Map Web runtime target errors on HTTP 409 (`target_not_found`, `stale_target` and similar) to `ACTION_FAILED` instead of `SESSION_BUSY`.
+- Docs: a new "Use your own model" guide (`docs/own-model.md` in the package), exact-action sections with runnable scripts in the web and mobile guides, and the `examples/byo-model` project.
+- Docs: a computer's lifetime is two hours from create, not 60 minutes; `expiresAt` / `expires_at` is the authoritative deadline.
+- Docs: the Web page explains how to create the Web app, starting with the dashboard, and drops the note about Revyl turning Web off. Getting started describes the new `init` and how the Python and Go SDKs sign in. The Go README has a runnable iOS Settings example.
+- Docs: Linux computers are no longer offered in the README, the package docs or the examples, and the README drops its Security and Telemetry sections (SECURITY.md is unchanged). `platform: 'linux'` still works; nothing is deprecated.
+
+## Go 0.3.0 (2026-11-11)
+
+Published as the `go/v0.3.0` tag.
+
+- Early access: run `Instruction` and `Validation` on your own model, as in TypeScript 0.4.0. `verify.WithModel("anthropic/claude-sonnet-5-5")` on `Open` or on one step reads the provider's usual key variable. The eight providers, `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` with or without `/v1`, and `verify.WithCustomModel(verify.CustomModel{...})` for any OpenAI-compatible endpoint. `StepResult.Model` reports turns and tokens, cached input included.
+- Custom agents: `verify.WithAgent(verify.LocalAgent{...})` with `verify.Anthropic` and `verify.OpenAICompatible`, or your own `ModelAdapter`.
+- New errors `ErrModelKeyMissing` (returned before any Revyl request) and `ErrModelError`, with the same next-step hints as TypeScript.
+- Early access: exact device actions on Web, iOS and Android: `Tap`, `Type`, `Swipe`, `PressKey`, `Back` (Web and Android), `OpenURL`, `LaunchApp` (iOS and Android), `Locate` and `ScreenSize`, by `verify.Point` or `verify.Element("...")`. They take a `context.Context`, and one cut off by its deadline returns `ErrActionUncertain`. `Swipe` directions are finger motion on every platform, so `SwipeUp` scrolls content down; on Web, Verify sends Revyl the matching page direction.
+- `Open`, `Instruction` and `Validation` now take option values (`OpenOption`, `StepOption`, `ValidationOption`). Existing `OpenOptions{...}`, `StepOptions{...}` and `ValidationOptions{...}` literals still compile; a call that spread a `[]OpenOptions`, `[]StepOptions` or `[]ValidationOptions` slice with `...` must pass the options one by one.
+- Map Web runtime target errors on HTTP 409 (`target_not_found`, `stale_target` and similar) to `ErrActionFailed` instead of `ErrSessionBusy`.
+- Same fix as 0.4.0: a `step_status` 404 "Live step not found" right after a step was accepted is retried for about 10 seconds and then returns `ErrStepFailed`, instead of `ErrSessionEnded`. The session stays open.
+- Classify the hosted refusal `computer_platform_at_capacity` as `ErrComputerLimit` with that reason, like 0.4.0.
+- Computer refusals name the Go methods and point to `Exec` instead of `exec()`, and `Navigate` on a computer is refused that way instead of suggesting `OpenURL`.
+- README: a runnable iOS Settings quick start, how the Go SDK uses a login saved by the other SDKs, a computer's two-hour lifetime, and Linux computers are no longer offered (`verify.Linux` still works).
+
+## Python 0.2.0 (2026-11-11)
+
+- Early access: run `instruction()` and `validation()` on your own model, as in TypeScript 0.4.0. `open(target, model="anthropic/claude-sonnet-5-5")` runs every step on it with the key from the provider's usual variable, and a step's `model=` overrides it. The eight providers, `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` with or without `/v1`, and `CustomModel(id, base_url, api_key, headers, provider, grounding)` for any OpenAI-compatible endpoint. Works on the sync and asyncio APIs. `StepResult.model` reports turns and tokens, cached input included.
+- Custom agents: `local_agent(model, grounding=, max_turns=, model_timeout=, max_image_side=)` with `anthropic()` and `openai_compatible()`, or your own `ModelAdapter`, passed as `agent=`.
+- New error codes `MODEL_KEY_MISSING` (raised before any Revyl request) and `MODEL_ERROR`, with the same next-step hints as TypeScript.
+- Early access: exact device actions on Web, iOS and Android, on `Session` and `AsyncSession`: `tap`, `type`, `swipe`, `press_key`, `back` (Web and Android), `open_url`, `launch_app` (iOS and Android), `locate` and `screen_size`, by `Point(x, y)` or a described target. `swipe` directions are finger motion on every platform, so `"up"` scrolls content down; on Web, Verify sends Revyl the matching page direction.
+- Map Web runtime target errors on HTTP 409 (`target_not_found`, `stale_target` and similar) to `ACTION_FAILED` instead of `SESSION_BUSY`.
+- Same fix as 0.4.0: a `step_status` 404 "Live step not found" right after a step was accepted is retried for about 10 seconds and then raises `STEP_FAILED`, instead of `SESSION_ENDED`. The session stays open.
+- Classify the hosted refusal `computer_platform_at_capacity` as `COMPUTER_LIMIT` with that `reason`, like 0.4.0.
+- `navigate()` on a computer raises `NOT_AVAILABLE_ON_PLATFORM` pointing to `exec()` and file operations, like the other device calls, instead of suggesting `open_url()`.
+- Print progress to stderr by default, like TypeScript: `[verify] <platform>: …` lines with the session link as soon as it is known, `ready`, and each instruction or validation's outcome and duration. Step text is not printed. Pass `log=False` to turn the lines off, or `log=callback` to receive them. An explicit `log=None` now means the default.
+- README: a computer's two-hour lifetime, and Linux computers are no longer offered (`Target(platform="linux")` still works).
+
+## 0.3.2 (2026-11-11)
+
+- Fix `npx @revyl/verify init` in pnpm projects: it now runs `pnpm add -D`. pnpm 9 and 10 rejected `--dev`, and pnpm 12 read it as "install only devDependencies", saved Verify under `dependencies` without installing it, and removed the project's other dependencies from `node_modules`.
+- Fix `init` in Yarn projects: Yarn 3 and 4 get `--mode=skip-build` (the old `skip-builds` was rejected), Yarn 1 gets `--ignore-scripts`, and Yarn 2 gets a plain `add --dev`.
+- `init` passes your environment to the package manager, so Corepack, proxy, registry and npm configuration variables reach the install.
+- Add a `default` condition to the package exports of `@revyl/verify` and `revyl-verify`, so `verify.config.ts` loads in Yarn Plug'n'Play projects and CommonJS `require('@revyl/verify')` resolves through Node.js require(esm) on Node.js 22.12 and later.
+- The `verify` CLI exits with `Verify needs Node.js 22.18 or later` on older Node.js instead of running `init` and writing a script that Node cannot load.
+
+## Python 0.1.0 (2026-11-06)
+
+First PyPI release of `revyl-verify` (import `revyl_verify`, Python ≥3.10), published from the `py/v0.1.0` tag with PyPI trusted publishing and attestations.
+
+- Includes the Python surface described under 0.3.0 below: typed sync and asyncio sessions, `bundle_id` mobile targets, web and mobile instructions and validations, screenshots, encoded (`argv_b64`/`path_b64`) computer operations, hosted child sessions, `attach()` and `current_computer()`.
+- Sign in automatically on the first interactive `open()`, `attach()` or `current_computer()` call through the Revyl browser approval flow, saving the login to `~/.revyl/credentials.json` for the Revyl CLI and other SDKs. Non-interactive runs and `CI` stay key-only and never open a browser.
+- Verified live on production: the iOS Settings quickstart (`bundle_id="com.apple.Preferences"`) through a first-run browser sign-in, and a Mac `exec`/file round trip, from the built wheel in a clean virtual environment.
+
 ## 0.3.1 (2026-11-03)
 
 - Docs: runnable `.mts` quickstart uses the built-in iOS Settings app, explains how to target an uploaded app with `appId`, clarifies that the Python SDK is not published to PyPI yet, and documents Web availability requirements.

package/README.md

@@ -1,16 +1,8 @@
 # Verify
 
-Verify runs end-to-end checks in a real browser, iOS simulator, or Android emulator on Revyl. You describe what the agent should do and what must be true afterward, instead of maintaining selectors and coordinates that break when a screen changes. Use it from a script, a coding agent, or the test runner you already have. Mac and Linux computers are also available for commands, files, and screenshots, not natural-language steps.
+![Terminal output from one Verify script beside a Mac computer's Terminal window showing the macOS version, and the screens the script reached in a cloud browser, an Android emulator, and an iOS simulator](https://raw.githubusercontent.com/RevylAI/verify/v0.4.0/docs/images/verify-hero.webp)
 
-Every run gives you a link to watch the target. The session keeps its report and available recording, and the SDK keeps instruction and validation results in order. A failed check leaves evidence you can inspect.
-
-## Install and run
-
-```bash
-npm install @revyl/verify
-```
-
-Save this as `verify/check.mts`:
+Verify runs end-to-end checks in a cloud browser, iOS simulator, or Android emulator on Revyl. You write what the agent should do and what must be true afterward, in plain sentences, and call it from a script, a coding agent, CI, or the test runner you already use. When you know exactly what to press, you can tap, type and swipe yourself instead. Verify also opens Mac computers for commands, files, and screenshots.
 
 ```ts
 import { open } from '@revyl/verify';
@@ -25,148 +17,106 @@ try {
 }
 ```
 
-Use `appId` when you want to target your own uploaded app.
-
-Run the script:
-
-```bash
-node verify/check.mts
-```
+You maintain sentences instead of selectors and coordinates that break when a screen changes, and every run prints a session link that keeps the report and available recording after the session closes.
 
-On the first interactive run, Verify opens the Revyl browser approval flow once and saves the login in `~/.revyl/credentials.json` for the CLI and SDK to share.
+## Quick start
 
-Verify prints a live session URL and progress like this:
+Paste this prompt into your coding agent, and it sets up Verify in the project's language:
 
 ```text
-[verify] ios: starting ios session https://app.revyl.ai/sessions/…
-[verify] ios: ready
-[verify] ios: ✓ instruction "Open General, then About" (12.0s)
-[verify] ios: ✓ validation "The screen shows the operating system version" (9.8s)
-[verify] ios: closed
-```
+Set up Verify in this project.
+
+Read https://docs.revyl.com/verify.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.
 
-The URL is live during the run and keeps the report and available recording after it closes. A failed instruction or validation throws a typed error and includes the same URL. In CI, Verify never opens a browser: provide `REVYL_API_KEY` as a secret.
+Use the SDK for this project's language: @revyl/verify on Node.js 22.18 or later for Node.js or TypeScript, revyl-verify on Python 3.10 or later for Python (install it with pip or uv), or the github.com/RevylAI/verify/go module for Go. Write the iOS Settings example in that language: open the com.apple.Preferences bundle, run one instruction, and run one validation that checks the operating system version. Ask before starting a paid cloud session, then run the example.
 
-For Web, use `open({ platform: 'web', app: { appId, url } })`; for a computer, use `open({ platform: 'mac' })`. Web targets need Web enabled for your organization; new self-serve organizations don't have it yet. `revyl app create --platform web` reports `Web is not enabled for this organization`; contact Revyl to enable it.
+You're done when the example has opened iOS Settings, the operating system version validation has passed, and the session has closed.
 
-## Scaffold a config (optional)
+Ask me before anything that needs my login or approval.
+```
 
-Use `init` when you want named targets in `verify.config.ts` and a generated `verify/example.ts` script:
+Or set it up yourself:
 
 ```bash
 npx @revyl/verify init
 ```
 
-`init` detects your package manager, asks before adding `@revyl/verify` as a dev dependency, creates `verify.config.ts` and `verify/example.ts`, and prints the command that runs the example. Use `--yes` to accept installation without a prompt, or `--no-install` when Verify is already installed. It is optional; installing the package is enough to use inline targets.
+`init` adds Verify to your project, asks what to open, writes `verify.config.ts` and an example script, signs you in through the browser on the first interactive run, and prints the command that runs the example. With no app id, the iOS and Android examples open the built-in Settings app, so they run on a new account before you upload anything. To skip the config, run `npm install @revyl/verify` and save the example above as `verify/check.mts`, then run `node verify/check.mts`. [Getting started](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/getting-started.md) covers sign-in, your own app, and [CI](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/ci.md).
 
-The generated project starts with a named target. Use `--platform web`, `--platform ios`, `--platform android`, or `--platform mac` when you want to skip the platform question. Web and mobile targets need a Revyl app id; a Mac target does not. The generated config is ordinary TypeScript, so edit it when the example needs a pinned build, a public Web URL, or a different target.
+For finished projects, see [`examples/`](https://github.com/RevylAI/verify/tree/v0.4.0/examples/): a [web store](https://github.com/RevylAI/verify/tree/v0.4.0/examples/web-store/), [mobile Settings](https://github.com/RevylAI/verify/tree/v0.4.0/examples/mobile-settings/), a [Mac workspace](https://github.com/RevylAI/verify/tree/v0.4.0/examples/mac-workspace/), a small [agent platform](https://github.com/RevylAI/verify/tree/v0.4.0/examples/agent-platform/) that runs web and iOS side by side, and [your own model](https://github.com/RevylAI/verify/tree/v0.4.0/examples/byo-model/) (with [Python](https://github.com/RevylAI/verify/blob/v0.4.0/python/examples/byo_model.py) and [Go](https://github.com/RevylAI/verify/blob/v0.4.0/go/examples/byomodel/main.go) versions).
 
-See the [TypeScript getting-started guide](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/getting-started.md), the [Python SDK guide](https://github.com/RevylAI/verify/blob/v0.3.1/python/README.md), and the [Go SDK guide](https://github.com/RevylAI/verify/tree/go/v0.2.0/go).
+## Exact actions
 
-## CI
+Tap, type, swipe and press keys yourself, by a description Revyl locates on screen or by coordinates, in the same script as your steps:
 
-For a normal GitHub Actions job, install from the lockfile with `npm ci` and pass `REVYL_API_KEY` from repository secrets to the script that runs Verify:
-
-```yaml
-- uses: actions/checkout@v5
-- uses: actions/setup-node@v5
-  with:
-    node-version: 24
-    cache: npm
-- run: npm ci
-- run: node verify/example.ts
-  env:
-    REVYL_API_KEY: ${{ secrets.REVYL_API_KEY }}
+```ts
+await session.type({ target: 'Email field' }, 'demo@example.com');   // Revyl finds the element you describe
+await session.pressKey('enter');
+await session.swipe('up');                                            // scrolls the content down
+await session.tap({ x: 196, y: 640 });                                // or device coordinates
+await session.instruction('Accept the terms if they are shown');      // the agent where it's fuzzy
+await session.validation('The welcome screen is shown');
 ```
 
-On a `revyl-macos` job, `currentComputer()` attaches to the runner's existing computer without taking ownership. The runner releases the computer; closing the Verify attachment still cleans up hosted children. See the [CI guide](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/ci.md) and [computer API](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/api.md#inside-a-revyl-macos-github-actions-job).
-
-## Reference authentication
-
-Use manual setup when you need to control the package manager or keep the generated files out of the project:
-
-```bash
-revyl auth login
-npx @revyl/verify whoami
-```
+`back`, `openUrl`, `launchApp`, `locate` and `screenSize` round them out; [which call works where](#which-call-works-where) shows the platform limits. Early access. In TypeScript (`@revyl/verify` 0.4.0), Python (`revyl-verify` 0.2.0) and Go (v0.3.0); the [Python](https://github.com/RevylAI/verify/blob/v0.4.0/python/README.md#exact-actions) and [Go](https://github.com/RevylAI/verify/blob/v0.4.0/go/README.md#exact-actions) READMEs show them with each language's names. The [web](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/web.md#exact-actions) and [mobile](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/mobile.md#exact-actions) guides have runnable scripts, and [api.md](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/api.md#exact-actions) lists every call.
 
-The SDK resolves credentials in this order: a usable stored CLI login marked `local_auth_override`, `REVYL_API_KEY`, then another usable stored CLI login. In CI, use a secret manager rather than putting a key in source, command arguments, or logs. `whoami` checks the credentials without starting a session.
+## Your own model
 
-## TypeScript
+Steps run on Revyl's agent unless you pass a model. Then the agent loop runs on your machine with your key, and Revyl provides the device and finds the elements your model names:
 
 ```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();
-}
-```
-
-For Web, use a public HTTPS URL in the target config. For iOS and Android, point the target at an app or build in Revyl. The [API guide](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/api.md) covers target options, step results, screenshots, reports, and cleanup.
-
-## Go
+const session = await open('ios', { model: 'anthropic/claude-sonnet-5-5' });       // key from ANTHROPIC_API_KEY
+await session.instruction('Open General, then About');
+await session.instruction('Open Privacy', { model: 'openai/gpt-5.5' });              // or per step
 
-Inside a function returning `error`, with a bounded `ctx`:
-
-```go
-session, err := verify.Open(ctx, verify.Target{Platform: verify.IOS, BundleID: "com.apple.Preferences"})
-if err != nil {
-    return err
-}
-defer func() { _ = session.Close(ctx) }()
-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
+await open('ios', { model: { id: 'qwen-3.8-27b', baseURL: 'https://api.cerebras.ai/v1', apiKey: process.env.CEREBRAS_API_KEY } });
 ```
 
-Go calls return errors instead of throwing. The [Go reference](https://github.com/RevylAI/verify/tree/go/v0.2.0/go) covers context deadlines, screenshots, computer operations, and hosted sessions.
+In TypeScript (`@revyl/verify` 0.4.0), Python (`revyl-verify` 0.2.0) and Go (v0.3.0); the [Python](https://github.com/RevylAI/verify/blob/v0.4.0/python/README.md#your-own-model) and [Go](https://github.com/RevylAI/verify/blob/v0.4.0/go/README.md#your-own-model) READMEs show them with each language's names. Built in: `anthropic`, `openai`, `google`, `openrouter`, `groq`, `cerebras`, `xai` and `ollama`; anything OpenAI-compatible works through `baseURL`. Early access; [Use your own model](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/own-model.md) covers the providers, picking a model, what Revyl still sees, limits and troubleshooting.
 
-## Python
+## Packages
 
-The Python SDK isn't published to PyPI yet; install it from source using the instructions in the [Python SDK guide](https://github.com/RevylAI/verify/blob/v0.3.1/python/README.md).
+| Package | Install | Status |
+| --- | --- | --- |
+| [`@revyl/verify`](https://www.npmjs.com/package/@revyl/verify) | `npm install @revyl/verify` | TypeScript SDK and the `verify` CLI (`init`, `login`, `logout`, `whoami`). Published on npm, Node.js 22.18 or later. |
+| [`revyl-verify`](https://www.npmjs.com/package/revyl-verify) (npm) | `npm install revyl-verify` | Alias of `@revyl/verify` at the same version. |
+| [Go module](https://github.com/RevylAI/verify/tree/go/v0.3.0/go) | `go get github.com/RevylAI/verify/go@v0.3.0` | Published as the `go/v0.3.0` tag, Go 1.26.9 or later. Calls return errors instead of throwing. |
+| [`revyl-verify`](https://pypi.org/project/revyl-verify/) (PyPI) | `pip install revyl-verify` or `uv add revyl-verify` | Python SDK, published on PyPI. Python 3.10 or later, sync and asyncio APIs, no CLI; see the [Python guide](https://github.com/RevylAI/verify/blob/v0.4.0/python/README.md). |
 
-```python
-from revyl_verify import Target, open
+## Platforms
 
-with open(Target(platform="ios", bundle_id="com.apple.Preferences")) as session:
-    session.instruction("Open General, then About")
-    session.validation("The screen shows the operating system version")
-```
+| Platform | Instructions / validations | Exact actions | Commands / files / processes | PNG screenshot |
+| --- | :---: | :---: | :---: | :---: |
+| Web | Yes | Yes | — | Yes |
+| iOS simulator | Yes | Yes | — | Yes |
+| Android emulator | Yes | Yes | — | Yes |
+| Mac computer | — | — | Yes | Yes |
 
-Python supports synchronous and asyncio APIs, but it has no bundled CLI. The [Python reference](https://github.com/RevylAI/verify/blob/v0.3.1/python/README.md) covers both APIs and computer operations.
+### Which call works where
 
-## Platforms
+| Call | Web | iOS | Android | Mac computer |
+| --- | --- | --- | --- | --- |
+| `tap`, `type`, `swipe`, `pressKey`, `locate`, `screenSize` | Yes | Yes | Yes | No, use `exec()` and files |
+| `back()` | Yes, browser history | No, tap the on-screen back control | Yes, the system back button | No |
+| `openUrl(url)` | Yes, loads an http(s) URL in the tab | Yes, a URL or deep link | Yes, a URL or deep link | No |
+| `launchApp(bundleId)` | No, use `openUrl` or `navigate` | Yes | Yes | No |
+| `navigate(url)` | Yes | No, use `openUrl` | No, use `openUrl` | No |
+| `instruction`, `validation`, your own model | Yes | Yes | Yes | No, use `exec()` |
+| `screenshot()` | Yes | Yes | Yes | Yes |
+| `exec`, files, processes | No, open a Mac computer | No, open a Mac computer | No, open a Mac computer | Yes |
 
-| Platform | Instructions / validations | Commands / files / processes | PNG screenshot |
-| --- | :---: | :---: | :---: |
-| Web | Yes | — | Yes |
-| iOS simulator | Yes | — | Yes |
-| Android emulator | Yes | — | Yes |
-| Mac computer | — | Yes | Yes |
-| Linux computer | — | Yes | Yes |
+Coordinates are in iOS points, Android pixels and Web CSS pixels, from the top-left corner. A call a platform doesn't support throws `NOT_AVAILABLE_ON_PLATFORM`, and its message names the alternative.
 
-Computer targets are early access and use commands, files, processes, and screenshots rather than natural-language agent steps. They have a server-bounded lifetime. See [computer setup](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/computers.md).
+Web is available to every organization. Mac computers are early access and have a server-bounded lifetime; see [computers](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/computers.md).
 
 ## Documentation
 
-- [Documentation index](https://github.com/RevylAI/verify/tree/v0.3.1/packages/verify/docs/) · [API](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/api.md) · [CI](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/ci.md) · [Coding agents](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/agents.md)
-- [End-to-end results and limitations](https://github.com/RevylAI/verify/blob/v0.3.1/packages/verify/docs/end-to-end.md)
-- [Examples](https://github.com/RevylAI/verify/tree/v0.3.1/examples/): [Web store](https://github.com/RevylAI/verify/tree/v0.3.1/examples/web-store/) · [Mobile Settings](https://github.com/RevylAI/verify/tree/v0.3.1/examples/mobile-settings/) · [Mac workspace](https://github.com/RevylAI/verify/tree/v0.3.1/examples/mac-workspace/)
-- [Contributing](https://github.com/RevylAI/verify/blob/v0.3.1/CONTRIBUTING.md) · [Security](https://github.com/RevylAI/verify/blob/v0.3.1/SECURITY.md) · [Releasing](https://github.com/RevylAI/verify/blob/v0.3.1/RELEASING.md)
+The [documentation](https://github.com/RevylAI/verify/tree/v0.4.0/packages/verify/docs/) covers the [API](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/api.md), [configuration](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/configuration.md), [web](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/web.md), [mobile](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/mobile.md), [computers](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/computers.md), [CI](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/ci.md), [your own model](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/own-model.md), [errors and troubleshooting](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/errors.md), [coding agents](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/agents.md), and [live end-to-end results](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/end-to-end.md). The npm package ships these pages in `node_modules/@revyl/verify/docs/`, with an [llms.txt](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/llms.txt) index, so a coding agent can read the docs for the version you installed. The Revyl docs site has an overview at [docs.revyl.com/verify](https://docs.revyl.com/verify).
 
-## Troubleshooting
+## Status
 
-- **`NOT_AVAILABLE_ON_PLATFORM`:** the requested method is not available for that target. Computer targets do not run instruction or validation steps; Web and mobile targets do not expose computer commands or files.
-- **`COMPUTER_LIMIT`:** computer admission was refused because of queued work or a concurrency limit. Verify does not retry creation or stop a definitely refused start.
-- **Blank first screen:** mobile startup uses a bounded, best-effort blank-frame observation, not a rendered-readiness guarantee. Begin with an instruction that reaches the screen your workflow needs.
-- **A validation report looks successful but the assertion failed:** inspect each step's `effective_status` and `validation_result`, and compare `validations_passed` with `total_validations` rather than transport counters.
+Verify is at 0.x, so APIs can still change between minor releases; the [changelog](https://github.com/RevylAI/verify/blob/v0.4.0/CHANGELOG.md) records each release. Mac computers are early access. See [Contributing](https://github.com/RevylAI/verify/blob/v0.4.0/CONTRIBUTING.md) and [Releasing](https://github.com/RevylAI/verify/blob/v0.4.0/RELEASING.md) to work on Verify.
 
 ## License
 
-[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.3.1/LICENSE).
+[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.4.0/LICENSE).

package/dist/agent/image.d.ts

@@ -0,0 +1,7 @@
+export interface ModelImage {
+    png: Uint8Array;
+    width: number;
+    height: number;
+}
+/** Shrinks a PNG by the smallest whole factor that keeps its longer side within maxSide, averaging each block of pixels. */
+export declare function fitPng(bytes: Uint8Array, maxSide: number): ModelImage;

package/dist/agent/image.js

@@ -0,0 +1,29 @@
+import { PNG } from 'pngjs';
+/** Shrinks a PNG by the smallest whole factor that keeps its longer side within maxSide, averaging each block of pixels. */
+export function fitPng(bytes, maxSide) {
+    const source = PNG.sync.read(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+    const factor = Math.ceil(Math.max(source.width, source.height) / maxSide);
+    if (factor <= 1)
+        return { png: bytes, width: source.width, height: source.height };
+    const width = Math.floor(source.width / factor);
+    const height = Math.floor(source.height / factor);
+    const target = new PNG({ width, height });
+    const area = factor * factor;
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const sums = [0, 0, 0, 0];
+            for (let dy = 0; dy < factor; dy += 1) {
+                const row = (y * factor + dy) * source.width;
+                for (let dx = 0; dx < factor; dx += 1) {
+                    const offset = (row + x * factor + dx) * 4;
+                    for (let channel = 0; channel < 4; channel += 1)
+                        sums[channel] += source.data[offset + channel];
+                }
+            }
+            const out = (y * width + x) * 4;
+            for (let channel = 0; channel < 4; channel += 1)
+                target.data[out + channel] = Math.round(sums[channel] / area);
+        }
+    }
+    return { png: PNG.sync.write(target), width, height };
+}

package/dist/agent/loop.d.ts

@@ -0,0 +1,97 @@
+import type { ModelAdapter } from './model.js';
+/** A point in device units: iOS points, Android and Web pixels, from the top-left corner. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** An element described in words, which Revyl's grounding model locates on the current screen. */
+export interface Target {
+    target: string;
+}
+export type Location = Point | Target;
+export type SwipeDirection = 'up' | 'down' | 'left' | 'right';
+export type DeviceAction = {
+    kind: 'tap';
+    at: Location;
+} | {
+    kind: 'type';
+    at: Location;
+    text: string;
+    clear: boolean;
+} | {
+    kind: 'swipe';
+    direction: SwipeDirection;
+    from?: Location;
+} | {
+    kind: 'key';
+    key: 'enter' | 'backspace';
+} | {
+    kind: 'back';
+} | {
+    kind: 'open_url';
+    url: string;
+};
+/** What the agent loop needs from a session. DeviceSession provides it. */
+export interface AgentControls {
+    readonly platform: 'ios' | 'android' | 'web';
+    capture(signal: AbortSignal): Promise<{
+        png: Uint8Array;
+        screenToken?: string;
+    }>;
+    screenSize(signal: AbortSignal): Promise<{
+        width: number;
+        height: number;
+    }>;
+    perform(action: DeviceAction, screenToken: string | undefined, signal: AbortSignal): Promise<Point | undefined>;
+}
+/**
+ * model: the model gives screenshot coordinates, and only device actions reach Revyl.
+ * revyl: the model names the element and Revyl's grounding model finds it, so element descriptions reach Revyl too.
+ */
+export type Grounding = 'model' | 'revyl';
+export interface LocalAgentOptions {
+    model: ModelAdapter;
+    /** Defaults to 'revyl'. */
+    grounding?: Grounding;
+    /** Model turns an instruction may take, each ending in one action. Defaults to 20, at most 100. */
+    maxTurns?: number;
+    /** Milliseconds one model call may take, retries included. Defaults to 60000. */
+    modelTimeout?: number;
+    /** The longest screenshot side sent to the model, in pixels. Defaults to 1280. */
+    maxImageSide?: number;
+}
+export interface LocalAgent {
+    readonly model: ModelAdapter;
+    readonly grounding: Grounding;
+    readonly maxTurns: number;
+    readonly modelTimeout: number;
+    readonly maxImageSide: number;
+}
+/** One model turn of a local step. */
+export interface ModelTurn {
+    /** The action the model chose, as text, such as 'tap "General"' or 'verdict true'. */
+    action: string;
+    /** Whether the action ran; a failed action is reported back to the model on its next turn. */
+    ok: boolean;
+    modelMs: number;
+    actionMs: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+/** How a step ran on your model instead of Revyl's agent. */
+export interface ModelRun {
+    /** The model's name, such as 'anthropic/claude-sonnet-5-5'. */
+    id: string;
+    grounding: Grounding;
+    turns: ModelTurn[];
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Runs instructions and validations on a model you choose, on your machine. Revyl only receives device actions. */
+export declare function localAgent(options: LocalAgentOptions): LocalAgent;
+/** Runs one instruction or validation through the agent's model. The caller enforces the step deadline through signal. */
+export declare function runLocalStep(type: 'instruction' | 'validation', task: string, agent: LocalAgent, controls: AgentControls, signal: AbortSignal, log: (line: string) => void): Promise<{
+    passed: boolean;
+    reason?: string;
+    run: ModelRun;
+}>;