qz-browser-agent 0.1.0 → 0.1.2

package/src/catalog.json

@@ -4,20 +4,18 @@
     "description": "查看本地 bridge 和当前在线的轻舟扩展客户端。",
     "inputSchema": {
       "properties": {
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_bridge_statusArguments",
       "type": "object"
     }
   },
   {
-    "name": "qingzhou_bridge_enable_snippet",
-    "description": "生成在轻舟扩展 DevTools Console 中启用 bridge 的 chrome.storage snippet。",
+    "name": "qingzhou_forget_browser",
+    "description": "Forget an offline browser registration, freeing its name for explicit pairing. Read qingzhou_bridge_status first and disconnect online browsers in their extension settings.",
     "inputSchema": {
-      "properties": {
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
-      },
-      "title": "qingzhou_bridge_enable_snippetArguments",
+      "properties": {"clientId": {"type": "string", "minLength": 1, "description": "Registered browser name or UUID."}},
+      "required": ["clientId"],
       "type": "object"
     }
   },
@@ -29,7 +27,7 @@
         "method": {"title": "Method", "type": "string"},
         "params": {"anyOf": [{"additionalProperties": true, "type": "object"}, {"type": "null"}], "default": null, "title": "Params"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["method"],
       "title": "qingzhou_callArguments",
@@ -42,7 +40,7 @@
     "inputSchema": {
       "properties": {
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_list_capabilitiesArguments",
       "type": "object"
@@ -56,7 +54,7 @@
         "limit": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Limit"},
         "excludeSessionId": {"default": "", "title": "Excludesessionid", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_list_sessionsArguments",
       "type": "object"
@@ -74,7 +72,7 @@
         "firstMessage": {"default": "", "title": "Firstmessage", "type": "string"},
         "parentSessionId": {"default": "", "title": "Parentsessionid", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number", "exclusiveMinimum": 0, "maximum": 86400}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_create_sessionArguments",
       "type": "object"
@@ -95,7 +93,7 @@
         "waitForStart": {"default": true, "title": "Waitforstart", "type": "boolean"},
         "waitForStartMs": {"default": 2000, "title": "Waitforstartms", "type": "number"},
         "timeoutSeconds": {"anyOf": [{"type": "number", "exclusiveMinimum": 0, "maximum": 86400}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["text"],
       "title": "qingzhou_send_messageArguments",
@@ -112,7 +110,7 @@
         "images": {"anyOf": [{"items": {}, "type": "array"}, {"type": "null"}], "default": null, "title": "Images"},
         "clientMessageId": {"default": "", "title": "Clientmessageid", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["text"],
       "title": "qingzhou_follow_upArguments",
@@ -127,7 +125,7 @@
         "sessionId": {"title": "Sessionid", "type": "string"},
         "cascade": {"default": true, "title": "Cascade", "type": "boolean"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["sessionId"],
       "title": "qingzhou_abort_sessionArguments",
@@ -176,7 +174,7 @@
         "waitId": {"title": "Waitid", "type": "string", "minLength": 1},
         "payload": {"anyOf": [{"additionalProperties": true, "type": "object"}, {"type": "null"}], "default": null, "title": "Payload"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["sessionId", "waitId"],
       "title": "qingzhou_continue_taskArguments",
@@ -193,7 +191,7 @@
         "waitId": {"title": "Waitid", "type": "string", "minLength": 1},
         "reason": {"default": "submitted", "title": "Reason", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["sessionId", "answers", "waitId"],
       "title": "qingzhou_submit_wait_formArguments",
@@ -208,7 +206,7 @@
         "sessionId": {"title": "Sessionid", "type": "string"},
         "waitId": {"title": "Waitid", "type": "string", "minLength": 1},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["sessionId", "waitId"],
       "title": "qingzhou_cancel_waitArguments",
@@ -222,7 +220,7 @@
       "properties": {
         "sessionId": {"default": "default", "title": "Sessionid", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_get_session_stateArguments",
       "type": "object"
@@ -242,7 +240,7 @@
         "traceLimit": {"default": 40, "title": "Tracelimit", "type": "number"},
         "includeTools": {"default": false, "title": "Includetools", "type": "boolean"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_get_session_snapshotArguments",
       "type": "object"
@@ -258,7 +256,7 @@
         "tail": {"default": true, "title": "Tail", "type": "boolean"},
         "num": {"default": 50, "title": "Num", "type": "number"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_get_messagesArguments",
       "type": "object"
@@ -272,7 +270,7 @@
         "sessionId": {"title": "Sessionid", "type": "string"},
         "cascade": {"default": true, "title": "Cascade", "type": "boolean"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["sessionId"],
       "title": "qingzhou_stop_sessionArguments",
@@ -286,7 +284,7 @@
       "properties": {
         "sessionId": {"default": "default", "title": "Sessionid", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_list_toolsArguments",
       "type": "object"
@@ -300,7 +298,7 @@
         "scope": {"default": "all", "title": "Scope", "type": "string"},
         "query": {"default": "", "title": "Query", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_list_skillsArguments",
       "type": "object"
@@ -315,7 +313,7 @@
         "includeContent": {"default": true, "title": "Includecontent", "type": "boolean"},
         "includeResources": {"default": false, "title": "Includeresources", "type": "boolean"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["name"],
       "title": "qingzhou_get_skillArguments",
@@ -332,7 +330,7 @@
         "start": {"default": 0, "title": "Start", "type": "number"},
         "maxChars": {"default": 300000, "title": "Maxchars", "type": "number"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["name", "path"],
       "title": "qingzhou_get_skill_resourceArguments",
@@ -350,7 +348,7 @@
         "runId": {"default": "", "title": "Runid", "type": "string"},
         "wait": {"default": true, "title": "Wait", "type": "boolean"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["name"],
       "title": "qingzhou_execute_toolArguments",
@@ -405,7 +403,7 @@
     "inputSchema": {
       "properties": {
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_get_configArguments",
       "type": "object"
@@ -418,7 +416,7 @@
       "properties": {
         "config": {"additionalProperties": true, "title": "Config", "type": "object"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "required": ["config"],
       "title": "qingzhou_save_configArguments",
@@ -432,7 +430,7 @@
       "properties": {
         "sessionId": {"default": "default", "title": "Sessionid", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_list_pluginsArguments",
       "type": "object"
@@ -446,7 +444,7 @@
         "limit": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Limit"},
         "runLimit": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Runlimit"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_list_automationsArguments",
       "type": "object"
@@ -458,7 +456,7 @@
     "inputSchema": {
       "properties": {
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
-        "clientId": {"default": "", "title": "Clientid", "type": "string"}
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
       "title": "qingzhou_get_traceArguments",
       "type": "object"

package/src/cli.mjs

@@ -7,7 +7,7 @@ import { ensureDaemon, findDaemon, stopDaemon } from "./daemon.mjs";
 import { openBrowser } from "./open-browser.mjs";
 import { parseCommand } from "./args.mjs";
 import { renderError, renderHelp, renderResult, renderInputNotice, sanitizeTerminalText } from "./terminal.mjs";
-import { waitForTask } from "./task-stream.mjs";
+import { TASK_NOT_FOUND_MESSAGE, waitForTask } from "./task-stream.mjs";
 import { createLiveOutput, outputMode } from "./output.mjs";
 import { resourceRequest, settingsPatch } from "./cli-resources.mjs";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "./package-info.mjs";
@@ -40,8 +40,28 @@ async function stdinText({ signal } = {}) {
   });
 }
 
-function connected(health, clientId = "") {
-  return clientId ? health.status?.clients?.some(client => client.clientId === clientId) : Boolean(health.status?.connected);
+const UPGRADE_HINT = "Use the latest CLI. After current tasks finish, run npx --yes qz-browser-agent@latest stop (disconnects all browsers), update and reload the qz extension, then run npx --yes qz-browser-agent@latest connect.";
+
+function requirePairingSupport(health) {
+  if (health?.features?.browserPairing !== 1) throw new QzError("upgrade_required",
+    "This qz service is unsupported. Upgrade the CLI and extension, then run qz stop and qz connect.",
+    { hint: UPGRADE_HINT });
+}
+
+function selectClient(health, selector = "", { allowEmpty = false } = {}) {
+  const clients = health.status?.clients || [];
+  if (selector) {
+    const entry = (health.status?.browsers || []).find(client => client.clientId === selector || client.name === selector);
+    const selected = clients.find(client => client.clientId === (entry?.clientId || selector));
+    if (selected) return selected.clientId;
+    throw new QzError(entry ? "client_offline" : "client_not_found", `Browser ${selector} is ${entry ? "offline" : "not registered"}.`,
+      { hint: "Run qz browsers to inspect names and UUIDs. Reconnect that profile from its extension settings." });
+  }
+  if (clients.length > 1) throw new QzError("selection_required", "Multiple browsers are connected. Select one with --client NAME|UUID.",
+    { clients: clients.map(({ clientId, name }) => ({ clientId, name })), hint: clients.map(client => `${client.name || client.clientId}: ${client.clientId}`).join("\n") });
+  if (clients.length === 1) return clients[0].clientId;
+  if (allowEmpty) return "";
+  throw connectionRequired();
 }
 
 function connectionRequired() {
@@ -53,11 +73,18 @@ function recoveryCommand(command, sessionId, clientId, stream = false) {
   if (clientId && sanitizeTerminalText(clientId) !== String(clientId)) clientId = "CLIENT_ID";
   const client = clientId ? ` --client${String(clientId).startsWith("-") ? "=" : " "}${shellArgument(clientId)}` : "";
   const options = `${client}${stream ? " --stream" : ""}`;
+  if (!sessionId) return `qz ${command}${options}`;
   return String(sessionId).startsWith("-")
     ? `qz ${command}${options} ${optionTerminator()} ${shellArgument(sessionId)}`
     : `qz ${command} ${shellArgument(sessionId)}${options}`;
 }
 
+function missingTaskDetails(sessionId, clientId) {
+  return { sessionId, ...(clientId ? { clientId } : {}),
+    hint: "Check the task ID and selected browser. Run qz browsers to inspect browser names and UUIDs. List tasks in the selected browser:",
+    command: recoveryCommand("tasks", "", clientId) };
+}
+
 export async function runCli(argv, dependencies = {}) {
   return executeCommand(parseCommand(argv), dependencies);
 }
@@ -66,7 +93,12 @@ async function executeCommand(parsed, dependencies) {
   if (parsed.command === "version") return parsed.options.json
     ? { result: { name: PACKAGE_NAME, version: PACKAGE_VERSION } }
     : { text: `qz ${PACKAGE_VERSION}\n` };
-  return withToolClient(callTool => dispatchCommand(parsed, { ...dependencies, callTool: dependencies.callTool || callTool }));
+  return withToolClient(async callTool => {
+    const returned = await dispatchCommand(parsed, { ...dependencies, callTool: dependencies.callTool || callTool });
+    const clientId = parsed.presentation?.clientId;
+    return clientId && returned.result && typeof returned.result === "object" && !Array.isArray(returned.result)
+      ? { ...returned, result: { ...returned.result, clientId } } : returned;
+  });
 }
 
 async function dispatchCommand(parsed, dependencies) {
@@ -79,11 +111,24 @@ async function dispatchCommand(parsed, dependencies) {
   if (command === "install") return { result: await open(INSTALL_URL) };
   if (command === "stop") return { result: await (dependencies.stopDaemon || stopDaemon)() };
   if (command === "connect") {
-    const running = await (dependencies.ensureDaemon || ensureDaemon)();
-    const connectUrl = `${running.endpoint}/qz-connect`;
+    const running = await (dependencies.ensureDaemon || ensureDaemon)(options.port === undefined ? {} : { preferredPort: options.port });
+    requirePairingSupport(running.health);
+    if (options.port !== undefined && Number(new URL(running.endpoint).port) !== options.port) throw new QzError("port_mismatch",
+      `The local service is already running at ${running.endpoint}.`, { endpoint: running.endpoint,
+        hint: "Use its current address, or run qz stop before connecting on a different port." });
+    const bindingUrl = new URL("/qz-connect", running.endpoint);
+    if (options.name !== undefined) bindingUrl.searchParams.set("name", options.name);
+    const connectUrl = bindingUrl.href;
+    if (options["no-open"] || options.name !== undefined) {
+      dependencies.signal?.throwIfAborted();
+      const opened = options["no-open"] ? false : Boolean((await open(connectUrl))?.opened);
+      return { result: { endpoint: running.endpoint, url: connectUrl, mcpUrl: `${running.endpoint}/mcp`, opened } };
+    }
     const deadline = Date.now() + timeoutSeconds * 1000;
+    let selected = selectClient(running.health, options["client-id"], { allowEmpty: true });
     const probe = async health => {
-      const clients = (health?.status?.clients || []).filter(client => !options["client-id"] || client.clientId === options["client-id"]);
+      const chosen = selected || selectClient(health, "", { allowEmpty: true });
+      const clients = (health?.status?.clients || []).filter(client => client.clientId === chosen);
       for (const client of clients) {
         dependencies.signal?.throwIfAborted();
         const timeoutMs = Math.min(2000, deadline - Date.now());
@@ -94,17 +139,19 @@ async function dispatchCommand(parsed, dependencies) {
           await dependencies.callTool(running.endpoint, "qingzhou_call", {
             method: "ping", clientId: client.clientId, timeoutSeconds: timeoutMs / 1000,
           }, { timeoutMs, signal: dependencies.signal ? AbortSignal.any([dependencies.signal, timeout]) : timeout });
+          selected = client.clientId;
           return true;
         } catch (error) {
           dependencies.signal?.throwIfAborted();
           if (error.code === "connection_error" || (!timeout.aborted
-            && !["BRIDGE_NOT_CONNECTED", "BRIDGE_REQUEST_TIMEOUT", -32001].includes(error.code))) throw error;
+            && !["BRIDGE_NOT_CONNECTED", "BRIDGE_CLIENT_OFFLINE", "BRIDGE_CLIENT_DISCONNECTED", "BRIDGE_REQUEST_TIMEOUT", -32001].includes(error.code))) throw error;
         }
       }
       return false;
     };
-    const result = health => ({ result: { connected: true, mcpUrl: `${running.endpoint}/mcp`, clients: health.status.clients } });
+    const result = health => ({ result: { connected: true, mcpUrl: `${running.endpoint}/mcp`, clients: health.status.clients, clientId: selected } });
     if (await probe(running.health)) return result(running.health);
+    if (options["client-id"]) throw new QzError("client_offline", "The selected browser is not responding. Reconnect it from its extension settings.");
     dependencies.signal?.throwIfAborted();
     await open(connectUrl);
     while (Date.now() < deadline) {
@@ -114,7 +161,7 @@ async function dispatchCommand(parsed, dependencies) {
       if (health && await probe(health)) return result(health);
       await delay(200, undefined, { signal: dependencies.signal });
     }
-    throw new QzError("connection_pending", "qz is waiting for Chrome. Open the connection URL in the Chrome profile with qz installed and accept its data notice. Then run qz connect again.", { url: connectUrl });
+    throw new QzError("connection_pending", "qz is waiting for Chrome. Open the connection URL in the Chrome profile with qz installed and confirm the connection in qz. Then run qz connect again.", { url: connectUrl });
   }
   // Validate JSON before connecting; malformed arguments cannot cause browser actions.
   let args = {};
@@ -134,14 +181,21 @@ async function dispatchCommand(parsed, dependencies) {
   dependencies.signal?.throwIfAborted();
   const resource = resourceRequest(parsed, config);
   const running = await find();
-  if (command === "status") return { result: running ? { running: true, endpoint: running.endpoint, updateAvailable: running.updateAvailable === true, ...running.health.status } : { running: false, connected: false } };
+  if (command === "status") return { result: running ? { running: true, endpoint: running.endpoint, updateAvailable: running.updateAvailable === true, ...(running.health.features?.browserPairing === 1 ? {} : { updateRequired: true, hint: UPGRADE_HINT }), ...running.health.status } : { running: false, connected: false } };
   if (!running) throw connectionRequired();
   if (command === "mcp") return options.json ? { result: { url: `${running.endpoint}/mcp` } } : { text: `${running.endpoint}/mcp\n` };
   const call = dependencies.callTool;
-  if (!connected(running.health, options["client-id"])) throw connectionRequired();
-  const clients = running.health.status?.clients || [];
-  // Keep a waited task in its creating browser even if other profiles connect or disconnect.
-  const clientId = options["client-id"] || ((options.wait || ["submit", "approve", "reject"].includes(command)) && clients.length === 1 ? clients[0].clientId : "");
+  requirePairingSupport(running.health);
+  if (command === "browsers") {
+    if (action === "list") return { result: running.health.status };
+    const browser = running.health.status?.browsers?.find(browser => browser.clientId === id || browser.name === id);
+    if (!browser) throw new QzError("client_not_found", `No registered browser named ${id}. Run qz browsers to inspect names and UUIDs.`);
+    return { result: await call(running.endpoint, "qingzhou_forget_browser", { clientId: browser.clientId }, { timeoutMs: timeoutSeconds * 1000, signal: dependencies.signal }) };
+  }
+  // Resolve names once. Every subsequent operation carries this profile UUID.
+  const clientId = selectClient(running.health, options["client-id"]);
+  parsed.presentation = { ...parsed.presentation, clientId };
+  options["client-id"] = clientId;
   const common = { timeoutSeconds, ...(clientId ? { clientId } : {}) };
   const requestOptions = { timeoutMs: timeoutSeconds * 1000, signal: dependencies.signal };
   const startedAt = Date.now();
@@ -172,6 +226,7 @@ async function dispatchCommand(parsed, dependencies) {
       });
     } catch (error) {
       const code = error.name === "TimeoutError" ? "timeout" : error.name === "AbortError" ? "interrupted" : error.code || "task_wait_failed";
+      if (code === "task_deleted") throw new QzError(code, error.message, { ...error.details, ...missingTaskDetails(sessionId, clientId) });
       const changed = code === "task_changed";
       throw new QzError(code, code === "timeout"
         ? "Stopped watching after the configured --timeout. The browser task may still be running." : error.message,
@@ -236,6 +291,9 @@ async function dispatchCommand(parsed, dependencies) {
       ...(action === "list" && options.limit !== undefined ? { limit: Number(options.limit) } : {}) };
   }
   let result = await call(running.endpoint, name, parameters, requestOptions);
+  if (command === "tasks" && action === "get" && result?.session === null) {
+    throw new QzError("task_not_found", TASK_NOT_FOUND_MESSAGE, missingTaskDetails(id, clientId));
+  }
   if (command === "tasks" && action === "create" && options.wait) {
     const sessionId = result?.session?.id || result?.sessionId;
     if (!sessionId) throw new QzError("invalid_response", "The task was created without an ID. Run qz tasks to find it before retrying.");
@@ -291,7 +349,7 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
     });
     live?.finish();
     stdout.write(result.text ?? (mode.json ? `${JSON.stringify({ ok: true, result: result.result })}\n`
-      : renderResult({ ...parsed, presentation: { streamed: live?.streamed } }, result.result, mode)));
+      : renderResult({ ...parsed, presentation: { ...parsed.presentation, streamed: live?.streamed } }, result.result, mode)));
     const status = result.result?.snapshot?.status || result.result?.snapshot?.runtime?.status;
     if (result.result?.accepted === false && !result.result?.requiresUserAction) return 1;
     return ["error", "failed", "aborted", "cancelled", "canceled", "interrupted"].includes(status) ? 1 : 0;
@@ -304,10 +362,30 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   }
 }
 
+/** Keep handlers installed while npm forwards duplicate signals and MCP closes. */
+export async function runMain(argv = process.argv.slice(2), dependencies = {}) {
+  const controller = new AbortController();
+  let interruptedExitCode;
+  const interrupt = code => {
+    if (controller.signal.aborted) return;
+    interruptedExitCode = code;
+    controller.abort();
+  };
+  const onSigint = () => interrupt(130);
+  const onSigterm = () => interrupt(143);
+  process.on("SIGINT", onSigint);
+  process.on("SIGTERM", onSigterm);
+  try {
+    const code = await main(argv, { ...dependencies, signal: controller.signal });
+    return interruptedExitCode ?? code;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+    process.removeListener("SIGTERM", onSigterm);
+  }
+}
+
 let isEntry = false;
 try { isEntry = realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch {}
 if (isEntry) {
-  const controller = new AbortController();
-  process.once("SIGINT", () => controller.abort());
-  process.exitCode = await main(process.argv.slice(2), { signal: controller.signal });
+  process.exitCode = await runMain();
 }

package/src/client.mjs

@@ -1,11 +1,10 @@
 import { request } from "node:http";
-import { Readable } from "node:stream";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { PACKAGE_VERSION } from "./package-info.mjs";
 
 export const GUIDE_URL = "https://github.com/alibaba/qz-browser-agent/blob/main/services/mcp-bridge/README.md";
-export const INSTALL_URL = "https://github.com/alibaba/qz-browser-agent/releases/latest";
+export { INSTALL_URL } from "./package-info.mjs";
 export const SERVICE_NAME = "qz-browser-agent";
 export const PROTOCOL_VERSION = 1;
 
@@ -27,6 +26,19 @@ export function localUrl(value) {
   return url;
 }
 
+function responseBody(response) {
+  const iterator = response[Symbol.asyncIterator]();
+  return {
+    [Symbol.asyncIterator]() { return this; },
+    next: () => iterator.next(),
+    return() {
+      // An iterator return waits behind a pending read. Destroy the HTTP stream first.
+      response.destroy();
+      return iterator.return();
+    },
+  };
+}
+
 // node:http does not inherit proxy environment settings. Every MCP request stays on loopback.
 export async function localFetch(input, init) {
   const prepared = new Request(input, init);
@@ -42,7 +54,7 @@ export async function localFetch(input, init) {
         return;
       }
       try {
-        resolve(new Response([204, 304].includes(res.statusCode) ? null : Readable.toWeb(res), {
+        resolve(new Response([204, 304].includes(res.statusCode) ? null : responseBody(res), {
           status: res.statusCode, headers: new Headers(Object.entries(res.headers)
             .flatMap(([key, value]) => Array.isArray(value) ? value.map(item => [key, item]) : value === undefined ? [] : [[key, value]])),
         }));

package/src/commands.mjs

@@ -8,8 +8,8 @@ const route = (tool, args = () => ({}), options = []) => ({ tool, args, options
 // CLI syntax, documentation, and direct MCP routes have one declaration per command.
 // Task execution and form responses retain their explicit handlers in cli.mjs.
 export const COMMANDS = {
-  connect: { options: request, summary: "Connect the browser",
-    help: ["qz connect [--timeout SECONDS]", "Start the local service and open its connection page.", "Use the Chrome profile with qz installed and accept its data notice.", "qz status"],
+  connect: { options: [...request, "port", "no-open", "name"], summary: "Connect the browser",
+    help: ["qz connect [--client NAME|UUID] [--port PORT] [--timeout SECONDS]", "Reuse a connected browser or open the connection page for first pairing.", "qz connect --no-open [--name NAME] --json", "Return a binding URL immediately. Open it in the target browser profile.", "--name assigns or changes that profile's name. Without --no-open, its binding page opens immediately.", "Use --port for a custom local service port. An existing service remains running.", "qz browsers"],
   },
   create: { options: [...waiting, "title", "parent"], summary: "Start a task",
     help: ['qz create "PROMPT" [--title TITLE] [--wait | --stream]', "Start a browser task. The title is optional.",
@@ -101,17 +101,20 @@ export const COMMANDS = {
       run: route("qingzhou_run_automation", ({ id }) => ({ automationId: id })),
     },
   },
+  browsers: { options: [], summary: "List or forget browser registrations",
+    help: ["qz browsers [list]", "List registered browser names, UUIDs, and connection status.", "qz browsers forget NAME|UUID", "Forget an offline registration to reuse its name. Disconnect online browsers in their extension settings first."],
+  },
   status: { options: [], summary: "Check the connection",
     help: ["qz status", "Show the local service and browser connection status."],
   },
   mcp: { options: [], summary: "Print the MCP URL",
     help: ["qz mcp [--json]", "Print the running service's MCP URL for an external agent.", "Run qz connect first."],
   },
-  install: { options: [], summary: "Download the extension",
-    help: ["qz install", "Open the latest extension download in your browser.", "Install it in Chrome, then run qz connect."],
+  install: { options: [], summary: "Install the Chrome extension",
+    help: ["qz install", "Open qz in the Chrome Web Store.", "Click Add to Chrome, then run qz connect."],
   },
   stop: { options: [], summary: "Stop the local service",
-    help: ["qz stop", "Stop the local service and disconnect the browser.", "Use qz cancel TASK_ID to stop a task.", "qz connect"],
+    help: ["qz stop", "Stop the local service and disconnect all browsers.", "Use qz cancel TASK_ID to stop a task.", "qz connect"],
   },
   help: { options: [] },
 };

package/src/daemon.mjs

@@ -83,6 +83,7 @@ async function withLock(paths, operation, { timeoutMs = 15000 } = {}) {
   await mkdir(candidate, { mode: 0o700 });
   const deadline = Date.now() + timeoutMs;
   let acquired = false;
+  let missingTargetPermissionError;
   try {
     await writeFile(join(candidate, ownerFile), JSON.stringify(owner), { mode: 0o600 });
     while (true) {
@@ -92,12 +93,25 @@ async function withLock(paths, operation, { timeoutMs = 15000 } = {}) {
         acquired = true;
         break;
       } catch (error) {
-        const existing = await stat(paths.lock).catch(() => null);
+        const existing = await stat(paths.lock).catch(error => {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        });
         if (!existing) {
+          if (process.platform === "win32" && error.code === "EPERM") {
+            // Windows reports directory collisions as EPERM. The owner may have
+            // released the lock before stat; try the same atomic publication once.
+            // A persistent denial remains EPERM rather than becoming a busy lock.
+            if (missingTargetPermissionError || Date.now() >= deadline) throw missingTargetPermissionError || error;
+            missingTargetPermissionError = error;
+            await delay(50);
+            continue;
+          }
           if (!["EEXIST", "ENOTEMPTY", "ENOTDIR"].includes(error.code)) throw error;
           if (Date.now() >= deadline) throw new QzError("connection_busy", "Another qz command is starting the local service. Try qz status shortly.");
           continue;
         }
+        missingTargetPermissionError = undefined;
         if (existing.isDirectory()) {
           for (const name of await readdir(paths.lock).catch(() => [])) {
             if (!/^\d+-[\da-f-]+\.json$/.test(name)) continue;
@@ -236,11 +250,12 @@ export async function stopDaemon(options = {}) {
 
 export async function startManagedBridge({ stateFile, scopeId, buildId = "", instanceId = randomUUID(), port = 18765, startBridge } = {}) {
   const start = startBridge || (await import("./server.mjs")).startBridge;
+  const registryPath = stateFile.replace(/\.json$/, "") + ".browsers.json";
   let running;
-  try { running = await start({ port, scopeId, instanceId, buildId }); }
+  try { running = await start({ port, scopeId, instanceId, buildId, registryPath }); }
   catch (error) {
     if (error.code !== "EADDRINUSE" || !port) throw error;
-    running = await start({ port: 0, scopeId, instanceId, buildId });
+    running = await start({ port: 0, scopeId, instanceId, buildId, registryPath });
   }
   const record = { service: SERVICE_NAME, protocolVersion: PROTOCOL_VERSION, endpoint: running.endpoint,
     processId: process.pid, scopeId, instanceId, buildId };

package/src/package-info.mjs

@@ -4,3 +4,4 @@ const metadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.
 
 export const PACKAGE_NAME = metadata.name;
 export const PACKAGE_VERSION = metadata.version;
+export const INSTALL_URL = "https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm";