qz-browser-agent 0.1.3 → 0.1.5

package/src/qz-drive-SKILL.md

@@ -0,0 +1,165 @@
+---
+name: qz-browser-agent
+description: Drive the connected browser through qz (轻舟) scripts. Create one titled session per task, pass its sessionId to every script, and bind each page with qz.tab(tabRef). Read qz skill for the installed CLI's guide. Read references/create-task.md only when the built-in agent should plan the task.
+---
+
+Use the installed `qz` command. If unavailable, use `npx -y qz-browser-agent@latest` in place of `qz` in the commands below. Run `qz skill` once at the start of a task for the matching guide. `qz --version` prints its version.
+
+<!-- qz-drive-guide:en -->
+The external agent plans the work and drives the connected browser through qz (轻舟). Do not configure a qz model or call `qz create`. Read references/create-task.md only when the built-in agent should plan and execute the task.
+
+## Connect
+
+Run commands with Node.js 22+ on the machine running the browser extension:
+
+```sh
+qz status --json
+```
+
+Session and script commands prepare the connection automatically: they reuse a responding online browser, or open the connection page once in the system default browser and wait for its extension to respond. Complete the extension's first-use notice and connection prompt when shown. If the extension is missing, `qz install` opens the store; ask the user to install it. When qz does not respond in that browser, the page offers the store and a copyable connection link, and a pending connection error carries the same link in `details.url`: ask the user which browser has qz installed, open the link there, and retry. Do not search browser profiles for the extension.
+
+When multiple browsers are registered, run `qz browsers --json` and pass `--client CLIENT_UUID` to select a profile explicitly. Existing sessions are located via read-only queries before execution; ambiguous or unavailable ownership requires explicit selection. To pair a specific profile without launching a browser, run `qz connect uri --name work --json` and open `result.url` in that profile. An incompatible local service is restarted once before browser operations; an incompatible extension requires updating the CLI and extension together.
+
+## One task uses one session
+
+Run `qz session create --title "Inspect example page"` first. A readable `--title` is required (omitting it exits 2). stdout prints `sessionId <id>`; with `--json`, read `result.sessionId`, and `result.qz_skills` lists the workflows available to the new session. Each call creates a fresh session without starting a model.
+
+Pass that same ID to every `qz script --session ID` call (missing `--session` exits 2). Scripts never create or resume a session implicitly. Use separate sessions for independent tasks. Run `qz session list` to list sessions and `qz session show ID` to read `{sessionId,title,status}`. If an ID is not found, check `qz session list` and the selected browser; never invent an ID.
+
+```sh
+CREATED=$(qz session create --title "Inspect example page" --json) || exit 1
+SID=$(printf '%s' "$CREATED" | node -e 'const x=JSON.parse(require("fs").readFileSync(0,"utf8")); if(!x.ok || !x.result.sessionId) process.exit(1); console.log(x.result.sessionId)') || exit 1
+qz script --session "$SID" - <<'JS'
+// Open one page and read its relevant text.
+const opened = await qz.openTab({ url: "https://example.com", tabAlias: "page" });
+return await qz.tab(opened).read({ limit: 3000 });
+JS
+```
+
+`qz.openTab({url,tabAlias?})` creates a page and returns a Tab `{tabRef,url,title,active}`; `qz.listTabs()` returns a list in `tabs`. `qz.tab(...)` binds an existing page using that Tab, its `tabRef`, or its optional alias. Aliases use 1–64 letters, digits, underscores, or hyphens (not all digits), and expire when the tab closes. Returned positive integers or numeric strings are valid references; never guess one. `active` marks the tab visible to the user and never selects an operation's target. Use `page.goto(url)` to navigate an existing task tab. `page.setMode("mobile")` switches to mobile mode (`"desktop"` restores it); a change reloads the page, so re-observe it afterward.
+
+One tab belongs to one session at a time. Use `qz.listTabs({scope:"all"})` for read-only inspection of other tabs, and a session-owned page for actions or evaluation. Binding a Page neither changes ownership nor selects the active tab.
+
+## Scripts and the qz SDK
+
+`qz script --session ID [FILE|-] [--args JSON]` runs JavaScript orchestration outside web pages. Read a local file or `-` for stdin; `--args` passes a JSON value exposed as `args`. Use top-level `await` and `return`, starting with a short comment stating the script's purpose. The outer script survives page navigation and provides `qz`, `args`, `trace()`, and `console`, without `document`/`window`, Node.js, `fs`, `process`, `require`, or `import`. Awaited SDK calls return business values directly and throw on failure.
+
+Bind `const page = qz.tab(tabRef)` and use:
+
+| Purpose | SDK methods |
+| --- | --- |
+| Navigation and page mode | `page.goto(url, options?)`, `page.close()`, `page.setMode(mode)` |
+| Focused observations | `page.read({limit,...})`, `page.find({role:"link",...})`, `page.axTree(options)`, `page.screenshot(options)` |
+| Page JavaScript | `page.evaluate(code, args?, options?)` |
+| State waits | `page.waitForURL(pattern, options?)`, `page.waitForLoad(options?)`, `page.waitForFunction(code, args?, options?)` |
+| Element operations | `page.locator(targetOrQuery)` with the methods below |
+
+Use `qz.listTools()` for compact signatures of additional capabilities and `qz.listTools({names:["list_images"]})` for selected full schemas, including declared `outputSchema` fields and examples. Invoke those capabilities through `qz.call(name, args)`, using their catalog names and explicit `tabRef` for page calls. Read unfamiliar schemas before calling and use declared return fields.
+
+`qz_skills` are browser workflows installed in the qz extension. `qz session create --json` returns their summaries in `result.qz_skills`, and each script receipt includes them in `context.qz_skills`: enabled user Global and Resident workflows, plus Site workflows matching sites visited by this task. Start a new site with a short observation script and check this catalog before further work. Global and Resident workflow tools are callable from session creation and appear in `qz.listTools()`; Site workflow tools become callable when the task visits a matching site. Load a relevant workflow with `return await qz.call("load_skill", {name:"skill-name"})`. Read its `content` and `tools`: each tool includes its exact calling `name`, description, input `parameters`, and declared `outputSchema` with examples. Loading activates those tools for the session immediately, so later calls in the same script can use them. Follow the workflow’s page prerequisites, then invoke `qz.call(name, args)` with those parameters and an explicit `tabRef` for page tools. After conversation compaction, reload the workflow if its instructions are missing. The catalog repeats on every receipt; full instructions are loaded on demand through qz, independently of the external agent's own Skill loader. Use `qz.call("list_skills", {url:"https://example.com"})` to query explicitly; omit `url` for all user workflows. Built-in Skills are hidden from discovery but remain loadable by name.
+
+Access page DOM and authenticated `fetch` inside self-contained `page.evaluate` or `page.waitForFunction` callbacks, including DOM reads used to build the outer return value. Their second argument supplies the function's input; return a JSON-serializable value. Closures, DOM nodes, functions, Page objects, and Locators cannot cross the page boundary.
+
+```sh
+qz script --session "$SID" --args '{"limit":1000}' - <<'JS'
+// Reuse the page opened earlier and read a compact DOM summary.
+const page = qz.tab("page");
+await page.goto("https://example.org");
+return await page.evaluate(
+  ({ limit }) => ({ title: document.title, text: document.body.innerText.slice(0, limit) }),
+  args
+);
+JS
+```
+
+Use outer SDK methods for clicks, form input, and navigation. `page.evaluate` waits for `DOMContentLoaded` by default (third argument `{waitUntil:"commit"}` allows early observation); wait for specific conditions when reading dynamic content. The page function has DOM access and cannot call the qz SDK. Navigating or closing its page can interrupt an in-flight evaluation; catch its error if the outer script should continue. Inspect completed state before retrying an uncertain action.
+
+## Observe, act, and verify
+
+Observe the relevant controls and choose the result needed by the next step. Use `page.read({limit})` for document text, lists, and tables, or a scoped `page.axTree(...)` / `page.find(...)` for controls. Element observations identify nodes by `target` (`uid:t<tab>.<snap>.<n>` or `css:...`); `rect` is `{x,y,width,height}`. Pass returned targets unchanged to `page.locator(target)`. A `uid:` always identifies its original node; navigation or DOM replacement can make it stale, requiring a new observation.
+
+Use search results as leads; verify key facts on the original pages. Include source URLs for key findings and make clear when evidence or coverage is incomplete.
+
+`page.locator(query)` stores a query and resolves it when an operation runs. Queries accept `target`, `role`, `name`, `text`, `exact`, `scope`, and `nth`; at least one of `target`, `role`, `name`, or `text` is required. The SDK accepts `{css:"#input"}` as shorthand for `{target:"css:#input"}`; use one form. CSS lists have one prefix for the whole expression (`"css:input, button"`). `name` matches the accessible name reported by `page.find` or `page.axTree`; `text` matches element text. Both normalize whitespace and match exactly, case-sensitively, by default; `exact:false` matches a substring. `scope` is an observed `uid:` or `css:` root, including a frame document reference. A pinned UID already identifies its scope; do not combine it with `scope`. Element operations require one match: narrow an ambiguous query or explicitly choose `locator.nth(index)` using a zero-based index.
+
+Locator methods are `click(options?)`, `doubleClick(options?)`, `hover(options?)`, `fill(value, options?)`, `press(key, options?)`, `select(value, options?)`, `check(options?)`, `uncheck(options?)`, `scroll(options?)`, and `dragTo(destination, options?)` on the same tab. Actions locate and wait for a usable element within their shared `timeout` budget (seconds, default 20, maximum 120), then dispatch once. Call the next locator operation directly; it handles readiness. Dispatched actions are never automatically replayed. Ordinary success returns `{}`, with `navigated`/`url` or `navigationPending` when navigation is detected, and `popups` for observed new Tabs. If `confirmationRequired` is true, verify the field locally before continuing.
+
+```js
+// Fill an observed form and choose its asynchronously appearing suggestion.
+const page = qz.tab("page");
+await page.locator(args.fieldTarget).fill(args.query);
+await page.locator({ role: "option", name: args.expectedOption }).click({ timeout: 10 });
+return await page.locator(args.fieldTarget).inspect();
+```
+
+Use `locator.inspect()` for current element state and `locator.read({limit})` for its text. `locator.wait({state:"visible",timeout:10})` waits for `attached`, `visible` (default), `hidden`, or `detached` state. Hidden includes removal or invisibility; detached requires removal. `locator.count()` reads the current attached match count, including hidden elements; `locator.wait({count:3,timeout:10})` waits for exactly that count, including zero. Use either `state` or `count` per wait. A match or count describes the current moment; it does not prove a dynamic list has finished updating.
+
+When an action must cause navigation or a popup, pass `waitFor:"navigation"` or `waitFor:"popup"` in its options. This installs the listener before dispatch. Navigation returns its observation; popup returns a Tab `{tabRef,url,title,active}` directly. A failed wait never replays the action.
+
+```js
+// Open a detail page and read it.
+const popup = await qz.tab("page").locator({ role: "link", name: "Details" })
+  .click({ waitFor: "popup", timeout: 10 });
+return await qz.tab(popup).read({ limit: 2000 });
+```
+
+Navigation waits observe new navigations, including reloads, SPA transitions, and hash changes. `page.waitForLoad()` checks the current load state; `page.waitForURL(pattern)` matches the full URL using a regular expression string or a `RegExp`. For in-page updates, use `page.waitForFunction(code, args?, options?)` to wait for the specific fields needed by the next step and return them. Keep action, condition, and focused result in one script. Match the requested item or mode as well as its required fields. Reserve fixed delays for tasks that require elapsed time.
+
+```js
+// Open a place's details. This page clears the old detail fields while loading.
+const page = qz.tab("page");
+await page.locator(args.itemTarget).click();
+return await page.waitForFunction(name => {
+  const panel = document.querySelector(".place-details");
+  const title = panel?.querySelector("h2")?.textContent?.trim();
+  const address = panel?.querySelector(".address")?.textContent?.trim();
+  return title === name && address ? { name: title, address } : null;
+}, args.place, { timeout: 20 });
+```
+
+Use selectors and fields observed on the page. If it retains previous values while loading, also wait for a completion signal that distinguishes the selected item's result.
+
+`page.find` returns an array of current element observations (up to `limit`), or `[]` when none match. Use normal array operations, e.g. `(await page.find({role:"link"})).slice(0,5)`; `waitFor:"match",timeout:10` waits for a candidate. Use `role`, `tag`, and `type` for single filters, or `roles`, `tags`, and `types` for multiple alternatives; use one form per filter. For example, `page.find({tag:"input",type:"search"})` finds search inputs. Its `pattern` accepts a regex string (case-insensitive by default) or a `RegExp`, as in `page.find({role:"link",pattern:/download/i})`; a `RegExp` supplies its own flags. Locator `name` and `text` match their specific fields. `page.axTree` uses `scope:"viewport"` or `"full"`; narrow `target` or `limit` when inspecting one control. Reserve screenshots for visual checks.
+
+Run one `qz script` at a time per session. Within it, use `await` for dependencies and `Promise.all` for independent page workflows. Same-page actions serialize; the caller sees results when the script returns. `Promise.all` preserves input order and rejects on first failure without cancelling siblings; use `Promise.allSettled` to retain every outcome. Await all calls before returning: exit cancels unfinished calls.
+
+```sh
+qz script --session "$SID" - <<'JS'
+// Open and read each page independently.
+return await Promise.all(
+  ["https://example.com", "https://example.org"].map(async url => {
+    const opened = await qz.openTab({ url });
+    return await qz.tab(opened).read({ limit: 1500 });
+  })
+);
+JS
+```
+
+Scripts are not transactions: completed actions remain in effect after a later failure. Return only the business data needed for the task. Use `trace()` at key checkpoints, such as completed stages and counts, to aid recovery. `trace` contains only errors and explicit `trace()`/`console` output, in order.
+
+## Documents and larger results
+
+For PDFs, load the document Skill before reading: call `qz.call("load_skill", {name:"qingzhou-documents"})`, and follow its schemas using the original PDF URL. PDF viewers do not support ordinary body reads or element actions. Keep returned `fileId`/`docModelId` values within the session and follow chunk cursors only as needed. `qz.call("load_skill_resource", {name,path})` parses packaged documents directly.
+
+Images and files remain in their artifact stores; return their references. Business results exceeding ~48,000 characters become `{truncated:true,totalChars,limitChars,preview}`; narrow the query or paginate instead of treating `preview` as complete. `ToolError` is never truncated.
+
+## Output and recovery
+
+stdout is JSON `{ok,result,trace}` on success and failure, with `context.qz_skills` for currently available user workflows when discovery succeeds. `ok` reports execution success; `result` is the returned business value (`null` for `undefined`) or the uncaught `{code,message,hint?,details?}` error (with script line/column in `details`); `trace` lists errors and explicit `trace()`/`console` messages in order, without levels. Exit codes: `0` success, `1` execution or connection failure, `2` invalid CLI arguments.
+
+`--timeout` sets script execution seconds (default `120`, range `>0` through `3600`); the request waits 60 seconds longer. Give the calling shell a longer deadline. A timeout or interrupted connection does not undo browser actions; inspect the session and page before repeating an action.
+
+- Disconnected: retry with the same `--session ID`; connection preparation is automatic. Use `qz connect uri` to pair a specific browser profile.
+- `DRIVE_SESSION_NOT_FOUND`: check `qz session list` and `--client`.
+- `DRIVE_SESSION_ENDED`: create a new session for a new task.
+- `DRIVE_SESSION_BUSY`: wait for the active operation to finish. Put concurrent page work inside one script with `Promise.all`.
+- `TAB_REF_REQUIRED`: bind `qz.tab(tabRef)` using a reference from `qz.openTab` or `qz.listTabs`.
+- Unknown alias or stale target: inspect `qz.listTabs()` or refresh the element observation. After a failed open, only reuse an alias if `qz.listTabs()` confirms it.
+- Login or challenge: stop and ask the user to complete it in the browser.
+
+## Finish
+
+Run `qz session cancel "$SID"` when the task is done. It ends the session and closes its created tabs (including while a script is running), while preserving pre-existing user tabs and tabs handed back to the user. To leave result pages open, pass their references with `--keep result --keep evidence`; all references are validated before stopping. Kept pages return to the user and the session still ends. Do not call `page.close()` after the session ends; further calls return `DRIVE_SESSION_ENDED`.
+
+Ctrl-C (`SIGINT`) or `SIGTERM` cancels the current script while preserving its session and tabs; already-dispatched browser actions may still finish and are not undone. CLI process exit does not close task tabs; ~30 minutes of inactivity triggers cleanup while the extension runtime is running. Always run `qz session cancel` for task cleanup. The side panel for a drive session is view-only. Use the qz SDK for page content and the shell for local files.
+<!-- qz-drive-guide:end -->

