@revyl/verify 0.3.2 → 0.4.0

package/dist/cli/main.js

@@ -1,25 +1,48 @@
 #!/usr/bin/env node
+import { rm } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs } from 'node:util';
 import { RevylClient } from '../api/client.js';
-import { missingCredentialsMessage, resolveCredentials } from '../auth.js';
+import { missingCredentialsMessage, resolveCredentials, revylCredentialsPath } from '../auth.js';
 import { VerifyError, errorMessage, isVerifyError } from '../errors.js';
 import { PACKAGE_NAME, VERSION } from '../version.js';
-import { initProject, validateInitAnswers } from './init.js';
+import { initProject, validateInitAnswers, webAppIdMissingMessage } from './init.js';
 import { installVerify, packageHasVerify } from './install.js';
 import { signIn } from './login.js';
+const INIT_USAGE = `npx ${PACKAGE_NAME} init [--platform ios|android|web|mac] [--app-id <id>] [--url <https-url>] [--force] [--yes] [--no-install]`;
+const DOCS = `https://github.com/RevylAI/verify/tree/v${VERSION}/packages/verify/docs`;
 const HELP = `verify ${VERSION}: open Revyl cloud browsers, devices, and computers from your code
 
 Usage
-  npx ${PACKAGE_NAME} init [--platform web|ios|android|mac] [--app-id <id>] [--url <https-url>] [--force] [--yes] [--no-install]
-      Install Verify, write verify.config.ts and an example script, then check authentication
+  ${INIT_USAGE}
+      Install Verify, write verify.config.ts and an example script, and sign in
+  npx ${PACKAGE_NAME} login
+      Sign in to Revyl through your browser
+  npx ${PACKAGE_NAME} logout
+      Remove the saved Revyl login from this computer
   npx ${PACKAGE_NAME} whoami
       Check which Revyl account your credentials belong to
 
 Authentication
-  REVYL_API_KEY, or a login from the Revyl CLI ('revyl auth login').
+  In a terminal, init, login, and your first open() sign you in through your browser and save the
+  login to ~/.revyl/credentials.json, which the Revyl CLI shares. In CI, set REVYL_API_KEY instead.
 
-Docs: https://github.com/RevylAI/verify/tree/v${VERSION}/packages/verify/docs
+Docs: ${DOCS}
+`;
+const INIT_HELP = `Usage: ${INIT_USAGE}
+
+Writes verify.config.ts and verify/example.mts, installs Verify when the project lacks it, and signs
+you in through your browser when no credentials are saved.
+
+  --platform    ios, android, web, or mac. Without it, init asks. iOS and Android without --app-id
+                open the device's built-in Settings app, so the example runs before you upload anything.
+  --app-id      The Revyl app to open. Required for web; create a Web app at https://app.revyl.ai first.
+  --url         The public HTTPS URL a web target opens (default https://example.com).
+  --force       Overwrite existing files.
+  --yes         Install Verify without asking.
+  --no-install  Skip installing Verify.
+
+Docs: ${DOCS}/getting-started.md
 `;
 const USAGE_CODES = new Set(['INVALID_ARGUMENT', 'AUTH_MISSING', 'AUTH_REJECTED']);
 export async function main(argv) {
@@ -37,8 +60,18 @@ export async function main(argv) {
             return 0;
         case 'init':
             return initCommand(rest);
-        case 'whoami':
-            return whoamiCommand();
+        case 'login':
+        case 'logout':
+        case 'whoami': {
+            const { values } = parseArgs({ args: rest, options: { help: { type: 'boolean', short: 'h' } } });
+            if (values.help) {
+                process.stdout.write(HELP);
+                return 0;
+            }
+            if (command === 'login')
+                return signInAndCheck(Boolean(process.stdin.isTTY) && !process.env.CI);
+            return command === 'logout' ? logoutCommand() : whoamiCommand();
+        }
         default:
             process.stderr.write(`Unknown command: ${command}\n\n${HELP}`);
             return 2;
@@ -54,8 +87,13 @@ async function initCommand(args) {
             force: { type: 'boolean' },
             yes: { type: 'boolean' },
             'no-install': { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
         },
     });
+    if (values.help) {
+        process.stdout.write(INIT_HELP);
+        return 0;
+    }
     const interactive = Boolean(process.stdin.isTTY) && !process.env.CI;
     let answers;
     if (values.platform) {
@@ -86,44 +124,46 @@ async function initCommand(args) {
     answers ??= await askInitQuestions(values['app-id'], values.url);
     const result = await initProject(process.cwd(), answers, { force: values.force ?? false });
     process.stdout.write(`Created ${result.created.join(' and ')}${result.gitignoreUpdated ? ', and added .verify/ to .gitignore' : ''}.\n`);
+    await signInAndCheck(interactive);
+    const steps = answers.platform === 'mac'
+        ? ['Mac computers are early access. Ask support@revyl.ai about access.', 'Once your organization has Mac access, run: node verify/example.mts']
+        : answers.appId
+            ? ['Run: node verify/example.mts']
+            : ['Run: node verify/example.mts', 'To test your own app, put its Revyl app id in verify.config.ts in place of the Settings bundle id.'];
+    process.stdout.write([
+        'Next:',
+        ...steps.map((step, index) => `  ${index + 1}. ${step}`),
+        '',
+    ].join('\n'));
+    return 0;
+}
+async function signInAndCheck(interactive) {
     const credentials = await resolveCredentials();
     if (!credentials) {
-        if (interactive) {
-            await signIn();
-        }
-        else {
+        if (!interactive)
             throw new VerifyError('AUTH_MISSING', `${missingCredentialsMessage()} In non-interactive environments, set the REVYL_API_KEY secret.`);
-        }
+        await signIn();
     }
     try {
-        await whoamiCommand();
+        return await whoamiCommand();
     }
     catch (error) {
         if (!interactive || !isVerifyError(error) || error.code !== 'AUTH_REJECTED')
             throw error;
         await signIn({ force: true });
-        await whoamiCommand();
+        return whoamiCommand();
     }
-    const steps = [
-        'Configure the generated verify.config.ts if needed',
-        ...(answers.platform === 'mac' ? ['Mac computers are early access. Ask support@revyl.ai about access.'] : []),
-        ...(answers.platform === 'mac' || answers.appId ? [] : ['Put your Revyl app id in verify.config.ts (or set REVYL_APP_ID)']),
-        'node verify/example.ts',
-    ];
-    process.stdout.write([
-        'Next:',
-        ...steps.map((step, index) => `  ${index + 1}. ${step}`),
-        '',
-    ].join('\n'));
-    return 0;
 }
 async function askInitQuestions(appId, url) {
     const readline = createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const platform = ((await readline.question('What do you want to open? [web/ios/android/mac] (web): ')).trim().toLowerCase() || 'web');
+        const platform = ((await readline.question('What do you want to open? [ios/android/web/mac] (ios): ')).trim().toLowerCase() || 'ios');
         if (platform === 'mac')
             return validateInitAnswers({ platform, ...(appId ? { appId } : {}), ...(url ? { url } : {}) });
-        const id = appId ?? ((await readline.question('Revyl app id (Enter to fill in later): ')).trim() || undefined);
+        const question = platform === 'web' ? 'Revyl Web app id (Enter if you have none yet): ' : 'Revyl app id (Enter to use the built-in Settings app): ';
+        const id = appId ?? ((await readline.question(question)).trim() || undefined);
+        if (platform === 'web' && !id)
+            throw new VerifyError('INVALID_ARGUMENT', webAppIdMissingMessage(url));
         const webUrl = platform === 'web' ? (url ?? ((await readline.question('HTTPS URL to open (Enter for https://example.com): ')).trim() || undefined)) : undefined;
         return validateInitAnswers({ platform, ...(id ? { appId: id } : {}), ...(webUrl ? { url: webUrl } : {}) });
     }
@@ -141,6 +181,21 @@ async function whoamiCommand() {
     process.stdout.write(`Signed in to Revyl as ${name}${org ? ` in ${org}` : ''} (credentials from ${credentials.source}).\n`);
     return 0;
 }
+async function logoutCommand() {
+    try {
+        await rm(revylCredentialsPath());
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new VerifyError('AUTH_MISSING', `Could not remove ~/.revyl/credentials.json: ${errorMessage(error)}`);
+        process.stdout.write('No saved Revyl login on this computer.\n');
+        return 0;
+    }
+    process.stdout.write('Signed out: removed ~/.revyl/credentials.json, which the Revyl CLI shares. The API key it held still works until you delete it in Revyl (Settings → API keys).\n');
+    if (process.env.REVYL_API_KEY?.trim())
+        process.stdout.write('REVYL_API_KEY is still set in this environment, so Verify keeps using it.\n');
+    return 0;
+}
 export async function runCli(argv) {
     const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
     if (major < 22 || (major === 22 && minor < 18)) {

package/dist/computer-session.d.ts

@@ -27,6 +27,15 @@ export declare class ComputerSession implements Session {
     open(target: HostedTargetConfig): Promise<OpenedSession>;
     report(): Promise<Record<string, unknown>>;
     navigate(): Promise<never>;
+    tap(): Promise<never>;
+    type(): Promise<never>;
+    swipe(): Promise<never>;
+    pressKey(): Promise<never>;
+    back(): Promise<never>;
+    openUrl(): Promise<never>;
+    launchApp(): Promise<never>;
+    locate(): Promise<never>;
+    screenSize(): Promise<never>;
     get expiresAt(): Date | undefined;
     recording(): Promise<ComputerRecording | null>;
     instruction(): Promise<never>;

package/dist/computer-session.js

@@ -123,6 +123,33 @@ export class ComputerSession {
     navigate() {
         return this.unavailable('navigate');
     }
+    tap() {
+        return this.unavailable('tap');
+    }
+    type() {
+        return this.unavailable('type');
+    }
+    swipe() {
+        return this.unavailable('swipe');
+    }
+    pressKey() {
+        return this.unavailable('pressKey');
+    }
+    back() {
+        return this.unavailable('back');
+    }
+    openUrl() {
+        return this.unavailable('openUrl');
+    }
+    launchApp() {
+        return this.unavailable('launchApp');
+    }
+    locate() {
+        return this.unavailable('locate');
+    }
+    screenSize() {
+        return this.unavailable('screenSize');
+    }
     get expiresAt() {
         return this.expiresAtMs === undefined ? undefined : new Date(this.expiresAtMs);
     }

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
-export type VerifyErrorCode = 'INVALID_ARGUMENT' | 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'AUTH_MISSING' | 'COMPUTER_ID_MISSING' | 'AUTH_REJECTED' | 'EDGE_BLOCKED' | 'API_ERROR' | 'SESSION_START_FAILED' | 'SESSION_ENDED' | 'SESSION_BUSY' | 'COMPUTER_LIMIT' | 'NOT_AVAILABLE_ON_PLATFORM' | 'ACTION_FAILED' | 'ACTION_UNCERTAIN' | 'INSTRUCTION_FAILED' | 'VALIDATION_FAILED' | 'STEP_FAILED' | 'COMMAND_FAILED' | 'NOT_FOUND' | 'ACCESS_DENIED' | 'TIMEOUT';
-export type RefusalReason = 'web_runtime_unavailable' | 'web_runtime_not_configured' | 'computer_limit' | 'runtime_unavailable' | 'computer_runtime_unavailable' | 'computer_at_capacity' | 'computer_not_running' | 'computer_cannot_host_platform' | 'computer_not_found' | 'web_build_required' | 'web_build_not_supported' | 'ios_build_required' | 'ios_build_not_supported' | 'android_build_required' | 'android_build_not_supported' | 'web_session_conflict' | 'ios_session_conflict' | 'android_session_conflict' | 'not_available_on_platform' | 'request_timeout' | 'protocol_error';
+export type VerifyErrorCode = 'INVALID_ARGUMENT' | 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'AUTH_MISSING' | 'COMPUTER_ID_MISSING' | 'AUTH_REJECTED' | 'EDGE_BLOCKED' | 'API_ERROR' | 'SESSION_START_FAILED' | 'SESSION_ENDED' | 'SESSION_BUSY' | 'COMPUTER_LIMIT' | 'NOT_AVAILABLE_ON_PLATFORM' | 'ACTION_FAILED' | 'ACTION_UNCERTAIN' | 'INSTRUCTION_FAILED' | 'VALIDATION_FAILED' | 'STEP_FAILED' | 'COMMAND_FAILED' | 'NOT_FOUND' | 'ACCESS_DENIED' | 'MODEL_ERROR' | 'MODEL_KEY_MISSING' | 'TIMEOUT';
+export type RefusalReason = 'web_runtime_unavailable' | 'web_runtime_not_configured' | 'computer_limit' | 'runtime_unavailable' | 'computer_runtime_unavailable' | 'computer_at_capacity' | 'computer_platform_at_capacity' | 'computer_not_running' | 'computer_cannot_host_platform' | 'computer_not_found' | 'web_build_required' | 'web_build_not_supported' | 'ios_build_required' | 'ios_build_not_supported' | 'android_build_required' | 'android_build_not_supported' | 'web_session_conflict' | 'ios_session_conflict' | 'android_session_conflict' | 'not_available_on_platform' | 'request_timeout' | 'protocol_error';
 export declare class VerifyError extends Error {
     readonly code: VerifyErrorCode;
     readonly reason?: RefusalReason;

package/dist/index.d.ts

@@ -6,3 +6,8 @@ export type { HostedTargetConfig, MobileAppConfig, MobileTargetConfig, ComputerT
 export type { Platform, ComputerPlatform, MobilePlatform } from './api/types.js';
 export { VerifyError, isVerifyError } from './errors.js';
 export type { RefusalReason, VerifyErrorCode } from './errors.js';
+export { localAgent } from './agent/loop.js';
+export type { Grounding, LocalAgent, LocalAgentOptions, Location, ModelRun, ModelTurn, Point, SwipeDirection, Target } from './agent/loop.js';
+export type { CustomModel, ModelOption } from './agent/providers.js';
+export { anthropic, openaiCompatible } from './agent/model.js';
+export type { AnthropicOptions, JsonSchema, ModelAdapter, ModelReply, ModelRequest, ModelTool, ModelToolCall, ModelUsage, OpenAICompatibleOptions } from './agent/model.js';

package/dist/index.js

@@ -1,3 +1,5 @@
 export { attach, currentComputer, open } from './open.js';
 export { defineConfig } from './config.js';
 export { VerifyError, isVerifyError } from './errors.js';
+export { localAgent } from './agent/loop.js';
+export { anthropic, openaiCompatible } from './agent/model.js';

package/dist/open.d.ts

@@ -1,6 +1,8 @@
 import { type TargetConfig } from './config.js';
 import { type OpenedSession } from './session.js';
 import { ComputerSession } from './computer-session.js';
+import type { LocalAgent } from './agent/loop.js';
+import { type ModelOption } from './agent/providers.js';
 export interface OpenOptions {
     /** The config file to read target names from. Defaults to the nearest verify.config.ts at or above the current folder. */
     config?: string;
@@ -8,6 +10,10 @@ export interface OpenOptions {
     log?: false | ((line: string) => void);
     backendUrl?: string;
     appUrl?: string;
+    /** Runs every instruction and validation on your model, such as 'anthropic/claude-sonnet-5-5', instead of Revyl's agent. Browsers and devices only. */
+    model?: ModelOption;
+    /** Runs every instruction and validation on a custom agent from localAgent(). Pass model or agent, not both. */
+    agent?: LocalAgent;
 }
 export interface AttachOptions extends Pick<OpenOptions, 'log' | 'backendUrl' | 'appUrl'> {
     stopOnClose?: boolean;

package/dist/open.js

@@ -5,6 +5,7 @@ import { DEFAULT_STEP_TIMEOUT_MS, loadConfig, validateTarget } from './config.js
 import { VerifyError } from './errors.js';
 import { DeviceSession } from './session.js';
 import { ComputerSession } from './computer-session.js';
+import { chooseAgent } from './agent/providers.js';
 const signIns = new Map();
 async function credentialsForUse(options) {
     const credentials = await resolveCredentials();
@@ -53,10 +54,14 @@ export async function open(target, options = {}) {
     else {
         resolved = validateTarget(target);
     }
+    const agent = chooseAgent(options, 'open()');
+    if (agent && (resolved.platform === 'mac' || resolved.platform === 'linux')) {
+        throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'Your own model runs steps on browsers and devices, not on computers.');
+    }
     const credentials = await credentialsForUse(options);
     const log = options.log === false ? undefined : (options.log ?? ((line) => void process.stderr.write(`[verify] ${line}\n`)));
     const client = new RevylClient({ token: credentials.token, backendUrl: options.backendUrl });
     if (resolved.platform === 'mac' || resolved.platform === 'linux')
         return ComputerSession.start(client, resolved, { stepTimeout, log, appUrl: options.appUrl });
-    return DeviceSession.start(client, resolved, { stepTimeout, log, appUrl: options.appUrl });
+    return DeviceSession.start(client, resolved, { stepTimeout, log, appUrl: options.appUrl, ...(agent ? { agent } : {}) });
 }

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;