dsh-llm-fallbacks 0.3.0 → 0.3.2

package/dist/index.js

@@ -21,7 +21,7 @@ function parseSelector(input) {
 	const provider = trimmed.slice(0, slash).trim();
 	const modelPart = trimmed.slice(slash + 1).trim();
 	if (!provider || !modelPart) throw new SelectorError(`invalid selector "${input}": empty provider or model`);
-	if (modelPart.includes("/")) throw new SelectorError(`invalid selector "${input}": unexpected extra separator`);
+	if (modelPart !== "*" && modelPart.includes("*")) throw new SelectorError(`invalid selector "${input}": unexpected wildcard in model`);
 	return {
 		provider,
 		model: modelPart === "*" ? void 0 : modelPart,
@@ -953,12 +953,17 @@ const CONFIG_SUBCOMMAND_DESCRIPTION = {
 	zh: "查看组合后的 fallbacks 配置（设置回读）",
 	en: "show the composed fallbacks config (settings readback)"
 };
+const REVERT_SEED_SUBCOMMAND_DESCRIPTION = {
+	zh: "将角色的 persona 还原为已声明的 Seed 默认",
+	en: "revert a role's persona to its declared seed default"
+};
 const FALLBACKS_COMMAND_LOCALES = {
 	zh: {
 		title: "当前会话 fallback 诊断（只读）",
 		description: "查看当前会话的降级链、最近降级切换与冷却状态（只读）",
 		usageConfig: CONFIG_SUBCOMMAND_DESCRIPTION.zh,
-		usage: `  /fallbacks config   ${CONFIG_SUBCOMMAND_DESCRIPTION.zh}`,
+		usageRevertSeed: REVERT_SEED_SUBCOMMAND_DESCRIPTION.zh,
+		usage: `  /fallbacks config   ${CONFIG_SUBCOMMAND_DESCRIPTION.zh}\n  /fallbacks config revert-seed <role-id>   ${REVERT_SEED_SUBCOMMAND_DESCRIPTION.zh}`,
 		origin: "会话来源",
 		role: "角色",
 		chain: "链",
@@ -982,22 +987,37 @@ const FALLBACKS_COMMAND_LOCALES = {
 		configTriggerCodes: "触发码",
 		configRootChain: "根链",
 		configEmpty: "（空）",
+		configTimeSlots: "分时槽",
+		configSlotPresetItem: "{preset}（chain: {n}, window {window}）",
+		configSlotPresetBare: "{preset}（chain: {n}）",
+		configSlotCustomItem: "custom {start}-{end}（chain: {n}）",
+		configTz: "时区",
 		configRoles: "角色",
 		configRoleItem: "{id}（chain: {n}）",
+		configRules: "角色规则",
 		configCooldown: "冷却",
 		configRevert: "回主策略",
 		configMaxSwitches: "单步最大切换",
 		configAlwaysCap: "always 上限",
 		configPresets: "预置",
 		configRoleAutoMatch: "角色自动匹配",
-		configEdit: "编辑：~/.dsh/profiles/<profile>/cordis.patch.yml（插件行）或 $DSH_HOME/settings.yaml（fallbacks: 分节）",
-		configEditHint: "TUI 无法修改配置——只能编辑文件"
+		configEdit: "编辑：/settings（TUI 设置界面）或 ~/.dsh/profiles/<profile>/cordis.patch.yml（插件行）/ $DSH_HOME/settings.yaml（fallbacks: 分节）",
+		configEditHint: "TUI 通过 /settings 修改配置；文件编辑仍然可用",
+		revertSeedOk: "角色 {id} 已还原为 Seed 默认",
+		revertSeedFail: "角色 {id} 未还原（{reason}）",
+		revertSeedError: "角色 {id} 还原失败（设置写入失败）",
+		revertSeedReason: {
+			"not-seeded": "未声明种子",
+			"row-absent": "角色行不存在",
+			"settings-unavailable": "设置通道不可用"
+		}
 	},
 	en: {
 		title: "Session fallback diagnostics (read-only)",
 		description: "Inspect fallback chain, recent fallback switches, and cooldown for this session (read-only)",
 		usageConfig: CONFIG_SUBCOMMAND_DESCRIPTION.en,
-		usage: `  /fallbacks config   ${CONFIG_SUBCOMMAND_DESCRIPTION.en}`,
+		usageRevertSeed: REVERT_SEED_SUBCOMMAND_DESCRIPTION.en,
+		usage: `  /fallbacks config   ${CONFIG_SUBCOMMAND_DESCRIPTION.en}\n  /fallbacks config revert-seed <role-id>   ${REVERT_SEED_SUBCOMMAND_DESCRIPTION.en}`,
 		origin: "Session origin",
 		role: "Role",
 		chain: "Chain",
@@ -1021,20 +1041,45 @@ const FALLBACKS_COMMAND_LOCALES = {
 		configTriggerCodes: "Trigger codes",
 		configRootChain: "Root chain",
 		configEmpty: "(empty)",
+		configTimeSlots: "Time slots",
+		configSlotPresetItem: "{preset} (chain: {n}, window {window})",
+		configSlotPresetBare: "{preset} (chain: {n})",
+		configSlotCustomItem: "custom {start}-{end} (chain: {n})",
+		configTz: "TZ",
 		configRoles: "Roles",
 		configRoleItem: "{id} (chain: {n})",
+		configRules: "Rules",
 		configCooldown: "Cooldown",
 		configRevert: "Revert",
 		configMaxSwitches: "Max switches/step",
 		configAlwaysCap: "Always-mode cap",
 		configPresets: "Presets",
 		configRoleAutoMatch: "Auto-match",
-		configEdit: "Edit: ~/.dsh/profiles/<profile>/cordis.patch.yml (plugin row) or $DSH_HOME/settings.yaml (fallbacks: section)",
-		configEditHint: "TUI cannot change config — edit files only"
+		configEdit: "Edit: /settings (TUI settings screen) or ~/.dsh/profiles/<profile>/cordis.patch.yml (plugin row) / $DSH_HOME/settings.yaml (fallbacks: section)",
+		configEditHint: "TUI edits config via /settings; file editing still works",
+		revertSeedOk: "role {id} reverted to its seed default",
+		revertSeedFail: "role {id} not reverted ({reason})",
+		revertSeedError: "role {id} revert failed (settings write failed)",
+		revertSeedReason: {
+			"not-seeded": "not a seeded role",
+			"row-absent": "role row absent",
+			"settings-unavailable": "settings channel unavailable"
+		}
 	}
 };
 function parseFallbacksSubcommand(rawInput) {
-	return rawInput.trim() === "config" ? "config" : "";
+	const trimmed = rawInput.trim();
+	if (trimmed === "config") return { kind: "config" };
+	const [head, sub, ...rest] = trimmed.split(/\s+/);
+	if (head === "config" && sub === "revert-seed") {
+		const arg = rest.join(" ").trim();
+		if (arg === "") return { kind: "" };
+		return {
+			kind: "revert-seed",
+			arg
+		};
+	}
+	return { kind: "" };
 }
 function isFallbacksSwitchData(data) {
 	if (typeof data !== "object" || data === null) return false;
@@ -1090,13 +1135,72 @@ function formatConfigRoles(roles, t) {
 	const list = items.length === 0 ? "" : `${items.join(", ")}${roles.length > 5 ? ", …" : ""}`;
 	return `${roles.length}${list.length === 0 ? "" : ` — ${list}`}`;
 }
+const DAY_NAMES = [
+	"Sun",
+	"Mon",
+	"Tue",
+	"Wed",
+	"Thu",
+	"Fri",
+	"Sat"
+];
+function formatDayMask(days) {
+	if (days.length === 0) return "";
+	const sorted = days.filter((day) => Number.isInteger(day) && day >= 0 && day <= 6).sort((a, b) => a - b);
+	if (sorted.length === 0) return "";
+	const runs = [];
+	let runStart = sorted[0];
+	let prev = sorted[0];
+	for (let index = 1; index <= sorted.length; index += 1) {
+		const day = sorted[index];
+		if (day === void 0 || day !== prev + 1) {
+			runs.push(prev === runStart ? DAY_NAMES[runStart] : `${DAY_NAMES[runStart]}-${DAY_NAMES[prev]}`);
+			runStart = day;
+			prev = day;
+		} else prev = day;
+	}
+	return runs.join(", ");
+}
+function formatDayMaskSegment(days) {
+	const mask = formatDayMask(days ?? []);
+	return mask === "" ? "" : ` (${mask})`;
+}
+function formatSlotWindow(preset) {
+	const definition = PRESETS[preset];
+	if (definition === void 0) return "";
+	const windows = definition.windows.map((window) => {
+		const dayMask = formatDayMaskSegment(window.days);
+		return `${window.start}-${window.end}${dayMask}`;
+	}).join(", ");
+	return definition.complement ? `outside ${windows}` : windows;
+}
+function formatConfigTimeSlots(slots, t) {
+	const items = slots.slice(0, 5).map((row) => {
+		if (row.preset !== void 0) {
+			const window = formatSlotWindow(row.preset);
+			return window === "" ? t.configSlotPresetBare.replace("{preset}", row.preset).replace("{n}", String(row.chainCount)) : t.configSlotPresetItem.replace("{preset}", row.preset).replace("{n}", String(row.chainCount)).replace("{window}", window);
+		}
+		const bounds = row.start !== void 0 && row.end !== void 0 ? `${row.start}-${row.end}${formatDayMaskSegment(row.days)}` : "";
+		return t.configSlotCustomItem.replace("{start}-{end}", bounds).replace("{n}", String(row.chainCount));
+	});
+	const list = items.length === 0 ? "" : `${items.join(", ")}${slots.length > 5 ? ", …" : ""}`;
+	return `${slots.length}${list.length === 0 ? "" : ` — ${list}`}`;
+}
+function formatConfigRules(rules, t) {
+	const items = rules.slice(0, 5).map((rule) => `${rule.provider === "" ? "*" : rule.provider}/${rule.model === "" ? "*" : rule.model} → ${rule.role}`);
+	const list = items.length === 0 ? "" : `${items.join(", ")}${rules.length > 5 ? ", …" : ""}`;
+	return `${rules.length}${list.length === 0 ? "" : ` — ${list}`}`;
+}
 function fallbacksConfigText(summary, locale = "zh") {
 	const t = FALLBACKS_COMMAND_LOCALES[locale];
 	return [
 		`${t.configTitle}: ${summary.enabled ? t.configEnabled : t.configDisabled}`,
 		`${t.configTriggerCodes}: ${summary.triggerCodes.length === 0 ? t.configEmpty : formatConfigList(summary.triggerCodes)}`,
 		`${t.configRootChain}: ${summary.rootChain.length === 0 ? t.configEmpty : formatConfigList(summary.rootChain)}`,
+		`${t.configTimeSlots}: ${summary.timeSlots.length === 0 ? t.configEmpty : formatConfigTimeSlots(summary.timeSlots, t)}`,
+		`${t.configTz}: ${summary.tz}`,
 		`${t.configRoles}: ${formatConfigRoles(summary.roles, t)}`,
+		`${t.configRules}: ${summary.rules.length === 0 ? t.configEmpty : formatConfigRules(summary.rules, t)}`,
 		`${t.configCooldown}: ${summary.cooldownMs} ms`,
 		`${t.configRevert}: ${summary.revertPolicy}`,
 		`${t.configMaxSwitches}: ${summary.maxSwitchesPerStep}`,
@@ -1132,10 +1236,31 @@ function fallbacksCommandText(snapshot, locale = "zh") {
 	return lines.join("\n");
 }
 function createFallbacksCommandHandler(controller, locale = "zh") {
-	return (invocation) => ({
-		kind: "success",
-		text: parseFallbacksSubcommand(invocation.rawInput ?? "") === "config" ? fallbacksConfigText(controller.getConfig(), locale) : fallbacksCommandText(controller.getSnapshot(invocation.agent), locale)
-	});
+	return (invocation) => {
+		const parsed = parseFallbacksSubcommand(invocation.rawInput ?? "");
+		if (parsed.kind === "config") return {
+			kind: "success",
+			text: fallbacksConfigText(controller.getConfig(), locale)
+		};
+		if (parsed.kind === "revert-seed" && parsed.arg !== void 0) {
+			const roleId = parsed.arg;
+			const t = FALLBACKS_COMMAND_LOCALES[locale];
+			return controller.revertSeed(roleId).then((outcome) => outcome.ok ? {
+				kind: "success",
+				text: t.revertSeedOk.replace("{id}", roleId)
+			} : {
+				kind: "error",
+				text: t.revertSeedFail.replace("{id}", roleId).replace("{reason}", t.revertSeedReason[outcome.reason ?? "not-seeded"])
+			}).catch(() => ({
+				kind: "error",
+				text: t.revertSeedError.replace("{id}", roleId)
+			}));
+		}
+		return {
+			kind: "success",
+			text: fallbacksCommandText(controller.getSnapshot(invocation.agent), locale)
+		};
+	};
 }
 function registerFallbacksCommands(registry, controller, locale = "zh") {
 	return registry.register({
@@ -1369,9 +1494,18 @@ const FALLBACKS_CONFIG_NODE = {
 		en: FALLBACKS_COMMAND_LOCALES.en.usageConfig
 	}
 };
+const REVERT_SEED_NODE = {
+	name: "revert-seed",
+	description: FALLBACKS_COMMAND_LOCALES.zh.usageRevertSeed,
+	descriptions: {
+		zh: FALLBACKS_COMMAND_LOCALES.zh.usageRevertSeed,
+		en: FALLBACKS_COMMAND_LOCALES.en.usageRevertSeed
+	}
+};
 function fallbacksChildren(canonicalPath) {
 	if (canonicalPath[0] !== "fallbacks") return [];
 	if (canonicalPath.length === 1) return [FALLBACKS_CONFIG_NODE];
+	if (canonicalPath.length === 2 && canonicalPath[1] === "config") return [REVERT_SEED_NODE];
 	return [];
 }
 const FALLBACKS_PROVIDER$1 = {
@@ -1397,6 +1531,309 @@ function installTuiClient(ctx, opts) {
 	});
 }
 //#endregion
+//#region .build/host/tui-settings.js
+const FALLBACKS_TUI_SECTION_NS = "fallbacks";
+function jsonFieldFormat(value) {
+	return value === void 0 || value === null ? "" : JSON.stringify(value, null, 2);
+}
+function jsonFieldParse(patch) {
+	return (text) => {
+		if (text.trim() === "") return { kind: "clear" };
+		if (new TextEncoder().encode(text).length > 65536) return void 0;
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return;
+		}
+		if (parsed === null) return { kind: "clear" };
+		try {
+			validateConfigPatch(patch(parsed));
+		} catch {
+			return;
+		}
+		return {
+			kind: "set",
+			value: parsed
+		};
+	};
+}
+function triggerCodesFormat(value) {
+	return Array.isArray(value) ? value.join(", ") : "";
+}
+function triggerCodesParse(text) {
+	if (text.trim() === "") return { kind: "clear" };
+	const tokens = text.split(",").map((token) => token.trim()).filter((token) => token !== "");
+	try {
+		validateConfigPatch({ triggerCodes: tokens });
+	} catch {
+		return;
+	}
+	return {
+		kind: "set",
+		value: tokens
+	};
+}
+function tzParse(text) {
+	const trimmed = text.trim();
+	if (trimmed === "") return { kind: "clear" };
+	try {
+		Intl.DateTimeFormat(void 0, { timeZone: trimmed });
+	} catch {
+		return;
+	}
+	return {
+		kind: "set",
+		value: trimmed
+	};
+}
+const BUNDLED_PRESETS_LABEL = `Bundled (${presetRoles.length} preset roles)`;
+function buildFallbacksTuiSection() {
+	return {
+		ns: FALLBACKS_TUI_SECTION_NS,
+		title: "fallbacks",
+		descriptions: {
+			zh: "回退设置：降级链、分时切换、角色与高级选项（与 Web 设置卡片完全一致）。",
+			en: "Fallback settings: degradation chains, time slots, roles, and advanced options (full parity with the web settings card)."
+		},
+		groups: [
+			{
+				id: "general",
+				title: "General",
+				descriptions: {
+					zh: "通用",
+					en: "General"
+				}
+			},
+			{
+				id: "chain",
+				title: "Fallback chain",
+				descriptions: {
+					zh: "降级链",
+					en: "Fallback chain"
+				}
+			},
+			{
+				id: "roles",
+				title: "Roles",
+				descriptions: {
+					zh: "角色",
+					en: "Roles"
+				}
+			},
+			{
+				id: "advanced",
+				title: "Advanced",
+				descriptions: {
+					zh: "高级",
+					en: "Advanced"
+				}
+			}
+		],
+		fields: [
+			{
+				path: ["enabled"],
+				label: "Enabled",
+				descriptions: {
+					zh: "启用回退",
+					en: "Enabled"
+				},
+				group: "general",
+				kind: "boolean"
+			},
+			{
+				path: ["roleAutoMatch"],
+				label: "LLM role auto-match",
+				descriptions: {
+					zh: "LLM 角色自动匹配",
+					en: "LLM role auto-match"
+				},
+				group: "general",
+				kind: "boolean"
+			},
+			{
+				path: ["presets"],
+				label: "Preset roles",
+				descriptions: {
+					zh: "预置角色",
+					en: "Preset roles"
+				},
+				group: "general",
+				kind: "select",
+				options: [{
+					value: "bundled",
+					label: BUNDLED_PRESETS_LABEL,
+					descriptions: {
+						zh: `预置（${presetRoles.length} 个预置角色）`,
+						en: BUNDLED_PRESETS_LABEL
+					}
+				}, {
+					value: "none",
+					label: "None",
+					descriptions: {
+						zh: "不注入",
+						en: "None"
+					}
+				}]
+			},
+			{
+				path: ["triggerCodes"],
+				label: "Trigger codes",
+				descriptions: {
+					zh: "触发码",
+					en: "Trigger codes"
+				},
+				hint: "Comma-separated failure codes that trigger the fallback. A code containing a comma cannot round-trip through this field.",
+				hintDescriptions: {
+					zh: "逗号分隔的触发回退的失败码；包含逗号的代码无法通过该字段往返。",
+					en: "Comma-separated failure codes that trigger the fallback. A code containing a comma cannot round-trip through this field."
+				},
+				group: "general",
+				kind: "text",
+				format: triggerCodesFormat,
+				parse: triggerCodesParse
+			},
+			{
+				path: ["tz"],
+				label: "Timezone",
+				descriptions: {
+					zh: "时区",
+					en: "Timezone"
+				},
+				hint: "IANA timezone identifier, e.g. Asia/Shanghai.",
+				hintDescriptions: {
+					zh: "IANA 时区标识符，如 Asia/Shanghai。",
+					en: "IANA timezone identifier, e.g. Asia/Shanghai."
+				},
+				group: "general",
+				kind: "text",
+				parse: tzParse
+			},
+			{
+				path: ["rootChain"],
+				label: "Root chain (JSON)",
+				descriptions: {
+					zh: "根降级链（JSON）",
+					en: "Root chain (JSON)"
+				},
+				hint: "JSON array of model selectors; the last entry must be an official V4 model.",
+				hintDescriptions: {
+					zh: "模型选择器 JSON 数组；末项必须是官方 V4 模型。",
+					en: "JSON array of model selectors; the last entry must be an official V4 model."
+				},
+				group: "chain",
+				kind: "text",
+				format: jsonFieldFormat,
+				parse: jsonFieldParse((parsed) => ({ rootChain: parsed }))
+			},
+			{
+				path: ["timeSlots"],
+				label: "Time slots (JSON)",
+				descriptions: {
+					zh: "分时切换（JSON）",
+					en: "Time slots (JSON)"
+				},
+				hint: "JSON array of slot rows (kind: preset|custom).",
+				hintDescriptions: {
+					zh: "分时行 JSON 数组（kind: preset|custom）。",
+					en: "JSON array of slot rows (kind: preset|custom)."
+				},
+				group: "chain",
+				kind: "text",
+				format: jsonFieldFormat,
+				parse: jsonFieldParse((parsed) => ({ timeSlots: parsed }))
+			},
+			{
+				path: ["roles", "list"],
+				label: "Roles (JSON)",
+				descriptions: {
+					zh: "角色列表（JSON）",
+					en: "Roles (JSON)"
+				},
+				group: "roles",
+				kind: "text",
+				format: jsonFieldFormat,
+				parse: jsonFieldParse((parsed) => ({ roles: { list: parsed } }))
+			},
+			{
+				path: ["roles", "rules"],
+				label: "Role rules (JSON)",
+				descriptions: {
+					zh: "角色规则（JSON）",
+					en: "Role rules (JSON)"
+				},
+				group: "roles",
+				kind: "text",
+				format: jsonFieldFormat,
+				parse: jsonFieldParse((parsed) => ({ roles: { rules: parsed } }))
+			},
+			{
+				path: ["cooldownMs"],
+				label: "Cooldown (ms)",
+				descriptions: {
+					zh: "冷却时间（毫秒）",
+					en: "Cooldown (ms)"
+				},
+				group: "advanced",
+				kind: "number"
+			},
+			{
+				path: ["maxSwitchesPerStep"],
+				label: "Max switches per step",
+				descriptions: {
+					zh: "单步最大切换次数",
+					en: "Max switches per step"
+				},
+				group: "advanced",
+				kind: "number"
+			},
+			{
+				path: ["alwaysModeRetryCap"],
+				label: "Always-mode retry cap",
+				descriptions: {
+					zh: "Always 模式重试上限",
+					en: "Always-mode retry cap"
+				},
+				group: "advanced",
+				kind: "number"
+			},
+			{
+				path: ["revertPolicy"],
+				label: "Revert policy",
+				descriptions: {
+					zh: "恢复策略",
+					en: "Revert policy"
+				},
+				group: "advanced",
+				kind: "select",
+				options: [{
+					value: "cooldown-expiry",
+					label: "Cooldown expiry",
+					descriptions: {
+						zh: "冷却到期",
+						en: "Cooldown expiry"
+					}
+				}, {
+					value: "never",
+					label: "Never",
+					descriptions: {
+						zh: "从不",
+						en: "Never"
+					}
+				}]
+			}
+		]
+	};
+}
+function installTuiSettingsSection(ctx, opts) {
+	if (!opts.serviceOwned) return;
+	ctx.inject(["tuiSettingsSections"], (tctx) => {
+		const registry = tctx.tuiSettingsSections;
+		if (registry === void 0) return;
+		return registry.register(buildFallbacksTuiSection());
+	});
+}
+//#endregion
 //#region .build/host/virtual-adapter.js
 const FALLBACKS_PROVIDER = "FallbacksChain";
 const FALLBACKS_CHAIN_MODEL = "Auto";
@@ -1836,10 +2273,25 @@ function apply(ctx, config = defaultFallbacksConfig) {
 				enabled: config.enabled,
 				triggerCodes: config.triggerCodes,
 				rootChain: config.rootChain,
+				timeSlots: (config.timeSlots ?? []).map((row) => row.kind === "preset" ? {
+					preset: row.preset,
+					chainCount: (row.chain ?? []).length
+				} : {
+					start: row.start,
+					end: row.end,
+					days: row.days,
+					chainCount: (row.chain ?? []).length
+				}),
+				tz: config.tz ?? "Asia/Shanghai",
 				roles: config.roles.list.map((role) => ({
 					id: role.id,
 					chainCount: role.chain?.length ?? 0
 				})),
+				rules: config.roles.rules.map((rule) => ({
+					provider: rule.provider ?? "",
+					model: rule.model ?? "",
+					role: rule.role
+				})),
 				cooldownMs: config.cooldownMs,
 				revertPolicy: config.revertPolicy,
 				maxSwitchesPerStep: config.maxSwitchesPerStep,
@@ -1847,12 +2299,21 @@ function apply(ctx, config = defaultFallbacksConfig) {
 				presets: config.presets ?? "bundled",
 				roleAutoMatch: config.roleAutoMatch ?? true
 			};
+		},
+		revertSeed: async (roleId) => {
+			const outcome = await seeds.revert(roleId, seedsIo);
+			if (outcome.reverted) return { ok: true };
+			return {
+				ok: false,
+				reason: outcome.reason ?? "not-seeded"
+			};
 		}
 	};
 	ctx.inject(["commands"], (commandCtx) => {
 		return registerFallbacksCommands(commandCtx.commands, fallbacksCommandController);
 	});
 	installTuiClient(ctx, { serviceOwned });
+	installTuiSettingsSection(ctx, { serviceOwned });
 	ctx.inject(["settings"], () => {
 		if (!serviceOwned) return;
 		if (seedsIo.read().presets === "none") return;

package/dist/selectors.d.ts

@@ -1,8 +1,10 @@
 /**
  * Selector parsing for `fallbacks` chains (spec §4, plan Task 2).
  *
- * Grammar: `provider/model` (exact) and `provider/*` (wildcard — the parsed
- * `model` is `undefined`). Illegal selectors throw {@link SelectorError} —
+ * Grammar: `provider/model` (exact — the model segment may itself contain
+ * `/`, e.g. NVIDIA NIM `nvidia/minimaxai/minimax-m3`) and `provider/*`
+ * (wildcard — the parsed `model` is `undefined`; `*` is only valid as the
+ * entire model segment). Illegal selectors throw {@link SelectorError} —
  * the catchable "config warning" path; warn-and-continue lives in Task 3.
  * These modules never crash on their own.
  *
@@ -25,7 +27,8 @@ export declare function selectorKey(provider: string, model?: string): string;
  * Parse a chain key or entry selector.
  *
  * Accepts `provider/model` and `provider/*`; throws {@link SelectorError}
- * on anything else (missing separator, empty parts, extra separators).
+ * on anything else (missing separator, empty parts, wildcard inside the
+ * model segment).
  */
 export declare function parseSelector(input: string): Selector;
 /**