package/src/script-call.mjs

@@ -0,0 +1,40 @@
+export const SCRIPT_API_VERSION = 2;
+
+/** Script timeout stays at 120 unless --timeout is set. The request waits 60 seconds longer. */
+export function scriptTimeouts({ timeoutOption, timeoutSeconds = 180 } = {}) {
+  const scriptSeconds = timeoutOption === undefined ? 120 : Number(timeoutSeconds);
+  return { scriptSeconds, requestSeconds: scriptSeconds + 60 };
+}
+
+/** Build an outer script request; each page tool supplies its own tabRef. */
+export function buildScriptRequest({ code = "", timeoutSeconds = 120, sessionId = "", args = {} } = {}) {
+  const id = String(sessionId || "").trim();
+  if (!id) throw new Error("qz script requires --session <id>. Pass the sessionId from qz session create.");
+  return { name: "run_script", sessionId: id, scriptApiVersion: SCRIPT_API_VERSION, args: { timeout: timeoutSeconds, code: String(code), args } };
+}
+
+/** The execution envelope, never business keys, determines success. */
+export function presentScriptResult(payload) {
+  const receipt = payload?.result;
+  if (payload?.scriptApiVersion !== SCRIPT_API_VERSION || typeof payload.isError !== "boolean"
+    || !receipt || typeof receipt.ok !== "boolean" || payload.isError === receipt.ok
+    || !Object.hasOwn(receipt, "result") || receipt.result === undefined
+    || !Array.isArray(receipt.trace) || !receipt.trace.every(row => typeof row === "string")) {
+    return presentScriptFailure({ code: "UPGRADE_REQUIRED", message: "The connected extension uses an incompatible script API.",
+      hint: "The script may have run. Inspect the browser before retrying, then update the CLI and extension together and reconnect." });
+  }
+  return { text: JSON.stringify(receipt) + "\n", exitCode: receipt.ok ? 0 : 1 };
+}
+
+/** Local and transport failures have no script receipt; only their diagnostics become trace. */
+export function presentScriptFailure(error = {}) {
+  const { trace: hostTrace, ...details } = error.details || {};
+  const trace = Array.isArray(hostTrace) ? hostTrace.flatMap(row => typeof row === "string" ? [row]
+    : typeof row?.message === "string" ? [row.message] : []) : [];
+  const failure = {
+    code: String(error.code || "TOOL_EXECUTION_FAILED").toUpperCase(),
+    message: typeof error.message === "string" ? error.message : "Script failed.",
+    ...(error.hint ? { hint: error.hint } : {}), ...(Object.keys(details).length ? { details } : {}),
+  };
+  return { text: JSON.stringify({ ok: false, result: failure, trace }) + "\n", exitCode: 1 };
+}

