@m2canvas/connect 0.3.1 → 0.5.0

package/dist/bridge/server.js

@@ -0,0 +1,379 @@
+/**
+ * 本机 ACP bridge 的 HTTP + WebSocket 服务：连接准入、握手、配对、方法分派、ACP 转发（页面 → agent 先经 acp-guard.ts 检查，agent → 页面原样）、心跳与清理。
+ * 协议规范见 protocol.ts 文件头指向的 design「页面协议」一节。
+ *
+ * 安全模型（改动前先读 security.ts / pairing.ts / acp-guard.ts 的文件头）：
+ * **配对 = 授权该页面以用户的身份驱动本机 agent**，包括让 agent 读写文件、执行命令（提示词、替用户回答审批、切换工作模式
+ * 都由页面发出）。所以安全的重心在「谁能配对」，配对之后能做的事只做纵深防御：
+ * - 只监听 127.0.0.1；upgrade 校验（对端、Host、Origin、路径）在完成握手之前，失败直接写 HTTP 状态并销毁 socket。
+ * - 握手后第一条消息必须是 hello；未配对的连接只能调用 pair，其余已知方法与 acp 帧一律 not_paired。
+ *   连接只有两种方式成为已配对：hello 带有效 token，或 hello 的 pairSecret 与启动命令的承诺一致（pairing.ts 文件头）。
+ * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
+ * - 页面发给 agent 的 ACP 行禁止含换行，并经 acp-guard.ts 检查：只能用白名单里的方法、会话目录固定为 bridge 的 cwd、不能让 agent 额外拉起 MCP 服务器。
+ *
+ * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责），不替用户登录。
+ */
+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 { checkPageAcpLine } from './acp-guard.js';
+import { checkUpgrade } from './security.js';
+import { BridgeFailure } from './service.js';
+export const HELLO_TIMEOUT_MS = 10_000;
+export const UNPAIRED_TIMEOUT_MS = 10 * 60 * 1000;
+export const MAX_UNPAIRED_CONNECTIONS = 4;
+export const PING_INTERVAL_MS = 30_000;
+export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+export const REJECT_LOG_WINDOW_MS = 60_000;
+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);
+}
+function rejectUpgrade(socket, status) {
+    const text = status === 403 ? 'Forbidden' : 'Not Found';
+    socket.end(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+    socket.destroy();
+}
+export function startBridgeServer(options) {
+    const timing = {
+        helloTimeoutMs: options.timing?.helloTimeoutMs ?? HELLO_TIMEOUT_MS,
+        unpairedTimeoutMs: options.timing?.unpairedTimeoutMs ?? UNPAIRED_TIMEOUT_MS,
+        pingIntervalMs: options.timing?.pingIntervalMs ?? PING_INTERVAL_MS,
+    };
+    const connections = new Map();
+    const log = options.log;
+    const send = (conn, frame) => {
+        if (conn.ws.readyState === conn.ws.OPEN)
+            conn.ws.send(JSON.stringify(frame));
+    };
+    const sendError = (conn, id, error) => send(conn, { type: 'error', id, error });
+    const processes = new ProcessManager({
+        env: options.agentEnv,
+        cwd: options.cwd,
+        killGraceMs: options.timing?.killGraceMs,
+        maxPerOwner: options.limits?.maxPerOwner,
+        maxTotal: options.limits?.maxTotal,
+        maxLineChars: options.limits?.maxLineChars,
+        // 每个进程只属于拉起它的连接，只投递给它
+        onLine: (ownerId, processId, line) => {
+            const conn = connections.get(ownerId);
+            if (conn)
+                send(conn, { type: 'acp', processId, line });
+        },
+        onExit: (ownerId, info) => {
+            const conn = connections.get(ownerId);
+            log(`${info.agent} exited (${info.reason}${info.code !== null ? `, code ${info.code}` : ''}${info.signal ? `, ${info.signal}` : ''})`);
+            if (conn)
+                send(conn, { type: 'event', event: 'process/exited', data: info });
+        },
+        onStderr: options.verbose ? (_id, agent, text) => process.stderr.write(`[${agent}] ${text}`) : undefined,
+    });
+    const unpairedCount = () => [...connections.values()].filter((conn) => !conn.paired).length;
+    const markPaired = (conn) => {
+        conn.paired = true;
+        if (conn.timer)
+            clearTimeout(conn.timer);
+        conn.timer = null;
+    };
+    async function handleCall(conn, id, method, params) {
+        if (method === 'pair') {
+            const code = params.code;
+            if (typeof code !== 'string')
+                throw new BridgeFailure('bad_message', 'pair needs a string "code"');
+            const result = options.pairing.pair(code, conn.origin);
+            if (!result.ok) {
+                if (result.code === 'pairing_invalid')
+                    throw new BridgeFailure('pairing_invalid', 'wrong pairing code', { attemptsLeft: result.attemptsLeft });
+                if (result.code === 'pairing_locked')
+                    throw new BridgeFailure('pairing_locked', 'too many wrong pairing codes; new pages cannot pair until the bridge is restarted');
+                throw new BridgeFailure('pairing_code_rotated', 'pairing code expired or used up; a new one is shown in the terminal');
+            }
+            markPaired(conn);
+            log(`Paired with ${conn.origin}.`);
+            return { token: result.token, cwd: options.cwd, idleExpiryDays: TOKEN_IDLE_DAYS };
+        }
+        if (!conn.paired)
+            throw new BridgeFailure('not_paired', 'pair this page first');
+        if (method === 'process/stop') {
+            const processId = params.processId;
+            if (typeof processId !== 'string' || !processes.stop(conn.id, processId))
+                throw new BridgeFailure('process_not_found', 'no such process on this connection');
+            return {};
+        }
+        if (method === 'agents/list')
+            return { agents: await options.service.list() };
+        const agent = params.agent;
+        if (!isAgentId(agent))
+            throw new BridgeFailure('unknown_agent', `unknown agent ${String(agent)}`);
+        switch (method) {
+            case 'agent/prepare':
+                return { agent, adapter: await options.service.prepare(agent) };
+            case 'agent/precheck':
+                return options.service.precheck(agent);
+            case 'm2/configure':
+                log(`Page asked to add M2 to ${agent}'s MCP config.`);
+                return { agent, ...(await options.service.configure(agent)) };
+            case 'process/start': {
+                const launch = await options.service.launch(agent);
+                try {
+                    const processId = await processes.start(conn.id, agent, launch);
+                    // 启动期间页面已断开：没有人会再停它，立刻清理
+                    if (!connections.has(conn.id))
+                        processes.stopOwner(conn.id);
+                    log(`Started ${agent}.`);
+                    return { processId, agent, cwd: options.cwd };
+                }
+                catch (error) {
+                    if (error instanceof ProcessError)
+                        throw new BridgeFailure(error.code, error.message);
+                    throw error;
+                }
+            }
+        }
+        // 未知方法在调用前已被 isMethod 拦下；走到这里说明 BRIDGE_METHODS 与上面的分支不一致
+        throw new BridgeFailure('internal', `unhandled method ${method} (call ${id})`);
+    }
+    function onHello(conn, frame) {
+        const protocols = Array.isArray(frame.protocols) ? frame.protocols.filter((value) => typeof value === 'number') : [];
+        if (frame.type !== 'hello' || protocols.length === 0) {
+            conn.ws.close(BRIDGE_CLOSE_CODES.badHandshake, 'expected hello');
+            return;
+        }
+        const common = protocols.filter((value) => BRIDGE_SUPPORTED_PROTOCOLS.includes(value));
+        if (common.length === 0) {
+            sendError(conn, null, { code: 'protocol_unsupported', message: 'no common protocol version', data: { supported: [...BRIDGE_SUPPORTED_PROTOCOLS] } });
+            conn.ws.close(BRIDGE_CLOSE_CODES.protocolUnsupported, 'protocol unsupported');
+            return;
+        }
+        // conn.hello 等 welcome 发出前一刻才置位：中间任何一步抛异常时，消息监听器的 catch 看到「还在握手」，
+        // 以 1011 关闭连接，而不是留下一个收不到 welcome、计时器又已清掉的挂起连接
+        if (conn.timer)
+            clearTimeout(conn.timer);
+        conn.timer = null;
+        const token = typeof frame.token === 'string' ? frame.token : undefined;
+        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);
+        }
+        else {
+            if (unpairedCount() > MAX_UNPAIRED_CONNECTIONS) {
+                conn.ws.close(BRIDGE_CLOSE_CODES.tooManyUnpaired, 'too many unpaired pages');
+                return;
+            }
+            options.pairing.ensureCode(conn.origin);
+            conn.timer = setTimeout(() => conn.ws.close(BRIDGE_CLOSE_CODES.timeout, 'pairing timed out'), timing.unpairedTimeoutMs);
+        }
+        const client = isObject(frame.client) && typeof frame.client.name === 'string' ? ` (${frame.client.name})` : '';
+        if (options.verbose)
+            log(`Page connected from ${conn.origin}${client}, ${paired ? 'paired' : 'not paired'}.`);
+        conn.hello = true;
+        send(conn, {
+            type: 'welcome',
+            protocol: Math.max(...common),
+            bridge: options.bridge,
+            paired,
+            tokenRejected: token !== undefined && !paired,
+            cwd: paired ? options.cwd : null,
+            ...(issuedToken ? { token: issuedToken } : {}),
+        });
+    }
+    function onFrame(conn, data, isBinary) {
+        if (isBinary) {
+            conn.ws.close(BRIDGE_CLOSE_CODES.unsupportedData, 'text frames only');
+            return;
+        }
+        let frame;
+        try {
+            frame = JSON.parse(data.toString());
+        }
+        catch {
+            frame = null;
+        }
+        if (!conn.hello) {
+            if (isObject(frame))
+                onHello(conn, frame);
+            else
+                conn.ws.close(BRIDGE_CLOSE_CODES.badHandshake, 'expected hello');
+            return;
+        }
+        if (!isObject(frame)) {
+            sendError(conn, null, { code: 'bad_message', message: 'frame must be a JSON object' });
+            return;
+        }
+        if (frame.type === 'acp') {
+            if (!conn.paired)
+                return sendError(conn, null, { code: 'not_paired', message: 'pair this page first' });
+            const { processId, line } = frame;
+            if (typeof processId !== 'string' || typeof line !== 'string' || /[\r\n]/.test(line)) {
+                return sendError(conn, null, { code: 'bad_message', message: 'acp frame needs processId and a single-line "line"' });
+            }
+            const guard = checkPageAcpLine(line, options.cwd);
+            if (!guard.ok) {
+                // 不转发：页面那个 JSON-RPC 请求不会得到 agent 的回应，页面按 data.rpcId 自己结束它
+                return sendError(conn, null, { code: 'acp_rejected', message: guard.reason, data: { processId, method: guard.method, rpcId: guard.rpcId } });
+            }
+            if (!processes.write(conn.id, processId, line))
+                sendError(conn, null, { code: 'process_not_found', message: 'no such process on this connection', data: { processId } });
+            return;
+        }
+        if (frame.type === 'call') {
+            const { id, method } = frame;
+            if (typeof id !== 'string' || id.length === 0 || id.length > MAX_CALL_ID) {
+                return sendError(conn, null, { code: 'bad_message', message: 'call needs a string id (≤ 64 chars)' });
+            }
+            if (!isMethod(method))
+                return sendError(conn, id, { code: 'unknown_method', message: `unknown method ${String(method)}` });
+            const params = isObject(frame.params) ? frame.params : {};
+            handleCall(conn, id, method, params).then((result) => send(conn, { type: 'result', id, result }), (error) => {
+                if (error instanceof BridgeFailure)
+                    sendError(conn, id, { code: error.code, message: error.message, ...(error.data === undefined ? {} : { data: error.data }) });
+                else {
+                    log(`Internal error in ${method}: ${error instanceof Error ? error.message : String(error)}`);
+                    sendError(conn, id, { code: 'internal', message: error instanceof Error ? error.message : String(error) });
+                }
+            });
+            return;
+        }
+        sendError(conn, null, { code: 'bad_message', message: `unknown frame type ${String(frame.type)}` });
+    }
+    const http = createServer((_req, res) => {
+        res.writeHead(426, { 'Content-Type': 'text/plain', Connection: 'close' });
+        res.end('M2 local agent bridge: WebSocket only.\n');
+    });
+    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES });
+    http.on('upgrade', (req, socket, head) => {
+        const port = http.address()?.port ?? options.port;
+        const decision = checkUpgrade({ origin: req.headers.origin, host: req.headers.host, remoteAddress: req.socket.remoteAddress, path: req.url }, port, options.allowedOrigins);
+        if (!decision.ok) {
+            rejectLog.note(decision.reason);
+            rejectUpgrade(socket, decision.status);
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            const conn = { id: randomUUID(), ws, origin: req.headers.origin, hello: false, paired: false, alive: true, timer: null };
+            connections.set(conn.id, conn);
+            conn.timer = setTimeout(() => ws.close(BRIDGE_CLOSE_CODES.timeout, 'hello timed out'), timing.helloTimeoutMs);
+            ws.on('pong', () => {
+                conn.alive = true;
+            });
+            ws.on('message', (data, isBinary) => {
+                // 任何同步异常都不能逃出监听器：未捕获异常会让 bridge 退出，exit 钩子会杀掉所有页面的 agent
+                try {
+                    onFrame(conn, data, isBinary);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    log(`Internal error while handling a message from ${conn.origin}: ${message}`);
+                    if (conn.hello)
+                        sendError(conn, null, { code: 'internal', message });
+                    else
+                        ws.close(BRIDGE_CLOSE_CODES.internalError, 'internal error');
+                }
+            });
+            ws.on('close', () => {
+                if (conn.timer)
+                    clearTimeout(conn.timer);
+                connections.delete(conn.id);
+                processes.stopOwner(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;
+    const rejectLog = (() => {
+        const suppressed = new Map();
+        const flush = () => {
+            for (const [reason, count] of suppressed) {
+                if (count > 0)
+                    log(`…and ${count} more connection${count === 1 ? '' : 's'} refused for the same reason (${reason}) in the last ${Math.round(rejectWindowMs / 1000)}s.`);
+            }
+            suppressed.clear();
+        };
+        const timer = setInterval(flush, rejectWindowMs);
+        timer.unref();
+        return {
+            note(reason) {
+                const count = suppressed.get(reason);
+                if (count === undefined) {
+                    log(`Rejected a connection: ${reason}.`);
+                    suppressed.set(reason, 0);
+                }
+                else
+                    suppressed.set(reason, count + 1);
+            },
+            stop() {
+                clearInterval(timer);
+                flush();
+            },
+        };
+    })();
+    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);
+        http.listen(options.port, '127.0.0.1', () => {
+            http.off('error', reject);
+            const address = http.address();
+            resolve({
+                port: address.port,
+                address: address.address,
+                processes,
+                broadcast(event, data) {
+                    for (const conn of connections.values())
+                        if (conn.paired)
+                            send(conn, { type: 'event', event, data });
+                },
+                close() {
+                    clearInterval(heartbeat);
+                    rejectLog.stop();
+                    for (const conn of connections.values())
+                        conn.ws.close(BRIDGE_CLOSE_CODES.goingAway, 'bridge is shutting down');
+                    processes.stopAll();
+                    return new Promise((done) => {
+                        wss.close();
+                        http.close(() => done());
+                        // 已建立的 WebSocket 不会因为 http.close 结束，给它们一点时间收到关闭帧后强制断开
+                        setTimeout(() => {
+                            for (const client of wss.clients)
+                                client.terminate();
+                            http.closeAllConnections();
+                        }, 500).unref();
+                    });
+                },
+            });
+        });
+    });
+}

package/dist/bridge/service.js

@@ -0,0 +1,109 @@
+/**
+ * 页面方法背后的 agent 操作：列表、准备适配器、预检、写 m2 配置、生成启动规格。server.ts 只做协议，这里只做业务。
+ *
+ * 前置条件统一在这里检查，错误以 BridgeFailure（带协议错误码）抛出：
+ * - 未安装 → agent_not_installed（安装命令与文档链接由前端提供，bridge 不代装）；
+ * - 适配器类 agent 未就绪 → adapter_not_ready（页面要先调 agent/prepare）。
+ *
+ * m2/configure 以子进程运行本包自己的 cli.js `--client <id> --yes`：stdin 不是 TTY，cli.js 走现有的非交互分支
+ * （只写配置、不跑登录、退出码 0 = 全部写入或已存在）。这样一字不改 clients.ts，也不让它的 spawnSync 卡住转发。
+ * 改 cli.js 非交互分支的行为时要同步检查这里。
+ */
+import { ADAPTERS, isAdapterAgent } from './adapters.js';
+import { LAUNCH_KIND, NATIVE_ACP_ARGS } from './agents.js';
+import { combinedOutput } from './exec.js';
+import { precheckAgent, precheckM2 } from './precheck.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）；
+ * 更低的版本没有验证过。connect 本身的 engines 是 >=18，所以在这里明确拦下，而不是拉起后崩溃。
+ */
+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;
+    }
+}
+/** bridge 的 agent id → connect `--client` 的取值 */
+const CLIENT_ID = {
+    claude: 'claude-code',
+    codex: 'codex',
+    cursor: 'cursor',
+    opencode: 'opencode',
+    qoder: 'qoder',
+};
+export function createAgentService(deps) {
+    const precheckDeps = { ...deps, env: deps.probeEnv };
+    async function installed(agent) {
+        const detected = await deps.detect(agent);
+        if (!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);
+        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;
+    }
+    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,
+                path: agent.path,
+                version: agent.version,
+                launch: LAUNCH_KIND[agent.id],
+                adapter: isAdapterAgent(agent.id) ? deps.adapters.info(agent.id) : null,
+            }));
+        },
+        async prepare(agent) {
+            await installed(agent);
+            if (!isAdapterAgent(agent))
+                return null;
+            const major = Number(deps.nodeVersion.split('.')[0]);
+            if (agent === 'claude' && major < MIN_NODE_MAJOR_FOR_CLAUDE) {
+                throw new BridgeFailure('adapter_install_failed', `the Claude adapter needs Node.js ${MIN_NODE_MAJOR_FOR_CLAUDE} or newer; this bridge runs on Node.js ${deps.nodeVersion}`, { adapter: { ...deps.adapters.info(agent), state: 'failed', error: `Node.js ${deps.nodeVersion} is too old` } });
+            }
+            const info = await deps.adapters.prepare(agent);
+            if (info.state !== 'ready') {
+                throw new BridgeFailure('adapter_install_failed', `installing ${ADAPTERS[agent].package}@${ADAPTERS[agent].version} failed`, { adapter: info });
+            }
+            return info;
+        },
+        async precheck(agent) {
+            return precheckAgent(await ready(agent), precheckDeps);
+        },
+        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,
+                cwd: deps.cwd,
+                timeoutMs: CONFIGURE_TIMEOUT_MS,
+            });
+            const output = combinedOutput(result);
+            return {
+                ok: result.code === 0,
+                output: output.length > CONFIGURE_OUTPUT_LIMIT ? output.slice(-CONFIGURE_OUTPUT_LIMIT) : output,
+                m2: await precheckM2(detected, precheckDeps),
+            };
+        },
+        async launch(agent) {
+            const detected = await ready(agent);
+            if (isAdapterAgent(agent))
+                return { command: deps.nodePath, args: [deps.adapters.entryPath(agent)] };
+            // 已安装的原生 agent 必有 path（detectAgent 的约定），这里只为收窄类型
+            if (!detected.path)
+                throw new BridgeFailure('internal', `no executable path for ${agent}`);
+            return { command: detected.path, args: NATIVE_ACP_ARGS[agent] };
+        },
+    };
+}

