@m2canvas/connect 0.4.0 → 0.6.0

package/dist/bridge/pairing.js

@@ -3,7 +3,11 @@
  * 和本机其他进程（可以伪造 Origin）。它们都拿不到只出现在终端里的配对码。
  * 配对 = 授权该页面以用户的身份驱动本机 agent（包括执行命令），所以码和 token 都按这个级别保管。
  *
- * 流程：终端打印一次性配对码 → 用户在页面输入 → 换取长期 token（页面存 localStorage）→ 之后每次 hello 带上。
+ * 两条途径，都要证明「终端用户同意了这个页面」（change acp-bridge-command-pairing）：
+ * - 输码：终端打印一次性配对码 → 用户在页面输入 → 换取长期 token（页面存 localStorage）→ 之后每次 hello 带上。
+ * - 命令承诺：页面生成密钥 S，启动命令只带承诺 c = base64url(sha256(S) 的前 16 字节)（`bridge --pair c`）；
+ *   页面在 hello 里出示 S，一致就换取同样的 token。「在自己终端里运行了这个页面给的命令」与「抄了终端里的码」证明的是同一件事。
+ *   命令会进 `ps` 与 shell 历史，所以命令里只能有承诺、不能有 S；承诺只在内存里、自挂上起 CODE_TTL_MS 有效、成功一次即作废。
  *
  * 维护约束：
  * - 本地只存 token 的 sha256，不存明文；文件 0600、目录 0700。
@@ -33,6 +37,18 @@ const PROMPT_DEDUPE_MS = 60_000;
 /** Crockford base32：去掉易混的 I、L、O、U */
 const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
 const CODE_LENGTH = 8;
