opera-devtools-mcp 0.7.0 → 0.8.1

package/build/src/opera/skills/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: opera-browser-cli
+description: Browser automation and web interaction using the opera-browser-cli tool. Use for navigating pages, clicking elements, filling forms, taking screenshots, inspecting console/network, running performance audits, and Opera AI features (chat available on any Opera browser; invoke_do, opera_make, opera_research require Opera Neon).
+metadata: {'openclaw': {'requires': {'bins': ['opera-browser-cli']}}}
+---
+
+# Skill: opera-browser-cli Browser Automation
+
+`opera-browser-cli` drives an Opera browser session through the
+`opera-devtools-mcp` daemon. Every command is an MCP tool name.
+
+- **Page and DevTools commands** (`new_page`, `take_snapshot`, `click`, `fill`,
+  `take_screenshot`, `list_pages`, `list_console_messages`,
+  `list_network_requests`, `lighthouse_audit`, the `*_heapsnapshot_*` family,
+  `emulate`, `screencast_start`, …) work with any Opera browser.
+- **`opera_chat`** — available on any Opera browser. Pass `--model <id>` to
+  select a model and `--conversation_id <id>` to continue a conversation. List
+  models with `opera_list_models`.
+- **`opera_do`, `opera_make`, `opera_research`** — require **Opera Neon** with an
+  active sign-in. `opera_make` accepts `--conversation_id <id>` to continue an
+  existing conversation.
+- **Opera AI MCP passthrough** (`opera_list_mcp_servers`, `opera_list_mcp_tools`,
+  `opera_call_mcp_tool`, `opera_register_mcp_server`, `opera_authenticate_mcp_server`,
+  `opera_unregister_mcp_server`, `opera_enable_mcp_server`,
+  `opera_disable_mcp_server`, `opera_connect_mcp_server`) — require Opera Neon.
+- **Research conversations are not resumable**: each research run creates a fresh
+  conversation with no `--conversation_id` flag. The ID it prints can be used
+  with `opera_chat` or `opera_make` for follow-ups in the same context.
+
+Run `opera-browser-cli --help` for the full command list, or
+`opera-browser-cli <command> --help` for one command's positionals and flags.
+
+```bash
+opera-browser-cli new_page https://example.com   # start here
+```
+
+## Calling convention
+
+Required parameters are **positional**; optional ones are `--flags`. Tool
+parameter names are snake_case, exactly as the MCP tool declares them.
+
+```bash
+opera-browser-cli click 1_4 --dblClick true   # NOT: click --uid 1_4
+```
+
+Run `opera-browser-cli <command> --help` to see the exact shape.
+
+Element refs are accepted in either form — `@2.4` as the snapshot prints it, or
+the wire form `2_4` — on `click`, `fill`, `hover`, `drag`, `upload_file`,
+`take_screenshot --uid`, and `url`.
+
+## Snapshot format
+
+Snapshots are **compact** by default: internal role names are shortened, refs use
+the `@PAGE.ELEM` form (e.g. `@2.4`), headings become markdown, and redundant ARIA
+attributes are stripped. Every command that returns a snapshot also prints
+contextual `help[N]:` suggestions for the next step.
+
+Pass `--raw` on any command to get the unprocessed MCP output instead, or
+`--full` to keep the complete snapshot without truncation.
+
+Repeated or very long URLs in compact output are replaced with `$uN` tokens, and
+a `urls:` trailer lists what each token resolves to. Both the body and the
+trailer keep the shortened (origin-stripped) form; `url` prints the full URL:
+
+```
+  @2.4 link "Download" url=$u1
+  ...
+urls:
+  $u1 /downloads/installer-v3.2.1-x86_64.tar.gz
+```
+
+```bash
+opera-browser-cli url $u1     # answered from the last snapshot's token map — no round-trip
+opera-browser-cli url @2.4    # a ref is page state, so this takes a fresh snapshot
+```
+
+## The configured profile is already open
+
+If Opera is already running on the profile `setup` selected — normally, without
+a debugging port — the CLI cannot launch a second browser on it. It asks before
+each command that has to pick a browser:
+
+- On a terminal: `[1]` restarts Opera with a debugging port (tabs are restored),
+  `[2]` runs this command on a separate profile where the user is not signed in.
+- With no terminal (which is how agents run it): `[2]`, no prompt. A note on
+  stderr names the profile it used instead.
+
+`--takeover` restarts Opera without asking, for scripted callers. It closes and
+reopens a browser the user may be using — pass it only with the user's
+agreement, never as a retry. A daemon that is already running keeps the browser
+it started with, so the question only comes up when one is being started, or on
+`start`.
+
+The same settling happens when a command fails with `A browser is already
+running with the profile …`: the command is retried once on the browser that was
+chosen, so that error is not something to work around. If it comes back again,
+the conflict could not be settled — report it rather than retrying.
+
+## Long-running Opera AI commands stream
+
+`opera_chat`, `opera_do`, `opera_make`, `opera_research`,
+`opera_call_mcp_tool`, and `opera_authenticate_mcp_server` write their partial
+output to **stderr** as it arrives; the final result goes to stdout.
+
+A dropped connection mid-call is **not** retried for these six. They are
+long-running, may be billable, and may already have acted on the page, so a
+silent second run could double a booking as easily as it could double a bill.
+Ask the user before re-running one.
+
+## Exit codes
+
+Branch on the exit code rather than parsing messages:
+
+| Code | Meaning                                             | What to do                                         |
+| ---- | --------------------------------------------------- | -------------------------------------------------- |
+| 0    | Success                                             | —                                                  |
+| 2    | Bad arguments, or the browser cannot do this        | Fix the command; do not retry as-is                |
+| 3    | Environment not ready (daemon, browser, connection) | Run `opera-browser-cli doctor`                     |
+| 4    | Sign-in, subscription, or consent needed            | Ask the user — you cannot fix this                 |
+| 5    | Timed out                                           | Retry                                              |
+| 6    | Stale element ref, or a closed page                 | Re-run `take_snapshot`, then retry with fresh refs |
+| 1    | Anything else                                       | Report it                                          |
+
+## Configuration
+
+```bash
+opera-browser-cli setup                    # interactive; writes ~/.opera-browser-cli/config
+opera-browser-cli setup --non-interactive  # detect and write, no prompts
+opera-browser-cli doctor                   # inspect config, browser, daemon, log
+opera-browser-cli doctor --fix             # repair what needs no decision
+opera-browser-cli logs                     # tail the daemon log
+opera-browser-cli logs --errors --follow   # just the failures, streaming
+```
+
+Settings live in `~/.opera-browser-cli/config` as `KEY="VALUE"` lines, and are
+also readable from the environment (the environment wins):
+
+| Key                         | Meaning                                                              |
+| --------------------------- | -------------------------------------------------------------------- |
+| `OPERA_CLI_EXECUTABLE_PATH` | Opera binary to launch                                               |
+| `OPERA_CLI_USER_DATA_DIR`   | Persistent profile directory (an explicit `--isolated` wins over it) |
+| `OPERA_CLI_HEADED`          | `1` to run headed (visible)                                          |
+| `OPERA_CLI_CHROME_ARGS`     | Whitespace-separated Chromium flags                                  |
+| `OPERA_CLI_BROWSER_URL`     | Attach to an already-running browser instead of launching            |
+
+The config file is a cache of decisions, never a prerequisite: the first command
+on a fresh machine detects the installed browser and configures itself.
+
+## Recovery is automatic
+
+The daemon starts on demand and restarts itself on version skew, a crash, or a
+dropped connection. Do not run `stop` speculatively — re-run the command. `stop`
+exists for cleanup at the end of a session.
+
+## Sign-in errors
+
+If an Opera AI command exits `4`, tell the user to sign in to their Opera account
+in a visible window. `opera-browser-cli doctor` reports the configuration that
+the AI tools depend on.

