@mearl/plugin-qoder 3.0.0-beta.8 → 3.0.0

package/README.en.md

@@ -0,0 +1,27 @@
+# @mearl/plugin-qoder
+
+[简体中文](README.md) | [English](README.en.md)
+
+Optional Qoder integration: local CLI/ACP agents and a Cloud Session API/SSE connector. The core does not depend on this package, register Qoder by default, read PATs, or launch the CLI. This is distributed as an independent npm package.
+
+To use the local Agent, select Qoder in Agent Chat and install the missing components there. A Qoder capability in the selected preset takes precedence. Use a preset to enable cloud pairing.
+
+The built `dist/capability/` contains self-contained Node modules, a digest manifest, and `preset.json`. Use the existing installation flow:
+
+```bash
+npx @mearl/setup preset apply ./node_modules/@mearl/plugin-qoder/dist/capability/preset.json
+```
+
+If you already use other capabilities, merge the `qoder` package declaration into your existing preset: `preset apply` selects the entire preset. `npm install` alone does not grant permissions or activate capabilities. Package resources can also be distributed over trusted HTTPS URLs.
+
+After installation, local agents are discovered through `agent.provider.qoder`. Uninstalling blocks new sessions while accepted sessions can continue and close. If sessions exist during an update, the new runtime activates only after they close.
+
+Generate a one-time Cloud pairing URL on the agent machine:
+
+```bash
+npx @mearl/plugin-qoder pair
+```
+
+Follow the output to start `mearl-cloud-connector` on the browser machine, then immediately call Qoder's custom `mearl` tool to complete pairing. The browser machine must have this capability installed and supply `QODER_PERSONAL_ACCESS_TOKEN`. Credentials resolve in this order: process environment, `MEARL_ENV_FILE`, `~/.mearl/.env`, and macOS Keychain `ai.mearl.qoder.pat`. Credentials are never written to pairing URLs, registration records, or logs.
+
+After installing the capability, you can also use `npx @mearl/setup --cloud-mode qoder --yes` with the cloud-server management commands. This package supplies both `cloud.connector.qoder` and `cloud.server.qoder`; missing installations report the missing capability explicitly. ACP permission events use the standard `acp/requestPermission` contract.

package/README.md

@@ -1,5 +1,7 @@
 # @mearl/plugin-qoder
 
+[简体中文](README.md) | [English](README.en.md)
+
 可选的 Qoder 接入：本地 CLI/ACP Agent 与 Cloud Session API/SSE 连接器。核心不依赖本包，也不默认注册 Qoder、读取 PAT 或启动 CLI。本包作为独立 npm 包分发。
 
 构建后的 `dist/capability/` 包含自包含 Node 模块、摘要清单与 `preset.json`。使用现有安装流程：
@@ -10,6 +12,8 @@ npx @mearl/setup preset apply ./node_modules/@mearl/plugin-qoder/dist/capability
 
 若已有其他能力，请将这里的 `qoder` 包声明合并进现有 preset；`preset apply` 选择的是整套预设。仅 `npm install` 不会自动获得权限或激活能力。包资源同样可通过受信任 HTTPS 地址分发。
 
+使用本地 Agent 时，可在 Agent 对话中选择 Qoder 并安装缺失组件。当前预设提供的 Qoder 能力优先，云端配对通过预设启用。
+
 本地 Agent 在安装后通过 `agent.provider.qoder` 被发现。卸载后禁止新会话；已接受会话仍可继续和关闭。更新期间有会话时，关闭会话后才启用新运行时。
 
 Cloud 配对在 Agent 机器生成一次性地址：

package/dist/agent.d.ts

@@ -1,19 +1,11 @@
 import type { AgentInstalledSkill } from '@mearl/browser-core/agentSkills';
-import fs from 'node:fs';
 import type * as acp from '@agentclientprotocol/sdk';
 import type { AgentChatImageInput, AgentChatModelInfo, AgentChatProviderDescriptor } from '@mearl/browser-core/agentChat';
 import type { AgentProvider, AgentProviderEvent, AgentProviderListSessionsOptions, AgentProviderListSessionsResult, AgentProviderResumeResult, AgentProviderSessionOptions } from '@mearl/agent-runtime';
