@m2canvas/connect 0.5.0 → 0.6.0

package/README.md

@@ -36,11 +36,12 @@ Lets M2 (in Chrome or another Chromium browser) start and talk to the agents on
 
 - **Local only.** It listens on `127.0.0.1:47821` and only accepts pages from `https://m2ui.ai`. Other sites, other machines and other hosts are refused before a connection is made. (`--dev` also accepts a local M2 dev server on port 5173; any app you serve on that port could then ask to pair, so only use it while developing M2.)
 - **Pairing gives the page your agents.** A paired page can make these agents read and change files and run commands as you, the same as typing into them yourself. Only run commands you copied from M2, and only enter the code into M2.
-- **Pairing.** When you start the bridge with the command M2 gives you, the page that gave it pairs automatically within 10 minutes. The command only carries a hash (`--pair`); the secret it matches stays in that browser tab, so the command is safe to appear in your shell history, and it works once. Any other page asks for the pairing code printed in this window; the window also shows which site is asking. After that the page remembers the pairing for 30 days of inactivity. After too many wrong codes, new pages can't pair until you restart the bridge (pages already paired keep working); close the page the window names first. `bridge --unpair` forgets all paired pages.
-- **Your own logins.** Agents use their own sign-in and their own M2 MCP setup; the bridge never signs in for you. It starts agents with a minimal environment, so variables set by a host app (for example `ANTHROPIC_BASE_URL` inside Claude Code) don't leak into them.
-- **Claude and Codex** run through pinned versions of the official adapters (`@agentclientprotocol/claude-agent-acp@0.84.0`, `@agentclientprotocol/codex-acp@2.1.0`). They are installed on first use into `~/.m2canvas/acp-adapters/` from the lockfiles in this package (a few hundred MB each, because they bundle the agent). Codex then needs its own M2 sign-in once, with the bundled `codex`; M2 shows the exact command.
+- **Pairing.** When you start the bridge with the command M2 gives you, the page that gave it pairs automatically within 10 minutes. The command only carries a hash (`--pair`); the secret it matches stays in that browser tab, so the command is safe to appear in your shell history, and it works once. Any other page asks for the pairing code printed in this window; the window also shows which site is asking. After that the page remembers the pairing for 30 days of inactivity. After too many wrong codes, new pages can't pair until you restart the bridge (pages already paired keep working); close the page the window names first. `bridge --unpair` forgets all paired pages. If you can't find this window, run the command M2 shows under the code box: it adds `--replace`, which stops the M2 bridge already running on the port (its agent sessions end) and starts a new one that pairs by itself. It only stops a bridge (0.6.0 or later) it can recognize from a small state file in `~/.m2canvas` (process id and start time; no codes or tokens are written there), never anything else on the port, and not on Windows. When it can't recognize what holds the port, it shows you that process (or how to find it) and leaves it alone. With an older bridge, M2 shows the Ctrl+C instructions instead.
+- **Your own logins.** Agents use their own sign-in and their own M2 MCP setup. It starts agents with a minimal environment, so variables set by a host app (for example `ANTHROPIC_BASE_URL` inside Claude Code) don't leak into them.
+- **Signing in from M2 (macOS).** M2 can start an agent's own sign-in, or its M2 authorization, for you: the bridge runs that agent's own command from a fixed list in this package, and M2 opens the sign-in page in the browser you are using (Codex opens your default browser itself). You finish signing in there; nothing is entered for you. The page only picks the agent and whether to sign in or authorize M2, never the command. Covered: sign-in for Claude Code, Codex, Cursor and Qoder; M2 authorization for Claude Code, Codex, Cursor and OpenCode (Qoder's M2 authorization is only available inside Qoder). Claude Code's M2 authorization needs a terminal, so the bridge provides one with macOS's built-in `/usr/bin/expect`. A sign-in can be canceled from M2, gives up after 10 minutes, and stops when the page disconnects or the bridge exits. On other systems M2 shows the command to run instead.
+- **Claude and Codex** run through pinned versions of the official adapters (`@agentclientprotocol/claude-agent-acp@0.84.0`, `@agentclientprotocol/codex-acp@2.1.0`). They are installed on first use into `~/.m2canvas/acp-adapters/` from the lockfiles in this package (about 270 MB and 350 MB, because they bundle the agent); M2 shows the download progress. You don't need Claude Code or Codex installed yourself: checking sign-in, adding M2 and signing in all use the bundled `claude` and `codex`, which read the same settings as your own installs.
 - Cursor runs as `agent acp`, OpenCode as `opencode acp`, Qoder as `qodercli --acp`.
 
 Agent sessions start in that directory.
 
-Options: `--port <n>`, `--cwd <dir>` (default: current directory), `--verbose` (also print agent stderr), `--dev` (also accept the local M2 dev server).
+Options: `--port <n>`, `--cwd <dir>` (default: current directory), `--verbose` (also print agent stderr), `--dev` (also accept the local M2 dev server), `--replace` (stop the M2 bridge already running on the port first).

package/dist/bridge/adapters.js

@@ -13,9 +13,12 @@
  * - `--ignore-scripts`：两条依赖链上没有安装脚本（实测），加上它能挡掉安装期执行代码。
  * - 安装目录名带 lockfile 哈希：换了 lockfile 就是新目录，旧目录不会被半新半旧地复用。旧目录目前不清理（FU-2026-10-02-120）。
  * - 先装到临时目录、写好就绪标记再原子改名；残留的临时目录或没有标记的目录一律视为未安装。
+ * - 升级 Claude 适配器时复核 bundledClaudePath 与 SDK 自身的解析规则是否仍一致（acp-terminal-free-auth evidence/sdk-binary-resolution.md），
+ *   并按新版本实测 installedBytes。
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { lstat, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { combinedOutput } from './exec.js';
 import { tail } from './precheck-parse.js';
@@ -25,18 +28,87 @@ export const ADAPTERS = {
         package: '@agentclientprotocol/claude-agent-acp',
         version: '0.84.0',
         entry: 'node_modules/@agentclientprotocol/claude-agent-acp/dist/index.js',
+        installedBytes: 268_451_230,
     },
     codex: {
         dir: 'codex-acp',
         package: '@agentclientprotocol/codex-acp',
         version: '2.1.0',
         entry: 'node_modules/@agentclientprotocol/codex-acp/dist/index.js',
+        installedBytes: 346_221_434,
     },
 };
 /** 适配器自带的 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';
+const PROGRESS_INTERVAL_MS = 1000;
+/**
+ * Linux 上没有 glibc（Alpine 等）时优先 musl 版本：与 claude-agent-sdk 自身的判断相同（process.report 的 glibcVersionRuntime）。
+ */
+function preferMusl() {
+    if (process.platform !== 'linux')
+        return false;
+    const report = typeof process.report?.getReport === 'function' ? process.report.getReport() : null;
+    return report !== null && report.header?.glibcVersionRuntime === undefined;
+}
+/**
+ * 适配器自带的 claude（D9）：会话真正用的是它，预检、写配置、授权也都用它，看到的才是同一份程序。
+ * 规则照搬 claude-agent-sdk 0.3.284 的解析（候选 `@anthropic-ai/claude-agent-sdk-<platform>-<arch>[-musl]/claude[.exe]`，
+ * 取第一个存在的）。找不到返回 null，调用方报 unknown —— **不得退回本机的 claude**，否则预检和会话用的是两个程序。
+ */
+export function bundledClaudePath(installDir, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const exists = options.exists ?? existsSync;
+    const musl = options.preferMusl ?? preferMusl();
+    const pkg = '@anthropic-ai/claude-agent-sdk';
+    const names = platform === 'android'
+        ? [`${pkg}-linux-${arch}-android`]
+        : platform === 'linux'
+            ? musl
+                ? [`${pkg}-linux-${arch}-musl`, `${pkg}-linux-${arch}`]
+                : [`${pkg}-linux-${arch}`, `${pkg}-linux-${arch}-musl`]
+            : [`${pkg}-${platform}-${arch}`];
+    const binary = platform === 'win32' ? 'claude.exe' : 'claude';
+    for (const name of names) {
+        const candidate = join(installDir, 'node_modules', ...name.split('/'), binary);
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** 已写入字节 / 预估体积 → 0–0.99（两位小数）；算不出时 undefined（页面退回转圈） */
+export function estimateProgress(bytes, expected) {
+    if (!Number.isFinite(bytes) || !Number.isFinite(expected) || expected <= 0)
+        return undefined;
+    return Math.min(0.99, Math.max(0, Math.floor((bytes / expected) * 100) / 100));
+}
+/** 目录里所有文件的字节数（不跟随符号链接）。npm 正在挪动文件，读不到的项直接跳过 */
+async function directoryBytes(dir) {
+    let total = 0;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            total += await directoryBytes(path);
+        else {
+            try {
+                total += (await lstat(path)).size;
+            }
+            catch {
+                // 刚被 npm 移走
+            }
+        }
+    }
+    return total;
+}
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -54,6 +126,7 @@ export class AdapterManager {
     options;
     installing = new Map();
     lastError = new Map();
+    progress = new Map();
     constructor(options) {
         this.options = options;
     }
@@ -71,13 +144,19 @@ export class AdapterManager {
         const dir = this.installDir(agent);
         return existsSync(join(dir, READY_MARKER)) && existsSync(join(dir, ADAPTERS[agent].entry));
     }
+    /** 适配器自带的 claude（D9）；适配器没就绪或找不到时为 null */
+    claudeBinary() {
+        return this.isReady('claude') ? bundledClaudePath(this.installDir('claude')) : null;
+    }
     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.installing.has(agent)) {
+            const progress = this.progress.get(agent);
+            return { ...base, state: 'installing', error: null, ...(progress === undefined ? {} : { progress }) };
+        }
         if (this.isReady(agent))
-            return { ...base, state: 'ready', error: null };
+            return { ...base, state: 'ready', error: null, progress: 1 };
         const error = this.lastError.get(agent);
         return error ? { ...base, state: 'failed', error } : { ...base, state: 'not_installed', error: null };
     }
@@ -91,6 +170,7 @@ export class AdapterManager {
         this.lastError.delete(agent);
         const job = this.install(agent).finally(() => {
             this.installing.delete(agent);
+            this.progress.delete(agent);
             this.options.onState?.(agent, this.info(agent));
         });
         this.installing.set(agent, job.then(() => this.info(agent)));
@@ -117,11 +197,13 @@ export class AdapterManager {
         const finalDir = this.installDir(agent);
         this.removeStaleTemps(spec);
         const tmpDir = join(this.options.installRoot, `.tmp-${spec.dir}-${process.pid}-${randomBytes(4).toString('hex')}`);
+        let stopProgress = () => undefined;
         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));
             }
