qz-browser-agent 0.1.3 → 0.1.5

package/README.md

@@ -2,54 +2,78 @@
 
 An open-source browser agent for humans and coding agents.
 
-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.
+qz is a local-first extension for Chrome and Edge. This CLI and its MCP endpoint let coding agents
+such as Claude Code, Codex, and pi drive your own browser, with your existing logins, or hand qz a
+whole web task. Driving the browser needs no model configured in qz: your agent writes a short
+script, and qz returns a compact result and trace that keep its token use low. People can watch
+and step in from the side panel. Everything runs locally.
 
 [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)
 
-![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)
-
 ## Quick start
 
 Requires Node.js 22 or later.
 
 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.
+   [Chrome Web Store](https://chromewebstore.google.com/detail/dknbdgkgoinlgjpfebapkklbmjjgdblm).
+2. **Install the CLI.** Or use `npx qz-browser-agent@latest` in place of `qz`.
+
+   ```bash
+   npm install --global qz-browser-agent@latest
+   ```
+3. **Drive the browser.** No model setup is needed in qz.
 
    ```bash
-   npx qz-browser-agent@latest connect
+   qz session create --title "Read example page"
+   qz script --session SESSION_ID - <<'JS'
+   const page = qz.tab(await qz.openTab({ url: "https://example.com" }));
+   return await page.read({ limit: 2000 });
+   JS
    ```
 
-3. **Run your first task.**
+   The first command connects the browser automatically. To teach your agent the full workflow,
+   install the qz Skill with `npx skills add alibaba/qz-browser-agent -g`, or have it read `qz skill`.
+4. **Or hand qz the whole task.** Choose a provider and model in the side panel's **Settings**, then:
 
    ```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
+   qz create "Find this year's Nobel Prize winners in every category and put them in a table with source links." --stream
    ```
 
    `--stream` shows progress, any questions qz needs you to answer, and the final result.
 
-For regular use, install the `qz` command globally and use it in place of
-`npx qz-browser-agent@latest`:
+## Drive the browser
 
 ```bash
-npm install --global qz-browser-agent@latest
-qz --version
+qz skill
+qz session create --title "Read example page" --json
+qz script --session SESSION_ID task.js --args '{"query":"example"}'
+qz session show SESSION_ID
+qz session cancel SESSION_ID
 ```
 
-To let your agent learn when and how to use qz, install the Skill with
-`npx skills add alibaba/qz-browser-agent -g`.
+`session create` starts no model. With `--json`, `result.qz_skills` lists the Skills the new session
+can use right away, and `qz.call("load_skill",{name})` makes another Skill's tools callable at once.
+
+Scripts run outside pages and use the `qz` SDK. Bind `qz.tab(tabRef)` for page operations,
+use `page.locator(query)` for element actions and waits, and `page.evaluate(code,args?)` for DOM access.
+Discover additional capabilities with `qz.listTools()` or `qz.listTools({names:["list_images"]})`,
+then invoke them through `qz.call(name,args)`. stdout is JSON `{ok,result,trace}`: execution status, the returned business value,
+and ordered error and `trace()`/`console` messages without levels. Failures put `ToolError` in `result`; `undefined`
+returns become `null`.
+
+Browser operations prepare their connection automatically: they reuse the first responding
+online browser, or open the connection page once in the system default browser. When qz does not respond
+there, the page links to the Chrome Web Store and shows its URL with a copy button for a browser that has qz.
+Select an existing profile with --client NAME|UUID; it never falls back to another profile. An incompatible
+local service is restarted once before browser operations. Complete the extension’s connection
+prompt when needed.
 
 ## Connect an MCP client
 
-After `connect`, print the MCP URL:
+Print the MCP URL; this starts the local service if needed:
 
 ```bash
 npx qz-browser-agent@latest mcp
@@ -80,15 +104,17 @@ claude mcp add --transport http qz http://127.0.0.1:18765/mcp
 }
 ```
 
-CLI and MCP share the same browser connection. The MCP tool list is in the
+CLI and MCP share the same browser connection. The default MCP catalog is the direct-drive set;
+`qz mcp --profile full` prints the URL for the task and diagnostic catalog. The MCP tool list is in the
 [reference](https://github.com/alibaba/qz-browser-agent/blob/main/docs/cli.md#task-and-resource-operations).
 
 ## Common commands
 
 | Command | What it does |
 | --- | --- |
-| `qz connect` | Start the local service and pair a browser |
+| `qz connect uri` | Print a URL to open in a chosen browser profile |
 | `qz status` | Check the connection and service address |
+| `qz cleanup` | Stop registered local services and remove runtime files and logs |
 | `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 |
@@ -102,7 +128,6 @@ CLI and MCP share the same browser connection. The MCP tool list is in the
 | `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.
@@ -116,8 +141,12 @@ Timeout or Ctrl-C ends observation while the browser task continues; execute the
 ## 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.
+endpoint. Local programs can control connected qz tasks while the service is running. Disconnect
+a profile in its qz connection settings; task cancellation remains a separate operation.
+Run `qz cleanup` to stop local services across installations and remove their runtime files and logs.
+It preserves browser registrations, tabs, tasks and saved data; the next browser command starts its
+service automatically. Active CLI requests and direct-drive scripts are interrupted; side-panel tasks
+continue. `QZ_STATE_DIR` selects a different runtime directory when set.
 Connection settings are stored in `~/.qz-browser-agent/run/`, and pairing credentials never
 leave your computer.
 

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "qz-browser-agent",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Local browser tools and MCP access for the qz extension",
   "type": "module",
   "engines": { "node": ">=22" },
   "bin": { "qz": "src/bin.mjs" },
-  "files": ["src/*.mjs", "src/catalog.json", "README.md", "LICENSE"],
+  "files": ["src/*.mjs", "src/catalog.json", "src/qz-drive-SKILL.md", "src/qz-logo.png", "src/qz-logo-day.png", "README.md", "LICENSE"],
+  "scripts": {
+    "prepack": "cp ../../skills/qz-browser-agent/SKILL.md src/qz-drive-SKILL.md && cp ../../src/icons/icon128.png src/qz-logo.png && cp ../../src/icons/logo-day.png src/qz-logo-day.png"
+  },
   "license": "Apache-2.0",
   "homepage": "https://alibaba.github.io/qz-browser-agent/",
   "bugs": { "url": "https://github.com/alibaba/qz-browser-agent/issues" },

package/src/args.mjs

@@ -1,10 +1,16 @@
 import { parseArgs } from "node:util";
 import { QzError } from "./client.mjs";
 import { browserName } from "./browser-registry.mjs";
-import { COMMANDS, commandOptions } from "./commands.mjs";
+import { COMMANDS, DRIVE_SESSION_REQUIRED, commandOptions } from "./commands.mjs";
 
 function invalid(message) {
-  throw new QzError("invalid_arguments", message);
+  throw new QzError("INVALID_ARGUMENTS", message, {
+    hint: "Run qz --help, or npm run qz -- --help, to check the command and its arguments.",
+  });
+}
+
+function requireDriveSession(command, options) {
+  if (!String(options.session || "").trim()) invalid(`qz ${command} requires --session <id>. ${DRIVE_SESSION_REQUIRED}`);
 }
 
 function helpTopic(parts) {
@@ -14,20 +20,29 @@ function helpTopic(parts) {
   invalid("Use qz help COMMAND.");
 }
 
+const argumentOptions = {
+  session: { type: "string", short: "s" }, timeout: { type: "string" },
+  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" }, port: { type: "string" }, name: { type: "string" },
+  wait: { type: "boolean" }, stream: { type: "boolean" }, steer: { type: "boolean" },
+  json: { type: "boolean" }, plain: { type: "boolean" }, "no-color": { type: "boolean" },
+  lang: { type: "string" }, profile: { type: "string" }, args: { type: "string" },
+  keep: { type: "string", multiple: true },
+  help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
+};
+
+/** Identify the command for syntax-error presentation while consuming option values normally. */
+export function commandNameFromArgs(argv) {
+  return parseArgs({ args: argv, allowPositionals: true, strict: false, options: argumentOptions }).positionals[0] || "help";
+}
+
 /** Parse syntax only. A prompt or args value of "-" is read from stdin by the caller. */
 export function parseCommand(argv) {
   let parsed;
   try {
-    parsed = parseArgs({ args: argv, allowPositionals: true, strict: true, tokens: true, options: {
-      session: { type: "string", short: "s" }, timeout: { type: "string" },
-      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" }, 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" },
-    } });
+    parsed = parseArgs({ args: argv, allowPositionals: true, strict: true, tokens: true, options: argumentOptions });
   } catch (error) { invalid(error.message); }
 
   const options = { ...parsed.values };
@@ -35,7 +50,7 @@ export function parseCommand(argv) {
   for (const token of parsed.tokens) {
     if (token.kind !== "option" || token.value === undefined) continue;
     const name = token.name;
-    if (seen.has(name)) invalid(`Provide --${name} only once.`);
+    if (seen.has(name) && !argumentOptions[name].multiple) invalid(`Provide --${name} only once.`);
     seen.add(name);
   }
   if (options.json && options.plain) invalid("Choose --json or --plain.");
@@ -57,11 +72,15 @@ 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.keep !== undefined) {
+    options.keep = options.keep.map(value => value.trim());
+    if (options.keep.some(value => !value)) invalid("--keep requires a non-empty tabRef.");
+  }
   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.client !== undefined && options.name !== undefined) {
+    invalid("Use --client to select an existing browser, or --name to name a new profile.");
   }
   if (options.port !== undefined) {
     const port = Number(options.port);
@@ -70,6 +89,8 @@ export function parseCommand(argv) {
   }
   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.profile !== undefined && !["full", "drive"].includes(options.profile)) invalid("--profile must be full or drive.");
+  if (options.lang !== undefined && !options.lang.trim()) invalid("--lang requires a value.");
   if (options.client !== undefined) {
     options["client-id"] = options.client;
     delete options.client;
@@ -90,7 +111,10 @@ export function parseCommand(argv) {
   }
 
   let command = originalCommand, action, id;
-  if (command === "browsers") {
+  if (command === "connect") {
+    if (words.length !== 1 || words[0] !== "uri") invalid("Use qz connect uri to print a browser connection URL.");
+    action = "uri";
+  } else 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];
@@ -141,6 +165,23 @@ export function parseCommand(argv) {
     id = words[0];
     if (command === "submit") options.args = words[1];
     if (command === "watch") options.wait = true;
+  } else if (command === "script") {
+    if (words.length > 1) invalid("Use qz script --session ID [FILE|-] [--args JSON].");
+    requireDriveSession("script", options);
+    options.file = words[0] ?? "-";
+    if (options.args !== undefined) {
+      try { options.args = JSON.parse(options.args); } catch { invalid("--args must be valid JSON."); }
+    }
+  } else if (command === "session") {
+    action = words[0] || "";
+    const count = ["create", "list"].includes(action) ? 1 : 2;
+    if (!Object.hasOwn(COMMANDS.session.actions, action) || words.length !== count || words.some(word => !word.trim())) {
+      invalid("Use qz session create --title TITLE, qz session list, qz session show ID, or qz session cancel ID.");
+    }
+    if (action === "create" && !String(options.title || "").trim()) invalid("qz session create requires --title TITLE. Choose a readable task title.");
+    id = words[1];
+  } else if (command === "skill") {
+    if (words.length) invalid("Use qz skill.");
   } else if (command === "tasks") {
     if (words.length) invalid("Use qz tasks to list tasks, qz create PROMPT, qz show ID, or qz cancel ID.");
     action = "list";

package/src/bin.mjs

@@ -9,11 +9,11 @@ if (isEntry) {
   const argv = process.argv.slice(2);
   if (Number(process.versions.node.split(".")[0]) < 22) {
     const error = {
-      code: "unsupported_node_version",
+      code: "UNSUPPORTED_NODE_VERSION",
       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`);
+    if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(error)}\n`);
     else process.stderr.write(`${error.message}\n${error.hint}\n`);
     process.exitCode = 1;
   } else {

package/src/catalog.json

@@ -53,6 +53,8 @@
       "properties": {
         "limit": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Limit"},
         "excludeSessionId": {"default": "", "title": "Excludesessionid", "type": "string"},
+        "scope": {"type": "string", "description": "session returns one session. Omit it to list tasks."},
+        "sessionId": {"type": "string", "description": "Session to return when scope is session."},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
         "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
@@ -228,7 +230,7 @@
   },
   {
     "name": "qingzhou_get_session_snapshot",
-    "description": "Read a task snapshot: session, runtime, current input, transcript, recent messages, artifacts, and optional trace/tools. Pending input includes field IDs, option values, instructions, and responseTemplate for answering directly. Tool transcript argsState/argsGenerating distinguish generating arguments from final empty arguments.",
+    "description": "Read a task snapshot: session, runtime, current input, transcript, recent messages, artifacts, cumulative usage, and optional trace/tools. usage sums recorded model calls (inputTokens, outputTokens, cachedTokens, costUsd, modelCalls) plus toolCalls, screenshots, and contextCompressions. Pending input includes field IDs, option values, instructions, and responseTemplate for answering directly. Tool transcript argsState/argsGenerating distinguish generating arguments from final empty arguments.",
     "inputSchema": {
       "properties": {
         "sessionId": {"default": "default", "title": "Sessionid", "type": "string"},
@@ -264,11 +266,13 @@
   },
   {
     "name": "qingzhou_stop_session",
-    "description": "停止轻舟会话运行。",
+    "description": "结束任务或直驱会话。直驱会话结束后不可再执行工具，也无需再调用 close_tab；默认自动关闭该会话创建的标签页，并保留用户原有或已交回给用户的标签页。keepTabRefs 指定要交还用户的会话标签，keepTabs:true 保留全部标签页。End a task or direct-drive session, closing its created tabs by default while preserving user tabs. Pass keepTabRefs to return selected session tabs to the user, or keepTabs:true to retain all tabs.",
     "inputSchema": {
       "properties": {
         "sessionId": {"title": "Sessionid", "type": "string"},
         "cascade": {"default": true, "title": "Cascade", "type": "boolean"},
+        "keepTabs": {"title": "Keeptabs", "type": "boolean"},
+        "keepTabRefs": {"type": "array", "items": {"anyOf": [{"type": "integer"}, {"type": "string"}]}, "description": "Session tabRef values to keep after ending the session. Validated before stopping."},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
         "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
@@ -279,10 +283,10 @@
   },
   {
     "name": "qingzhou_list_tools",
-    "description": "列出当前 session 可用的轻舟内置工具和插件工具 schema。",
+    "description": "List default direct-drive tool signatures; sessionId is optional. Query non-default or loaded Skill tools by exact name with qingzhou_get_tool (pass sessionId for loaded Skills). For full schemas, call tools.list_tools({names:[...]}) inside run_script. Never creates a session.",
     "inputSchema": {
       "properties": {
-        "sessionId": {"default": "default", "title": "Sessionid", "type": "string"},
+        "sessionId": {"title": "Sessionid", "type": "string"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
         "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
@@ -337,20 +341,79 @@
       "type": "object"
     }
   },
+  {
+    "name": "qingzhou_list_drive_sessions",
+    "description": "List direct-drive sessions as {sessionId,title,status} observations.",
+    "inputSchema": {
+      "properties": {
+        "timeoutSeconds": {"type": ["number", "null"], "default": null},
+        "clientId": {"type": "string", "default": "", "description": "Browser name or UUID."}
+      },
+      "type": "object"
+    }
+  },
+  {
+    "name": "qingzhou_get_drive_session",
+    "description": "Read one direct-drive session as {sessionId,title,status}.",
+    "inputSchema": {
+      "properties": {
+        "sessionId": {"type": "string", "minLength": 1},
+        "timeoutSeconds": {"type": ["number", "null"], "default": null},
+        "clientId": {"type": "string", "default": "", "description": "Browser name or UUID."}
+      },
+      "required": ["sessionId"],
+      "type": "object"
+    }
+  },
+  {
+    "name": "qingzhou_create_drive_session",
+    "description": "Create one direct-drive session with a readable title and return sessionId, title, status, and qz_skills (summaries of the user workflows available to the session). Pass that id on every tool execution. This does not start a model.",
+    "inputSchema": {
+      "required": ["title"],
+      "properties": {
+        "title": {"type": "string", "minLength": 1, "pattern": "\\S", "description": "Readable task title."},
+        "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
+        "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
+      },
+      "title": "qingzhou_create_drive_sessionArguments",
+      "type": "object"
+    }
+  },
   {
     "name": "qingzhou_execute_tool",
-    "description": "直接执行轻舟工具，用于系统 skill/plugin 调试。依赖 Agent 生命周期的页面工具请传当前 runId；wait=false 时后台执行并立即返回 jobId。",
+    "description": "在已连接的浏览器里执行现有工具。先调用 qingzhou_create_drive_session 创建会话，再传入该 sessionId（不会隐式创建会话）。单次调用传 name 与 args；已知参数的并发或顺序批次传 calls（每项含 id、name、args，id 仅用于关联结果，不支持跨项插值）；多步逻辑与条件编排可调用 name:\"run_script\"（页面外执行，支持顶层 await/return 与 tools.*，页面内 DOM 函数用 evaluate）。页面工具显式传 tabRef。逐项检查 isError，批次与脚本均非事务；run_script 的 result 为 {ok,result,trace} 回执，trace 按序记录报错与显式 trace()/console 输出。Execute browser tools in an explicitly created session (pass sessionId from qingzhou_create_drive_session). Supply name/args for one call, calls ([{id,name,args}]) for a static batch, or name:\"run_script\" for outer JS orchestration (use evaluate for in-page DOM functions). Page tools require an explicit tabRef. Check isError on each call; batches and scripts are not transactions. run_script returns {ok,result,trace}, where trace lists errors and explicit trace()/console diagnostics in order.",
     "inputSchema": {
       "properties": {
+        "scriptApiVersion": {"type": "integer", "minimum": 1, "description": "Script API protocol version; must match the extension before executing the request."},
         "name": {"title": "Name", "type": "string"},
         "args": {"anyOf": [{"additionalProperties": true, "type": "object"}, {"type": "null"}], "default": null, "title": "Args"},
-        "sessionId": {"default": "default", "title": "Sessionid", "type": "string"},
-        "runId": {"default": "", "title": "Runid", "type": "string"},
+        "calls": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "name"],
+            "properties": {
+              "id": {"type": "string"},
+              "name": {"type": "string"},
+              "args": {"type": "object", "additionalProperties": true}
+            }
+          }
+        },
+        "limits": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "timeoutSeconds": {"type": "number"},
+            "maxCalls": {"type": "number"}
+          }
+        },
+        "sessionId": {"title": "Sessionid", "type": "string"},
         "wait": {"default": true, "title": "Wait", "type": "boolean"},
         "timeoutSeconds": {"anyOf": [{"type": "number"}, {"type": "null"}], "default": null, "title": "Timeoutseconds"},
         "clientId": {"default": "", "title": "Clientid", "type": "string", "description": "Browser name or UUID. Required when multiple browsers are online. Offline or unknown selections never fall back to another browser."}
       },
-      "required": ["name"],
+      "required": ["sessionId"],
       "title": "qingzhou_execute_toolArguments",
       "type": "object"
     }
@@ -372,12 +435,12 @@
   },
   {
     "name": "qingzhou_get_tool",
-    "description": "Read one browser tool's description and input schema by exact name in the selected task's context.",
+    "description": "Read a tool by exact name without a session. Pass sessionId for a loaded Skill tool. Direct drive returns a compact signature and description; this call never creates a session.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "name": {"type": "string", "minLength": 1},
-        "sessionId": {"type": "string", "default": "default"},
+        "sessionId": {"type": "string"},
         "timeoutSeconds": {"type": ["number", "null"], "default": null},
         "clientId": {"type": "string", "default": ""}
       },

package/src/cli-resources.mjs

@@ -11,9 +11,9 @@ export function settingsPatch(id, value, json = {}) {
     try { parsed = JSON.parse(value); } catch { /* An unquoted CLI value is a string. */ }
     config = { [id]: parsed };
   }
-  if (!record(config) || !Object.keys(config).length) throw new QzError("invalid_arguments", "Settings must be a non-empty JSON object.");
+  if (!record(config) || !Object.keys(config).length) throw new QzError("INVALID_ARGUMENTS", "Settings must be a non-empty JSON object.");
   if (Object.keys(config).some(key => !key.trim() || ["__proto__", "prototype", "constructor"].includes(key))) {
-    throw new QzError("invalid_arguments", "Settings contain an invalid field name.");
+    throw new QzError("INVALID_ARGUMENTS", "Settings contain an invalid field name.");
   }
   return config;
 }