package/build/src/opera/streamingTools.js

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * The tools whose output arrives in pieces, and the ones that must not be
+ * replayed.
+ *
+ * Ported from opera-browser-cli's `src/client.ts` (`OPERA_AI_TOOLS`,
+ * `NON_REPLAYABLE_TOOLS`, `OPERA_AI_TIMEOUT`). The set is the same on both
+ * sides of the bridge: the browser streams `notifications/message` chunks while
+ * these run, and a dropped connection part-way through is never retried — the
+ * call may already have acted on the page or billed the account, so a silent
+ * second run could double a booking as easily as it could double a bill.
+ */
+/** Tools that stream partial output and get the long timeout. */
+export const OPERA_AI_TOOLS = {
+    opera_chat: true,
+    opera_do: true,
+    opera_research: true,
+    opera_make: true,
+    opera_call_mcp_tool: true,
+    opera_authenticate_mcp_server: true,
+};
+/**
+ * Tools that must never be replayed after a dropped connection.
+ *
+ * `sendCommand` is single-shot by construction (no retry loop), so this is the
+ * contract a test pins rather than a branch in the CLI.
+ */
+export const NON_REPLAYABLE_TOOLS = OPERA_AI_TOOLS;
+/** 20 minutes: a research run can legitimately take longer than any other tool. */
+export const OPERA_AI_TIMEOUT_MS = 1_200_000;
+/**
+ * How long a streamed action may report *nothing at all* before it is treated
+ * as one that never started.
+ *
+ * The browser's contract for these actions is an ack, then events: chunks while
+ * it works, and a completion or a failure at the end. `do` streams within
+ * seconds of its ack. An action that has emitted no event at all for five
+ * minutes is not a slow run — it is the failure a research tab sitting open
+ * with no prompt in it represents — and waiting out the twenty-minute cap only
+ * hides it. The deadline covers the first event alone: once one arrives the run
+ * is the browser's to finish, and a research run may legitimately be quiet
+ * before and between chunks.
+ *
+ * Mutable so tests can drive the deadline without waiting on real time, like
+ * `serviceWorkerRetryPolicy`.
+ */
+export const operaAiStreamPolicy = {
+    firstEventTimeoutMs: 300_000,
+};
+/** Whether `toolName` is one of those long-running, streamed tools. */
+export function isOperaAiTool(toolName) {
+    return Object.hasOwn(OPERA_AI_TOOLS, toolName);
+}
+/**
+ * The request timeout `toolName` gets, or `undefined` for the caller's default.
+ *
+ * Both ends of the chain have to ask this question, because both enforce a
+ * timeout of their own and the *shorter* one decides: the CLI's `sendCommand`
+ * on the socket, and the daemon's MCP client around `tools/call`. The daemon
+ * used to be left on the SDK's 60-second default, so a research run was killed
+ * there while the CLI was still waiting out its twenty minutes — and because a
+ * timed-out MCP request is cancelled, the tool was aborted mid-run in the
+ * browser too.
+ */
+export function operaAiTimeoutMs(toolName) {
+    return isOperaAiTool(toolName) ? OPERA_AI_TIMEOUT_MS : undefined;
+}
+//# sourceMappingURL=streamingTools.js.map

