@revyl/verify 0.3.2 → 0.4.1

package/dist/agent/model.d.ts

@@ -0,0 +1,91 @@
+/** A JSON Schema object describing one tool's arguments. */
+export type JsonSchema = Record<string, unknown>;
+export interface ModelTool {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+}
+/** One stateless request: the system prompt, the task and history as text, and the current screenshot. */
+export interface ModelRequest {
+    system: string;
+    text: string;
+    image: {
+        png: Uint8Array;
+        width: number;
+        height: number;
+    };
+    tools: ModelTool[];
+}
+export interface ModelToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ModelUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface ModelReply {
+    /** The tool the model chose, if it chose one. */
+    toolCall?: ModelToolCall;
+    text?: string;
+    usage: ModelUsage;
+    /** True when the reply stopped at the output token cap. */
+    truncated?: boolean;
+}
+/**
+ * The only contract a model has to meet to drive a Verify session. Implement it to plug in any provider,
+ * a local model, or an agent runtime. Each call is independent: Verify sends the full context every turn.
+ */
+export interface ModelAdapter {
+    /** Shown in logs, step results and the Revyl session report, so never put a secret in it. */
+    readonly name: string;
+    complete(request: ModelRequest, signal: AbortSignal): Promise<ModelReply>;
+}
+export interface AnthropicOptions {
+    /** For example 'claude-sonnet-4-5'. */
+    model: string;
+    /** Defaults to the ANTHROPIC_API_KEY environment variable. Sent only to baseURL. */
+    apiKey?: string;
+    /** Defaults to the ANTHROPIC_BASE_URL environment variable, then https://api.anthropic.com. */
+    baseURL?: string;
+    /** Output token cap per turn, thinking included. Defaults to 4096. */
+    maxTokens?: number;
+    /** Attempts after a rate limit, a 5xx or a network error. Defaults to 2. */
+    maxRetries?: number;
+}
+/** Claude through Anthropic's Messages API. */
+export declare function anthropic(options: AnthropicOptions): ModelAdapter;
+export interface OpenAICompatibleOptions {
+    /** For example 'gpt-5.5', 'qwen-3.8-27b' or 'qwen2.5vl:7b'. */
+    model: string;
+    /**
+     * The API root that serves /chat/completions. Defaults to the OPENAI_BASE_URL environment variable, then https://api.openai.com/v1;
+     * Ollama is http://localhost:11434/v1.
+     */
+    baseURL?: string;
+    /**
+     * Sent as a bearer token only to baseURL. Defaults to OPENAI_API_KEY when baseURL is left out,
+     * and to no key otherwise, so a key for one provider never reaches another.
+     */
+    apiKey?: string;
+    /** Extra headers sent only to baseURL, such as a gateway's api-key header. Never logged. */
+    headers?: Record<string, string>;
+    /** Prefixes the model in logs and reports, such as 'cerebras'. The baseURL itself is never reported. */
+    provider?: string;
+    /** Output token cap per turn, reasoning included. Defaults to 4096 for OpenAI and 2048 elsewhere. */
+    maxTokens?: number;
+    /** Attempts after a rate limit, a 5xx or a network error. Defaults to 2. */
+    maxRetries?: number;
+}
+/** Any server that speaks OpenAI's chat completions with tools and image input: OpenAI, Ollama, vLLM, OpenRouter, Cerebras and others. */
+export declare function openaiCompatible(options: OpenAICompatibleOptions): ModelAdapter;
+/** Request differences between OpenAI-compatible servers. */
+export interface ChatCompletionsQuirks {
+    /** OpenAI's reasoning models reject max_tokens. */
+    tokenField?: 'max_tokens' | 'max_completion_tokens';
+    /** Gemini documents only 'auto'. */
+    toolChoice?: 'required' | 'auto';
+    /** Where the key came from, named in errors when the provider rejects it. */
+    keySource?: string;
+}
+export declare function chatCompletions(options: OpenAICompatibleOptions, quirks: ChatCompletionsQuirks): ModelAdapter;

package/dist/agent/model.js

