@coclaw/openclaw-coclaw 0.22.4 → 0.24.0

package/src/provider-auth/handlers.js

@@ -1,5 +1,6 @@
 /**
- * provider-auth handlers —— `coclaw.providerAuth.*` 三个 RPC 的纯函数实现
+ * provider-auth handlers —— `coclaw.providerAuth.*` RPC 的纯函数实现
+ * （setApiKey / list / remove + OAuth 的 loginOauth / cancelOauth）
  *
  * 设计要点（详见 docs/model-config-api.md § 2 + § 6）：
  * - 通过 dependency injection 拿 SDK / agentDir 解析器，便于单测；产线注入在 ./index.js
@@ -20,9 +21,33 @@
  * 与 plugin 既有 `respondError` / `respondInvalid`（在 plugins/openclaw/index.js）的关系：
  * 既有 helper 用 `INVALID_INPUT` / `INTERNAL_ERROR`，与本节 RPC 契约（`INVALID_ARGS` /
  * `IO_FAILED`）不一致——所以本模块自带局部 helper，避免改既有 helper 影响所有现存 RPC。
+ *
+ * OAuth（loginOauth / cancelOauth）补充：
+ * - **真·两阶段 res**（plugin respond 可多调，详见 docs/model-config-api.md § 2.3.2）：
+ *   phase-1 同步 respond accepted 帧（payload 必带 `status:'accepted'` 否则中继提前清路由），
+ *   phase-2 后台轮询出结果后用同一 reqId respond 终态帧
+ * - phase-1 之前的失败（region 非法 / 设备码请求失败）走单帧错误响应（INVALID_ARGS / IO_FAILED）
+ * - phase-2 失败用 payload.status 区分语义（error / timeout / cancelled），结构化 error.code
+ *   按语义给 OAUTH_FAILED / OAUTH_TIMEOUT / OAUTH_CANCELLED；写凭据 null / 写配置抛错走 IO_FAILED
+ * - 后台轮询 fire-and-forget，但 runOAuthBackground 内全程 try/catch 保证恰好 respond 一次且不外抛；
+ *   终态在 finally 清 registry
  */
 
+import { randomUUID } from 'node:crypto';
+import { PORTAL_PROVIDER_ID, CONFIG_DEFAULT_BASE_URL, VALID_REGIONS } from './minimax-oauth.js';
+import { getPortalModels } from './portal-model-catalog.js';
+import { remoteLog } from '../remote-log.js';
+import { getClawConfig } from '../claw-config.js';
+import { deepMergeInto } from '../utils/deep-merge.js';
+import {
+	isVerificationNote,
+	extractVerification,
+	findDeviceCodeMethod,
+	makeDeviceCodeCtx,
+} from './device-code-login.js';
+
 const VALID_CRED_TYPES = new Set(['api_key', 'oauth', 'token']);
+const PORTAL_PROFILE_ID = `${PORTAL_PROVIDER_ID}:default`;
 
 function respondInvalid(respond, message) {
 	respond(false, undefined, { code: 'INVALID_ARGS', message });
@@ -40,7 +65,7 @@ function isNonEmptyString(v) {
 }
 
 /**
- * 构造三个 handler。
+ * 构造 handler 集合。
  *
  * @param {object} opts
  * @param {object} opts.sdk - openclaw/plugin-sdk/provider-auth 命名空间（或 stub）
@@ -49,10 +74,28 @@ function isNonEmptyString(v) {
  * @param {Function} opts.sdk.ensureAuthProfileStore - 位置参数 (agentDir, options?)
  * @param {Function} opts.sdk.removeProviderAuthProfilesWithLock - async；返回 store（成功）/ null（锁/磁盘失败）
  * @param {Function} opts.sdk.formatApiKeyPreview - 遮蔽显示 helper
+ * @param {Function} [opts.sdk.mutateConfigFile] - async；OAuth 写 cfg（openclaw/plugin-sdk/config-mutation）
  * @param {Function} opts.resolveAgentDir - 返回 main agent 完整路径（含 /agent 子目录）
- * @returns {{ setApiKey: Function, list: Function, remove: Function }}
+ * @param {object} [opts.oauth] - createMiniMaxOAuth 实例（requestDeviceCode / pollUntilSettled）；MiniMax B2 才用
+ * @param {object} [opts.registry] - oauth-registry（registerLogin / getLogin / removeLogin）；B2/B1 共用
+ * @param {Function} [opts.genLoginId] - () → loginId，默认 randomUUID
+ * @param {Function} [opts.scheduleBackground] - (promise) → void，挂后台任务；默认 fire-and-forget + .catch
+ * @param {Function} [opts.logRemote] - (text) → void，OAuth 终态诊断推送；默认模块级 remoteLog（测试注入 spy）
+ * @param {Function} [opts.resolveConfig] - () → OpenClaw runtime config 快照；通用 device-code 登录（B1）拿 config 用，默认 getClawConfig
+ * @param {Function} [opts.resolveProviders] - ({ config, providerRefs }) → ProviderPlugin[]；B1 经它拿 provider 的 auth 方法（生产由入口注入，内部 activate:false），默认抛错
+ * @returns {{ setApiKey, list, remove, loginOauth, cancelOauth }}
  */
-export function buildProviderAuthHandlers({ sdk, resolveAgentDir }) {
+export function buildProviderAuthHandlers({
+	sdk,
+	resolveAgentDir,
+	oauth,
+	registry,
+	genLoginId = randomUUID,
+	scheduleBackground = (p) => { p.catch(() => {}); },
+	logRemote = remoteLog,
+	resolveConfig = getClawConfig,
+	resolveProviders = () => { throw new Error('provider catalog runtime not injected'); },
+}) {
 	// TODO: 将来若要支持"设默认模型 / 多账号顺序"等需要写 cfg 的操作，会撞上
 	// gateway 重启窗口的 UX 问题——参 docs/model-config-api.md § 3 / § 5（占位章节）。
 	// 当前三个 RPC 都只动 secret 不动 cfg，零重启。
@@ -144,7 +187,333 @@ export function buildProviderAuthHandlers({ sdk, resolveAgentDir }) {
 		}
 	}
 
-	return { setApiKey, list, remove };
+	// --- OAuth（MiniMax device-code，真·两阶段 res） ---
+
+	// 写凭据 + 写 cfg；恰好 respond 一次，不外抛（成功 ok / 失败 IO_FAILED 都在内部消化）
+	async function persistOAuthSuccess({ region, token, loginId, respond }) {
+		try {
+			const credential = {
+				type: 'oauth',
+				provider: PORTAL_PROVIDER_ID,
+				access: token.access,
+				refresh: token.refresh,
+				expires: token.expires,
+			};
+			const result = await sdk.upsertAuthProfileWithLock({
+				profileId: PORTAL_PROFILE_ID,
+				credential,
+				agentDir: resolveAgentDir(),
+			});
+			// 同 setApiKey：锁/磁盘失败时上游静默返回 null
+			if (result === null) {
+				respond(false, { status: 'error' }, {
+					code: 'IO_FAILED',
+					message: 'failed to write auth-profiles store',
+				});
+				logRemote(`providerAuth.oauth.io-failed loginId=${loginId} stage=credential`);
+				return;
+			}
+			// 写 provider 节点 baseUrl —— hot-reload 路径，零打断（afterWrite:auto，禁传 restart）。
+			// baseUrl 优先用服务端动态返回的 resourceUrl，缺省回落 cn/global 默认（带 /anthropic 后缀）
+			const baseUrl = token.resourceUrl || CONFIG_DEFAULT_BASE_URL[region];
+			// 写模型清单进 provider 节点：上游对 minimax-portal 用写死静态清单且第三方触发不到其
+			// catalog discovery，不写则 catalog 为空、模型不可用。直接取内置静态表（与上游对齐），
+			// 不再网络拉取——避免登录拉一次后静态过时 + 带进旧模型。后续升级新模型靠启动对账补。
+			// 详见 docs/model-config-api.md § 2.3
+			const models = getPortalModels(PORTAL_PROVIDER_ID);
+			await sdk.mutateConfigFile({
+				afterWrite: { mode: 'auto' },
+				mutate(draft) {
+					if (!draft.models || typeof draft.models !== 'object' || Array.isArray(draft.models)) {
+						draft.models = {};
+					}
+					const p = draft.models.providers;
+					if (!p || typeof p !== 'object' || Array.isArray(p)) {
+						draft.models.providers = {};
+					}
+					draft.models.providers[PORTAL_PROVIDER_ID] = {
+						baseUrl,
+						api: 'anthropic-messages',
+						authHeader: true,
+						models,
+					};
+				},
+			});
+			respond(true, { status: 'ok', profileId: PORTAL_PROFILE_ID });
+			logRemote(`providerAuth.oauth.ok loginId=${loginId} profileId=${PORTAL_PROFILE_ID} models=${models.length}`);
+		}
+		catch (err) {
+			respond(false, { status: 'error' }, {
+				code: 'IO_FAILED',
+				message: String(err?.message ?? err),
+			});
+			logRemote(`providerAuth.oauth.io-failed loginId=${loginId} stage=config msg=${String(err?.message ?? err)}`);
+		}
+	}
+
+	// 后台轮询循环 → 终态 respond（phase-2）。全程 try/catch，保证恰好 respond 一次且不外抛；
+	// finally 清 registry，无论成功/失败/取消
+	async function runOAuthBackground({ region, loginId, deviceCode, abortController, respond }) {
+		try {
+			const outcome = await oauth.pollUntilSettled({
+				region,
+				userCode: deviceCode.userCode,
+				verifier: deviceCode.verifier,
+				expiresAt: deviceCode.expiresAt,
+				interval: deviceCode.interval,
+				signal: abortController.signal,
+			});
+			if (outcome.status === 'cancelled') {
+				respond(false, { status: 'cancelled' }, {
+					code: 'OAUTH_CANCELLED',
+					message: 'MiniMax OAuth login was cancelled',
+				});
+				logRemote(`providerAuth.oauth.cancelled loginId=${loginId}`);
+				return;
+			}
+			if (outcome.status === 'timeout') {
+				respond(false, { status: 'timeout' }, {
+					code: 'OAUTH_TIMEOUT',
+					message: 'MiniMax OAuth timed out before authorization completed',
+				});
+				logRemote(`providerAuth.oauth.timeout loginId=${loginId}`);
+				return;
+			}
+			if (outcome.status === 'error') {
+				respond(false, { status: 'error' }, {
+					code: 'OAUTH_FAILED',
+					message: outcome.message || 'MiniMax OAuth authorization failed',
+				});
+				logRemote(`providerAuth.oauth.error loginId=${loginId} msg=${outcome.message || 'authorization failed'}`);
+				return;
+			}
+			// success：persistOAuthSuccess 内部恰好 respond 一次，不外抛
+			await persistOAuthSuccess({ region, token: outcome.token, loginId, respond });
+		}
+		catch (err) {
+			// 防御：pollUntilSettled 未预期抛错（多半是 /oauth/token 轮询期的网络/传输失败）。
+			// 终态帧回 error + OAUTH_FAILED——属轮询阶段失败，区别于写盘失败的 IO_FAILED（见 docs § 2.3.6）；
+			// 避免发起方永远挂着
+			respond(false, { status: 'error' }, {
+				code: 'OAUTH_FAILED',
+				message: String(err?.message ?? err),
+			});
+			logRemote(`providerAuth.oauth.error loginId=${loginId} stage=poll msg=${String(err?.message ?? err)}`);
+		}
+		finally {
+			registry.removeLogin(loginId);
+		}
+	}
+
+	// MiniMax 设备码登录（B2：自家复刻设备码流，码已嵌在 verification URL 里 + 写静态模型清单）。
+	// 不并入通用 B1：MiniMax 不在 OpenClaw 内置 provider 字典，登录后还要补写 models.providers 清单
+	// （上游对 portal 不做 catalog discovery），与 codex/copilot「内置、模型自带」不同——见 docs § 6.16。
+	async function loginOauthMiniMax({ params, respond }) {
+		try {
+			const region = params?.region ?? 'cn';
+			if (!VALID_REGIONS.has(region)) {
+				respondInvalid(respond, 'region must be "cn" or "global"');
+				return;
+			}
+			let deviceCode;
+			try {
+				deviceCode = await oauth.requestDeviceCode({ region });
+			}
+			catch (err) {
+				// phase-1 之前失败（网络 / HTTP / 响应不全）：单帧错误响应
+				respondIoFailed(respond, err);
+				return;
+			}
+			const loginId = genLoginId();
+			const abortController = new AbortController();
+			// 先登记再 respond accepted：让紧随其后的 cancelOauth 一定能找到该 loginId
+			registry.registerLogin(loginId, { abortController });
+			respond(true, {
+				status: 'accepted',
+				loginId,
+				verificationUri: deviceCode.verificationUri,
+				userCode: deviceCode.userCode,
+				expiresAt: deviceCode.expiresAt,
+				interval: deviceCode.interval,
+			});
+			scheduleBackground(
+				runOAuthBackground({ region, loginId, deviceCode, abortController, respond }),
+			);
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	// --- 通用设备码登录（B1：驱动上游 provider 的 device_code run，跟随上游同步） ---
+
+	// 设备码失败的终态响应：phase-1 已发过 accepted → 发 phase-2 错误帧（带 status）；
+	// phase-1 之前就失败 → 单帧错误（payload undefined，与 MiniMax phase-1 之前失败同形）
+	function respondDeviceFailure(respond, phase1Sent, code, message, status = 'error') {
+		if (phase1Sent) respond(false, { status }, { code, message });
+		else respond(false, undefined, { code, message });
+	}
+
+	// 设备码登录成功：逐个写凭据 + 有 configPatch 就深合并进 cfg（hot-reload，零打断），恰好 respond 一次
+	async function persistDeviceCodeSuccess({ provider, result, loginId, phase1Sent, respond }) {
+		try {
+			const profileIds = [];
+			for (const profile of result.profiles) {
+				// 同一 auth-profiles 文件，顺序写避免锁竞争（device-code 通常仅 1 个 profile）
+				 
+				const r = await sdk.upsertAuthProfileWithLock({
+					profileId: profile.profileId,
+					credential: profile.credential,
+					agentDir: resolveAgentDir(),
+				});
+				if (r === null) {
+					respondDeviceFailure(respond, phase1Sent, 'IO_FAILED', 'failed to write auth-profiles store');
+					logRemote(`providerAuth.deviceCode.io-failed provider=${provider} loginId=${loginId} stage=credential`);
+					return;
+				}
+				profileIds.push(profile.profileId);
+			}
+			const patch = result.configPatch;
+			if (patch && typeof patch === 'object' && !Array.isArray(patch)) {
+				// configPatch 是 provider 自带的 onboarding 默认（如 codex 写 agents.defaults.models 别名）；
+				// 深合并保留其它 provider，afterWrite:auto 走 hot-reload 不重启（与 MiniMax 写 cfg 一致）
+				await sdk.mutateConfigFile({
+					afterWrite: { mode: 'auto' },
+					mutate(draft) { deepMergeInto(draft, patch); },
+				});
+			}
+			respond(true, { status: 'ok', provider, profileIds });
+			logRemote(`providerAuth.deviceCode.ok provider=${provider} loginId=${loginId} profiles=${profileIds.length}`);
+		}
+		catch (err) {
+			respondDeviceFailure(respond, phase1Sent, 'IO_FAILED', String(err?.message ?? err));
+			logRemote(`providerAuth.deviceCode.io-failed provider=${provider} loginId=${loginId} stage=config msg=${String(err?.message ?? err)}`);
+		}
+	}
+
+	async function loginOauthDeviceCode({ provider, respond }) {
+		try {
+			const config = resolveConfig() ?? {};
+			let providers;
+			try {
+				// resolveProviders 可能 async（生产侧惰性加载 catalog-runtime SDK 后再 resolve）
+				providers = await resolveProviders({ config, providerRefs: [provider] });
+			}
+			catch (err) {
+				// 加载器异常（SDK import 失败 / resolvePluginProviders 抛错）：phase-1 之前，单帧错误
+				respondIoFailed(respond, err);
+				return;
+			}
+			const method = findDeviceCodeMethod(providers, provider);
+			if (!method) {
+				respond(false, undefined, {
+					code: 'NOT_FOUND',
+					message: `provider "${provider}" has no device-code login method`,
+				});
+				return;
+			}
+
+			const loginId = genLoginId();
+			const abortController = new AbortController();
+			let phase1Sent = false;
+
+			// run 内 prompter.note 吐出「含 URL 的验证 note」→ 触发 phase-1 accepted（仅一次）。
+			// 结构化字段抠不到给 null，rawText 永远带上全文交前端兜底。登记发生在 respond accepted 之前，
+			// 让紧随其后的 cancelOauth 一定能按 loginId 找到该登录。
+			const ctx = makeDeviceCodeCtx({
+				config,
+				agentDir: resolveAgentDir(),
+				onNote: (text) => {
+					if (phase1Sent || !isVerificationNote(text)) return;
+					phase1Sent = true;
+					registry.registerLogin(loginId, { abortController });
+					const { verificationUri, userCode } = extractVerification(text);
+					respond(true, {
+						status: 'accepted',
+						loginId,
+						provider,
+						verificationUri,
+						userCode,
+						rawText: text,
+					});
+				},
+			});
+
+			// 起 run（不 await 整体）；run 仅跑一次，resolve/reject 都到这里恰好终态一次。
+			// run 无 abort 钩子：取消停不掉上游后台轮询，cancelOauth 只 abort 信号 → run 到期自己 settle
+			// 时这里识别 aborted、回 cancelled 终态、不写凭据（终态必达 + 清理，不做复查骚操作）。
+			async function runAndSettle() {
+				let result;
+				let runErr;
+				try {
+					result = await Promise.resolve().then(() => method.run(ctx));
+				}
+				catch (err) {
+					runErr = err;
+				}
+				if (phase1Sent) registry.removeLogin(loginId);
+
+				if (runErr) {
+					respondDeviceFailure(respond, phase1Sent, 'OAUTH_FAILED', String(runErr?.message ?? runErr));
+					logRemote(`providerAuth.deviceCode.error provider=${provider} loginId=${loginId} stage=run msg=${String(runErr?.message ?? runErr)}`);
+					return;
+				}
+				if (abortController.signal.aborted) {
+					respondDeviceFailure(respond, phase1Sent, 'OAUTH_CANCELLED', `device-code login for ${provider} was cancelled`, 'cancelled');
+					logRemote(`providerAuth.deviceCode.cancelled provider=${provider} loginId=${loginId}`);
+					return;
+				}
+				// 上游会把中途失败吞成空 profiles（如 copilot access_denied / expired）→ 空即失败
+				const profiles = Array.isArray(result?.profiles) ? result.profiles : [];
+				if (profiles.length === 0) {
+					respondDeviceFailure(respond, phase1Sent, 'OAUTH_FAILED', `device-code login for ${provider} returned no credentials`);
+					logRemote(`providerAuth.deviceCode.error provider=${provider} loginId=${loginId} stage=empty-profiles`);
+					return;
+				}
+				await persistDeviceCodeSuccess({ provider, result, loginId, phase1Sent, respond });
+			}
+
+			scheduleBackground(runAndSettle());
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	// 登录入口路由：minimax-portal（或缺省，向后兼容）→ B2 自家流；其它任何带 device_code 方法的
+	// provider → 通用 B1 驱动。不针对 codex/copilot 硬编码，后续 OpenClaw 新增 device_code provider 自动适用。
+	async function loginOauth({ params, respond }) {
+		const provider = params?.provider;
+		// provider 给了就必须是非空串（缺省保留给 MiniMax B2 向后兼容）：空串 / 非串在边界挡掉，
+		// 不让其漏进 B1 当 NOT_FOUND，也不把非串塞给上游 resolvePluginProviders（providerRefs 期望串）
+		if (provider !== undefined && !isNonEmptyString(provider)) {
+			respondInvalid(respond, 'provider must be a non-empty string when provided');
+			return;
+		}
+		if (provider === undefined || provider === PORTAL_PROVIDER_ID) {
+			return loginOauthMiniMax({ params, respond });
+		}
+		return loginOauthDeviceCode({ provider, respond });
+	}
+
+	async function cancelOauth({ params, respond }) {
+		try {
+			const loginId = params?.loginId;
+			if (!isNonEmptyString(loginId)) {
+				respondInvalid(respond, 'loginId must be a non-empty string');
+				return;
+			}
+			const entry = registry.getLogin(loginId);
+			// 幂等：未知 loginId 也回 {}（可能已终态自清，或从来没有）
+			if (entry) entry.abortController.abort();
+			respond(true, {});
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	return { setApiKey, list, remove, loginOauth, cancelOauth };
 }
 
 /**

package/src/provider-auth/index.js

@@ -1,38 +1,61 @@
 /**
- * provider-auth 注册入口 —— 把三个 handler 接到 gateway。
+ * provider-auth 注册入口 —— 把 handler 接到 gateway。
+ * （coclaw.providerAuth.setApiKey / list / remove / loginOauth / cancelOauth）
  *
  * 设计：
  * - SDK 通过**懒加载 dynamic import** 拿，避免本模块在测试环境（无 openclaw npm 包）下
  *   一加载就崩。第一次 RPC 调用时才解析；后续调用复用缓存的 promise
+ * - OAuth 额外需要 `mutateConfigFile`（config-mutation 子入口）写 provider 节点 baseUrl；
+ *   PKCE / 表单编码器从 provider-auth 子入口拿（同一 barrel 已导出）
  * - `mainAgentDir` 走 claw-paths.js 统一入口，handler 每次调用都现拿（state-dir 由 runtime 决定）
  * - `opts` 主要给单测用：可注入 fake sdk / agentDir resolver / loader
+ *
+ * 生产路径上 loadSdk / loadConfigMutation 必须由入口（plugins/openclaw/index.js）注入字面量
+ * dynamic import —— OpenClaw plugin loader 只扫入口源码识别 `openclaw/plugin-sdk/*` 字面量并
+ * 触发 jiti 重写；藏在本子模块的字面量 loader 看不到 → 原生 Node 解析必败。
  */
 import { buildProviderAuthHandlers } from './handlers.js';
+import { createMiniMaxOAuth } from './minimax-oauth.js';
+import { registerLogin, getLogin, removeLogin } from './oauth-registry.js';
 import { mainAgentDir } from '../claw-paths.js';
 
 // link-UNSAFE：模块级 dedup 缓存。`--link` 模式下两实例各自 lazy-load 一次
 // SDK（结果一致、运行无伤但去重失效）。当前仅 RPC handler 走该路径——
 // 不要在 hook 回调里访问本模块的 export。详见 docs/module-boundaries.md。
 let _sdkPromise;
+let _configMutationPromise;
+let _catalogRuntimePromise;
 
-// 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入 loadSdk，
+// 默认 loader 仅作 fallback：生产路径必须由入口（plugins/openclaw/index.js）注入，
 // 因为 OpenClaw plugin loader 只扫入口源码识别 `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；
 // 字面量留在本子模块里 loader 看不到 → 原生 Node 解析必败。
-// 此处的 import 在生产环境永不被调用；保留只为测试在不注入 opts.loadSdk 时仍能拿到一个失败路径
+// 此处的 import 在生产环境永不被调用；保留只为测试在不注入 opts.load* 时仍能拿到一个失败路径
 function defaultLoadSdk() {
 	_sdkPromise ??= import('openclaw/plugin-sdk/provider-auth');
 	return _sdkPromise;
 }
 
+function defaultLoadConfigMutation() {
+	_configMutationPromise ??= import('openclaw/plugin-sdk/config-mutation');
+	return _configMutationPromise;
+}
+
+function defaultLoadProviderCatalogRuntime() {
+	_catalogRuntimePromise ??= import('openclaw/plugin-sdk/provider-catalog-runtime');
+	return _catalogRuntimePromise;
+}
+
 /**
  * 测试辅助：清掉懒加载 SDK 缓存。
  */
 export function __resetSdkCache() {
 	_sdkPromise = undefined;
+	_configMutationPromise = undefined;
+	_catalogRuntimePromise = undefined;
 }
 
 /**
- * 在 gateway api 上注册 `coclaw.providerAuth.setApiKey` / `list` / `remove`。
+ * 在 gateway api 上注册 `coclaw.providerAuth.*`。
  *
  * 仅 `register(api)` 的 `if (api.registrationMode === 'full')` 分支调；
  * 其它 mode 注册副作用违规（参 plugins/openclaw/CLAUDE.md "Service / register 副作用边界"）。
@@ -41,17 +64,50 @@ export function __resetSdkCache() {
  * @param {object} [opts]
  * @param {Function} [opts.resolveAgentDir] - 覆盖 agentDir 解析（默认 mainAgentDir）
  * @param {Function} [opts.loadSdk] - 必传（生产由入口注入字面量 dynamic import）；缺省回退仅为测试兜底
+ * @param {Function} [opts.loadConfigMutation] - 必传（同上，OAuth 写 cfg 用）
+ * @param {Function} [opts.loadProviderCatalogRuntime] - 必传（同上，通用 device-code 登录 B1 拿 resolvePluginProviders 用）
+ * @param {object} [opts.registry] - 覆盖 oauth-registry（默认模块级单例）
  */
 export function registerProviderAuthHandlers(api, opts = {}) {
 	const resolveAgentDir = opts.resolveAgentDir ?? mainAgentDir;
 	const loadSdk = opts.loadSdk ?? defaultLoadSdk;
+	const loadConfigMutation = opts.loadConfigMutation ?? defaultLoadConfigMutation;
+	const loadProviderCatalogRuntime = opts.loadProviderCatalogRuntime ?? defaultLoadProviderCatalogRuntime;
+	const registry = opts.registry ?? { registerLogin, getLogin, removeLogin };
+
+	// catalog-runtime 仅通用 device-code 登录（B1）才需要，独立惰性加载——不耦合进 getHandlers
+	// 的 Promise.all，避免 setApiKey / list / remove / minimax-oauth 因这个 SDK 子入口缺失而连带失败。
+	let catalogRuntimePromise;
+	const resolveProviders = async ({ config, providerRefs }) => {
+		catalogRuntimePromise ??= loadProviderCatalogRuntime();
+		const catalogRuntime = await catalogRuntimePromise;
+		// 铁律：activate:false —— 只读拿 method.run，不激活 provider，零副作用（不动 gateway 活跃插件名册）。
+		return catalogRuntime.resolvePluginProviders({
+			config,
+			providerRefs,
+			activate: false,
+			mode: 'runtime',
+		});
+	};
 
 	let handlersPromise;
 	async function getHandlers() {
 		if (!handlersPromise) {
 			handlersPromise = (async () => {
-				const sdk = await loadSdk();
-				return buildProviderAuthHandlers({ sdk, resolveAgentDir });
+				const [providerAuthSdk, configMutation] = await Promise.all([
+					loadSdk(),
+					loadConfigMutation(),
+				]);
+				const sdk = {
+					...providerAuthSdk,
+					mutateConfigFile: configMutation.mutateConfigFile,
+				};
+				// PKCE / 表单编码器从 provider-auth barrel 取，注入给设备码流原语
+				const oauth = createMiniMaxOAuth({
+					generatePkce: providerAuthSdk.generatePkceVerifierChallenge,
+					toForm: providerAuthSdk.toFormUrlEncoded,
+				});
+				return buildProviderAuthHandlers({ sdk, resolveAgentDir, oauth, registry, resolveProviders });
 			})();
 		}
 		return handlersPromise;
@@ -78,4 +134,6 @@ export function registerProviderAuthHandlers(api, opts = {}) {
 	api.registerGatewayMethod('coclaw.providerAuth.setApiKey', wrap('setApiKey'));
 	api.registerGatewayMethod('coclaw.providerAuth.list', wrap('list'));
 	api.registerGatewayMethod('coclaw.providerAuth.remove', wrap('remove'));
+	api.registerGatewayMethod('coclaw.providerAuth.loginOauth', wrap('loginOauth'));
+	api.registerGatewayMethod('coclaw.providerAuth.cancelOauth', wrap('cancelOauth'));
 }