@revyl/verify 0.3.1 → 0.4.0

package/dist/agent/loop.js

@@ -0,0 +1,215 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { VerifyError, errorMessage, isVerifyError } from '../errors.js';
+import { fitPng } from './image.js';
+/** Runs instructions and validations on a model you choose, on your machine. Revyl only receives device actions. */
+export function localAgent(options) {
+    if (!options || typeof options.model?.complete !== 'function' || typeof options.model.name !== 'string') {
+        throw new VerifyError('INVALID_ARGUMENT', 'localAgent() needs a model adapter, such as anthropic() or openaiCompatible().');
+    }
+    const grounding = options.grounding ?? 'revyl';
+    if (grounding !== 'model' && grounding !== 'revyl')
+        throw new VerifyError('INVALID_ARGUMENT', "localAgent() grounding must be 'model' or 'revyl'.");
+    const maxTurns = bounded(options.maxTurns ?? 20, 1, 100, 'maxTurns');
+    const modelTimeout = bounded(options.modelTimeout ?? 60_000, 1_000, 600_000, 'modelTimeout');
+    const maxImageSide = bounded(options.maxImageSide ?? 1280, 256, 4096, 'maxImageSide');
+    return Object.freeze({ model: options.model, grounding, maxTurns, modelTimeout, maxImageSide });
+}
+const VALIDATION_ATTEMPTS = 3;
+const NO_TOOL_LIMIT = 3;
+const ABORTING_CODES = new Set(['SESSION_ENDED', 'SESSION_BUSY', 'AUTH_REJECTED', 'EDGE_BLOCKED', 'MODEL_ERROR', 'TIMEOUT', 'API_ERROR', 'ACTION_UNCERTAIN']);
+/** Runs one instruction or validation through the agent's model. The caller enforces the step deadline through signal. */
+export async function runLocalStep(type, task, agent, controls, signal, log) {
+    const run = { id: agent.model.name, grounding: agent.grounding, turns: [], inputTokens: 0, outputTokens: 0 };
+    const history = [];
+    const size = await controls.screenSize(signal);
+    const tools = type === 'validation' ? [VERDICT_TOOL] : instructionTools(controls.platform, agent.grounding);
+    const turns = type === 'validation' ? VALIDATION_ATTEMPTS : agent.maxTurns;
+    let turnsWithoutTool = 0;
+    for (let turn = 1; turn <= turns; turn += 1) {
+        signal.throwIfAborted();
+        const shot = await controls.capture(signal);
+        const image = fitPng(shot.png, agent.maxImageSide);
+        const modelStarted = Date.now();
+        const reply = await agent.model.complete({
+            system: type === 'validation' ? validationPrompt(controls.platform) : instructionPrompt(controls.platform, agent.grounding),
+            text: turnText(type, task, image, history),
+            image,
+            tools,
+        }, AbortSignal.any([signal, AbortSignal.timeout(agent.modelTimeout)]));
+        const record = { action: 'no tool call', ok: false, modelMs: Date.now() - modelStarted, actionMs: 0, inputTokens: reply.usage.inputTokens, outputTokens: reply.usage.outputTokens };
+        run.turns.push(record);
+        run.inputTokens += record.inputTokens;
+        run.outputTokens += record.outputTokens;
+        const call = reply.toolCall;
+        if (reply.truncated) {
+            throw new VerifyError('MODEL_ERROR', `${agent.model.name}'s reply was cut off at its output token cap ${call ? 'in the middle of a tool call, so Verify did not use it' : 'before it called a tool'}. Pass the model to localAgent() through an adapter with a higher maxTokens, such as anthropic({ model, maxTokens: 8192 }) or openaiCompatible({ model, baseURL, maxTokens: 8192 }).`);
+        }
+        if (!call) {
+            turnsWithoutTool += 1;
+            if (turnsWithoutTool === NO_TOOL_LIMIT) {
+                throw new VerifyError('MODEL_ERROR', `${agent.model.name} answered ${NO_TOOL_LIMIT} times in a row without calling a tool. Pick a model that supports tool calls.`);
+            }
+            history.push(`${turn}. You answered without calling a tool. Call exactly one tool.`);
+            log(`  · turn ${turn}: no tool call (${record.modelMs} ms)`);
+            continue;
+        }
+        turnsWithoutTool = 0;
+        if (!tools.some((tool) => tool.name === call.name)) {
+            record.action = call.name.slice(0, 40);
+            history.push(`${turn}. ${record.action}: failed: not one of the offered tools (${tools.map((tool) => tool.name).join(', ')}).`);
+            log(`  · turn ${turn}: ${record.action} is not an offered tool (${record.modelMs} ms)`);
+            continue;
+        }
+        if (call.name === 'done' || call.name === 'verdict') {
+            const passed = (call.name === 'done' ? call.arguments.success : call.arguments.passed) === true;
+            const reason = typeof call.arguments.reason === 'string' ? call.arguments.reason.slice(0, 1_000) : undefined;
+            record.action = `${call.name} ${passed}`;
+            record.ok = true;
+            log(`  · turn ${turn}: ${record.action} (${record.modelMs} ms)`);
+            return { passed, ...(reason ? { reason } : {}), run };
+        }
+        const actionStarted = Date.now();
+        try {
+            const action = toAction(call, controls.platform, agent.grounding, image, size);
+            record.action = describe(action);
+            const at = await controls.perform(action, shot.screenToken, signal);
+            record.ok = true;
+            history.push(`${turn}. ${record.action}${at ? ` at (${at.x}, ${at.y})` : ''}: done.`);
+        }
+        catch (error) {
+            if (isVerifyError(error) && ABORTING_CODES.has(error.code))
+                throw error;
+            if (record.action === 'no tool call')
+                record.action = call.name;
+            history.push(`${turn}. ${record.action}: failed: ${errorMessage(error).slice(0, 300)}`);
+        }
+        record.actionMs = Date.now() - actionStarted;
+        log(`  · turn ${turn}: ${record.action}${record.ok ? '' : ' (failed)'} (model ${record.modelMs} ms, action ${record.actionMs} ms)`);
+        await delay(controls.platform === 'web' ? 500 : 1_000, undefined, { signal });
+    }
+    if (type === 'validation')
+        throw new VerifyError('STEP_FAILED', `${agent.model.name} gave no verdict in ${turns} attempts.`);
+    return { passed: false, reason: `${agent.model.name} did not finish within ${turns} turns.`, run };
+}
+function toAction(call, platform, grounding, image, size) {
+    const args = call.arguments;
+    const location = (required) => {
+        if (grounding === 'revyl') {
+            if (typeof args.target === 'string' && args.target.trim())
+                return { target: args.target.trim().slice(0, 500) };
+            if (required)
+                throw new VerifyError('INVALID_ARGUMENT', 'target is required: describe the element by its visible text or appearance.');
+            return undefined;
+        }
+        if (typeof args.x !== 'number' || typeof args.y !== 'number') {
+            if (required)
+                throw new VerifyError('INVALID_ARGUMENT', 'x and y are required.');
+            return undefined;
+        }
+        if (args.x < 0 || args.y < 0 || args.x >= image.width || args.y >= image.height) {
+            throw new VerifyError('INVALID_ARGUMENT', `(${args.x}, ${args.y}) is outside the ${image.width}x${image.height} screenshot.`);
+        }
+        return { x: Math.round((args.x * size.width) / image.width), y: Math.round((args.y * size.height) / image.height) };
+    };
+    switch (call.name) {
+        case 'tap':
+            return { kind: 'tap', at: location(true) };
+        case 'type':
+            if (typeof args.text !== 'string')
+                throw new VerifyError('INVALID_ARGUMENT', 'text is required.');
+            return { kind: 'type', at: location(true), text: args.text, clear: args.clear !== false };
+        case 'swipe': {
+            if (!['up', 'down', 'left', 'right'].includes(String(args.direction)))
+                throw new VerifyError('INVALID_ARGUMENT', 'direction must be up, down, left or right.');
+            const from = location(false);
+            return { kind: 'swipe', direction: args.direction, ...(from ? { from } : {}) };
+        }
+        case 'press_key':
+            if (args.key !== 'enter' && args.key !== 'backspace')
+                throw new VerifyError('INVALID_ARGUMENT', 'key must be enter or backspace.');
+            return { kind: 'key', key: args.key };
+        case 'back':
+            if (platform === 'ios')
+                throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'iOS has no back button; tap the on-screen back control.');
+            return { kind: 'back' };
+        case 'open_url':
+            if (typeof args.url !== 'string' || !args.url)
+                throw new VerifyError('INVALID_ARGUMENT', 'url is required.');
+            return { kind: 'open_url', url: args.url };
+        default:
+            throw new VerifyError('INVALID_ARGUMENT', `${call.name} is not a tool.`);
+    }
+}
+function describe(action) {
+    const where = (at) => (at === undefined ? '' : 'target' in at ? ` "${at.target}"` : ` (${at.x}, ${at.y})`);
+    switch (action.kind) {
+        case 'tap':
+            return `tap${where(action.at)}`;
+        case 'type':
+            return `type ${JSON.stringify(action.text.length > 40 ? `${action.text.slice(0, 40)}…` : action.text)} into${where(action.at)}`;
+        case 'swipe':
+            return `swipe ${action.direction}${action.from ? ` from${where(action.from)}` : ''}`;
+        case 'key':
+            return `press ${action.key}`;
+        case 'back':
+            return 'back';
+        case 'open_url':
+            return `open ${action.url}`;
+    }
+}
+const PLATFORM_LABEL = { ios: 'iPhone simulator', android: 'Android emulator', web: 'web browser' };
+function instructionPrompt(platform, grounding) {
+    return [
+        `You operate a ${PLATFORM_LABEL[platform]} to carry out a task. Every turn you see the current screenshot and the actions taken so far, and you call exactly one tool.`,
+        grounding === 'revyl'
+            ? 'To point at an element, describe it in target by its visible text or look, for example "General row" or "Search field". Do not give coordinates.'
+            : 'To point at an element, give the pixel coordinates of its center in the screenshot, x to the right and y down from the top-left corner.',
+        'Check the screenshot before each action: the previous action may not have done what you expected. To see content further down, swipe up.',
+        'Call done with success true as soon as the screenshot shows the task is complete. Call done with success false and a reason if it cannot be done.',
+    ].join('\n');
+}
+function validationPrompt(platform) {
+    return `You check whether a statement holds on the current screen of a ${PLATFORM_LABEL[platform]}. Judge only what the screenshot shows, then call verdict with passed and a one-sentence reason.`;
+}
+function turnText(type, task, image, history) {
+    const lines = [type === 'validation' ? `Statement: ${task}` : `Task: ${task}`, `The screenshot is ${image.width}x${image.height} pixels.`];
+    if (type === 'instruction')
+        lines.push(history.length ? `Actions so far:\n${history.slice(-30).join('\n')}` : 'No actions yet.');
+    else if (history.length)
+        lines.push(`Earlier attempts:\n${history.join('\n')}`);
+    return lines.join('\n');
+}
+const VERDICT_TOOL = {
+    name: 'verdict',
+    description: 'Report whether the statement holds on the screen.',
+    parameters: { type: 'object', properties: { passed: { type: 'boolean' }, reason: { type: 'string' } }, required: ['passed', 'reason'] },
+};
+function instructionTools(platform, grounding) {
+    const at = grounding === 'revyl'
+        ? { properties: { target: { type: 'string', description: 'The element, by its visible text or look.' } }, required: ['target'] }
+        : { properties: { x: { type: 'integer', description: 'Screenshot pixel x.' }, y: { type: 'integer', description: 'Screenshot pixel y.' } }, required: ['x', 'y'] };
+    const tools = [
+        { name: 'tap', description: 'Tap an element.', parameters: { type: 'object', ...at } },
+        {
+            name: 'type',
+            description: 'Tap a text field and type into it. Clears the field first unless clear is false.',
+            parameters: { type: 'object', properties: { ...at.properties, text: { type: 'string' }, clear: { type: 'boolean' } }, required: [...at.required, 'text'] },
+        },
+        {
+            name: 'swipe',
+            description: "Swipe from a point, or from the screen's center. up moves the finger up, which scrolls content down.",
+            parameters: { type: 'object', properties: { direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] }, ...at.properties }, required: ['direction'] },
+        },
+        { name: 'press_key', description: 'Press a key on the focused field.', parameters: { type: 'object', properties: { key: { type: 'string', enum: ['enter', 'backspace'] } }, required: ['key'] } },
+        { name: 'open_url', description: platform === 'web' ? 'Load a URL in the current tab.' : 'Open a URL or deep link on the device.', parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] } },
+        { name: 'done', description: 'Finish the task.', parameters: { type: 'object', properties: { success: { type: 'boolean' }, reason: { type: 'string' } }, required: ['success', 'reason'] } },
+    ];
+    if (platform !== 'ios')
+        tools.splice(4, 0, { name: 'back', description: platform === 'web' ? 'Go back in browser history.' : 'Press the Android back button.', parameters: { type: 'object', properties: {} } });
+    return tools;
+}
+function bounded(value, min, max, name) {
+    if (!Number.isInteger(value) || value < min || value > max)
+        throw new VerifyError('INVALID_ARGUMENT', `localAgent() ${name} must be an integer from ${min} to ${max}.`);
+    return value;
+}

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;
 }