@revyl/verify 0.3.2 → 0.4.0

package/dist/session.js

@@ -6,16 +6,22 @@ import { apiError, edgeBlockedError, parseJson, responseDetail, responseErrorCod
 import { trackSession, untrackSession } from './cleanup.js';
 import { VerifyError, errorMessage, isVerifyError } from './errors.js';
 import { screenHasContent } from './screen-readiness.js';
+import { runLocalStep } from './agent/loop.js';
+import { chooseAgent } from './agent/providers.js';
 const POLL_INTERVAL_MS = 2_000;
 const DEVICE_CONNECT_TIMEOUT_MS = 90_000;
 const STEP_POLL_BASE_MS = 500;
 const STEP_POLL_MAX_MS = 5_000;
+// Revyl can briefly answer a just-accepted step's status with 404 "Live step not found" before its run is listed.
+const LIVE_STEP_GRACE_MS = 10_000;
+const LIVE_STEP_NOT_FOUND = /^live step not found/i;
 const STEP_CANCEL_TIMEOUT_MS = 5_000;
 const MAX_STEP_TEXT_LENGTH = 4_000;
 const ENDED_STATUSES = new Set(['completed', 'failed', 'cancelled', 'timeout', 'stopping']);
 const STEP_TERMINAL_STATUSES = new Set(['completed', 'failed']);
 const SESSION_NOT_RUNNING = /session is (not running|not active|stopping)/i;
 const UNCERTAIN_ERROR_CODES = new Set(['request_timeout', 'connection_closed', 'protocol_error']);
+const WEB_TARGET_ERRORS = new Set(['stale_target', 'target_unstable', 'invalid_coordinates', 'target_not_found', 'unsupported_web_element', 'invalid_action', 'grounding_failed', 'password_field_required', 'password_focus_changed']);
 /** A Revyl cloud browser or iOS or Android device. */
 export class DeviceSession {
     client;
@@ -34,6 +40,8 @@ export class DeviceSession {
     stepRunning = false;
     parent;
     readySignal;
+    size;
+    attribution;
     get expiresAt() {
         return this.parent?.expiresAt;
     }
@@ -139,7 +147,7 @@ export class DeviceSession {
                     : reason === 'computer_not_found' || response.status === 404 ? 'NOT_FOUND'
                         : reason === 'computer_not_running' ? 'SESSION_ENDED'
                             : reason === 'computer_cannot_host_platform' || reason === 'computer_runtime_unavailable' || reason === 'web_runtime_unavailable' || reason === 'web_runtime_not_configured' || reason === 'runtime_unavailable' || reason === 'not_available_on_platform' ? 'NOT_AVAILABLE_ON_PLATFORM'
-                                : reason === 'computer_at_capacity' || reason === 'computer_limit' ? 'COMPUTER_LIMIT'
+                                : reason === 'computer_at_capacity' || reason === 'computer_platform_at_capacity' || reason === 'computer_limit' ? 'COMPUTER_LIMIT'
                                     : response.status === 422 || response.status === 400 ? 'INVALID_ARGUMENT'
                                         : response.status === 409 ? 'SESSION_BUSY'
                                             : response.status === 408 || response.status >= 500 ? 'ACTION_UNCERTAIN' : 'API_ERROR';
@@ -178,7 +186,7 @@ export class DeviceSession {
     }
     /** Asks Revyl's agent to do something on the app, such as "add the first product to the cart". Throws INSTRUCTION_FAILED when it cannot. */
     async instruction(text, options = {}) {
-        const result = await this.step('instruction', text, options.timeout);
+        const result = await this.step('instruction', text, options);
         if (!result.passed) {
             throw new VerifyError('INSTRUCTION_FAILED', `Instruction failed: "${result.text}". ${sentence(result.reason)} See ${this.viewerUrl}`);
         }
@@ -189,7 +197,7 @@ export class DeviceSession {
      * unless soft is set, and STEP_FAILED when Revyl could not reach a verdict.
      */
     async validation(text, options = {}) {
-        const result = await this.step('validation', text, options.timeout);
+        const result = await this.step('validation', text, options);
         if (!result.passed && !options.soft) {
             throw new VerifyError('VALIDATION_FAILED', `Validation failed: "${result.text}". ${sentence(result.reason)} See ${this.viewerUrl}`);
         }
@@ -215,9 +223,12 @@ export class DeviceSession {
             throw new VerifyError('API_ERROR', 'Revyl returned an invalid session report.');
         return report;
     }
-    async navigate(url) {
+    navigate(url) {
+        return this.navigateTo(url);
+    }
+    async navigateTo(url, signal) {
         if (this.platform !== 'web')
-            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'navigate() is available only on web sessions.');
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'navigate() is available only on web sessions; use openUrl() on iOS and Android.');
         if (typeof url !== 'string' || url.length > 2048 || /[\x00-\x20\x7f-\x9f\s\\]/.test(url))
             throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires an http(s) URL without credentials, whitespace, or backslashes.');
         let parsed;
@@ -229,7 +240,8 @@ export class DeviceSession {
         }
         if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password)
             throw new VerifyError('INVALID_ARGUMENT', 'navigate() requires an http(s) URL without credentials.');
-        const response = await this.worker('POST', 'open_url', { body: { url }, retry: false });
+        signal?.throwIfAborted();
+        const response = await this.worker('POST', 'open_url', { body: { url }, retry: false, ...(signal ? { signal } : {}) });
         const result = parseJson(response, 'open_url');
         if (!result || typeof result !== 'object' || typeof result.success !== 'boolean' || (result.action !== undefined && result.action !== 'navigate') || (result.status_code !== undefined && (!Number.isInteger(result.status_code) || result.status_code < 100 || result.status_code > 599)))
             throw new VerifyError('API_ERROR', 'Revyl returned an invalid navigation response.');
@@ -279,11 +291,12 @@ export class DeviceSession {
     [Symbol.asyncDispose]() {
         return this.close();
     }
-    async step(type, text, timeout) {
+    async step(type, text, options) {
         if (typeof text !== 'string' || text.trim() === '' || text.length > MAX_STEP_TEXT_LENGTH) {
             throw new VerifyError('INVALID_ARGUMENT', `${type}() takes a description of 1 to ${MAX_STEP_TEXT_LENGTH} characters.`);
         }
-        const timeoutMs = timeout ?? this.options.stepTimeout;
+        const agent = chooseAgent(options, `${type}()`) ?? this.options.agent;
+        const timeoutMs = options.timeout ?? this.options.stepTimeout;
         if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000) {
             throw new VerifyError('INVALID_ARGUMENT', `${type}() takes a timeout of at least 1000 ms.`);
         }
@@ -294,6 +307,13 @@ export class DeviceSession {
         const description = text.trim();
         const startedAt = Date.now();
         try {
+            if (agent) {
+                const local = await this.runLocal(type, description, timeoutMs, agent);
+                const result = { type, text: description, passed: local.passed, ...(local.reason ? { reason: local.reason } : {}), durationMs: Date.now() - startedAt, model: local.run };
+                this.steps.push(result);
+                this.log(`${local.passed ? '✓' : '✗'} ${type} "${description}" (${formatDuration(result.durationMs)}, ${local.run.turns.length} turn${local.run.turns.length === 1 ? '' : 's'} on ${local.run.id}, ${local.run.inputTokens + local.run.outputTokens} tokens)${!local.passed && local.reason ? `: ${local.reason}` : ''}`);
+                return result;
+            }
             const outcome = await this.runStep(type, description, timeoutMs);
             const output = outcome.step_output ?? {};
             const reason = output.status_reason ?? output.reasoning ?? undefined;
@@ -336,9 +356,17 @@ export class DeviceSession {
                 throw new VerifyError('API_ERROR', 'Revyl answered execute_step without a result or an accepted step id.');
             }
             stepId = body.step_id;
+            const acceptedAt = Date.now();
+            const liveStepNotFound = (response) => response.status === 404 && LIVE_STEP_NOT_FOUND.test(responseDetail(response) ?? '');
             for (let wait = STEP_POLL_BASE_MS;; wait = Math.min(wait * 2, STEP_POLL_MAX_MS)) {
                 await delay(wait, undefined, { signal });
-                const status = parseJson(await this.worker('GET', `step_status/${encodeURIComponent(stepId)}`, { signal, retry: true }), 'step_status');
+                const response = await this.worker('GET', `step_status/${encodeURIComponent(stepId)}`, { signal, retry: true, allow: liveStepNotFound });
+                if (liveStepNotFound(response)) {
+                    if (Date.now() - acceptedAt < LIVE_STEP_GRACE_MS)
+                        continue;
+                    throw new VerifyError('STEP_FAILED', `Revyl accepted the ${type} but could not find it for ${LIVE_STEP_GRACE_MS / 1000} s: "${description}". The session is still open and the step may still be running, so wait for it to finish before sending another. See ${this.viewerUrl}`, { httpStatus: 404 });
+                }
+                const status = parseJson(response, 'step_status');
                 if (status.status === 'running')
                     continue;
                 if (status.status === 'cancelled') {
@@ -365,6 +393,169 @@ export class DeviceSession {
             throw new VerifyError('TIMEOUT', `The ${type} did not finish within ${timeoutMs} ms and was cancelled: "${description}". See ${this.viewerUrl}`);
         }
     }
+    async runLocal(type, description, timeoutMs, agent) {
+        const signal = AbortSignal.timeout(timeoutMs);
+        this.attribution = {
+            'X-Revyl-Agent': `Verify local: ${agent.model.name}`.replace(/[^\x20-\x7e]/g, '?').slice(0, 100),
+            'X-Revyl-Agent-Session-Id': randomUUID(),
+        };
+        try {
+            return await runLocalStep(type, description, agent, this.agentControls(), signal, (line) => this.log(line));
+        }
+        catch (error) {
+            if (signal.aborted && !(isVerifyError(error) && error.code !== 'TIMEOUT')) {
+                throw new VerifyError('TIMEOUT', `The ${type} did not finish within ${timeoutMs} ms on ${agent.model.name}: "${description}". See ${this.viewerUrl}`, { cause: error });
+            }
+            throw error;
+        }
+        finally {
+            this.attribution = undefined;
+        }
+    }
+    agentControls() {
+        const platform = this.platform;
+        if (platform !== 'ios' && platform !== 'android' && platform !== 'web')
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `Local agents run on browsers and devices, not on ${platform}.`);
+        return {
+            platform,
+            capture: (signal) => this.capture(signal),
+            screenSize: (signal) => this.readScreenSize(signal),
+            perform: (action, screenToken, signal) => this.perform(action, screenToken, signal),
+        };
+    }
+    /** Taps a point in device units, or an element Revyl locates from a description. Returns the point tapped. */
+    async tap(at) {
+        return (await this.perform({ kind: 'tap', at: checkLocation(at) }));
+    }
+    /** Taps a text field and types into it, clearing it first unless clear is false. Returns the point tapped. */
+    async type(at, text, options = {}) {
+        if (typeof text !== 'string' || text.length > 16_384)
+            throw new VerifyError('INVALID_ARGUMENT', 'type() takes text of at most 16384 characters.');
+        return (await this.perform({ kind: 'type', at: checkLocation(at), text, clear: options.clear !== false }));
+    }
+    /** Swipes from a point or the screen's center. 'up' moves the finger up, which scrolls content down. */
+    async swipe(direction, options = {}) {
+        if (!['up', 'down', 'left', 'right'].includes(direction))
+            throw new VerifyError('INVALID_ARGUMENT', "swipe() takes 'up', 'down', 'left' or 'right'.");
+        await this.perform({ kind: 'swipe', direction, ...(options.from ? { from: checkLocation(options.from) } : {}) });
+    }
+    /** Presses Enter or Backspace on the focused field. */
+    async pressKey(key) {
+        if (key !== 'enter' && key !== 'backspace')
+            throw new VerifyError('INVALID_ARGUMENT', "pressKey() takes 'enter' or 'backspace'.");
+        await this.perform({ kind: 'key', key });
+    }
+    /** Goes back: browser history on Web, the back button on Android. Not on iOS. */
+    async back() {
+        await this.perform({ kind: 'back' });
+    }
+    /** Opens a URL or deep link on a device, or loads a URL in a browser. */
+    async openUrl(url) {
+        if (typeof url !== 'string' || url.length === 0 || url.length > 8_192)
+            throw new VerifyError('INVALID_ARGUMENT', 'openUrl() takes a URL of 1 to 8192 characters.');
+        if (this.platform === 'web' && !/^https?:/i.test(url))
+            throw new VerifyError('INVALID_ARGUMENT', 'On web, openUrl() takes an http(s) URL; deep links such as myapp://orders/42 open only on iOS and Android.');
+        await this.perform({ kind: 'open_url', url });
+    }
+    /** Launches an installed app by bundle ID or package name. Devices only. */
+    async launchApp(bundleId) {
+        if (this.platform === 'web')
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'launchApp() is available only on iOS and Android sessions; on web, use openUrl() or navigate().');
+        if (typeof bundleId !== 'string' || !/^[A-Za-z0-9._-]{1,255}$/.test(bundleId))
+            throw new VerifyError('INVALID_ARGUMENT', 'launchApp() takes a bundle ID or package name.');
+        await this.act('launch', { bundle_id: bundleId });
+    }
+    /** Asks Revyl's grounding model where an element is on the current screen, in device units. */
+    async locate(target) {
+        const { x, y } = await this.resolve(checkLocation({ target }));
+        return { x, y };
+    }
+    /** The screen size in device units: iOS points, Android and Web pixels. */
+    screenSize() {
+        return this.readScreenSize();
+    }
+    async readScreenSize(signal) {
+        if (this.size)
+            return this.size;
+        if (this.platform !== 'web') {
+            const health = parseJson(await this.worker('GET', 'health', { retry: true, ...(signal ? { signal } : {}) }), 'health');
+            if (Number.isInteger(health.screen_width) && Number.isInteger(health.screen_height) && health.screen_width > 0 && health.screen_height > 0) {
+                this.size = { width: health.screen_width, height: health.screen_height };
+                return this.size;
+            }
+        }
+        const size = pngSize((await this.capture(signal)).png);
+        if (!size)
+            throw new VerifyError('ACTION_FAILED', 'Revyl returned a screenshot that is not a PNG image.');
+        this.size = size;
+        return size;
+    }
+    async capture(signal) {
+        const response = await this.worker('GET', 'screenshot', { retry: true, ...(signal ? { signal } : {}) });
+        if (!pngSize(response.body))
+            throw new VerifyError('ACTION_FAILED', 'Revyl returned a screenshot that is not a PNG image.');
+        const screenToken = this.platform === 'web' ? response.headers.get('x-revyl-screen-token') ?? undefined : undefined;
+        return { png: response.body, ...(screenToken ? { screenToken } : {}) };
+    }
+    async perform(action, screenToken, signal) {
+        switch (action.kind) {
+            case 'tap': {
+                if ('target' in action.at && this.platform !== 'web') {
+                    signal?.throwIfAborted();
+                    const result = parseJson(await this.worker('POST', 'tap_target', { body: { target: action.at.target, ...(this.id ? { session_id: this.id } : {}) }, ...(signal ? { signal } : {}) }), 'tap_target');
+                    if (result.found === false)
+                        throw new VerifyError('ACTION_FAILED', `Revyl could not find "${action.at.target}" on the screen.`);
+                    if (result.success !== true || typeof result.x !== 'number' || typeof result.y !== 'number')
+                        throw new VerifyError('ACTION_FAILED', `tap failed: ${result.error ?? 'no reason given'}`);
+                    return { x: Math.round(result.x), y: Math.round(result.y) };
+                }
+                const point = await this.resolve(action.at, screenToken, signal);
+                await this.act('tap', pointBody(point, action.at), signal);
+                return { x: point.x, y: point.y };
+            }
+            case 'type': {
+                const point = await this.resolve(action.at, screenToken, signal);
+                await this.act('input', { ...pointBody(point, action.at), text: action.text, clear_first: action.clear }, signal);
+                return { x: point.x, y: point.y };
+            }
+            case 'swipe': {
+                const point = action.from ? await this.resolve(action.from, screenToken, signal) : await this.readScreenSize(signal).then((size) => ({ x: Math.floor(size.width / 2), y: Math.floor(size.height / 2) }));
+                const direction = this.platform === 'web' ? { up: 'down', down: 'up', left: 'right', right: 'left' }[action.direction] : action.direction;
+                await this.act('swipe', { ...pointBody(point, action.from), direction, duration_ms: 500 }, signal);
+                return undefined;
+            }
+            case 'key':
+                await this.act('key', { key: this.platform === 'web' ? (action.key === 'enter' ? 'Enter' : 'Backspace') : action.key.toUpperCase() }, signal);
+                return undefined;
+            case 'back':
+                if (this.platform === 'ios')
+                    throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'back() is not available on iOS; tap the on-screen back control.');
+                await this.act('back', undefined, signal);
+                return undefined;
+            case 'open_url':
+                signal?.throwIfAborted();
+                if (this.platform === 'web')
+                    await this.navigateTo(action.url, signal);
+                else
+                    await this.act('open_url', { url: action.url }, signal);
+                return undefined;
+        }
+    }
+    async resolve(at, screenToken, signal) {
+        if ('x' in at)
+            return { x: at.x, y: at.y, ...(screenToken ? { screenToken } : {}) };
+        const result = parseJson(await this.worker('POST', 'resolve_target', { body: { target: at.target, ...(this.id ? { session_id: this.id } : {}), ...(screenToken ? { screen_token: screenToken } : {}) }, ...(signal ? { signal } : {}) }), 'resolve_target');
+        if (result.found !== true || typeof result.x !== 'number' || typeof result.y !== 'number') {
+            throw new VerifyError('ACTION_FAILED', `Revyl could not find "${at.target}" on the screen${result.error && this.platform !== 'web' ? `: ${result.error}` : ''}.`);
+        }
+        return { x: Math.round(result.x), y: Math.round(result.y), ...(result.screen_token ? { screenToken: result.screen_token } : {}) };
+    }
+    async act(action, body, signal) {
+        signal?.throwIfAborted();
+        const result = parseJson(await this.worker('POST', action, { body: body ?? {}, ...(signal ? { signal } : {}) }), action);
+        if (result.success !== true)
+            throw new VerifyError('ACTION_FAILED', `${action} failed on the ${this.target} session: ${result.error ?? 'no reason given'}. See ${this.viewerUrl}`);
+    }
     async launch(bundleId) {
         const response = await this.worker('POST', 'launch', { body: { bundle_id: bundleId } });
         const result = parseJson(response, 'launch');
@@ -413,10 +604,20 @@ export class DeviceSession {
             ...(this.parent.expiresAt ? [AbortSignal.timeout(Math.max(0, this.parent.expiresAt.getTime() - Date.now()))] : []),
             ...(options.signal ? [options.signal] : []),
         ]) : options.signal;
-        const response = await this.client.worker(this.workflowRunId, action, { method, ...options, signal });
-        if (response.status >= 200 && response.status < 300)
+        const { allow, ...request } = options;
+        let response;
+        try {
+            response = await this.client.worker(this.workflowRunId, action, { method, ...request, signal, ...(this.attribution ? { headers: this.attribution } : {}) });
+        }
+        catch (error) {
+            if (method === 'POST' && action !== 'resolve_target' && options.signal?.aborted && isVerifyError(error) && error.code === 'TIMEOUT') {
+                throw new VerifyError('ACTION_UNCERTAIN', `The step deadline passed while ${action} was in flight, so it may have been applied. Verify did not repeat it. See ${this.viewerUrl}`, { cause: error });
+            }
+            throw error;
+        }
+        if ((response.status >= 200 && response.status < 300) || allow?.(response))
             return response;
-        if (action === 'open_url') {
+        if (action === 'open_url' && this.platform === 'web') {
             const error = this.workerError(method, action, response);
             const reason = responseRefusalReason(response);
             const message = error.code === 'ACTION_UNCERTAIN' && reason === 'request_timeout'
@@ -439,6 +640,9 @@ export class DeviceSession {
             }
             return new VerifyError('NOT_AVAILABLE_ON_PLATFORM', `${baseAction} is not available on ${this.platform} sessions (${reason}).`);
         }
+        if (WEB_TARGET_ERRORS.has(code ?? detail ?? '')) {
+            return new VerifyError('ACTION_FAILED', `${baseAction} could not act on the screen (${code ?? detail}). Take a fresh screenshot and try again. See ${this.viewerUrl}`);
+        }
         if (response.status === 404 || response.status === 410) {
             return new VerifyError('SESSION_ENDED', `The ${this.target} session is no longer reachable (${reason}). See ${this.viewerUrl}`);
         }
@@ -554,6 +758,20 @@ export function pngSize(bytes) {
     const height = view.getUint32(20);
     return width > 0 && height > 0 ? { width, height } : undefined;
 }
+function checkLocation(at) {
+    if (at && typeof at === 'object' && 'target' in at) {
+        if (typeof at.target !== 'string' || at.target.trim() === '' || at.target.length > 500)
+            throw new VerifyError('INVALID_ARGUMENT', 'A target is a description of 1 to 500 characters.');
+        return { target: at.target.trim() };
+    }
+    if (!at || typeof at !== 'object' || !Number.isInteger(at.x) || !Number.isInteger(at.y) || at.x < 0 || at.y < 0) {
+        throw new VerifyError('INVALID_ARGUMENT', 'A location is { x, y } in non-negative whole device units, or { target: "description" }.');
+    }
+    return { x: at.x, y: at.y };
+}
+function pointBody(point, at) {
+    return { x: point.x, y: point.y, ...(point.screenToken ? { screen_token: point.screenToken } : {}), ...(at && 'target' in at ? { target: at.target } : {}) };
+}
 function formatDuration(ms) {
     return ms < 60_000 ? `${(ms / 1_000).toFixed(1)}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1_000)}s`;
 }

package/docs/README.md

@@ -8,10 +8,11 @@ These files ship inside the npm package at `node_modules/@revyl/verify/docs/`, s
 | [getting-started.md](getting-started.md) | Install Verify, authenticate, and run a first script |
 | [api.md](api.md) | Look up session lifecycle, agent steps, screenshots, commands, files, and processes |
 | [configuration.md](configuration.md) | Look up every option in `verify.config.ts`, the environment variables, and the CLI |
-| [web.md](web.md) | Open a web app in a Revyl cloud browser |
-| [mobile.md](mobile.md) | Open an iOS or Android app on a Revyl cloud device |
-| [computers.md](computers.md) | Open a Mac or Linux computer for commands, files, processes, screenshots, and optional recording metadata |
+| [web.md](web.md) | Open a web app in a Revyl cloud browser, and act on it with exact actions |
+| [mobile.md](mobile.md) | Open an iOS or Android app on a Revyl cloud device, and act on it with exact actions |
+| [computers.md](computers.md) | Open a Mac computer for commands, files, processes, screenshots, and optional recording metadata |
 | [ci.md](ci.md) | Call Verify from CI or from a test runner you already use |
+| [own-model.md](own-model.md) | Run instructions and validations on your own model, such as Claude, GPT or a local model |
 | [errors.md](errors.md) | Understand an error code and fix it, or troubleshoot a common problem |
 | [agents.md](agents.md) | Use Verify as a coding agent |
 

package/docs/agents.md

@@ -1,10 +1,10 @@
 # For coding agents
 
-This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that use Verify to check an app on a cloud browser/device or run commands and files on a Mac or Linux computer. The rest of this folder describes the API in full; this page is the workflow.
+This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that use Verify to check an app on a cloud browser/device or run commands and files on a Mac computer. The rest of this folder describes the API in full; this page is the workflow.
 
 ## Workflow
 
-1. Read `verify.config.ts` to learn the target names and their platforms. If there is none, run `npx @revyl/verify init --platform <web|ios|android> --app-id <id>`, or `npx @revyl/verify init --platform mac` without an app id. You can also pass a target object to `open()`.
+1. Read `verify.config.ts` to learn the target names and their platforms. If there is none, run `npx @revyl/verify init --platform ios` or `--platform android` (without `--app-id` they open the built-in Settings app), `npx @revyl/verify init --platform web --app-id <id> --url <https-url>`, or `npx @revyl/verify init --platform mac`. You can also pass a target object to `open()`.
 2. Check the credentials once with `npx @revyl/verify whoami`. It starts no session.
 3. Write a short script, or extend an existing one, that opens one target, runs the steps you need, and closes:
    ```ts
@@ -24,11 +24,11 @@ This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that
 
 ## Rules
 
-Mac and Linux computers are early access. Ask support@revyl.ai about access before starting a computer; do not repeat an uncertain start/stop to probe availability.
+Mac computers are early access. Ask support@revyl.ai about access before starting a computer; do not repeat an uncertain start/stop to probe availability.
 
-For computer work, use structured `exec(['program', 'arg'])`, `readFile`, `writeFile`, `stat`, and run-owned handles from `processes()`/`terminate(id)`. Check command output with ordinary assertions and close in `finally`; screenshots are supported, but instruction/validation are not. Do not fall back to agent steps on computers or shell/file methods on mobile/web. See [computers.md](computers.md) for limits. Linux uses inline targets or config entries; Linux init is intentionally unavailable. Starting a computer is a paid external action and needs the same approval as starting a device.
+For computer work, use structured `exec(['program', 'arg'])`, `readFile`, `writeFile`, `stat`, and run-owned handles from `processes()`/`terminate(id)`. Check command output with ordinary assertions and close in `finally`; screenshots are supported, but instruction/validation are not. Do not fall back to agent steps on computers or shell/file methods on mobile/web. See [computers.md](computers.md) for limits. Starting a computer is a paid external action and needs the same approval as starting a device.
 
-Computers have a hard 60-minute lifetime from create, not from readiness or activity. `expiresAt` is optional on older APIs; expiry does not prevent close. After terminal state and confirmed release, `recording()` can return private signed metadata or null, including after close. Never log or share its signed URL/query. Do not automatically wait for recordings or retry `COMPUTER_LIMIT` starts: queued work (including iOS) or the concurrency limit may be responsible.
+Computers have a hard lifetime from create (two hours today), not from readiness or activity; `expiresAt` is the authoritative deadline. `expiresAt` is optional on older APIs; expiry does not prevent close. After terminal state and confirmed release, `recording()` can return private signed metadata or null, including after close. Never log or share its signed URL/query. Do not automatically wait for recordings or retry `COMPUTER_LIMIT` starts: queued work (including iOS) or the concurrency limit may be responsible.
 
 - Write steps the way you would brief a person: what to do, or what should be true, in one sentence. Name visible things ("the blue Save button in the footer"), not implementation details.
 - Use `instruction` for doing and `validation` for checking. Do not ask an instruction to check something, or a validation to change anything.

package/docs/api.md

@@ -6,22 +6,21 @@ import { attach, open, defineConfig, VerifyError, isVerifyError } from '@revyl/v
 
 ## open(target, options?)
 
-Linux targets are supported **since 0.2.0**; 0.1.0 includes the target type but rejects Linux locally.
+Starts a Revyl cloud browser, device, or Mac computer. Mobile first-screen readiness is [best-effort](mobile.md#steps), not a foreground/rendered-readiness guarantee. Computer starts retain a 10-minute default timeout; an unclaimed start may fail after 120 seconds with no-host context.
 
-Starts a Revyl cloud browser, device, or Mac or Linux computer. Mobile first-screen readiness is [best-effort](mobile.md#steps), not a foreground/rendered-readiness guarantee. Computer starts retain a 10-minute default timeout; an unclaimed start may fail after 120 seconds with no-host context.
-
-Both computer operating systems are early access. Ask support@revyl.ai about access.
+Mac computers are early access. Ask support@revyl.ai about access.
 
 ```ts
 const web = await open('web');                                       // a target named in verify.config.ts
 const ios = await open({ platform: 'ios', app: { appId: '…' } });    // or a target object, no config needed
 const mac = await open({ platform: 'mac' });                        // computer, no app needed
-const linux = await open({ platform: 'linux' });                    // same computer surface
 ```
 
 - `target`: a target name from `verify.config.ts`, or a target object with the same shape as a config entry (see [configuration.md](configuration.md)). Verify reads the nearest `verify.config.ts` at or above the current folder.
 - `options.config`: the path of a config file to read instead.
 - `options.log`: where progress lines go. By default Verify writes the session link and each step's outcome to stderr, prefixed with `[verify]`. Pass a function to receive the lines yourself, or `false` to turn them off.
+- `options.model`: runs every instruction and validation on your own model instead of Revyl's agent; see [Your own model](#your-own-model). Browsers and devices only; computers throw `NOT_AVAILABLE_ON_PLATFORM`.
+- `options.agent`: the same with a custom agent; see [Custom agents](#custom-agents). Pass `model` or `agent`, not both.
 
 `open` needs credentials: `REVYL_API_KEY` or a Revyl CLI login. It throws `AUTH_MISSING` without them, `CONFIG_NOT_FOUND` or `CONFIG_INVALID` for config problems, and `SESSION_START_FAILED` or `TIMEOUT` when the browser or device does not start.
 
@@ -53,7 +52,7 @@ The attachment, hosted-child and navigation APIs below are included in the TypeS
 
 `open()` and `computer.open()` return the extended `OpenedSession` interface. The original `Session` interface keeps its existing required members, so applications implementing or mocking it do not need to add the new methods. Use `OpenedSession` when explicitly annotating a value that calls `report`, `navigate` or `open`.
 
-Attaches to an active Mac or Linux computer in your organization without creating a new one. `options.log` controls progress. The returned computer owns cleanup by default: `close()` stops it, and automatic cleanup also applies. Attaching requires a valid expiry and does not extend the lifetime. Invalid, inaccessible, inactive or expired computers fail without sending a stop request.
+Attaches to an active Mac computer in your organization without creating a new one. `options.log` controls progress. The returned computer owns cleanup by default: `close()` stops it, and automatic cleanup also applies. Attaching requires a valid expiry and does not extend the lifetime. Invalid, inaccessible, inactive or expired computers fail without sending a stop request.
 
 When attaching to a computer you do not own, such as a CI runner, pass `attach(computerId, { stopOnClose: false })`. The attachment is not registered for automatic cleanup. Its `close()` still cancels pending child starts and gives hosted children the same five-second cleanup phase, but never stops the computer; its owner must release it. Child cleanup failures remain observable. This option is explicit and is never inferred from the environment.
 
@@ -61,7 +60,7 @@ When attaching to a computer you do not own, such as a CI runner, pass `attach(c
 
 Starts a child app session inside this computer, returning the normal session API. It inherits the parent's authenticated client, logging and step timeout; callers cannot route a child to another backend. Both `target.app.appId` and `target.app.buildId` are required. Web accepts an existing external HTTPS build, plus optional viewport/sign-in settings; native builds use the computer's fixed device profile and accept no bundle, artifact or device override. Named targets and initial URL overrides are not supported here.
 
-Mac supports Web and iOS children. Linux supports Android and may support Web when its runtime advertises that capability; Linux Web currently has a runtime limitation, so do not rely on it without confirming availability. The server remains authoritative for access, capability and capacity. Children require and share the parent's known deadline. Closing a child leaves the parent running; closing the parent cancels pending starts and gives child cleanup at most five seconds total before requesting confirmed computer release. The parent stop also stops any remaining children, so a slow child cannot prevent that request. A failed child start never closes the parent.
+Mac supports Web and iOS children. The server remains authoritative for access, capability and capacity. Children require and share the parent's known deadline. Closing a child leaves the parent running; closing the parent cancels pending starts and gives child cleanup at most five seconds total before requesting confirmed computer release. The parent stop also stops any remaining children, so a slow child cannot prevent that request. A failed child start never closes the parent.
 
 ```ts
 const computer = await attach(existingComputerId, { log: false });
@@ -83,6 +82,41 @@ This requires an already-running service on the computer. The initial Web build
 
 Web only, hosted or normal. Sends one deterministic `open_url` action and checks the returned navigation outcome. Accepts an HTTP(S) URL without credentials, whitespace, control characters or backslashes. Loopback addresses are accepted on every Web session: a hosted browser can reach its parent computer's loopback address; a normal cloud browser's localhost is its own runtime, not your machine. A cold development server may need a warm-up request before navigation succeeds; after an uncertain timeout, re-navigating is the caller's choice because the original request may still commit. The runtime is responsible for enforcing its navigation network policy. Navigation is not replayed by Verify and does not run an agent step. It resolves with no value, or throws a typed error. Computer and native sessions reject it locally.
 
+## Exact actions
+
+**Since 0.4.0. 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. Web, iOS and Android sessions take device actions that need no agent.
+
+| 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 |
+
+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.
+
+A location is `{ x, y }` in device units (iOS points, Android and Web pixels, from the top-left corner; `screenSize()` gives the bounds) or `{ target: 'Login button' }`, which Revyl's grounding model finds on the current screen.
+
+| Call | What it does |
+| --- | --- |
+| `tap(at)` | Taps and resolves with the point tapped |
+| `type(at, text, { clear })` | Taps a text field and types into it, clearing it first unless `clear` is `false` |
+| `swipe(direction, { from })` | Swipes from a location or the screen's center; `'up'` moves the finger up, which scrolls content down |
+| `pressKey('enter' \| 'backspace')` | Presses a key on the focused field |
+| `back()` | Browser history on Web, the back button on Android; iOS throws `NOT_AVAILABLE_ON_PLATFORM` |
+| `openUrl(url)` | Opens a URL or deep link on a device, or loads a URL in a browser |
+| `launchApp(bundleId)` | Launches an installed app on a device |
+| `locate(target)` | Resolves with Revyl's best match on the current screen, without acting |
+| `screenSize()` | Resolves with `{ width, height }` in device units |
+
+A failed action throws `ACTION_FAILED`, including when Revyl cannot find a target or nothing at a point can take the action. One whose outcome Revyl can't confirm throws `ACTION_UNCERTAIN` or `TIMEOUT`, so check the session before acting again. Actions are never repeated. If Verify can't reach Revyl, the action fails with `API_ERROR` and isn't resent either, so check the session before trying it again.
+
+Exact actions return when Revyl has accepted them, not when the screen has finished changing. After `swipe`, `openUrl` or `launchApp`, let the screen settle or check it before you `locate` or tap coordinates. `locate` returns Revyl's best match on the current screen and can return a point for an element that is off screen, so bring the element on screen first and check the point before you use it.
+
 ## session.report()
 
 Returns authenticated JSON metadata: `/execution/device-sessions/{id}` for normal and hosted app sessions, or the computer report for computers. It works after close, but fails locally with `NOT_FOUND` when no session ID is known. It does not download recordings or turn a device stop acknowledgment into proof of physical release. Treat returned metadata as private.
@@ -116,8 +150,9 @@ interface StepResult {
   type: 'instruction' | 'validation';
   text: string;          // the step as sent, trimmed
   passed: boolean;
-  reason?: string;       // Revyl's explanation, when it gave one
+  reason?: string;       // Revyl's explanation, or your model's on a local agent
   durationMs: number;
+  model?: ModelRun;      // set when the step ran on your model
 }
 ```
 
@@ -125,6 +160,47 @@ interface StepResult {
 
 When inspecting `revyl device report --session-id <id>`, read validation verdicts from the step's `effective_status` and `validation_result`, with `validations_passed` / `total_validations` for the validation summary. `passed_steps` / `failed_steps` and transport `status` are not enough: a successfully executed validation can have a false verdict. The SDK's `StepResult.passed` reflects that verdict, not just transport success.
 
+## Your own model
+
+**Since 0.4.0. 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#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. Runs instructions and validations on a model you choose, in your process, instead of Revyl's agent. Revyl still provides the browser or device. Leave `model` out and Revyl's agent runs the step, as before.
+
+```ts
+const session = await open('ios', { model: 'anthropic/claude-sonnet-5-5' });  // every step on your model
+await session.instruction('Open General, then About');
+await session.validation('The screen shows the iOS version');
+await session.instruction('Open Privacy', { model: 'openai/gpt-5.5' });       // or one step
+
+// Your own OpenAI-compatible endpoint: vLLM, LiteLLM, a gateway
+const custom = await open('ios', {
+  model: { id: 'qwen-3.8-27b', baseURL: 'https://api.cerebras.ai/v1', apiKey: process.env.CEREBRAS_API_KEY },
+});
+```
+
+`options.model` is a `'provider/model'` string, with the key read from the provider's usual environment variable (and `ANTHROPIC_BASE_URL` or `OPENAI_BASE_URL` for a proxy), or `{ id, baseURL, apiKey?, headers?, provider?, grounding? }` for any OpenAI-compatible endpoint. [Use your own model](own-model.md) has the provider table, which providers are verified live, how to pick a model, what Revyl still sees, the limits and troubleshooting. A missing key throws `MODEL_KEY_MISSING` before any session starts; an unknown prefix throws `INVALID_ARGUMENT`. The model must accept images and tool calls.
+
+The object form's key comes only from `apiKey`, never from the environment.
+
+`StepResult.model` reports `{ id, grounding, turns, inputTokens, outputTokens }`, with each turn's action, model and action time, and token counts. Provider failures throw `MODEL_ERROR` with the key redacted; model calls are retried up to twice on rate limits and server errors. An instruction stops after 20 turns, and the step's `timeout` bounds the whole step.
+
+## Custom agents
+
+For more control, build the agent yourself with `localAgent()` and pass it as `agent` on `open()` or a step:
+
+```ts
+import { localAgent, anthropic, openaiCompatible } from '@revyl/verify';
+
+const agent = localAgent({
+  model: openaiCompatible({ baseURL: 'http://localhost:11434/v1', model: 'qwen3-vl:8b' }),
+  grounding: 'model',
+  maxTurns: 10,
+});
+const session = await open('ios', { agent });
+```
+
+- `model`: a `ModelAdapter`. `anthropic({ model, apiKey, baseURL, maxTokens, maxRetries })` uses `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` for what you leave out. `openaiCompatible({ model, baseURL, apiKey, headers, provider, maxTokens, maxRetries })` uses `OPENAI_BASE_URL` and `OPENAI_API_KEY` only when `baseURL` is left out, so a key never reaches another provider; it then sends OpenAI's `max_completion_tokens`. To wrap another SDK or runtime, implement `{ name, complete(request, signal) }`: it gets the system prompt, text, screenshot and tools, and returns the chosen tool call and token usage.
+- `grounding`: `'revyl'` (default) as above. `'model'` has the model give screenshot coordinates instead, so Revyl receives only taps, typing and swipes, never element descriptions; it needs a model that points accurately.
+- `maxTurns` (default 20, up to 100), `modelTimeout` per model call (default 60000), `maxImageSide` for screenshots sent to the model (default 1280).
+
 ## session.screenshot(options?)
 
 Resolves with a PNG of the screen as a `Uint8Array`. With `options.path`, also writes it there, creating folders as needed.
@@ -137,7 +213,7 @@ For owning computers, cleanup must be confirmed; a terminal state alone does not
 
 ## Computer commands, files, and processes
 
-Mac and Linux sessions provide `exec(argv: string[], options?)`, `readFile(path, options?)` returning `Buffer`, `writeFile(path, string | Uint8Array, options?)`, `stat(path, options?)` returning `{ kind, size }`, `processes(options?)` returning `{ id, state, exitCode? }[]`, and `terminate(id, options?)`. They throw `NOT_AVAILABLE_ON_PLATFORM` on web/iOS/Android. See [computers.md](computers.md) for complete signatures, limits, timeouts, and examples. Both support `screenshot()`; instruction/validation do not run on computers.
+Mac sessions provide `exec(argv: string[], options?)`, `readFile(path, options?)` returning `Buffer`, `writeFile(path, string | Uint8Array, options?)`, `stat(path, options?)` returning `{ kind, size }`, `processes(options?)` returning `{ id, state, exitCode? }[]`, and `terminate(id, options?)`. They throw `NOT_AVAILABLE_ON_PLATFORM` on web/iOS/Android. See [computers.md](computers.md) for complete signatures, limits, timeouts, and examples. Both support `screenshot()`; instruction/validation do not run on computers.
 
 ### `session.recording(): Promise<ComputerRecording | null>`
 
@@ -151,17 +227,17 @@ Computers only. First reads the report and requires terminal state plus confirme
 | --- | --- |
 | `viewerUrl` | The session in Revyl: a live view while it runs, its recording/report after. Use `revyl device report --session-id <id>` for web/mobile, or `revyl computer report <id>` for computers. |
 | `id` | Revyl's session id |
-| `platform` | `'web'`, `'ios'`, `'android'`, `'mac'`, or `'linux'` |
-| `expiresAt` | **Since 0.2.0.** Validated API expiry as a `Date`, or undefined for devices and older APIs. Computers have a hard 60-minute lifetime from create. Operations/screenshot observation are bounded by expiry; close and recording remain possible. |
+| `platform` | `'web'`, `'ios'`, `'android'`, or `'mac'` |
+| `expiresAt` | **Since 0.2.0.** Validated API expiry as a `Date`, or undefined for devices and older APIs. Computers have a hard lifetime from create (two hours today); this value is the authoritative deadline. Operations/screenshot observation are bounded by expiry; close and recording remain possible. |
 | `target` | The target name, or the platform for a target object |
 | `closed` | Whether `close()` was called |
 
 ## Rules worth knowing
 
 - **One step at a time.** Await each step before starting the next on the same session; a second concurrent step throws `INVALID_ARGUMENT`. Separate sessions can run in parallel.
-- **No hidden retries.** Verify never repeats a step or a device action. A step whose outcome is unknown because the connection failed mid-request throws `ACTION_UNCERTAIN`.
+- **No hidden retries.** Verify never repeats a step or a device action. A local agent retries only its own model calls. A step whose outcome is unknown because the connection failed mid-request throws `ACTION_UNCERTAIN`.
 - **No memory between steps.** Each step is independent: Revyl does not carry values from one step to the next. Put everything a step needs into its text.
-- **No replay or cache.** Every step runs Revyl's agent again, every time.
+- **No replay or cache.** Every step runs its agent again, every time.
 
 ## Cleanup