@mearl/plugin-qoder 0.0.0-stage → 3.0.0-beta.7

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './agent.js';
+export * from './connector.js';
+export * from './pairing.js';
+export * from './endpoint.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './agent.js';
+export * from './connector.js';
+export * from './pairing.js';
+export * from './endpoint.js';

package/dist/pairing.d.ts

@@ -0,0 +1,29 @@
+export interface QoderPairingInfo {
+    pairingCode: string;
+    createdAt: number;
+    connectorUrl: string;
+    toolInput: {
+        action: 'pair';
+        payload: {
+            code: string;
+        };
+    };
+}
+export interface QoderPairingOptions {
+    now?: () => number;
+    createCode?: () => string;
+}
+export type CloudServerCommand = 'start' | 'stop' | 'restart' | 'status' | 'logs';
+interface QoderCloudServerDependencies {
+    createPairing?: () => QoderPairingInfo;
+    isServerRunning: () => boolean;
+    printLogs: () => void;
+    printStatus: () => void;
+    stopServer: () => Promise<void>;
+    writeLine?: (message: string) => void;
+}
+/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
+export declare function createQoderPairingInfo(options?: QoderPairingOptions): QoderPairingInfo;
+export declare function formatQoderPairingOutput(info: QoderPairingInfo): string;
+export declare function runQoderCloudServerCommand(command: CloudServerCommand, dependencies: QoderCloudServerDependencies): Promise<void>;
+export {};

package/dist/pairing.js

