@revyl/verify 0.3.2 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.4.1 (unreleased)
+
+- **Breaking for iOS exact actions (early access):** coordinates are now screenshot pixels on every platform. On iOS, `tap`, `type`, `swipe`'s `from`, `locate`, `screenSize` and the points `tap` and `type` return used the screen's points (440 × 956 on an iPhone whose screenshots are 1320 × 2868); they now use the screenshot's pixels, and Verify converts them to points for you. A script that passed iOS points must pass screenshot pixels instead: multiply by the screenshot's width over 0.4.0's `screenSize()` width (3 on that iPhone). Android and Web coordinates are unchanged, because their screenshots already match the screen.
+- A point outside the screenshot is refused with `INVALID_ARGUMENT` before any action is sent, and the message names the valid range. The first call in a session that takes or returns a point reads the screen size once (on iOS, plus one screenshot), and later calls reuse it. Before refusing a point, Verify reads the size again, so a rotated device or a resized Web viewport doesn't get a valid point refused. On Android and Web, if the size can't be read, the action is sent as in 0.4.0; on iOS the call fails, because the scale is needed. Calls by description send the same requests as 0.4.0 on Android and Web.
+- `locate()` keeps an off-screen match outside `screenSize()` instead of moving it to the edge, so you can tell it is off screen, and an action at it is refused.
+- `instruction()` and `validation()` on your own model are unchanged: the model still sees screenshots, and Verify still maps its answers to the device.
+- Docs: one coordinate rule in the same words for TypeScript, Python and Go, in the README, `api.md`, the web and mobile guides, `agents.md` and `llms.txt`. Web coordinates are screenshot pixels, which are CSS pixels at the default device scale factor of 1.
+
+## Go 0.3.1 (unreleased)
+
+Published as the `go/v0.3.1` tag.
+
+- **Breaking for iOS exact actions (early access):** coordinates are now screenshot pixels on every platform, as in TypeScript 0.4.1. On iOS, `Tap`, `Type`, `Swipe`'s `From`, `Locate`, `ScreenSize` and the points `Tap` and `Type` return used the screen's points; they now use the screenshot's pixels, and Verify converts them to points for you. Android and Web coordinates are unchanged.
+- A point outside the screenshot returns `ErrInvalidArgument` before any action is sent, naming the valid range, after Verify reads the size again in case the screen rotated. The screen size is read once per session. On Android and Web a failed size read skips the check and sends the action as before; on iOS it returns the error.
+- README: the same coordinate rule as TypeScript and Python.
+
+## Python 0.2.1 (unreleased)
+
+- **Breaking for iOS exact actions (early access):** coordinates are now screenshot pixels on every platform, as in TypeScript 0.4.1. On iOS, `tap`, `type`, `swipe`'s `from_`, `locate`, `screen_size` and the points `tap` and `type` return used the screen's points; they now use the screenshot's pixels, and Verify converts them to points for you. Android and Web coordinates are unchanged. `AsyncSession` behaves the same.
+- A point outside the screenshot raises `INVALID_ARGUMENT` before any action is sent, naming the valid range, after Verify reads the size again in case the screen rotated. The screen size is read once per session. On Android and Web a failed size read skips the check and sends the action as before; on iOS it raises.
+- README: the same coordinate rule as TypeScript and Go.
+
+## 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`.

package/README.md

@@ -1,8 +1,8 @@
 # Verify
 
-![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.3.2/docs/images/verify-hero.webp)
+![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.1/docs/images/verify-hero.webp)
 
