@coclaw/openclaw-coclaw 0.21.5 → 0.22.2

package/src/cli-registrar.js

@@ -3,6 +3,7 @@ import { callGatewayMethod } from './common/gateway-notify.js';
 import {
 	notBound, bindOk, unbindOk,
 	claimCodeCreated,
+	apiKeySetOk, authListEntries, authListEmpty, authRemoveOk,
 } from './common/messages.js';
 
 /**
@@ -113,7 +114,7 @@ export function registerCoclawCli({ program, logger: _logger }, deps = {}) {
 					return;
 				}
 
-				const data = result.status;
+				const data = result.payload;
 				console.log(bindOk(data));
 			}
 			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
@@ -139,8 +140,7 @@ export function registerCoclawCli({ program, logger: _logger }, deps = {}) {
 				}
 
 				// RPC 成功：输出认领码信息
-				// gateway method 的 respond 数据包含 status 字段
-				const data = result.status;
+				const data = result.payload;
 				if (data?.code && data?.appUrl) {
 					console.log(claimCodeCreated({
 						code: data.code,
@@ -179,7 +179,7 @@ export function registerCoclawCli({ program, logger: _logger }, deps = {}) {
 					return;
 				}
 
-				const data = result.status;
+				const data = result.payload;
 				console.log(unbindOk(data));
 			}
 			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
@@ -188,4 +188,84 @@ export function registerCoclawCli({ program, logger: _logger }, deps = {}) {
 				process.exitCode = 1;
 			}
 		});
+
+	// 开发期辅助：provider-auth 三个 RPC 的瘦 CLI。
+	// 与 bind/unbind 一致——参数解析后调 gateway RPC，不重复业务逻辑。
+	const auth = coclaw
+		.command('auth')
+		.description('Manage provider auth credentials (developer helper)');
+
+	auth
+		.command('set-api-key <provider>')
+		.description('Store an API key for a provider')
+		.requiredOption('--key <key>', 'API key value (plaintext)')
+		.option('--profile-id <id>', 'Override profileId (default: <provider>:default)')
+		.action(async (provider, opts) => {
+			try {
+				const params = { provider, apiKey: opts.key };
+				if (opts.profileId) params.profileId = opts.profileId;
+				const result = await callWithRetry('coclaw.providerAuth.setApiKey', deps, {
+					params, timeoutMs: RPC_TIMEOUT_MS,
+				});
+				if (!result.ok) {
+					handleRpcError(result, 'set-api-key failed');
+					return;
+				}
+				const data = result.payload;
+				console.log(apiKeySetOk({ provider, profileId: data?.profileId ?? `${provider}:default` }));
+			}
+			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
+			catch (err) {
+				console.error(`Error: ${resolveErrorMessage(err)}`);
+				process.exitCode = 1;
+			}
+		});
+
+	auth
+		.command('list')
+		.description('List stored auth profiles')
+		.option('--provider <provider>', 'Filter by provider id')
+		.action(async (opts) => {
+			try {
+				const rpcOpts = { timeoutMs: RPC_TIMEOUT_MS };
+				if (opts.provider) rpcOpts.params = { provider: opts.provider };
+				const result = await callWithRetry('coclaw.providerAuth.list', deps, rpcOpts);
+				if (!result.ok) {
+					handleRpcError(result, 'list failed');
+					return;
+				}
+				const profiles = result.payload?.profiles ?? [];
+				if (profiles.length === 0) {
+					console.log(authListEmpty(opts.provider));
+					return;
+				}
+				console.log(authListEntries(profiles));
+			}
+			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
+			catch (err) {
+				console.error(`Error: ${resolveErrorMessage(err)}`);
+				process.exitCode = 1;
+			}
+		});
+
+	auth
+		.command('remove <provider>')
+		.description('Remove all stored auth profiles for a provider')
+		.action(async (provider) => {
+			try {
+				const result = await callWithRetry('coclaw.providerAuth.remove', deps, {
+					params: { provider }, timeoutMs: RPC_TIMEOUT_MS,
+				});
+				if (!result.ok) {
+					handleRpcError(result, 'remove failed');
+					return;
+				}
+				console.log(authRemoveOk(provider));
+			}
+			/* c8 ignore next 4 -- callGatewayMethod 不会抛异常，纯防御 */
+			catch (err) {
+				console.error(`Error: ${resolveErrorMessage(err)}`);
+				process.exitCode = 1;
+			}
+		});
 }

