qz-browser-agent 0.1.2 → 0.1.5

package/src/task-stream.mjs

@@ -1,8 +1,9 @@
 import { setTimeout as delay } from "node:timers/promises";
 
-const STOP_STATUSES = new Set(["completed", "error", "failed", "aborted", "cancelled", "interrupted"]);
+const FAILURE_STATUSES = new Set(["error", "failed", "aborted", "cancelled", "interrupted"]);
 const ACTIVE_STATUSES = new Set(["pending", "running", "waiting_user", "paused"]);
 const INPUT_STATUSES = new Set(["waiting_user", "paused"]);
+const QUEUE_FIELDS = ["pendingFollowUps", "pendingFollowUpMessages", "pendingSteerings", "pendingSteeringMessages"];
 const record = value => value && typeof value === "object" && !Array.isArray(value) ? value : {};
 
 export const TASK_NOT_FOUND_MESSAGE = "The task was not found in the selected browser. It may have been deleted, the task ID may be incorrect, or a different browser may be selected.";
@@ -13,6 +14,11 @@ function taskStatus(snapshot) {
   return status.toLowerCase() === "canceled" ? "cancelled" : status.toLowerCase();
 }
 
+function hasPendingWork(runtime) {
+  return runtime.running === true || runtime.pendingStart === true
+    || QUEUE_FIELDS.some(key => Array.isArray(runtime[key]) && runtime[key].length > 0);
+}
+
 function assistantText(content) {
   if (typeof content === "string") return content;
   return Array.isArray(content) ? content.filter(part => part?.type === "text")
@@ -37,12 +43,13 @@ function abortable(operation, signal) {
 }
 
 /** Observe snapshots only: timeout, interruption, and polling failures never cancel or restart a browser task.
+ * Follow one Session across runs until execution and its accepted queues are finished.
  * User input pauses execution, not observation; input events expose each pending request.
  * Total observation is unlimited by default; each snapshot request has its own finite deadline.
  * getSnapshot must request compact:false and tail:false so transcript identities and streaming text survive.
  */
 export async function waitForTask({ sessionId, clientId, timeoutSeconds = null, requestTimeoutSeconds = 180, signal, getSnapshot, onUpdate,
-  pollIntervalMs = 750, expectedRunId = "", expectedMessageId = "", previousRunId = "", ignoreWaitId = "", allowIdle = false } = {}) {
+  pollIntervalMs = 750, expectedRunId = "", expectedMessageId = "", messageWasQueued = false, ignoreWaitId = "", allowIdle = false } = {}) {
   if (!String(sessionId || "").trim()) throw new TypeError("sessionId is required");
   if (typeof getSnapshot !== "function") throw new TypeError("getSnapshot is required");
   if (timeoutSeconds !== null && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) throw new TypeError("timeoutSeconds must be positive or null");
@@ -65,7 +72,7 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
     const requestDeadline = Date.now() + milliseconds;
     const requestExpiresFirst = deadline === null || requestDeadline < deadline;
     const requestTimeout = Object.assign(new Error(`Reading task ${sessionId} timed out after ${requestTimeoutSeconds} seconds. Check the browser connection, then resume watching this task.`),
-      { code: "request_timeout" });
+      { code: "REQUEST_TIMEOUT" });
     // A request timeout ends observation too. One controller preserves the first reason,
     // and equal deadlines belong to the total timer. Downstream keeps its full request budget.
     const requestTimer = requestExpiresFirst ? setTimeout(() => controller.abort(requestTimeout), milliseconds) : null;
@@ -86,12 +93,11 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
     }
   };
   const messages = new Map();
-  let selectedRunId = String(expectedRunId || "");
-  let observedRun = false;
+  let firstRunId = String(expectedRunId || "");
+  let trackingReady = false;
   let observedActivity = false;
   let awaitingMessage = Boolean(expectedMessageId);