-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. Verify also opens Mac and Linux computers for commands, files, and screenshots.
+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';
@@ -41,47 +41,84 @@ Or set it up yourself:
 npx @revyl/verify init
 ```
 
-`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. 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.3.2/packages/verify/docs/getting-started.md) covers sign-in, your own app, and [CI](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/ci.md).
+`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.1/packages/verify/docs/getting-started.md) covers sign-in, your own app, and [CI](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/ci.md).
 
-For finished projects, see [`examples/`](https://github.com/RevylAI/verify/tree/v0.3.2/examples/): a [web store](https://github.com/RevylAI/verify/tree/v0.3.2/examples/web-store/), [mobile Settings](https://github.com/RevylAI/verify/tree/v0.3.2/examples/mobile-settings/), a [Mac workspace](https://github.com/RevylAI/verify/tree/v0.3.2/examples/mac-workspace/), and a small [agent platform](https://github.com/RevylAI/verify/tree/v0.3.2/examples/agent-platform/) that runs web and iOS side by side.
+For finished projects, see [`examples/`](https://github.com/RevylAI/verify/tree/v0.4.1/examples/): a [web store](https://github.com/RevylAI/verify/tree/v0.4.1/examples/web-store/), [mobile Settings](https://github.com/RevylAI/verify/tree/v0.4.1/examples/mobile-settings/), a [Mac workspace](https://github.com/RevylAI/verify/tree/v0.4.1/examples/mac-workspace/), a small [agent platform](https://github.com/RevylAI/verify/tree/v0.4.1/examples/agent-platform/) that runs web and iOS side by side, and [your own model](https://github.com/RevylAI/verify/tree/v0.4.1/examples/byo-model/) (with [Python](https://github.com/RevylAI/verify/blob/v0.4.1/python/examples/byo_model.py) and [Go](https://github.com/RevylAI/verify/blob/v0.4.1/go/examples/byomodel/main.go) versions).
+
+## Exact actions
+
+Tap, type, swipe and press keys yourself, by a description Revyl locates on screen or by coordinates, in the same script as your steps:
+
+```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 a point in screenshot pixels
+await session.instruction('Accept the terms if they are shown');      // the agent where it's fuzzy
+await session.validation('The welcome screen is shown');
+```
+
+`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.1/python/README.md#exact-actions) and [Go](https://github.com/RevylAI/verify/blob/v0.4.1/go/README.md#exact-actions) READMEs show them with each language's names. The [web](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/web.md#exact-actions) and [mobile](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/mobile.md#exact-actions) guides have runnable scripts, and [api.md](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/api.md#exact-actions) lists every call.
+
+## Your own model
+
+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
+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
+
+await open('ios', { model: { id: 'qwen-3.8-27b', baseURL: 'https://api.cerebras.ai/v1', apiKey: process.env.CEREBRAS_API_KEY } });
+```
+
+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.1/python/README.md#your-own-model) and [Go](https://github.com/RevylAI/verify/blob/v0.4.1/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.1/packages/verify/docs/own-model.md) covers the providers, picking a model, what Revyl still sees, limits and troubleshooting.
 
 ## Packages
 
 | Package | Install | Status |
 | --- | --- | --- |
-| [`@revyl/verify`](https://www.npmjs.com/package/@revyl/verify) | `npm install @revyl/verify` | TypeScript SDK and the `verify` CLI (`init`, `whoami`). Published on npm, Node.js 22.18 or later. |
+| [`@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.2.0/go) | `go get github.com/RevylAI/verify/go@v0.2.0` | Published as the `go/v0.2.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.3.2/python/README.md). |
+| [Go module](https://github.com/RevylAI/verify/tree/go/v0.3.1/go) | `go get github.com/RevylAI/verify/go@v0.3.1` | Published as the `go/v0.3.1` 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.1/python/README.md). |
 
 ## Platforms
 
-| 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 |
+| 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 |
 
-Web is available to every organization. Mac and Linux computers are early access and have a server-bounded lifetime; see [computers](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/computers.md).
+### Which call works where
 
-## Documentation
+| 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 |
 
-The [documentation](https://github.com/RevylAI/verify/tree/v0.3.2/packages/verify/docs/) covers the [API](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/api.md), [configuration](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/configuration.md), [web](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/web.md), [mobile](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/mobile.md), [computers](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/computers.md), [CI](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/ci.md), [errors and troubleshooting](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/errors.md), [coding agents](https://github.com/RevylAI/verify/blob/v0.3.2/packages/verify/docs/agents.md), and [live end-to-end results](https://github.com/RevylAI/verify/blob/v0.3.2/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.3.2/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).
+**Coordinates.** Prefer a description, such as `tap({ target: 'Sign in button' })`: Revyl finds the element on the current screen, and you never handle coordinates. Otherwise a point is `{ x, y }` in screenshot pixels on every platform: whole numbers from the top-left corner of the image `screenshot()` returns. So a position you read off a screenshot goes to `tap()`, `type()` and `swipe()` unchanged. `screenSize()` returns the screenshot's width and height, and `locate()` and the points `tap()` and `type()` return use the same pixels. A point outside the screenshot is refused with `INVALID_ARGUMENT` before any action is sent, and the message names the valid range. On iOS, Verify converts the pixels to the screen's points for you. On Web they equal CSS pixels at the default device scale factor of 1, and you still pass screenshot pixels at any other. This holds from TypeScript 0.4.1, Python 0.2.1 and Go v0.3.1; earlier versions took iOS points.
 
-## Security
+A call a platform doesn't support throws `NOT_AVAILABLE_ON_PLATFORM`, and its message names the alternative.
 
-Don't open a public issue for a vulnerability. Follow [SECURITY.md](https://github.com/RevylAI/verify/blob/v0.3.2/SECURITY.md) and email support@revyl.ai. Each session is a paid remote session that acts on your app, and step text is sent to Revyl and printed to stderr, so use test accounts and keep credentials and customer data out of steps.
+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.1/packages/verify/docs/computers.md).
 
-## Telemetry
+## Documentation
 
-Verify sends no usage telemetry of its own. Its requests to the Revyl API carry a `User-Agent` with the Verify and runtime versions and an `X-Revyl-Client: verify` header.
+The [documentation](https://github.com/RevylAI/verify/tree/v0.4.1/packages/verify/docs/) covers the [API](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/api.md), [configuration](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/configuration.md), [web](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/web.md), [mobile](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/mobile.md), [computers](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/computers.md), [CI](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/ci.md), [your own model](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/own-model.md), [errors and troubleshooting](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/errors.md), [coding agents](https://github.com/RevylAI/verify/blob/v0.4.1/packages/verify/docs/agents.md), and [live end-to-end results](https://github.com/RevylAI/verify/blob/v0.4.1/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.1/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).
 
 ## Status
 
-Verify is at 0.x, so APIs can still change between minor releases; the [changelog](https://github.com/RevylAI/verify/blob/v0.3.2/CHANGELOG.md) records each release. Mac and Linux computers are early access. See [Contributing](https://github.com/RevylAI/verify/blob/v0.3.2/CONTRIBUTING.md) and [Releasing](https://github.com/RevylAI/verify/blob/v0.3.2/RELEASING.md) to work on Verify.
+Verify is at 0.x, so APIs can still change between minor releases; the [changelog](https://github.com/RevylAI/verify/blob/v0.4.1/CHANGELOG.md) records each release. Mac computers are early access. See [Contributing](https://github.com/RevylAI/verify/blob/v0.4.1/CONTRIBUTING.md) and [Releasing](https://github.com/RevylAI/verify/blob/v0.4.1/RELEASING.md) to work on Verify.
 
 ## License
 
-[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.3.2/LICENSE).
+[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.4.1/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 screenshot 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;
+}>;

package/dist/agent/loop.js

@@ -0,0 +1,215 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { VerifyError, errorMessage, isVerifyError } from '../errors.js';
+import { fitPng } from './image.js';
+/** Runs instructions and validations on a model you choose, on your machine. Revyl only receives device actions. */
+export function localAgent(options) {
+    if (!options || typeof options.model?.complete !== 'function' || typeof options.model.name !== 'string') {
+        throw new VerifyError('INVALID_ARGUMENT', 'localAgent() needs a model adapter, such as anthropic() or openaiCompatible().');
+    }
+    const grounding = options.grounding ?? 'revyl';
+    if (grounding !== 'model' && grounding !== 'revyl')
+        throw new VerifyError('INVALID_ARGUMENT', "localAgent() grounding must be 'model' or 'revyl'.");
+    const maxTurns = bounded(options.maxTurns ?? 20, 1, 100, 'maxTurns');
+    const modelTimeout = bounded(options.modelTimeout ?? 60_000, 1_000, 600_000, 'modelTimeout');
+    const maxImageSide = bounded(options.maxImageSide ?? 1280, 256, 4096, 'maxImageSide');
+    return Object.freeze({ model: options.model, grounding, maxTurns, modelTimeout, maxImageSide });
+}
+const VALIDATION_ATTEMPTS = 3;
+const NO_TOOL_LIMIT = 3;
+const ABORTING_CODES = new Set(['SESSION_ENDED', 'SESSION_BUSY', 'AUTH_REJECTED', 'EDGE_BLOCKED', 'MODEL_ERROR', 'TIMEOUT', 'API_ERROR', 'ACTION_UNCERTAIN']);
+/** Runs one instruction or validation through the agent's model. The caller enforces the step deadline through signal. */
+export async function runLocalStep(type, task, agent, controls, signal, log) {
+    const run = { id: agent.model.name, grounding: agent.grounding, turns: [], inputTokens: 0, outputTokens: 0 };
+    const history = [];
+    const size = await controls.screenSize(signal);
+    const tools = type === 'validation' ? [VERDICT_TOOL] : instructionTools(controls.platform, agent.grounding);
+    const turns = type === 'validation' ? VALIDATION_ATTEMPTS : agent.maxTurns;
+    let turnsWithoutTool = 0;
+    for (let turn = 1; turn <= turns; turn += 1) {
+        signal.throwIfAborted();
+        const shot = await controls.capture(signal);
+        const image = fitPng(shot.png, agent.maxImageSide);
+        const modelStarted = Date.now();
+        const reply = await agent.model.complete({
+            system: type === 'validation' ? validationPrompt(controls.platform) : instructionPrompt(controls.platform, agent.grounding),
+            text: turnText(type, task, image, history),
+            image,
+            tools,
+        }, AbortSignal.any([signal, AbortSignal.timeout(agent.modelTimeout)]));
+        const record = { action: 'no tool call', ok: false, modelMs: Date.now() - modelStarted, actionMs: 0, inputTokens: reply.usage.inputTokens, outputTokens: reply.usage.outputTokens };
+        run.turns.push(record);
+        run.inputTokens += record.inputTokens;
+        run.outputTokens += record.outputTokens;
+        const call = reply.toolCall;
+        if (reply.truncated) {
+            throw new VerifyError('MODEL_ERROR', `${agent.model.name}'s reply was cut off at its output token cap ${call ? 'in the middle of a tool call, so Verify did not use it' : 'before it called a tool'}. Pass the model to localAgent() through an adapter with a higher maxTokens, such as anthropic({ model, maxTokens: 8192 }) or openaiCompatible({ model, baseURL, maxTokens: 8192 }).`);
+        }
+        if (!call) {
+            turnsWithoutTool += 1;
+            if (turnsWithoutTool === NO_TOOL_LIMIT) {
+                throw new VerifyError('MODEL_ERROR', `${agent.model.name} answered ${NO_TOOL_LIMIT} times in a row without calling a tool. Pick a model that supports tool calls.`);
+            }
+            history.push(`${turn}. You answered without calling a tool. Call exactly one tool.`);
+            log(`  · turn ${turn}: no tool call (${record.modelMs} ms)`);
+            continue;
+        }
+        turnsWithoutTool = 0;
+        if (!tools.some((tool) => tool.name === call.name)) {
+            record.action = call.name.slice(0, 40);
+            history.push(`${turn}. ${record.action}: failed: not one of the offered tools (${tools.map((tool) => tool.name).join(', ')}).`);
+            log(`  · turn ${turn}: ${record.action} is not an offered tool (${record.modelMs} ms)`);
+            continue;
+        }
+        if (call.name === 'done' || call.name === 'verdict') {
+            const passed = (call.name === 'done' ? call.arguments.success : call.arguments.passed) === true;
+            const reason = typeof call.arguments.reason === 'string' ? call.arguments.reason.slice(0, 1_000) : undefined;
+            record.action = `${call.name} ${passed}`;
+            record.ok = true;
+            log(`  · turn ${turn}: ${record.action} (${record.modelMs} ms)`);
+            return { passed, ...(reason ? { reason } : {}), run };
+        }
+        const actionStarted = Date.now();
+        try {
+            const action = toAction(call, controls.platform, agent.grounding, image, size);
+            record.action = describe(action);
+            const at = await controls.perform(action, shot.screenToken, signal);
+            record.ok = true;
+            history.push(`${turn}. ${record.action}${at ? ` at (${at.x}, ${at.y})` : ''}: done.`);
+        }
+        catch (error) {
+            if (isVerifyError(error) && ABORTING_CODES.has(error.code))
+                throw error;
+            if (record.action === 'no tool call')
+                record.action = call.name;
+            history.push(`${turn}. ${record.action}: failed: ${errorMessage(error).slice(0, 300)}`);
+        }
+        record.actionMs = Date.now() - actionStarted;
+        log(`  · turn ${turn}: ${record.action}${record.ok ? '' : ' (failed)'} (model ${record.modelMs} ms, action ${record.actionMs} ms)`);
+        await delay(controls.platform === 'web' ? 500 : 1_000, undefined, { signal });
+    }
+    if (type === 'validation')
+        throw new VerifyError('STEP_FAILED', `${agent.model.name} gave no verdict in ${turns} attempts.`);
+    return { passed: false, reason: `${agent.model.name} did not finish within ${turns} turns.`, run };
+}
+function toAction(call, platform, grounding, image, size) {
+    const args = call.arguments;
+    const location = (required) => {
+        if (grounding === 'revyl') {
+            if (typeof args.target === 'string' && args.target.trim())
+                return { target: args.target.trim().slice(0, 500) };
+            if (required)
+                throw new VerifyError('INVALID_ARGUMENT', 'target is required: describe the element by its visible text or appearance.');
+            return undefined;
+        }
+        if (typeof args.x !== 'number' || typeof args.y !== 'number') {
+            if (required)
+                throw new VerifyError('INVALID_ARGUMENT', 'x and y are required.');
+            return undefined;
+        }
+        if (args.x < 0 || args.y < 0 || args.x >= image.width || args.y >= image.height) {
+            throw new VerifyError('INVALID_ARGUMENT', `(${args.x}, ${args.y}) is outside the ${image.width}x${image.height} screenshot.`);
+        }
+        return { x: Math.round((args.x * size.width) / image.width), y: Math.round((args.y * size.height) / image.height) };
+    };
+    switch (call.name) {
+        case 'tap':
+            return { kind: 'tap', at: location(true) };
+        case 'type':
+            if (typeof args.text !== 'string')
+                throw new VerifyError('INVALID_ARGUMENT', 'text is required.');
+            return { kind: 'type', at: location(true), text: args.text, clear: args.clear !== false };
+        case 'swipe': {
+            if (!['up', 'down', 'left', 'right'].includes(String(args.direction)))
+                throw new VerifyError('INVALID_ARGUMENT', 'direction must be up, down, left or right.');
+            const from = location(false);
+            return { kind: 'swipe', direction: args.direction, ...(from ? { from } : {}) };
+        }
+        case 'press_key':
+            if (args.key !== 'enter' && args.key !== 'backspace')
+                throw new VerifyError('INVALID_ARGUMENT', 'key must be enter or backspace.');
+            return { kind: 'key', key: args.key };
+        case 'back':
+            if (platform === 'ios')
+                throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'iOS has no back button; tap the on-screen back control.');
+            return { kind: 'back' };
+        case 'open_url':
+            if (typeof args.url !== 'string' || !args.url)
+                throw new VerifyError('INVALID_ARGUMENT', 'url is required.');
+            return { kind: 'open_url', url: args.url };
+        default:
+            throw new VerifyError('INVALID_ARGUMENT', `${call.name} is not a tool.`);
+    }
+}
+function describe(action) {
+    const where = (at) => (at === undefined ? '' : 'target' in at ? ` "${at.target}"` : ` (${at.x}, ${at.y})`);
+    switch (action.kind) {
+        case 'tap':
+            return `tap${where(action.at)}`;
+        case 'type':
+            return `type ${JSON.stringify(action.text.length > 40 ? `${action.text.slice(0, 40)}…` : action.text)} into${where(action.at)}`;
+        case 'swipe':
+            return `swipe ${action.direction}${action.from ? ` from${where(action.from)}` : ''}`;
+        case 'key':
+            return `press ${action.key}`;
+        case 'back':
+            return 'back';
+        case 'open_url':
+            return `open ${action.url}`;
+    }
+}
+const PLATFORM_LABEL = { ios: 'iPhone simulator', android: 'Android emulator', web: 'web browser' };
+function instructionPrompt(platform, grounding) {
+    return [
+        `You operate a ${PLATFORM_LABEL[platform]} to carry out a task. Every turn you see the current screenshot and the actions taken so far, and you call exactly one tool.`,
+        grounding === 'revyl'
+            ? 'To point at an element, describe it in target by its visible text or look, for example "General row" or "Search field". Do not give coordinates.'
+            : 'To point at an element, give the pixel coordinates of its center in the screenshot, x to the right and y down from the top-left corner.',
+        'Check the screenshot before each action: the previous action may not have done what you expected. To see content further down, swipe up.',
+        'Call done with success true as soon as the screenshot shows the task is complete. Call done with success false and a reason if it cannot be done.',
+    ].join('\n');
+}
+function validationPrompt(platform) {
+    return `You check whether a statement holds on the current screen of a ${PLATFORM_LABEL[platform]}. Judge only what the screenshot shows, then call verdict with passed and a one-sentence reason.`;
+}
+function turnText(type, task, image, history) {
+    const lines = [type === 'validation' ? `Statement: ${task}` : `Task: ${task}`, `The screenshot is ${image.width}x${image.height} pixels.`];
+    if (type === 'instruction')
+        lines.push(history.length ? `Actions so far:\n${history.slice(-30).join('\n')}` : 'No actions yet.');
+    else if (history.length)
+        lines.push(`Earlier attempts:\n${history.join('\n')}`);
+    return lines.join('\n');
+}
+const VERDICT_TOOL = {
+    name: 'verdict',
+    description: 'Report whether the statement holds on the screen.',
+    parameters: { type: 'object', properties: { passed: { type: 'boolean' }, reason: { type: 'string' } }, required: ['passed', 'reason'] },
+};
+function instructionTools(platform, grounding) {
+    const at = grounding === 'revyl'
+        ? { properties: { target: { type: 'string', description: 'The element, by its visible text or look.' } }, required: ['target'] }
+        : { properties: { x: { type: 'integer', description: 'Screenshot pixel x.' }, y: { type: 'integer', description: 'Screenshot pixel y.' } }, required: ['x', 'y'] };
+    const tools = [
+        { name: 'tap', description: 'Tap an element.', parameters: { type: 'object', ...at } },
+        {
+            name: 'type',
+            description: 'Tap a text field and type into it. Clears the field first unless clear is false.',
+            parameters: { type: 'object', properties: { ...at.properties, text: { type: 'string' }, clear: { type: 'boolean' } }, required: [...at.required, 'text'] },
+        },
+        {
+            name: 'swipe',
+            description: "Swipe from a point, or from the screen's center. up moves the finger up, which scrolls content down.",
+            parameters: { type: 'object', properties: { direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] }, ...at.properties }, required: ['direction'] },
+        },
+        { name: 'press_key', description: 'Press a key on the focused field.', parameters: { type: 'object', properties: { key: { type: 'string', enum: ['enter', 'backspace'] } }, required: ['key'] } },
+        { name: 'open_url', description: platform === 'web' ? 'Load a URL in the current tab.' : 'Open a URL or deep link on the device.', parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] } },
+        { name: 'done', description: 'Finish the task.', parameters: { type: 'object', properties: { success: { type: 'boolean' }, reason: { type: 'string' } }, required: ['success', 'reason'] } },
+    ];
+    if (platform !== 'ios')
+        tools.splice(4, 0, { name: 'back', description: platform === 'web' ? 'Go back in browser history.' : 'Press the Android back button.', parameters: { type: 'object', properties: {} } });
+    return tools;
+}
+function bounded(value, min, max, name) {
+    if (!Number.isInteger(value) || value < min || value > max)
+        throw new VerifyError('INVALID_ARGUMENT', `localAgent() ${name} must be an integer from ${min} to ${max}.`);
+    return value;
+}