package/src/server.mjs

@@ -3,18 +3,27 @@ import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest, isJSONRPCRequest } from "@modelcontextprotocol/sdk/types.js";
 import { BridgeState, PROTOCOL_VERSION } from "./state.mjs";
-import { INSTALL_URL } from "./package-info.mjs";
+import { CONNECT_PAGE, CONNECT_PAGE_CSP, CONNECT_LOGOS } from "./connect-page.mjs";
 import { createMcpServer } from "./tools.mjs";
 import { BrowserRegistry } from "./browser-registry.mjs";
 
+import { SCRIPT_API_VERSION } from "./script-call.mjs";
+
 const MAX_BODY_BYTES = 32 * 1024 * 1024;
-const CONNECT_PAGE = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Connect qz</title><style>body{font:16px/1.6 system-ui,sans-serif;max-width:38rem;margin:15vh auto;padding:24px;background:#fafafa;color:#202020}h1{font-size:28px;line-height:1.2}a{color:inherit}p{color:#555}</style><h1>Connect qz</h1><p data-qz-connection-status>Connecting to the qz browser extension…</p><p>Keep this page open while qz connects. If qz is not installed, <a href="${INSTALL_URL}" target="_blank" rel="noopener noreferrer">install qz from the Chrome Web Store</a>.</p></html>`;
 
 function sendJson(response, status, body, headers = {}) {
   response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", ...headers });
   response.end(JSON.stringify(body));
 }
 
+// Chrome origins stay `chrome-extension://` plus 32 characters from a-p.
+// Firefox origins are `moz-extension://` plus the lowercase UUID stored for the
+// gecko id in `extensions.webextensions.uuids`. The pairing token authenticates the profile.
+export function isExtensionBridgeOrigin(origin) {
+  return /^chrome-extension:\/\/[a-p]{32}$/.test(origin)
+    || /^moz-extension:\/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(origin);
+}
+
 async function readJson(request) {
   let length = 0;
   const chunks = [];
@@ -32,7 +41,7 @@ async function readJson(request) {
   }
 }
 
-export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId = randomUUID(), scopeId = "", buildId = "", onClose,
+export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId = randomUUID(), scopeId = "", buildId = "", pidNamespace = "", onClose,
   registryPath, registry, requestTimeoutSeconds = 180, connectWaitMs = 2000, mcpSessionIdleTimeoutMs = 30 * 60 * 1000 } = {}) {
   if (!["127.0.0.1", "localhost"].includes(host)) throw new Error("qz bridge must bind to loopback");
   if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error("Invalid bridge port");
@@ -86,8 +95,9 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
       }
       const path = new URL(request.url, state.endpoint).pathname;
       const origin = String(request.headers.origin || "");