@@ -0,0 +1,53 @@
+import { randomBytes } from 'node:crypto';
+/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
+export function createQoderPairingInfo(options = {}) {
+    const pairingCode = (options.createCode ?? (() => randomBytes(24).toString('base64url')))();
+    if (!/^[A-Za-z0-9_-]{16,128}$/.test(pairingCode)) {
+        throw new Error('Qoder pairing code must be 16-128 URL-safe characters');
+    }
+    const createdAt = (options.now ?? Date.now)();
+    if (!Number.isSafeInteger(createdAt) ||
+        createdAt < 1_000_000_000_000 ||
+        createdAt > 9_999_999_999_999) {
+        throw new Error('Qoder pairing timestamp must be a 13-digit epoch millisecond value');
+    }
+    return {
+        pairingCode,
+        createdAt,
+        connectorUrl: `qoder://pair/${pairingCode}?created=${createdAt}`,
+        toolInput: { action: 'pair', payload: { code: pairingCode } },
+    };
+}
+export function formatQoderPairingOutput(info) {
+    const connectorCommand = `npx @mearl/cloud-connector start "${info.connectorUrl}"`;
+    return `[CloudServer] Qoder pairing mode is ready.
+
+  Connect from your local machine:
+    ${connectorCommand}
+
+  Then immediately invoke the Qoder client-side custom tool named "mearl" with this input:
+    ${JSON.stringify(info.toolInput)}
+
+The connector resolves QODER_PERSONAL_ACCESS_TOKEN from the local environment, ~/.mearl/.env, or supported local credential storage. Never add the PAT to the pairing URL.`;
+}
+export async function runQoderCloudServerCommand(command, dependencies) {
+    const writeLine = dependencies.writeLine ?? console.log;
+    switch (command) {
+        case 'start':
+        case 'restart':
+            if (dependencies.isServerRunning())
+                await dependencies.stopServer();
+            writeLine(formatQoderPairingOutput((dependencies.createPairing ?? (() => createQoderPairingInfo()))()));
+            break;
+        case 'status':
+            dependencies.printStatus();
+            writeLine('[CloudServer] Mode: qoder pairing (no listening service)');
+            break;
+        case 'stop':
+            await dependencies.stopServer();
+            break;
+        case 'logs':
+            dependencies.printLogs();
+            break;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,14 @@
+import { QoderAgentProvider } from './agent.js';
+import { QoderConnector } from './connector.js';
+import { runQoderCloudServerCommand } from './pairing.js';
+/** Factories remain idle until the host selects this installed contribution. */
+export default function createQoderPlugin(): {
+    agent: (options: {
+        log: (message: string) => void;
+        version: string;
+    }) => QoderAgentProvider;
+    connector: (options: Omit<ConstructorParameters<typeof QoderConnector>[0], "endpoint"> & {
+        serverUrl: string;
+    }) => QoderConnector;
+    server: typeof runQoderCloudServerCommand;
+};

package/dist/runtime.js

@@ -0,0 +1,12 @@
+import { QoderAgentProvider } from './agent.js';
+import { QoderConnector } from './connector.js';
+import { requireQoderEndpoint } from './endpoint.js';
+import { runQoderCloudServerCommand } from './pairing.js';
+/** Factories remain idle until the host selects this installed contribution. */
+export default function createQoderPlugin() {
+    return {
+        agent: (options) => new QoderAgentProvider(options.log, options.version),
+        connector: (options) => new QoderConnector({ ...options, endpoint: requireQoderEndpoint(options.serverUrl) }),
+        server: runQoderCloudServerCommand,
+    };
+}

package/docs/cloud-pairing.md

@@ -0,0 +1,50 @@
+# Qoder Cloud Agent 配对模式
+
+当前运行于 Qoder Cloud Agent 时使用本模式；其他远端 Agent 使用 cloud-server / WebSocket 模式。浏览器机器先按本包 README 安装 Qoder 能力，Agent 机器可直接使用本包生成配对信息；两种模式保持相同的 Mearl action 契约。
+
+Qoder 模式使用官方 Client-Side 自定义工具和 Session 事件接口，不依赖 Cloudflare Tunnel，也不把 Qoder 沙箱公网入口当作 WebSocket。Agent 按以下顺序处理：
+
+1. 检查当前 Agent 是否已经提供名为 `mearl` 的 Client-Side 自定义工具。若已提供，Agent 直接执行：
+
+   ```bash
+   npx @mearl/plugin-qoder pair
+   ```
+
+   从输出读取本地 `npx @mearl/cloud-connector start "qoder://pair/..."` 命令和 `pair` 输入。先把本地命令展示给用户，再立即调用 `mearl` 自定义工具提交输出中的 `pair` 输入；该工具调用会暂停，直到用户在浏览器所在机器执行连接命令并完成配对。
+
+2. 配对后，本 Session 的浏览器操作不再在 Qoder 沙箱中执行 `mearl ...` shell 命令。Agent 在内部把 Skill 中相同的 action、payload、browser 和 timeout 映射为 `mearl` 自定义工具调用。对用户仍按正常 Mearl 操作结果交付，不额外暴露协议差异。
+
+3. 如果当前 Agent 没有 `mearl` 自定义工具，先判断 Agent 是否能使用已有 Qoder PAT 和 Agent ID/version 直接读取当前完整 `tools` 数组、追加下方配置并更新 Agent。不得覆盖其他已有工具。若缺少必要权限或信息，再引导用户在 Qoder Agent 配置中添加：
+
+   ```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"]
+     }
+   }
+   ```
+
+   Qoder 工具配置绑定 Agent；修改后只对新 Session 生效。明确提示用户新建 Session，再从正常流程开始；不要在当前 Session 反复重试。
+
+4. 仅当本地报认证缺失、401 或 PAT 过期时，按 connector 错误提示在浏览器所在机器配置 Qoder PAT 并重启 connector。凭据来源和本地配置方式由错误提示提供；不要求用户把 PAT 发给 Agent，不把 PAT 放进命令 URL、聊天消息或日志。用户已主动提供 PAT 并明确要求配置时，可写入受支持来源，但不得复述。
+
+5. `page_screenshot` 结果会优先以 Qoder 图片内容块回传，并保留截图元数据；若接口版本暂不接受图片块，connector 自动退回包含原始 base64 的 JSON 文本，确保截图数据不丢失。
+
+---
+
+<a id="common"></a>
+
+## 通用问题
+
+<a id="timeout"></a>

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@mearl/plugin-qoder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.0-beta.7",
+  "description": "Optional Qoder CLI agent and cloud connector capability for Mearl",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mearl-qoder": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.d.ts"
+  ],
+  "engines": {
+    "node": ">=20.18.0"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.2.1",
+    "@mearl/agent-runtime": "3.0.0-beta.7",
+    "@mearl/client": "3.0.0-beta.7",
+    "@mearl/cloud-connector": "3.0.0-beta.7",
+    "@mearl/browser-core": "3.0.0-beta.7"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "esbuild": "^0.28.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
+    "directory": "packages/plugin-qoder"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && tsc && node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }