@m2canvas/connect 0.5.0 → 0.7.0

package/README.md

@@ -36,11 +36,29 @@ 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).
+
+## One-time install (macOS)
+
+M2's Local Agent tab can have an agent app set the bridge up for you, so you need neither a terminal nor Node.js:
+
+```bash
+curl -fsSL https://m2ui.ai/connect/install.sh | sh -s -- --pair <value from M2>
+```
+
+- **From M2.** Click "Connect with Claude" (or Codex, or Cursor): the app opens with this command in a prompt, and you press Return. The installer puts a private Node.js and a pinned version of this package in `~/.m2canvas`, checking every download against the hashes M2 publishes; writes the launcher `~/.m2canvas/bin/m2-bridge`; and starts the bridge in the background. The page pairs by itself. Agent sessions start in `~/.m2canvas/workspace`.
+- **Nothing starts at login.** After a restart, M2 asks the agent app to run `~/.m2canvas/bin/m2-bridge start --pair <value>` (you can run it yourself too). The launcher first updates the bridge to the version listed at `https://m2ui.ai/connect/manifest.json`, and goes back to the previous version if the new one doesn't start. The bridge keeps running after you quit the app, until you log out or shut down.
+- **No pairing codes in the background.** A bridge started this way has no window to show a code in. If a page isn't paired (the pairing expired, or you use another browser), M2 offers "Reconnect", which runs the launcher with `--replace`: it restarts the bridge and pairs that page, and agent sessions on the old bridge end.
+- **Sandboxes.** Codex needs its Full access permission mode: its default sandbox can't reach the network or write to your home folder. Inside the Codex or Claude command sandbox, the scripts change nothing and say what to do instead.
+- **What it leaves alone.** macOS 13.5 or later. It doesn't use sudo, register anything to start at login, change your shell config or PATH, or touch a Node.js you installed yourself. Logs are in `~/.m2canvas/logs/`.
+- **Uninstall** with `curl -fsSL https://m2ui.ai/connect/uninstall.sh | sh`, or "Uninstall local connection" in the Local Agent tab's ⋯ menu. It stops the bridge and removes what the installer added; `~/.m2canvas/workspace` is kept if it has files in it, and your agents' M2 settings stay as they are.
+
+The `npx` command above still works and is what M2 shows under "Advanced", for running the bridge in a folder you choose.

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,89 @@ 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';
+/** 安装完成的标记文件：没有它的目录一律视为未安装（自动更新清理旧目录时也只删带它的，change acp-bridge-one-time-install N2） */
+export const ADAPTER_READY_MARKER = '.m2canvas-ready';
+const READY_MARKER = ADAPTER_READY_MARKER;
+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);
@@ -50,19 +124,24 @@ function isProcessAlive(pid) {
 export function isAdapterAgent(agent) {
     return agent === 'claude' || agent === 'codex';
 }
+/**
+ * 安装目录名 = `<适配器目录名>-<lockfile 的 sha256 前 16 位>`：换了 lockfile 就是新目录。
+ * 自动更新按 current / previous 两个版本各自的 lockfile 算出要保留的目录（change acp-bridge-one-time-install N2），所以规则只能在这一处。
+ */
+export function adapterInstallDirName(sourceRoot, dir) {
+    const lock = readFileSync(join(sourceRoot, dir, 'package-lock.json'));
+    return `${dir}-${createHash('sha256').update(lock).digest('hex').slice(0, 16)}`;
+}
 export class AdapterManager {
     options;
     installing = new Map();
     lastError = new Map();
+    progress = 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)}`);
+        return join(this.options.installRoot, adapterInstallDirName(this.options.sourceRoot, ADAPTERS[agent].dir));
     }
     entryPath(agent) {
         return join(this.installDir(agent), ADAPTERS[agent].entry);
@@ -71,13 +150,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 +176,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 +203,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 +228,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;
+    }
+}