-      // Browser sites cannot call the bridge. Only extension origins use poll/result routes.
-      if (origin && (path === "/mcp" || !/^chrome-extension:\/\/[a-p]{32}$/.test(origin))) {
+      // Browser sites cannot call the bridge. Extension origins may use poll/result routes.
+      // /mcp stays closed to every Origin so a page cannot open an MCP session.
+      if (origin && (path === "/mcp" || !isExtensionBridgeOrigin(origin))) {
         return sendJson(response, 403, { error: "invalid bridge origin" });
       }
       cors = origin ? {
@@ -99,16 +109,21 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
         return response.end();
       }
       if (request.method === "GET" && path === "/health") return sendJson(response, 200, {
-        ok: true, service: "qz-browser-agent", protocolVersion: PROTOCOL_VERSION, features: { browserPairing: 1 }, instanceId, scopeId, buildId, processId: process.pid, status: state.status(),
+        ok: true, service: "qz-browser-agent", protocolVersion: PROTOCOL_VERSION, features: { browserPairing: 1, scriptApiVersion: SCRIPT_API_VERSION }, instanceId, scopeId, buildId, processId: process.pid, status: state.status(),
+        ...(pidNamespace ? { pidNamespace } : {}),
       }, cors);
       if (request.method === "GET" && path === "/qz-connect") {
         response.writeHead(200, {
           "content-type": "text/html; charset=utf-8", "cache-control": "no-store",
-          "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; frame-ancestors 'none'",
+          "content-security-policy": CONNECT_PAGE_CSP,
           "x-content-type-options": "nosniff",
         });
         return response.end(CONNECT_PAGE);
       }
+      if (request.method === "GET" && CONNECT_LOGOS.has(path)) {
+        response.writeHead(200, { "content-type": "image/png", "cache-control": "public, max-age=86400", "x-content-type-options": "nosniff" });
+        return response.end(CONNECT_LOGOS.get(path));
+      }
       if (request.method === "POST" && String(request.headers["content-type"] || "").split(";")[0].trim().toLowerCase() !== "application/json") {
         return sendJson(response, 415, { error: "JSON content-type required" }, cors);
       }
@@ -130,7 +145,9 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
         let session = typeof sessionId === "string" ? sessions.get(sessionId) : undefined;
         const body = request.method === "POST" ? await readJson(request) : undefined;
         if (!session && !sessionId && request.method === "POST" && isInitializeRequest(body)) {
-          const mcp = createMcpServer(state);
+          const clientName = typeof body?.params?.clientInfo?.name === "string" ? body.params.clientInfo.name : "";
+          const profile = new URL(request.url || "/", "http://127.0.0.1").searchParams.get("profile") || "";
+          const mcp = createMcpServer(state, { clientName, profile });
           const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: randomUUID,
             onsessioninitialized: id => sessions.set(id, session),

package/src/state.mjs

@@ -11,16 +11,25 @@ const bounded = (value, fallback, min, max) => Number.isFinite(Number(value))
 
 export class BridgeError extends Error {
   constructor(code, message, details) {
-    super(`${code}: ${message}`);
-    this.code = code;
-    const fields = code === "DOWNLOAD_INTERRUPTED" ? ["downloadId", "filename", "reason"]
-      : code === "SKILL_NOT_FOUND" ? ["name"] : code === "SKILL_RESOURCE_NOT_FOUND" ? ["name", "path"] : [];
-    this.details = Object.fromEntries(fields.filter(key => typeof details?.[key] === "string" || typeof details?.[key] === "number")
-      .map(key => [key, details[key]]));
-    if (["SKILL_NOT_FOUND", "SKILL_RESOURCE_NOT_FOUND"].includes(code) && Array.isArray(details?.available)) {
+    super(message);
+    this.code = String(code || "BRIDGE_TOOL_ERROR").toUpperCase();
+    const fields = ["tabRef", "target", "line", "column", "trace",
+      ...(this.code === "DOWNLOAD_INTERRUPTED" ? ["downloadId", "filename", "reason"]
+        : ["SKILL_NOT_FOUND", "SKILL_NAME_AMBIGUOUS"].includes(this.code) ? ["name"]
+          : this.code === "SKILL_RESOURCE_NOT_FOUND" ? ["name", "path"] : [])];
+    this.details = Object.fromEntries(fields.filter(key => details?.[key] !== undefined).map(key => [key, details[key]]));
+    if (this.code === "SKILL_NAME_AMBIGUOUS" && Array.isArray(details?.candidates)) {
+      this.details.candidates = details.candidates.map(({ name, displayName }) => ({ name: String(name || ""), displayName: String(displayName || "") }));
+    }
+    if (["SKILL_NOT_FOUND", "SKILL_RESOURCE_NOT_FOUND"].includes(this.code) && Array.isArray(details?.available)) {
       this.details.available = details.available.filter(value => typeof value === "string");
     }
   }
+
+  toJSON() {
+    return { code: this.code, message: this.message,
+      ...(this.hint ? { hint: this.hint } : {}), ...(Object.keys(this.details).length ? { details: this.details } : {}) };
+  }
 }
 
 export class BridgeState {
@@ -42,7 +51,7 @@ export class BridgeState {
   }
 
   liveClients() {
-    return [...this.clients.values()].filter(client => now() - client.lastSeenAt <= client.pollLeaseSeconds);
+    return [...this.clients.values()].filter(client => client.pollLeaseSeconds > 0 && now() - client.lastSeenAt <= client.pollLeaseSeconds);
   }
 
   status() {
@@ -55,9 +64,13 @@ export class BridgeState {
       capabilities: client.capabilities || {},
       paired: Boolean(client.connectionId),
     })).sort((a, b) => a.clientId.localeCompare(b.clientId));
+    const connecting = [...this.clients.values()].filter(client => client.reconnectUntil > now()).map(client => ({
+      clientId: client.id, name: client.name, retryAfterMs: Math.ceil((client.reconnectUntil - now()) * 1000),
+    }));
     return {
       endpoint: this.endpoint, protocolVersion: PROTOCOL_VERSION, connected: clients.length > 0,
       clientCount: clients.length, clients, browsers: this.registry.list().map(entry => ({ ...entry, online: clients.some(client => client.clientId === entry.clientId) })), pending: this.pending.size, inflight: this.inflight.size,
+      ...(connecting.length ? { connecting } : {}),
       uptimeSeconds: rounded(now() - this.startedAt),
     };
   }
@@ -95,6 +108,10 @@ export class BridgeState {
       }
       const previous = this.clients.get(input.clientId);
       if (previous && this.liveClients().includes(previous) && previous.connectionId !== input.connectionId) {
+        if (sameToken(input.pairingToken, this.registry.entries.get(input.clientId)?.pairingToken)) {
+          previous.reconnectUntil = previous.lastSeenAt + previous.pollLeaseSeconds + 5;
+          this.events.emit("change");
+        }
         throw Object.assign(pairingError("BRIDGE_CLIENT_IN_USE", "This browser identity has an active connection. Wait for it to disconnect, or connect from a distinct browser profile."), {
           retryAfterMs: Math.max(1, Math.ceil((previous.lastSeenAt + previous.pollLeaseSeconds - now()) * 1000) + 1),
         });
@@ -102,8 +119,9 @@ export class BridgeState {
       const entry = await this.registry.pair(input);
       this.closed.signal.throwIfAborted();
       if (previous?.connectionId !== input.connectionId) this.revokeClient(input.clientId);
-      const client = this.clients.get(input.clientId) || { id: input.clientId, connectionId: input.connectionId, controller: new AbortController() };
-      Object.assign(client, { name: entry.name, lastSeenAt: now(), pollLeaseSeconds: 46 });
+      const client = this.clients.get(input.clientId) || { id: input.clientId, connectionId: input.connectionId, controller: new AbortController(), cancellations: new Map() };
+      Object.assign(client, { name: entry.name, lastSeenAt: now(), pollLeaseSeconds: 46, reconnectUntil: 0,
+        leaseRevision: (client.leaseRevision || 0) + 1 });
       this.clients.set(client.id, client);
       this.events.emit("change");
       return { ok: true, ...entry, connectionId: input.connectionId, instanceId: this.instanceId };
@@ -209,33 +227,53 @@ export class BridgeState {
   }
 
   async poll(client, { timeoutMs = 30000, maxBatch = 4, signal } = {}) {
-    const info = await this.serializeRegistration(() => {
+    const { info, leaseRevision } = await this.serializeRegistration(() => {
       this.signal(signal).throwIfAborted();
       if (client.pairingVersion !== 1) throw pairingError("BRIDGE_PAIRING_REQUIRED", "Update qz to use the supported pairing protocol.");
       const info = this.authenticatedClient(client);
+      info.pollCount = (info.pollCount || 0) + 1;
       this.touchClient(info, client, timeoutMs);
-      return info;
+      return { info, leaseRevision: info.leaseRevision };
     });
     const activeSignal = AbortSignal.any([this.signal(signal), info.controller.signal]);
-    activeSignal.throwIfAborted();
-    const deadline = Date.now() + bounded(timeoutMs, 30000, 100, 60000);
-    const limit = Math.floor(bounded(maxBatch, 4, 1, 16));
-    while (true) {
+    try {
       activeSignal.throwIfAborted();
-      const requests = [];
-      for (const [id, request] of this.pending) {
-        if (requests.length >= limit) break;
-        if (request.client !== info) continue;
-        this.pending.delete(id);
-        this.inflight.set(id, request);
-        requests.push({ id, method: request.method, params: request.params, timeoutMs: request.timeoutMs });
+      const deadline = Date.now() + bounded(timeoutMs, 30000, 100, 60000);
+      const limit = Math.floor(bounded(maxBatch, 4, 1, 16));
+      while (true) {
+        activeSignal.throwIfAborted();
+        const requests = [];
+        // Deliver cancellation before new work, on the connection that received the request.
+        for (const [id, expiresAt] of info.cancellations) {
+          if (expiresAt <= Date.now()) { info.cancellations.delete(id); continue; }
+          if (requests.length >= limit) break;
+          info.cancellations.delete(id);
+          requests.push({ id, method: "cancel_request" });
+        }
+        for (const [id, request] of this.pending) {
+          if (requests.length >= limit) break;
+          if (request.client !== info) continue;
+          this.pending.delete(id);
+          this.inflight.set(id, request);
+          requests.push({ id, method: request.method, params: request.params, timeoutMs: request.timeoutMs });
+        }
+        if (requests.length || Date.now() >= deadline) {
+          info.leaseRevision += 1;
+          return requests;
+        }
+        await this.waitForChange(deadline - Date.now(), activeSignal);
+      }
+    } finally {
+      info.pollCount -= 1;
+      // A closed transport releases its lease, while issued work retains its result authority.
+      if (signal?.aborted && this.clients.get(info.id) === info && !info.pollCount && info.leaseRevision === leaseRevision) {
+        info.pollLeaseSeconds = 0;
+        this.events.emit("change");
       }
-      if (requests.length || Date.now() >= deadline) return requests;
-      await this.waitForChange(deadline - Date.now(), activeSignal);
     }
   }
 
-  async callExtension(method, params = {}, { timeoutSeconds, clientId = "", signal } = {}) {
+  async callExtension(method, params = {}, { timeoutSeconds, clientId = "", signal, cancelOnAbort = false } = {}) {
     if (typeof method !== "string" || !method.trim()) throw new BridgeError("INVALID_ARGUMENTS", "method is required");
     const activeSignal = this.signal(signal);
     const seconds = bounded(timeoutSeconds || this.requestTimeoutSeconds, this.requestTimeoutSeconds, 1, 86400);
@@ -253,7 +291,16 @@ export class BridgeState {
         activeSignal.removeEventListener("abort", aborted);
         error ? reject(error) : resolve(result);
       };
-      const aborted = () => finish(activeSignal.reason);
+      const aborted = () => {
+        if (cancelOnAbort && this.inflight.has(id) && !this.closed.signal.aborted && !client.controller.signal.aborted) {
+          for (const [requestId, expiresAt] of client.cancellations) {
+            if (expiresAt <= Date.now()) client.cancellations.delete(requestId);
+          }
+          client.cancellations.set(id, Date.now() + seconds * 1000);
+        }
+        finish(activeSignal.reason);
+        this.events.emit("change");
+      };
       const timer = setTimeout(() => finish(new BridgeError("BRIDGE_REQUEST_TIMEOUT",
         `Request timed out after ${seconds}s: ${method}. A started operation may still be running; check its state before retrying.`)), seconds * 1000);
       activeSignal.addEventListener("abort", aborted, { once: true });
@@ -268,7 +315,12 @@ export class BridgeState {
     let client;
     try { client = this.authenticatedClient(payload); } catch { return false; }
     if (client !== request.client) return false;
-    if (payload.ok === false) request.finish(new BridgeError(payload.code || "BRIDGE_TOOL_ERROR", String(payload.error || "qz bridge request failed"), payload.details));
+    if (payload.ok === false) {
+      const failure = typeof payload.error === "object" && payload.error ? payload.error : payload;
+      request.finish(Object.assign(new BridgeError(failure.code || "BRIDGE_TOOL_ERROR",
+        String(failure.message || payload.error || "qz bridge request failed"), failure.details),
+        failure.hint ? { hint: failure.hint } : {}));
+    }
     else request.finish(null, payload.result);
     return true;
   }
@@ -289,7 +341,7 @@ export class BridgeState {
         job.result = await this.callExtension(method, params, { ...options, signal: options.connectionSignal });
         job.status = "completed";
       } catch (error) {
-        job.error = error.message || String(error);
+        job.error = Object.assign(new BridgeError(error.code || "BRIDGE_TOOL_ERROR", error.message || String(error), error.details), { hint: error.hint }).toJSON();
         job.status = "failed";
       }
       job.completedAt = now();

package/src/task-stream.mjs

@@ -72,7 +72,7 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
     const requestDeadline = Date.now() + milliseconds;
     const requestExpiresFirst = deadline === null || requestDeadline < deadline;
     const requestTimeout = Object.assign(new Error(`Reading task ${sessionId} timed out after ${requestTimeoutSeconds} seconds. Check the browser connection, then resume watching this task.`),
-      { code: "request_timeout" });
+      { code: "REQUEST_TIMEOUT" });
     // A request timeout ends observation too. One controller preserves the first reason,
     // and equal deadlines belong to the total timer. Downstream keeps its full request budget.
     const requestTimer = requestExpiresFirst ? setTimeout(() => controller.abort(requestTimeout), milliseconds) : null;
@@ -127,10 +127,10 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
       const snapshot = record(await readSnapshot());
       checkActive();
       if (snapshot.sessionId && snapshot.sessionId !== sessionId) {
-        throw Object.assign(new Error("The task snapshot belongs to a different session."), { code: "task_changed" });
+        throw Object.assign(new Error("The task snapshot belongs to a different session."), { code: "TASK_CHANGED" });
       }
       if (Object.hasOwn(snapshot, "session") && snapshot.session === null) {
-        throw Object.assign(new Error(TASK_NOT_FOUND_MESSAGE), { code: "task_deleted" });
+        throw Object.assign(new Error(TASK_NOT_FOUND_MESSAGE), { code: "TASK_DELETED" });
       }
       const runtime = record(snapshot.runtime);
       const canonicalInput = Object.hasOwn(snapshot, "input") ? record(snapshot.input) : null;
@@ -138,7 +138,7 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
       const status = taskStatus(snapshot);
       if (!status) {
         throw Object.assign(new Error("The task snapshot has no status. Check the browser connection, then resume watching this task."),
-          { code: "invalid_response" });
+          { code: "INVALID_RESPONSE" });
       }
       const transcript = Array.isArray(snapshot.transcript) ? snapshot.transcript : Array.isArray(snapshot.tail) ? snapshot.tail : [];
       const submittedMessageIndex = expectedMessageId