qz-browser-agent 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,467 @@
-# Temporary Holding Version
+# qz command line and MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## 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.
+
+## Connect and stop
+
+```bash
+qz connect
+qz status
+qz browsers
+qz mcp
+qz stop
+```
+
+`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.
+
+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:
+
+```sh
+google-chrome --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
+```
+
+For Chrome installed under Program Files on Windows, set `$QzProfileDirectory` and
+`$QzPairingUrl` to those same values in PowerShell:
+
+```powershell
+& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" "--profile-directory=$QzProfileDirectory" $QzPairingUrl
+```
+
+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:
+
+```sh
+open -na "Google Chrome" --args --user-data-dir="$QZ_USER_DATA_DIR" --profile-directory="$QZ_PROFILE_DIRECTORY" "$QZ_PAIRING_URL"
+```
+
+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.
+
+`--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:
+
+```bash
+qz browsers --json
+qz create "Summarize the current page." --client UUID --stream
+```
+
+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
+```
+
+`--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.
+
+Names remain registered while their browsers are offline and across service restarts. To release
+an offline name, remove its registration explicitly:
+
+```bash
+qz browsers forget work
+```
+
+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
+
+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:
+
+```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
+
+```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
+```
+
+`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:
+
+```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
+```
+
+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.
+
+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.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.