qz-browser-agent 0.1.0 → 0.1.2

package/src/server.mjs

@@ -2,11 +2,13 @@ import { createServer } from "node:http";
 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, PROJECT_URL } from "./state.mjs";
+import { BridgeState, PROTOCOL_VERSION } from "./state.mjs";
+import { INSTALL_URL } from "./package-info.mjs";
 import { createMcpServer } from "./tools.mjs";
+import { BrowserRegistry } from "./browser-registry.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="${PROJECT_URL}" target="_blank" rel="noopener noreferrer">install qz from GitHub</a>.</p></html>`;
+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 });
@@ -31,11 +33,11 @@ async function readJson(request) {
 }
 
 export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId = randomUUID(), scopeId = "", buildId = "", onClose,
-  requestTimeoutSeconds = 180, connectWaitMs = 2000, mcpSessionIdleTimeoutMs = 30 * 60 * 1000 } = {}) {
+  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");
   if (!Number.isFinite(mcpSessionIdleTimeoutMs) || mcpSessionIdleTimeoutMs <= 0) throw new Error("Invalid MCP session idle timeout");
-  const state = new BridgeState({ requestTimeoutSeconds, connectWaitMs });
+  const state = new BridgeState({ requestTimeoutSeconds, connectWaitMs, instanceId, registry: registry || await BrowserRegistry.open(registryPath) });
   const sessions = new Map();
   const mcpResponses = new Set();
   let actualPort;
@@ -76,6 +78,7 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
     response.once("close", disconnected);
   };
   const server = createServer(async (request, response) => {
+    let cors = {};
     try {
       if (closing) return sendJson(response, 503, { error: "The local bridge is stopping" });
       if (![ `127.0.0.1:${actualPort}`, `localhost:${actualPort}` ].includes(String(request.headers.host || "").toLowerCase())) {
@@ -87,7 +90,7 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
       if (origin && (path === "/mcp" || !/^chrome-extension:\/\/[a-p]{32}$/.test(origin))) {
         return sendJson(response, 403, { error: "invalid bridge origin" });
       }
-      const cors = origin ? {
+      cors = origin ? {
         "access-control-allow-origin": origin, vary: "Origin",
         "access-control-allow-methods": "GET, POST, OPTIONS", "access-control-allow-headers": "content-type",
       } : {};
@@ -96,7 +99,7 @@ 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, instanceId, scopeId, buildId, processId: process.pid, status: state.status(),
+        ok: true, service: "qz-browser-agent", protocolVersion: PROTOCOL_VERSION, features: { browserPairing: 1 }, instanceId, scopeId, buildId, processId: process.pid, status: state.status(),
       }, cors);
       if (request.method === "GET" && path === "/qz-connect") {
         response.writeHead(200, {
@@ -145,6 +148,10 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
         await session.transport.handleRequest(request, response, body);
         return;
       }
+      if (request.method === "POST" && ["/v1/qingzhou/pair", "/v1/qingzhou/rename", "/v1/qingzhou/disconnect"].includes(path)) {
+        const body = await readJson(request);
+        return sendJson(response, 200, await state[path.split("/").at(-1)](body), cors);
+      }
       if (request.method === "POST" && ["/v1/qingzhou/poll", "/v1/qingzhou/result"].includes(path)) {
         const body = await readJson(request);
         if (path.endsWith("/poll")) {
@@ -157,7 +164,7 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
               timeoutMs: client.pollTimeoutMs || body.pollTimeoutMs || 30000,
               maxBatch: client.maxBatch || body.maxBatch || 4, signal: controller.signal,
             });
-            if (!response.destroyed) sendJson(response, 200, { requests }, cors);
+            if (!response.destroyed) sendJson(response, 200, { requests, ...state.connectionInfo(client) }, cors);
           } finally {
             response.off("close", disconnected);
           }
@@ -169,7 +176,10 @@ export async function startBridge({ host = "127.0.0.1", port = 18765, instanceId
       }
       sendJson(response, 404, { error: "not found" }, cors);
     } catch (error) {
-      if (!response.destroyed && !response.headersSent) sendJson(response, error.status || 500, { ok: false, error: error.message });
+      if (!response.destroyed && !response.headersSent) sendJson(response, error.status || (error.code ? 409 : 500), {
+        ok: false, ...(error.code ? { code: error.code } : {}), error: error.message,
+        ...(error.code === "BRIDGE_CLIENT_IN_USE" && Number.isFinite(error.retryAfterMs) ? { retryAfterMs: error.retryAfterMs } : {}),
+      }, cors);
       else if (!response.destroyed) response.end();
     }
   });

package/src/state.mjs

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
+import { BrowserRegistry, browserName, isBrowserId, sameToken, pairingError } from "./browser-registry.mjs";
+import { INSTALL_URL } from "./package-info.mjs";
 
 export const PROTOCOL_VERSION = 1;
-export const PROJECT_URL = "https://github.com/alibaba/qz-browser-agent";
 const now = () => Date.now() / 1000;
 const rounded = value => Math.round(value * 1000) / 1000;
 const bounded = (value, fallback, min, max) => Number.isFinite(Number(value))
@@ -23,8 +24,11 @@ export class BridgeError extends Error {
 }
 
 export class BridgeState {
-  constructor({ endpoint = "http://127.0.0.1:18765", requestTimeoutSeconds = 180, connectWaitMs = 2000 } = {}) {
+  constructor({ endpoint = "http://127.0.0.1:18765", requestTimeoutSeconds = 180, connectWaitMs = 2000, instanceId = randomUUID(), registry = new BrowserRegistry() } = {}) {
     this.endpoint = endpoint;
+    this.instanceId = instanceId;
+    this.registry = registry;
+    this.registration = Promise.resolve();
     this.requestTimeoutSeconds = Math.max(1, requestTimeoutSeconds);
     this.connectWaitMs = connectWaitMs;
     this.clients = new Map();
@@ -49,33 +53,118 @@ export class BridgeState {
       extensionId: client.extensionId || "",
       name: client.name || "",
       capabilities: client.capabilities || {},
+      paired: Boolean(client.connectionId),
     })).sort((a, b) => a.clientId.localeCompare(b.clientId));
     return {
       endpoint: this.endpoint, protocolVersion: PROTOCOL_VERSION, connected: clients.length > 0,
-      clientCount: clients.length, clients, pending: this.pending.size, inflight: this.inflight.size,
+      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,
       uptimeSeconds: rounded(now() - this.startedAt),
     };
   }
 
-  enableSnippet(clientId = "") {
-    const config = {
-      enabled: true, endpoint: this.endpoint, pollIntervalMs: 500, pollTimeoutMs: 30000,
-      requestTimeoutMs: this.requestTimeoutSeconds * 1000, maxBatch: 4, includeCapabilities: true,
-      ...(clientId ? { clientId } : {}),
-    };
-    return `await chrome.storage.local.set({\n  "_qingzhou_mcp_bridge": ${JSON.stringify(config, null, 2)}\n});\nawait chrome.storage.local.get("_qingzhou_mcp_bridge");`;
+  serializeRegistration(operation) {
+    const result = this.registration.then(() => {
+      this.closed.signal.throwIfAborted();
+      return operation();
+    });
+    this.registration = result.catch(() => {});
+    return result;
+  }
+
+  requireInstance(instanceId) {
+    if (instanceId !== this.instanceId) throw pairingError("BRIDGE_INSTANCE_CHANGED", "The local service changed. Check its health and pair again.");
+  }
+
+  revokeClient(id, message = "The browser connection ended. Reconnect that browser before retrying.") {
+    const client = this.clients.get(id);
+    if (!client) return;
+    const error = pairingError("BRIDGE_CLIENT_DISCONNECTED", message);
+    this.clients.delete(id);
+    client.controller.abort(error);
+    for (const request of [...this.pending.values(), ...this.inflight.values()]) {
+      if (request.client === client) request.finish(error);
+    }
+    this.events.emit("change");
+  }
+
+  pair(input) {
+    return this.serializeRegistration(async () => {
+      this.requireInstance(input.instanceId);
+      if (!isBrowserId(input.clientId) || !isBrowserId(input.connectionId)) {
+        throw pairingError("INVALID_ARGUMENTS", "clientId and connectionId must be UUIDs.");
+      }
+      const previous = this.clients.get(input.clientId);
+      if (previous && this.liveClients().includes(previous) && previous.connectionId !== input.connectionId) {
+        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),
+        });
+      }
+      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 });
+      this.clients.set(client.id, client);
+      this.events.emit("change");
+      return { ok: true, ...entry, connectionId: input.connectionId, instanceId: this.instanceId };
+    });
+  }
+
+  authenticatedClient(input) {
+    this.requireInstance(input.instanceId);
+    const id = input.clientId || input.id;
+    const entry = this.registry.entries.get(id), client = this.clients.get(id);
+    if (!entry || !sameToken(input.pairingToken, entry.pairingToken) || !client?.connectionId
+      || client.connectionId !== input.connectionId) {
+      throw pairingError("BRIDGE_PAIRING_REQUIRED", "This browser connection is no longer paired. Connect again from the extension settings.");
+    }
+    return client;
+  }
+
+  connectionInfo(input) {
+    const client = this.authenticatedClient(input);
+    return { clientId: client.id, name: client.name, connectionId: client.connectionId, instanceId: this.instanceId };
+  }
+
+  rename(input) {
+    return this.serializeRegistration(async () => {
+      const client = this.authenticatedClient(input);
+      if (!this.liveClients().includes(client)) throw pairingError("BRIDGE_CLIENT_OFFLINE", "Reconnect this browser before renaming it.");
+      const entry = await this.registry.pair({ ...input, name: browserName(input.name) });
+      this.closed.signal.throwIfAborted();
+      client.name = entry.name;
+      return { ok: true, ...this.connectionInfo(input) };
+    });
+  }
+
+  disconnect(input) {
+    return this.serializeRegistration(() => {
+      const client = this.authenticatedClient(input);
+      this.revokeClient(client.id);
+      return { ok: true, clientId: client.id };
+    });
+  }
+
+  forgetBrowser(selector) {
+    return this.serializeRegistration(async () => {
+      const entry = this.registry.get(selector);
+      if (!entry) throw pairingError("BRIDGE_CLIENT_NOT_FOUND", `No registered browser named ${selector}. Use qz browsers to list names and UUIDs.`);
+      if (this.liveClients().some(client => client.id === entry.clientId)) {
+        throw pairingError("BRIDGE_CLIENT_IN_USE", "Disconnect this browser in its extension settings before forgetting its registration.");
+      }
+      await this.registry.forget(entry.clientId);
+      this.revokeClient(entry.clientId);
+      return { forgotten: true, clientId: entry.clientId, name: entry.name };
+    });
   }
 