+            stopProgress = this.trackProgress(agent, tmpDir);
             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))}`);
@@ -140,7 +222,40 @@ export class AdapterManager {
             this.lastError.set(agent, error instanceof Error ? error.message : String(error));
         }
         finally {
+            stopProgress();
             rmSync(tmpDir, { recursive: true, force: true });
         }
     }
+    /**
+     * npm ci 不报进度（D12）：每隔一段时间统计临时安装目录已写入的字节，除以预估体积得到近似进度，变化了才广播。
+     * 只读不写，统计失败当 0 处理；返回停止函数。
+     */
+    trackProgress(agent, dir) {
+        const expected = this.options.expectedBytes?.[agent] ?? ADAPTERS[agent].installedBytes;
+        let stopped = false;
+        let measuring = false;
+        const timer = setInterval(() => {
+            if (measuring)
+                return;
+            measuring = true;
+            void directoryBytes(dir)
+                .then((bytes) => {
+                const next = estimateProgress(bytes, expected);
+                if (stopped || next === undefined || next === this.progress.get(agent))
+                    return;
+                this.progress.set(agent, next);
+                this.options.onState?.(agent, this.info(agent));
+            })
+                // 广播失败（日志 / 连接写出出错）只影响这一次进度：不能变成未处理的 rejection 让 bridge 退出、杀掉所有 agent（契约 5）
+                .catch((error) => console.warn(`Could not report adapter install progress: ${error instanceof Error ? error.message : String(error)}`))
+                .finally(() => {
+                measuring = false;
+            });
+        }, this.options.progressIntervalMs ?? PROGRESS_INTERVAL_MS);
+        timer.unref();
+        return () => {
+            stopped = true;
+            clearInterval(timer);
+        };
+    }
 }

package/dist/bridge/agents.js

@@ -12,7 +12,12 @@
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { isExecutable, which } from '../system.js';
+import { BRIDGE_AGENT_IDS } from './protocol.js';
 export const VERSION_TIMEOUT_MS = 15_000;
+/** 页面传来的 agent id 只能是五家之一（server.ts 与 auth-call.ts 共用） */
+export function isBridgeAgentId(value) {
+    return typeof value === 'string' && BRIDGE_AGENT_IDS.includes(value);
+}
 /** claude / codex 经适配器拉起（不用检测到的本机二进制）；其余三家用自带的 ACP 模式 */
 export const LAUNCH_KIND = {
     claude: 'adapter',

package/dist/bridge/auth-call.js

@@ -0,0 +1,68 @@
+/**
+ * `agent/authorize` / `agent/authorize-cancel` 的分派（change acp-terminal-free-auth，design D2 / D7 / D16），从 server.ts 拆出。
+ *
+ * 安全边界（契约 3）：页面只能选 agent × 动作，params 只能恰好是规定的键，多一个（command、args、cwd、env、entry……）就 bad_message、
+ * 不静默忽略；命令计划由 service 按写死清单生成（authorize.ts）。授权链接只发给发起的连接；发起的连接关闭即取消（server.ts 的 close 监听器）。
+ * 终端日志说明页面让 bridge 做了什么与结果，**不打印链接**（带 state 等一次性参数）。
+ */
+import { isBridgeAgentId } from './agents.js';
+import { BridgeFailure } from './errors.js';
+import { BRIDGE_AUTH_ACTIONS } from './protocol.js';
+function isAuthAction(value) {
+    return typeof value === 'string' && BRIDGE_AUTH_ACTIONS.includes(value);
+}
+/** params 必须恰好是这些键（自有属性，`__proto__` 之类的也算多出来的键） */
+function hasExactKeys(params, keys) {
+    const own = Object.keys(params);
+    return own.length === keys.length && keys.every((key) => Object.hasOwn(params, key));
+}
+function describeOutcome(action, result) {
+    switch (result.outcome) {
+        case 'succeeded':
+            return action === 'login' ? 'signed in' : 'authorized';
+        case 'failed':
+            return result.exitCode === null ? 'failed' : `failed (exit ${result.exitCode})`;
+        case 'canceled':
+            return 'canceled';
+        case 'timed_out':
+            return 'timed out';
+    }
+}
+export async function handleAuthCall(ctx, ownerId, method, params) {
+    const keys = method === 'agent/authorize' ? ['agent', 'action'] : ['agent'];
+    if (!hasExactKeys(params, keys))
+        throw new BridgeFailure('bad_message', `${method} takes exactly: ${keys.join(', ')}`);
+    const agent = params.agent;
+    if (!isBridgeAgentId(agent))
+        throw new BridgeFailure('unknown_agent', `unknown agent ${String(agent)}`);
+    if (method === 'agent/authorize-cancel') {
+        if (!ctx.authorizations.cancel(ownerId, agent))
+            throw new BridgeFailure('auth_not_found', `no sign-in for ${agent} in progress on this connection`);
+        return {};
+    }
+    const action = params.action;
+    if (!isAuthAction(action))
+        throw new BridgeFailure('bad_message', `action must be one of ${BRIDGE_AUTH_ACTIONS.join(', ')}`);
+    const what = action === 'login' ? 'sign-in' : 'M2 authorization';
+    const pending = ctx.authorizations.run({
+        ownerId,
+        agent,
+        action,
+        plan: () => ctx.service.authorizePlan(agent, action),
+        precheck: () => ctx.service.precheck(agent),
+        onLink: (link) => ctx.sendLink(ownerId, { agent, action, url: link.url, open: link.open }),
+    });
+    // 占用在 run 的同步部分已登记；此时页面若已断开（极少见），没有人会再取消它
+    if (!ctx.isConnected(ownerId))
+        ctx.authorizations.cancelOwner(ownerId);
+    ctx.log(action === 'login' ? `Page asked to sign in to ${agent}.` : `Page asked to authorize M2 for ${agent}.`);
+    try {
+        const result = await pending;
+        ctx.log(`${agent} ${what}: ${describeOutcome(action, result)}.`);
+        return result;
+    }
+    catch (error) {
+        ctx.log(`${agent} ${what}: did not start (${error instanceof BridgeFailure ? error.code : 'internal'}).`);
+        throw error;
+    }
+}

package/dist/bridge/authorize.js

@@ -0,0 +1,341 @@
+/**
+ * bridge 代跑授权命令（change acp-terminal-free-auth）：账号登录与 m2 MCP 授权不再要求用户打开终端。
+ *
+ * 安全边界（`connect/local-bridge` 契约 3 / 8，design D2 / 安全分析）：
+ * - 页面只能选「哪个 agent × 哪个动作」。可执行文件、参数、环境、cwd 全部来自下面写死的 AUTH_COMMANDS 与 bridge 自己的检测；
+ *   m2 授权用的配置项名只取 bridge 自己的 m2 预检（调用方 service.ts 负责：优先用最近一次预检的结果，没有记录时拉起前重跑，D19），不接受页面传入。
+ * - 授权必须由用户在浏览器里亲自完成：bridge 只截下 CLI 要打开的授权页链接交给页面，从不替用户点任何东西。
+ *
+ * 链接怎么截（D4，各家行为实测见 evidence/auth-commands-macos.md）：
+ * - 每次授权新建 0700 的临时目录，放 `open` / `xdg-open` 替身并排在 PATH 最前；替身只把参数逐行追加到 `M2_AUTH_LINK_FILE`，
+ *   **从不执行参数、从不打开浏览器**。Claude / Cursor / OpenCode / Qoder 都经 PATH 上的 `open` 打开授权页。
+ * - Codex 的原生程序经 NSWorkspace 直接打开默认浏览器，截不到，但会把链接打印出来：从输出里取（`opens: 'agent'`，页面只作备用）。
+ * - 按每条命令的链接来源只取一种：Claude 打印在输出里的是「粘码」备用链接，回调不在本机，不能转交。
+ * - 只转交 https、≤ 8KB 的链接，同一条只转交一次；事件只发给发起授权的连接（server.ts）。
+ *
+ * 生命周期（D7）：同一个 agent 同一时间一次（跨连接）；拥有者是发起的连接，连接关闭即取消；10 分钟超时；
+ * 取消 / 超时 = 对进程组 SIGTERM，2 秒后仍在则 SIGKILL（OpenCode 收到 SIGTERM 约 20 秒不退出）。
+ * 命令经 exec.ts 的 startCommand 拉起，与一次性命令共用 active 集合，bridge 退出时一起清理；临时目录由 killAllNow 同步删除。
+ *
+ * Claude 的 m2 授权（D6）：`claude mcp login` 遇到非终端直接拒绝，用 macOS 自带的 /usr/bin/expect 提供伪终端。
+ * 脚本文本固定，参数经 Tcl 的 $argv 列表传给 `spawn {*}$argv`，不拼进脚本。expect 退出后伪终端关闭，claude 随之收到 SIGHUP 退出，
+ * 所以对 expect 的进程组发信号足以清理（evidence/pty-cleanup.md）。
+ *
+ * 结果以预检为准（D8）：命令结束后重跑预检随结果返回，outcome 只反映命令本身（退出码不可靠）。
+ */
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { CODEX_SCRIPT } from './adapters.js';
+import { prependPath } from './env.js';
+import { BridgeFailure } from './errors.js';
+import { combinedOutput, startCommand } from './exec.js';
+import { stripAnsi } from './precheck-parse.js';
+import { BRIDGE_MAX_AUTH_LINK_CHARS } from './protocol.js';
+export const AUTH_TIMEOUT_MS = 10 * 60 * 1000;
+export const AUTH_KILL_GRACE_MS = 2_000;
+export const AUTH_LINK_POLL_MS = 250;
+export const MAX_AUTH_LINK_CHARS = BRIDGE_MAX_AUTH_LINK_CHARS;
+export const AUTH_OUTPUT_LIMIT = 4096;
+/** 每条输出流保留的尾部（只为截链接与最终的 4KB 摘要，不需要更多） */
+const AUTH_STREAM_KEEP = 64 * 1024;
+export const EXPECT_PATH = '/usr/bin/expect';
+/**
+ * 写死的命令清单（design「命令清单」表）。不在这里的组合一律 auth_unavailable：
+ * OpenCode 的登录是交互菜单、预检也不要求登录；Qoder 的 m2 授权没有命令行与 ACP 入口。
+ */
+export const AUTH_COMMANDS = {
+    claude: { login: { opens: 'page', linkSource: 'open', pty: false }, m2: { opens: 'page', linkSource: 'open', pty: true } },
+    codex: { login: { opens: 'agent', linkSource: 'output', pty: false }, m2: { opens: 'agent', linkSource: 'output', pty: false } },
+    cursor: { login: { opens: 'page', linkSource: 'open', pty: false }, m2: { opens: 'page', linkSource: 'open', pty: false } },
+    opencode: { m2: { opens: 'page', linkSource: 'open', pty: false } },
+    qoder: { login: { opens: 'page', linkSource: 'open', pty: false } },
+};
+/**
+ * 预检结果里的 `authorize` 字段（D1、D5）：只在 macOS（实测平台）出现；Claude 要找得到自带的 claude，Claude 的 m2 还要有 expect。
+ * 页面只在这个字段存在时调用 agent/authorize，所以旧 bridge 与其他平台自动退回命令引导。
+ */
+export function authCapability(agent, action, env) {
+    const spec = AUTH_COMMANDS[agent]?.[action];
+    if (env.platform !== 'darwin' || !spec)
+        return null;
+    if (agent === 'claude' && !env.claudeBinary)
+        return null;
+    if (spec.pty && !env.expectAvailable)
+        return null;
+    return { opens: spec.opens };
+}
+const unavailable = (message) => new BridgeFailure('auth_unavailable', message);
+/**
+ * m2 配置项名会作为参数传给 CLI。它来自 bridge 自己的预检，但预检读的配置包括会话目录里的项目文件（Cursor 的
+ * `<cwd>/.cursor/mcp.json`、Claude 的 `.mcp.json`）—— 仓库可以把它命名成 `--xxx`，让页面一键触发时注入 CLI 选项（review r1 S-3）。
+ * 参数走 argv、不经过 shell，所以只挡选项与控制字符：不以 `-` 开头、不含控制字符、1–128 字符；空格、中文、引号照常传
+ * （误拒会让按钮无端消失，review r2 R2-S1）。预检的 `authorize` 能力用同一个函数判断，按钮出现就一定能执行。
+ */
+// eslint-disable-next-line no-control-regex
+const SAFE_ENTRY = /^(?!-)[^\u0000-\u001f\u007f]{1,128}$/u;
+export function isSafeAuthEntry(entry) {
+    return SAFE_ENTRY.test(entry);
+}
+/** 把 agent × 动作翻译成具体命令。调用方已确认平台、安装、适配器就绪与 expect；这里只按清单组装。 */
+export function buildAuthPlan(input) {
+    const { agent, action, entry } = input;
+    const spec = AUTH_COMMANDS[agent]?.[action];
+    if (!spec)
+        throw unavailable(`the bridge cannot run ${action === 'login' ? 'sign-in' : 'M2 authorization'} for ${agent}`);
+    if (action === 'm2' && !entry)
+        throw unavailable(`add M2 to ${agent}'s MCP config first (m2/configure)`);
+    if (action === 'm2' && entry && !isSafeAuthEntry(entry))
+        throw unavailable(`the M2 entry name ${JSON.stringify(entry)} can't be passed to ${agent} safely; use the terminal command instead`);
+    const m2Entry = entry ?? '';
+    const base = { agent, action, cwd: input.cwd, env: input.env, pty: spec.pty, linkSource: spec.linkSource, opens: spec.opens };
+    switch (agent) {
+        case 'claude': {
+            const claude = input.claudeBinary;
+            if (!claude)
+                throw unavailable('the Claude Code program bundled with the adapter was not found');
+            return { ...base, steps: [{ command: claude, args: action === 'login' ? ['auth', 'login'] : ['mcp', 'login', m2Entry] }], pathPrefix: [dirname(claude)] };
+        }
+        case 'codex': {
+            const script = join(input.codexDir, CODEX_SCRIPT);
+            const args = action === 'login' ? [script, 'login'] : [script, 'mcp', 'login', m2Entry];
+            return { ...base, steps: [{ command: input.nodePath, args }], pathPrefix: [join(input.codexDir, 'node_modules', '.bin'), dirname(input.nodePath)] };
+        }
+        default: {
+            const path = input.detected.path;
+            if (!path)
+                throw unavailable(`${agent} is not installed on this machine`);
+            // OpenCode 已授权时重跑 `mcp auth` 会停在交互确认（Re-authenticate?），无终端会卡住；先 logout（无交互）再 auth（D15）
+            const steps = agent === 'opencode'
+                ? [
+                    { command: path, args: ['mcp', 'logout', m2Entry], ignoreFailure: true },
+                    { command: path, args: ['mcp', 'auth', m2Entry] },
+                ]
+                : [{ command: path, args: action === 'login' ? ['login'] : ['mcp', 'login', m2Entry] }];
+            return { ...base, steps, pathPrefix: [] };
+        }
+    }
+}
+// ───────────────────────────── 链接 ─────────────────────────────
+/** 只收能解析的 https 链接、≤ 8KB；其余（http 本机回调、file:、命令行选项）返回 null */
+export function acceptAuthLink(candidate) {
+    const text = candidate.trim();
+    if (text.length === 0 || text.length > MAX_AUTH_LINK_CHARS)
+        return null;
+    try {
+        return new URL(text).protocol === 'https:' ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+// eslint-disable-next-line no-control-regex
+const OUTPUT_LINK_RE = /https:\/\/[^\s"'<>\u001b]+(?=[\s"'<>])/g;
+/**
+ * 从命令输出里取完整的 https 链接：必须后面跟着空白或引号，避免把还没输出完的半截链接转交出去。
+ * 调用方传入累计输出（去 ANSI 在这里做，转义序列可能跨两段输出）。
+ */
+export function linksInOutput(text) {
+    const found = [];
+    for (const match of stripAnsi(text).matchAll(OUTPUT_LINK_RE)) {
+        const link = acceptAuthLink(match[0]);
+        if (link && !found.includes(link))
+            found.push(link);
+    }
+    return found;
+}
+// ───────────────────────────── 运行 ─────────────────────────────
+/** 替身：只把参数逐行追加到 bridge 指定的文件。不执行参数、不打开浏览器（D4） */
+const OPEN_SHIM = `#!/bin/sh
+# M2 local agent bridge: records the sign-in link for the M2 page to open in your current browser. It never runs its arguments.
+for arg in "$@"; do
+  printf '%s\\n' "$arg" >> "$M2_AUTH_LINK_FILE"
+done
+exit 0
+`;
+/** 伪终端包装（D6）：文本固定，被包命令只经 $argv 传入 */
+const PTY_SCRIPT = `set timeout -1
+log_user 1
+spawn -noecho {*}$argv
+expect eof
+catch wait result
+exit [lindex $result 3]
+`;
+function outputTail(text) {
+    const clean = stripAnsi(text).replace(/\r/g, '');
+    return clean.length > AUTH_OUTPUT_LIMIT ? clean.slice(-AUTH_OUTPUT_LIMIT) : clean;
+}
+export function startAuthRun(plan, options) {
+    const dir = mkdtempSync(join(tmpdir(), 'm2-auth-'));
+    chmodSync(dir, 0o700);
+    let removed = false;
+    const removeDir = () => {
+        if (removed)
+            return;
+        removed = true;
+        rmSync(dir, { recursive: true, force: true });
+    };
+    let current = null;
+    let canceled = false;
+    let timedOut = false;
+    const seen = new Set();
+    const offer = (candidate) => {
+        const link = acceptAuthLink(candidate);
+        if (!link || seen.has(link))
+            return;
+        seen.add(link);
+        options.onLink(link);
+    };
+    let linkFile = '';
+    let script = '';
+    let env = plan.env;
+    try {
+        const bin = join(dir, 'bin');
+        mkdirSync(bin, { mode: 0o700 });
+        for (const name of ['open', 'xdg-open'])
+            writeFileSync(join(bin, name), OPEN_SHIM, { mode: 0o700 });
+        linkFile = join(dir, 'links');
+        writeFileSync(linkFile, '', { mode: 0o600 });
+        script = join(dir, 'pty.exp');
+        if (plan.pty)
+            writeFileSync(script, PTY_SCRIPT, { mode: 0o600 });
+        env = { ...prependPath(plan.env, [bin, ...plan.pathPrefix]), M2_AUTH_LINK_FILE: linkFile };
+    }
+    catch (error) {
+        removeDir();
+        throw error;
+    }
+    let linkLines = 0;
+    const readLinkFile = () => {
+        let text;
+        try {
+            text = readFileSync(linkFile, 'utf8');
+        }
+        catch {
+            return; // 临时目录已删（结束或 killNow）
+        }
+        // 最后一段可能是替身还没写完的半行
+        const lines = text.split('\n').slice(0, -1);
+        for (const line of lines.slice(linkLines))
+            offer(line);
+        linkLines = lines.length;
+    };
+    const poll = plan.linkSource === 'open' ? setInterval(readLinkFile, options.pollMs) : null;
+    poll?.unref();
+    let scanned = '';
+    const onOutput = plan.linkSource === 'output'
+        ? (chunk) => {
+            scanned = (scanned + chunk).slice(-2 * MAX_AUTH_LINK_CHARS);
+            for (const link of linksInOutput(scanned))
+                offer(link);
+        }
+        : undefined;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        current?.terminate(options.graceMs, 'timed out', true);
+    }, options.timeoutMs);
+    timer.unref();
+    const execute = async () => {
+        const outputs = [];
+        let last = null;
+        try {
+            for (const step of plan.steps) {
+                if (canceled || timedOut)
+                    break;
+                const command = plan.pty ? EXPECT_PATH : step.command;
+                const args = plan.pty ? ['-f', script, '--', step.command, ...step.args] : step.args;
+                current = startCommand(command, args, { env, cwd: plan.cwd, maxOutput: AUTH_STREAM_KEEP, onOutput });
+                last = await current.result;
+                current = null;
+                outputs.push(combinedOutput(last));
+                if (last.code !== 0 && !step.ignoreFailure)
+                    break;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            if (poll)
+                clearInterval(poll);
+            removeDir();
+        }
+        const outcome = canceled ? 'canceled' : timedOut ? 'timed_out' : last?.code === 0 ? 'succeeded' : 'failed';
+        return { outcome, exitCode: last?.code ?? null, output: outputTail(outputs.filter((part) => part.length > 0).join('\n')) };
+    };
+    return {
+        result: execute(),
+        cancel() {
+            if (canceled)
+                return;
+            canceled = true;
+            current?.terminate(options.graceMs, 'canceled');
+        },
+        killNow() {
+            canceled = true;
+            current?.kill('bridge is shutting down');
+            clearTimeout(timer);
+            if (poll)
+                clearInterval(poll);
+            removeDir();
+        },
+    };
+}
+export class AuthorizationManager {
+    options;
+    /** 按 agent 记：同一 agent 的两次授权会争同一个本机回调端口（Cursor 固定 8787）、写同一份凭证 */
+    entries = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async run(request) {
+        const { agent, action } = request;
+        if (this.entries.has(agent))
+            throw new BridgeFailure('auth_busy', `another sign-in for ${agent} is in progress`, { agent });
+        const entry = { ownerId: request.ownerId, canceled: false, run: null };
+        this.entries.set(agent, entry);
+        const canceledResult = { agent, action, outcome: 'canceled', exitCode: null, output: '', precheck: null };
+        let ran;
+        try {
+            const plan = await request.plan();
+            if (entry.canceled)
+                return canceledResult;
+            const start = this.options.start ?? startAuthRun;
+            entry.run = start(plan, {
+                timeoutMs: this.options.timeoutMs ?? AUTH_TIMEOUT_MS,
+                graceMs: this.options.graceMs ?? AUTH_KILL_GRACE_MS,
+                pollMs: this.options.pollMs ?? AUTH_LINK_POLL_MS,
+                onLink: (url) => request.onLink({ url, open: plan.opens }),
+            });
+            ran = await entry.run.result;
+        }
+        finally {
+            // 命令结束即释放：端口与凭证的争用已经结束，之后的预检不需要占着
+            if (this.entries.get(agent) === entry)
+                this.entries.delete(agent);
+        }
+        if (ran.outcome === 'canceled' || entry.canceled)
+            return { ...canceledResult, exitCode: ran.exitCode, output: ran.output };
+        return { agent, action, ...ran, precheck: await request.precheck() };
+    }
+    /** 页面取消：只有发起的连接能取消 */
+    cancel(ownerId, agent) {
+        const entry = this.entries.get(agent);
+        if (!entry || entry.ownerId !== ownerId)
+            return false;
+        entry.canceled = true;
+        entry.run?.cancel();
+        return true;
+    }
+    /** 连接关闭 */
+    cancelOwner(ownerId) {
+        for (const [agent, entry] of this.entries)
+            if (entry.ownerId === ownerId)
+                this.cancel(ownerId, agent);
+    }
+    /** bridge 退出：同步杀掉全部并删除临时目录 */
+    killAllNow() {
+        for (const entry of this.entries.values()) {
+            entry.canceled = true;
+            entry.run?.killNow();
+        }
+    }
+}

package/dist/bridge/env.js

@@ -105,3 +105,15 @@ export function buildProbeEnv(source = process.env, platform = process.platform)
 export function buildNpmEnv(source = process.env, platform = process.platform) {
     return { ...buildAgentEnv(source, platform), ...pick(source, (name) => NPM_CONFIG_NAMES.includes(name)) };
 }
+/**
+ * 把目录排到 PATH 最前（D10：让 connect 的 cli.js 与授权命令找得到适配器自带的 claude / codex 和 bridge 自己的 node）。
+ * Windows 的环境变量名不区分大小写，白名单保留的可能是 `Path`：改写原来那个键，不另加一个 `PATH`。
+ */
+export function prependPath(env, dirs, platform = process.platform) {
+    if (dirs.length === 0)
+        return env;
+    const key = platform === 'win32' ? (Object.keys(env).find((name) => name.toUpperCase() === 'PATH') ?? 'PATH') : 'PATH';
+    const separator = platform === 'win32' ? ';' : ':';
+    const current = env[key];
+    return { ...env, [key]: [...dirs, ...(current ? [current] : [])].join(separator) };
+}