qz-browser-agent 0.1.1 → 0.1.2

package/README.md

@@ -1,467 +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
-
-Install [qz from the Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm)
-with **Add to Chrome**. Open the qz side panel, complete its first-use data notice, and configure
-your provider and model in Settings.
-
-Run the published package with npx:
-
-```bash
-npx qz-browser-agent@latest connect
-npx qz-browser-agent@latest create "Summarize the current page." --stream
-```
-
-`npx qz-browser-agent@latest install` opens the same Chrome Web Store page. For a manual ZIP
-installation, download the [latest GitHub release](https://github.com/alibaba/qz-browser-agent/releases/latest)
-and follow the [manual installation steps](https://github.com/alibaba/qz-browser-agent/blob/main/README.md#manual-installation).
-
-`connect` starts the local MCP service and opens its connection page for first pairing. Use the
-Chrome profile where qz is installed. The first new profile is named `default`;
-accepting the data notice alone does not enable the local connection. Repeating `connect` reuses
-an online browser. Add further profiles with a [pairing URL](#pair-a-selected-browser-from-the-shell)
-or from their own qz Settings.
-
-The examples and suggested next commands use `qz`. Replace it with
-`npx qz-browser-agent@latest`, or install the command globally:
-
-```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 a compatible release version verified with your extension.
+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.
 
-## Connect and stop
-
-```bash
-qz connect
-qz status
-qz browsers
-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. It prefers port 18765;
-if that port belongs to another program, the service chooses a free port. `status` shows the actual
-service address, and `mcp` prints its MCP URL. Both commands are read-only. To request a custom port,
-run `qz connect --port 18766`; an existing service on another port remains running and the command
-reports its address. The extension connects only to its configured address.
+![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)
 
-The connection page can be closed once `qz browsers` shows the profile online. Connections start
-only through `qz connect` or **qz Settings → Advanced → CLI → Connect CLI**. For ordinary connection
-failures, the extension makes at most three recovery attempts, 30 seconds apart, then pauses.
-After a browser or background restart, it may first wait once for the previous connection to expire.
-The saved retry budget survives worker restarts. Click **Connect CLI** in that browser's settings to retry.
-
-To disconnect one browser, click **Disconnect: NAME** in its qz Settings. `qz stop` stops the local
-service and disconnects every browser and MCP client using it. Browser tasks already running
-remain in the extension; stopping the service does not cancel them. Use `qz cancel TASK_ID` to stop
-a task, adding `--client NAME|UUID` when needed.
-
-### Pair a selected browser from the shell
-
-Get a pairing URL without opening the default browser or waiting for a connection:
-
-```bash
-qz connect --no-open --json
-qz connect --no-open --name work --json
-```
-
-The JSON envelope contains `result.endpoint`, `result.url`, `result.mcpUrl`, and
-`result.opened: false`. The command starts or reuses the service even when other browsers are
-already connected. Open the exact returned URL in the intended browser Profile with qz installed.
-
-Set `QZ_PAIRING_URL` to that URL and `QZ_PROFILE_DIRECTORY` to the selected profile's directory
-name, such as `Default` or `Profile 2`. These are directory names, not Chrome's display labels.
-Use a Profile already chosen by the user. On macOS:
-
-```sh
-open -na "Google Chrome" --args --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
-```
-
-For Chrome on Linux:
+## Quick start
 
-```sh
-google-chrome --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
-```
+Requires Node.js 22 or later.
 
-For Chrome installed under Program Files on Windows, set `$QzProfileDirectory` and
-`$QzPairingUrl` to those same values in PowerShell:
+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.
 
-```powershell
-& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" "--profile-directory=$QzProfileDirectory" $QzPairingUrl
-```
+   ```bash
+   npx qz-browser-agent@latest connect
+   ```
 
-Use the installed browser's executable or app name. For an existing custom data directory, also
-pass `--user-data-dir` with its exact path; for example on macOS:
+3. **Run your first task.**
 
-```sh
-open -na "Google Chrome" --args --user-data-dir="$QZ_USER_DATA_DIR" --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
-```
+   ```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
+   ```
 
-The [Chrome profile documentation](https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md)
-distinguishes the data directory from the Profile inside it. A new data directory needs its own
-extension installation and first-use setup.
+   `--stream` shows progress, any questions qz needs you to answer, and the final result.
 
-`--name work` adds `?name=work` to the URL. The Profile opening it receives that identifier,
-including when it already has a connection. Without `--name`, a registered Profile keeps its name;
-a new Profile receives the next available name: `default`, `browser-2`, and so on. A name conflict
-requires another name. `qz connect --name work` opens the URL automatically and returns immediately.
-These URL-returning commands do not confirm that a browser connected. Verify it with:
+For regular use, install the `qz` command globally and use it in place of
+`npx qz-browser-agent@latest`:
 
 ```bash
-qz browsers --json
-qz create "Summarize the current page." --client UUID --stream
+npm install --global qz-browser-agent@latest
+qz --version
 ```
 
-Read `result.browsers`, then use the intended online entry's `clientId` UUID. `--client` selects an
-existing connection and cannot be combined with `--no-open` or `--name`. `--port` works with either
-pairing mode and follows the existing-service behavior above.
-
-### Add and select browsers
-
-You can also pair from **qz Settings → Advanced → CLI** in the intended Profile. Enter a distinct
-browser identifier and connect. Use the service address printed by `qz status` in **Local service address** if
-its port differs from 18765. Names use 1–64 letters, digits, underscores, or hyphens, beginning with
-a letter or digit; names are case-sensitive. UUID-shaped names are reserved for profile IDs.
-
-```bash
-qz browsers
-qz create "Summarize the current page." --client work --stream
-qz show TASK_ID --client work
-qz data --client work
-```
+To let your agent learn when and how to use qz, install the Skill with
+`npx skills add alibaba/qz-browser-agent -g`.
 
-`--client NAME|UUID` and `-c NAME|UUID` select a profile. With exactly one online browser, the CLI
-selects it automatically. With several online browsers, a selection is required; `default` is a
-name, not a routing preference. An unknown or offline selection fails without opening or using
-another browser. Each command resolves its name once and carries the UUID through subsequent
-requests. JSON task results and suggested next commands include that UUID.
+## Connect an MCP client
 
-Names remain registered while their browsers are offline and across service restarts. To release
-an offline name, remove its registration explicitly:
+After `connect`, print the MCP URL:
 
 ```bash
-qz browsers forget work
+npx qz-browser-agent@latest mcp
 ```
 
-An online browser must first disconnect in its settings. Forgetting a registration leaves the
-browser's tasks and data intact. A browser can then explicitly pair using the released name.
-
-### Update the connection
+The default is `http://127.0.0.1:18765/mcp`; use the URL your command prints if the port differs.
 
-Use the current CLI and extension together. Source edits and a newer npm package leave a healthy
-running service in place; `qz status` reports an available update. An incompatible service returns
-an update instruction instead of being stopped automatically.
-
-1. Use the latest CLI and let current tasks finish.
-2. Run `npx --yes qz-browser-agent@latest stop`. This disconnects all browsers using that service.
-3. Update qz from the [Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm).
-   For a manual ZIP installation, replace its extracted files with the
-   [latest release](https://github.com/alibaba/qz-browser-agent/releases/latest) and reload it at `chrome://extensions`.
-4. Run `npx --yes qz-browser-agent@latest connect`, then reconnect additional profiles using their
-   pairing URL or settings.
-
-## Connect an MCP client
-
-Run `qz connect`, then `qz mcp`. Copy the returned URL into your MCP client's HTTP configuration:
+**Codex** (`~/.codex/config.toml`):
 
 ```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`. Use `qingzhou_bridge_status` to list browser names
-and UUIDs, then pass `clientId: "work"` or a UUID to browser tools. Selection is required with
-multiple online browsers. Task results include the resolved `clientId`. MCP initialization and streaming are handled by your
-client's MCP implementation.
-
-### Task and resource operations
-
-CLI and MCP use the same task observer and browser operations. The task and resource commands map to these MCP operations:
-
-| CLI | MCP tool |
-| --- | --- |
-| `browsers`, `browsers forget` | `qingzhou_bridge_status`, `qingzhou_forget_browser` |
-| `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:
-
-```json
-{"firstMessage":"Summarize the current page.","stream":true}
-```
-
-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.
-
-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.
-
-## Run a task
-
-```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
-```
-
-`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
-
-```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
-```
-
-`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 NAME|UUID` or `-c NAME|UUID` to select a browser. `qz browsers` lists registered names,
-UUIDs, and online status. See [browser selection](#add-and-select-browsers) for pairing and name reuse.
-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
-
-```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
-```
-
-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.
-
-## Settings and automations
+**Claude Code**:
 
 ```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
+claude mcp add --transport http qz 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. Browser commands accept
-`--client NAME|UUID` to select a 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 and browser registrations are stored in `~/.qz-browser-agent/run/`;
-`QZ_STATE_DIR` selects another local directory for isolated tests. Registration writes are atomic;
-a failed write leaves the previous registration active. Private pairing proofs stay in local storage
-and are omitted from status output. 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:
+**Clients with an `mcpServers` JSON config**, such as Cursor:
 
-```bash
-npm ci
-npm run qz -- --version
-npm run qz -- connect
-npm run qz -- create "Summarize the current page." --stream
-```
-
-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.
-
-```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.1.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
-
-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.
-
-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.
+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).
 
-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/).
+## Common commands
 
-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.1.tgz
-npm publish tests/results/npm/qz-browser-agent-0.1.1.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.1 --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.1",
+  "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/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/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";
@@ -73,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);
 }
@@ -219,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,
@@ -283,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.");
@@ -351,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,5 +1,4 @@
 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";
@@ -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/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, "")

package/src/tools.mjs

@@ -91,8 +91,10 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
         : 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;
     }
   };