-  let messageRunId = "";
-  let awaitingResume = Boolean(ignoreWaitId);
+  let observedQueuedMessage = messageWasQueued;
   let lastStatus = "";
   let lastInput = "";
   const emit = async update => {
@@ -121,10 +127,10 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
       const snapshot = record(await readSnapshot());
       checkActive();
       if (snapshot.sessionId && snapshot.sessionId !== sessionId) {
-        throw Object.assign(new Error("The task snapshot belongs to a different session."), { code: "task_changed" });
+        throw Object.assign(new Error("The task snapshot belongs to a different session."), { code: "TASK_CHANGED" });
       }
       if (Object.hasOwn(snapshot, "session") && snapshot.session === null) {
-        throw Object.assign(new Error(TASK_NOT_FOUND_MESSAGE), { code: "task_deleted" });
+        throw Object.assign(new Error(TASK_NOT_FOUND_MESSAGE), { code: "TASK_DELETED" });
       }
       const runtime = record(snapshot.runtime);
       const canonicalInput = Object.hasOwn(snapshot, "input") ? record(snapshot.input) : null;
@@ -132,72 +138,68 @@ export async function waitForTask({ sessionId, clientId, timeoutSeconds = null,
       const status = taskStatus(snapshot);
       if (!status) {
         throw Object.assign(new Error("The task snapshot has no status. Check the browser connection, then resume watching this task."),
-          { code: "invalid_response" });
+          { code: "INVALID_RESPONSE" });
       }
       const transcript = Array.isArray(snapshot.transcript) ? snapshot.transcript : Array.isArray(snapshot.tail) ? snapshot.tail : [];
       const submittedMessageIndex = expectedMessageId
         ? transcript.findIndex(entry => entry?.type === "user" && entry.clientMessageId === expectedMessageId) : -1;
-      if (awaitingMessage) {
-        const message = transcript[submittedMessageIndex];
-        if (message?.runId) {
-          messageRunId = String(message.runId);
-          selectedRunId = messageRunId;
-          awaitingMessage = false;
-        } else {
-          // A queued message may wait behind an earlier run's question or permission.
-          // Keep that input actionable, but never mistake its answer for this message's result.
-          if (status !== "completed") await emitStatus(status, runId, runtime);
-          await emitInput(status, runId, runtime, canonicalInput);
-          if (STOP_STATUSES.has(status) && status !== "completed") return snapshot;
-          await pollingDelay();
-          continue;
-        }
+      if (awaitingMessage && QUEUE_FIELDS.some(key => Array.isArray(runtime[key])
+        && runtime[key].some(message => message?.clientMessageId === expectedMessageId))) observedQueuedMessage = true;
+      const submittedMessage = transcript[submittedMessageIndex];
+      if (awaitingMessage && submittedMessage?.runId) {
+        firstRunId = String(submittedMessage.runId);
+        awaitingMessage = false;
       }
-      const previous = previousRunId && (!runId || runId === previousRunId);
-      const awaitedRunId = messageRunId || expectedRunId;
-      const awaitingExpected = awaitedRunId && runId !== awaitedRunId;
       const targetIndex = submittedMessageIndex >= 0 ? submittedMessageIndex
-        : awaitedRunId ? transcript.findIndex(entry => entry?.runId === awaitedRunId) : -1;
-      // A fast queued run can finish before the first poll. A later accepted user message
-      // distinguishes that replacement from an older runtime snapshot still catching up.
-      const passedTarget = awaitingExpected && runId && targetIndex >= 0
+        : firstRunId ? transcript.findIndex(entry => entry?.runId === firstRunId) : -1;
+      // The runtime can lag the transcript or skip whole runs between polls. Admit the
+      // target run or a proven successor once, then follow the Session without a run fence.
+      const passedTarget = runId && targetIndex >= 0
         && transcript.slice(targetIndex + 1).some(entry => entry?.type === "user" && entry.runId === runId);
-      if ((observedRun && runId && selectedRunId !== runId) || passedTarget) {
-        throw Object.assign(new Error("A different run replaced the task being watched. Use qz show to inspect its conversation."), {
-          code: "task_changed", details: { expectedRunId: selectedRunId || awaitedRunId, actualRunId: runId },
-        });
+      // Resolving a wait and persisting its updated snapshot are separate operations.
+      // Ignore that exact old wait even while its runtime lags the acknowledged run.
+      const oldWait = !trackingReady && ignoreWaitId && status === "waiting_user" && String(canonicalInput?.waitId || runtime.waitId || "") === ignoreWaitId;
+      if (oldWait) {
+        await pollingDelay();
+        continue;
       }
-      if (!previous && !awaitingExpected) {
-        if (runId) { selectedRunId = runId; observedRun = true; }
-        // Resolving a wait and persisting its updated snapshot are separate operations.
-        // Ignore that exact old wait until the resumed run or its next wait is visible.
-        const oldWait = awaitingResume && status === "waiting_user" && String(canonicalInput?.waitId || runtime.waitId || "") === ignoreWaitId;
-        if (oldWait) {
-          await pollingDelay();
-          continue;
-        }
-        awaitingResume = false;
-        if (ACTIVE_STATUSES.has(status)) observedActivity = true;
-        await emitStatus(status, runId, runtime);
-        for (const [index, entry] of transcript.entries()) {
-          // Steering can continue the same run. Only stream responses after this submitted message.
-          if (expectedMessageId && (submittedMessageIndex < 0 || index <= submittedMessageIndex)) continue;
-          if (entry?.type !== "assistant" || (entry.runId && selectedRunId && entry.runId !== selectedRunId)) continue;
-          const messageId = messageIdentity(entry, index, selectedRunId);
-          const fullText = assistantText(entry.content);
-          const seen = messages.has(messageId);
-          const previousText = messages.get(messageId) || "";
-          if (fullText === previousText) continue;
-          messages.set(messageId, fullText);
-          const append = fullText.startsWith(previousText);
-          await emit({ type: append ? "text" : "replace", sessionId, runId: String(entry.runId || runId), messageId,
-            text: append ? fullText.slice(previousText.length) : fullText, fullText,
-            newMessage: !seen, streaming: entry.streaming === true });
-        }
+      if (!trackingReady && (awaitingMessage || (firstRunId && runId !== firstRunId && !passedTarget))) {
+        // Queue acceptance precedes these reads; pending precedes dequeue. A settled
+        // task with no trace of an accepted queued message means it was removed.
+        const removedMessage = awaitingMessage && observedQueuedMessage && submittedMessageIndex < 0
+          && status === "completed" && !hasPendingWork(runtime);
+        // A queued message can wait behind another run's question. Keep it actionable,
+        // but do not emit its earlier answer or accept its successful completion.
+        if (status !== "completed" || removedMessage) await emitStatus(status, runId, runtime);
         await emitInput(status, runId, runtime, canonicalInput);
-        // A newly created session can report idle before its first run starts.
-        if (STOP_STATUSES.has(status) || (status === "idle" && (observedActivity || allowIdle))) return snapshot;
+        if (FAILURE_STATUSES.has(status) || removedMessage) return snapshot;
+        await pollingDelay();
+        continue;
+      }
+      trackingReady = true;
+      if (!firstRunId && runId) firstRunId = runId;
+      if (ACTIVE_STATUSES.has(status)) observedActivity = true;
+      await emitStatus(status, runId, runtime);
+      for (const [index, entry] of transcript.entries()) {
+        // Steering can continue the same run. Only stream responses after this submitted message.
+        if (expectedMessageId && (submittedMessageIndex < 0 || index <= submittedMessageIndex)) continue;
+        if (entry?.type !== "assistant") continue;
+        if (!expectedMessageId && (targetIndex >= 0 ? index < targetIndex : entry.runId && entry.runId !== runId)) continue;
+        const messageId = messageIdentity(entry, index, firstRunId);
+        const fullText = assistantText(entry.content);
+        const seen = messages.has(messageId);
+        const previousText = messages.get(messageId) || "";
+        if (fullText === previousText) continue;
+        messages.set(messageId, fullText);
+        const append = fullText.startsWith(previousText);
+        await emit({ type: append ? "text" : "replace", sessionId, runId: String(entry.runId || runId), messageId,
+          text: append ? fullText.slice(previousText.length) : fullText, fullText,
+          newMessage: !seen, streaming: entry.streaming === true });
       }
+      await emitInput(status, runId, runtime, canonicalInput);
+      // A newly created session can report idle before its first run starts.
+      if (FAILURE_STATUSES.has(status) || (!hasPendingWork(runtime)
+        && (status === "completed" || (status === "idle" && (observedActivity || allowIdle))))) return snapshot;
       await pollingDelay();
     }
   } catch (error) {

package/src/terminal.mjs

@@ -198,6 +198,29 @@ export function renderInputNotice(input, options = {}) {
   return out.finish();
 }
 
+function formatUsage(usage) {
+  if (!usage || typeof usage !== "object") return "";
+  const count = value => {
+    const number = Number(value);
+    return Number.isFinite(number) ? String(Math.max(0, Math.trunc(number))) : "0";
+  };
+  const cost = Number(usage.costUsd);
+  const text = Number.isFinite(cost) ? cost.toFixed(6).replace(/\.?0+$/u, "") : "";
+  const shown = ["inputTokens", "outputTokens", "cachedTokens", "costUsd", "modelCalls", "toolCalls", "screenshots", "contextCompressions"]
+    .some(key => Number(usage[key]) > 0);
+  if (!shown) return "";
+  return [
+    `input ${count(usage.inputTokens)}`,
+    `output ${count(usage.outputTokens)}`,
+    `cached ${count(usage.cachedTokens)}`,
+    `cost $${text || "0"}`,
+    `model calls ${count(usage.modelCalls)}`,
+    `tool calls ${count(usage.toolCalls)}`,
+    `screenshots ${count(usage.screenshots)}`,
+    `compressions ${count(usage.contextCompressions)}`,
+  ].join(", ");
+}
+
 function snapshotView(out, snapshot, { streamed = false, clientId = "" } = {}) {
   const status = taskStatus(snapshot);
   out.line(label(status), tone(status));
@@ -212,6 +235,8 @@ function snapshotView(out, snapshot, { streamed = false, clientId = "" } = {}) {
   if (response && !streamed) {
     out.line(); out.line("Latest response", "muted"); out.line(response);
   }
+  const usage = formatUsage(snapshot.usage);
+  if (usage) out.field("Usage", usage);
 }
 
 function taskList(out, sessions, client = "") {
@@ -412,13 +437,14 @@ export function renderResult(parsed, result, options = {}) {
     if (action === "list" || !action) taskList(out, result?.sessions || [], client);
     else if (action === "get") snapshotView(out, result || {}, presentation);
     else if (action === "create") {
+      const sessionId = result?.session?.sessionId || result?.sessionId || result?.session?.id;
       if (result?.snapshot) snapshotView(out, result.snapshot, presentation);
       else {
         out.line(result?.started ? "Task queued" : "Task created", "accent");
-        out.field("Task", result?.session?.id);
+        out.field("Task", sessionId);
         out.field("Title", single(result?.session?.title));
       }
-      taskCommands(out, result?.session?.id || result?.snapshot?.sessionId, { client, cancel: !result?.snapshot || ["pending", "running", "waiting_user", "waitingUser", "paused"].includes(taskStatus(result.snapshot)) });
+      taskCommands(out, sessionId || result?.snapshot?.sessionId, { client, cancel: !result?.snapshot || ["pending", "running", "waiting_user", "waitingUser", "paused"].includes(taskStatus(result.snapshot)) });
     } else if (action === "stop") {
       out.line(result?.stopped ? "Task stopped" : "Task has no active run", "accent");
       out.field("Task", result?.sessionId || parsed.id);
@@ -456,16 +482,19 @@ export function renderResult(parsed, result, options = {}) {
       out.line("Service upgrade required for browser pairing.", "waiting");
       out.line(result.hint);
     } else if (result?.updateAvailable) {
-      out.line("Service update available. Restart when your current work is finished:", "waiting");
-      out.command("qz stop && qz connect");
-    } else if (!result?.connected) out.command("qz connect");
+      out.line("Service update available. Compatible connections remain in use.", "waiting");
+    } else if (!result?.connected) out.command("qz connect uri");
+  } else if (command === "cleanup") {
+    out.line(result?.stopped || result?.removedFiles ? "Cleanup complete" : "Nothing to clean", "accent");
+    out.field("Services stopped", result?.stopped ?? 0);
+    out.field("Runtime files removed", result?.removedFiles ?? 0);
+    for (const service of result?.services || []) {
+      if (service.status === "stopped") out.field(`Stopped PID ${service.processId}`, service.endpoint || service.scopeId);
+    }
   } else if (command === "install") {
     out.line(result?.opened ? "Chrome Web Store opened" : "Install qz from the Chrome Web Store", "accent");
     if (!result?.opened) out.line(result?.url);
-    out.line("Click Add to Chrome, then connect:"); out.command("qz connect");
-  } else if (command === "stop") {
-    out.line(result?.stopped ? "Local service stopped" : "Local service is already stopped", "accent");
-    out.command("qz connect");
+    out.line("Click Add to Chrome, then create a session:"); out.command('qz session create --title "Browser task"');
   } else {
     out.line(JSON.stringify(result ?? null, null, 2));
   }
@@ -480,13 +509,18 @@ export function renderHelp(topic = "", options = {}) {
     for (const detail of details) { out.line(); out.line(detail, detail.startsWith("qz ") ? "accent" : undefined); }
   } else {
     out.line("qz · Your browser, from the terminal", "accent");
-    out.line("Run tasks with the qz browser agent, manage results, and connect via MCP.");
+    out.line("Drive your browser with sessions and scripts, or delegate a task to the built-in agent.");
     out.line();
-    for (const { help, summary: description } of Object.values(COMMANDS)) {
-      if (!help) continue;
-      const name = help[0].replace(/^qz /, "").replace(/ \[.*$/, "");
-      if (out.width >= 64) out.line(`  ${pad(name, 23)} ${description}`);
-      else { out.command(`qz ${name}`); out.line(`    ${description}`, "muted"); }
+    const entries = Object.entries(COMMANDS);
+    for (const direct of [true, false]) {
+      out.line(direct ? "Browser scripts" : "Connection, built-in agent and saved results", "accent");
+      for (const [command, { help, summary: description }] of entries) {
+        if (!help || (["session", "script"].includes(command)) !== direct) continue;
+        const name = help[0].replace(/^qz /, "").replace(/ \[.*$/, "");
+        if (out.width >= 64) out.line(`  ${pad(name, 23)} ${description}`);
+        else { out.command(`qz ${name}`); out.line(`    ${description}`, "muted"); }
+      }
+      out.line();
     }
     out.line(); out.command('qz create "Summarize this page." --stream');
     out.command('qz create "Compare these tabs." --title Research --wait');
@@ -503,15 +537,31 @@ export function renderHelp(topic = "", options = {}) {
   out.line("Version: qz --version (-v)", "muted");
   out.line("npm: npm run qz -- COMMAND [options]", "muted");
   out.shellNote();
+  if (!topic) {
+    out.line();
+    out.line("Full browser guide: qz skill", "muted");
+  }
   return out.finish();
 }
 
 export function renderError(payload, options = {}) {
   const out = output(options);
-  const error = payload?.error || payload || {};
-  const waiting = error.code === "connection_pending";
-  out.line(waiting ? "Waiting for Chrome" : "qz error", waiting ? "waiting" : "error");
+  const value = payload?.error || payload || {};
+  const error = { ...value.details, ...value };
+  const waiting = error.code === "CONNECTION_PENDING";
+  out.line(waiting ? "Waiting for browser extension" : "qz error", waiting ? "waiting" : "error");
   out.line(error.message || "The command could not be completed.");
+  if (error.code === "CLEANUP_INCOMPLETE") {
+    for (const service of error.services || []) {
+      if (service.status === "skipped") out.field(service.endpoint || service.scopeId, service.message || service.code);
+    }
+  }
+  if (waiting || error.code === "CLIENT_OFFLINE") {
+    out.field("Stage", error.stage);
+    out.field("Browser", error.selectedBrowser?.name);
+    out.field("UUID", error.selectedBrowser?.clientId);
+    if (Array.isArray(error.attemptedBrowsers)) out.field("Browsers tried", error.attemptedBrowsers.slice(0, 3).join(", ") || "None");
+  }
   if (error.url) { out.line(); out.line(error.url, "accent"); }
   if (error.hint) { out.line(); out.line(error.hint); }
   if (error.command) out.script(error.command);

package/src/tools.mjs

@@ -5,6 +5,9 @@ import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv
 import { BridgeError } from "./state.mjs";
 import { waitForTask } from "./task-stream.mjs";
 import { PACKAGE_VERSION } from "./package-info.mjs";
+import { driveGuide } from "./drive-guide.mjs";
+import { driveExtensionTimeoutSeconds } from "./drive-timeout.mjs";
+export { driveExtensionTimeoutSeconds } from "./drive-timeout.mjs";
 
 // Public MCP tools use the extension's version 1 wire protocol.
 export const TOOL_CATALOG = JSON.parse(readFileSync(new URL("./catalog.json", import.meta.url), "utf8"))
@@ -50,7 +53,7 @@ function argumentsWithDefaults(definition, input) {
   }));
 }
 
-export async function executeMcpTool(state, name, input = {}, { signal, onTaskUpdate } = {}) {
+export async function executeMcpTool(state, name, input = {}, { signal, onTaskUpdate, clientName } = {}) {
   const args = validateMcpToolInput(name, input);
   if (name === "qingzhou_bridge_status") return state.status();
   if (name === "qingzhou_forget_browser") return state.forgetBrowser(args.clientId);
@@ -62,12 +65,12 @@ export async function executeMcpTool(state, name, input = {}, { signal, onTaskUp
   const connectionSignal = state.signal(connection.controller.signal);
   const operationSignal = signal ? AbortSignal.any([connectionSignal, signal]) : connectionSignal;
   operationSignal.throwIfAborted();
-  const result = await executeBrowserTool(state, name, args, { signal: operationSignal, connectionSignal, onTaskUpdate });
+  const result = await executeBrowserTool(state, name, args, { signal: operationSignal, connectionSignal, onTaskUpdate, clientName });
   return args.clientId && (observableTools.has(name) || taskInputResults.has(name) || ["qingzhou_list_sessions", "qingzhou_get_user_input", "qingzhou_stop_session", "qingzhou_abort_session"].includes(name)) && result && typeof result === "object" && !Array.isArray(result)
     ? { ...result, clientId: args.clientId } : result;
 }
 
-async function executeBrowserTool(state, name, args, { signal, connectionSignal, onTaskUpdate }) {
+async function executeBrowserTool(state, name, args, { signal, connectionSignal, onTaskUpdate, clientName }) {
   const observe = observableTools.has(name) && (name === "qingzhou_watch_task" || args.wait || args.stream);
   const asyncTool = name === "qingzhou_execute_tool" && args.wait === false;
   const options = { timeoutSeconds: args.timeoutSeconds, clientId: args.clientId, signal };
@@ -78,7 +81,7 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
       if (remaining !== null && remaining <= 0) throw new DOMException("Stopped watching after waitTimeoutSeconds. The browser task may still be running.", "TimeoutError");
       return await waitForTask({ sessionId, clientId: args.clientId, signal, timeoutSeconds: remaining,
         requestTimeoutSeconds: args.timeoutSeconds || state.requestTimeoutSeconds || 180,
-        expectedRunId: tracking.runId, expectedMessageId: tracking.clientMessageId,
+        expectedRunId: tracking.runId, expectedMessageId: tracking.clientMessageId, messageWasQueued: tracking.disposition === "queued",
         ignoreWaitId: tracking.ignoreWaitId, allowIdle: tracking.allowIdle,
         onUpdate: onTaskUpdate && (event => args.stream || !["text", "replace"].includes(event.type) ? onTaskUpdate(event) : undefined),
         getSnapshot: async ({ signal: requestSignal, timeoutSeconds }) => bindInputClient("qingzhou_get_session_snapshot",
@@ -88,21 +91,24 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
       });
     } catch (cause) {
       const code = typeof cause.code === "string" ? cause.code
-        : cause.name === "TimeoutError" ? "timeout" : cause.name === "AbortError" ? "interrupted" : "task_wait_failed";
+        : cause.name === "TimeoutError" ? "TIMEOUT" : cause.name === "AbortError" ? "INTERRUPTED" : "TASK_WAIT_FAILED";
       const error = Object.assign(new Error(cause.message, { cause }), { code });
       error.details = { ...cause.details, sessionId, clientId: args.clientId,
-        recovery: code === "task_deleted"
+        recovery: code === "TASK_DELETED"
           ? { tool: "qingzhou_list_sessions", arguments: { clientId: args.clientId } }
-          : { tool: code === "task_changed" ? "qingzhou_get_session_snapshot" : "qingzhou_watch_task",
+          : { tool: code === "TASK_CHANGED" ? "qingzhou_get_session_snapshot" : "qingzhou_watch_task",
             arguments: { sessionId, clientId: args.clientId } } };
       throw error;
     }
   };
   if (name === "qingzhou_watch_task") return { sessionId: args.sessionId, snapshot: await watch(args.sessionId, { allowIdle: true }) };
   if (name === "qingzhou_get_tool") {
-    const listed = await state.callExtension("list_tools", { sessionId: args.sessionId, timeoutSeconds: args.timeoutSeconds }, options);
-    const tool = (Array.isArray(listed) ? listed : listed?.tools || []).find(tool => (tool.name || tool.function?.name) === args.name);
-    if (!tool) throw new BridgeError("tool_not_found", `No browser tool named ${args.name}. Use qingzhou_list_tools to list available tools.`);
+    const tool = await state.callExtension("get_tool", {
+      sessionId: args.sessionId, name: args.name, timeoutSeconds: args.timeoutSeconds,
+    }, options);
+    if (!tool || typeof tool !== "object") {
+      throw new BridgeError("TOOL_NOT_FOUND", `No browser tool named ${args.name}. Use qingzhou_list_tools to list available tools.`);
+    }
     return tool;
   }
   if (name === "qingzhou_call") return state.callExtension(args.method.trim(), args.params || {}, options);
@@ -116,11 +122,35 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
   }
   if (name === "qingzhou_follow_up") params.images ||= [];
   if (name === "qingzhou_submit_wait_form") params.answers ||= {};
+  if (name === "qingzhou_create_drive_session") {
+    const displayName = String(clientName || "").trim();
+    if (displayName) params.clientName = displayName;
+  }
   if (name === "qingzhou_execute_tool") {
+    const scriptApiVersion = params.scriptApiVersion;
+    if (scriptApiVersion != null) {
+      const capabilities = await state.callExtension("capabilities", {}, options);
+      if (capabilities?.scriptApiVersion !== scriptApiVersion) {
+        throw Object.assign(new BridgeError("UPGRADE_REQUIRED", "The connected extension does not support this script API. No script was executed."), {
+          hint: "Update the CLI and extension together, then reconnect before running the script.",
+        });
+      }
+    }
     delete params.wait;
-    params.args ||= {};
-    return asyncTool ? { ...state.startExtensionJob("execute_tool", params, { ...options, connectionSignal }), sessionId: args.sessionId, clientId }
-      : state.callExtension("execute_tool", params, options);
+    if (!Array.isArray(params.calls)) params.args ||= {};
+    const displayName = String(clientName || "").trim();
+    if (displayName) params.clientName = displayName;
+    const requestTimeout = driveExtensionTimeoutSeconds(params, args.timeoutSeconds || state.requestTimeoutSeconds || 180);
+    const callOptions = { ...options, timeoutSeconds: requestTimeout, cancelOnAbort: !asyncTool };
+    const invoke = () => asyncTool
+      ? { ...state.startExtensionJob("execute_tool", params, { ...callOptions, connectionSignal }), sessionId: args.sessionId, clientId }
+      : state.callExtension("execute_tool", params, callOptions);
+    try {
+      return await invoke();
+    } catch (error) {
+      if (error?.code === "DRIVE_SESSION_BUSY") return await invoke();
+      throw error;
+    }
   }
   const method = name === "qingzhou_abort_session" ? "stop_session" : name.slice("qingzhou_".length);
   let result = await state.callExtension(method, params, options);
@@ -133,16 +163,19 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
   }
   result = bindInputClient(name, result, clientId);
   if (observe) {
-    const sessionId = name === "qingzhou_create_session" ? result?.session?.id || result?.sessionId : args.sessionId;
+    const sessionId = name === "qingzhou_create_session"
+      ? result?.session?.sessionId || result?.sessionId || result?.session?.id : args.sessionId;
     if (name === "qingzhou_create_session") {
-      if (!sessionId) throw new BridgeError("invalid_response", "The task was created without an ID. Use qingzhou_list_sessions to find it before retrying.");
+      if (!sessionId) throw new BridgeError("INVALID_RESPONSE", "The task was created without an ID. Use qingzhou_list_sessions to find it before retrying.");
       await onTaskUpdate?.({ type: "created", sessionId, clientId, ...result });
       result = { ...result, snapshot: await watch(sessionId, { allowIdle: !args.firstMessage.trim() }) };
     } else if (name === "qingzhou_send_message" && result?.accepted === true) {
       if (typeof result.clientMessageId !== "string" || !result.clientMessageId.trim()) {
-        throw new BridgeError("invalid_response", "The message was accepted without a tracking ID. Inspect the task before sending it again.");
+        throw Object.assign(new BridgeError("INVALID_RESPONSE", "The message was accepted without a tracking ID. Continue watching the same task before sending it again."), {
+          details: { sessionId, clientId, recovery: { tool: "qingzhou_watch_task", arguments: { sessionId, clientId } } },
+        });
       }
-      result = { ...result, snapshot: await watch(sessionId, { clientMessageId: result.clientMessageId }) };
+      result = { ...result, snapshot: await watch(sessionId, { clientMessageId: result.clientMessageId, disposition: result.disposition }) };
     } else if (name === "qingzhou_respond_to_user_input" && (result?.accepted === true || result?.requiresUserAction)) {
       const snapshot = await watch(sessionId, { runId: result.runId || "", ignoreWaitId: result.requiresUserAction ? "" : args.waitId });
       result = result.requiresUserAction ? { sessionId, waitId: args.waitId, snapshot } : { ...result, snapshot };
@@ -154,44 +187,131 @@ async function executeBrowserTool(state, name, args, { signal, connectionSignal,
 /** Validate input against the advertised tool schema and apply its defaults. */
 export function validateMcpToolInput(name, input = {}) {
   const definition = definitions.get(name);
-  if (!definition) throw Object.assign(new Error(`Unknown tool: ${name}. Read the MCP tool list for available names.`), { code: "invalid_arguments" });
+  if (!definition) throw Object.assign(new Error(`Unknown tool: ${name}. Read the MCP tool list for available names.`), { code: "INVALID_ARGUMENTS" });
   try {
     return argumentsWithDefaults(definition, input);
   } catch (error) {
-    error.code = "invalid_arguments";
+    error.code = "INVALID_ARGUMENTS";
     throw error;
   }
 }
 
-export function resultToContent(result) {
+function imageEntries(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || !Array.isArray(value.images)) return [];
+  return value.images.filter(image => image && typeof image.data === "string" && typeof image.mimeType === "string");
+}
+
+function withoutImages(value) {
+  if (!imageEntries(value).length) return value;
+  const { images: _images, ...rest } = value;
+  return rest;
+}
+
+function imageBlock(image, meta) {
+  return {
+    type: "image",
+    data: image.data,
+    mimeType: image.mimeType,
+    ...(meta && Object.keys(meta).length ? { _meta: meta } : {}),
+  };
+}
+
+function peelCallImages(value, callId, sink) {
+  const images = imageEntries(value);
+  if (!images.length) return value;
+  const placeholders = images.map((image, offset) => {
+    const meta = { ...(callId ? { id: callId } : {}), index: offset };
+    sink.push(imageBlock(image, meta));
+    return meta;
+  });
+  return { ...withoutImages(value), images: placeholders };
+}
+
+export function resultToContent(result, { toolResult = false } = {}) {
   if (result == null) return [];
-  if (Array.isArray(result)) return result.flatMap(resultToContent);
-  return [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }];
+  if (Array.isArray(result)) return result.flatMap(item => resultToContent(item));
+  if (typeof result !== "object") return [{ type: "text", text: String(result) }];
+  const nested = [];
+  let body = result;
+  if (toolResult && Array.isArray(result.results)) {
+    body = {
+      ...result,
+      results: result.results.map(item => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+        const callId = String(item.id || "");
+        return peelCallImages(item, callId, nested);
+      }),
+    };
+  }
+  const top = toolResult ? imageEntries(body) : [];
+  if (!top.length && !nested.length) {
+    return [{ type: "text", text: JSON.stringify(body) }];
+  }
+  return [
+    { type: "text", text: JSON.stringify(top.length ? withoutImages(body) : body) },
+    ...top.map(image => imageBlock(image)),
+    ...nested,
+  ];
+}
+
+const DRIVE_TOOL_NAMES = ["qingzhou_guide", "qingzhou_create_drive_session", "qingzhou_list_drive_sessions", "qingzhou_get_drive_session", "qingzhou_stop_session", "qingzhou_execute_tool", "qingzhou_list_tools", "qingzhou_get_tool", "qingzhou_bridge_status"];
+const GUIDE_TOOL = {
+  name: "qingzhou_guide",
+  description: "Return the qz CLI direct-drive guide as an optional reference.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {},
+  },
+};
+const DRIVE_INSTRUCTIONS = "先用 qingzhou_create_drive_session 或 qz session create --title TITLE 创建带可读标题的会话，后续每次执行工具或脚本都传入该 sessionId（CLI 必传 --session，缺失退出码为 2，不会自动建会话）；list_tools/get_tool 查询基础目录无需会话。页面工具必传 tabRef（open_tab 设置的可选 tabAlias，或 open_tab / list_tabs 返回的 tabRef）。通过 qingzhou_execute_tool（单工具、calls 批次或 run_script 外层编排）执行操作，页面内 DOM 求值使用 evaluate。Create a session with a readable title using qingzhou_create_drive_session or qz session create --title TITLE, then pass that sessionId on every tool or script execution (CLI calls require --session; omitting it exits 2 and does not create a session). list_tools/get_tool can inspect the base catalog without a session. Page tools require tabRef (an optional tabAlias from open_tab, or the tabRef returned by open_tab or list_tabs). Orchestrate with qingzhou_execute_tool (single tool, calls batch, or outer run_script) and use evaluate for in-page DOM execution.";
+
+export function mcpCatalogProfile({ clientName = "", profile = "" } = {}) {
+  const explicit = String(profile || "").trim().toLowerCase();
+  if (explicit === "full" || explicit === "drive") return explicit;
+  return clientName === "qz-cli" ? "full" : "drive";
+}
+
+export function driveToolCatalog() {
+  const byName = new Map(TOOL_CATALOG.map(tool => [tool.name, tool]));
+  return DRIVE_TOOL_NAMES.map(name => name === "qingzhou_guide" ? GUIDE_TOOL : byName.get(name));
 }
 
-export function createMcpServer(state) {
+export function createMcpServer(state, { clientName = "", profile = "" } = {}) {
+  const catalogProfile = mcpCatalogProfile({ clientName, profile });
   const server = new Server({ name: "qz-browser-agent-mcp-bridge", version: PACKAGE_VERSION }, {
-    capabilities: { tools: {} }, instructions: "Control qz tasks and browser tools through the local bridge.",
+    capabilities: { tools: {} },
+    instructions: catalogProfile === "drive" ? DRIVE_INSTRUCTIONS : "Control qz tasks and browser tools through the local bridge.",
   });
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_CATALOG }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: catalogProfile === "drive" ? driveToolCatalog() : TOOL_CATALOG,
+  }));
   server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     try {
       let progress = 0;
       const progressToken = request.params._meta?.progressToken;
-      const result = await executeMcpTool(state, request.params.name, request.params.arguments || {}, { signal: extra.signal,
+      const input = { ...(request.params.arguments || {}) };
+      if (request.params.name === "qingzhou_guide") {
+        return { content: [{ type: "text", text: driveGuide() }] };
+      }
+      if (catalogProfile === "drive" && request.params.name === "qingzhou_list_sessions") {
+        if (!String(input.scope || "").trim()) input.scope = "session";
+      }
+      if (request.params.name === "qingzhou_execute_tool" && !String(input.sessionId || "").trim()) {
+        throw new BridgeError("DRIVE_SESSION_REQUIRED", "Pass sessionId from qz session create (MCP: qingzhou_create_drive_session). CLI calls require --session. This call does not create a session.");
+      }
+      const result = await executeMcpTool(state, request.params.name, input, { signal: extra.signal, clientName,
         onTaskUpdate: progressToken === undefined ? undefined : event => extra.sendNotification({
           method: "notifications/progress", params: { progressToken, progress: ++progress,
             message: ["text", "replace"].includes(event.type) ? event.text : JSON.stringify(event),
             _meta: { "qz/task-event": event } },
         }).catch(() => {}),
       });
-      return { content: resultToContent(result) };
+      return { content: resultToContent(result, { toolResult: request.params.name === "qingzhou_execute_tool" }) };
     } catch (error) {
-      const message = error.message || String(error);
-      const value = typeof error.code === "string" && error.code ? {
-        code: error.code, message,
-        ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}),
-      } : message;
+      const value = { code: String(error.code || "TOOL_EXECUTION_FAILED").toUpperCase(), message: error.message || String(error),
+        ...(error.hint ? { hint: error.hint } : {}),
+        ...(error.details && Object.keys(error.details).length ? { details: error.details } : {}) };
       return { isError: true, content: resultToContent(value) };
     }
   });