+/** 页面密钥 S：32 字节随机数的 base64url（无填充） */
+const PAIR_SECRET_RE = /^[A-Za-z0-9_-]{43}$/;
+/** 承诺：sha256(S) 前 16 字节的 base64url（无填充） */
+const PAIR_COMMITMENT_RE = /^[A-Za-z0-9_-]{22}$/;
+const COMMITMENT_BYTES = 16;
+export function isPairCommitment(value) {
+    return PAIR_COMMITMENT_RE.test(value);
+}
+/** 承诺 = base64url(sha256(S 的 UTF-8) 的前 16 字节)。前端 `bridge-pair-secret.ts` 用 WebCrypto 算同一个值，改这里要同批改那边。 */
+export function pairCommitmentOf(secret) {
+    return sha256(secret).subarray(0, COMMITMENT_BYTES).toString('base64url');
+}
 /** 用户输入归一：大小写、空格、连字符；按 Crockford 规则把 O 视同 0、I / L 视同 1 */
 export function normalizePairingCode(input) {
     return input
@@ -57,6 +73,10 @@ function errorText(error) {
 }
 export class PairingManager {
     active = null;
+    /** `--pair` 挂上的承诺（只在内存里：bridge 重启即失效，重新运行同一条命令会重新挂上） */
+    commitment = null;
+    /** 已用掉的承诺：同一个密钥再出现时告警（只在内存里，只记最近一个） */
+    consumed = null;
     /** 自上次成功配对以来累计的错码次数（跨码、跨过期）；配对成功时清零 */
     failuresSinceSuccess = 0;
     locked = false;
@@ -67,12 +87,14 @@ export class PairingManager {
     onCodeIssued;
     onLocked;
     onProblem;
+    onCommitmentReused;
     constructor(options) {
         this.store = options.store;
         this.now = options.now ?? Date.now;
         this.onCodeIssued = options.onCodeIssued;
         this.onLocked = options.onLocked ?? (() => undefined);
         this.onProblem = options.onProblem ?? (() => undefined);
+        this.onCommitmentReused = options.onCommitmentReused ?? (() => undefined);
     }
     /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式 */
     issueCode(reason, origin = null) {
@@ -152,6 +174,59 @@ export class PairingManager {
         this.issueCode('too_many_failures', origin);
         return { ok: false, code: 'pairing_code_rotated' };
     }
+    /** 挂上启动命令里的承诺，返回它的过期时刻。格式不对时抛出：由 `--pair` 的参数解析先挡掉。 */
+    armCommitment(commitment) {
+        if (!isPairCommitment(commitment))
+            throw new Error('invalid pairing commitment');
+        const armedAt = this.now();
+        this.commitment = { value: Buffer.from(commitment, 'base64url'), armedAt };
+        return armedAt + CODE_TTL_MS;
+    }
+    /**
+     * 页面在 hello 里出示 S。对不上不计入错码次数：S 有 32 字节、承诺有 128 bit，不存在可猜性，
+     * 计入只会让多标签页、旧 S 这类无害的不匹配把用户锁住。锁定期间一律不成立 —— 「锁定只能重启解除」不设例外。
+     * 签发 token 写盘失败时不抛出（hello 里抛出会以 1011 关闭，等待中的页面会反复撞上）、不消费承诺，交给调用方按未配对处理。
+     */
+    pairWithSecret(secret, origin) {
+        const commitment = this.commitment;
+        // 重现检查在锁定检查之前：否则抢先配对的一方再用错码把 bridge 锁住，就能压掉这次告警（review r2 S1）
+        if (!commitment)
+            return this.checkReused(secret, origin);
+        if (this.locked)
+            return { ok: false, reason: 'locked' };
+        if (this.now() - commitment.armedAt > CODE_TTL_MS) {
+            this.commitment = null;
+            return { ok: false, reason: 'expired' };
+        }
+        if (!PAIR_SECRET_RE.test(secret))
+            return { ok: false, reason: 'malformed' };
+        if (!timingSafeEqual(sha256(secret).subarray(0, COMMITMENT_BYTES), commitment.value))
+            return { ok: false, reason: 'mismatch' };
+        let token;
+        try {
+            token = this.createToken(origin);
+        }
+        catch (error) {
+            this.onProblem(`Could not save the pairing (${errorText(error)}). This page will be asked for a pairing code instead.`);
+            return { ok: false, reason: 'store_failed' };
+        }
+        this.commitment = null;
+        this.consumed = { value: commitment.value, origin, usedAt: this.now(), warned: false };
+        this.failuresSinceSuccess = 0;
+        return { ok: true, token };
+    }
+    checkReused(secret, origin) {
+        const consumed = this.consumed;
+        if (!consumed || !PAIR_SECRET_RE.test(secret))
+            return { ok: false, reason: 'no_commitment' };
+        if (!timingSafeEqual(sha256(secret).subarray(0, COMMITMENT_BYTES), consumed.value))
+            return { ok: false, reason: 'no_commitment' };
+        if (!consumed.warned) {
+            consumed.warned = true;
+            this.onCommitmentReused({ origin, firstOrigin: consumed.origin, usedAt: consumed.usedAt });
+        }
+        return { ok: false, reason: 'reused' };
+    }
     createToken(origin) {
         const token = randomBytes(32).toString('base64url');
         const nowIso = new Date(this.now()).toISOString();

package/dist/bridge/precheck.js

@@ -4,15 +4,19 @@
  * 为什么要预检：m2 没配置、没授权、还没连上时，ACP 里没有任何信号，agent 只会说「没有这个工具」（PoC 报告 §4.1）。
  *
  * 边界：
- * - 只运行不修改配置的状态命令（status、mcp list；注意 `claude mcp list` 会启动用户配置的 stdio MCP 做健康检查）；bridge 不替用户登录、不替用户授权，只返回命令让用户在自己的终端执行。
+ * - 只运行不修改配置的状态命令（status、mcp list；注意 `claude mcp list` 会启动用户配置的 stdio MCP 做健康检查）。
+ *   预检本身不登录、不授权，只返回命令（终端兜底）；代跑写死清单里的授权命令是 agent/authorize 的事（authorize.ts），
+ *   预检结果里的 `authorize` 能力由 service.ts 加上。
  * - 不调用 ACP authenticate 探测登录：Qoder 未登录时 60 秒不响应（PoC 报告 §2.5）。
  * - `qodercli mcp list` 会以 `mcp-test-client` 身份连 M2，服务端判成 mcp、不进项目房间（总控 §6）：页面不要把这次连接当成 Qoder 会话。
  * - Cursor 的 m2 授权按目录保存，mcp list 与授权命令都必须在会话 cwd 下执行。
  * - Codex 的预检与授权都用适配器自带的 codex（调用方保证适配器已就绪）。
+ * - Claude 同样用适配器自带的 claude（D9）：会话用的就是它，本机那份只决定兜底命令怎么显示。找不到自带程序时报 unknown，
+ *   不退回本机的 claude（否则预检和会话看的是两个程序）。
  */
 import { join } from 'node:path';
 import { findM2Names } from './m2-config.js';
-import { CODEX_BIN_LINK, CODEX_SCRIPT } from './adapters.js';
+import { ADAPTERS, CODEX_BIN_LINK, CODEX_SCRIPT } from './adapters.js';
 import { combinedOutput } from './exec.js';
 import { parseClaudeAuthStatus, parseClaudeMcpList, parseCodexLoginStatus, parseCodexMcpListJson, parseCursorMcpList, parseCursorStatus, parseOpencodeMcpList, parseQoderMcpList, parseQoderStatus, tail, } from './precheck-parse.js';
 export const PRECHECK_TIMEOUT_MS = 45_000;
@@ -41,20 +45,27 @@ function plan(agent, deps) {
     const cmd = agent.command ?? agent.path ?? agent.id;
     const path = agent.path ?? cmd;
     switch (agent.id) {
-        case 'claude':
+        case 'claude': {
+            const binary = deps.adapters.claudeBinary();
+            // 兜底命令：本机装了 claude 就显示 `claude …`（用户熟悉），否则显示自带程序的绝对路径（D9）
+            const shown = agent.installed ? cmd : (binary ?? cmd);
             return {
-                exec: { command: path, prefix: [] },
-                login: { args: ['auth', 'status', '--json'], parse: (r) => parseClaudeAuthStatus(r.stdout, r.code), next: run(cmd, ['auth', 'login']) },
+                exec: { command: binary ?? '', prefix: [] },
+                missing: binary
+                    ? undefined
+                    : `Could not find the Claude Code program bundled with ${ADAPTERS.claude.package}@${ADAPTERS.claude.version}; try reinstalling the adapter.`,
+                login: { args: ['auth', 'status', '--json'], parse: (r) => parseClaudeAuthStatus(r.stdout, r.code), next: run(shown, ['auth', 'login']) },
                 m2: {
                     args: ['mcp', 'list'],
                     parse: (r) => parseClaudeMcpList(combinedOutput(r), r.code),
                     next: (state, entry) => state === 'needs_auth'
-                        ? run(cmd, ['mcp', 'login', entry])
+                        ? run(shown, ['mcp', 'login', entry])
                         : state === 'needs_enable'
                             ? { kind: 'manual', text: `Run claude in ${deps.cwd} and approve the project MCP server "${entry}".` }
                             : null,
                 },
             };
+        }
         case 'codex': {
             const dir = deps.adapters.installDir('codex');
             const display = join(dir, CODEX_BIN_LINK);
@@ -126,6 +137,8 @@ async function runStep(deps, p, args) {
 }
 export async function precheckM2(agent, deps) {
     const p = plan(agent, deps);
+    if (p.missing)
+        return toM2({ state: 'unknown', entry: null, raw: tail(p.missing) }, p.m2.next);
     const result = await runStep(deps, p, p.m2.args);
     const failure = failed(result);
     return toM2(failure ? { state: 'unknown', entry: null, raw: failure } : p.m2.parse(result), p.m2.next);
@@ -133,6 +146,9 @@ export async function precheckM2(agent, deps) {
 /** 调用方保证 agent 已安装；适配器类 agent 的适配器已就绪 */
 export async function precheckAgent(agent, deps, now = () => new Date()) {
     const p = plan(agent, deps);
+    if (p.missing) {
+        return { agent: agent.id, login: toLogin({ state: 'unknown', raw: tail(p.missing) }, p.login.next), m2: await precheckM2(agent, deps), checkedAt: now().toISOString() };
+    }
     const loginArgs = p.login.args;
     const [loginResult, m2] = await Promise.all([
         loginArgs ? runStep(deps, p, loginArgs) : Promise.resolve(null),

package/dist/bridge/protocol.js

@@ -1,7 +1,8 @@
 /**
  * 本机 ACP bridge ↔ M2 页面的 WebSocket 协议（change acp-local-bridge，给 change 3 acp-panel-local-agent 用）。
  *
- * 规范正文在 openspec 里该 change 的 design「页面协议」一节；本文件是它的类型落地，两者不一致时以 design 为准并修正这里。
+ * 规范正文在 openspec/archive/acp-local-bridge/design.md 的「页面协议」一节（之后改协议的 change 在自己的 design 里写出变化）；
+ * 本文件是它的类型落地，两者不一致时以 design 为准并修正这里。长期契约见 openspec/specs/connect/local-bridge.md。
  *
  * 维护约束：
  * - 本文件同时被 bridge（Node，ES2022 / NodeNext）和前端（浏览器，ES2020 / bundler / noUncheckedIndexedAccess）编译，
@@ -20,6 +21,13 @@ export const BRIDGE_DEFAULT_PORT = 47821;
 export const BRIDGE_WS_PATH = '/bridge';
 /** 与前端 src/lib/agent-types 的 AgentType 取值一致（是它的子集），顺序即 agents/list 的返回顺序 */
 export const BRIDGE_AGENT_IDS = ['claude', 'codex', 'cursor', 'opencode', 'qoder'];
+/**
+ * `agent/authorize` 的动作（change acp-terminal-free-auth，0.6.0 起）：login = agent 账号登录，m2 = m2 MCP 授权。
+ * 页面只能选「哪个 agent × 哪个动作」，可执行文件、参数、环境、工作目录全部由 bridge 的写死清单决定（契约 3）。
+ */
+export const BRIDGE_AUTH_ACTIONS = ['login', 'm2'];
+/** `auth/link` 的链接上限（bridge 只转交不超过它的 https 链接，页面收到时再按同一上限把一次关） */
+export const BRIDGE_MAX_AUTH_LINK_CHARS = 8 * 1024;
 /**
  * 页面可以发给 agent 的 ACP 方法（bridge 的 acp-guard.ts 按它放行，名单外回 `acp_rejected`、不转发）。
  * 页面对 agent 请求的响应（没有 method 键，例如审批结果）不受它限制。页面要用新方法：先在这里加上并发新版 bridge，
@@ -46,6 +54,8 @@ export const BRIDGE_METHODS = [
     'm2/configure',
     'process/start',
     'process/stop',
+    'agent/authorize',
+    'agent/authorize-cancel',
 ];
 export const BRIDGE_CLOSE_CODES = {
     normal: 1000,

package/dist/bridge/server.js

@@ -7,17 +7,23 @@
  * 都由页面发出）。所以安全的重心在「谁能配对」，配对之后能做的事只做纵深防御：
  * - 只监听 127.0.0.1；upgrade 校验（对端、Host、Origin、路径）在完成握手之前，失败直接写 HTTP 状态并销毁 socket。
  * - 握手后第一条消息必须是 hello；未配对的连接只能调用 pair，其余已知方法与 acp 帧一律 not_paired。
- * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
+ *   连接只有两种方式成为已配对：hello 带有效 token，或 hello 的 pairSecret 与启动命令的承诺一致（pairing.ts 文件头）。
+ * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、授权动作（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
+ *   agent/authorize 与 agent/authorize-cancel 的 params 只能有规定的键，多一个就 bad_message（分派在 auth-call.ts，命令清单写死在 authorize.ts）。
  * - 页面发给 agent 的 ACP 行禁止含换行，并经 acp-guard.ts 检查：只能用白名单里的方法、会话目录固定为 bridge 的 cwd、不能让 agent 额外拉起 MCP 服务器。
  *
- * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责），不替用户登录。
+ * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责）。
+ * 登录 / m2 授权只代跑写死清单里的命令，授权页由用户在浏览器里亲自完成（authorize.ts）；授权链接只发给发起的连接，不进终端日志。
  */
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
 import { TOKEN_IDLE_DAYS } from './pairing.js';
 import { ProcessError, ProcessManager } from './processes.js';
-import { BRIDGE_AGENT_IDS, BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
+import { isBridgeAgentId } from './agents.js';
+import { handleAuthCall } from './auth-call.js';
+import { AuthorizationManager } from './authorize.js';
+import { BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
 import { checkPageAcpLine } from './acp-guard.js';
 import { checkUpgrade } from './security.js';
 import { BridgeFailure } from './service.js';
@@ -31,9 +37,6 @@ const MAX_CALL_ID = 64;
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function isAgentId(value) {
-    return typeof value === 'string' && BRIDGE_AGENT_IDS.includes(value);
-}
 function isMethod(value) {
     return typeof value === 'string' && BRIDGE_METHODS.includes(value);
 }
@@ -76,6 +79,23 @@ export function startBridgeServer(options) {
         },
         onStderr: options.verbose ? (_id, agent, text) => process.stderr.write(`[${agent}] ${text}`) : undefined,
     });
+    const authorizations = new AuthorizationManager({
+        timeoutMs: options.timing?.authTimeoutMs,
+        graceMs: options.timing?.authGraceMs,
+        pollMs: options.timing?.authPollMs,
+    });
+    const authContext = {
+        authorizations,
+        service: options.service,
+        log,
+        isConnected: (ownerId) => connections.has(ownerId),
+        // 授权链接只发给发起的连接（D4）
+        sendLink: (ownerId, data) => {
+            const owner = connections.get(ownerId);
+            if (owner)
+                send(owner, { type: 'event', event: 'auth/link', data });
+        },
+    };
     const unpairedCount = () => [...connections.values()].filter((conn) => !conn.paired).length;
     const markPaired = (conn) => {
         conn.paired = true;
@@ -110,8 +130,10 @@ export function startBridgeServer(options) {
         }
         if (method === 'agents/list')
             return { agents: await options.service.list() };
+        if (method === 'agent/authorize' || method === 'agent/authorize-cancel')
+            return handleAuthCall(authContext, conn.id, method, params);
         const agent = params.agent;
-        if (!isAgentId(agent))
+        if (!isBridgeAgentId(agent))
             throw new BridgeFailure('unknown_agent', `unknown agent ${String(agent)}`);
         switch (method) {
             case 'agent/prepare':
@@ -159,7 +181,19 @@ export function startBridgeServer(options) {
             clearTimeout(conn.timer);
         conn.timer = null;
         const token = typeof frame.token === 'string' ? frame.token : undefined;
-        const paired = options.pairing.verifyToken(token, conn.origin);
+        let paired = options.pairing.verifyToken(token, conn.origin);
+        // 命令承诺配对：在未配对名额检查之前 —— 合法页面不被别人占满的未配对名额挡住。对不上（含写盘失败）一律按未配对继续，不抛出
+        let issuedToken;
+        if (!paired && typeof frame.pairSecret === 'string') {
+            const result = options.pairing.pairWithSecret(frame.pairSecret, conn.origin);
+            if (result.ok) {
+                paired = true;
+                issuedToken = result.token;
+                log(`Paired with ${conn.origin}.`);
+            }
+            else if (options.verbose)
+                log(`${conn.origin} did not pair from the start command (${result.reason}).`);
+        }
         if (paired) {
             markPaired(conn);
         }
@@ -182,6 +216,7 @@ export function startBridgeServer(options) {
             paired,
             tokenRejected: token !== undefined && !paired,
             cwd: paired ? options.cwd : null,
+            ...(issuedToken ? { token: issuedToken } : {}),
         });
     }
     function onFrame(conn, data, isBinary) {
@@ -282,12 +317,12 @@ export function startBridgeServer(options) {
                     clearTimeout(conn.timer);
                 connections.delete(conn.id);
                 processes.stopOwner(conn.id);
+                authorizations.cancelOwner(conn.id);
             });
             // ws 的错误（非法帧、超过 maxPayload 等）之后必然紧跟 'close'，清理在 close 里做；这里只防止未处理的 error 事件让进程崩溃
             ws.on('error', () => undefined);
         });
     });
-    // 心跳：浏览器自动回 pong；连续一个周期没回（休眠、崩溃、断网）就断开并清理它的进程
     // 被拒连接的终端日志限频：任何网站都能反复连 127.0.0.1，逐条打印会把配对码和「X wants to pair」顶出视野（review r3 S5）。
     // 同一原因在一个窗口内只打第一条，窗口结束时汇总被合并的次数。
     const rejectWindowMs = options.timing?.rejectLogWindowMs ?? REJECT_LOG_WINDOW_MS;
@@ -318,25 +353,33 @@ export function startBridgeServer(options) {
             },
         };
     })();
-    const heartbeat = setInterval(() => {
-        for (const conn of connections.values()) {
-            if (!conn.alive) {
-                conn.ws.terminate();
-                continue;
-            }
-            conn.alive = false;
-            conn.ws.ping();
-        }
-    }, timing.pingIntervalMs);
     return new Promise((resolve, reject) => {
-        http.once('error', reject);
+        // 监听失败（端口被占）时停掉已经开始的计时器：--replace 会在同一进程里再监听一次（review r4 N4）。心跳在监听成功后才开始
+        const fail = (error) => {
+            rejectLog.stop();
+            wss.close();
+            reject(error);
+        };
+        http.once('error', fail);
         http.listen(options.port, '127.0.0.1', () => {
-            http.off('error', reject);
+            http.off('error', fail);
+            // 心跳：浏览器自动回 pong；连续一个周期没回（休眠、崩溃、断网）就断开并清理它的进程
+            const heartbeat = setInterval(() => {
+                for (const conn of connections.values()) {
+                    if (!conn.alive) {
+                        conn.ws.terminate();
+                        continue;
+                    }
+                    conn.alive = false;
+                    conn.ws.ping();
+                }
+            }, timing.pingIntervalMs);
             const address = http.address();
             resolve({
                 port: address.port,
                 address: address.address,
                 processes,
+                authorizations,
                 broadcast(event, data) {
                     for (const conn of connections.values())
                         if (conn.paired)
@@ -345,6 +388,8 @@ export function startBridgeServer(options) {
                 close() {
                     clearInterval(heartbeat);
                     rejectLog.stop();
+                    // 先于关闭连接：标记取消，被杀掉的授权命令不会被当成「失败」再去重跑预检
+                    authorizations.killAllNow();
                     for (const conn of connections.values())
                         conn.ws.close(BRIDGE_CLOSE_CODES.goingAway, 'bridge is shutting down');
                     processes.stopAll();

package/dist/bridge/service.js

@@ -1,19 +1,29 @@
 /**
- * 页面方法背后的 agent 操作：列表、准备适配器、预检、写 m2 配置、生成启动规格。server.ts 只做协议，这里只做业务。
+ * 页面方法背后的 agent 操作：列表、准备适配器、预检、写 m2 配置、生成启动规格与授权命令计划。server.ts 只做协议，这里只做业务。
  *
  * 前置条件统一在这里检查，错误以 BridgeFailure（带协议错误码）抛出：
- * - 未安装 → agent_not_installed（安装命令与文档链接由前端提供，bridge 不代装）；
+ * - 拉不起来 → agent_not_installed（安装命令与文档链接由前端提供，bridge 不代装）。claude / codex 用适配器自带的程序，
+ *   本机没装命令行也能拉起（D11：`available` 恒为 true；`installed` 仍只表示本机检测到了命令行）；
  * - 适配器类 agent 未就绪 → adapter_not_ready（页面要先调 agent/prepare）。
  *
  * m2/configure 以子进程运行本包自己的 cli.js `--client <id> --yes`：stdin 不是 TTY，cli.js 走现有的非交互分支
  * （只写配置、不跑登录、退出码 0 = 全部写入或已存在）。这样一字不改 clients.ts，也不让它的 spawnSync 卡住转发。
- * 改 cli.js 非交互分支的行为时要同步检查这里。
+ * 改 cli.js 非交互分支的行为时要同步检查这里。clients.ts 只认 PATH 上跑得起来的 claude / codex，所以对这两家把自带程序所在目录
+ * 和 bridge 自己的 node 排到 PATH 最前（D10），本机没装命令行也能写配置。
+ *
+ * 授权（change acp-terminal-free-auth）：authorizePlan 按写死清单生成命令（authorize.ts），m2 的配置项名只取 bridge 自己的 m2 预检：
+ * 优先用最近一次预检 / 写配置时得到的名字（D19，页面先预检才会显示按钮，省掉一次重跑 —— Claude 的 `mcp list` 实测约 5 秒），没有记录时重跑；
+ * 预检 / 写配置的结果按同一判据带上 `authorize` 能力，页面只在能力存在时才调用 agent/authorize。
  */
+import { dirname, join } from 'node:path';
 import { ADAPTERS, isAdapterAgent } from './adapters.js';
+import { BridgeFailure } from './errors.js';
 import { LAUNCH_KIND, NATIVE_ACP_ARGS } from './agents.js';
+import { authCapability, buildAuthPlan, isSafeAuthEntry } from './authorize.js';
+import { prependPath } from './env.js';
 import { combinedOutput } from './exec.js';
 import { precheckAgent, precheckM2 } from './precheck.js';
-import { BRIDGE_AGENT_IDS } from './protocol.js';
+import { BRIDGE_AGENT_IDS, } from './protocol.js';
 export const CONFIGURE_TIMEOUT_MS = 120_000;
 /**
  * Claude 适配器（claude-agent-acp@0.84.0）声明 `node >=22`，实测在 Node 20 上可用（ACP PoC 与本 change 的端到端都是 Node 20）；
@@ -21,15 +31,7 @@ export const CONFIGURE_TIMEOUT_MS = 120_000;
  */
 export const MIN_NODE_MAJOR_FOR_CLAUDE = 20;
 const CONFIGURE_OUTPUT_LIMIT = 4096;
-export class BridgeFailure extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.code = code;
-        this.data = data;
-    }
-}
+export { BridgeFailure };
 /** bridge 的 agent id → connect `--client` 的取值 */
 const CLIENT_ID = {
     claude: 'claude-code',
@@ -40,25 +42,74 @@ const CLIENT_ID = {
 };
 export function createAgentService(deps) {
     const precheckDeps = { ...deps, env: deps.probeEnv };
-    async function installed(agent) {
+    /**
+     * 最近一次 m2 预检得到的配置项名（D19）。只由 bridge 自己的预检写入，页面仍不能指定（契约 3）；
+     * 最近一次没有名字（未配置、读不出）就清掉，授权时重跑。名字过期（预检到点击之间用户改了配置）时，授权命令失败并带输出（再点一次即可：命令结束后的预检已经刷新了记录），
+     * 或者针对同名的新配置项（用户在授权页上看得到授权对象）。Claude / Codex / Cursor 实测名字不存在时退出码 1；OpenCode 不是，所以它不用记录（见下）。
+     */
+    const m2Entries = new Map();
+    /**
+     * 授权前总是重新检查、不用记录的 agent（D21）。OpenCode 的 m2 授权先 `mcp logout <entry>`：名字过期时可能删掉同名的别的服务器的凭证；
+     * 而且名字不存在时 `mcp logout` / `mcp auth` 都以退出码 0 结束（实测 1.18.5），bridge 会判成成功。多 2–4 秒，换来名字一定是当下的。
+     */
+    const alwaysRecheck = new Set(['opencode']);
+    function remember(agent, m2) {
+        if (m2.state !== 'not_configured' && m2.entry)
+            m2Entries.set(agent, m2.entry);
+        else
+            m2Entries.delete(agent);
+        return m2;
+    }
+    /** 能拉起（D11）：claude / codex 用适配器自带的程序，不要求本机命令行；其余三家要本机装了 */
+    async function available(agent) {
         const detected = await deps.detect(agent);
-        if (!detected.installed)
+        if (!isAdapterAgent(agent) && !detected.installed)
             throw new BridgeFailure('agent_not_installed', `${agent} is not installed on this machine`);
         return detected;
     }
     async function ready(agent) {
-        const detected = await installed(agent);
+        const detected = await available(agent);
         if (isAdapterAgent(agent) && !deps.adapters.isReady(agent)) {
             throw new BridgeFailure('adapter_not_ready', `call agent/prepare for ${agent} first`, { adapter: deps.adapters.info(agent) });
         }
         return detected;
     }
+    const capability = (agent, action) => authCapability(agent, action, {
+        platform: deps.platform,
+        expectAvailable: deps.expectAvailable(),
+        claudeBinary: agent === 'claude' ? deps.adapters.claudeBinary() : null,
+    });
+    /** 预检 / 写配置结果带上「能不能代跑」：与 authorizePlan 用同一判据（含 m2 配置项名的校验），页面看到按钮就一定能调用 */
+    function withCapability(check, agent, action) {
+        const authorize = capability(agent, action);
+        const entry = 'entry' in check ? check.entry : null;
+        if (!authorize || (entry !== null && !isSafeAuthEntry(entry)))
+            return check;
+        return { ...check, authorize };
+    }
+    const withCapabilities = (result) => ({
+        ...result,
+        login: withCapability(result.login, result.agent, 'login'),
+        m2: withCapability(result.m2, result.agent, 'm2'),
+    });
+    /** D10：clients.ts 只认 PATH 上能跑起来的 claude / codex */
+    function configureEnv(agent) {
+        const node = dirname(deps.nodePath);
+        if (agent === 'claude') {
+            const claude = deps.adapters.claudeBinary();
+            return prependPath(deps.probeEnv, claude ? [dirname(claude), node] : [node], deps.platform);
+        }
+        if (agent === 'codex')
+            return prependPath(deps.probeEnv, [join(deps.adapters.installDir('codex'), 'node_modules', '.bin'), node], deps.platform);
+        return deps.probeEnv;
+    }
     return {
         async list() {
             const detected = await Promise.all(BRIDGE_AGENT_IDS.map((id) => deps.detect(id)));
             return detected.map((agent) => ({
                 id: agent.id,
                 installed: agent.installed,
+                available: isAdapterAgent(agent.id) || agent.installed,
                 path: agent.path,
                 version: agent.version,
                 launch: LAUNCH_KIND[agent.id],
@@ -66,7 +117,7 @@ export function createAgentService(deps) {
             }));
         },
         async prepare(agent) {
-            await installed(agent);
+            await available(agent);
             if (!isAdapterAgent(agent))
                 return null;
             const major = Number(deps.nodeVersion.split('.')[0]);
@@ -80,12 +131,14 @@ export function createAgentService(deps) {
             return info;
         },
         async precheck(agent) {
-            return precheckAgent(await ready(agent), precheckDeps);
+            const result = await precheckAgent(await ready(agent), precheckDeps);
+            remember(agent, result.m2);
+            return withCapabilities(result);
         },
         async configure(agent) {
             const detected = await ready(agent);
             const result = await deps.exec(deps.nodePath, [deps.cliPath, '--client', CLIENT_ID[agent], '--yes'], {
-                env: deps.probeEnv,
+                env: configureEnv(agent),
                 cwd: deps.cwd,
                 timeoutMs: CONFIGURE_TIMEOUT_MS,
             });
@@ -93,7 +146,7 @@ export function createAgentService(deps) {
             return {
                 ok: result.code === 0,
                 output: output.length > CONFIGURE_OUTPUT_LIMIT ? output.slice(-CONFIGURE_OUTPUT_LIMIT) : output,
-                m2: await precheckM2(detected, precheckDeps),
+                m2: withCapability(remember(agent, await precheckM2(detected, precheckDeps)), agent, 'm2'),
             };
         },
         async launch(agent) {
@@ -105,5 +158,35 @@ export function createAgentService(deps) {
                 throw new BridgeFailure('internal', `no executable path for ${agent}`);
             return { command: detected.path, args: NATIVE_ACP_ARGS[agent] };
         },
+        async authorizePlan(agent, action) {
+            const verb = action === 'login' ? 'sign-in' : 'M2 authorization';
+            if (deps.platform !== 'darwin')
+                throw new BridgeFailure('auth_unavailable', `the bridge only runs ${verb} on macOS; use the terminal command instead`);
+            const detected = await ready(agent);
+            if (!capability(agent, action))
+                throw new BridgeFailure('auth_unavailable', `the bridge cannot run ${verb} for ${agent}; use the terminal command instead`);
+            let entry = null;
+            if (action === 'm2') {
+                // 配置项名不一定叫 m2，也不能由页面指定：用 bridge 最近一次预检的结果，没有就重跑（D19）；OpenCode 总是重跑（D21）
+                const rechecked = alwaysRecheck.has(agent) || !m2Entries.has(agent) ? remember(agent, await precheckM2(detected, precheckDeps)) : null;
+                entry = m2Entries.get(agent) ?? null;
+                if (!entry) {
+                    // 读不出（unknown）不等于没配置：不能叫已经配置了 M2 的用户「先添加」（review r5 R5-N5）
+                    const why = rechecked?.state === 'unknown' ? `couldn't read ${agent}'s MCP config; check again, or use the terminal command` : `add M2 to ${agent}'s MCP config first (m2/configure)`;
+                    throw new BridgeFailure('auth_unavailable', why);
+                }
+            }
+            return buildAuthPlan({
+                agent,
+                action,
+                detected,
+                entry,
+                cwd: deps.cwd,
+                env: deps.probeEnv,
+                nodePath: deps.nodePath,
+                claudeBinary: agent === 'claude' ? deps.adapters.claudeBinary() : null,
+                codexDir: deps.adapters.installDir('codex'),
+            });
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Connect your local agent clients (Claude Code, Codex, Cursor, OpenCode, Qoder) to M2 Canvas over MCP in one command, and run the local bridge that lets M2 drive them over ACP.",
   "type": "module",
   "bin": {