-  registerClient(client, timeoutMs = client.pollTimeoutMs || 30000) {
-    const id = String(client.id || client.clientId || "qingzhou-extension").trim() || "qingzhou-extension";
-    const info = {
-      ...client, id, lastSeenAt: now(),
+  touchClient(info, client, timeoutMs) {
+    Object.assign(info, { lastSeenAt: now(), extensionId: client.extensionId || info.extensionId,
+      capabilities: client.capabilities || info.capabilities,
       pollLeaseSeconds: (bounded(timeoutMs, 30000, 100, 60000)
-        + bounded(client.pollIntervalMs ?? 750, 750, 100, 60000)) / 1000 + 15,
-    };
-    this.clients.set(id, info);
+        + bounded(client.pollIntervalMs ?? 750, 750, 100, 60000)) / 1000 + 15 });
+    this.clients.set(info.id, info);
     this.events.emit("change");
-    return info;
   }
 
   signal(signal) {
@@ -99,25 +188,36 @@ export class BridgeState {
     });
   }
 
-  async resolveClient(clientId, timeoutMs, signal) {
+  async resolveClient(clientId, timeoutMs, signal, returnConnection = false) {
+    const registered = clientId && this.registry.get(clientId);
+    const target = registered?.clientId || clientId;
     const deadline = Date.now() + Math.min(timeoutMs, this.connectWaitMs);
     while (true) {
       signal.throwIfAborted();
       const clients = this.liveClients();
-      if (clientId && clients.some(client => client.id === clientId)) return clientId;
-      if (!clientId && clients.length === 1) return clients[0].id;
+      const selected = target && clients.find(client => client.id === target);
+      if (selected) return returnConnection ? selected : selected.id;
+      if (clientId && (registered || this.clients.has(target) || Date.now() >= deadline)) throw new BridgeError(registered || this.clients.has(target) ? "BRIDGE_CLIENT_OFFLINE" : "BRIDGE_CLIENT_NOT_FOUND",
+        `Browser ${clientId} is ${registered || this.clients.has(target) ? "offline" : "not registered"}. Use qz browsers to inspect browser names and UUIDs.`);
+      if (!clientId && clients.length === 1) return returnConnection ? clients[0] : clients[0].id;
       if (!clientId && clients.length > 1) throw new BridgeError("BRIDGE_CLIENT_REQUIRED",
-        `Multiple qz browsers are connected. Pass clientId from qingzhou_bridge_status: ${clients.map(client => client.id).sort().join(", ")}`);
+        `Multiple qz browsers are connected. Pass clientId from qingzhou_bridge_status: ${clients.map(client => `${client.name || client.id} (${client.id})`).sort().join(", ")}`);
       if (Date.now() >= deadline) throw new BridgeError("BRIDGE_NOT_CONNECTED",
-        `No active qz extension${clientId ? ` (${clientId})` : ""}. Open qz in Chrome and accept its data notice, then retry. Install qz: ${PROJECT_URL}`);
+        `No active qz extension${clientId ? ` (${clientId})` : ""}. Run qz connect, then confirm the connection in the extension. Install qz: ${INSTALL_URL}`);
       await this.waitForChange(deadline - Date.now(), signal);
     }
   }
 
   async poll(client, { timeoutMs = 30000, maxBatch = 4, signal } = {}) {
-    const activeSignal = this.signal(signal);
+    const info = 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);
+      this.touchClient(info, client, timeoutMs);
+      return info;
+    });
+    const activeSignal = AbortSignal.any([this.signal(signal), info.controller.signal]);
     activeSignal.throwIfAborted();
