@revyl/verify 0.3.1 → 0.4.0

package/dist/session.d.ts

@@ -1,19 +1,27 @@
 import { RevylClient } from './api/client.js';
 import type { LiveStepType, Platform } from './api/types.js';
 import type { HostedTargetConfig, ResolvedDeviceTarget } from './config.js';
+import { type LocalAgent, type Location, type ModelRun, type Point, type SwipeDirection } from './agent/loop.js';
+import { type ModelOption } from './agent/providers.js';
 export type StepType = LiveStepType;
 /** The outcome of one instruction or validation, as Revyl's agent reported it. */
 export interface StepResult {
     type: StepType;
     text: string;
     passed: boolean;
-    /** Revyl's explanation, when it gave one. */
+    /** Revyl's explanation, or your model's when the step ran on a local agent. */
     reason?: string;
     durationMs: number;
+    /** Present when the step ran on your model: its name, grounding, turns and token use. */
+    model?: ModelRun;
 }
 export interface StepOptions {
-    /** Milliseconds before the step is cancelled on Revyl. Defaults to stepTimeout from the config, or 180000. */
+    /** Milliseconds before the step is cancelled. Defaults to stepTimeout from the config, or 180000. */
     timeout?: number;
+    /** Runs this step on your model, such as 'anthropic/claude-sonnet-5-5', instead of Revyl's agent. Overrides the model passed to open(). */
+    model?: ModelOption;
+    /** Runs this step on a custom agent from localAgent(). Overrides the one passed to open(); pass model or agent, not both. */
+    agent?: LocalAgent;
 }
 export interface ValidationOptions extends StepOptions {
     /** Return a failed result instead of throwing VALIDATION_FAILED. */
@@ -95,11 +103,37 @@ export interface OpenedSession extends Session {
     report(): Promise<Record<string, unknown>>;
     navigate(url: string): Promise<void>;
     open(target: HostedTargetConfig): Promise<OpenedSession>;
+    /** Taps a point in device units, or an element Revyl locates from a description. Returns the point tapped. Browsers and devices only. */
+    tap(at: Location): Promise<Point>;
+    /** Taps a text field and types into it, clearing it first unless clear is false. Returns the point tapped. Browsers and devices only. */
+    type(at: Location, text: string, options?: {
+        clear?: boolean;
+    }): Promise<Point>;
+    /** Swipes from a point or the screen's center. 'up' moves the finger up, which scrolls content down. Browsers and devices only. */
+    swipe(direction: SwipeDirection, options?: {
+        from?: Location;
+    }): Promise<void>;
+    /** Presses Enter or Backspace on the focused field. Browsers and devices only. */
+    pressKey(key: 'enter' | 'backspace'): Promise<void>;
+    /** Goes back: browser history on Web, the back button on Android. Not on iOS. */
+    back(): Promise<void>;
+    /** Opens a URL or deep link on a device, or loads a URL in a browser. */
+    openUrl(url: string): Promise<void>;
+    /** Launches an installed app by bundle ID or package name. Devices only. */
+    launchApp(bundleId: string): Promise<void>;
+    /** Asks Revyl's grounding model where an element is on the current screen, in device units. Browsers and devices only. */
+    locate(target: string): Promise<Point>;
+    /** The screen size in device units: iOS points, Android and Web pixels. Browsers and devices only. */
+    screenSize(): Promise<{
+        width: number;
+        height: number;
+    }>;
 }
 export interface SessionOptions {
     stepTimeout: number;
     log: ((line: string) => void) | undefined;
     appUrl?: string;
+    agent?: LocalAgent;
 }
 export interface HostingParent {
     id: string;
@@ -125,6 +159,8 @@ export declare class DeviceSession implements Session {
     private stepRunning;
     private parent?;
     private readySignal?;
+    private size?;
+    private attribution?;
     get expiresAt(): Date | undefined;
     private constructor();
     static start(client: RevylClient, target: ResolvedDeviceTarget, options: SessionOptions, parent?: HostingParent): Promise<DeviceSession>;
@@ -143,6 +179,7 @@ export declare class DeviceSession implements Session {
     }): Promise<Uint8Array>;
     report(): Promise<Record<string, unknown>>;
     navigate(url: string): Promise<void>;
+    private navigateTo;
     exec(): Promise<ExecResult>;
     open(): Promise<never>;
     recording(): Promise<never>;
@@ -156,6 +193,38 @@ export declare class DeviceSession implements Session {
     [Symbol.asyncDispose](): Promise<void>;
     private step;
     private runStep;
+    private runLocal;
+    private agentControls;
+    /** Taps a point in device units, or an element Revyl locates from a description. Returns the point tapped. */
+    tap(at: Location): Promise<Point>;
+    /** Taps a text field and types into it, clearing it first unless clear is false. Returns the point tapped. */
+    type(at: Location, text: string, options?: {
+        clear?: boolean;
+    }): Promise<Point>;
+    /** Swipes from a point or the screen's center. 'up' moves the finger up, which scrolls content down. */
+    swipe(direction: SwipeDirection, options?: {
+        from?: Location;
+    }): Promise<void>;
+    /** Presses Enter or Backspace on the focused field. */
+    pressKey(key: 'enter' | 'backspace'): Promise<void>;
+    /** Goes back: browser history on Web, the back button on Android. Not on iOS. */
+    back(): Promise<void>;
+    /** Opens a URL or deep link on a device, or loads a URL in a browser. */
+    openUrl(url: string): Promise<void>;
+    /** Launches an installed app by bundle ID or package name. Devices only. */
+    launchApp(bundleId: string): Promise<void>;
+    /** Asks Revyl's grounding model where an element is on the current screen, in device units. */
+    locate(target: string): Promise<Point>;
+    /** The screen size in device units: iOS points, Android and Web pixels. */
+    screenSize(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    private readScreenSize;
+    private capture;
+    private perform;
+    private resolve;
+    private act;
     private launch;
     private waitForScreenContent;
     private log;

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,11 +8,12 @@ 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 |
-| [errors.md](errors.md) | Understand an error code and fix it |
+| [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 |
 
 [llms.txt](llms.txt) lists the same files in the llms.txt format.

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.