@@ -0,0 +1,255 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { VerifyError, errorMessage } from '../errors.js';
+/** Claude through Anthropic's Messages API. */
+export function anthropic(options) {
+    const model = requireText(options.model, 'anthropic() model');
+    const apiKey = (options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '').trim();
+    if (!apiKey)
+        throw new VerifyError('MODEL_KEY_MISSING', 'anthropic() needs apiKey or ANTHROPIC_API_KEY in the environment. Create a key in the Anthropic Console.');
+    const urlSource = options.baseURL === undefined && process.env.ANTHROPIC_BASE_URL?.trim() ? 'ANTHROPIC_BASE_URL' : undefined;
+    const { endpoint, appended } = endpointUrl(options.baseURL ?? (urlSource ? process.env.ANTHROPIC_BASE_URL : 'https://api.anthropic.com'), 'messages', 'unless-versioned', urlSource);
+    const maxTokens = options.maxTokens ?? 4096;
+    const name = `anthropic/${model}`;
+    const call = { endpoint, appended, name, model, secrets: [apiKey], keySource: options.apiKey === undefined ? 'ANTHROPIC_API_KEY' : 'the apiKey you passed', urlSource, maxRetries: options.maxRetries };
+    return {
+        name,
+        async complete(turn, signal) {
+            const body = await postJson(call, {
+                model,
+                max_tokens: maxTokens,
+                system: turn.system,
+                tools: turn.tools.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.parameters })),
+                tool_choice: { type: 'any' },
+                messages: [{
+                        role: 'user',
+                        content: [
+                            { type: 'image', source: { type: 'base64', media_type: 'image/png', data: Buffer.from(turn.image.png).toString('base64') } },
+                            { type: 'text', text: turn.text },
+                        ],
+                    }],
+            }, { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' }, signal);
+            const content = Array.isArray(body.content) ? body.content : [];
+            const toolUse = content.find((block) => block.type === 'tool_use');
+            const text = content.filter((block) => block.type === 'text').map((block) => String(block.text ?? '')).join('\n').trim();
+            const usage = (body.usage ?? {});
+            return {
+                ...(toolUse && typeof toolUse.name === 'string' ? { toolCall: { name: toolUse.name, arguments: asRecord(toolUse.input) } } : {}),
+                ...(text ? { text } : {}),
+                usage: { inputTokens: count(usage.input_tokens) + count(usage.cache_creation_input_tokens) + count(usage.cache_read_input_tokens), outputTokens: count(usage.output_tokens) },
+                ...(body.stop_reason === 'max_tokens' ? { truncated: true } : {}),
+            };
+        },
+    };
+}
+/** Any server that speaks OpenAI's chat completions with tools and image input: OpenAI, Ollama, vLLM, OpenRouter, Cerebras and others. */
+export function openaiCompatible(options) {
+    return chatCompletions(options, {});
+}
+export function chatCompletions(options, quirks) {
+    const model = requireText(options.model, 'openaiCompatible() model');
+    const openAI = options.baseURL === undefined;
+    const urlSource = openAI && process.env.OPENAI_BASE_URL?.trim() ? 'OPENAI_BASE_URL' : undefined;
+    const root = options.baseURL ?? (urlSource ? process.env.OPENAI_BASE_URL : 'https://api.openai.com/v1');
+    const apiKey = (options.apiKey ?? (openAI ? process.env.OPENAI_API_KEY : undefined) ?? '').trim();
+    const { endpoint, appended } = endpointUrl(root, 'chat/completions', 'at-host-root', urlSource);
+    const openAIModels = openAI || endpoint.hostname === 'api.openai.com';
+    const extraHeaders = checkHeaders(options.headers);
+    const maxTokens = options.maxTokens ?? (openAIModels ? 4096 : 2048);
+    const tokenField = quirks.tokenField ?? (openAIModels ? 'max_completion_tokens' : 'max_tokens');
+    const name = options.provider ? `${options.provider}/${model}` : model;
+    const keySource = quirks.keySource ?? (options.apiKey !== undefined ? 'the apiKey you passed' : apiKey ? 'OPENAI_API_KEY' : undefined);
+    const call = { endpoint, appended, name, model, secrets: [apiKey, ...Object.values(extraHeaders)].filter(Boolean), keySource, urlSource, maxRetries: options.maxRetries };
+    return {
+        name,
+        async complete(turn, signal) {
+            const body = await postJson(call, {
+                model,
+                [tokenField]: maxTokens,
+                tool_choice: quirks.toolChoice ?? 'required',
+                tools: turn.tools.map((tool) => ({ type: 'function', function: tool })),
+                messages: [
+                    { role: 'system', content: turn.system },
+                    {
+                        role: 'user',
+                        content: [
+                            { type: 'text', text: turn.text },
+                            { type: 'image_url', image_url: { url: `data:image/png;base64,${Buffer.from(turn.image.png).toString('base64')}` } },
+                        ],
+                    },
+                ],
+            }, { ...extraHeaders, ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}) }, signal);
+            const choices = Array.isArray(body.choices) ? body.choices : [];
+            const message = asRecord(choices[0]?.message);
+            const calls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+            const fn = asRecord(calls[0]?.function);
+            const text = typeof message.content === 'string' ? message.content.trim() : '';
+            const usage = asRecord(body.usage);
+            const toolCall = typeof fn.name === 'string' ? { name: fn.name, arguments: parseArguments(fn.arguments) } : toolCallFromText(text);
+            return {
+                ...(toolCall ? { toolCall } : {}),
+                ...(text ? { text } : {}),
+                usage: { inputTokens: count(usage.prompt_tokens), outputTokens: count(usage.completion_tokens) },
+                ...(choices[0]?.finish_reason === 'length' ? { truncated: true } : {}),
+            };
+        },
+    };
+}
+const RETRYABLE = new Set([408, 409, 429, 500, 502, 503, 504, 529]);
+const MAX_RETRY_DELAY_MS = 10_000;
+async function postJson(call, payload, headers, signal) {
+    const retries = call.maxRetries ?? 2;
+    if (!Number.isInteger(retries) || retries < 0 || retries > 5)
+        throw new VerifyError('INVALID_ARGUMENT', 'maxRetries must be an integer from 0 to 5.');
+    const where = `${call.name} at ${call.endpoint.host}`;
+    try {
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            try {
+                response = await fetch(call.endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', ...headers }, body: JSON.stringify(payload), redirect: 'error', signal });
+            }
+            catch (error) {
+                if (signal.aborted)
+                    throw error;
+                if (attempt < retries) {
+                    await delay(1_000 * 3 ** attempt, undefined, { signal });
+                    continue;
+                }
+                throw new VerifyError('MODEL_ERROR', `Could not reach ${where}: ${scrub(errorMessage(error), call.secrets)}. Check the baseURL and that the server is running.`);
+            }
+            const text = await response.text();
+            if (response.ok) {
+                try {
+                    return asRecord(JSON.parse(text));
+                }
+                catch {
+                    throw new VerifyError('MODEL_ERROR', `${where} returned a response that is not JSON. Check that the baseURL serves OpenAI-style chat completions.`);
+                }
+            }
+            if (RETRYABLE.has(response.status) && attempt < retries) {
+                const retryAfter = Number(response.headers.get('retry-after'));
+                await delay(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1_000, MAX_RETRY_DELAY_MS) : 1_000 * 3 ** attempt, undefined, { signal });
+                continue;
+            }
+            const message = scrub(providerMessage(text), call.secrets).slice(0, 300).replace(/[.\s]*$/, '.');
+            const step = nextStep(response.status, message, call, retries);
+            throw new VerifyError('MODEL_ERROR', `${where} refused the request (HTTP ${response.status}): ${message}${step ? ` ${step}` : ''}`, { httpStatus: response.status });
+        }
+    }
+    catch (error) {
+        if (error instanceof VerifyError || !signal.aborted)
+            throw error;
+        throw new VerifyError('TIMEOUT', `${where} did not answer in time. Raise localAgent() modelTimeout for slow or local models.`, { cause: error });
+    }
+}
+function nextStep(status, message, call, retries) {
+    if (status === 401 || status === 403) {
+        const address = call.urlSource ? ` (from ${call.urlSource})` : '';
+        return call.keySource
+            ? `${call.endpoint.host}${address} rejected the key from ${call.keySource}. Check that the key is valid for that endpoint.`
+            : `${call.endpoint.host}${address} needs a key: pass apiKey or headers.`;
+    }
+    if (status === 429)
+        return `Still rate limited after ${retries} retries. Wait and rerun, run fewer sessions at once, or raise your limit with the provider.`;
+    const unsupported = /not support|unsupported|only supported|not enabled|not allowed|cannot (accept|process|read)/i.test(message);
+    if (unsupported && /image|vision|multimodal|modalit/i.test(message))
+        return `${call.model} does not accept images. Pick a model that takes image input.`;
+    if (unsupported && /tool|function/i.test(message))
+        return `${call.model} does not support tool calls. Pick a model that does.`;
+    if (/model.*(not.?found|not exist|invalid|unknown|not a valid|no such)|(invalid|unknown|no such|not a valid).*model/i.test(message))
+        return `Check that '${call.model}' is a model name this provider serves.`;
+    if (status === 404) {
+        const address = call.urlSource ?? 'the baseURL';
+        return `Verify added ${call.appended} to ${address}. Check that '${call.model}' is a model this provider serves, and whether ${address} should include /v1.`;
+    }
+    if (status >= 500)
+        return 'The provider failed; try again later.';
+    return '';
+}
+function providerMessage(text) {
+    try {
+        const body = asRecord(JSON.parse(text));
+        const error = body.error;
+        const message = typeof error === 'string' ? error : asRecord(error).message ?? body.message;
+        if (typeof message === 'string')
+            return message;
+        return 'no error message';
+    }
+    catch { }
+    const plain = text.replace(/\s+/g, ' ').trim();
+    return plain && !plain.startsWith('<') ? plain : 'no error message';
+}
+function scrub(text, secrets) {
+    return secrets.reduce((out, secret) => (secret.length >= 4 ? out.split(secret).join('[redacted]') : out), text);
+}
+function checkHeaders(headers) {
+    if (headers === undefined)
+        return {};
+    if (!headers || typeof headers !== 'object' || Array.isArray(headers))
+        throw new VerifyError('INVALID_ARGUMENT', 'Model headers must be an object of header names to string values.');
+    const entries = Object.entries(headers);
+    if (entries.length > 20)
+        throw new VerifyError('INVALID_ARGUMENT', 'Pass at most 20 model headers.');
+    for (const [name, value] of entries) {
+        if (!/^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$/.test(name) || typeof value !== 'string' || value.length > 8_192 || /[\r\n\0]/.test(value)) {
+            throw new VerifyError('INVALID_ARGUMENT', 'Model headers need valid names and single-line string values.');
+        }
+    }
+    return { ...headers };
+}
+function toolCallFromText(text) {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return undefined;
+    try {
+        const parsed = asRecord(JSON.parse(text.slice(start, end + 1)));
+        const name = parsed.name ?? parsed.tool;
+        if (typeof name !== 'string')
+            return undefined;
+        return { name, arguments: parseArguments(parsed.arguments ?? parsed.parameters ?? {}) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseArguments(value) {
+    if (typeof value !== 'string')
+        return asRecord(value);
+    try {
+        return asRecord(JSON.parse(value));
+    }
+    catch {
+        return {};
+    }
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function requireText(value, what) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new VerifyError('INVALID_ARGUMENT', `${what} must be a non-empty string.`);
+    return value.trim();
+}
+/**
+ * Builds the request URL from a base address given with or without its /v1 suffix.
+ * unless-versioned: Anthropic's habit; add v1/ unless the address already ends in a version such as /v1.
+ * at-host-root: OpenAI-compatible; add v1/ only to a bare host, since other paths (/openai/v1, /v1beta/openai) are already complete.
+ */
+function endpointUrl(root, path, version, source = 'The model baseURL') {
+    let url;
+    try {
+        url = new URL(root.trim().endsWith('/') ? root.trim() : `${root.trim()}/`);
+    }
+    catch {
+        throw new VerifyError('INVALID_ARGUMENT', `${source} is not a valid URL.`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new VerifyError('INVALID_ARGUMENT', `${source} must be an http(s) URL without credentials.`);
+    const versioned = /\/v\d+[a-z0-9]*\/$/i.test(url.pathname);
+    const addVersion = version === 'unless-versioned' ? !versioned : url.pathname === '/';
+    const appended = addVersion ? `v1/${path}` : path;
+    return { endpoint: new URL(appended, url), appended: `/${appended}` };
+}

package/dist/agent/providers.d.ts

@@ -0,0 +1,23 @@
+import { type Grounding, type LocalAgent } from './loop.js';
+/** Your own OpenAI-compatible endpoint, such as vLLM, LiteLLM or a gateway. */
+export interface CustomModel {
+    /** The model name the endpoint expects. */
+    id: string;
+    /** The API root that serves /chat/completions. */
+    baseURL: string;
+    /** Sent as a bearer token only to baseURL. Never read from the environment, logged or sent to Revyl. */
+    apiKey?: string;
+    /** Extra headers sent only to baseURL. */
+    headers?: Record<string, string>;
+    /** Prefixes the model in step results and reports, such as 'anthropic' for 'anthropic/claude-sonnet-5-5'. */
+    provider?: string;
+    /** 'revyl' (default) has the model name elements for Revyl to locate; 'model' has it give screen coordinates. */
+    grounding?: Grounding;
+}
+/** A built-in 'provider/model' string, such as 'anthropic/claude-sonnet-5-5', or your own endpoint. */
+export type ModelOption = string | CustomModel;
+/** Picks the local agent for a step or session: a model option, an agent, or neither for Revyl's agent. */
+export declare function chooseAgent(options: {
+    model?: ModelOption;
+    agent?: LocalAgent;
+}, where: string): LocalAgent | undefined;

package/dist/agent/providers.js

@@ -0,0 +1,58 @@
+import { VerifyError } from '../errors.js';
+import { localAgent } from './loop.js';
+import { anthropic, chatCompletions } from './model.js';
+const PROVIDERS = {
+    anthropic: { label: 'Anthropic', env: ['ANTHROPIC_API_KEY'] },
+    openai: { label: 'OpenAI', env: ['OPENAI_API_KEY'] },
+    google: { label: 'Google AI Studio', env: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'], baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/', quirks: { toolChoice: 'auto' }, maxTokens: 4096 },
+    openrouter: { label: 'OpenRouter', env: ['OPENROUTER_API_KEY'], baseURL: 'https://openrouter.ai/api/v1' },
+    groq: { label: 'Groq', env: ['GROQ_API_KEY'], baseURL: 'https://api.groq.com/openai/v1' },
+    cerebras: { label: 'Cerebras', env: ['CEREBRAS_API_KEY'], baseURL: 'https://api.cerebras.ai/v1' },
+    xai: { label: 'xAI', env: ['XAI_API_KEY'], baseURL: 'https://api.x.ai/v1' },
+    ollama: { label: 'Ollama', env: [], baseURL: 'http://localhost:11434/v1' },
+};
+/** Picks the local agent for a step or session: a model option, an agent, or neither for Revyl's agent. */
+export function chooseAgent(options, where) {
+    if (options.model !== undefined && options.agent !== undefined) {
+        throw new VerifyError('INVALID_ARGUMENT', `${where} takes model or agent, not both.`);
+    }
+    if (options.model !== undefined)
+        return agentForModel(options.model);
+    if (options.agent !== undefined && typeof options.agent?.model?.complete !== 'function') {
+        throw new VerifyError('INVALID_ARGUMENT', `${where} takes an agent made with localAgent().`);
+    }
+    return options.agent;
+}
+const USAGE = `Pass 'provider/model', such as 'anthropic/claude-sonnet-5-5', with a provider of ${Object.keys(PROVIDERS).join(', ')}, or { id, baseURL } for your own OpenAI-compatible endpoint.`;
+function agentForModel(option) {
+    if (typeof option === 'string') {
+        const slash = option.indexOf('/');
+        const name = slash > 0 ? option.slice(0, slash) : '';
+        const id = option.slice(slash + 1).trim();
+        const provider = Object.hasOwn(PROVIDERS, name) ? PROVIDERS[name] : undefined;
+        if (!provider || !id) {
+            throw new VerifyError('INVALID_ARGUMENT', `Unknown model '${option.slice(0, 100)}'. ${USAGE}`);
+        }
+        const keyVariable = provider.env.find((variable) => process.env[variable]?.trim());
+        if (provider.env.length > 0 && !keyVariable) {
+            throw new VerifyError('MODEL_KEY_MISSING', `model '${option}' reads its key from ${provider.env.join(' or ')}, which is not set. Set it to your ${provider.label} API key.`);
+        }
+        const apiKey = keyVariable ? process.env[keyVariable].trim() : undefined;
+        if (name === 'anthropic')
+            return localAgent({ model: anthropic({ model: id }) });
+        return localAgent({
+            model: chatCompletions({ model: id, ...(provider.baseURL ? { baseURL: provider.baseURL } : {}), provider: name, ...(apiKey ? { apiKey } : {}), ...(provider.maxTokens ? { maxTokens: provider.maxTokens } : {}) }, { ...provider.quirks, ...(keyVariable ? { keySource: keyVariable } : {}) }),
+        });
+    }
+    if (!option || typeof option !== 'object' || typeof option.id !== 'string' || typeof option.baseURL !== 'string') {
+        throw new VerifyError('INVALID_ARGUMENT', `model must be a string or an object. ${USAGE}`);
+    }
+    if (option.apiKey !== undefined && typeof option.apiKey !== 'string')
+        throw new VerifyError('INVALID_ARGUMENT', 'model apiKey must be a string.');
+    if (option.provider !== undefined && (typeof option.provider !== 'string' || !option.provider.trim()))
+        throw new VerifyError('INVALID_ARGUMENT', 'model provider must be a non-empty string.');
+    return localAgent({
+        model: chatCompletions({ model: option.id, baseURL: option.baseURL, ...(option.apiKey !== undefined ? { apiKey: option.apiKey } : {}), ...(option.headers ? { headers: option.headers } : {}), ...(option.provider ? { provider: option.provider.trim() } : {}) }, {}),
+        ...(option.grounding ? { grounding: option.grounding } : {}),
+    });
+}

package/dist/api/client.d.ts

@@ -52,6 +52,7 @@ export declare class RevylClient {
         timeoutMs?: number;
         signal?: AbortSignal;
         retry?: boolean;
+        headers?: Record<string, string>;
     }): Promise<RawResponse>;
     private sendOnce;
 }

package/dist/api/client.js

@@ -91,7 +91,7 @@ export class RevylClient {
             timeoutMs: options.timeoutMs,
             signal: options.signal,
             retry: options.retry ?? false,
-            headers: { 'X-Revyl-Agent': 'Verify' },
+            headers: { 'X-Revyl-Agent': 'Verify', ...options.headers },
         });
     }
     async sendOnce(method, url, options) {
@@ -198,7 +198,7 @@ export function edgeBlockedError(response) {
 }
 const REFUSAL_REASONS = new Set([
     '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',
+    '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',

package/dist/auth.js

@@ -28,8 +28,8 @@ export async function resolveCredentials(options = {}) {
 export function missingCredentialsMessage() {
     return [
         'No Revyl credentials found.',
-        'Set REVYL_API_KEY to an API key from https://app.revyl.ai (Settings → API keys),',
-        "or sign in once with the Revyl CLI: 'revyl auth login'.",
+        "Sign in through your browser with 'npx @revyl/verify login' in a terminal,",
+        'or set REVYL_API_KEY to an API key from https://app.revyl.ai (Settings → API keys).',
     ].join(' ');
 }
 async function readStoredCredentials(path) {

package/dist/cli/init.d.ts

@@ -8,6 +8,7 @@ export interface InitResult {
     created: string[];
     gitignoreUpdated: boolean;
 }
+export declare function webAppIdMissingMessage(url: string | undefined): string;
 export declare function validateInitAnswers(answers: InitAnswers): InitAnswers;
 export declare function initProject(cwd: string, answers: InitAnswers, options?: {
     force?: boolean;

package/dist/cli/init.js

@@ -5,7 +5,15 @@ import { VerifyError } from '../errors.js';
 import { PACKAGE_NAME } from '../version.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const CONFIG_FILE = 'verify.config.ts';
-const EXAMPLE_SCRIPT = join('verify', 'example.ts');
+const EXAMPLE_SCRIPT = join('verify', 'example.mts');
+const SETTINGS_BUNDLE_ID = { ios: 'com.apple.Preferences', android: 'com.android.settings' };
+export function webAppIdMissingMessage(url) {
+    return [
+        'A Web target needs the id of a Web app in Revyl, so init wrote no files.',
+        'Create one at https://app.revyl.ai: click Create app, keep Web selected, and enter your site\'s public HTTPS URL. Then copy the app id from the app\'s page.',
+        `Then run: npx ${PACKAGE_NAME} init --platform web --app-id <app-id> --url ${url ?? 'https://example.com'}`,
+    ].join('\n');
+}
 export function validateInitAnswers(answers) {
     if (!['web', 'ios', 'android', 'mac'].includes(answers.platform)) {
         throw new VerifyError('INVALID_ARGUMENT', "--platform must be 'web', 'ios', 'android', or 'mac'. Linux init is unavailable; use open({ platform: 'linux' }) or a Linux config target.");
@@ -23,13 +31,16 @@ export function validateInitAnswers(answers) {
             throw new VerifyError('INVALID_ARGUMENT', '--url must be a public HTTPS URL without credentials, query, or fragment.');
         }
     }
+    if (answers.platform === 'web' && answers.appId === undefined) {
+        throw new VerifyError('INVALID_ARGUMENT', webAppIdMissingMessage(answers.url));
+    }
     return answers;
 }
 export async function initProject(cwd, answers, options = {}) {
     validateInitAnswers(answers);
     const files = [
         [CONFIG_FILE, configTemplate(answers)],
-        [EXAMPLE_SCRIPT, scriptTemplate(answers.platform)],
+        [EXAMPLE_SCRIPT, scriptTemplate(answers)],
     ];
     const existing = files.map(([path]) => path).filter((path) => existsSync(join(cwd, path)));
     if (existing.length > 0 && !options.force) {
@@ -50,25 +61,33 @@ async function ignoreOutput(cwd) {
     return true;
 }
 function configTemplate({ platform, appId, url }) {
-    const app = appId ? `'${appId}'` : `process.env.REVYL_APP_ID ?? 'REPLACE_WITH_YOUR_REVYL_APP_ID'`;
     const target = platform === 'mac'
         ? `    mac: { platform: 'mac' },`
         : platform === 'web'
             ? `    web: {
       platform: 'web',
       app: {
-        // The Revyl web app to open: copy its id from the app's page in Revyl.
-        appId: ${app},
+        // The Revyl Web app to open.
+        appId: '${appId}',
         // A public HTTPS URL, such as a preview deployment. Remove it to open the app's newest Revyl build.
         url: '${url ?? 'https://example.com'}',
       },
       viewport: { width: 1280, height: 800 },
     },`
-            : `    ${platform}: {
+            : appId
+                ? `    ${platform}: {
       platform: '${platform}',
       app: {
         // The Revyl app to install: each session installs its newest build. Use buildId to pin one build.
-        appId: ${app},
+        appId: '${appId}',
+      },
+    },`
+                : `    ${platform}: {
+      platform: '${platform}',
+      app: {
+        // The device's built-in Settings app, so the example runs before you upload anything.
+        // To test your own app, replace this line with appId: '<your Revyl app id>'.
+        bundleId: '${SETTINGS_BUNDLE_ID[platform]}',
       },
     },`;
     return `import { defineConfig } from '${PACKAGE_NAME}';
@@ -80,7 +99,7 @@ ${target}
 });
 `;
 }
-function scriptTemplate(platform) {
+function scriptTemplate({ platform, appId }) {
     if (platform === 'mac') {
         return `// Mac computers are in early access; ask support@revyl.ai to enable your organization.
 import assert from 'node:assert/strict';
@@ -101,7 +120,13 @@ try {
     const steps = platform === 'web'
         ? `await session.instruction('Follow the link on the page');
 await session.validation('A page about domains reserved for documentation is shown');`
-        : `await session.instruction('Wait for the app to finish opening and show its first screen');
+        : !appId && platform === 'ios'
+            ? `await session.instruction('Open General, then About');
+await session.validation('The screen shows the operating system version');`
+            : !appId && platform === 'android'
+                ? `await session.instruction('Open the screen that shows information about this device, such as About or About phone, then scroll or navigate until the operating system version is visible');
+await session.validation('The screen shows the version of the operating system');`
+                : `await session.instruction('Wait for the app to finish opening and show its first screen');
 await session.validation('The app has opened and shows its first screen without an error');`;
     return `import { open } from '${PACKAGE_NAME}';
 

package/dist/cli/login.js

@@ -53,7 +53,7 @@ export async function signIn(options = {}) {
                 continue;
             }
             if (credential.state === 'denied')
-                throw new VerifyError('AUTH_REJECTED', 'The Revyl login request was denied. Run your script again to sign in, or use revyl auth login.');
+                throw new VerifyError('AUTH_REJECTED', 'The Revyl login request was denied. Run your script again to sign in, or run npx @revyl/verify login.');
             if (credential.state !== 'approved')
                 throw invalidResponse();
             const token = requiredString(credential, 'api_key_token');
@@ -80,11 +80,11 @@ export async function signIn(options = {}) {
             await writePrivateState('credentials.json', stored);
             return { token, source: 'revyl-cli-login' };
         }
-        throw new VerifyError('AUTH_MISSING', 'The Revyl login request expired. Run your script again to sign in, or use revyl auth login.');
+        throw new VerifyError('AUTH_MISSING', 'The Revyl login request expired. Run your script again to sign in, or run npx @revyl/verify login.');
     }
     catch (error) {
         if (signal.aborted)
-            throw new VerifyError('AUTH_MISSING', 'Revyl sign-in was cancelled or timed out. Run your script again to sign in, or use revyl auth login.');
+            throw new VerifyError('AUTH_MISSING', 'Revyl sign-in was cancelled or timed out. Run your script again to sign in, or run npx @revyl/verify login.');
         throw error;
     }
     finally {
@@ -98,12 +98,12 @@ async function post(backendUrl, path, body, signal) {
         response = await fetch(new URL(path, backendUrl), { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body), redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(15_000)]) });
     }
     catch {
-        throw new VerifyError('AUTH_MISSING', 'Could not reach Revyl to sign in. Run your script again, use revyl auth login, or set REVYL_API_KEY.');
+        throw new VerifyError('AUTH_MISSING', 'Could not reach Revyl to sign in. Run your script again, run npx @revyl/verify login, or set REVYL_API_KEY.');
     }
     if (response.status === 404)
-        throw new VerifyError('AUTH_MISSING', 'The Revyl login request is unavailable or expired. Run your script again, or use revyl auth login.');
+        throw new VerifyError('AUTH_MISSING', 'The Revyl login request is unavailable or expired. Run your script again, or run npx @revyl/verify login.');
     if (!response.ok)
-        throw new VerifyError('AUTH_REJECTED', `Revyl sign-in failed (HTTP ${response.status}). Run your script again, use revyl auth login, or set REVYL_API_KEY.`);
+        throw new VerifyError('AUTH_REJECTED', `Revyl sign-in failed (HTTP ${response.status}). Run your script again, run npx @revyl/verify login, or set REVYL_API_KEY.`);
     let value;
     try {
         value = await response.json();
@@ -130,7 +130,7 @@ function optionalString(value, key) {
     return text || undefined;
 }
 function invalidResponse() {
-    return new VerifyError('AUTH_REJECTED', 'Revyl returned an invalid sign-in response. Run your script again, use revyl auth login, or set REVYL_API_KEY.');
+    return new VerifyError('AUTH_REJECTED', 'Revyl returned an invalid sign-in response. Run your script again, run npx @revyl/verify login, or set REVYL_API_KEY.');
 }
 function tokenExpiry(token) {
     try {