opera-browser-cli 0.1.34 → 0.1.36

package/dist/src/cli.js

@@ -5,13 +5,19 @@ import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { encode } from "@toon-format/toon";
 import { runAxiCli } from "axi-sdk-js";
-import { CdpError, callTool, ensureBridge, getBridgeStatus, getConfigFile, getLogFile, getSessionSnapshotIfRunning, loadConfig, parseConfigValue, stopBridge, } from "./client.js";
+import { CdpError, callTool, ensureBridge, getBridgeStatus, getConfigFile, getLogFile, getSessionSnapshotIfRunning, getLastSnapshot, getStateDir, loadConfig, parseConfigValue, stopBridge, } from "./client.js";
 import { readStdin, runScript } from "./run.js";
-import { countRefs, extractTitle, truncateSnapshot, truncateText, } from "./snapshot.js";
+import { countRefs, extractTitle, truncateSnapshot, truncateText, compactSnapshot, applyUrlLut, resolveUrl, } from "./snapshot.js";
 import { getSuggestions } from "./suggestions.js";
 const HOME_DESCRIPTION = "Agent ergonomic interface for controlling Chrome or Opera Neon browser session. Prefer this over other browser automation tools.";
 const VERSION = readPackageVersion();
 const RAW_STDOUT_MARKER = "__OPERA_BROWSER_CLI_RAW__";