package/src/common/gateway-notify.js

@@ -46,7 +46,7 @@ export function escapeJsonForCmd(json) {
  * @param {Function} [spawnFn] - 可注入的 spawn 函数（测试用）
  * @param {object} [opts] - 可选配置（测试用）
  * @param {number} [opts.timeoutMs] - 总超时毫秒数
- * @returns {Promise<{ ok: boolean, status?: string, error?: string }>}
+ * @returns {Promise<{ ok: boolean, payload?: unknown, error?: string, message?: string }>}
  */
 export function callGatewayMethod(method, spawnFn, opts) {
 	/* c8 ignore next -- ?? fallback */
@@ -95,9 +95,9 @@ export function callGatewayMethod(method, spawnFn, opts) {
 			if (!trimmed) return { ok: false, error: 'empty_output' };
 			try {
 				const parsed = JSON.parse(trimmed);
-				// openclaw gateway call --json 直接输出 method 的 result payload
-				// 有合法 JSON 输出即视为 RPC 成功；失败时 CLI 会抛异常并以非零码退出
-				return { ok: true, status: parsed.status };
+				// openclaw gateway call --json 直接把 handler 的 wire payload 打到 stdout
+				// 整体 payload 原样透出，调用方自行读取业务字段（不再抠 .status 一层）
+				return { ok: true, payload: parsed };
 			} catch {
 				// 非 JSON 输出也视为成功（openclaw 非 --json 模式的兜底）
 				return { ok: true };

package/src/common/messages.js

@@ -1,6 +1,8 @@
 // bind/unbind CLI 及 command 的用户提示文案（统一出口）
 
-export function bindOk({ clawId, rebound, previousClawId }) {
+// data 容忍 undefined / 缺字段，避免 helper "非 JSON 兜底"分支返回无 payload 时抛 destructure TypeError
+export function bindOk(data) {
+	const { clawId = 'unknown', rebound, previousClawId } = data ?? {};
 	const action = rebound ? 're-bound' : 'bound';
 	const prev = previousClawId
 		? ` (previous Claw ${previousClawId} was auto-unbound)`
@@ -8,9 +10,9 @@ export function bindOk({ clawId, rebound, previousClawId }) {
 	return `OK. Claw (${clawId}) ${action} to CoClaw.${prev}`;
 }
 
-export function unbindOk({ clawId }) {
-	const id = clawId ?? 'unknown';
-	return `OK. Claw (${id}) unbound from CoClaw.`;
+export function unbindOk(data) {
+	const { clawId = 'unknown' } = data ?? {};
+	return `OK. Claw (${clawId}) unbound from CoClaw.`;
 }
 
 export function notBound() {
@@ -26,3 +28,39 @@ export function claimCodeCreated({ code, appUrl, expiresMinutes }) {
 		"If you don't have a CoClaw account yet, you can register on that page.",
 	].join('\n');
 }
+
+// provider-auth CLI 输出（auth set-api-key / list / remove）
+
+export function apiKeySetOk({ provider, profileId }) {
+	return `OK. API key for "${provider}" stored (profileId=${profileId}).`;
+}
+
+export function authListEmpty(provider) {
+	return provider
+		? `No auth profiles found for provider "${provider}".`
+		: 'No auth profiles found.';
+}
+
+/**
+ * 把 list RPC 返回的 profiles 数组渲染成多行文本。
+ * 每行格式：`<profileId>  <type>  <preview-or-meta>`
+ * 调用方负责处理空数组（用 authListEmpty）。
+ */
+export function authListEntries(profiles) {
+	const lines = profiles.map((p) => {
+		const meta = [];
+		if (p.keyPreview) meta.push(p.keyPreview);
+		if (p.email) meta.push(p.email);
+		if (p.displayName) meta.push(p.displayName);
+		if (typeof p.expiresAt === 'number') {
+			meta.push(`expires=${new Date(p.expiresAt).toISOString()}`);
+		}
+		const metaStr = meta.length > 0 ? `  ${meta.join('  ')}` : '';
+		return `${p.profileId}  ${p.type}${metaStr}`;
+	});
+	return lines.join('\n');
+}
+
+export function authRemoveOk(provider) {
+	return `OK. Removed all auth profiles for "${provider}".`;
+}

package/src/model-default/handlers.js

@@ -0,0 +1,177 @@
+/**
+ * model-default/handlers.js —— coclaw.model.set / list 两个 RPC 的纯函数实现
+ *
+ * 设计要点（详见 docs/model-config-api.md § 3）：
+ * - DI 注入 sdk（mutateConfigFile / buildModelsProviderData / isProviderAuthProfileConfigured）
+ *   + loadConfig + resolveAgentDir，便于单测；产线注入在 ./index.js
+ * - **出参不加 status wrap**（gateway-method-design skill 新约定）：set → {}；list → { default, agents }
+ * - 错误码只用 INVALID_ARGS / IO_FAILED，参考 provider-auth/handlers.js
+ *   既有 plugin 的 respondError 用 INTERNAL_ERROR 与本节契约不一致，所以本模块自带局部 helper
+ * - set 校验 fail-fast 顺序：params shape → 拒未知字段 → agentId → primary 类型 → primary 形态
+ *   （纯字符串：含 '/'、'/' 不在端点；不依赖 cfg）→ loadConfig → provider 凭据 → catalog
+ *   形态校验**前置在 loadConfig 之前**，cfg 不可读时非法形态仍是 INVALID_ARGS 而非 IO_FAILED
+ * - catalog 校验用 `view: 'all'`：picker 可见性过滤会误判某些合法 provider 不存在（subagent 调研结论）
+ */
+
+import { listAllPrimaries } from './resolve.js';
+import { writePrimary } from './persist.js';
+
+const ALLOWED_KEYS = new Set(['agentId', 'primary']);
+
+function respondInvalid(respond, message) {
+	respond(false, undefined, { code: 'INVALID_ARGS', message });
+}
+
+function respondIoFailed(respond, err) {
+	respond(false, undefined, {
+		code: 'IO_FAILED',
+		message: String(err?.message ?? err),
+	});
+}
+
+function isNonEmptyString(v) {
+	return typeof v === 'string' && v.trim().length > 0;
+}
+
+/**
+ * 纯字符串形态拆分：要求 primary 含 '/'，且 '/' 不在端点。
+ * @returns {{ provider: string, model: string }|null}
+ */
+function parseProviderModel(primary) {
+	const slashIdx = primary.indexOf('/');
+	if (slashIdx <= 0 || slashIdx === primary.length - 1) return null;
+	return {
+		provider: primary.slice(0, slashIdx),
+		model: primary.slice(slashIdx + 1),
+	};
+}
+
+/**
+ * cfg 相关的 primary 校验：provider 凭据 + catalog 存在性。
+ * 形态拆分由调用方完成（fail-fast 前置在 loadConfig 之前）。
+ *
+ * @returns {Promise<string|null>} 错误 message；null 表通过
+ */
+async function validateProviderCredAndCatalog({ provider, model, primary, cfg, sdk, agentDir }) {
+	// 凭据校验：isProviderAuthProfileConfigured 内部就是 listUsableProviderAuthProfileIds().length > 0
+	// cooldown profile 仍算"已配置"（cooldown 是临时态，上游 fallback 主循环会主动跳）
+	const hasCred = sdk.isProviderAuthProfileConfigured({ provider, cfg, agentDir });
+	if (!hasCred) {
+		return `provider "${provider}" has no usable auth profile`;
+	}
+
+	// catalog 校验：view: 'all' 绕开 picker 可见性过滤（picker 过滤掉的 provider 不影响合法性）
+	const data = await sdk.buildModelsProviderData(cfg, undefined, { view: 'all' });
+	const modelSet = data?.byProvider?.get(provider);
+	if (!modelSet || !modelSet.has(model)) {
+		return `model "${primary}" not found in catalog`;
+	}
+	return null;
+}
+
+/**
+ * 构造 set + list 两个 handler。
+ *
+ * @param {object} opts
+ * @param {object} opts.sdk
+ * @param {Function} opts.sdk.mutateConfigFile - openclaw/plugin-sdk/config-mutation
+ * @param {Function} opts.sdk.buildModelsProviderData - openclaw/plugin-sdk/models-provider-runtime
+ * @param {Function} opts.sdk.isProviderAuthProfileConfigured - openclaw/plugin-sdk/provider-auth
+ * @param {Function} opts.loadConfig - 返回当前 cfg snapshot；缺失时返回 null
+ * @param {Function} opts.resolveAgentDir - 返回 main agent /agent 子目录全路径
+ * @returns {{ set: Function, list: Function }}
+ */
+export function buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir }) {
+	async function set({ params, respond }) {
+		try {
+			if (!params || typeof params !== 'object' || Array.isArray(params)) {
+				respondInvalid(respond, 'params must be an object');
+				return;
+			}
+			for (const key of Object.keys(params)) {
+				if (!ALLOWED_KEYS.has(key)) {
+					respondInvalid(respond, `unknown field: ${key}`);
+					return;
+				}
+			}
+
+			const { agentId } = params;
+			if (agentId !== undefined && !isNonEmptyString(agentId)) {
+				respondInvalid(respond, 'agentId must be a non-empty string when provided');
+				return;
+			}
+
+			if (!Object.hasOwn(params, 'primary')) {
+				respondInvalid(respond, 'primary is required');
+				return;
+			}
+			const primary = params.primary;
+			if (primary !== null && typeof primary !== 'string') {
+				respondInvalid(respond, 'primary must be a string or null');
+				return;
+			}
+			if (primary !== null && primary.length === 0) {
+				respondInvalid(respond, 'primary must be a non-empty string or null');
+				return;
+			}
+
+			if (primary !== null) {
+				// 形态校验前置：纯字符串检查，不依赖 cfg → cfg 不可读时也能给 INVALID_ARGS
+				const parts = parseProviderModel(primary);
+				if (!parts) {
+					respondInvalid(respond, 'primary must look like "<provider>/<model>"');
+					return;
+				}
+				const cfg = loadConfig();
+				if (!cfg) {
+					respondIoFailed(respond, new Error('runtime config not available'));
+					return;
+				}
+				const validationError = await validateProviderCredAndCatalog({
+					...parts,
+					primary,
+					cfg,
+					sdk,
+					agentDir: resolveAgentDir(),
+				});
+				if (validationError) {
+					respondInvalid(respond, validationError);
+					return;
+				}
+			}
+
+			// 单独 catch 写盘错误为 IO_FAILED；外层 catch 兜更上层异常（DI 调用本身崩之类）
+			try {
+				await writePrimary(
+					{ agentId, primary },
+					{ mutateConfigFile: sdk.mutateConfigFile },
+				);
+			}
+			catch (err) {
+				respondIoFailed(respond, err);
+				return;
+			}
+
+			respond(true, {});
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	async function list({ respond }) {
+		try {
+			const cfg = loadConfig();
+			if (!cfg) {
+				respondIoFailed(respond, new Error('runtime config not available'));
+				return;
+			}
+			respond(true, listAllPrimaries(cfg));
+		}
+		catch (err) {
+			respondIoFailed(respond, err);
+		}
+	}
+
+	return { set, list };
+}

package/src/model-default/index.js

@@ -0,0 +1,106 @@
+/**
+ * model-default 注册入口 —— 把 coclaw.model.set / list 接到 gateway。
+ *
+ * 设计（同 provider-auth/index.js）：
+ * - 三个 SDK 子入口（config-mutation / models-provider-runtime / provider-auth）懒加载，
+ *   首次 RPC 调用才解析；失败硬编码 IO_FAILED 透 message
+ * - mainAgentDir 走 claw-paths.js；loadConfig 走 claw-config.js
+ * - opts 主要给单测用：可注入 fake sdk 工厂 / fake agentDir resolver / fake loadConfig
+ *
+ * 生产路径上 loadXxx 必须由入口（plugins/openclaw/index.js）显式注入字面量
+ * dynamic import —— 因 OpenClaw plugin loader 只扫入口源码识别
+ * `openclaw/plugin-sdk/*` 字面量并触发 jiti 重写；本子模块里的 import 字面量 loader
+ * 看不到 → 原生 Node 解析必败（详见 provider-auth/index.js 同款说明）。
+ */
+
+import { buildModelDefaultHandlers } from './handlers.js';
+import { mainAgentDir } from '../claw-paths.js';
+import { getClawConfig } from '../claw-config.js';
+
+let _configMutationP;
+let _modelsP;
+let _providerAuthP;
+
+function defaultLoadConfigMutation() {
+	_configMutationP ??= import('openclaw/plugin-sdk/config-mutation');
+	return _configMutationP;
+}
+function defaultLoadModelsProviderRuntime() {
+	_modelsP ??= import('openclaw/plugin-sdk/models-provider-runtime');
+	return _modelsP;
+}
+function defaultLoadProviderAuth() {
+	_providerAuthP ??= import('openclaw/plugin-sdk/provider-auth');
+	return _providerAuthP;
+}
+
+/**
+ * 测试辅助：清掉懒加载 SDK 缓存。
+ */
+export function __resetSdkCaches() {
+	_configMutationP = undefined;
+	_modelsP = undefined;
+	_providerAuthP = undefined;
+}
+
+/**
+ * 在 gateway api 上注册 `coclaw.model.set` / `coclaw.model.list`。
+ *
+ * 仅 `register(api)` 的 `if (api.registrationMode === 'full')` 分支调；
+ * 其它 mode 注册副作用违规（参 plugins/openclaw/CLAUDE.md "Service / register 副作用边界"）。
+ *
+ * @param {object} api - OpenClaw 注入的 plugin api
+ * @param {object} [opts]
+ * @param {Function} [opts.resolveAgentDir] - 覆盖 agentDir 解析（默认 mainAgentDir）
+ * @param {Function} [opts.loadConfig] - 覆盖 cfg 读取（默认 getClawConfig）
+ * @param {Function} [opts.loadConfigMutation] - 必传（生产由入口注入字面量 dynamic import）
+ * @param {Function} [opts.loadModelsProviderRuntime] - 必传（同上）
+ * @param {Function} [opts.loadProviderAuth] - 必传（同上）
+ */
+export function registerModelDefaultHandlers(api, opts = {}) {
+	const resolveAgentDir = opts.resolveAgentDir ?? mainAgentDir;
+	const loadConfig = opts.loadConfig ?? getClawConfig;
+	const loadConfigMutation = opts.loadConfigMutation ?? defaultLoadConfigMutation;
+	const loadModelsProviderRuntime = opts.loadModelsProviderRuntime ?? defaultLoadModelsProviderRuntime;
+	const loadProviderAuth = opts.loadProviderAuth ?? defaultLoadProviderAuth;
+
+	let handlersPromise;
+	async function getHandlers() {
+		if (!handlersPromise) {
+			handlersPromise = (async () => {
+				const [configMutation, modelsRuntime, providerAuth] = await Promise.all([
+					loadConfigMutation(),
+					loadModelsProviderRuntime(),
+					loadProviderAuth(),
+				]);
+				const sdk = {
+					mutateConfigFile: configMutation.mutateConfigFile,
+					buildModelsProviderData: modelsRuntime.buildModelsProviderData,
+					isProviderAuthProfileConfigured: providerAuth.isProviderAuthProfileConfigured,
+				};
+				return buildModelDefaultHandlers({ sdk, loadConfig, resolveAgentDir });
+			})();
+		}
+		return handlersPromise;
+	}
+
+	function wrap(methodName) {
+		return async (ctx) => {
+			let handlers;
+			try {
+				handlers = await getHandlers();
+			}
+			catch (err) {
+				ctx.respond(false, undefined, {
+					code: 'IO_FAILED',
+					message: String(err?.message ?? err),
+				});
+				return;
+			}
+			await handlers[methodName](ctx);
+		};
+	}
+
+	api.registerGatewayMethod('coclaw.model.set', wrap('set'));
+	api.registerGatewayMethod('coclaw.model.list', wrap('list'));
+}

package/src/model-default/persist.js

@@ -0,0 +1,115 @@
+/**
+ * model-default/persist.js —— 把 default/per-agent primary 字段级写回 cfg
+ *
+ * 关键约束（钉死自 D1 dump v9 + zod-schema.agent-model.ts AgentModelSchema）：
+ * - 走 mutateConfigFile —— mutator 拿到的是 structuredClone 出的 deep draft，字段级修改安全；
+ *   但**整体重写 model 字段会丢失 fallbacks / timeoutMs 等兄弟字段**，必须按现有形态分支处理
+ * - model 字段有三态：string 简写（等价 { primary }）/ object / 缺省
+ *   - object 形态：保留 fallbacks / timeoutMs，只动 primary 一项
+ *   - string 形态：升级成 { primary }（原 string 本来就只有 primary 这一项语义，无损）
+ *   - 缺省形态：直接置 { primary }
+ * - clear primary 时：object 上 delete primary；若 object 删掉 primary 后没剩字段，删整个 model；
+ *   string 形态直接删 model；entry / defaults 容器留空壳，不主动从 list 删（dump v9 § "删除某 scope 覆盖"）
+ * - last-writer-wins，不传 baseHash（mutate.ts assertBaseHashMatches 在 undefined 时直接通过）
+ */
+
+/**
+ * 把 default 或某 agent 的 primary 写回 cfg。
+ *
+ * @param {object} args
+ * @param {string} [args.agentId] - 缺省 = default scope；传非空 string = per-agent scope
+ * @param {string|null} args.primary - 非空 string 为设；null 为清
+ * @param {object} deps
+ * @param {Function} deps.mutateConfigFile - openclaw/plugin-sdk/config-mutation 的 mutateConfigFile
+ */
+export async function writePrimary(args, deps) {
+	const { agentId, primary } = args;
+	const { mutateConfigFile } = deps;
+	await mutateConfigFile({
+		mutate(draft) {
+			ensureAgents(draft);
+			if (agentId === undefined || agentId === null) {
+				applyDefaultScope(draft, primary);
+				return;
+			}
+			applyAgentScope(draft, agentId, primary);
+		},
+	});
+}
+
+function ensureAgents(draft) {
+	const a = draft.agents;
+	if (!a || typeof a !== 'object' || Array.isArray(a)) {
+		draft.agents = {};
+	}
+}
+
+function applyDefaultScope(draft, primary) {
+	if (primary === null) {
+		clearOnContainer(draft.agents.defaults);
+		// defaults 容器即便清空也保留，避免影响 cfg 中其它 defaults.* 字段（这里没改它们）
+		return;
+	}
+	const d = draft.agents.defaults;
+	if (!d || typeof d !== 'object' || Array.isArray(d)) {
+		draft.agents.defaults = {};
+	}
+	setOnContainer(draft.agents.defaults, primary);
+}
+
+function applyAgentScope(draft, agentId, primary) {
+	if (!Array.isArray(draft.agents.list)) {
+		draft.agents.list = [];
+	}
+	const idx = draft.agents.list.findIndex((e) => e?.id === agentId);
+	if (primary === null) {
+		if (idx === -1) return; // 没该 entry，无操作
+		clearOnContainer(draft.agents.list[idx]);
+		// dump v9：entry 整个就只剩这一项时留空壳，不主动从 list 删
+		return;
+	}
+	if (idx === -1) {
+		// AgentEntrySchema 内部所有子 schema 都 optional 或外层 optional，
+		// { id, model: { primary } } 是合法最小 entry（核源 zod-schema.agent-runtime.ts:889）
+		draft.agents.list.push({ id: agentId, model: { primary } });
+		return;
+	}
+	setOnContainer(draft.agents.list[idx], primary);
+}
+
+/**
+ * 在容器（defaults 对象 或 list[i] entry）上字段级设置 model.primary。
+ * 容器存在性已由调用方保证。
+ */
+function setOnContainer(container, primary) {
+	const cur = container.model;
+	if (cur && typeof cur === 'object') {
+		// 保留 fallbacks / timeoutMs 等兄弟字段
+		cur.primary = primary;
+		return;
+	}
+	// string / undefined / null：原状态没有可保留的兄弟字段，直接置 { primary }
+	container.model = { primary };
+}
+
+/**
+ * 在容器上字段级清除 model.primary。
+ * 容器不存在 / model 不存在 → 无操作。
+ */
+function clearOnContainer(container) {
+	if (!container || typeof container !== 'object') return;
+	const cur = container.model;
+	if (cur === undefined || cur === null) return;
+	if (typeof cur === 'string') {
+		// string 形态整个就只表达 primary，删 model 即清
+		delete container.model;
+		return;
+	}
+	if (typeof cur === 'object') {
+		delete cur.primary;
+		// primary 是 model object 唯一字段时整体删，避免留 {} 空壳
+		if (Object.keys(cur).length === 0) {
+			delete container.model;
+		}
+	}
+}

package/src/model-default/resolve.js

@@ -0,0 +1,88 @@
+/**
+ * model-default/resolve.js —— 从 cfg 读 default + per-agent primary 的纯函数
+ *
+ * model 字段三态（见上游 zod-schema.agent-model.ts AgentModelSchema）：
+ * - string：modelId 简写形态，等价于 { primary: <string> }
+ * - object：{ primary?, fallbacks?, timeoutMs? }，primary 可缺省（schema 标了 optional）
+ * - 缺省 / null：未设
+ *
+ * D1 只读 primary 字段；fallbacks / timeoutMs 在 list RPC 出参里不暴露
+ * （设计 dump v9 § "RPC method"、docs/model-config-api.md § 3）。
+ */
+
+export const MAIN_AGENT_ID = 'main';
+
+/**
+ * 从 model 字段（string|object|null|undefined）中提取 primary。
+ * @param {unknown} modelField - cfg.agents.defaults.model 或 cfg.agents.list[i].model
+ * @returns {string|null}
+ */
+export function readPrimaryFromModel(modelField) {
+	if (typeof modelField === 'string') {
+		return modelField.length > 0 ? modelField : null;
+	}
+	if (modelField && typeof modelField === 'object') {
+		const p = modelField.primary;
+		return typeof p === 'string' && p.length > 0 ? p : null;
+	}
+	return null;
+}
+
+/**
+ * 读 default scope 的 primary（cfg.agents.defaults.model）
+ * @param {object} cfg
+ * @returns {string|null}
+ */
+export function readDefaultPrimary(cfg) {
+	return readPrimaryFromModel(cfg?.agents?.defaults?.model);
+}
+
+/**
+ * 读某 agent 的 primary（cfg.agents.list[i].model）。
+ * 未找到该 agentId 也返回 null（与"未设"不区分）。
+ * @param {object} cfg
+ * @param {string} agentId
+ * @returns {string|null}
+ */
+export function readAgentPrimary(cfg, agentId) {
+	const entry = findAgentEntry(cfg, agentId);
+	return entry ? readPrimaryFromModel(entry.model) : null;
+}
+
+/**
+ * 在 cfg.agents.list 里按 id 找 entry。
+ * @returns {object|null}
+ */
+export function findAgentEntry(cfg, agentId) {
+	const list = cfg?.agents?.list;
+	if (!Array.isArray(list)) return null;
+	return list.find((e) => e?.id === agentId) ?? null;
+}
+
+/**
+ * 装配 coclaw.model.list 出参（D1 契约见 docs/model-config-api.md § 3）。
+ * agents 来源：cfg.agents.list 所有 entry + 永远包含 main（心智模型 § 3.5）。
+ * @param {object} cfg
+ * @returns {{
+ *   default: { primary: string|null },
+ *   agents: Record<string, { primary: string|null }>,
+ * }}
+ */
+export function listAllPrimaries(cfg) {
+	const out = {
+		default: { primary: readDefaultPrimary(cfg) },
+		agents: {},
+	};
+	const list = cfg?.agents?.list;
+	if (Array.isArray(list)) {
+		for (const entry of list) {
+			if (!entry || typeof entry.id !== 'string' || entry.id.length === 0) continue;
+			out.agents[entry.id] = { primary: readPrimaryFromModel(entry.model) };
+		}
+	}
+	// main agent 始终存在（心智模型 § 3.5）：cfg list 没显式 main entry 时补一条 primary=null
+	if (!Object.hasOwn(out.agents, MAIN_AGENT_ID)) {
+		out.agents[MAIN_AGENT_ID] = { primary: null };
+	}
+	return out;
+}