@m2canvas/connect 0.3.1 → 0.4.0

package/adapters/claude-agent-acp/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "m2canvas-acp-adapter-claude",
+  "private": true,
+  "description": "Locked Claude ACP adapter, installed on demand by `npx @m2canvas/connect bridge`. Install with `npm ci` only.",
+  "dependencies": {
+    "@agentclientprotocol/claude-agent-acp": "0.84.0"
+  }
+}

package/adapters/codex-acp/package-lock.json

@@ -0,0 +1,364 @@
+{
+  "name": "m2canvas-acp-adapter-codex",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "m2canvas-acp-adapter-codex",
+      "dependencies": {
+        "@agentclientprotocol/codex-acp": "2.1.0",
+        "@agentclientprotocol/sdk": "1.5.1"
+      }
+    },
+    "node_modules/@agentclientprotocol/codex-acp": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@agentclientprotocol/codex-acp/-/codex-acp-2.1.0.tgz",
+      "integrity": "sha512-MJv/+hcnutTkUFdJj7ETwshyqOx1mMw+Q7Oaol2V3bnhudhz/wfG3L11IZI47+H2mryCB3FYHzZssc2fxtgXcg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@agentclientprotocol/sdk": "^1.5.0",
+        "@openai/codex": "^0.159.1",
+        "diff": "^9.0.0",
+        "open": "^11.0.1",
+        "vscode-jsonrpc": "^9.0.1",
+        "zod": "^4.0.0"
+      },
+      "bin": {
+        "codex-acp": "dist/index.js"
+      }
+    },
+    "node_modules/@agentclientprotocol/sdk": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-1.5.1.tgz",
+      "integrity": "sha512-nSUIrC1fOR9+ppKfx9KdwjBBND2sAPzFHo4yVQrGbXZHnayUYpwL8CDVR5LSxbapY/oKMOzNP0wvwfyx3PS2KA==",
+      "license": "Apache-2.0",
+      "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+      }
+    },
+    "node_modules/@openai/codex": {
+      "version": "0.159.3",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.159.3.tgz",
+      "integrity": "sha512-hg4nlqCwRb87GocxNnHvz4sadOrdJ71mO0a4CUYWXjAozJe2gtuAdRFldKGSQXw9m7SgR4ydis12KDVVPgzDkQ==",
+      "license": "Apache-2.0",
+      "bin": {
+        "codex": "bin/codex.js"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "optionalDependencies": {
+        "@openai/codex-darwin-arm64": "npm:@openai/codex@0.159.3-darwin-arm64",
+        "@openai/codex-darwin-x64": "npm:@openai/codex@0.159.3-darwin-x64",
+        "@openai/codex-linux-arm64": "npm:@openai/codex@0.159.3-linux-arm64",
+        "@openai/codex-linux-x64": "npm:@openai/codex@0.159.3-linux-x64",
+        "@openai/codex-win32-arm64": "npm:@openai/codex@0.159.3-win32-arm64",
+        "@openai/codex-win32-x64": "npm:@openai/codex@0.159.3-win32-x64"
+      }
+    },
+    "node_modules/@openai/codex-darwin-arm64": {
+      "name": "@openai/codex",
+      "version": "0.159.3-darwin-arm64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.159.3-darwin-arm64.tgz",
+      "integrity": "sha512-aI4UY14YURYxJxnRK+AE4QU+aek0mgtyyo7Rw9rNbCQUYETRQ0NYdJzU9ytljERGpPlht3dHHI1u4NhqHoDJDQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@openai/codex-darwin-x64": {
+      "name": "@openai/codex",
+      "version": "0.159.3-darwin-x64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.159.3-darwin-x64.tgz",
+      "integrity": "sha512-KTOQOD184DMXpR3TqnDUnLsgad14WJn+x3XmjBaXRHchKYGttjREwqrwzC61xQYFeh6VkogAceybR+SMbbgvYQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@openai/codex-linux-arm64": {
+      "name": "@openai/codex",
+      "version": "0.159.3-linux-arm64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.159.3-linux-arm64.tgz",
+      "integrity": "sha512-84C1yhAI+i0hqh77Akp/Ma09Z4d5oLKcZKqW1WZpEDh8bKbNvvbNEd6pE+GMUe2Kwg7jCbuvkRNH1zgK+SCM3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@openai/codex-linux-x64": {
+      "name": "@openai/codex",
+      "version": "0.159.3-linux-x64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.159.3-linux-x64.tgz",
+      "integrity": "sha512-xlHydfOksnNt/qz4BEVFvjMWunweaVSNtha/DkVUwWZnVZxbqiJwsXSl2iZDk04b6k/g0OI7jU06XqzHB2s5og==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@openai/codex-win32-arm64": {
+      "name": "@openai/codex",
+      "version": "0.159.3-win32-arm64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.159.3-win32-arm64.tgz",
+      "integrity": "sha512-4C+EuH1zE4rO5w1MsrnS98Tvq6Ff4+zeNr3pVeR/UsQ+VrTY5BCA9nZuXuCXNLKak1tLOw81b+fQM4jKGFCeDA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@openai/codex-win32-x64": {
+      "name": "@openai/codex",
+      "version": "0.159.3-win32-x64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.159.3-win32-x64.tgz",
+      "integrity": "sha512-h8w5nslfQyoYbonZaRlLwvPKFS9Mcxz5vUeCeoHKF5SsZUP9jSBH7hxUdc8RWJffJtfbV2qxdnImVAj9zy2fwA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/bundle-name": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/bundle-name/-/bundle-name-4.1.1.tgz",
+      "integrity": "sha512-DdH81/zPLVS11EUgWq3tEu/xn+EzljlMYooDNdzWEnFha3R3NBMpMV1UqYIpjYHV/SgpFKMIX1Oh7o06SjM/oA==",
+      "license": "MIT",
+      "dependencies": {
+        "run-applescript": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/default-browser": {
+      "version": "5.5.1",
+      "resolved": "https://registry.npmjs.org/default-browser/-/default-browser-5.5.1.tgz",
+      "integrity": "sha512-m1pAzaJgZ/gssEqlOhJkPJp8Xly7QyW6xcrkUa2KKcDeDSEMP7X8xipU3snUcfisTQx0w1AGae+9UtJSfVnXGw==",
+      "license": "MIT",
+      "dependencies": {
+        "bundle-name": "^4.1.0",
+        "default-browser-id": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/default-browser-id": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/default-browser-id/-/default-browser-id-5.0.1.tgz",
+      "integrity": "sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/define-lazy-prop": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-3.0.0.tgz",
+      "integrity": "sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/diff": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/diff/-/diff-9.0.0.tgz",
+      "integrity": "sha512-svtcdpS8CgJyqAjEQIXdb3OjhFVVYjzGAPO8WGCmRbrml64SPw/jJD4GoE98aR7r25A0XcgrK3F02yw9R/vhQw==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.3.1"
+      }
+    },
+    "node_modules/is-docker": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-3.0.0.tgz",
+      "integrity": "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==",
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-in-ssh": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-in-ssh/-/is-in-ssh-1.0.0.tgz",
+      "integrity": "sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-inside-container": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-inside-container/-/is-inside-container-1.0.0.tgz",
+      "integrity": "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==",
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^3.0.0"
+      },
+      "bin": {
+        "is-inside-container": "cli.js"
+      },
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-wsl": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-3.1.1.tgz",
+      "integrity": "sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-inside-container": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/open": {
+      "version": "11.0.4",
+      "resolved": "https://registry.npmjs.org/open/-/open-11.0.4.tgz",
+      "integrity": "sha512-++Zlftm0kVLPmzC06t6epuWmcRMDbI4z5P3NNX979WA/k23+NtSOynEGzsVfZwguKw2mi5umVgnBlJQMwRz4Pg==",
+      "license": "MIT",
+      "dependencies": {
+        "default-browser": "^5.5.1",
+        "define-lazy-prop": "^3.0.0",
+        "is-in-ssh": "^1.0.0",
+        "is-inside-container": "^1.0.0",
+        "powershell-utils": "^0.2.1",
+        "wsl-utils": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/powershell-utils": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/powershell-utils/-/powershell-utils-0.2.1.tgz",
+      "integrity": "sha512-C+y9x90UElAddDZmV4qOx9W53B61PO7cIqWz2dQsWlwswuq4mr8NEwytdGKboYbQlGZ3awrkTeNvcZiZNHnQ8A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/run-applescript": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/run-applescript/-/run-applescript-7.1.0.tgz",
+      "integrity": "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/vscode-jsonrpc": {
+      "version": "9.0.3",
+      "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-9.0.3.tgz",
+      "integrity": "sha512-qETYf9PCl1lVfwR+oBmMfc4vP2nqLNA35ABxorw3j06+xlKRgDVxbLgKm4Y/xPL0YWdeDjLoI4ImICIT3nB0zQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/wsl-utils": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/wsl-utils/-/wsl-utils-1.0.1.tgz",
+      "integrity": "sha512-c16PKLIRxBYpR3jSWsdS7SFp0COm5SOQdiFjY818dYFHJbMGuLBszpF07LBWmOS1uzrHa9VGdynsEgoeKy0oOQ==",
+      "license": "MIT",
+      "dependencies": {
+        "is-wsl": "^3.1.0",
+        "powershell-utils": "^0.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.6.5",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.5.tgz",
+      "integrity": "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/adapters/codex-acp/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "m2canvas-acp-adapter-codex",
+  "private": true,
+  "description": "Locked Codex ACP adapter, installed on demand by `npx @m2canvas/connect bridge`. Install with `npm ci` only. @agentclientprotocol/sdk is pinned to the version the ACP PoC ran with (codex-acp itself asks for ^1.5.0).",
+  "dependencies": {
+    "@agentclientprotocol/codex-acp": "2.1.0",
+    "@agentclientprotocol/sdk": "1.5.1"
+  }
+}

package/dist/bridge/acp-guard.js

@@ -0,0 +1,92 @@
+/**
+ * 页面 → agent 方向的 ACP 消息检查（纯函数）。bridge 唯一会解析的 ACP 内容就在这里；agent → 页面方向仍然原样转发、不解析。
+ *
+ * 为什么要有它（review r3 B1）：ACP 允许客户端在会话类请求里指定工作目录（`cwd`）、让 agent 额外拉起 MCP 服务器
+ * （`mcpServers`，stdio 类型带 command / args / env）、扩大工作区（`additionalDirectories`），Claude 适配器还会从
+ * `_meta.claudeCode.options` 读 env / settings。原样转发等于让页面绕过「会话目录由终端用户决定」「不注入 MCP」这两条
+ * 已拍板的边界。这里把它们落到实处：
+ * - 方法白名单（review r4 R4-1）：只放行 `PAGE_ACP_METHODS`，其余一律拒收。名单外有能改 agent 状态的方法 ——
+ *   `providers/set` 换掉 Claude 的 API 地址与 headers（作用于所有会话）、`authenticate` 的 gateway 方式经 `_meta` 传
+ *   baseUrl / headers、`logout` 把用户登出、`session/delete` 删本机历史 —— 按字段名扫描挡不住换了字段名的同义参数，
+ *   所以按方法放行。页面要用新方法时，在这里加上并发新版 bridge；旧 bridge 会回 `acp_rejected`，页面按 `bridge.version` 引导升级。
+ * - 会话类方法（session/new、load、resume、list）：`cwd` 必须逐字等于 bridge 的会话目录（welcome 里报给页面的那个值）；
+ *   session/list 必须带 cwd（不带时 Claude / Codex 会列出全机所有项目的会话标题）。
+ * - 白名单内的任何请求：params 里出现 `cwd` 必须等于会话目录；`mcpServers` 只能是空数组或不带；不允许 `_meta`、
+ *   不允许非空 `additionalDirectories`。
+ * - 形状：不是 JSON 对象的行一律拒收（含 JSON-RPC 批量数组 —— ACP SDK 会把数组逐条入队）；有 `method` 键但不是字符串的拒收
+ *   （不能当成响应放行）；消息或 params 自带 `__proto__` / `constructor` / `prototype` 键的拒收。
+ *
+ * 边界（不要把它当成安全的全部）：这是纵深防御，不改变「配对 = 授权该页面以你的身份驱动本机 agent」——
+ * 页面仍可以用提示词让 agent 执行命令、替用户回答审批、切换到不审批的工作模式。真正的门槛是 security.ts / pairing.ts 的准入。
+ * 前提：agent 解析 JSON 的结果与这里一致（例如重复键都取最后一个）。2026-10-03 核实：两个适配器经 ACP SDK 1.5.1 的
+ * stream.js 用 JSON.parse；Cursor 是 node bundle；OpenCode、Qoder 是 Bun 单文件可执行（证据见 change 的 verification §13）。
+ * 哪家换了解析器，要重新核这一条。
+ */
+import { BRIDGE_PAGE_ACP_METHODS } from './protocol.js';
+/** 页面可以发给 agent 的方法：change 3 实际用到的方法 + JSON-RPC 层的取消请求（定义在 protocol.ts，前端也能 import） */
+export const PAGE_ACP_METHODS = BRIDGE_PAGE_ACP_METHODS;
+/** cwd 由 bridge 决定的会话类方法（必须带 cwd） */
+export const SESSION_SCOPE_METHODS = ['session/new', 'session/load', 'session/resume', 'session/list'];
+/** JSON.parse 会把这些键建成普通自有属性；agent 侧的对象合并 / 校验可能对它们另有处理，一律不放行 */
+const FORBIDDEN_KEYS = ['__proto__', 'constructor', 'prototype'];
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function hasForbiddenKey(value) {
+    return Object.keys(value).some((key) => FORBIDDEN_KEYS.includes(key));
+}
+function rpcIdOf(message) {
+    const id = message.id;
+    return typeof id === 'string' || typeof id === 'number' ? id : null;
+}
+/** 返回违规原因；合规返回 null */
+function scopeViolation(params, cwd, sessionScoped) {
+    if (hasForbiddenKey(params))
+        return 'params must not contain __proto__ / constructor / prototype';
+    if (hasOwn(params, 'cwd') || sessionScoped) {
+        if (params.cwd !== cwd)
+            return `cwd must be the bridge working directory (${cwd})`;
+    }
+    if (hasOwn(params, 'mcpServers') && !(Array.isArray(params.mcpServers) && params.mcpServers.length === 0)) {
+        return 'mcpServers must be empty: agents use their own MCP configuration';
+    }
+    if (hasOwn(params, 'additionalDirectories') && !(Array.isArray(params.additionalDirectories) && params.additionalDirectories.length === 0)) {
+        return 'additionalDirectories is not allowed';
+    }
+    if (hasOwn(params, '_meta'))
+        return '_meta is not allowed';
+    return null;
+}
+export function checkPageAcpLine(line, cwd) {
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return { ok: false, reason: 'not valid JSON', method: null, rpcId: null };
+    }
+    if (!isObject(message))
+        return { ok: false, reason: 'must be a single JSON-RPC message object', method: null, rpcId: null };
+    const method = typeof message.method === 'string' ? message.method : null;
+    const reject = (reason) => ({ ok: false, reason, method, rpcId: rpcIdOf(message) });
+    if (hasForbiddenKey(message))
+        return reject('message must not contain __proto__ / constructor / prototype');
+    // 没有 method 键的是页面对 agent 请求的响应（例如审批结果），不涉及方法与会话范围
+    if (!hasOwn(message, 'method'))
+        return { ok: true };
+    if (method === null)
+        return reject('method must be a string');
+    if (!PAGE_ACP_METHODS.includes(method))
+        return reject(`method ${method} is not allowed from the page`);
+    const sessionScoped = SESSION_SCOPE_METHODS.includes(method);
+    const params = message.params;
+    if (params === undefined && !sessionScoped)
+        return { ok: true };
+    if (!isObject(params))
+        return reject('params must be an object');
+    const violation = scopeViolation(params, cwd, sessionScoped);
+    return violation ? reject(violation) : { ok: true };
+}

package/dist/bridge/adapters.js

@@ -0,0 +1,146 @@
+/**
+ * Claude / Codex 的 ACP 适配器：按需安装、精确锁定（用户拍板：用适配器自带的 agent 版本，首次使用时再装）。
+ *
+ * 为什么不放进 connect 的 dependencies：两个适配器各自带一份原生 agent（darwin-arm64 解压后 Claude 226MB、Codex 331MB）。
+ * 放进去会让每一次 `npx @m2canvas/connect --client X`（Copy to agent 起手式，在 agent 的沙箱里跑）都下载这些。
+ *
+ * 为什么必须用随包 lockfile + `npm ci`，而不是 `npx <adapter>@<version>`：codex-acp 对 @openai/codex 是 ^0.159.1，
+ * claude-agent-sdk 的 peer 依赖也是范围，只有 lockfile 能把整棵树（含平台二进制）锁死；npm ci 还会校验 integrity。
+ *
+ * 维护约束：
+ * - 升级适配器 = 改 adapters/<dir>/package.json + 用官方 registry 重新生成 package-lock.json + 改下面的 ADAPTERS 常量
+ *   （单测会核对三者一致），并按 ACP PoC 的场景重新实测。不要只改版本号。
+ * - `--ignore-scripts`：两条依赖链上没有安装脚本（实测），加上它能挡掉安装期执行代码。
+ * - 安装目录名带 lockfile 哈希：换了 lockfile 就是新目录，旧目录不会被半新半旧地复用。旧目录目前不清理（FU-2026-10-02-120）。
+ * - 先装到临时目录、写好就绪标记再原子改名；残留的临时目录或没有标记的目录一律视为未安装。
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { combinedOutput } from './exec.js';
+import { tail } from './precheck-parse.js';
+export const ADAPTERS = {
+    claude: {
+        dir: 'claude-agent-acp',
+        package: '@agentclientprotocol/claude-agent-acp',
+        version: '0.84.0',
+        entry: 'node_modules/@agentclientprotocol/claude-agent-acp/dist/index.js',
+    },
+    codex: {
+        dir: 'codex-acp',
+        package: '@agentclientprotocol/codex-acp',
+        version: '2.1.0',
+        entry: 'node_modules/@agentclientprotocol/codex-acp/dist/index.js',
+    },
+};
+/** 适配器自带的 codex：预检与授权命令都要用它（本机旧版 codex 存的凭证，新版本刷新不了，PoC 报告 §2.2） */
+export const CODEX_SCRIPT = 'node_modules/@openai/codex/bin/codex.js';
+export const CODEX_BIN_LINK = 'node_modules/.bin/codex';
+const READY_MARKER = '.m2canvas-ready';
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM = 进程在但属于别的用户，也算活着
+        return error.code === 'EPERM';
+    }
+}
+export function isAdapterAgent(agent) {
+    return agent === 'claude' || agent === 'codex';
+}
+export class AdapterManager {
+    options;
+    installing = new Map();
+    lastError = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    lockKey(agent) {
+        const lock = readFileSync(join(this.options.sourceRoot, ADAPTERS[agent].dir, 'package-lock.json'));
+        return createHash('sha256').update(lock).digest('hex').slice(0, 16);
+    }
+    installDir(agent) {
+        return join(this.options.installRoot, `${ADAPTERS[agent].dir}-${this.lockKey(agent)}`);
+    }
+    entryPath(agent) {
+        return join(this.installDir(agent), ADAPTERS[agent].entry);
+    }
+    isReady(agent) {
+        const dir = this.installDir(agent);
+        return existsSync(join(dir, READY_MARKER)) && existsSync(join(dir, ADAPTERS[agent].entry));
+    }
+    info(agent) {
+        const spec = ADAPTERS[agent];
+        const base = { package: spec.package, version: spec.version };
+        if (this.installing.has(agent))
+            return { ...base, state: 'installing', error: null };
+        if (this.isReady(agent))
+            return { ...base, state: 'ready', error: null };
+        const error = this.lastError.get(agent);
+        return error ? { ...base, state: 'failed', error } : { ...base, state: 'not_installed', error: null };
+    }
+    /** 已就绪直接返回；正在装就等同一次安装；否则开始安装。失败不抛错，返回 state = failed */
+    prepare(agent) {
+        if (this.isReady(agent))
+            return Promise.resolve(this.info(agent));
+        const running = this.installing.get(agent);
+        if (running)
+            return running;
+        this.lastError.delete(agent);
+        const job = this.install(agent).finally(() => {
+            this.installing.delete(agent);
+            this.options.onState?.(agent, this.info(agent));
+        });
+        this.installing.set(agent, job.then(() => this.info(agent)));
+        this.options.onState?.(agent, this.info(agent));
+        return this.installing.get(agent);
+    }
+    /**
+     * 清掉之前被中途杀掉的安装留下的临时目录（可能有几百 MB；那次安装的 finally 没机会执行）。
+     * 只删「目录名里的 pid 已不在运行」的；pid 仍在（可能是另一个 bridge 正在装，或 pid 被复用）就不动，宁可多留。
+     */
+    removeStaleTemps(spec) {
+        if (!existsSync(this.options.installRoot))
+            return;
+        const pattern = new RegExp(`^\\.tmp-${spec.dir}-(\\d+)-[0-9a-f]+$`);
+        for (const name of readdirSync(this.options.installRoot)) {
+            const pid = Number(pattern.exec(name)?.[1]);
+            if (!pid || isProcessAlive(pid))
+                continue;
+            rmSync(join(this.options.installRoot, name), { recursive: true, force: true });
+        }
+    }
+    async install(agent) {
+        const spec = ADAPTERS[agent];
+        const finalDir = this.installDir(agent);
+        this.removeStaleTemps(spec);
+        const tmpDir = join(this.options.installRoot, `.tmp-${spec.dir}-${process.pid}-${randomBytes(4).toString('hex')}`);
+        try {
+            mkdirSync(tmpDir, { recursive: true });
+            for (const file of ['package.json', 'package-lock.json']) {
+                copyFileSync(join(this.options.sourceRoot, spec.dir, file), join(tmpDir, file));
+            }
+            const result = await this.options.runNpmCi(tmpDir);
+            if (result.code !== 0)
+                throw new Error(`npm ci failed (${result.timedOut ? 'timed out' : `exit ${String(result.code)}`}): ${tail(combinedOutput(result))}`);
+            if (!existsSync(join(tmpDir, spec.entry)))
+                throw new Error(`npm ci finished but ${spec.entry} is missing`);
+            writeFileSync(join(tmpDir, READY_MARKER), `${JSON.stringify({ package: spec.package, version: spec.version, installedAt: new Date().toISOString() })}\n`);
+            if (existsSync(finalDir)) {
+                // 另一个 bridge 先装好了（或残留了没有标记的旧目录）：前者直接用，后者替换掉
+                if (this.isReady(agent))
+                    return;
+                rmSync(finalDir, { recursive: true, force: true });
+            }
+            renameSync(tmpDir, finalDir);
+        }
+        catch (error) {
+            this.lastError.set(agent, error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+    }
+}