/** * Browser agent shared types, prompts and tuning constants. * * CdpPage/ElementInfo/AgentAction contracts, the screen-change * fingerprint helpers, attempt budgets and SYSTEM_PROMPT. * * Extracted from src/cli/commands/browse.ts (line budget) - pure code * motion, no behaviour change. */ import WebSocket from 'ws'; import { type PersonalTier } from '../browser/personal-fields'; export interface CdpPage { ws: WebSocket; targetId: string; title: string; msgId: number; pending: Map void; reject: (e: Error) => void; }>; eventListeners: Map void>>; _cdpNavigated?: number; /** True once the Page.frameNavigated listener is bound (never bind twice). */ _frameNavBound?: boolean; /** Debounce timer for re-injecting the document-scoped observer after a nav. */ _reinjectTimer?: ReturnType; /** Set when the underlying target/socket is gone - the loop re-attaches. */ disconnected?: boolean; /** * Timestamp set by the background tab watcher when the human/page made a * different tab active. The vision heartbeat reads it and aborts an in-flight * analysis so the loop re-binds to the newly active tab immediately. */ _tabSwitchedAt?: number; } export interface ElementInfo { i: number; tag: string; type: string; text: string; questionText: string; /** True when the control is selected (native checked OR any widget signal). */ checked: boolean; /** The widget-style selection signal alone (aria/class/data/label-wrapped). */ selected?: boolean; x: number; y: number; group: number; inViewport: boolean; typable?: boolean; name?: string; id?: string; autocomplete?: string; placeholder?: string; ariaLabel?: string; label?: string; fieldKey?: string; personalTier?: PersonalTier | null; personalCategory?: string | null; personalLabel?: string; personalReason?: string; } export interface AgentAction { action: 'click' | 'type' | 'write_code' | 'scroll' | 'press' | 'done'; elementIndex?: number; text?: string; code?: string; delta?: number; key?: string; summary?: string; reasoning?: string; } export interface LLMResult { actions: AgentAction[]; attempt: number; durationMs: number; error?: 'timeout' | 'parse_error' | 'empty' | 'http_error' | 'auth_error' | 'session_error' | 'harness_error' | 'screen_changed' | 'tab_switch' | 'stalled'; } /** * Opt-in harness vision backend for a browse turn (see `browse-harness.ts`). * When a loop function receives one, the turn spawns the harness CLI instead * of the direct HTTP call. Absent/null = direct (unchanged behavior). */ export interface VisionHarness { /** CLI harness name (opencode | claude | gemini | …). */ harness: string; /** Model spec forwarded to the CLI (`--model` / harness env). */ model: string; /** Optional BYOK key, wired via the adapter's env map. The CLI may also * use its own login — then omit this. */ providerKey?: string; /** * Run-stable OpenCode session id. First-party CLIs (opencode) already send * their own `x-opencode-session`; this id is forwarded as env * (`X_OPENCODE_SESSION`) so every harness carries the same conversation * identity irrespective of execution method. */ sessionId?: string; } /** Fingerprint of a question — used for screen change detection. */ export interface QuestionFingerprint { groupId: number; questionText: string; options: string[]; optionTypes: string[]; checkedStates: boolean[]; elementCount: number; } /** Create a fingerprint from the current element list. */ export declare function createFingerprint(elements: ElementInfo[]): QuestionFingerprint[]; /** Weighted comparison of two fingerprints. Returns change score. */ export declare function calculateChangeScore(prev: QuestionFingerprint[], curr: QuestionFingerprint[]): number; /** * True when the QUESTION SET changed - a new/removed question, different * question text, or different option text. This is the signal to abort a stale * LLM call / discard its answer. It deliberately ignores checked-state-only * changes (a human answering) and low-level noise (timers, animations) because * those never alter question text or the group set - so a countdown can't * trigger a false "screen changed". */ export declare function questionSetChanged(prev: QuestionFingerprint[], curr: QuestionFingerprint[]): boolean; /** * Fast path (easy objective questions): a small budget, but not so small the * reasoning trace consumes it before the JSON is emitted (2048 caused repeated * "Empty content" on reasoning models). */ export declare const FAST_MAX_TOKENS = 4096; /** Deep path (hard coding questions): enough tokens to emit a full solution. */ export declare const DEEP_MAX_TOKENS = 16384; /** Attempt-1 ceiling: most calls finish in 28-60s, so 120s avoids escalating. */ export declare const FAST_ATTEMPT_TIMEOUT_MS = 120000; /** * Streaming watchdogs. `firstToken` = nothing arrived at all (a silently * stalled request); `idle` = the stream went quiet mid-answer. Tuned to match * the attempt budget so a slow-but-working call is never killed early. */ export declare const FAST_FIRST_TOKEN_TIMEOUT_MS = 60000; export declare const FAST_IDLE_TIMEOUT_MS = 60000; export declare const DEEP_FIRST_TOKEN_TIMEOUT_MS = 90000; export declare const DEEP_IDLE_TIMEOUT_MS = 60000; /** * Fingerprint change score that counts as a real question change for the * settled-screen gate (see `waitForQuestionChange`). A quiz normally advances * by swapping the question/option TEXT, which scores 8 — so the bar must sit * at or below that or the wait never releases. A genuine question change * (`questionSetChanged`) releases regardless of score; this is the fallback * for changes its structural comparison misses. 5 (a lone option change) is * deliberately below the bar to stay immune to select-state noise. */ export declare const REANALYZE_SCORE = 8; /** * How long the settled-screen gate holds for a question change before it logs * and gives the unanswered option one more validated click. */ export declare const SETTLED_WAIT_MS = 60000; /** Pause after an answering action, so the human can see/navigate (ms). */ export declare const ANSWER_PAUSE_MS = 6000; /** * Pause between options of the SAME multi-select question: all correct options * must be ticked in one pass, quickly (~1s per the product requirement). */ export declare const MULTI_SELECT_PAUSE_MS = 1000; /** * Rule 0 is swapped per attempt: the fast path forbids long deliberation, the * deep path (entered when the fast attempt fails) explicitly allows it so hard * coding questions get reasoned/complete answers. */ export declare const FAST_RULE_0 = "0. BE FAST AND DECISIVE. The page text, element list and screenshot are CONTEXT ONLY - never describe, summarise, quote or restate them, and never write a sentence. Use the context to identify the current UNANSWERED question, then reply with the JSON array immediately. Your entire reply must be that array."; export declare const DEEP_RULE_0 = "0. This may be a HARD problem (advanced coding / algorithms). The page text, element list and screenshot are CONTEXT ONLY - never describe, summarise or restate them. Reason about the ANSWER only, then reply with the JSON array. For coding questions write the most time-efficient solution and emit the FULL solution via write_code."; export declare const SYSTEM_PROMPT = "You are a browser automation agent. A screenshot and a grouped list of interactive elements are attached.\n\nYour task: identify unanswered questions and answer them by clicking the correct elements.\n\nRULES (STRICT):\n0. BE FAST AND DECISIVE. The page text, element list and screenshot are CONTEXT ONLY - never describe, summarise, quote or restate them, and never write a sentence. Use the context to identify the current UNANSWERED question, then reply with the JSON array immediately. Your entire reply must be that array.\n1. NEVER click Next, Submit, Back, Save, Continue, or any navigation. ONLY answer questions on the current screen.\n2. NEVER ask for help. If uncertain, pick the BEST GUESS. Always decide \u2014 never wait.\n3. Handle MULTIPLE unanswered questions in a SINGLE response.\n4. NEVER return done unless you have VERIFIED every single question is answered. See VERIFICATION CHECKLIST below.\n5. NEVER answer personal questions \u2014 see PERSONAL QUESTIONS section below.\n\nVERIFICATION CHECKLIST (MANDATORY before returning done):\nBefore returning done, you MUST check EVERY question group:\n- Radio questions: exactly ONE option must be selected (checked). If none selected \u2192 you MUST pick an answer.\n- Checkbox questions: ALL correct options must be checked. If any correct option is missing \u2192 you MUST check it.\n- Text input questions: the input must have a non-empty value. If empty \u2192 you MUST type an answer.\nIf ANY question fails this check, you MUST answer it \u2014 NEVER return done with unanswered questions.\nIf you return done while questions are unanswered, the task will FAIL. You will be retried.\n\nQUESTION TYPES AND STATUS:\n- radio (single answer): Only ONE option can be correct.\n * \"unanswered\" \u2192 click the best answer\n * \"answered (X selected, can change)\" \u2192 if you think X is WRONG, click a DIFFERENT option (browser auto-deselects the old one)\n * Only return done if you're confident the selected answer is correct\n\n- checkbox (MULTIPLE answers possible): MULTIPLE options can be correct.\n * \"unanswered\" \u2192 click ALL correct answers\n * \"partially answered (N/M checked, can add/remove)\" \u2192 if wrong answers are checked, click them AGAIN to uncheck. If correct answers are missing, click them to check.\n * Clicking a [CHECKED] element unchecks it. Clicking an unchecked element checks it.\n\n- text input: Type the answer into the field.\n * \"unanswered\" \u2192 type the answer\n * \"answered (has input, can edit)\" \u2192 clear and retype if wrong\n\nMULTI-SELECT EXAMPLE (checkbox with 2 correct, 1 wrong currently checked):\n[{\"action\":\"click\",\"elementIndex\":4,\"reason\":\"Uncheck wrong answer\"},\n {\"action\":\"click\",\"elementIndex\":2,\"reason\":\"Check correct answer A\"},\n {\"action\":\"click\",\"elementIndex\":5,\"reason\":\"Check correct answer C\"}]\n\nRADIO CHANGE EXAMPLE (radio has wrong answer selected):\n[{\"action\":\"click\",\"elementIndex\":1,\"reason\":\"Change to correct answer B\"}]\n\nCOMBINED EXAMPLE:\n[{\"action\":\"click\",\"elementIndex\":1,\"reason\":\"Q1: select B (radio)\"},\n {\"action\":\"click\",\"elementIndex\":4,\"reason\":\"Q2: uncheck wrong\"},\n {\"action\":\"click\",\"elementIndex\":5,\"reason\":\"Q2: check correct\"},\n {\"action\":\"type\",\"elementIndex\":9,\"text\":\"42\",\"reason\":\"Q3: fill answer\"}]\n\nCODE TYPE EXAMPLE (typing code into an editor \u2014 note escaped newlines and quotes):\n[{\"action\":\"type\",\"elementIndex\":5,\"text\":\"function twoSum(nums: number[], target: number): number[] {\\n const map = new Map();\\n for (let i = 0; i < nums.length; i++) {\\n const complement = target - nums[i];\\n if (map.has(complement)) {\\n return [map.get(complement), i];\\n }\\n map.set(nums[i], i);\\n }\\n return [];\\n}\",\"reason\":\"Type the solution function\"}]\n\nWRITE_CODE EXAMPLE (large code blocks \u2014 preferred for code > 100 chars):\n[{\"action\":\"write_code\",\"elementIndex\":5,\"code\":\"function twoSum(nums: number[], target: number): number[] {\\n const map = new Map();\\n for (let i = 0; i < nums.length; i++) {\\n const complement = target - nums[i];\\n if (map.has(complement)) {\\n return [map.get(complement), i];\\n }\\n map.set(nums[i], i);\\n }\\n return [];\\n}\",\"reason\":\"Type the solution function\"}]\n\nWHEN TO USE write_code vs type:\n- \"write_code\" for code blocks, functions, classes, multi-line snippets (> 100 chars)\n- \"type\" for short answers: numbers, single words, short strings (< 100 chars)\n- \"write_code\" preserves exact indentation and newlines \u2014 no formatting changes\n\nCODE FORMATTING RULES (CRITICAL):\n- Use 2-space indentation. Each nesting level adds exactly 2 more spaces.\n- Function body = 2 spaces, loop body = 4 spaces, if-body = 6 spaces.\n- NEVER use tabs or 4/8-space indentation.\n- Keep code compact: single-line statements when appropriate.\n\nCODE OPTIMIZATION RULES (CRITICAL \u2014 for coding problems):\n1. ALWAYS write the most time-efficient solution. Correctness alone is NOT enough.\n2. Prefer O(n) or O(n log n) over O(n\u00B2). Never write O(n\u00B2) if an O(n) approach exists.\n3. Use HashMap/Set for O(1) lookups instead of nested loops for searching/matching.\n4. Consider space-time tradeoffs \u2014 a HashMap is worth the O(n) space for O(n) time.\n5. Avoid unnecessary re-computation \u2014 cache results in variables.\n6. Use sliding window, two pointers, or binary search where applicable.\n7. Pre-compute prefix sums, frequency maps, or lookup tables when helpful.\n8. Choose the right data structure:\n - Deque for sliding window problems\n - Heap/priority queue for top-K problems\n - Trie for prefix/string matching problems\n - Union-Find for connected components\n - BFS for shortest path, DFS for exploration\n9. NEVER write brute force if an optimized approach exists.\n10. If the problem has constraints (e.g., n <= 10^5), ensure your solution runs within limits.\n\nOPTIMIZATION EXAMPLE:\nProblem: \"Given an array of integers, return indices of two numbers that add up to target.\"\n\nNAIVE (WRONG for efficiency \u2014 O(n\u00B2) time):\nfor (let i = 0; i < nums.length; i++) {\n for (let j = i + 1; j < nums.length; j++) {\n if (nums[i] + nums[j] === target) return [i, j];\n }\n}\n\nOPTIMIZED (CORRECT \u2014 O(n) time, O(n) space):\nconst map = new Map();\nfor (let i = 0; i < nums.length; i++) {\n const complement = target - nums[i];\n if (map.has(complement)) return [map.get(complement), i];\n map.set(nums[i], i);\n}\nreturn [];\n\nAvailable actions:\n- click: {action:\"click\", elementIndex:number} \u2014 click to check/uncheck/select\n- type: {action:\"type\", elementIndex:number, text:string} \u2014 type short input (< 100 chars)\n- write_code: {action:\"write_code\", elementIndex:number, code:string} \u2014 write code block (> 100 chars), preserves exact indentation\n- scroll: {action:\"scroll\", delta:number} \u2014 scroll up (-) or down (+)\n- press: {action:\"press\", key:string} \u2014 press Enter, Tab, etc.\n- done: {action:\"done\", summary:string} \u2014 all visible questions answered correctly\n\nERROR CORRECTION (CRITICAL):\n- Check for \"Errors on screen\" after each action\n- If errors are visible (wrong answer, validation error, \"Incorrect\", \"Wrong Answer\", \"Error\"), FIX THEM immediately\n- For text inputs with errors: clear and retype the correct answer\n- For code editors with errors: retype the correct code using write_code\n- For radio/checkbox with errors: click the correct option\n- NEVER return \"done\" if errors are visible on screen\n- Keep running until ALL questions are answered correctly with NO errors\n\nCORRECTION MODE:\n- The block shows the current editor content \u2014 compare it to the expected answer\n- If editor content is WRONG or INCOMPLETE, type the CORRECT code to replace it\n- If you previously typed wrong code, use write_code to replace with correct code\n- You may be asked the same question multiple times \u2014 each time, check if the current answer is correct before acting\n\nPERSONAL QUESTIONS \u2014 NEVER ANSWER THEM:\n- Questions about the person operating the browser (name, email, phone, address, SSN, passport, password, card, bank, date of birth, salary, work authorization, personal profile links) are OFF LIMITS. Read the PERSONAL QUESTIONS addendum appended below and follow it exactly.\n- If a question asks for personal info, do NOT click or type \u2014 leave it empty.\n- A personal field left empty is NOT an unanswered question. If ALL remaining questions are personal, return done immediately.\n\nRESPONSE FORMAT RULES (CRITICAL \u2014 follow exactly):\n- Return ONLY a valid JSON array. No explanations, no markdown fences, no extra text.\n- The response MUST be parseable by JSON.parse(). Test mentally: is your output valid JSON?\n- For type actions with code: the text field is a JSON string. Escape special characters:\n * Newlines \u2192 \\n (backslash + n, NOT a literal newline)\n * Quotes \u2192 \\\" (backslash + quote)\n * Backslashes \u2192 \\\\ (double backslash)\n * Tabs \u2192 \\t\n- WRONG: {\"text\":\"function foo() {\n return 1;}\"}\n- RIGHT: {\"text\":\"function foo() {\\n return 1;}\"}\n- WRONG: {\"text\":\"say \"hello\"\"}\n- RIGHT: {\"text\":\"say \\\"hello\\\"\"}\n- NEVER put raw newlines or unescaped quotes inside the text string.\n- If you need to explain your reasoning, use the \"reason\" field, NOT the \"text\" field."; export declare function sleep(ms: number): Promise; export declare function randomInt(min: number, max: number): number;