qz-browser-agent 0.1.0 → 0.1.2

package/README.md

@@ -1,353 +1,126 @@
-# qz command line and MCP
+# qz
 
-Run browser tasks, manage results, and connect external agents to qz through CLI or MCP.
-Requires Node.js 24 or later and Chrome. CLI and MCP share the same browser connection.
+An open-source browser agent for humans and coding agents.
 
-## Quick start
-
-Run the published package with npx:
-
-```bash
-npx qz-browser-agent@latest install
-npx qz-browser-agent@latest connect
-npx qz-browser-agent@latest create "Summarize the current page." --stream
-```
-
-`install` opens the [latest extension release](https://github.com/alibaba/qz-browser-agent/releases/latest).
-Extract its ZIP, open `chrome://extensions`, enable **Developer mode**, and choose **Load unpacked**.
-Select the extracted extension folder. Open qz and accept its first-use data notice.
-
-`connect` starts the local MCP service and opens a connection page if a browser has not connected.
-Open that page in the Chrome profile where qz is installed. The connection page identifies the
-local service to the extension; no token or DevTools configuration is required.
-
-The examples and suggested next commands use `qz`. Replace it with
-`npx qz-browser-agent@latest`, or install the command globally:
+qz is a local-first extension for Chrome and Edge.
+People use it from the side panel; agents such as Claude Code, Codex, and pi hand it web tasks
+through this CLI or MCP. qz works in your own browser, with your existing logins, and returns
+tables, files, or reports with sources. Everything runs locally, and your data goes only to the
+model you choose.
 
-```sh
-npm install --global qz-browser-agent@latest
-qz --version
-```
-
-On Windows, use PowerShell 7.3 or newer with its default native argument passing. After a global
-install, use `qz.ps1` for commands containing JSON or quoted names; Windows command suggestions
-use that wrapper. For automation, pin an exact npm version such as `qz-browser-agent@0.1.0`.
-
-## Connect and stop
-
-```bash
-qz connect
-qz status
-qz mcp
-qz stop
-```
+[Website](https://alibaba.github.io/qz-browser-agent/) ·
+[GitHub](https://github.com/alibaba/qz-browser-agent) ·
+[Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm) ·
+[Full CLI and MCP reference](https://github.com/alibaba/qz-browser-agent/blob/main/docs/cli.md)
 
-`connect` reuses the healthy service already running for this installation and protocol. It prefers port
-18765; if another program owns that port, it uses a free port chosen by the operating system.
-It confirms that a browser responds before reporting success, and opens the connection page to
-resume polling if a previously connected browser no longer responds.
-`mcp` prints the actual MCP URL. `status` and `mcp` never start a service or open a browser.
-`stop` shuts down the shared service and disconnects the extension and MCP clients.
-
-After first-use consent, an unavailable local service gets up to three connection attempts.
-Once a connection succeeds, later interruptions switch to one recovery attempt per minute after
-three consecutive failed polls, using that same endpoint. Recovery continues across worker restarts;
-disabling the bridge stops it. Run `qz connect` to retry immediately. Connected browsers use long polls
-capped at 20 seconds and reload saved settings before each poll. The side panel and connection page
-can be closed.
-
-`status` distinguishes an unavailable local service from a running service with no connected
-browser. A failed health check is retried once; an unresponsive live service is reported without
-starting another instance. After updating the extension, reload it at `chrome://extensions` and
-run `qz connect` to reconnect.
+![A coding agent handing a GitHub research task to qz](https://raw.githubusercontent.com/alibaba/qz-browser-agent/main/docs/images/examples/en/pi-delegate-en.gif)
 
-## Connect an MCP client
-
-Run `qz connect`, then `qz mcp`. Copy the returned URL into your MCP client's HTTP configuration:
-
-```toml
-[mcp_servers.qz]
-url = "http://127.0.0.1:18765/mcp"
-```
-
-Use the URL printed by your command if its port differs. `qz mcp --json` returns the URL as JSON
-for scripts. The `qingzhou_*` MCP tool names and extension protocol remain available. Responses
-to pending input bind to an explicit `waitId`. MCP initialization and streaming are handled by your
-client's MCP implementation.
+## Quick start
 
-### Task and resource operations
+Requires Node.js 22 or later.
 
-CLI and MCP use the same task observer and browser operations. The task and resource commands map to these MCP operations:
+1. **Install the extension.** Click **Add to Chrome** on the
+   [Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm),
+   open the qz side panel, and choose a provider and model in **Settings**.
+2. **Connect.** This starts the local service and pairs automatically with your default browser.
 
-| CLI | MCP tool |
-| --- | --- |
-| `create`, `send`, `cancel` | `qingzhou_create_session`, `qingzhou_send_message`, `qingzhou_stop_session` |
-| `tasks`, `show`, `watch` | `qingzhou_list_sessions`, `qingzhou_get_session_snapshot`, `qingzhou_watch_task` |
-| `show`, `submit` / `approve` / `reject` | `qingzhou_get_session_snapshot`, `qingzhou_respond_to_user_input` |
-| `data list` / `delete` / `export` | `qingzhou_list_data_tables`, `qingzhou_delete_data_table`, `qingzhou_export_data_table` |
-| `images list` / `delete` / `export` | `qingzhou_list_image_collections`, `qingzhou_delete_image_collection`, `qingzhou_export_image_collection` |
-| `skills list` / `show` / `read` / `tools` / `export` | `qingzhou_list_skills`, `qingzhou_get_skill`, `qingzhou_get_skill_resource`, `qingzhou_list_plugins`, `qingzhou_export_skill` |
-| `settings get` / `set` | `qingzhou_get_settings`, `qingzhou_update_settings` |
-| `automations list` / `run` | `qingzhou_list_automations`, `qingzhou_run_automation` |
-
-MCP creation, message submission, and input responses accept `wait: true` to wait for completion;
-`stream: true` also sends assistant text through standard MCP progress notifications. A watch call
-always waits. For example, call `qingzhou_create_session` with:
+   ```bash
+   npx qz-browser-agent@latest connect
+   ```
 
-```json
-{"firstMessage":"Summarize the current page.","stream":true}
-```
+3. **Run your first task.**
 
-Supply `_meta.progressToken` on the MCP request to receive progress. Each notification includes a
-readable `message` and its structured event in `params._meta["qz/task-event"]`. Events include
-`created`, `status`, `text`, `replace`, and `input`. Input events include the current form, exact
-field IDs, option values, and `responseTemplate`. Fill that template and pass it to
-`qingzhou_respond_to_user_input`; another CLI or MCP connection can answer while the original call
-keeps waiting. Native Chrome permissions still require the user's click in the side panel.
+   ```bash
+   npx qz-browser-agent@latest create "Find this year's Nobel Prize winners in every category and put them in a table with source links." --stream
+   ```
 
-MCP `timeoutSeconds` bounds each browser request (180 seconds by default).
-`waitTimeoutSeconds` bounds the whole observation; omit it for no overall deadline. Configure your
-MCP client's own request deadline for long tasks. On timeout or cancellation, the browser task
-continues; error details include the task ID and a recovery tool call. `send_message` supports
-`steer: true` and follows its returned `clientMessageId`, including when steering stays in the same
-run. A long observation stays bound to the browser selected when it started.
+   `--stream` shows progress, any questions qz needs you to answer, and the final result.
 
-## Run a task
+For regular use, install the `qz` command globally and use it in place of
+`npx qz-browser-agent@latest`:
 
 ```bash
-qz create "Compare these two laptops."
-qz create "Summarize the current page." --title "Research" --wait
-qz create "Find the main differences between these pages." --stream
-qz send TASK_ID "Add the source links." --stream
-qz send TASK_ID "Focus on open-source options." --steer --stream
-qz tasks
-qz show TASK_ID
-qz cancel TASK_ID
+npm install --global qz-browser-agent@latest
+qz --version
 ```
 
-`create` starts a task and returns its ID. The title is optional. `--wait` waits for the result;
-`--stream` also displays progress as it arrives. Both stay connected while the task waits for user
-input and continue automatically after you respond. Task observation has no default time limit.
-Add `--timeout SECONDS` to set a total deadline, including time spent waiting for input. Each
-individual connection request remains bounded (180 seconds by default). A timeout or Ctrl-C ends
-watching; `qz watch TASK_ID --stream` resumes observation and `qz cancel TASK_ID` stops the task.
-Each CLI command initializes one MCP connection on its first tool call and reuses it for subsequent
-reads and responses. Completion, errors, and Ctrl-C close that connection. Transport failures are
-reported without automatically repeating browser actions.
-
-Provide the task text directly after `create`, or read it from stdin with `qz create -`.
-Use `--parent TASK_ID` to create a child task, and `qz tasks --limit N` to limit the task list.
-`send TASK_ID MESSAGE` sends a follow-up to the specified task; `qz send TASK_ID -` reads the message
-from stdin. A busy task queues a follow-up for its next run. Add `--steer` to deliver the message
-to the current run at its next safe boundary. Both start a new run when the task is idle. Pending
-questions and permissions still require a response.
-
-`--wait` and `--stream` track the submitted message. Streaming starts after that message, including
-when steering continues the same run. Pending questions from the preceding run remain visible so
-you can answer them and let a queued follow-up proceed. A connection failure never resends a message
-automatically.
-
-## Respond to a task
+To let your agent learn when and how to use qz, install the Skill with
+`npx skills add alibaba/qz-browser-agent -g`.
 
-```bash
-qz show TASK_ID
-qz submit TASK_ID '{"selectedIds":["option-a"]}' --stream
-qz approve TASK_ID --wait
-qz reject TASK_ID
-qz watch TASK_ID --stream
-```
+## Connect an MCP client
 
-`show` and pending-input notices include the current question, labeled field IDs,
-option values, descriptions, image URLs, and a submission template with the actual field IDs.
-Edit its placeholder values and run the displayed command to respond. `submit` takes a JSON object
-keyed by field IDs; use option values for choices and arrays for multiple choices. Use
-`qz submit TASK_ID -` to read answers from stdin. Invalid or stale submissions return the current
-input and its template so you can correct the response directly.
-`approve` continues a confirmation after you finish the requested action. `reject` declines the
-current request; `cancel` stops the whole task.
-
-Each response reads the current wait ID before sending. To answer a specific request you already
-read, pass `--wait-id WAIT_ID` to `submit`, `approve`, or `reject`. A stale or invalid response
-leaves the request pending. Review the application consent notice included in the pending input,
-such as location sharing, before approving. Native Chrome permissions require a click in the qz side panel; CLI
-approval reports that action is needed and preserves the wait without opening a browser page.
-With `--wait` or `--stream`, the command stays connected while you grant permission in Chrome.
-Location approval reads the current disclosure version and includes it in the response. Human
-terminal output shows the notice before submitting the explicit approval; JSON output remains a
-single final result. MCP callers should show the notice to the user before sending approval with
-the returned `consentVersion`.
-
-`submit`, `approve`, and `reject` accept `--wait` and `--stream` to follow the task until it finishes, including
-further questions and permission requests. Each new request is shown once. Respond in the side
-panel or another terminal; the original command continues automatically. `watch` follows an
-existing task without resubmitting anything. Timeouts and Ctrl-C stop watching, while the task
-continues in the browser.
-
-## Browser selection and MCP tools
-
-Use `--client ID` or `-c ID` to select a browser when several are connected. Find IDs in `qz status`.
-Use `-t` for `--title`. Run `qz help COMMAND` or `qz COMMAND --help` for command-specific options.
-
-MCP clients can inspect browser tool schemas with `qingzhou_list_tools` and `qingzhou_get_tool`,
-then call `qingzhou_execute_tool` in a task. Set `wait: false` to receive a job ID and read the result
-with `qingzhou_get_tool_job`. Pass `runId` to bind execution to a particular task run. MCP also
-provides `qingzhou_get_trace` and `qingzhou_clear_trace` for diagnostics.
-
-If a request times out or its connection is interrupted, an operation already started in the
-browser may still be running. Check the task before repeating it. Disconnected MCP requests are
-cancelled in the service, and reconnecting does not replay their browser actions.
-
-## Data, images, and Skills
+After `connect`, print the MCP URL:
 
 ```bash
-qz data
-qz data export TABLE
-qz data export TABLE --format csv
-qz data delete TABLE
-qz images
-qz images export COLLECTION
-qz images delete COLLECTION
-qz skills --query research
-qz skills show NAME
-qz skills read NAME scripts/run.js --limit 20000
-qz skills tools --session TASK_ID
-qz skills export NAME
+npx qz-browser-agent@latest mcp
 ```
 
-Use the exact names printed by each list; quote names containing spaces. Data exports default to
-Excel (`xlsx`); `--format csv` selects CSV. Image collections export as a ZIP containing available
-image files and metadata. Missing local images are reported in the result. Skill exports contain
-one user-installed Skill and its resources; built-in Skills require the extension and cannot be
-exported independently.
-
-`skills show` includes the resource paths. `skills read NAME PATH` reads one resource, with a
-default limit of 20,000 characters. Use `--start` and `--limit` to select a chunk; truncated text
-includes the command for the next chunk. `skills tools` lists contributed tools and whether they
-are active in the selected task's context.
-`skills --scope all|global|site|resident` filters by activation scope. Exports accept `--filename NAME`.
-`automations --limit N` limits the automation list.
-
-Exports use Chrome downloads. The result includes the download status, ID, filename, and path when
-Chrome provides it. Check pending downloads in `chrome://downloads`. `delete` removes the named table
-or image collection and its rows. Image blobs shared by other collections or task history remain
-in the asset store.
+The default is `http://127.0.0.1:18765/mcp`; use the URL your command prints if the port differs.
 
-## Settings and automations
+**Codex** (`~/.codex/config.toml`):
 
-```bash
-qz settings
-qz settings get model
-qz settings set model MODEL_ID
-qz settings set vision true
-qz settings set '{"modelParameters":{"temperature":0.5}}'
-qz settings set - < settings.json
-qz automations
-qz automations run AUTOMATION_ID
+```toml
+[mcp_servers.qz]
+url = "http://127.0.0.1:18765/mcp"
 ```
 
-`settings` returns current values, editable fields, provider IDs, and protocol IDs. Credentials are
-redacted; `qz settings get apiKey` reports whether a key is configured. `set KEY VALUE` parses JSON
-values such as booleans, numbers, objects, and arrays; other values are strings. `set JSON` applies
-a patch containing the supplied top-level fields. Follow the field descriptions for values that
-replace an entire object, such as `modelParameters`.
-
-Read credential patches from stdin to keep them out of shell history. JSON is validated before
-connecting. The extension validates field names and values before saving. All commands accept
-`--client ID` to select a browser profile. `automations run` starts an existing automation and
-returns its task ID.
-
-The CLI uses the same browser operations as MCP. Its commands correspond to tasks, data,
-images, Skills, settings, and automations. `qz mcp` only returns the connection URL for MCP
-clients.
-
-## Terminal output
-
-Interactive terminals show readable text; pipes and redirected output receive JSON. Use `--json`
-to request JSON explicitly or `--plain` to keep text when redirecting output. `--no-color` or the
-`NO_COLOR` environment variable disables color. `qz mcp` prints only the MCP URL by default;
-`qz mcp --json` returns a JSON result.
-
-In JSON mode, `--wait` and `--stream` emit one final JSON result on stdout. Complete pending-input
-notices and submission templates appear on stderr so you can respond while preserving
-machine-readable output. MCP snapshots and rejected responses include `input`, with a
-`responseTemplate` that binds answers to the current session and wait. Chrome-native permission
-requests provide user instructions instead of an approval template.
-Exit codes are `0` for success (including reading pending input), `1` for an operation or
-task failure or a rejected submission, `2` for invalid arguments, and `130` for Ctrl-C.
-Connection errors include the GitHub setup guide and installation link.
-
-## Local access
-
-The service listens on loopback. It validates Host and Origin, rejects redirects, and accepts
-extension polling only from extension origins or local clients. Ordinary websites cannot send
-requests through the MCP endpoint. Local programs can control connected qz tasks while the
-service is running. Run `qz stop` to disconnect.
-
-Connection metadata is stored in `~/.qz-browser-agent/run/`; `QZ_STATE_DIR` selects another local
-directory for isolated tests. Atomic startup locks prevent duplicate services. Development copies
-and published installations use separate identities. The client verifies the service identity,
-protocol version, instance, and process before reusing or stopping it. Editing source files or
-running a newer package keeps the healthy service and its connections alive. `status` reports
-when a different build is available. To load the new service code, finish active work, run
-`qz stop`, then `qz connect`.
-
-## Package development
-
-The npm package name is `qz-browser-agent`; the executable name is `qz`. Local development uses
-this same package name. The repository root stays private, and this service directory is the
-publishable package. Publishing requires separate authorization and ownership of the npm name.
-
-From the repository root, install the locked dependencies and run the local source:
+**Claude Code**:
 
 ```bash
-npm ci
-npm run qz -- --version
-npm run qz -- connect
-npm run qz -- create "Summarize the current page." --stream
+claude mcp add --transport http qz http://127.0.0.1:18765/mcp
 ```
 
-Keep the `--` separator when forwarding options through npm. For a local `qz` executable,
-run `npm link` in `services/mcp-bridge`. JavaScript runs directly on Node.js. The published
-package contains the runtime files, tool catalog, README, and license.
+**Clients with an `mcpServers` JSON config**, such as Cursor:
 
-```bash
-npm test -- services --match node
-node tests/release/npm-package.mjs
+```json
+{
+  "mcpServers": {
+    "qz": { "url": "http://127.0.0.1:18765/mcp" }
+  }
+}
 ```
 
-The package check packs the service and installs that tarball in two clean temporary directories
-using the public npm registry. It checks the installed command, versions, MCP tools, service reuse,
-and shutdown on an isolated port. The test owns its npm configuration, cache, connection state,
-and service process. It requires network access to download dependencies.
-
-Use `--output tests/results/npm/qz-browser-agent-0.1.0.tgz` to retain the verified tarball.
-Use `--tarball PATH` to check an existing tarball. The check also runs through
-`npm test -- release --match npm-package`.
-
-## Publish to npm
+CLI and MCP share the same browser connection. The MCP tool list is in the
+[reference](https://github.com/alibaba/qz-browser-agent/blob/main/docs/cli.md#task-and-resource-operations).
 
-Choose the package version in `services/mcp-bridge/package.json`, complete the repository checks,
-and commit the intended source before publishing. CLI and MCP report that same package version.
-Each published version identifies immutable package contents; use a new version for updates.
+## Common commands
 
-The **npm package** GitHub Actions workflow tests the CLI and the installed package on Linux,
-macOS, and Windows. On a manual run, provide the expected version. With **publish** left unchecked,
-it only validates the package and retains the tested tarball. Publishing requires a manual run
-from `main` with **publish** checked; all three platforms must pass first.
-
-Configure the npm package's trusted publisher for the `alibaba/qz-browser-agent` repository,
-workflow `npm-package.yml`, and GitHub environment `npm`. Enable direct publishing in that
-trusted publisher configuration. The publish job uses OIDC and uploads the exact Linux-tested
-tarball. The npm package must be created under an account with publishing rights before this
-trusted publisher can be configured. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
-
-For the first manual release, log in with npm, verify the saved tarball, and publish it:
-
-```bash
-npm login --registry=https://registry.npmjs.org
-node tests/release/npm-package.mjs --output tests/results/npm/qz-browser-agent-0.1.0.tgz
-npm publish tests/results/npm/qz-browser-agent-0.1.0.tgz --access public --registry=https://registry.npmjs.org
-```
-
-The root package stays private. Publishing the service does not publish the Chrome extension.
-After publication, check `npx qz-browser-agent@0.1.0 --version` from a directory outside the repository.
+| Command | What it does |
+| --- | --- |
+| `qz connect` | Start the local service and pair a browser |
+| `qz status` | Check the connection and service address |
+| `qz browsers` | List paired browsers, or `forget` an offline one |
+| `qz create "PROMPT"` | Start a task; add `--stream` or `--wait` to follow it |
+| `qz send TASK_ID "MESSAGE"` | Send a follow-up, or `--steer` the current run |
+| `qz tasks` | List tasks |
+| `qz show TASK_ID` | Read a task's status, response, or pending question |
+| `qz watch TASK_ID` | Follow a running task until it finishes |
+| `qz submit` / `approve` / `reject` | Answer a question or permission request |
+| `qz cancel TASK_ID` | Stop a task |
+| `qz data` | List, export, or delete data tables |
+| `qz images` | List, export, or delete image collections |
+| `qz skills` | Find, read, or export Skills |
+| `qz settings` | Read or update settings |
+| `qz automations` | List or run automations |
+| `qz stop` | Stop the local service and disconnect all browsers |
+
+With several browser profiles connected, choose one with `--client NAME|UUID` (or `-c`).
+Run `qz COMMAND --help` for options. Interactive terminals show readable text; pipes receive JSON.
+
+## Privacy and local access
+
+The service accepts connections only on your computer, and ordinary websites cannot use its MCP
+endpoint. Local programs can control connected qz tasks while the service is running. `qz stop`
+disconnects all browsers and MCP clients; tasks already running in the browser keep going.
+Connection settings are stored in `~/.qz-browser-agent/run/`, and pairing credentials never
+leave your computer.
+
+## Reference
+
+See the [qz CLI and MCP reference](https://github.com/alibaba/qz-browser-agent/blob/main/docs/cli.md)
+for pairing a specific browser profile, Windows PowerShell notes, updates, task responses,
+exports, output formats, exit codes, and the MCP tool mapping.
+
+## License
+
+[Apache-2.0](https://github.com/alibaba/qz-browser-agent/blob/main/LICENSE)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "qz-browser-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local browser tools and MCP access for the qz extension",
   "type": "module",
-  "engines": { "node": ">=24" },
+  "engines": { "node": ">=22" },
   "bin": { "qz": "src/bin.mjs" },
   "files": ["src/*.mjs", "src/catalog.json", "README.md", "LICENSE"],
   "license": "Apache-2.0",

package/src/args.mjs

@@ -1,5 +1,6 @@
 import { parseArgs } from "node:util";
 import { QzError } from "./client.mjs";
+import { browserName } from "./browser-registry.mjs";
 import { COMMANDS, commandOptions } from "./commands.mjs";
 
 function invalid(message) {
@@ -22,7 +23,7 @@ export function parseCommand(argv) {
       title: { type: "string", short: "t" }, client: { type: "string", short: "c" },
       "wait-id": { type: "string" }, format: { type: "string" }, query: { type: "string" },
       start: { type: "string" }, limit: { type: "string" }, scope: { type: "string" }, filename: { type: "string" },
-      parent: { type: "string" },
+      parent: { type: "string" }, port: { type: "string" }, name: { type: "string" }, "no-open": { type: "boolean" },
       wait: { type: "boolean" }, stream: { type: "boolean" }, steer: { type: "boolean" },
       json: { type: "boolean" }, plain: { type: "boolean" }, "no-color": { type: "boolean" },
       help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
@@ -56,6 +57,17 @@ export function parseCommand(argv) {
   for (const name of ["session", "client", "wait-id", "parent"]) {
     if (options[name] !== undefined && !options[name].trim()) invalid(`--${name} requires a non-empty ID.`);
   }
+  if (options.name !== undefined) {
+    try { options.name = browserName(options.name); } catch (error) { invalid(error.message); }
+  }
+  if (options.client !== undefined && (options.name !== undefined || options["no-open"])) {
+    invalid("Use --client to select an existing browser, or --name/--no-open to prepare a binding URL.");
+  }
+  if (options.port !== undefined) {
+    const port = Number(options.port);
+    if (!options.port.trim() || !Number.isInteger(port) || port < 1 || port > 65535) invalid("--port must be an integer from 1 to 65535.");
+    options.port = port;
+  }
   if (options.filename !== undefined && !options.filename.trim()) invalid("--filename requires a non-empty name.");
   if (options.scope !== undefined && !["all", "global", "site", "resident"].includes(options.scope)) invalid("--scope must be all, global, site, or resident.");
   if (options.client !== undefined) {
@@ -78,7 +90,11 @@ export function parseCommand(argv) {
   }
 
   let command = originalCommand, action, id;
-  if (command === "send") {
+  if (command === "browsers") {
+    action = words[0] || "list";
+    if (action === "list" ? words.length > 1 : action !== "forget" || words.length !== 2 || !words[1].trim()) invalid("Use qz browsers [list], or qz browsers forget NAME|UUID.");
+    id = words[1];
+  } else if (command === "send") {
     id = words[0]; options.prompt = words.slice(1).join(" ");
     if (!id?.trim() || !options.prompt.trim()) invalid('Use qz send TASK_ID "MESSAGE".');
   } else if (command === "data" || command === "images" || command === "skills") {

package/src/bin.mjs

@@ -7,19 +7,17 @@ let isEntry = false;
 try { isEntry = realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch {}
 if (isEntry) {
   const argv = process.argv.slice(2);
-  if (Number(process.versions.node.split(".")[0]) < 24) {
+  if (Number(process.versions.node.split(".")[0]) < 22) {
     const error = {
       code: "unsupported_node_version",
-      message: `qz requires Node.js 24 or later. Current version: ${process.versions.node}.`,
-      hint: "Install Node.js 24 or later, then run qz again.",
+      message: `qz requires Node.js 22 or later. Current version: ${process.versions.node}.`,
+      hint: "Install Node.js 22 or later, then run qz again.",
     };
     if (argv.includes("--json")) process.stdout.write(`${JSON.stringify({ ok: false, error })}\n`);
     else process.stderr.write(`${error.message}\n${error.hint}\n`);
     process.exitCode = 1;
   } else {
-    const { main } = await import("./cli.mjs");
-    const controller = new AbortController();
-    process.once("SIGINT", () => controller.abort());
-    process.exitCode = await main(argv, { signal: controller.signal });
+    const { runMain } = await import("./cli.mjs");
+    process.exitCode = await runMain(argv);
   }
 }

package/src/browser-registry.mjs

@@ -0,0 +1,101 @@
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isBrowserId = value => typeof value === "string" && uuid.test(value);
+export function pairingError(code, message) {
+  return Object.assign(new Error(`${code}: ${message}`), { code });
+}
+export function browserName(value) {
+  const name = typeof value === "string" ? value.trim() : "";
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name) || uuid.test(name)) {
+    throw pairingError("BRIDGE_NAME_INVALID", "Use 1–64 letters, digits, underscores, or hyphens, starting with a letter or digit. A UUID cannot be used as a name.");
+  }
+  return name;
+}
+export function sameToken(actual, expected) {
+  if (typeof actual !== "string" || typeof expected !== "string") return false;
+  const a = Buffer.from(actual), b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+async function missingRegistry(path) {
+  // On Windows, ENOENT can also mean that a parent component is a file.
+  for (let candidate = path; ; candidate = dirname(candidate)) {
+    try { await lstat(candidate); }
+    catch (error) {
+      if (error.code !== "ENOENT" || dirname(candidate) === candidate) return false;
+      continue;
+    }
+    return candidate !== path && await stat(candidate).then(entry => entry.isDirectory(), () => false);
+  }
+}
+
+/** The daemon owns this file; its scope lock prevents competing writers. */
+export class BrowserRegistry {
+  constructor({ path, entries = [], persist } = {}) {
+    this.path = path;
+    this.entries = new Map(entries.map(entry => [entry.clientId, entry]));
+    this.persist = persist || (async entries => {
+      if (!path) return;
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+      const temporary = `${path}.${randomUUID()}.tmp`;
+      try {
+        await writeFile(temporary, `${JSON.stringify({ version: 1, browsers: entries })}\n`, { mode: 0o600 });
+        await rename(temporary, path);
+      } finally { await rm(temporary, { force: true }).catch(() => {}); }
+    });
+  }
+
+  static async open(path) {
+    if (!path) return new BrowserRegistry();
+    let document;
+    try { document = JSON.parse(await readFile(path, "utf8")); }
+    catch (error) {
+      if (error.code === "ENOENT" && await missingRegistry(path)) return new BrowserRegistry({ path });
+      throw pairingError("BRIDGE_REGISTRY_READ_FAILED", "Cannot read the browser registry. Restore its valid contents before restarting qz.");
+    }
+    try {
+      if (document.version !== 1 || !Array.isArray(document.browsers)) throw new Error();
+      const ids = new Set(), names = new Set();
+      for (const entry of document.browsers) {
+        if (!isBrowserId(entry.clientId) || browserName(entry.name) !== entry.name
+          || !/^[A-Za-z0-9_-]{43}$/.test(entry.pairingToken) || ids.has(entry.clientId) || names.has(entry.name)) throw new Error();
+        ids.add(entry.clientId); names.add(entry.name);
+      }
+      return new BrowserRegistry({ path, entries: document.browsers });
+    } catch { throw pairingError("BRIDGE_REGISTRY_READ_FAILED", "The browser registry is invalid. Restore its valid contents before restarting qz."); }
+  }
+
+  list() { return [...this.entries.values()].map(({ clientId, name }) => ({ clientId, name })); }
+  get(selector) { return this.entries.get(selector) || [...this.entries.values()].find(entry => entry.name === selector); }
+  async save(entries) {
+    try { await this.persist([...entries.values()]); }
+    catch { throw pairingError("BRIDGE_REGISTRY_WRITE_FAILED", "Could not save the browser registry. Check its directory permissions and retry."); }
+    this.entries = entries;
+  }
+  async pair({ clientId, name, pairingToken }) {
+    const existing = this.entries.get(clientId);
+    if (existing && !sameToken(pairingToken, existing.pairingToken)) {
+      throw pairingError("BRIDGE_PAIRING_REQUIRED", "This browser identity is already paired. Use its original profile, or forget the offline browser before pairing again.");
+    }
+    if (!name && !existing) {
+      let index = this.entries.size ? 2 : 1;
+      do { name = index === 1 ? "default" : `browser-${index}`; index++; } while (this.get(name));
+    }
+    name = browserName(name || existing?.name);
+    const occupied = this.get(name);
+    if (occupied && occupied.clientId !== clientId) throw pairingError("BRIDGE_NAME_IN_USE", `Browser name ${name} is already registered. Choose another name or forget its offline registration.`);
+    if (existing?.name === name) return existing;
+    if (pairingToken !== undefined && !/^[A-Za-z0-9_-]{43}$/.test(pairingToken)) throw pairingError("BRIDGE_PAIRING_REQUIRED", "The browser pairing proof is invalid. Reconnect from the extension settings.");
+    const entry = { clientId, name, pairingToken: existing?.pairingToken || pairingToken || randomBytes(32).toString("base64url") };
+    await this.save(new Map(this.entries).set(clientId, entry));
+    return entry;
+  }
+  async forget(clientId) {
+    const entries = new Map(this.entries);
+    entries.delete(clientId);
+    await this.save(entries);
+  }
+}