@revyl/verify 0.3.2 → 0.4.1

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,10 @@ export class DeviceSession {
     stepRunning = false;
     parent;
     readySignal;
+    size;
+    sizeSource;
+    screenshotSize;
+    attribution;
     get expiresAt() {
         return this.parent?.expiresAt;
     }
@@ -139,7 +149,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 +188,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 +199,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 +225,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 +242,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 +293,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 +309,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 +358,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 +395,231 @@ 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 screenshot pixels, or an element Revyl locates from a description. Returns the point tapped, in screenshot pixels. */
+    async tap(at) {
+        const location = await this.toDevice(checkLocation(at));
+        if (this.platform === 'ios')
+            await this.readScreenshotSize();
+        return this.toScreenshot((await this.perform({ kind: 'tap', at: location })));
+    }
+    /** 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.');
+        const location = await this.toDevice(checkLocation(at));
+        if (this.platform === 'ios')
+            await this.readScreenshotSize();
+        return this.toScreenshot((await this.perform({ kind: 'type', at: location, 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: await this.toDevice(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 screenshot pixels. */
+    async locate(target) {
+        const { x, y } = await this.resolve(checkLocation({ target }));
+        return this.toScreenshot({ x, y });
+    }
+    /** The screenshot's size in pixels, the space every coordinate uses. */
+    async screenSize() {
+        const { width, height } = await this.readScreenshotSize();
+        return { width, height };
+    }
+    /** The screenshot's size and the device size Revyl acts in. They differ on iOS, where Revyl acts in points and a screenshot has more pixels. */
+    async readScreenshotSize(fresh = false) {
+        if (fresh) {
+            const cached = [this.size, this.sizeSource, this.screenshotSize];
+            [this.size, this.sizeSource, this.screenshotSize] = [undefined, undefined, undefined];
+            try {
+                return await this.readScreenshotSize();
+            }
+            catch (error) {
+                [this.size, this.sizeSource, this.screenshotSize] = cached;
+                throw error;
+            }
+        }
+        if (this.screenshotSize)
+            return this.screenshotSize;
+        const device = await this.readScreenSize();
+        let size = device;
+        if (this.platform === 'ios') {
+            if (this.sizeSource !== 'health')
+                throw new VerifyError('ACTION_FAILED', `Revyl did not report this iOS screen's size in points, so Verify cannot map screenshot pixels to it and sent no action. See ${this.viewerUrl}`);
+            size = pngSize((await this.capture()).png);
+        }
+        this.screenshotSize = { width: size.width, height: size.height, device };
+        return this.screenshotSize;
+    }
+    async toDevice(at) {
+        if ('target' in at)
+            return at;
+        const read = async (fresh) => {
+            try {
+                return await this.readScreenshotSize(fresh);
+            }
+            catch (error) {
+                if (this.platform === 'ios' || !(error instanceof VerifyError))
+                    throw error;
+                return undefined;
+            }
+        };
+        let size = await read(false);
+        if (size && (at.x >= size.width || at.y >= size.height))
+            size = await read(true);
+        if (!size)
+            return at;
+        if (at.x >= size.width || at.y >= size.height) {
+            throw new VerifyError('INVALID_ARGUMENT', `(${at.x}, ${at.y}) is outside the screenshot: x must be 0 to ${size.width - 1} and y 0 to ${size.height - 1}, in screenshot pixels.`);
+        }
+        return { x: Math.min(size.device.width - 1, Math.round((at.x * size.device.width) / size.width)), y: Math.min(size.device.height - 1, Math.round((at.y * size.device.height) / size.height)) };
+    }
+    async toScreenshot(point) {
+        if (this.platform !== 'ios')
+            return point;
+        const size = await this.readScreenshotSize();
+        return { x: Math.round((point.x * size.width) / size.device.width), y: Math.round((point.y * size.height) / size.device.height) };
+    }
+    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 };
+                this.sizeSource = 'health';
+                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 +668,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 +704,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 +822,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 screenshot pixels, 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
@@ -22,13 +22,42 @@ This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that
 4. Run it with `node path/to/script.ts`. Share the session link from the first `[verify]` line with the user, so they can watch.
 5. Read the outcome from the exit code and stderr. Each step prints `✓` or `✗` with its text; a failure prints `CODE: message`, ending with the session link. Look at any screenshot you saved before changing the script or the app.
 
+## Exact actions and coordinates
+
+Use `instruction()` when the step needs judgement, and exact actions (`tap`, `type`, `swipe`, `pressKey`, `locate`, `screenSize`) when you know exactly what to press. They work on Web, iOS and Android, not on computers.
+
+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.
+
+`swipe('up')` moves the finger up, so content scrolls down, on every platform. Actions return once Revyl accepts them, so after a swipe, `openUrl` or `launchApp`, wait for the screen to settle before you `locate` or tap by coordinates.
+
+```ts
+import { open } from '@revyl/verify';
+
+const session = await open('ios');
+try {
+  await session.tap({ target: 'General' });                 // first choice: describe the element
+  const about = await session.locate('About');              // a point in screenshot pixels
+  await session.tap(about);                                 // so it goes straight to tap()
+
+  await session.screenshot({ path: '.verify/screen.png' }); // open it and find what to press
+  await session.tap({ x: 660, y: 1500 });                   // a position read off the screenshot, unchanged
+  await session.swipe('up', { from: { x: 660, y: 2000 } }); // swipe from a screenshot position too
+  const { width, height } = await session.screenSize();     // the screenshot's size
+  console.log(`x is 0 to ${width - 1}, y is 0 to ${height - 1}`);
+} finally {
+  await session.close();
+}
+```
+
+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 state the same rule with each language's names. [api.md](api.md#exact-actions) lists every call and its errors.
+
 ## 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.