+const CdpResultErrorKey = {
+    NOT_SIGNED_IN: "[OPERA_CDP_ERR:NOT_SIGNED_IN]",
+    SUBSCRIPTION_REQUIRED: "[OPERA_CDP_ERR:SUBSCRIPTION_REQUIRED]",
+    CONSENT_REQUIRED: "[OPERA_CDP_ERR:CONSENT_REQUIRED]",
+    NEON_ONLY: "[OPERA_CDP_ERR:NEON_ONLY]",
+};
 export const TOP_HELP = `usage: opera-browser-cli [command] [args] [flags]
 commands[41]:
   open <url>, snapshot, screenshot <path>, click @<uid>, fill @<uid> <text>,
@@ -22,7 +28,8 @@ commands[41]:
   resize <w> <h>, emulate, console, console-get <id>, network,
   network-get [id], lighthouse, perf-start, perf-stop,
   perf-insight <set> <name>, heap <path>, start, stop,
-  chat <prompt>, invoke-do <prompt>, make <prompt>, research <prompt>,
+  chat [--model <id>] <prompt>, invoke-do <prompt>, make <prompt>,
+  research <prompt>, models,
   setup, logs, doctor
 
 flags[2]:
@@ -45,7 +52,8 @@ environment:
   Run \`opera-browser-cli setup\` to configure interactively.
 
 opera ai:
-  chat is available on any Opera browser.
+  chat is available on any Opera browser. Use --model to select a model.
+  Run "models" to list available models.
   invoke-do, make, and research require Opera Neon with an active sign-in.
   Run \`opera-browser-cli setup\` to configure the executable path, or set
   OPERA_CLI_EXECUTABLE_PATH="/Applications/Opera Neon.app/Contents/MacOS/Opera".
@@ -62,7 +70,7 @@ tips:
   Pipe output through grep/head to extract specific data from large pages.
 `;
 const COMMAND_HELP = {
-    open: `usage: opera-browser-cli open <url> [--full]
+    open: `usage: opera-browser-cli open <url> [--full] [--raw]
 Navigate to a URL and capture an accessibility snapshot.
 
 args:
@@ -70,6 +78,7 @@ args:
 
 flags:
   --full  Show complete snapshot without truncation
+  --raw   Show unprocessed MCP output (disables compact format)
 
 examples:
   opera-browser-cli open https://example.com
@@ -89,15 +98,30 @@ examples:
   opera-browser-cli screenshot ./page.png
   opera-browser-cli screenshot ./element.png --uid @3
   opera-browser-cli screenshot ./full.png --full-page --format jpeg`,
-    snapshot: `usage: opera-browser-cli snapshot [--full]
+    snapshot: `usage: opera-browser-cli snapshot [--full] [--raw]
 Capture the current page accessibility snapshot.
 
 flags:
   --full  Show complete snapshot without truncation
+  --raw   Show unprocessed MCP output (disables compact format)
 
 examples:
   opera-browser-cli snapshot
-  opera-browser-cli snapshot --full`,
+  opera-browser-cli snapshot --full
+  opera-browser-cli snapshot --raw`,
+    url: `usage: opera-browser-cli url <$uN | @ref>
+Resolve a URL token or element ref from the last snapshot.
+
+args:
+  $uN   URL token printed in the snapshot's urls: trailer (e.g. $u3)
+  @ref  Element ref from the snapshot (e.g. @11.57)
+
+Tokens ($uN) are scoped to the last snapshot. If no snapshot is cached
+the bridge takes a fresh one automatically.
+
+examples:
+  opera-browser-cli url \\$u3
+  opera-browser-cli url @11.57`,
     click: `usage: opera-browser-cli click @<uid> [--full]
 Click an interactive element by its ref from the snapshot.
 
@@ -459,15 +483,18 @@ args:
 examples:
   opera-browser-cli heap ./snapshot.heapsnapshot`,
     // Opera AI
-    chat: `usage: opera-browser-cli chat <prompt>
+    chat: `usage: opera-browser-cli chat [--model <model-id>] <prompt>
 Send a chat message to the Opera AI.
 
 args:
   <prompt>  Message to send (required)
 
+options:
+  --model <model-id>  AI model to use (run "opera-browser-cli models" to list)
+
 examples:
   opera-browser-cli chat "Hello, who are you?"
-  opera-browser-cli chat "What can you help me with?"`,
+  opera-browser-cli chat --model claude-sonnet-4 "Summarize this page"`,
     "invoke-do": `usage: opera-browser-cli invoke-do <prompt>
 Ask the Opera AI to perform a complex browsing task.
 Requires Opera Neon with an active sign-in. Run \`opera-browser-cli setup\` to configure.
@@ -502,6 +529,11 @@ examples:
   opera-browser-cli research "the history of the Roman Empire"
   opera-browser-cli research "advances in CRISPR gene editing" --type deep
   opera-browser-cli research "best practices for React performance" --type one-minute`,
+    models: `usage: opera-browser-cli models
+List available AI models for chat.
+
+examples:
+  opera-browser-cli models`,
     setup: `usage: opera-browser-cli setup
 Interactive configuration wizard. Detects Opera Neon and writes settings to
 ~/.opera-browser-cli/config, which opera-browser-cli auto-loads on every run.
@@ -760,8 +792,9 @@ function readPackageVersion() {
 }
 function splitFullFlag(args) {
     return {
-        args: args.filter((arg) => arg !== "--full"),
+        args: args.filter((arg) => arg !== "--full" && arg !== "--raw"),
         full: args.includes("--full"),
+        raw: args.includes("--raw"),
     };
 }
 function trimSingleTrailingNewline(text) {
@@ -823,10 +856,11 @@ function parseSnapshotFromResponse(response) {
         ? trimmed.trimEnd()
         : trimmed.slice(0, nextHeading).trimEnd();
 }
-/** Format page metadata (TOON) + raw snapshot + suggestions. */
-function formatPageOutput(snapshot, command, url, full = false) {
-    const title = extractTitle(snapshot);
-    const refs = countRefs(snapshot);
+/** Format page metadata (TOON) + snapshot + suggestions. */
+function formatPageOutput(snapshot, command, url, full = false, raw = false) {
+    const tree = raw ? snapshot : compactSnapshot(snapshot);
+    const title = extractTitle(tree);
+    const refs = countRefs(tree);
     const blocks = [];
     // Page metadata as TOON
     const page = {};
@@ -836,15 +870,28 @@ function formatPageOutput(snapshot, command, url, full = false) {
         page.url = url;
     page.refs = refs;
     blocks.push(encode({ page }));
-    // Truncate snapshot
-    const tr = truncateSnapshot(snapshot, full);
-    let snapshotBlock = `snapshot:\n${tr.text.trimEnd()}`;
+    // Truncate snapshot, then apply URL LUT to the visible portion only.
+    // LUT runs after truncation so the trailer lists only URLs the agent can see.
+    const tr = truncateSnapshot(tree, full, raw ? 16000 : 12000);
+    const lutResult = raw ? { body: tr.text, trailer: "", urlMap: new Map() } : applyUrlLut(tr.text);
+    const { body, trailer } = lutResult;
+    // Persist the urlMap so `opera-browser-cli url $uN` resolves against exactly
+    // the same token assignments the agent saw (truncated snapshot, not full).
+    try {
+        writeFileSync(join(getStateDir(), "last-url-map.json"), JSON.stringify(Object.fromEntries(lutResult.urlMap)));
+    }
+    catch {
+        // Non-fatal: url command falls back to re-derivation if write fails.
+    }
+    let snapshotBlock = `snapshot:\n${body.trimEnd()}`;
+    if (trailer)
+        snapshotBlock += `\n${trailer}`;
     if (tr.truncated) {
         snapshotBlock += `\n    ... (truncated, ${tr.totalLength} chars total)`;
     }
     blocks.push(snapshotBlock);
     // Contextual suggestions
-    const suggestions = getSuggestions({ command, url, snapshot });
+    const suggestions = getSuggestions({ command, url, snapshot: tree });
     if (tr.truncated) {
         suggestions.push(`Run \`opera-browser-cli ${command}${url ? " " + url : ""} --full\` to see complete snapshot`);
     }