-    const info = this.registerClient(client, timeoutMs);
     const deadline = Date.now() + bounded(timeoutMs, 30000, 100, 60000);
     const limit = Math.floor(bounded(maxBatch, 4, 1, 16));
     while (true) {
@@ -125,7 +225,7 @@ export class BridgeState {
       const requests = [];
       for (const [id, request] of this.pending) {
         if (requests.length >= limit) break;
-        if (request.clientId !== info.id) continue;
+        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 });
@@ -139,8 +239,11 @@ export class BridgeState {
     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);
-    const target = await this.resolveClient(String(clientId || "").trim(), seconds * 1000, activeSignal);
+    const client = await this.resolveClient(String(clientId || "").trim(), seconds * 1000, activeSignal, true);
     activeSignal.throwIfAborted();
+    const target = client.id;
+    if (this.clients.get(target) !== client || !this.liveClients().includes(client)) throw pairingError("BRIDGE_CLIENT_OFFLINE", "The selected browser disconnected before the request could start.");
+    client.controller.signal.throwIfAborted();
     return new Promise((resolve, reject) => {
       const id = `qz_${Date.now()}_${randomUUID()}`;
       const finish = (error, result) => {
@@ -154,7 +257,7 @@ export class BridgeState {
       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 });
-      this.pending.set(id, { id, method, params, clientId: target, timeoutMs: seconds * 1000, finish });
+      this.pending.set(id, { id, method, params, clientId: target, client, timeoutMs: seconds * 1000, finish });
       this.events.emit("change");
     });
   }
