qz-browser-agent 0.1.3 → 0.1.5

package/src/cli.mjs

@@ -1,17 +1,21 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { setTimeout as delay } from "node:timers/promises";
-import { GUIDE_URL, INSTALL_URL, QzError, withToolClient, readHealth } from "./client.mjs";
-import { ensureDaemon, findDaemon, stopDaemon } from "./daemon.mjs";
+import { GUIDE_URL, INSTALL_URL, QzError, withToolClient } from "./client.mjs";
+import { cleanupDaemons, ensureDaemon, findDaemon } from "./daemon.mjs";
 import { openBrowser } from "./open-browser.mjs";
-import { parseCommand } from "./args.mjs";
+import { connectionUri, prepareConnection } from "./connection.mjs";
+import { commandNameFromArgs, parseCommand } from "./args.mjs";
 import { renderError, renderHelp, renderResult, renderInputNotice, sanitizeTerminalText } from "./terminal.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";
 import { optionTerminator, shellArgument } from "./shell.mjs";
+import { driveGuide } from "./drive-guide.mjs";
+import { buildScriptRequest, presentScriptFailure, presentScriptResult, scriptTimeouts } from "./script-call.mjs";
 
 export const HELP = renderHelp();
 
@@ -40,32 +44,33 @@ async function stdinText({ signal } = {}) {
   });
 }
 