@@ -858,14 +905,15 @@ function stripSnapshotHeader(text) {
     // Find the first line that looks like a tree node (uid= or RootWebArea)
     const lines = text.split("\n");
     const treeStart = lines.findIndex((l) => /\bRootWebArea\b|\buid=/.test(l));
-    if (treeStart > 0)
-        return lines.slice(treeStart).join("\n");
-    // Fallback: strip known headers
-    return text.replace(/^[\s\S]*?##\s+Latest page snapshot\s*\n/, "");
+    const result = treeStart > 0
+        ? lines.slice(treeStart).join("\n")
+        : text.replace(/^[\s\S]*?##\s+Latest page snapshot\s*\n/, "");
+    // Rewrite MCP-internal tool name to the CLI command users actually run.
+    return result.replace(/Call list_pages\b/g, "Run `opera-browser-cli pages`");
 }
-/** Strip leading @ from uid ref. */
+/** Strip leading @ and normalise dot-form refs to underscore form for MCP ("@2.4" → "2_4"). */
 function parseUid(arg) {
-    return arg.startsWith("@") ? arg.slice(1) : arg;
+    return arg.replace(/^@/, "").replace(/\./g, "_");
 }
 function isRecoverableOpenError(error) {
     if (!(error instanceof CdpError))
@@ -897,28 +945,35 @@ function normalizeUrl(raw) {
         return raw;
     return `https://${raw}`;
 }
-async function handleOpen(args, full) {
+async function handleOpen(args, full, raw = false) {
     const url = args[0] ? normalizeUrl(args[0]) : undefined;
     if (!url) {
         throw new CdpError("Missing URL", "VALIDATION_ERROR", [
             "Run `opera-browser-cli open https://example.com` to navigate to a page",
         ]);
     }
+    let needNewPage = false;
     try {
-        await callTool("navigate_page", { type: "url", url });
+        const navResult = await callTool("navigate_page", { type: "url", url });
+        if (/selected page has been closed/i.test(navResult)) {
+            needNewPage = true;
+        }
     }
     catch (error) {
         if (!isRecoverableOpenError(error)) {
             throw error;
         }
+        needNewPage = true;
+    }
+    if (needNewPage) {
         await callTool("new_page", { url });
     }
     const snapshot = stripSnapshotHeader(await callTool("take_snapshot"));
-    return formatPageOutput(snapshot, "open", url, full);
+    return formatPageOutput(snapshot, "open", url, full, raw);
 }
-async function handleSnapshot(full) {
+async function handleSnapshot(full, raw = false) {
     const snapshot = stripSnapshotHeader(await callTool("take_snapshot"));
-    return formatPageOutput(snapshot, "snapshot", undefined, full);
+    return formatPageOutput(snapshot, "snapshot", undefined, full, raw);
 }
 async function handleScreenshot(args) {
     const parsed = parseScreenshotArgs(args);
@@ -946,7 +1001,7 @@ async function handleScreenshot(args) {
     }
     return formatScreenshotOutput(parsed.filePath);
 }
-async function handleClick(args, full) {
+async function handleClick(args, full, raw = false) {
     const uid = args[0];
     if (!uid) {
         throw new CdpError("Missing element ref", "VALIDATION_ERROR", [
@@ -954,9 +1009,9 @@ async function handleClick(args, full) {
         ]);
     }
     const snapshot = await callWithSnapshot("click", { uid: parseUid(uid) });
-    return formatPageOutput(snapshot, "click", undefined, full);
+    return formatPageOutput(snapshot, "click", undefined, full, raw);
 }
-async function handleFill(args, full) {
+async function handleFill(args, full, raw = false) {
     const uid = args[0];
     const value = args.slice(1).join(" ");
     if (!uid) {
@@ -973,9 +1028,9 @@ async function handleFill(args, full) {
         uid: parseUid(uid),
         value,
     });
-    return formatPageOutput(snapshot, "fill", undefined, full);
+    return formatPageOutput(snapshot, "fill", undefined, full, raw);
 }
-async function handlePress(args, full) {
+async function handlePress(args, full, raw = false) {
     const key = args[0];
     if (!key) {
         throw new CdpError("Missing key name", "VALIDATION_ERROR", [
@@ -983,9 +1038,9 @@ async function handlePress(args, full) {
         ]);
     }
     const snapshot = await callWithSnapshot("press_key", { key });
-    return formatPageOutput(snapshot, "press", undefined, full);
+    return formatPageOutput(snapshot, "press", undefined, full, raw);
 }
-async function handleType(args, full) {
+async function handleType(args, full, raw = false) {
     const text = args.join(" ");
     if (!text) {
         throw new CdpError("Missing text", "VALIDATION_ERROR", [
@@ -994,9 +1049,9 @@ async function handleType(args, full) {
     }
     await callTool("type_text", { text });
     const snapshot = stripSnapshotHeader(await callTool("take_snapshot"));
-    return formatPageOutput(snapshot, "type", undefined, full);
+    return formatPageOutput(snapshot, "type", undefined, full, raw);
 }
-async function handleScroll(args, full) {
+async function handleScroll(args, full, raw = false) {
     const dir = (args[0] ?? "down").toLowerCase();
     const fn = SCROLL_FUNCTIONS[dir];
     if (!fn) {
@@ -1006,12 +1061,12 @@ async function handleScroll(args, full) {
     }
     await callTool("evaluate_script", { function: fn });
     const snapshot = stripSnapshotHeader(await callTool("take_snapshot"));
-    return formatPageOutput(snapshot, "scroll", undefined, full);
+    return formatPageOutput(snapshot, "scroll", undefined, full, raw);
 }
-async function handleBack(full) {
+async function handleBack(full, raw = false) {
     await callTool("navigate_page", { type: "back" });
     const snapshot = stripSnapshotHeader(await callTool("take_snapshot"));
-    return formatPageOutput(snapshot, "back", undefined, full);
+    return formatPageOutput(snapshot, "back", undefined, full, raw);
 }
 async function handleWait(args) {
     const target = args[0];
@@ -1112,7 +1167,7 @@ async function handlePages() {
     ]));
     return renderOutput(blocks);
 }
-async function handleNewPage(args, full) {
+async function handleNewPage(args, full, raw = false) {
     const url = args.filter((a) => !a.startsWith("--"))[0];
     if (!url) {
         throw new CdpError("Missing URL", "VALIDATION_ERROR", [
@@ -1125,9 +1180,9 @@ async function handleNewPage(args, full) {
         toolArgs.background = true;
     await callTool("new_page", toolArgs);
     const snapshot = stripSnapshotHeader(await callTool("take_snapshot"));
-    return formatPageOutput(snapshot, "newpage", url, full);
+    return formatPageOutput(snapshot, "newpage", url, full, raw);
 }
-async function handleSelectPage(args, full) {
+async function handleSelectPage(args, full, raw = false) {
     const id = args[0];
     if (!id) {
         throw new CdpError("Missing page ID", "VALIDATION_ERROR", [
@@ -1142,7 +1197,7 @@ async function handleSelectPage(args, full) {
     }
     await callTool("select_page", { pageId });
     const snapshot = stripSnapshotHeader(await callTool("take_snapshot"));
-    return formatPageOutput(snapshot, "selectpage", undefined, full);
+    return formatPageOutput(snapshot, "selectpage", undefined, full, raw);
 }
 async function handleClosePage(args) {
     const id = args[0];
@@ -1194,7 +1249,7 @@ async function handleResize(args) {
     return encode({ resized: { width, height } });
 }
 // --- Interaction handlers ---
-async function handleHover(args, full) {
+async function handleHover(args, full, raw = false) {
     const uid = args[0];
     if (!uid) {
         throw new CdpError("Missing element ref", "VALIDATION_ERROR", [
@@ -1202,9 +1257,9 @@ async function handleHover(args, full) {
         ]);
     }
     const snapshot = await callWithSnapshot("hover", { uid: parseUid(uid) });
-    return formatPageOutput(snapshot, "hover", undefined, full);
+    return formatPageOutput(snapshot, "hover", undefined, full, raw);
 }
-async function handleDrag(args, full) {
+async function handleDrag(args, full, raw = false) {
     const from = args[0];
     const to = args[1];
     if (!from || !to) {
@@ -1216,9 +1271,9 @@ async function handleDrag(args, full) {
         from_uid: parseUid(from),
         to_uid: parseUid(to),
     });
-    return formatPageOutput(snapshot, "drag", undefined, full);
+    return formatPageOutput(snapshot, "drag", undefined, full, raw);
 }
-async function handleFillForm(args, full) {
+async function handleFillForm(args, full, raw = false) {
     const { entries } = parseFillFormArgs(args);
     if (entries.length === 0) {
         throw new CdpError("No valid field entries", "VALIDATION_ERROR", [
@@ -1226,7 +1281,7 @@ async function handleFillForm(args, full) {
         ]);
     }
     const snapshot = await callWithSnapshot("fill_form", { elements: entries });
-    return formatPageOutput(snapshot, "fillform", undefined, full);
+    return formatPageOutput(snapshot, "fillform", undefined, full, raw);
 }
 async function handleDialog(args) {
     const action = args[0];
@@ -1242,7 +1297,7 @@ async function handleDialog(args) {
     await callTool("handle_dialog", params);
     return encode({ dialog: action });
 }
-async function handleUpload(args, full) {
+async function handleUpload(args, full, raw = false) {
     const uid = args[0];
     const filePath = args[1];
     if (!uid) {
@@ -1259,7 +1314,7 @@ async function handleUpload(args, full) {
         uid: parseUid(uid),
         filePath,
     });
-    return formatPageOutput(snapshot, "upload", undefined, full);
+    return formatPageOutput(snapshot, "upload", undefined, full, raw);
 }
 // --- Emulation handler ---
 async function handleEmulate(args) {
@@ -1835,19 +1890,57 @@ function requireNeon(command) {
     ]);
 }
 /**
- * Opera Neon returns the "not signed in" message as text content on a
- * successful tool call (no MCP isError flag), so callTool resolves rather
- * than throws. Detect it here and convert to a CdpError so the UX matches
- * the thrown-error path.
+ * Error conditions that Opera returns as plain text content on a successful
+ * tool call (no MCP isError flag). Each descriptor is checked in order;
+ * the first match is converted to a CdpError.
  */
-function checkAiResultForSignInError(command, result) {
-    if (result.includes("User is not signed in") ||
-        (result.includes("Opera.dispatchAction") &&
-            result.includes("not signed in"))) {
-        throw new CdpError("Opera: user is not signed in", "BROWSER_ERROR", [
-            `Re-run \`opera-browser-cli ${command}\` after signing in`,
+const CDP_RESULT_ERRORS = [
+    {
+        match: (r) => r.includes(CdpResultErrorKey.NOT_SIGNED_IN),
+        message: "Opera: user is not signed in",
+        code: "BROWSER_ERROR",
+        suggestions: (cmd) => [
+            `Re-run \`opera-browser-cli ${cmd}\` after signing in`,
             "Run `opera-browser-cli doctor` to inspect the current configuration",
-        ]);
+        ],
+    },
+    {
+        match: (r) => r.includes(CdpResultErrorKey.SUBSCRIPTION_REQUIRED),
+        message: "Opera: an active subscription is required",
+        code: "BROWSER_ERROR",
+        suggestions: (cmd) => [
+            "Check your Opera subscription at https://auth.opera.com/account/",
+            `Re-run \`opera-browser-cli ${cmd}\` after activating a subscription`,
+        ],
+    },
+    {
+        match: (r) => r.includes(CdpResultErrorKey.CONSENT_REQUIRED),
+        message: "Opera: user consent has not been accepted",
+        code: "BROWSER_ERROR",
+        suggestions: (cmd) => [
+            "Open Opera and accept the consent prompt before using AI features",
+            `Re-run \`opera-browser-cli ${cmd}\` after accepting consent`,
+        ],
+    },
+    {
+        match: (r) => r.includes(CdpResultErrorKey.NEON_ONLY),
+        message: (cmd) => `Opera: ${cmd} is only available on Opera Neon`,
+        code: "BROWSER_ERROR",
+        suggestions: () => [
+            "Install Opera Neon from https://www.operaneon.com",
+            "Run `opera-browser-cli setup` to configure the Opera Neon executable path",
+            "Run `opera-browser-cli doctor` to inspect the current configuration",
+        ],
+    },
+];
+function checkAiResultForCdpError(command, result) {
+    for (const descriptor of CDP_RESULT_ERRORS) {
+        if (descriptor.match(result)) {
+            const message = typeof descriptor.message === "function"
+                ? descriptor.message(command)
+                : descriptor.message;
+            throw new CdpError(message, descriptor.code, descriptor.suggestions(command));
+        }
     }
 }
 async function callAiTool(command, name, args) {
@@ -1872,14 +1965,19 @@ async function callAiTool(command, name, args) {
     }
 }
 async function handleChat(args) {
-    const prompt = args.join(" ");
+    const { prompt, model } = parseChatArgs(args);
     if (!prompt) {
         throw new CdpError("Missing prompt", "VALIDATION_ERROR", [
             'Run `opera-browser-cli chat "What is on this page?"` to chat with Opera AI',
+            "Use --model <id> to select a model (run `opera-browser-cli models` to list)",
         ]);
     }
-    const result = await callAiTool("chat", "opera_chat", { prompt });
-    checkAiResultForSignInError("chat", result);
+    const toolArgs = { prompt };
+    if (model !== undefined) {
+        toolArgs["model"] = model;
+    }
+    const result = await callAiTool("chat", "opera_chat", toolArgs);
+    checkAiResultForCdpError("chat", result);
     return formatMcpResult("result", result, []);
 }
 async function handleInvokeDo(args) {
@@ -1891,7 +1989,7 @@ async function handleInvokeDo(args) {
     }
     requireNeon("invoke-do");
     const result = await callAiTool("invoke-do", "opera_do", { prompt });
-    checkAiResultForSignInError("invoke-do", result);
+    checkAiResultForCdpError("invoke-do", result);
     return formatMcpResult("result", result, []);
 }
 async function handleMake(args) {
@@ -1903,10 +2001,25 @@ async function handleMake(args) {
     }
     requireNeon("make");
     const result = await callAiTool("make", "opera_make", { prompt });
-    checkAiResultForSignInError("make", result);
+    checkAiResultForCdpError("make", result);
     return formatMcpResult("result", result, []);
 }
 const VALID_RESEARCH_TYPES = ["local", "one-minute", "deep"];
+export function parseChatArgs(args) {
+    let model;
+    const promptParts = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--model") {
+            if (i + 1 < args.length) {
+                model = args[++i];
+            }
+        }
+        else {
+            promptParts.push(args[i]);
+        }
+    }
+    return { prompt: promptParts.join(" "), model };
+}
 export function parseResearchArgs(args) {
     let researchType;
     const promptParts = [];
@@ -1937,9 +2050,28 @@ async function handleResearch(args) {
     if (researchType !== undefined)
         toolArgs.researchType = researchType;
     const result = await callAiTool("research", "opera_research", toolArgs);
-    checkAiResultForSignInError("research", result);
+    checkAiResultForCdpError("research", result);
     return formatMcpResult("result", result, []);
 }
+async function handleModels() {
+    requireNeon("models");
+    const raw = await callTool("opera_list_models", {});
+    checkAiResultForCdpError("models", raw);
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new CdpError(raw || "Model listing returned an invalid response", /Tool.*not found/i.test(raw) ? "UNSUPPORTED_OPERATION" : "UNKNOWN", ['Run `opera-browser-cli doctor` to check the connection']);
+    }
+    const lines = ["Available models:"];
+    for (const m of data.models) {
+        const marker = m.isDefault ? "* " : "  ";
+        const suffix = m.isDefault ? " (default)" : "";
+        lines.push(`  ${marker}${m.id}${suffix}`);
+    }
+    return lines.join("\n");
+}
 async function handleRun() {
     if (process.stdin.isTTY) {
         throw new CdpError("No script provided on stdin", "VALIDATION_ERROR", [
@@ -1968,7 +2100,7 @@ async function handleHome(_full) {
             renderHelp(help),
         ]);
     }
-    const snapshot = stripSnapshotHeader(result);
+    const snapshot = compactSnapshot(stripSnapshotHeader(result));
     const title = extractTitle(snapshot);
     const refs = countRefs(snapshot);
     const page = {};
@@ -1982,10 +2114,52 @@ async function handleHome(_full) {
     ];
     return renderOutput([encode({ page }), renderHelp(help)]);
 }
+async function handleUrl(args) {
+    const target = args[0];
+    if (!target) {
+        throw new CdpError("Missing argument", "VALIDATION_ERROR", [
+            "Run `opera-browser-cli url \\$u3` to resolve a URL token",
+            "Run `opera-browser-cli url @11.57` to resolve an element ref",
+        ]);
+    }
+    // Prefer the bridge's cached snapshot to avoid an extra MCP round-trip.
+    // Fall back to a fresh snapshot if the cache is cold.
+    let raw;
+    const cached = await getLastSnapshot();
+    if (cached) {
+        raw = cached.raw;
+    }
+    else {
+        await ensureBridge();
+        raw = stripSnapshotHeader(await callTool("take_snapshot"));
+    }
+    // Use the urlMap persisted at render time so token IDs match exactly what the
+    // agent saw (derived from the truncated snapshot). Fall back to re-derivation
+    // on the full snapshot only if the sidecar file is missing.
+    // Use compact (no LUT applied) as the body: ref lookups find literal url="..."
+    // values there, so token-index alignment with urlMap is not needed.
+    const compact = compactSnapshot(raw);
+    let urlMap;
+    try {
+        const stored = JSON.parse(readFileSync(join(getStateDir(), "last-url-map.json"), "utf-8"));
+        urlMap = new Map(Object.entries(stored));
+    }
+    catch {
+        ({ urlMap } = applyUrlLut(compact));
+    }
+    const body = compact;
+    const resolved = resolveUrl(body, urlMap, target);
+    if (resolved === null) {
+        process.stderr.write(`url: "${target}" not found in last snapshot\n`);
+        process.exitCode = 1;
+        return "";
+    }
+    return resolved;
+}
 function withFullFlag(handler) {
     return (args) => {
         const parsed = splitFullFlag(args);
-        return handler(parsed.args, parsed.full);
+        return handler(parsed.args, parsed.full, parsed.raw);
     };
 }
 function withoutFullFlag(handler) {
@@ -1993,14 +2167,15 @@ function withoutFullFlag(handler) {
 }
 const COMMANDS = {
     open: withFullFlag(handleOpen),
-    snapshot: async (args) => handleSnapshot(splitFullFlag(args).full),
+    snapshot: async (args) => { const f = splitFullFlag(args); return handleSnapshot(f.full, f.raw); },
+    url: withoutFullFlag(handleUrl),
     screenshot: withoutFullFlag(handleScreenshot),
     click: withFullFlag(handleClick),
     fill: withFullFlag(handleFill),
     type: withFullFlag(handleType),
     press: withFullFlag(handlePress),
     scroll: withFullFlag(handleScroll),
-    back: async (args) => handleBack(splitFullFlag(args).full),
+    back: async (args) => { const f = splitFullFlag(args); return handleBack(f.full, f.raw); },
     wait: withoutFullFlag(handleWait),
     eval: withFullFlag(handleEval),
     run: async () => handleRun(),
@@ -2030,6 +2205,7 @@ const COMMANDS = {
     "invoke-do": withoutFullFlag(handleInvokeDo),
     make: withoutFullFlag(handleMake),
     research: withoutFullFlag(handleResearch),
+    models: withoutFullFlag(handleModels),
     setup: withoutFullFlag(handleSetup),
     logs: withoutFullFlag(handleLogs),
     doctor: withoutFullFlag(handleDoctor),
@@ -2040,7 +2216,7 @@ function warnIfUnconfigured(argv) {
     if (cmd !== undefined && SETUP_SKIP_COMMANDS.has(cmd))
         return;
     const configFile = join(homedir(), ".opera-browser-cli", "config");
-    if (!existsSync(configFile) && !process.env.OPERA_CLI_EXECUTABLE_PATH) {
+    if (!existsSync(configFile) && !process.env.OPERA_CLI_EXECUTABLE_PATH && !process.env.OPERA_CLI_BROWSER_URL) {
         process.stderr.write("hint: run `opera-browser-cli setup` to configure (first-time setup)\n");
     }
 }