@m2canvas/connect 0.8.0 → 0.9.0

package/README.md

@@ -40,6 +40,7 @@ Lets M2 (in Chrome or another Chromium browser) start and talk to the agents on
 - **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 (they bundle the agent: about 110 MB and 140 MB to download, 270 MB and 350 MB on disk); 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.
+- **Checking an agent before use.** Before starting an agent, M2 asks the bridge whether it is signed in and has M2 set up (commands such as `claude auth status` and `claude mcp list`; `claude mcp list` starts the MCP servers you configured in order to check them). From 0.9.0 the bridge runs this check for Claude Code and Codex once when it starts, and remembers a result that passed, so opening another project doesn't wait for it again. It checks again when you click "Check again" in M2 and when M2 adds itself to an agent or signs in for you; when a page uses a remembered result that is more than 5 minutes old, it also checks again in the background and tells M2 if the result no longer holds. There is no periodic check. Results that need you to do something are never remembered, and nothing is written to disk.
 - Cursor runs as `agent acp`, OpenCode as `opencode acp`, Qoder as `qodercli --acp`.
 
 Agent sessions start in that directory.

package/dist/bridge/call-dispatch.js

@@ -38,7 +38,8 @@ export async function handleCall(ctx, conn, id, method, params) {
         case 'agent/prepare':
             return { agent, adapter: await ctx.service.prepare(agent) };
         case 'agent/precheck':
-            return ctx.service.precheck(agent);
+            // 带连接 id：每条连接第一次查这家可用缓存，之后一律真跑（契约 18）
+            return ctx.service.precheck(agent, conn.id);
         case 'm2/configure':
             ctx.log(`Page asked to add M2 to ${agent}'s MCP config.`);
             return { agent, ...(await ctx.service.configure(agent)) };

package/dist/bridge/main.js

@@ -15,7 +15,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { home, isExecutable, which } from '../system.js';
-import { AdapterManager, ADAPTERS } from './adapters.js';
+import { AdapterManager, ADAPTERS, isAdapterAgent } from './adapters.js';
 import { BRIDGE_HELP, EXIT_ALREADY_RUNNING, EXIT_PORT_UNAVAILABLE, backgroundLifetimeMs, parseBridgeArgs } from './args.js';
 import { detectAgent } from './agents.js';
 import { EXPECT_PATH } from './authorize.js';
@@ -29,6 +29,7 @@ import { PairingManager, createFilePairingStore } from './pairing.js';
 import { BRIDGE_AGENT_IDS, BRIDGE_WS_PATH } from './protocol.js';
 import { resolveNpmCommand } from './npm-command.js';
 import { allowedOrigins } from './security.js';
+import { prewarmPrechecks } from './precheck-cache.js';
 import { selfTestProblems } from './self-test.js';
 import { runCheckUpdate } from './update-io.js';
 import { startBridgeServer } from './server.js';
@@ -36,6 +37,8 @@ import { createAgentService } from './service.js';
 import { KILL_GRACE_MS } from './processes.js';
 import { createSelfUninstaller, uninstallScriptPath } from './uninstall.js';
 const NPM_CI_TIMEOUT_MS = 15 * 60 * 1000;
+/** 启动时预热预检的 agent（契约 18；用户 2026-11-04 拍板 B-P1：随包的两家，不管用没用过） */
+const PREWARM_AGENTS = ['claude', 'codex'];
 const LABELS = {
     claude: 'Claude Code',
     codex: 'Codex',
@@ -191,6 +194,9 @@ export async function runBridge(argv) {
         cliPath: fileURLToPath(new URL('../cli.js', import.meta.url)),
         platform: process.platform,
         expectAvailable: () => isExecutable(EXPECT_PATH),
+        // 出现过「通过」之后一次真跑没通过：告诉之前可能拿到通过的页面（尽力收回，契约 18）
+        onPrecheckRevoked: (result) => server?.broadcast('precheck/updated', result),
+        log,
     });
     const version = packageVersion();
     const origins = allowedOrigins(parsed.dev);
@@ -330,6 +336,13 @@ export async function runBridge(argv) {
             log,
         });
     }