-const UPGRADE_HINT = "Use the latest CLI. After current tasks finish, run npx --yes qz-browser-agent@latest stop (disconnects all browsers), update and reload the qz extension, then run npx --yes qz-browser-agent@latest connect.";
+const UPGRADE_HINT = "Update the installed CLI and browser extension, then retry the command.";
 
 function requirePairingSupport(health) {
-  if (health?.features?.browserPairing !== 1) throw new QzError("upgrade_required",
-    "This qz service is unsupported. Upgrade the CLI and extension, then run qz stop and qz connect.",
+  if (health?.features?.browserPairing !== 1) throw new QzError("UPGRADE_REQUIRED",
+    "This qz service is unsupported. Update the CLI and extension, then retry the command.",
     { hint: UPGRADE_HINT });
 }
 
-function selectClient(health, selector = "", { allowEmpty = false } = {}) {
-  const clients = health.status?.clients || [];
-  if (selector) {
-    const entry = (health.status?.browsers || []).find(client => client.clientId === selector || client.name === selector);
-    const selected = clients.find(client => client.clientId === (entry?.clientId || selector));
-    if (selected) return selected.clientId;
-    throw new QzError(entry ? "client_offline" : "client_not_found", `Browser ${selector} is ${entry ? "offline" : "not registered"}.`,
-      { hint: "Run qz browsers to inspect names and UUIDs. Reconnect that profile from its extension settings." });
-  }
-  if (clients.length > 1) throw new QzError("selection_required", "Multiple browsers are connected. Select one with --client NAME|UUID.",
-    { clients: clients.map(({ clientId, name }) => ({ clientId, name })), hint: clients.map(client => `${client.name || client.clientId}: ${client.clientId}`).join("\n") });
-  if (clients.length === 1) return clients[0].clientId;
-  if (allowEmpty) return "";
-  throw connectionRequired();
+function connectionRequired() {
+  return new QzError("NOT_CONNECTED", "Run qz connect uri and open its URL in the browser profile with qz installed. Session and script commands prepare their connection automatically.");
 }
 
-function connectionRequired() {
-  return new QzError("not_connected", "Run qz connect to start the local service and connect Chrome. If qz is not installed, run qz install.");
+function imageFilePaths(images, directory, prefix) {
+  const files = (Array.isArray(images) ? images : []).filter(image => image && typeof image.data === "string");
+  if (!files.length) return null;
+  return files.map((image, index) => {
+    const extension = image.mimeType === "image/jpeg" ? "jpg" : image.mimeType === "image/webp" ? "webp" : "png";
+    const path = join(directory, `${prefix}${index}.${extension}`);
+    writeFileSync(path, Buffer.from(image.data, "base64"));
+    return path;
+  });
+}
+
+export function materializeToolImages(result) {
+  if (!result || !Array.isArray(result.images) || !result.images.some(image => typeof image?.data === "string")) return result;
+  const directory = mkdtempSync(join(tmpdir(), "qz-script-"));
+  return { ...result, images: imageFilePaths(result.images, directory, "") };
 }
 
 function recoveryCommand(command, sessionId, clientId, stream = false) {
@@ -96,7 +101,7 @@ async function executeCommand(parsed, dependencies) {
   return withToolClient(async callTool => {
     const returned = await dispatchCommand(parsed, { ...dependencies, callTool: dependencies.callTool || callTool });
     const clientId = parsed.presentation?.clientId;
-    return clientId && returned.result && typeof returned.result === "object" && !Array.isArray(returned.result)
+    return parsed.command !== "session" && clientId && returned.result && typeof returned.result === "object" && !Array.isArray(returned.result)
       ? { ...returned, result: { ...returned.result, clientId } } : returned;
   });
 }
@@ -105,99 +110,96 @@ async function dispatchCommand(parsed, dependencies) {
   const { command, action, id, options = {}, timeoutSeconds, waitTimeoutSeconds } = parsed;
   if (command === "help") return { text: renderHelp(parsed.helpTopic) };
   dependencies.signal?.throwIfAborted();
+  if (command === "cleanup") {
+    const result = await (dependencies.cleanupDaemons || cleanupDaemons)({ signal: dependencies.signal });
+    if (result.skipped) throw new QzError("CLEANUP_INCOMPLETE",
+      `Stopped ${result.stopped} qz services and removed ${result.removedFiles} runtime files; ${result.skipped} entries could not be cleaned.`,
+      { ...result, hint: "Check the reported entries, then retry qz cleanup." });
+    return { result };
+  }
   const open = dependencies.openBrowser || openBrowser;
   const find = dependencies.findDaemon || findDaemon;
-  const healthReader = dependencies.readHealth || readHealth;
-  if (command === "install") return { result: await open(INSTALL_URL) };
-  if (command === "stop") return { result: await (dependencies.stopDaemon || stopDaemon)() };
-  if (command === "connect") {
-    const running = await (dependencies.ensureDaemon || ensureDaemon)(options.port === undefined ? {} : { preferredPort: options.port });
-    requirePairingSupport(running.health);
-    if (options.port !== undefined && Number(new URL(running.endpoint).port) !== options.port) throw new QzError("port_mismatch",
-      `The local service is already running at ${running.endpoint}.`, { endpoint: running.endpoint,
-        hint: "Use its current address, or run qz stop before connecting on a different port." });
-    const bindingUrl = new URL("/qz-connect", running.endpoint);
-    if (options.name !== undefined) bindingUrl.searchParams.set("name", options.name);
-    const connectUrl = bindingUrl.href;
-    if (options["no-open"] || options.name !== undefined) {
-      dependencies.signal?.throwIfAborted();
-      const opened = options["no-open"] ? false : Boolean((await open(connectUrl))?.opened);
-      return { result: { endpoint: running.endpoint, url: connectUrl, mcpUrl: `${running.endpoint}/mcp`, opened } };
-    }
-    const deadline = Date.now() + timeoutSeconds * 1000;
-    let selected = selectClient(running.health, options["client-id"], { allowEmpty: true });
-    const probe = async health => {
-      const chosen = selected || selectClient(health, "", { allowEmpty: true });
-      const clients = (health?.status?.clients || []).filter(client => client.clientId === chosen);
-      for (const client of clients) {
-        dependencies.signal?.throwIfAborted();
-        const timeoutMs = Math.min(2000, deadline - Date.now());
-        if (timeoutMs <= 0) return false;
-        const timeout = AbortSignal.timeout(timeoutMs);
-        try {
-          // A lease can outlive a stopped poller. Confirm a real extension round trip.
-          await dependencies.callTool(running.endpoint, "qingzhou_call", {
-            method: "ping", clientId: client.clientId, timeoutSeconds: timeoutMs / 1000,
-          }, { timeoutMs, signal: dependencies.signal ? AbortSignal.any([dependencies.signal, timeout]) : timeout });
-          selected = client.clientId;
-          return true;
-        } catch (error) {
-          dependencies.signal?.throwIfAborted();
-          if (error.code === "connection_error" || (!timeout.aborted
-            && !["BRIDGE_NOT_CONNECTED", "BRIDGE_CLIENT_OFFLINE", "BRIDGE_CLIENT_DISCONNECTED", "BRIDGE_REQUEST_TIMEOUT", -32001].includes(error.code))) throw error;
-        }
+  if (command === "install") {
+    try { return { result: await open(INSTALL_URL) }; }
+    catch (error) {
+      if (error?.code === "BROWSER_OPEN_FAILED" && !error.hint && !error.details?.hint) {
+        error.hint = "Open the store URL manually, or configure a default browser and retry qz install.";
       }
-      return false;
-    };
-    const result = health => ({ result: { connected: true, mcpUrl: `${running.endpoint}/mcp`, clients: health.status.clients, clientId: selected } });
-    if (await probe(running.health)) return result(running.health);
-    if (options["client-id"]) throw new QzError("client_offline", "The selected browser is not responding. Reconnect it from its extension settings.");
-    dependencies.signal?.throwIfAborted();
-    await open(connectUrl);
-    while (Date.now() < deadline) {
-      dependencies.signal?.throwIfAborted();
-      const health = await healthReader(running.endpoint).catch(() => null);
-      if (health && health.instanceId !== running.instanceId) throw new QzError("connection_changed", "The local service changed. Run qz connect again.", { url: connectUrl });
-      if (health && await probe(health)) return result(health);
-      await delay(200, undefined, { signal: dependencies.signal });
+      throw error;
     }
-    throw new QzError("connection_pending", "qz is waiting for Chrome. Open the connection URL in the Chrome profile with qz installed and confirm the connection in qz. Then run qz connect again.", { url: connectUrl });
+  }
+  if (command === "connect") {
+    const running = await find({ allowIncompatible: true }) || await (dependencies.ensureDaemon || ensureDaemon)(options.port === undefined ? {} : { preferredPort: options.port });
+    if (options.port !== undefined && Number(new URL(running.endpoint).port) !== options.port) throw new QzError("PORT_MISMATCH",
+      `The local service is already running at ${running.endpoint}.`, { endpoint: running.endpoint, hint: "Use its current address." });
+    const url = connectionUri(running, options);
+    return options.json ? { result: { url } } : { text: `${url}\n` };
   }
   // Validate JSON before connecting; malformed arguments cannot cause browser actions.
+  let scriptCode = "";
+  if (command === "script") {
+    if (options.file && options.file !== "-") {
+      try { scriptCode = readFileSync(options.file, "utf8"); }
+      catch { throw new QzError("INVALID_ARGUMENTS", `Could not read ${options.file}. Use qz script --session ID [FILE|-] [--args JSON].`); }
+    } else {
+      scriptCode = await (dependencies.readStdin || stdinText)({ signal: dependencies.signal });
+    }
+    if (!String(scriptCode).trim()) throw new QzError("INVALID_ARGUMENTS", "The script is empty. Use qz script --session ID [FILE|-] [--args JSON].");
+  }
   let args = {};
   if (command === "submit" || (command === "settings" && action === "set" && id === undefined)) {
     const source = options.args === "-" ? await (dependencies.readStdin || stdinText)({ signal: dependencies.signal }) : options.args ?? "{}";
     try { args = JSON.parse(source); }
-    catch { throw new QzError("invalid_arguments", "Pass a JSON object, or - to read one from stdin."); }
-    if (!args || Array.isArray(args) || typeof args !== "object") throw new QzError("invalid_arguments", `${command === "submit" ? "Answers" : "Settings"} must be a JSON object.`);
+    catch { throw new QzError("INVALID_ARGUMENTS", "Pass a JSON object, or - to read one from stdin."); }
+    if (!args || Array.isArray(args) || typeof args !== "object") throw new QzError("INVALID_ARGUMENTS", `${command === "submit" ? "Answers" : "Settings"} must be a JSON object.`);
   }
   let config;
   if (command === "settings" && action === "set") config = settingsPatch(id, options.value, args);
   let prompt = options.prompt || "";
   if (((command === "tasks" && action === "create") || command === "send") && prompt === "-") {
     prompt = await (dependencies.readStdin || stdinText)({ signal: dependencies.signal });
-    if (!prompt.trim()) throw new QzError("invalid_arguments", "The prompt read from stdin is empty.");
+    if (!prompt.trim()) throw new QzError("INVALID_ARGUMENTS", "The prompt read from stdin is empty.");
   }
   dependencies.signal?.throwIfAborted();
   const resource = resourceRequest(parsed, config);
-  const running = await find();
+  const sessionId = command === "script" ? options.session
+    : command === "session" && ["show", "cancel"].includes(action) ? id
+      : ["send", "watch", "submit", "approve", "reject"].includes(command) || command === "tasks" && ["get", "stop"].includes(action) ? id : options.session || "";
+  const prepared = !["status", "browsers", "mcp"].includes(command)
+    ? await prepareConnection({ options, timeoutSeconds, script: command === "script", sessionId }, dependencies) : null;
+  const running = prepared?.running || (["mcp", "browsers"].includes(command) ? await (dependencies.ensureDaemon || ensureDaemon)() : await find());
   if (command === "status") return { result: running ? { running: true, endpoint: running.endpoint, updateAvailable: running.updateAvailable === true, ...(running.health.features?.browserPairing === 1 ? {} : { updateRequired: true, hint: UPGRADE_HINT }), ...running.health.status } : { running: false, connected: false } };
   if (!running) throw connectionRequired();
-  if (command === "mcp") return options.json ? { result: { url: `${running.endpoint}/mcp` } } : { text: `${running.endpoint}/mcp\n` };
+  if (command === "mcp") {
+    const url = new URL("/mcp", running.endpoint);
+    if (options.profile) url.searchParams.set("profile", options.profile);
+    return options.json ? { result: { url: url.href } } : { text: `${url.href}\n` };
+  }
   const call = dependencies.callTool;
   requirePairingSupport(running.health);
   if (command === "browsers") {
     if (action === "list") return { result: running.health.status };
     const browser = running.health.status?.browsers?.find(browser => browser.clientId === id || browser.name === id);
-    if (!browser) throw new QzError("client_not_found", `No registered browser named ${id}. Run qz browsers to inspect names and UUIDs.`);
+    if (!browser) throw new QzError("CLIENT_NOT_FOUND", `No registered browser named ${id}. Run qz browsers to inspect names and UUIDs.`);
     return { result: await call(running.endpoint, "qingzhou_forget_browser", { clientId: browser.clientId }, { timeoutMs: timeoutSeconds * 1000, signal: dependencies.signal }) };
   }
   // Resolve names once. Every subsequent operation carries this profile UUID.
-  const clientId = selectClient(running.health, options["client-id"]);
+  const clientId = prepared.clientId;
   parsed.presentation = { ...parsed.presentation, clientId };
   options["client-id"] = clientId;
   const common = { timeoutSeconds, ...(clientId ? { clientId } : {}) };
   const requestOptions = { timeoutMs: timeoutSeconds * 1000, signal: dependencies.signal };
+  if (command === "script") {
+    const budgets = scriptTimeouts({ timeoutOption: options.timeout, timeoutSeconds });
+    const request = buildScriptRequest({ code: scriptCode, timeoutSeconds: budgets.scriptSeconds, sessionId: options.session, args: options.args });
+    const result = await call(running.endpoint, "qingzhou_execute_tool", { ...request, ...common, timeoutSeconds: budgets.requestSeconds }, {
+      ...requestOptions,
+      timeoutMs: budgets.requestSeconds * 1000,
+    });
+    const output = materializeToolImages(result);
+    const shown = presentScriptResult(output);
+    return { ...shown, ...(output?.images?.length ? { stderr: output.images.map(path => `Image: ${path}\n`).join("") } : {}) };
+  }
   const startedAt = Date.now();
   const readSnapshot = async (sessionId, seconds, signal) => {
     try {
@@ -206,9 +208,9 @@ async function dispatchCommand(parsed, dependencies) {
       }, { timeoutMs: seconds * 1000, signal });
     } catch (error) {
       signal?.throwIfAborted();
-      if (error.name === "TimeoutError" || error.code === -32001 || error.code === "timeout" || error.code === "BRIDGE_REQUEST_TIMEOUT"
-        || (error.code === "tool_error" && /BRIDGE_REQUEST_TIMEOUT/.test(error.message))) {
-        throw new QzError("request_timeout", "Reading the task status timed out. The browser task may still be running.");
+      if (error.name === "TimeoutError" || error.code === -32001 || error.code === "TIMEOUT" || error.code === "BRIDGE_REQUEST_TIMEOUT"
+        || (error.code === "TOOL_ERROR" && /BRIDGE_REQUEST_TIMEOUT/.test(error.message))) {
+        throw new QzError("REQUEST_TIMEOUT", "Reading the task status timed out. The browser task may still be running.");
       }
       throw error;
     }
@@ -225,10 +227,10 @@ async function dispatchCommand(parsed, dependencies) {
         getSnapshot: ({ timeoutSeconds: seconds, signal }) => readSnapshot(sessionId, seconds, signal),
       });
     } 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"
+      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,
       { ...error.details, sessionId, ...(clientId ? { clientId } : {}), hint: changed ? "Inspect the task conversation before sending another message:" : "Continue watching the same task:",
         command: recoveryCommand(changed ? "show" : "watch", sessionId, clientId, !changed) });
@@ -241,7 +243,7 @@ async function dispatchCommand(parsed, dependencies) {
     }, requestOptions);
     if (options.wait && result?.accepted === true) {
       if (typeof result.clientMessageId !== "string" || !result.clientMessageId.trim()) {
-        throw new QzError("invalid_response", "The message was accepted without a tracking ID. Inspect the task before sending it again.", {
+        throw new QzError("INVALID_RESPONSE", "The message was accepted without a tracking ID. Inspect the task before sending it again.", {
           sessionId: id, hint: "Continue watching the same task:", command: recoveryCommand("watch", id, clientId, true),
         });
       }
@@ -257,13 +259,13 @@ async function dispatchCommand(parsed, dependencies) {
     if (!waitId || command === "approve") {
       input = await call(running.endpoint, "qingzhou_get_user_input", { ...common, sessionId: id }, requestOptions);
       if (!waitId) {
-        if (!input?.waiting || !input?.waitId) throw new QzError("not_waiting", "This task has no pending input.", { sessionId: id });
+        if (!input?.waiting || !input?.waitId) throw new QzError("NOT_WAITING", "This task has no pending input.", { sessionId: id });
         waitId = input.waitId;
       }
     }
     if (command === "approve" && input?.waiting && input.waitId === waitId && input.kind === "location_consent") {
       if (!Number.isInteger(input.consentVersion) || input.consentVersion < 1) {
-        throw new QzError("invalid_response", "The location notice has no valid consent version. Run qz show to review the current request.", { sessionId: id });
+        throw new QzError("INVALID_RESPONSE", "The location notice has no valid consent version. Run qz show to review the current request.", { sessionId: id });
       }
       consentVersion = input.consentVersion;
       await dependencies.onUserInput?.(input);
@@ -283,6 +285,13 @@ async function dispatchCommand(parsed, dependencies) {
     }
     return { result };
   }
+  if (command === "session" && action === "create") {
+    const created = await call(running.endpoint, "qingzhou_create_drive_session", { ...common, ...resource.args }, requestOptions);
+    const sessionId = String(created?.sessionId || "").trim();
+    if (!sessionId) throw new QzError("INVALID_RESPONSE", "The drive session was created without an ID. Run qz session create again.");
+    if (options.json) return { result: created };
+    return { text: `sessionId ${sessionId}\n` };
+  }
   let name, parameters;
   if (resource) {
     name = resource.name; parameters = { ...common, ...resource.args };
@@ -294,35 +303,32 @@ async function dispatchCommand(parsed, dependencies) {
   }
   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));
+    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.");
+    const sessionId = result?.session?.sessionId || result?.sessionId || result?.session?.id;
+    if (!sessionId) throw new QzError("INVALID_RESPONSE", "The task was created without an ID. Run qz tasks to find it before retrying.");
     await dependencies.onTaskCreated?.(result);
     result = { ...result, snapshot: await observe(sessionId) };
   }
   return { result };
 }
 
-export function errorPayload(error) {
-  if (error.code === "invalid_arguments") return { ok: false, error: {
-    code: error.code, message: error.message,
-    hint: "With npm, use npm run qz -- <command> [options]. Run qz --help for usage.",
-  } };
-  const interrupted = error.name === "AbortError" || error.code === "interrupted";
-  const timeout = error.name === "TimeoutError" || error.code === -32001 || error.code === "timeout";
-  const code = interrupted ? "interrupted" : timeout ? "timeout" : error.code || "connection_error";
-  const payload = { code, message: interrupted ? "Stopped waiting. A started browser task may still be running."
-    : timeout && error.code !== "timeout" ? "The request timed out. A started browser task may still be running." : error.message, ...error.details };
-  if (!payload.hint && (timeout || interrupted)) payload.hint = "Run qz tasks to inspect the task before repeating the command.";
-  if (!payload.hint && code === "BRIDGE_REQUEST_TIMEOUT") payload.hint = "The browser operation may still be running. Check the task before repeating the command.";
-  if (!payload.hint && code === "BRIDGE_CLIENT_REQUIRED") payload.hint = "Run qz status to list browser IDs, then repeat with --client ID.";
-  if (["not_connected", "connection_error", "connection_unavailable", "connection_pending", "connection_changed", "browser_open_failed", "BRIDGE_NOT_CONNECTED", "BRIDGE_CLOSED"].includes(code)) {
-    Object.assign(payload, { guide: GUIDE_URL, install: INSTALL_URL,
-      hint: payload.hint || "Run qz install if the extension is missing, then qz connect. See the GitHub guide for setup." });
+export function errorPayload(error, { script = false } = {}) {
+  const interrupted = error.name === "AbortError" || error.code === "INTERRUPTED";
+  const timeout = error.name === "TimeoutError" || error.code === -32001 || error.code === "TIMEOUT";
+  const code = String(interrupted ? "INTERRUPTED" : timeout ? "TIMEOUT" : error.code || "CONNECTION_ERROR").toUpperCase();
+  const { hint: detailHint, ...details } = error.details || {};
+  const payload = { code, message: interrupted ? script
+    ? "Script request interrupted. Its session and tabs are preserved; check the page state before continuing."
+    : "Stopped waiting. A started browser task may still be running."
+    : timeout && error.code !== "TIMEOUT" ? "The request timed out. A started browser task may still be running." : error.message,
+    ...(error.hint || detailHint ? { hint: error.hint || detailHint } : {}) };
+  if (["NOT_CONNECTED", "CONNECTION_ERROR", "CONNECTION_UNAVAILABLE", "CONNECTION_PENDING", "CONNECTION_CHANGED", "BROWSER_OPEN_FAILED", "BRIDGE_NOT_CONNECTED", "BRIDGE_CLOSED"].includes(code)) {
+    Object.assign(details, { guide: GUIDE_URL, install: INSTALL_URL });
   }
-  return { ok: false, error: payload };
+  if (Object.keys(details).length) payload.details = details;
+  return payload;
 }
 
 export async function main(argv = process.argv.slice(2), dependencies = {}) {
@@ -331,15 +337,20 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   const env = dependencies.env || process.env;
   // Preserve explicit machine output even when argument validation itself fails.
   let mode = outputMode({ json: argv.includes("--json"), plain: argv.includes("--plain"), "no-color": argv.includes("--no-color") }, stdout, env);
-  let live;
+  let live, parsed;
   try {
-    const parsed = parseCommand(argv);
+    parsed = parseCommand(argv);
     mode = outputMode(parsed.options, stdout, env);
     if (parsed.command === "help") {
       const help = renderHelp(parsed.helpTopic, mode);
       stdout.write(parsed.options.json ? `${JSON.stringify({ ok: true, result: { help } })}\n` : help);
       return 0;
     }
+    if (parsed.command === "skill") {
+      const guide = driveGuide();
+      stdout.write(parsed.options.json ? `${JSON.stringify({ ok: true, result: { guide } })}\n` : guide);
+      return 0;
+    }
     if (parsed.options.wait) live = createLiveOutput(parsed, { stdout, stderr, ...mode });
     const result = await executeCommand(parsed, { ...dependencies,
       onTaskCreated: async task => { live?.created(task); await dependencies.onTaskCreated?.(task); },
@@ -350,17 +361,21 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
       },
     });
     live?.finish();
+    if (result.stderr) stderr.write(result.stderr);
     stdout.write(result.text ?? (mode.json ? `${JSON.stringify({ ok: true, result: result.result })}\n`
       : renderResult({ ...parsed, presentation: { ...parsed.presentation, streamed: live?.streamed } }, result.result, mode)));
     const status = result.result?.snapshot?.status || result.result?.snapshot?.runtime?.status;
+    if (Number.isInteger(result.exitCode) && result.exitCode > 0) return result.exitCode;
     if (result.result?.accepted === false && !result.result?.requiresUserAction) return 1;
     return ["error", "failed", "aborted", "cancelled", "canceled", "interrupted"].includes(status) ? 1 : 0;
   } catch (error) {
     live?.finish();
-    const payload = errorPayload(error);
-    if (mode.json) stdout.write(`${JSON.stringify(payload)}\n`);
+    const scriptCommand = (parsed?.command ?? commandNameFromArgs(argv)) === "script";
+    const payload = errorPayload(error, { script: scriptCommand });
+    if (scriptCommand) stdout.write(presentScriptFailure(payload).text);
+    else if (mode.json) stdout.write(`${JSON.stringify(payload)}\n`);
     else stderr.write(renderError(payload, { ...mode, color: mode.color && Boolean(stderr.isTTY) }));
-    return payload.error.code === "invalid_arguments" ? 2 : payload.error.code === "interrupted" ? 130 : 1;
+    return payload.code === "INVALID_ARGUMENTS" ? 2 : !scriptCommand && payload.code === "INTERRUPTED" ? 130 : 1;
   }
 }
 

package/src/client.mjs

@@ -11,17 +11,17 @@ export const PROTOCOL_VERSION = 1;
 export class QzError extends Error {
   constructor(code, message, details = {}) {
     super(message);
-    this.code = code;
+    this.code = String(code || "CONNECTION_ERROR").toUpperCase();
     this.details = details;
   }
 }
 
 export function localUrl(value) {
   let url;
-  try { url = new URL(value); } catch { throw new QzError("invalid_endpoint", "The local service URL is invalid."); }
+  try { url = new URL(value); } catch { throw new QzError("INVALID_ENDPOINT", "The local service URL is invalid."); }
   if (url.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(url.hostname)
     || url.username || url.password || url.hash || url.search || url.port === "0") {
-    throw new QzError("invalid_endpoint", "Use an HTTP local service URL on 127.0.0.1 or localhost.");
+    throw new QzError("INVALID_ENDPOINT", "Use an HTTP local service URL on 127.0.0.1 or localhost.");
   }
   return url;
 }
@@ -50,7 +50,7 @@ export async function localFetch(input, init) {
       headers: { ...Object.fromEntries(prepared.headers), host: url.host } }, res => {
       if (res.statusCode >= 300 && res.statusCode < 400) {
         res.resume();
-        reject(new QzError("redirect_blocked", "The local service returned a redirect."));
+        reject(new QzError("REDIRECT_BLOCKED", "The local service returned a redirect."));
         return;
       }
       try {
@@ -65,21 +65,58 @@ export async function localFetch(input, init) {
   });
 }
 
-export async function readHealth(endpoint, { timeoutMs = 1000, fetch = localFetch } = {}) {
+export async function readHealth(endpoint, { timeoutMs = 1000, fetch = localFetch, allowIncompatible = false, signal } = {}) {
+  signal?.throwIfAborted();
   const url = localUrl(endpoint);
-  const response = await fetch(`${url.origin}/health`, { signal: AbortSignal.timeout(timeoutMs) });
-  if (!response.ok) throw new QzError("connection_unavailable", `The qz connection health check failed (${response.status}).`);
-  const health = await response.json();
-  if (health.service !== SERVICE_NAME || health.protocolVersion !== PROTOCOL_VERSION || !health.instanceId) {
-    throw new QzError("incompatible_service", "The local service is not a compatible qz installation.");
+  const timeout = AbortSignal.timeout(timeoutMs);
+  try {
+    const response = await fetch(`${url.origin}/health`, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+    if (!response.ok) throw new QzError("CONNECTION_UNAVAILABLE", `The qz connection health check failed (${response.status}).`);
+    const health = await response.json();
+    signal?.throwIfAborted();
+    if (health.service !== SERVICE_NAME || !health.instanceId || (!allowIncompatible && health.protocolVersion !== PROTOCOL_VERSION)) {
+      throw new QzError("INCOMPATIBLE_SERVICE", "The local service is not a compatible qz installation.");
+    }
+    return health;
+  } catch (error) {
+    signal?.throwIfAborted();
+    throw error;
   }
-  return health;
+}
+
+function restoreCallImages(value, blocks) {
+  const tagged = blocks.map((block, position) => ({
+    mimeType: block.mimeType,
+    data: block.data,
+    id: String(block._meta?.id || ""),
+    index: Number.isInteger(block._meta?.index) ? block._meta.index : position,
+  }));
+  const bytes = image => ({ mimeType: image.mimeType, data: image.data });
+  if (!Array.isArray(value.results)) return { ...value, images: tagged.map(bytes) };
+  const used = new Set();
+  const results = value.results.map(item => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+    const id = String(item.id || "");
+    const owned = tagged.filter(image => image.id && image.id === id);
+    for (const image of owned) used.add(image);
+    if (!owned.length) return item;
+    owned.sort((left, right) => left.index - right.index);
+    return { ...item, images: owned.map(bytes) };
+  });
+  const leftover = tagged.filter(image => !image.id || !used.has(image));
+  return { ...value, results, ...(leftover.length ? { images: leftover.map(bytes) } : {}) };
 }
 
 export function resultValue(result) {
   if (result.structuredContent != null) return result.structuredContent;
-  if (result.content?.length === 1 && result.content[0].type === "text") {
-    try { return JSON.parse(result.content[0].text); } catch { return result.content[0].text; }
+  const blocks = Array.isArray(result.content) ? result.content : [];
+  const texts = blocks.filter(block => block?.type === "text");
+  const images = blocks.filter(block => block?.type === "image" && typeof block.data === "string");
+  if (texts.length === 1 && images.length + texts.length === blocks.length) {
+    let value;
+    try { value = JSON.parse(texts[0].text); } catch { value = texts[0].text; }
+    if (images.length && value && typeof value === "object" && !Array.isArray(value)) return restoreCallImages(value, images);
+    if (!images.length) return value;
   }
   return { content: result.content || [] };
 }
@@ -88,7 +125,7 @@ function initialize(client, transport, timeoutMs, signal) {
   let timer, aborted;
   return new Promise((resolve, reject) => {
     const fail = error => {
-      const failure = new QzError("connection_error", `Could not initialize the MCP connection: ${error.message}`);
+      const failure = new QzError("CONNECTION_ERROR", `Could not initialize the MCP connection: ${error.message}`);
       if (error.name === "AbortError") failure.name = error.name;
       reject(failure);
     };
@@ -105,7 +142,7 @@ export async function withToolClient(operation) {
   const call = async (target, name, args, { timeoutMs = 180000, signal, fetch = localFetch } = {}) => {
     signal?.throwIfAborted();
     const origin = localUrl(target).origin;
-    if (endpoint && endpoint !== origin) throw new QzError("connection_changed", "The local service changed during the command.");
+    if (endpoint && endpoint !== origin) throw new QzError("CONNECTION_CHANGED", "The local service changed during the command.");
     if (!client) {
       endpoint = origin;
       client = new Client({ name: "qz-cli", version: PACKAGE_VERSION });
@@ -117,14 +154,19 @@ export async function withToolClient(operation) {
     }
     await connecting;
     signal?.throwIfAborted();
-    const result = await client.callTool({ name, arguments: args }, undefined, { timeout: timeoutMs, signal });
+    const result = await client.callTool({ name, arguments: args }, undefined, { timeout: timeoutMs, signal }).catch(error => {
+      // The MCP SDK wraps caller cancellation as RequestTimeout; retain the caller's reason.
+      signal?.throwIfAborted();
+      throw error;
+    });
     const value = resultValue(result);
     if (result.isError) {
       if (value && typeof value.code === "string" && typeof value.message === "string") {
-        throw new QzError(value.code, value.message,
-          value.details && typeof value.details === "object" && !Array.isArray(value.details) ? value.details : {});
+        throw Object.assign(new QzError(value.code, value.message,
+          value.details && typeof value.details === "object" && !Array.isArray(value.details) ? value.details : {}),
+          value.hint ? { hint: value.hint } : {});
       }
-      throw new QzError("tool_error", typeof value === "string" ? value : "The browser tool failed.", { result: value });
+      throw new QzError("TOOL_ERROR", typeof value === "string" ? value : "The browser tool failed.", { result: value });
     }
     return value;
   };