+export { qoderExecutableCandidatePaths } from '@mearl/agent-runtime/execution';
 export declare function qoderModelInfo(configOptions: acp.SessionConfigOption[] | null | undefined): AgentChatModelInfo | undefined;
 export declare function parseQoderSkillsList(output: string, cwd: string, home?: string): AgentInstalledSkill[];
 export declare function qoderInstallCommand(platform?: NodeJS.Platform): string;
-interface QoderExecutableCandidateOptions {
-    env?: NodeJS.ProcessEnv;
-    homedir?: () => string;
-    platform?: NodeJS.Platform;
-    processExecPath?: string;
-    readdirSync?: typeof fs.readdirSync;
-}
-export declare function qoderExecutableCandidatePaths(options?: QoderExecutableCandidateOptions): string[];
 export declare class QoderAgentProvider implements AgentProvider {
     private readonly log;
     private readonly clientVersion;
@@ -65,4 +57,3 @@ export declare class QoderAgentProvider implements AgentProvider {
     private resolveExecutableCandidates;
     private emit;
 }
-export {};

package/dist/agent.js

@@ -1,10 +1,10 @@
-import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { Readable, Writable } from 'node:stream';
-import { agentExecutableCandidatePaths, AgentExecutableResolver, executableFileCandidates, probeAgentExecutable, } from '@mearl/agent-runtime/execution';
+import { AgentExecutableResolver, executableFileCandidates, probeAgentExecutable, qoderExecutableCandidatePaths, } from '@mearl/agent-runtime/execution';
 import { agentSpawnCommand, createAgentChildEnv } from '@mearl/agent-runtime/execution';
+export { qoderExecutableCandidatePaths } from '@mearl/agent-runtime/execution';
 const PROBE_TIMEOUT_MS = 5_000;
 const REQUEST_TIMEOUT_MS = 30_000;
 const MAX_MODEL_CHARS = 256;
@@ -78,18 +78,6 @@ export function parseQoderSkillsList(output, cwd, home = os.homedir()) {
     finish();
     return skills;
 }
-function qoderManagedExecutableCandidates(home, readdirSync = fs.readdirSync) {
-    const directory = path.join(home, '.qoder', 'bin', 'qodercli');
-    try {
-        return readdirSync(directory, { withFileTypes: true })
-            .filter(entry => entry.isFile() && entry.name.startsWith('qodercli-'))
-            .sort((left, right) => right.name.localeCompare(left.name, undefined, { numeric: true }))
-            .map(entry => path.join(directory, entry.name));
-    }
-    catch {
-        return [];
-    }
-}
 function isPermissionResponse(value) {
     if (!value || typeof value !== 'object')
         return false;
@@ -105,25 +93,6 @@ export function qoderInstallCommand(platform = process.platform) {
         ? 'npm install -g @qoder-ai/qodercli'
         : 'curl -fsSL https://qoder.com/install | bash';
 }
-export function qoderExecutableCandidatePaths(options = {}) {
-    const env = options.env ?? process.env;
-    const home = (options.homedir ?? os.homedir)();
-    const platform = options.platform ?? process.platform;
-    const executableNames = platform === 'win32' ? ['qodercli.exe', 'qodercli.cmd'] : ['qodercli'];
-    return agentExecutableCandidatePaths({
-        executableNames,
-        configuredPath: env.MEARL_QODER_PATH,
-        env,
-        extraUserCandidates: [
-            ...qoderManagedExecutableCandidates(home, options.readdirSync),
-            ...executableNames.map(name => path.join(home, '.qoder', 'bin', name)),
-        ],
-        home,
-        platform,
-        processExecPath: options.processExecPath,
-        readdirSync: options.readdirSync,
-    });
-}
 function sessionOptions(options) {
     const cwd = path.resolve(options.cwd || os.homedir());
     return {

package/dist/capability/bundle.json

@@ -7,8 +7,8 @@
   },
   "resources": {
     "runtime.cjs": {
-      "sha256": "eaad2563840828ecfc0e8a2cda9ead4b3c58cc480d8001074b0622b0b8d33b0d",
-      "byteLength": 1103773
+      "sha256": "1a603acc3c2e3f00922cb20f2b29cfe0a05a9a2a5d7f9388809e7a6cb52f6a14",
+      "byteLength": 1103931
     }
   },
   "contributions": {

package/dist/capability/runtime.cjs

@@ -302,10 +302,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path4) {
-  if (!path4)
+function getElementAtPath(obj, path5) {
+  if (!path5)
     return obj;
-  return path4.reduce((acc, key) => acc?.[key], obj);
+  return path5.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -564,11 +564,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path4, issues) {
+function prefixIssues(path5, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path4);
+    iss.path.unshift(path5);
     return iss;
   });
 }
@@ -1101,16 +1101,16 @@ function flattenError(error62, mapper = (issue2) => issue2.message) {
 }
 function formatError(error62, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error63, path4 = []) => {
+  const processError = (error63, path5 = []) => {
     for (const issue2 of error63.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path4, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path5, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path5, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path5, ...issue2.path]);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path5, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -1149,17 +1149,17 @@ function formatError(error62, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error62, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error63, path4 = []) => {
+  const processError = (error63, path5 = []) => {
     var _a3;
     for (const issue2 of error63.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path4, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path5, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path5, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path5, ...issue2.path]);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path5, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -1198,8 +1198,8 @@ function treeifyError(error62, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path4 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path4) {
+  const path5 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path5) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -19231,13 +19231,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path4 = ref.slice(1).split("/").filter(Boolean);
-  if (path4.length === 0) {
+  const path5 = ref.slice(1).split("/").filter(Boolean);
+  if (path5.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path4[0] === defsKey) {
-    const key = path4[1] === void 0 ? void 0 : decodeJSONPointerSegment(path4[1]);
+  if (path5[0] === defsKey) {
+    const key = path5[1] === void 0 ? void 0 : decodeJSONPointerSegment(path5[1]);
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -25031,9 +25031,8 @@ __export(runtime_exports, {
 module.exports = __toCommonJS(runtime_exports);
 
 // src/agent.ts
-var import_node_fs3 = __toESM(require("node:fs"), 1);
-var import_node_os2 = __toESM(require("node:os"), 1);
-var import_node_path4 = __toESM(require("node:path"), 1);
+var import_node_os3 = __toESM(require("node:os"), 1);
+var import_node_path5 = __toESM(require("node:path"), 1);
 var import_node_child_process2 = require("node:child_process");
 var import_node_stream = require("node:stream");
 
@@ -25292,6 +25291,38 @@ function isExecutableFile(candidate) {
   }
 }
 
+// ../agent-runtime/dist/qoder-executable.js
+var import_node_fs3 = __toESM(require("node:fs"), 1);
+var import_node_os2 = __toESM(require("node:os"), 1);
+var import_node_path4 = __toESM(require("node:path"), 1);
+function qoderManagedExecutableCandidates(home, readdirSync = import_node_fs3.default.readdirSync) {
+  const directory = import_node_path4.default.join(home, ".qoder", "bin", "qodercli");
+  try {
+    return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.startsWith("qodercli-")).sort((left, right) => right.name.localeCompare(left.name, void 0, { numeric: true })).map((entry) => import_node_path4.default.join(directory, entry.name));
+  } catch {
+    return [];
+  }
+}
+function qoderExecutableCandidatePaths(options = {}) {
+  const env = options.env ?? process.env;
+  const home = (options.homedir ?? import_node_os2.default.homedir)();
+  const platform = options.platform ?? process.platform;
+  const executableNames = platform === "win32" ? ["qodercli.exe", "qodercli.cmd"] : ["qodercli"];
+  return agentExecutableCandidatePaths({
+    executableNames,
+    configuredPath: env.MEARL_QODER_PATH,
+    env,
+    extraUserCandidates: [
+      ...qoderManagedExecutableCandidates(home, options.readdirSync),
+      ...executableNames.map((name) => import_node_path4.default.join(home, ".qoder", "bin", name))
+    ],
+    home,
+    platform,
+    processExecPath: options.processExecPath,
+    readdirSync: options.readdirSync
+  });
+}
+
 // src/agent.ts
 var PROBE_TIMEOUT_MS = 5e3;
 var REQUEST_TIMEOUT_MS = 3e4;
@@ -25325,14 +25356,14 @@ function qoderModelInfo(configOptions) {
     ...displayName && displayName !== id ? { displayName } : {}
   };
 }
-function parseQoderSkillsList(output2, cwd, home = import_node_os2.default.homedir()) {
+function parseQoderSkillsList(output2, cwd, home = import_node_os3.default.homedir()) {
   const skills = [];
   let current;
   const finish = () => {
     if (!current) return;
     const skillPath = current.path || (current.builtIn ? "bundled" : "");
-    const relativeToCwd = skillPath && import_node_path4.default.isAbsolute(skillPath) ? import_node_path4.default.relative(cwd, skillPath) : "";
-    const inProject = Boolean(relativeToCwd) && relativeToCwd !== ".." && !relativeToCwd.startsWith(`..${import_node_path4.default.sep}`) && !import_node_path4.default.isAbsolute(relativeToCwd);
+    const relativeToCwd = skillPath && import_node_path5.default.isAbsolute(skillPath) ? import_node_path5.default.relative(cwd, skillPath) : "";
+    const inProject = Boolean(relativeToCwd) && relativeToCwd !== ".." && !relativeToCwd.startsWith(`..${import_node_path5.default.sep}`) && !import_node_path5.default.isAbsolute(relativeToCwd);
     skills.push({
       name: current.name,
       path: skillPath,
@@ -25357,14 +25388,6 @@ function parseQoderSkillsList(output2, cwd, home = import_node_os2.default.homed
   finish();
   return skills;
 }
-function qoderManagedExecutableCandidates(home, readdirSync = import_node_fs3.default.readdirSync) {
-  const directory = import_node_path4.default.join(home, ".qoder", "bin", "qodercli");
-  try {
-    return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.startsWith("qodercli-")).sort((left, right) => right.name.localeCompare(left.name, void 0, { numeric: true })).map((entry) => import_node_path4.default.join(directory, entry.name));
-  } catch {
-    return [];
-  }
-}
 function isPermissionResponse(value) {
   if (!value || typeof value !== "object") return false;
   const outcome = value.outcome;
@@ -25375,27 +25398,8 @@ function isPermissionResponse(value) {
 function qoderInstallCommand(platform = process.platform) {
   return platform === "win32" ? "npm install -g @qoder-ai/qodercli" : "curl -fsSL https://qoder.com/install | bash";
 }
-function qoderExecutableCandidatePaths(options = {}) {
-  const env = options.env ?? process.env;
-  const home = (options.homedir ?? import_node_os2.default.homedir)();
-  const platform = options.platform ?? process.platform;
-  const executableNames = platform === "win32" ? ["qodercli.exe", "qodercli.cmd"] : ["qodercli"];
-  return agentExecutableCandidatePaths({
-    executableNames,
-    configuredPath: env.MEARL_QODER_PATH,
-    env,
-    extraUserCandidates: [
-      ...qoderManagedExecutableCandidates(home, options.readdirSync),
-      ...executableNames.map((name) => import_node_path4.default.join(home, ".qoder", "bin", name))
-    ],
-    home,
-    platform,
-    processExecPath: options.processExecPath,
-    readdirSync: options.readdirSync
-  });
-}
 function sessionOptions(options) {
-  const cwd = import_node_path4.default.resolve(options.cwd || import_node_os2.default.homedir());
+  const cwd = import_node_path5.default.resolve(options.cwd || import_node_os3.default.homedir());
   return {
     ...options,
     cwd,
@@ -25620,7 +25624,7 @@ var QoderAgentProvider = class {
       throw new Error(resolution.error);
     }
     const { executable } = resolution;
-    const resolvedCwd = cwd || import_node_os2.default.homedir();
+    const resolvedCwd = cwd || import_node_os3.default.homedir();
     const output2 = await this.runSkillsList(executable, resolvedCwd);
     return parseQoderSkillsList(output2, resolvedCwd);
   }
@@ -26360,27 +26364,27 @@ function scrollElementInPage(direction, distance, targetLabel, containerPolicy =
       } catch {
       }
     }
-    const path4 = [];
+    const path5 = [];
     let cursor = candidate;
-    while (cursor && cursor.nodeType === 1 && path4.length < 8) {
+    while (cursor && cursor.nodeType === 1 && path5.length < 8) {
       const tag = String(cursor.tagName || "").toLowerCase();
       if (!tag)
         break;
       const parent = cursor.parentElement;
       if (!parent) {
-        path4.unshift(tag);
+        path5.unshift(tag);
         break;
       }
       const siblings = Array.from(parent.children).filter((sibling) => sibling.tagName === cursor.tagName);
       const index = siblings.indexOf(cursor) + 1;
-      path4.unshift(siblings.length > 1 ? tag + ":nth-of-type(" + index + ")" : tag);
+      path5.unshift(siblings.length > 1 ? tag + ":nth-of-type(" + index + ")" : tag);
       cursor = parent;
       if (cursor === documentRef.documentElement) {
-        path4.unshift("html");
+        path5.unshift("html");
         break;
       }
     }
-    return path4.join(" > ");
+    return path5.join(" > ");
   }
   let metrics = scrollMetrics(element);
   if (!metrics)
@@ -26550,27 +26554,27 @@ function inspectElementsInPage(selector, filter, styles, maxResults, invalidSele
       } catch {
       }
     }
-    const path4 = [];
+    const path5 = [];
     let cursor = element;
-    while (cursor && cursor.nodeType === 1 && path4.length < 8) {
+    while (cursor && cursor.nodeType === 1 && path5.length < 8) {
       const tag = String(cursor.tagName || "").toLowerCase();
       if (!tag)
         break;
       const parent = cursor.parentElement;
       if (!parent) {
-        path4.unshift(tag);
+        path5.unshift(tag);
         break;
       }
       const siblings = Array.from(parent.children).filter((sibling) => sibling.tagName === cursor.tagName);
       const index = siblings.indexOf(cursor) + 1;
-      path4.unshift(siblings.length > 1 ? tag + ":nth-of-type(" + index + ")" : tag);
+      path5.unshift(siblings.length > 1 ? tag + ":nth-of-type(" + index + ")" : tag);
       cursor = parent;
       if (cursor === documentRef.documentElement) {
-        path4.unshift("html");
+        path5.unshift("html");
         break;
       }
     }
-    return path4.join(" > ");
+    return path5.join(" > ");
   }
   function readStyle(style, property) {
     const cssValue = style.getPropertyValue?.(property);
@@ -26999,8 +27003,8 @@ function resolveActionTimeoutSec(action, data, fallback = 15) {
 
 // src/auth.ts
 var import_node_fs4 = require("node:fs");
-var import_node_os3 = require("node:os");
-var import_node_path5 = require("node:path");
+var import_node_os4 = require("node:os");
+var import_node_path6 = require("node:path");
 var import_node_child_process3 = require("node:child_process");
 var QODER_TOKEN_KEY = "QODER_PERSONAL_ACCESS_TOKEN";
 var QODER_KEYCHAIN_SERVICE = "ai.mearl.qoder.pat";
@@ -27040,7 +27044,7 @@ function readMacKeychainToken() {
   const securityPath = "/usr/bin/security";
   if (!(0, import_node_fs4.existsSync)(securityPath)) return void 0;
   try {
-    const account = (0, import_node_os3.userInfo)().username;
+    const account = (0, import_node_os4.userInfo)().username;
     const result = (0, import_node_child_process3.spawnSync)(
       securityPath,
       ["find-generic-password", "-a", account, "-s", QODER_KEYCHAIN_SERVICE, "-w"],
@@ -27062,10 +27066,10 @@ function resolveQoderPersonalAccessToken(options = {}) {
   const env = options.env ?? process.env;
   const inherited = normalizeToken(env[QODER_TOKEN_KEY]);
   if (inherited) return inherited;
-  const homeDirectory = options.homeDirectory ?? (0, import_node_os3.homedir)();
+  const homeDirectory = options.homeDirectory ?? (0, import_node_os4.homedir)();
   const envFiles = [
-    ...env.MEARL_ENV_FILE?.trim() ? [(0, import_node_path5.resolve)(env.MEARL_ENV_FILE)] : [],
-    (0, import_node_path5.resolve)(homeDirectory, ".mearl", ".env")
+    ...env.MEARL_ENV_FILE?.trim() ? [(0, import_node_path6.resolve)(env.MEARL_ENV_FILE)] : [],
+    (0, import_node_path6.resolve)(homeDirectory, ".mearl", ".env")
   ];
   const readFile = options.readFile ?? ((file2) => (0, import_node_fs4.readFileSync)(file2, "utf8"));
   for (const file2 of new Set(envFiles)) {
@@ -27208,8 +27212,8 @@ var QoderApiClient = class {
   token;
   fetchImpl;
   baseUrl;
-  async request(path4, init = {}) {
-    const response = await this.fetchImpl(`${this.baseUrl}${path4}`, {
+  async request(path5, init = {}) {
+    const response = await this.fetchImpl(`${this.baseUrl}${path5}`, {
       ...init,
       headers: {
         Authorization: `Bearer ${this.token}`,

package/docs/cloud-pairing.en.md

@@ -0,0 +1,52 @@
+# Qoder Cloud Agent pairing
+
+[简体中文](cloud-pairing.md) | [English](cloud-pairing.en.md)
+
+Use this mode when running in Qoder Cloud Agent. Other remote agents use cloud-server / WebSocket. Install the Qoder capability on the browser machine as described in this package's README. The Agent machine can generate pairing information directly with this package. Both modes share Mearl action contracts.
+
+Qoder mode uses official Client-Side custom tools and Session event APIs, without Cloudflare Tunnel or treating Qoder sandbox public endpoints as WebSockets. Follow this sequence:
+
+1. Check whether the Agent already exposes a Client-Side custom tool named `mearl`. If so, run:
+
+   ```bash
+   npx @mearl/plugin-qoder pair
+   ```
+
+   Read the local `npx @mearl/cloud-connector start "qoder://pair/..."` command and `pair` input from output. Show the local command to the user, then immediately submit the generated `pair` input to the `mearl` custom tool. It pauses until the user runs the connection command on the browser machine and pairing completes.
+
+2. After pairing, do not run `mearl ...` shell commands inside the Qoder sandbox for this Session's browser operations. Internally map the Skill's action, payload, browser, and timeout to custom-tool calls. Deliver ordinary Mearl results to users without exposing transport differences.
+
+3. Without a `mearl` tool, first determine whether available Qoder PAT and Agent ID/version permit reading the complete existing `tools` array, appending the configuration below, and updating the Agent. Do not overwrite other tools. If permissions or information are missing, guide the user to add:
+
+   ```json
+   {
+     "type": "custom",
+     "name": "mearl",
+     "description": "Invoke a Mearl browser action on the user's paired local browser. Use action=pair only with a code generated by @mearl/plugin-qoder pair.",
+     "input_schema": {
+       "type": "object",
+       "additionalProperties": false,
+       "properties": {
+         "action": { "type": "string" },
+         "payload": { "type": "object" },
+         "browser": { "type": "string" },
+         "timeoutSec": { "type": "number", "minimum": 1 }
+       },
+       "required": ["action"]
+     }
+   }
+   ```
+
+   Tool configuration belongs to the Agent and affects new Sessions only. Tell users to create a new Session and restart the normal flow rather than repeatedly retrying the current Session.
+
+4. Only if the local connector reports missing authentication, 401, or an expired PAT, follow its error to configure a Qoder PAT on the browser machine and restart. Errors provide supported credential sources and configuration. Do not ask users to send PATs to the Agent or put them in command URLs, chat, or logs. If users proactively provide a PAT and explicitly request configuration, write a supported source without repeating it.
+
+5. `page_screenshot` prefers Qoder image-content blocks while preserving metadata. If the API version rejects image blocks, connector falls back to JSON text containing original base64 so image data is not lost.
+
+---
+
+<a id="common"></a>
+
+## Common issues
+
+<a id="timeout"></a>

package/docs/cloud-pairing.md

@@ -1,5 +1,7 @@
 # Qoder Cloud Agent 配对模式
 
+[简体中文](cloud-pairing.md) | [English](cloud-pairing.en.md)
+
 当前运行于 Qoder Cloud Agent 时使用本模式；其他远端 Agent 使用 cloud-server / WebSocket 模式。浏览器机器先按本包 README 安装 Qoder 能力，Agent 机器可直接使用本包生成配对信息；两种模式保持相同的 Mearl action 契约。
 
 Qoder 模式使用官方 Client-Side 自定义工具和 Session 事件接口，不依赖 Cloudflare Tunnel，也不把 Qoder 沙箱公网入口当作 WebSocket。Agent 按以下顺序处理：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/plugin-qoder",
-  "version": "3.0.0-beta.8",
+  "version": "3.0.0",
   "description": "Optional Qoder CLI agent and cloud connector capability for Mearl",
   "type": "module",
   "license": "Apache-2.0",
@@ -16,6 +16,7 @@
     }
   },
   "files": [
+    "README.en.md",
     "dist",
     "docs",
     "!dist/**/__tests__/**",
@@ -26,10 +27,10 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.2.1",
-    "@mearl/browser-core": "3.0.0-beta.8",
-    "@mearl/client": "3.0.0-beta.8",
-    "@mearl/agent-runtime": "3.0.0-beta.8",
-    "@mearl/cloud-connector": "3.0.0-beta.8"
+    "@mearl/agent-runtime": "3.0.0",
+    "@mearl/cloud-connector": "3.0.0",
+    "@mearl/browser-core": "3.0.0",
+    "@mearl/client": "3.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3",