+    // 预热（契约 18，用户 2026-11-04 拍板 B-P1）：信号处理装好之后再起，收尾时 killActiveExecs 能杀掉它的命令；不等它，页面来查会加入
+    void prewarmPrechecks({
+        agents: PREWARM_AGENTS,
+        ready: (agent) => isAdapterAgent(agent) && adapters.isReady(agent),
+        warm: (agent) => service.warmPrecheck(agent),
+        log,
+    });
     const lifetime = backgroundLifetimeMs(parsed);
     if (lifetime !== null) {
         setTimeout(() => {

package/dist/bridge/precheck-cache.js

@@ -0,0 +1,144 @@
+/** 缓存最长可用这么久；之后的第一次查询真跑 */
+export const PRECHECK_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/** 用到的缓存比这更旧时，同时在后台复查一次 */
+export const PRECHECK_REFRESH_AFTER_MS = 5 * 60 * 1000;
+/** 能缓存的「通过」：比页面的 precheckPasses 严 —— 登录 unknown、已跳过的 m2 unknown 页面放行，这里都不记 */
+export function isCacheablePrecheck(result) {
+    const login = result.login.state;
+    const m2 = result.m2.state;
+    return (login === 'logged_in' || login === 'not_required') && (m2 === 'ready' || m2 === 'unverified');
+}
+export class PrecheckCache {
+    deps;
+    slots = new Map();
+    /** 每条连接查过哪几家；连接关闭时 forgetConnection */
+    asked = new Map();
+    sequence = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 页面连接上的一次 `agent/precheck` */
+    forConnection(connectionId, agent) {
+        const asked = this.asked.get(connectionId) ?? new Set();
+        this.asked.set(connectionId, asked);
+        if (asked.has(agent))
+            return this.fresh(agent, 'same page checked again');
+        asked.add(agent);
+        const slot = this.slot(agent);
+        const cached = slot.cached;
+        if (cached && this.deps.usable(agent)) {
+            const age = this.deps.now() - cached.startedAt;
+            // 年龄为负（系统时钟往回拨过）当作过期：不能让它一直「不到 5 分钟」而永不复查（review r1 N2）
+            if (age >= 0 && age <= PRECHECK_CACHE_MAX_AGE_MS) {
+                const refresh = age > PRECHECK_REFRESH_AFTER_MS;
+                this.deps.log(`Precheck of ${agent} for a page: used the result from ${Math.round(age / 1000)}s ago${refresh ? ' (checking again in the background)' : ''}.`);
+                if (refresh)
+                    this.warm(agent, 'background re-check').catch(() => undefined); // 结果与出错由 start 记日志
+                slot.passHandedOut = true;
+                return Promise.resolve(cached.result);
+            }
+        }
+        if (slot.shared) {
+            this.deps.log(`Precheck of ${agent} for a page: joined a check already running.`);
+            return slot.shared;
+        }
+        return this.warm(agent, 'first check for a page');
+    }
+    /** 独立的一次真跑（同一连接的再查、授权结束后的重查）：不加入任何在跑的，结果照常写回 */
+    fresh(agent, reason) {
+        return this.start(agent, reason);
+    }
+    /** 可共享的真跑：这家已有一次在跑就加入它，否则起一次 */
+    warm(agent, reason) {
+        const slot = this.slot(agent);
+        if (slot.shared)
+            return slot.shared;
+        const running = this.start(agent, reason);
+        slot.shared = running;
+        const clear = () => {
+            if (slot.shared === running)
+                slot.shared = null;
+        };
+        running.then(clear, clear);
+        return running;
+    }
+    /** 写配置 / 授权开始时：这家的状态马上要变 */
+    invalidate(agent) {
+        const slot = this.slot(agent);
+        slot.generation += 1;
+        slot.cached = null;
+        slot.latest = null;
+        slot.shared = null;
+    }
+    forgetConnection(connectionId) {
+        this.asked.delete(connectionId);
+    }
+    slot(agent) {
+        let slot = this.slots.get(agent);
+        if (!slot) {
+            slot = { generation: 0, cached: null, latest: null, lastWrite: 0, passHandedOut: false, shared: null };
+            this.slots.set(agent, slot);
+        }
+        return slot;
+    }
+    start(agent, reason) {
+        const slot = this.slot(agent);
+        const run = { sequence: ++this.sequence, generation: slot.generation, startedAt: this.deps.now() };
+        return this.deps.run(agent).then((result) => {
+            const seconds = ((this.deps.now() - run.startedAt) / 1000).toFixed(1);
+            this.deps.log(`Precheck of ${agent} (${reason}): ${verdict(result)} in ${seconds}s.`);
+            this.write(agent, run, result);
+            // 被更晚开始、已写入的真跑推翻：交出那个更新的结论。不看代数：latest 作废时清空、之后只由作废后开始的真跑写入，必然更新
+            const handedOut = run.sequence < slot.lastWrite && slot.latest ? slot.latest : result;
+            if (isCacheablePrecheck(handedOut))
+                slot.passHandedOut = true;
+            return handedOut;
+        }, (error) => {
+            this.deps.log(`Precheck of ${agent} (${reason}) did not run: ${error instanceof Error ? error.message : String(error)}`);
+            // 前置条件不满足：原来的通过不再可信，删掉；不推送 —— 调用方自己会拿到这个错误
+            if (this.canWrite(slot, run)) {
+                slot.lastWrite = run.sequence;
+                slot.cached = null;
+                slot.latest = null;
+            }
+            throw error;
+        });
+    }
+    canWrite(slot, run) {
+        return run.generation === slot.generation && run.sequence > slot.lastWrite;
+    }
+    write(agent, run, result) {
+        const slot = this.slot(agent);
+        if (!this.canWrite(slot, run))
+            return;
+        slot.lastWrite = run.sequence;
+        slot.latest = result;
+        if (isCacheablePrecheck(result)) {
+            slot.cached = { result, startedAt: run.startedAt };
+            return;
+        }
+        slot.cached = null;
+        if (slot.passHandedOut) {
+            slot.passHandedOut = false;
+            this.deps.onRevoked(agent, result);
+        }
+    }
+}
+function verdict(result) {
+    return isCacheablePrecheck(result) ? 'passed' : `not passed (sign-in ${result.login.state}, M2 ${result.m2.state})`;
+}
+/**
+ * bridge 开始监听之后预热（design D6，用户 2026-11-04 拍板 B-P1：Claude 与 Codex，不管用没用过）。
+ * 副作用（契约 8）：`claude mcp list` 会启动用户配置的 stdio MCP 并联网，客户端用户同意连接后每次打开客户端都会发生一次。
+ * 只在启动时一次，不定时重复；各家并行；失败不抛出。结果与耗时由检查本身记一行（`Precheck of … (startup): …`），
+ * 真机的 bridge.log 因此自带每次启动的预检耗时。
+ */
+export async function prewarmPrechecks(deps) {
+    await Promise.all(deps.agents.map(async (agent) => {
+        if (!deps.ready(agent)) {
+            deps.log(`Skipped the startup precheck of ${agent}: its adapter isn't installed.`);
+            return;
+        }
+        await deps.warm(agent).catch(() => undefined);
+    }));
+}

package/dist/bridge/precheck.js

@@ -10,7 +10,8 @@
  * - 不调用 ACP authenticate 探测登录：Qoder 未登录时 60 秒不响应（PoC 报告 §2.5）。
  * - `qodercli mcp list` 会以 `mcp-test-client` 身份连 M2，服务端判成 mcp、不进项目房间（总控 §6）：页面不要把这次连接当成 Qoder 会话。
  * - Cursor 的 m2 授权按目录保存，mcp list 与授权命令都必须在会话 cwd 下执行。
- * - Codex 的预检与授权都用适配器自带的 codex（调用方保证适配器已就绪）。
+ * - Codex 的预检与授权都用适配器自带的 codex（调用方保证适配器已就绪）。Codex 的 m2 检查先断网跑一次，只有本地就能定的
+ *   三种结果直接用，其余联网再跑（`CODEX_OFFLINE_PROXY` 处的说明）。
  * - Claude 同样用适配器自带的 claude（D9）：会话用的就是它，本机那份只决定兜底命令怎么显示。找不到自带程序时报 unknown，
  *   不退回本机的 claude（否则预检和会话看的是两个程序）。
  */
@@ -20,6 +21,24 @@ 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;
+/**
+ * Codex 的 m2 检查先断网跑一次（change bridge-precheck-speedup D12）。`codex mcp list --json` 联网时会探测每个还没存凭证的
+ * HTTP 服务器支不支持 OAuth（用户真实环境 3–6.6 秒）；而 M2 的 `o_auth`（有本地凭证）、没配置、停用三种状态只由本地配置与凭证决定，
+ * 断网结果与联网一致（2026-11-04 隔离实测，`evidence/measurement.md` §1c）。「配了没授权」断网会给 unknown（联网是 not_logged_in），
+ * 所以只有这三种直接采用，其余一律联网再跑、以联网为准 —— 结果与只联网逐状态一致，变化只在耗时。
+ * 依赖 Codex 的实现细节：升级 Codex 适配器时按该 evidence 的做法重测三种状态（契约 7）。
+ */
+export const CODEX_OFFLINE_PROXY = 'http://127.0.0.1:9';
+/**
+ * 断网那次实测 0.06 秒；超过这个时限就当没结果、联网再跑。不用更紧的值：新铺的程序第一次运行有约 4 秒的系统扫描
+ * （`desktop-bundled-local-runtime` 实测），太紧会让首次 Codex 预检白等一次再联网（review r1 N3）。
+ */
+export const CODEX_OFFLINE_TIMEOUT_MS = 10_000;
+const OFFLINE_TRUSTED = new Set(['unverified', 'not_configured', 'needs_enable']);
+function offlineEnv(env) {
+    const proxy = CODEX_OFFLINE_PROXY;
+    return { ...env, HTTPS_PROXY: proxy, HTTP_PROXY: proxy, ALL_PROXY: proxy, https_proxy: proxy, http_proxy: proxy, all_proxy: proxy, NO_PROXY: '', no_proxy: '' };
+}
 export function shellQuote(value) {
     return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -74,6 +93,7 @@ function plan(agent, deps) {
                 login: { args: ['login', 'status'], parse: (r) => parseCodexLoginStatus(combinedOutput(r), r.code), next: run(display, ['login']) },
                 m2: {
                     args: ['mcp', 'list', '--json'],
+                    offlineFirst: true,
                     parse: (r) => parseCodexMcpListJson(r.stdout, r.code),
                     next: (state, entry) => state === 'needs_auth' || state === 'unverified'
                         ? run(display, ['mcp', 'login', entry])
@@ -132,13 +152,23 @@ function plan(agent, deps) {
             };
     }
 }
-async function runStep(deps, p, args) {
-    return deps.exec(p.exec.command, [...p.exec.prefix, ...args], { env: deps.env, cwd: deps.cwd, timeoutMs: PRECHECK_TIMEOUT_MS });
+async function runStep(deps, p, args, options = {}) {
+    return deps.exec(p.exec.command, [...p.exec.prefix, ...args], {
+        env: options.offline ? offlineEnv(deps.env) : deps.env,
+        cwd: deps.cwd,
+        timeoutMs: options.offline ? CODEX_OFFLINE_TIMEOUT_MS : PRECHECK_TIMEOUT_MS,
+    });
 }
 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);
+    if (p.m2.offlineFirst) {
+        // 断网那次出任何意外（起不来、超时、退出码非 0、认不出），Codex 的解析都给 unknown（退出码不是 0 就不信输出），于是联网再跑
+        const offline = p.m2.parse(await runStep(deps, p, p.m2.args, { offline: true }));
+        if (OFFLINE_TRUSTED.has(offline.state))
+            return toM2(offline, 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);

package/dist/bridge/server.js

@@ -304,6 +304,7 @@ export function startBridgeServer(options) {
                 connections.delete(conn.id);
                 processes.stopOwner(conn.id);
                 authorizations.cancelOwner(conn.id);
+                options.service.forgetConnection(conn.id);
             });
             // ws 的错误（非法帧、超过 maxPayload 等）之后必然紧跟 'close'，清理在 close 里做；这里只防止未处理的 error 事件让进程崩溃
             ws.on('error', () => undefined);

package/dist/bridge/service.js

@@ -14,6 +14,10 @@
  * 授权（change acp-terminal-free-auth）：authorizePlan 按写死清单生成命令（authorize.ts），m2 的配置项名只取 bridge 自己的 m2 预检：
  * 优先用最近一次预检 / 写配置时得到的名字（D19，页面先预检才会显示按钮，省掉一次重跑 —— Claude 的 `mcp list` 实测约 5 秒），没有记录时重跑；
  * 预检 / 写配置的结果按同一判据带上 `authorize` 能力，页面只在能力存在时才调用 agent/authorize。
+ *
+ * 预检缓存（change bridge-precheck-speedup，契约 18，规则在 precheck-cache.ts）：带连接 id 的预检是页面的 `agent/precheck`，
+ * 每条连接第一次查某家可以用缓存；不带的（授权结束后的重查）一律真跑并写回。写配置、授权在**开始运行之前**作废这家的缓存 ——
+ * 前置条件不满足而什么都没运行时不作废。缓存存不带能力的原始结果，给出时再按当前判据加 `authorize`。
  */
 import { dirname, join } from 'node:path';
 import { ADAPTERS, isAdapterAgent } from './adapters.js';
@@ -23,6 +27,7 @@ import { authCapability, buildAuthPlan, isSafeAuthEntry } from './authorize.js';
 import { prependPath } from './env.js';
 import { combinedOutput } from './exec.js';
 import { precheckAgent, precheckM2 } from './precheck.js';
+import { PrecheckCache } from './precheck-cache.js';
 import { BRIDGE_AGENT_IDS, } from './protocol.js';
 export const CONFIGURE_TIMEOUT_MS = 120_000;
 /**
@@ -92,6 +97,18 @@ export function createAgentService(deps) {
         login: withCapability(result.login, result.agent, 'login'),
         m2: withCapability(result.m2, result.agent, 'm2'),
     });
+    const precheckCache = new PrecheckCache({
+        run: async (agent) => {
+            const result = await precheckAgent(await ready(agent), precheckDeps);
+            remember(agent, result.m2);
+            return result;
+        },
+        // 只看文件状态、不起子进程；原生 agent 的检测要跑命令行，不在给缓存前做（拉起时 launch 会报 agent_not_installed）
+        usable: (agent) => !isAdapterAgent(agent) || deps.adapters.isReady(agent),
+        now: deps.now ?? Date.now,
+        onRevoked: (_agent, result) => deps.onPrecheckRevoked?.(withCapabilities(result)),
+        log: deps.log ?? (() => undefined),
+    });
     /** D10：clients.ts 只认 PATH 上能跑起来的 claude / codex */
     function configureEnv(agent) {
         const node = dirname(deps.nodePath);
@@ -130,13 +147,21 @@ export function createAgentService(deps) {
             }
             return info;
         },
-        async precheck(agent) {
-            const result = await precheckAgent(await ready(agent), precheckDeps);
-            remember(agent, result.m2);
+        async precheck(agent, connectionId) {
+            // 不带连接的只有授权结束后的重查（auth-call.ts）：一律新起一次真跑，不加入授权期间别的连接起的共享真跑（契约 12 delta）
+            const result = connectionId === undefined ? await precheckCache.fresh(agent, 'after sign-in or M2 authorization') : await precheckCache.forConnection(connectionId, agent);
             return withCapabilities(result);
         },
+        async warmPrecheck(agent) {
+            return precheckCache.warm(agent, 'startup');
+        },
+        forgetConnection(connectionId) {
+            precheckCache.forgetConnection(connectionId);
+        },
         async configure(agent) {
             const detected = await ready(agent);
+            // 马上要写配置：这家的预检结果不再可信（契约 18）
+            precheckCache.invalidate(agent);
             const result = await deps.exec(deps.nodePath, [deps.cliPath, '--client', CLIENT_ID[agent], '--yes'], {
                 env: configureEnv(agent),
                 cwd: deps.cwd,
@@ -165,6 +190,9 @@ export function createAgentService(deps) {
             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`);
+            // 取计划之后就运行授权命令（AuthorizationManager.run）：登录 / 授权状态马上要变，先作废缓存（契约 18）。
+            // 下面因配置项名缺失而 auth_unavailable 时也已作废 —— 没运行任何命令，多一次真跑无害
+            precheckCache.invalidate(agent);
             let entry = null;
             if (action === 'm2') {
                 // 配置项名不一定叫 m2，也不能由页面指定：用 bridge 最近一次预检的结果，没有就重跑（D19）；OpenCode 总是重跑（D21）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.8.0",
+  "version": "0.9.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": {