package/build/src/opera/suggestions.js

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+import { CLI_BIN_NAME } from './branding.js';
+import { extractRefs, isInputType } from './compactSnapshot.js';
+/**
+ * A label that means "this button submits the form".
+ *
+ * Anchored, because the label is prose: `Sign in` and `Sign up` are submits, but
+ * `Sponsor`, `Booking` and `Register` merely contain `ok`, `go` and `sign`, and
+ * treating them as submits both suggests the wrong button after a `fill` and
+ * skips them when suggesting what else to click.
+ */
+const SUBMIT_LABEL_PATTERN = /\b(?:submit|search|go|send|login|sign|ok)\b/i;
+export function getSuggestions(ctx) {
+    // Commands without auto-snapshot — suggest viewing page state
+    if (ctx.command === 'wait' || ctx.command === 'eval') {
+        return [`Run \`${CLI_BIN_NAME} snapshot\` to see current page state`];
+    }
+    const refs = ctx.snapshot ? extractRefs(ctx.snapshot) : [];
+    const links = refs.filter(r => r.type === 'link');
+    const buttons = refs.filter(r => r.type === 'button');
+    const inputs = refs.filter(r => isInputType(r.type));
+    const lines = [];
+    // After filling a field, suggest submitting
+    if (ctx.command === 'fill') {
+        const submitBtn = buttons.find(r => SUBMIT_LABEL_PATTERN.test(r.label));
+        if (submitBtn) {
+            lines.push(`Run \`${CLI_BIN_NAME} click @${submitBtn.ref}\` to click "${submitBtn.label}"`);
+        }
+        else {
+            lines.push(`Run \`${CLI_BIN_NAME} press Enter\` to submit the form`);
+        }
+    }
+    // Suggest filling inputs (unless we just filled one)
+    if (inputs.length > 0 && ctx.command !== 'fill') {
+        const inp = inputs[0];
+        const label = inp.label ? `the "${inp.label}" field` : 'the input field';
+        lines.push(`Run \`${CLI_BIN_NAME} fill @${inp.ref} "text"\` to fill ${label}`);
+    }
+    // Suggest clicking buttons
+    if (buttons.length > 0) {
+        const btn = ctx.command === 'fill'
+            ? (buttons.find(r => !SUBMIT_LABEL_PATTERN.test(r.label)) ?? buttons[0])
+            : buttons[0];
+        if (btn && !lines.some(l => l.includes(`@${btn.ref}`))) {
+            const label = btn.label ? `"${btn.label}" ` : '';
+            lines.push(`Run \`${CLI_BIN_NAME} click @${btn.ref}\` to click the ${label}button`);
+        }
+    }
+    // Suggest clicking links
+    if (links.length > 0) {
+        const link = links[0];
+        lines.push(`Run \`${CLI_BIN_NAME} click @${link.ref}\` to click the "${link.label}" link`);
+    }
+    // Suggest scrolling if page has many elements
+    if (refs.length > 5) {
+        lines.push(`Run \`${CLI_BIN_NAME} scroll down\` to scroll down`);
+    }
+    // Teach eval syntax — use IIFE for multi-statement logic
+    lines.push(`Use \`${CLI_BIN_NAME} eval <expr>\` for JS expressions. For multi-statement code, wrap in an IIFE: \`eval "(() => { ...; return result })()"\``);
+    return lines;
+}
+//# sourceMappingURL=suggestions.js.map