@@ -162,8 +265,9 @@ export class BridgeState {
   complete(requestId, payload) {
     const request = this.inflight.get(requestId);
     if (!request) return false;
-    // Legacy v1 clients may omit clientId; an explicit identity must match the dispatched request.
-    if (payload.clientId && payload.clientId !== request.clientId) return false;
+    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));
     else request.finish(null, payload.result);
     return true;
@@ -181,8 +285,8 @@ export class BridgeState {
       job.status = "running";
       job.startedAt = now();
       try {
-        // Async jobs outlive their initial MCP call and can be polled with get_tool_job.
-        job.result = await this.callExtension(method, params, { ...options, signal: undefined });
+        // Jobs outlive the initial MCP response, but retain that browser connection's authority.
+        job.result = await this.callExtension(method, params, { ...options, signal: options.connectionSignal });
         job.status = "completed";
       } catch (error) {
         job.error = error.message || String(error);

package/src/task-stream.mjs

@@ -5,6 +5,8 @@ const ACTIVE_STATUSES = new Set(["pending", "running", "waiting_user", "paused"]
 const INPUT_STATUSES = new Set(["waiting_user", "paused"]);
 const record = value => value && typeof value === "object" && !Array.isArray(value) ? value : {};
 
+export const TASK_NOT_FOUND_MESSAGE = "The task was not found in the selected browser. It may have been deleted, the task ID may be incorrect, or a different browser may be selected.";
+
 function taskStatus(snapshot) {
   const status = String(snapshot.status || snapshot.runtime?.status || snapshot.state?.status || "").trim();
   if (status === "waitingUser") return "waiting_user";
@@ -55,8 +57,8 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
     if (deadline !== null && Date.now() >= deadline) controller.abort(timeout);
     activeSignal.throwIfAborted();
   };
-  const pollingDelay = () => delay(deadline === null ? pollIntervalMs : Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())),
-    undefined, { signal: activeSignal });
+  // The total deadline cancels this sleep; shortening it can wake before that deadline.
+  const pollingDelay = () => delay(pollIntervalMs, undefined, { signal: activeSignal });
   const readSnapshot = async () => {
     checkActive();
     const milliseconds = Math.max(1, Math.ceil(requestTimeoutSeconds * 1000));
@@ -122,7 +124,7 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
         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("The task was deleted while waiting for its result."), { 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;

package/src/terminal.mjs

@@ -7,7 +7,9 @@ const palette = { accent: 36, muted: 90, error: 31, waiting: 33 };
 
 // Remote pages and model responses are text, never terminal instructions.
 export function sanitizeTerminalText(value) {
-  return stripVTControlCharacters(String(value ?? ""))
+  // Early Node 22 versions do not strip OSC strings terminated by ESC + backslash.
+  const text = String(value ?? "").replace(/(?:\u001b\]|\u009d)[\s\S]*?(?:\u0007|\u001b\\|\u009c|$)/g, "");
+  return stripVTControlCharacters(text)
     .replace(/\r\n?/g, "\n")
     .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "")
     .replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "")
@@ -117,11 +119,11 @@ function label(status) { return statusLabels[status] || single(status); }
 function tone(status) {
   return ["waiting_user", "waitingUser", "paused", "pending", "interrupted"].includes(status) ? "waiting" : status === "error" ? "error" : "accent";
 }
-function taskCommands(out, id, { cancel = true } = {}) {
+function taskCommands(out, id, { cancel = true, client = "" } = {}) {
   if (!id) return;
   out.line();
-  out.command(`qz show ${commandArgument(id, "TASK_ID")}`);
-  if (cancel) out.command(`qz cancel ${commandArgument(id, "TASK_ID")}`);
+  out.script(`qz show ${commandArgument(id, "TASK_ID")}${client}`);
+  if (cancel) out.script(`qz cancel ${commandArgument(id, "TASK_ID")}${client}`);
 }
 function latestResponse(snapshot) {
   const events = snapshot?.transcript?.length ? snapshot.transcript : snapshot?.tail || [];
@@ -212,9 +214,9 @@ function snapshotView(out, snapshot, { streamed = false, clientId = "" } = {}) {
   }
 }
 
-function taskList(out, sessions) {
+function taskList(out, sessions, client = "") {
   out.line(`Tasks · ${sessions.length}`, "accent");
-  if (!sessions.length) { out.line("No tasks yet."); out.command('qz create "Summarize the current page."'); return; }
+  if (!sessions.length) { out.line("No tasks yet."); out.script(`qz create "Summarize the current page."${client}`); return; }
   out.line();
   const idWidth = Math.max(2, ...sessions.map(task => measure(single(task.id || task.sessionId))));
   const titleWidth = out.width - idWidth - 18;
@@ -230,7 +232,7 @@ function taskList(out, sessions) {
       out.field("ID", task.id || task.sessionId);
     });
   }
-  out.line(); out.command("qz show TASK_ID");
+  out.line(); out.script(`qz show TASK_ID${client}`);
 }
 
 function resourceList(out, command, result, client) {
@@ -309,7 +311,7 @@ function settingsView(out, result, client) {
 export function renderResult(parsed, result, options = {}) {
   const out = output(options);
   const { command, action } = parsed;
-  const clientId = parsed.options?.["client-id"] || "";
+  const clientId = parsed.presentation?.clientId || result?.clientId || parsed.options?.["client-id"] || "";
   const client = clientId ? ` --client ${commandArgument(clientId, "CLIENT_ID")}` : "";
   const presentation = { streamed: parsed.presentation?.streamed === true, clientId };
   if (command === "watch") snapshotView(out, result?.snapshot || result || {}, presentation);
@@ -407,7 +409,7 @@ export function renderResult(parsed, result, options = {}) {
       else out.script(`qz show ${commandArgument(result?.sessionId || parsed.id, "TASK_ID")}${client}`);
     }
   } else if (command === "tasks") {
-    if (action === "list" || !action) taskList(out, result?.sessions || []);
+    if (action === "list" || !action) taskList(out, result?.sessions || [], client);
     else if (action === "get") snapshotView(out, result || {}, presentation);
     else if (action === "create") {
       if (result?.snapshot) snapshotView(out, result.snapshot, presentation);
@@ -416,31 +418,51 @@ export function renderResult(parsed, result, options = {}) {
         out.field("Task", result?.session?.id);
         out.field("Title", single(result?.session?.title));
       }
-      taskCommands(out, result?.session?.id || result?.snapshot?.sessionId, { cancel: !result?.snapshot || ["pending", "running", "waiting_user", "waitingUser", "paused"].includes(taskStatus(result.snapshot)) });
+      taskCommands(out, result?.session?.id || result?.snapshot?.sessionId, { client, cancel: !result?.snapshot || ["pending", "running", "waiting_user", "waitingUser", "paused"].includes(taskStatus(result.snapshot)) });
     } else if (action === "stop") {
       out.line(result?.stopped ? "Task stopped" : "Task has no active run", "accent");
       out.field("Task", result?.sessionId || parsed.id);
       if (result?.status) out.field("Status", label(result.status));
     }
+  } else if (command === "browsers") {
+    if (action === "forget") {
+      out.line("Browser registration removed", "accent"); out.field("Name", result.name); out.field("UUID", result.clientId);
+    } else {
+      const browsers = result.browsers || [];
+      out.line(`Browsers · ${browsers.length}`, "accent");
+      for (const browser of browsers) { out.line(); out.field("Name", browser.name); out.field("UUID", browser.clientId); out.field("Status", browser.online ? "Connected" : "Offline"); }
+      out.line(); out.command('qz create "TASK" --client NAME');
+    }
+  } else if (command === "connect" && result?.url) {
+    out.line(result.opened ? "Browser binding page opened" : "Browser binding URL ready", "accent");
+    out.field("URL", result.url);
+    out.line("Open this URL in the browser profile you want to connect.");
+    out.command("qz browsers");
   } else if (command === "connect") {
     out.line(result?.connected ? "Connected to qz" : "Waiting for qz", result?.connected ? "accent" : "waiting");
+    const selected = result?.clients?.find(browser => browser.clientId === clientId);
+    out.field("Browser", selected?.name);
+    out.field("UUID", clientId);
     out.field("MCP", result?.mcpUrl);
-    if (result?.connected) out.command('qz create "Summarize the current page."');
+    if (result?.connected) out.script(`qz create "Summarize the current page."${client}`);
   } else if (command === "status") {
     out.line(result?.connected ? "Connected to qz" : result?.running ? "Service running · browser disconnected" : "Local service stopped", result?.connected ? "accent" : "waiting");
     out.field("Service", result?.endpoint);
     if (result?.connected) {
       out.field("Browsers", result.clientCount ?? result.clients?.length ?? 1);
-      for (const client of result.clients || []) out.field("Client", client.clientId);
+      for (const client of result.clients || []) out.field(client.name || "Client", client.clientId);
     }
-    if (result?.updateAvailable) {
+    if (result?.updateRequired) {
+      out.line("Service upgrade required for browser pairing.", "waiting");
+      out.line(result.hint);
+    } else if (result?.updateAvailable) {
       out.line("Service update available. Restart when your current work is finished:", "waiting");
       out.command("qz stop && qz connect");
     } else if (!result?.connected) out.command("qz connect");
   } else if (command === "install") {
-    out.line(result?.opened ? "Extension download opened" : "Download the qz extension", "accent");
+    out.line(result?.opened ? "Chrome Web Store opened" : "Install qz from the Chrome Web Store", "accent");
     if (!result?.opened) out.line(result?.url);
-    out.line("Install the extension in Chrome, then connect:"); out.command("qz connect");
+    out.line("Click Add to Chrome, then connect:"); out.command("qz connect");
   } else if (command === "stop") {
     out.line(result?.stopped ? "Local service stopped" : "Local service is already stopped", "accent");
     out.command("qz connect");
@@ -470,7 +492,7 @@ export function renderHelp(topic = "", options = {}) {
     out.command('qz create "Compare these tabs." --title Research --wait');
   }
   if (!topic || commandOptions(topic).includes("client")) {
-    out.line(); out.line("Browser: --client ID (-c)", "muted");
+    out.line(); out.line("Browser: --client NAME|UUID (-c)", "muted");
   }
   if (!topic || topic === "watch" || commandOptions(topic).includes("wait")) {
     out.line(); out.line("Task waiting: no default time limit. --timeout SECONDS sets a total deadline, including input pauses.", "muted");

package/src/tools.mjs

@@ -13,11 +13,6 @@ const schemaValidator = new AjvJsonSchemaValidator();
 const definitions = new Map(TOOL_CATALOG.map(tool => [tool.name, {
   tool, validate: schemaValidator.getValidator(tool.inputSchema),
 }]));
-const skillFallbacks = {
-  qingzhou_list_skills: { name: "qingzhou_skill_author__list_skills", fields: ["scope"] },
-  qingzhou_get_skill: { name: "load_skill", fields: ["name", "includeContent", "includeResources"] },
-  qingzhou_get_skill_resource: { name: "load_skill_resource", fields: ["name", "path", "start", "maxChars"] },
-};
 const taskInputResults = new Set([
   "qingzhou_get_session_snapshot", "qingzhou_get_session_state", "qingzhou_send_message",
   "qingzhou_respond_to_user_input", "qingzhou_continue_task", "qingzhou_submit_wait_form", "qingzhou_cancel_wait",
@@ -58,15 +53,23 @@ function argumentsWithDefaults(definition, input) {
 export async function executeMcpTool(state, name, input = {}, { signal, onTaskUpdate } = {}) {
   const args = validateMcpToolInput(name, input);
   if (name === "qingzhou_bridge_status") return state.status();
-  if (name === "qingzhou_bridge_enable_snippet") return {
-    snippet: state.enableSnippet(args.clientId), storageKey: "_qingzhou_mcp_bridge",
-  };
+  if (name === "qingzhou_forget_browser") return state.forgetBrowser(args.clientId);
   if (name === "qingzhou_get_tool_job") return state.getJob(args.jobId, args.includeResult);
+  // One MCP operation, including observation, belongs to one connection.
+  const connection = await state.resolveClient(String(args.clientId || "").trim(),
+    (args.timeoutSeconds || state.requestTimeoutSeconds || 180) * 1000, state.signal(signal), true);
+  args.clientId = connection.id;
+  const connectionSignal = state.signal(connection.controller.signal);
+  const operationSignal = signal ? AbortSignal.any([connectionSignal, signal]) : connectionSignal;
+  operationSignal.throwIfAborted();
+  const result = await executeBrowserTool(state, name, args, { signal: operationSignal, connectionSignal, onTaskUpdate });
+  return args.clientId && (observableTools.has(name) || taskInputResults.has(name) || ["qingzhou_list_sessions", "qingzhou_get_user_input", "qingzhou_stop_session", "qingzhou_abort_session"].includes(name)) && result && typeof result === "object" && !Array.isArray(result)
+    ? { ...result, clientId: args.clientId } : result;
+}
+
+async function executeBrowserTool(state, name, args, { signal, connectionSignal, onTaskUpdate }) {
   const observe = observableTools.has(name) && (name === "qingzhou_watch_task" || args.wait || args.stream);
   const asyncTool = name === "qingzhou_execute_tool" && args.wait === false;
-  // Resolve once before a mutation or watch so subsequent reads stay in the same browser.
-  if (observe || asyncTool) args.clientId = await state.resolveClient(args.clientId,
-    (args.timeoutSeconds || state.requestTimeoutSeconds || 180) * 1000, state.signal(signal));
   const options = { timeoutSeconds: args.timeoutSeconds, clientId: args.clientId, signal };
   const startedAt = Date.now();
   const watch = async (sessionId, tracking = {}) => {
@@ -88,8 +91,10 @@ export async function executeMcpTool(state, name, input = {}, { signal, onTaskUp
         : cause.name === "TimeoutError" ? "timeout" : cause.name === "AbortError" ? "interrupted" : "task_wait_failed";
       const error = Object.assign(new Error(cause.message, { cause }), { code });
       error.details = { ...cause.details, sessionId, clientId: args.clientId,
-        recovery: { tool: code === "task_changed" ? "qingzhou_get_session_snapshot" : "qingzhou_watch_task",
-          arguments: { sessionId, clientId: args.clientId } } };
+        recovery: code === "task_deleted"
+          ? { tool: "qingzhou_list_sessions", arguments: { clientId: args.clientId } }
+          : { tool: code === "task_changed" ? "qingzhou_get_session_snapshot" : "qingzhou_watch_task",
+            arguments: { sessionId, clientId: args.clientId } } };
       throw error;
     }
   };
@@ -114,25 +119,11 @@ export async function executeMcpTool(state, name, input = {}, { signal, onTaskUp
   if (name === "qingzhou_execute_tool") {
     delete params.wait;
     params.args ||= {};
-    return asyncTool ? { ...state.startExtensionJob("execute_tool", params, options), sessionId: args.sessionId, clientId }
+    return asyncTool ? { ...state.startExtensionJob("execute_tool", params, { ...options, connectionSignal }), sessionId: args.sessionId, clientId }
       : state.callExtension("execute_tool", params, options);
   }
   const method = name === "qingzhou_abort_session" ? "stop_session" : name.slice("qingzhou_".length);
-  let result;
-  try {
-    result = await state.callExtension(method, params, options);
-  } catch (error) {
-    const fallback = skillFallbacks[name];
-    if (!fallback || !String(error.message).includes("Unknown Qingzhou MCP bridge method")) throw error;
-    result = await state.callExtension("execute_tool", {
-      sessionId: "default", name: fallback.name,
-      args: Object.fromEntries(fallback.fields.map(key => [key, args[key]])), timeoutSeconds: args.timeoutSeconds,
-    }, options);
-  }
-  if (name === "qingzhou_list_skills" && args.query && result && typeof result === "object") {
-    const names = (result.names || []).filter(item => typeof item === "string" && item.toLowerCase().includes(args.query.toLowerCase()));
-    if (names.length) result = { ...result, query: args.query, count: names.length, names, items: names.map(item => ({ name: item })) };
-  }
+  let result = await state.callExtension(method, params, options);
   if (resourceResults.has(name) && result && typeof result.code === "string" && typeof result.error === "string") {
     throw new BridgeError(result.code, result.error, {
       ...result.details,