package/dist/cli.js

@@ -12,6 +12,7 @@ import { CLIENTS, detectClients, isClientId } from './clients.js';
 import { run } from './system.js';
 const CLIENT_IDS = Object.keys(CLIENTS).join(', ');
 const HELP = `Usage: npx @m2canvas/connect [--client <id>] [--yes] [--dry-run]
+       npx @m2canvas/connect bridge [--help]
 
 Adds M2 Canvas (${M2_MCP_URL}) to every agent client found on this machine
 (Claude Code, Codex, Cursor, OpenCode, Qoder), then signs each one in.
@@ -23,7 +24,9 @@ sign-in steps.
   --client <id>  only set up this client (${CLIENT_IDS})
   -y, --yes      skip the confirmation prompt
   --dry-run      only show what would change
-  -h, --help     show this help`;
+  -h, --help     show this help
+
+  bridge         run the local agent bridge so M2 can use the agents on this machine`;
 async function confirm(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -151,7 +154,10 @@ function printExistingSignIn(plans, interactive) {
         console.log(`  - ${plan.label}: ${describePending(plan.signIn(interactive, plan.existing))}`);
     }
 }
-main().then((code) => process.exit(code), (error) => {
+// `bridge` 子命令（本机 ACP bridge）按需动态加载：默认流程（Copy to agent 起手式）不加载它的代码和依赖。
+// 必须是子命令而不是另一个 bin —— npx 遇到多个 bin 只运行与包名同名的，加 bin 会让 `npx @m2canvas/connect` 失效。
+const entry = process.argv[2] === 'bridge' ? import('./bridge/main.js').then((bridge) => bridge.runBridge(process.argv.slice(3))) : main();
+entry.then((code) => process.exit(code), (error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exit(1);
 });

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.3.1",
-  "description": "Connect your local agent clients (Claude Code, Codex, Cursor, OpenCode, Qoder) to M2 Canvas over MCP in one command.",
+  "version": "0.5.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": {
     "m2canvas-connect": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "adapters"
   ],
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "ws": "8.22.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"