package/build/src/opera/toolHandlerHooks.js

@@ -5,6 +5,8 @@
  * This file is an original work developed by Opera.
  */
 import { ToolCategory } from '../tools/categories.js';
+import { logger } from '../utils/logger.js';
+import { noteToolFinished, noteToolStarted } from './browserActivity.js';
 import { ensureBrowserFlagsForTool } from './browserFlags.js';
 export function createOperaToolHooks(deps) {
     return {
@@ -12,25 +14,47 @@ export function createOperaToolHooks(deps) {
             return tool.annotations.category === ToolCategory.OPERA;
         },
         async beforeInvoke(tool) {
+            // Claimed before the flags are ensured, so the relaunch this may perform
+            // can see who else is using the browser — itself included.
+            noteToolStarted(tool.name);
             await ensureBrowserFlagsForTool(tool.name, deps.serverArgs, deps.logFile, { resetContext: deps.resetContext });
         },
+        afterInvoke(tool) {
+            noteToolFinished(tool.name);
+        },
         makeLogCallback(extra) {
             const sendNotification = extra?.sendNotification;
             if (!sendNotification) {
                 return undefined;
             }
+            const streamToken = extra?._meta?.streamToken;
             return (message) => {
                 // `logger` carries the MCP request ID so the opera-cli bridge can route
                 // this chunk to the correct HTTP response (see bridge.ts requestLoggers).
                 // `data` stays a plain string so non-bridge MCP hosts (Claude Desktop,
                 // VS Code, etc.) continue to render it as readable text.
-                void sendNotification.call(extra, {
+                sendNotification
+                    .call(extra, {
                     method: 'notifications/message',
                     params: {
                         level: 'info',
                         data: message,
                         logger: String(extra?.requestId),
+                        // Echoed back so the daemon can route the chunk to the request
+                        // that asked for streaming — see `opera/daemonStreaming.ts`.
+                        ...(typeof streamToken === 'string'
+                            ? { _meta: { streamToken } }
+                            : {}),
                     },
+                })
+                    // Best-effort, and never a rejection: `sendNotification` rejects when
+                    // the transport has already closed, and an unhandled rejection lands in
+                    // the daemon's `unhandledRejection` handler, which tears the session
+                    // down — so one undeliverable chunk would cost the whole run, and the
+                    // supervisor respawning the MCP server would make a burst of them a
+                    // supervision loop. Losing the chunk costs the user that line only.
+                    .catch(error => {
+                    logger?.('Opera AI chunk not delivered:', error);
                 });
             };
         },

package/build/src/opera/tools/opera.js

@@ -4,55 +4,124 @@
  *
  * This file is an original work developed by Opera.
  */
-import { zod } from '../../third_party/index.js';
+import { CDPSessionEvent, zod } from '../../third_party/index.js';
 import { ToolCategory } from '../../tools/categories.js';
 import { definePageTool } from '../../tools/ToolDefinition.js';
 import { withServiceWorkerRetry } from '../serviceWorkerRetry.js';
+import { operaAiStreamPolicy } from '../streamingTools.js';
 const getCDPSession = (page) => page._client();
 const dispatchAction = async (session, payload) => {
     const response = (await withServiceWorkerRetry(() => session.send('Opera.dispatchAction', { payload })));
     return response.result;
 };
+/**
+ * Dispatch a streamed action and wait for the browser to report it finished.
+ *
+ * The dispatch reply and the action's own events are separate messages, and the
+ * events can be delivered before the reply — or in the same read as it, which
+ * the SDK dispatches before the promise callback that learns the correlationId
+ * can run. Until that id arrives there is nothing to match an event against, so
+ * the listeners are attached before the dispatch is sent and whatever arrives
+ * meanwhile is held and replayed. Without that, an action that answers inside
+ * the dispatch round trip loses its completion and the caller waits for an
+ * event the browser has already sent.
+ */
 const dispatchWithStreamedResponse = (session, payload, onChunkCallback, signal) => {
-    return withServiceWorkerRetry(() => session.send('Opera.dispatchWithStreamedResponse', { payload })).then(raw => {
-        const { correlationId } = raw;
-        return new Promise((resolve, reject) => {
-            const onChunk = (params) => {
-                const { correlationId: id, chunk } = params;
-                if (id === correlationId && onChunkCallback) {
-                    onChunkCallback(chunk);
-                }
-            };
-            const onCompleted = (params) => {
-                const { correlationId: id, result } = params;
-                if (id === correlationId) {
-                    cleanup();
-                    resolve(result);
-                }
-            };
-            const onFailed = (params) => {
-                const { correlationId: id, error } = params;
-                if (id === correlationId) {
-                    cleanup();
-                    reject(new Error(error));
-                }
-            };
-            const cleanup = () => {
-                session.off('Opera.actionChunk', onChunk);
-                session.off('Opera.actionCompleted', onCompleted);
-                session.off('Opera.actionFailed', onFailed);
-            };
-            if (signal?.aborted) {
-                reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        /** Events that arrived before `correlationId` was known, in arrival order. */
+        const early = [];
+        let correlationId;
+        let settled = false;
+        let firstEventTimer;
+        const cleanup = () => {
+            clearTimeout(firstEventTimer);
+            session.off('Opera.actionChunk', onChunk);
+            session.off('Opera.actionCompleted', onCompleted);
+            session.off('Opera.actionFailed', onFailed);
+            session.off(CDPSessionEvent.Disconnected, onDisconnected);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const settle = (finish) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            finish();
+        };
+        /** Any event at all means the browser started the run; stop watching. */
+        const noteEvent = () => {
+            clearTimeout(firstEventTimer);
+            firstEventTimer = undefined;
+        };
+        const apply = (event) => {
+            if (settled) {
+                return;
+            }
+            const { correlationId: id } = event.params;
+            if (id !== correlationId) {
+                return;
+            }
+            noteEvent();
+            if (event.kind === 'chunk') {
+                const { chunk } = event.params;
+                onChunkCallback?.(chunk);
                 return;
             }
-            signal?.addEventListener('abort', () => {
-                cleanup();
-                reject(signal.reason);
-            }, { once: true });
-            session.on('Opera.actionChunk', onChunk);
-            session.on('Opera.actionCompleted', onCompleted);
-            session.on('Opera.actionFailed', onFailed);
+            if (event.kind === 'completed') {
+                const { result } = event.params;
+                settle(() => resolve(result));
+                return;
+            }
+            const { error } = event.params;
+            settle(() => reject(new Error(error)));
+        };
+        const receive = (event) => {
+            if (settled) {
+                return;
+            }
+            if (correlationId === undefined) {
+                // Held, not attributable — but it is still the browser working, and
+                // attributing it later must not re-arm a deadline it already beat.
+                noteEvent();
+                early.push(event);
+                return;
+            }
+            apply(event);
+        };
+        // Named rather than inlined into `session.on`: `cleanup` has to hand the
+        // same identities back to `off`, or the listeners outlive the call.
+        const onChunk = (params) => receive({ kind: 'chunk', params });
+        const onCompleted = (params) => receive({ kind: 'completed', params });
+        const onFailed = (params) => receive({ kind: 'failed', params });
+        const onDisconnected = () => settle(() => reject(new Error('CDP session disconnected')));
+        const onAbort = () => settle(() => reject(signal?.reason));
+        session.on('Opera.actionChunk', onChunk);
+        session.on('Opera.actionCompleted', onCompleted);
+        session.on('Opera.actionFailed', onFailed);
+        session.on(CDPSessionEvent.Disconnected, onDisconnected);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) {
+            settle(() => reject(signal.reason));
+            return;
+        }
+        // Armed before the dispatch is sent, not before its ack: a browser that
+        // took the dispatch and did nothing with it — no ack, no events — is the
+        // same failure from here, and this is the only deadline that sees it.
+        const { firstEventTimeoutMs } = operaAiStreamPolicy;
+        firstEventTimer = setTimeout(() => {
+            settle(() => reject(new Error(`Opera did not start the ${String(payload['action'])} action: no progress was reported for ${Math.round(firstEventTimeoutMs / 1000)}s after the dispatch`)));
+        }, firstEventTimeoutMs);
+        withServiceWorkerRetry(() => session.send('Opera.dispatchWithStreamedResponse', { payload }))
+            .then(raw => {
+            const { correlationId: id } = raw;
+            correlationId = id;
+            for (const event of early.splice(0)) {
+                apply(event);
+            }
+        })
+            .catch(error => {
+            settle(() => reject(error));
         });
     });
 };

package/build/src/opera/urlResolver.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * `url` — resolve a `$uN` URL token or an `@ref` element ref back to the full
+ * URL. Both forms are shortened for the snapshot (same-site URLs lose their
+ * origin, repeated/long ones become tokens), so the page origin is re-attached
+ * here before the URL is printed.
+ *
+ * Ported from opera-browser-cli's `src/cli.ts` `handleUrl`. The source read the
+ * bridge's cached `/last-snapshot`; here the token→URL map and the origin are
+ * persisted next to the config on every rendered snapshot (`cliOutput.ts`'s
+ * `writeUrlMapSidecar`, one file per session), so a token is answerable with no
+ * round-trip at all.
+ *
+ * An element ref is different: it is only resolvable against the tree it came
+ * from, so that path always asks for one. The narrowed `take_snapshot` fetch is
+ * injected by the CLI, which knows how to bring the daemon up.
+ */
+import { absolutizeUrl, applyUrlLut, compactSnapshot, extractPageOrigin, refToDisplay, refToMcp, resolveUrl, } from './compactSnapshot.js';
+import { CLI_BIN_NAME } from './branding.js';
+import { loadUrlMapSidecar } from './cliOutput.js';
+import { CdpError, EXIT_CODES } from './cdpErrors.js';
+export async function handleUrl(args, fetchSnapshot, sessionId) {
+    const target = args[0];
+    if (!target) {
+        throw new CdpError('Missing argument', 'VALIDATION_ERROR', [
+            `Run \`${CLI_BIN_NAME} url $u3\` to resolve a URL token`,
+            `Run \`${CLI_BIN_NAME} url @11.57\` to resolve an element ref`,
+        ]);
+    }
+    const persisted = loadUrlMapSidecar(sessionId);
+    // A token is `$uN` and never carries `@` — that is a ref marker, so the two
+    // shapes stay disjoint and `url @$u2` is answered like any other bad ref.
+    if (persisted && target.startsWith('$u')) {
+        const resolved = resolveUrl('', persisted.tokens, target);
+        if (resolved !== null) {
+            return {
+                output: absolutizeUrl(resolved, persisted.origin),
+                exitCode: 0,
+            };
+        }
+    }
+    // The body is the compact, *non-LUT* tree: a ref lookup searches for the
+    // element's literal `url="..."`, so token-index alignment with the map is not
+    // needed. The map is only consulted for refs whose URL was tokenised.
+    //
+    // The raw tree is kept because it is the only place the page origin still
+    // exists: compaction rewrites same-site URLs (root `url=` included) to
+    // relative paths, and `url`'s contract is the full URL.
+    const raw = await fetchSnapshot();
+    const origin = extractPageOrigin(raw) ?? persisted?.origin ?? null;
+    const body = compactSnapshot(raw);
+    const urlMap = persisted?.tokens ?? applyUrlLut(body).urlMap;
+    // The same translation the tool commands apply (refArgs.ts): the tree carries
+    // display-form refs, and `--raw` prints the wire form `4_11`, so accept both.
+    const resolved = resolveUrl(body, urlMap, `@${refToDisplay(refToMcp(target))}`);
+    if (resolved === null) {
+        return {
+            output: `url: "${target}" not found in last snapshot`,
+            exitCode: EXIT_CODES.REF_NOT_FOUND,
+        };
+    }
+    return { output: absolutizeUrl(resolved, origin), exitCode: 0 };
+}
+//# sourceMappingURL=urlResolver.js.map