dsh-switchman 1.3.0

package/host/dispatch.js

@@ -0,0 +1,205 @@
+/** dsh-switchman dispatch-pool layer (Phase 2).
+ *
+ * Ported from opencode-switchman's pool lanes and model ranking onto DSH
+ * services: one dynamic systemPrompt section (order 10400, after the
+ * language section at 10300) renders the `[SWITCHMAN:POOLS]` recommendation
+ * table from the live volatile settings, and — only in enforce mode — a
+ * `tools/pre-execute` waterfall listener denies `subagent` calls that name
+ * a provider+model outside every configured pool and modelRank.
+ *
+ * Model-facing text is English and byte-stable for a given configuration
+ * (the anchor line never varies with UI locale). All reads go through the
+ * live volatile references, so settings edits apply without a plugin
+ * restart. Fail-open everywhere: a crashing gate or unreadable capability
+ * snapshot degrades to advice, never blocks a tool.
+ */
+
+import { LANES, laneEffortsField, laneField, laneManualField } from "./config.js";
+import { isModelRoute, loadCapabilityDefaults, normalizeModelKey, orderedPool } from "./lib/rank.js";
+
+/** True for a well-formed {provider, model, effort} pin; the effort value
+ *  is free-form — its valid set is the DSH adapter's reported efforts. */
+function isEffortEntry(value) {
+	return isModelRoute(value) && typeof value.effort === "string" && value.effort !== "";
+}
+
+/** Read one volatile settings field as a plain string (live `.get()` reference;
+ *  mirrors host/lang.js's helper — the files stay independently mountable). */
+function readField(field) {
+	if (field !== null && typeof field === "object" && typeof field.get === "function") {
+		try {
+			const value = field.get();
+			return typeof value === "string" ? value : "";
+		} catch {
+			return "";
+		}
+	}
+	return typeof field === "string" ? field : "";
+}
+
+/** Read one volatile settings field as an array (non-arrays degrade to []). */
+function readList(field) {
+	if (field !== null && typeof field === "object" && typeof field.get === "function") {
+		try {
+			const value = field.get();
+			return Array.isArray(value) ? value : [];
+		} catch {
+			return [];
+		}
+	}
+	return Array.isArray(field) ? field : [];
+}
+
+/** Boolean volatile-field read (false on any malformed value). */
+function readBool(field) {
+	if (field !== null && typeof field === "object" && typeof field.get === "function") {
+		try {
+			return field.get() === true;
+		} catch {
+			return false;
+		}
+	}
+	return field === true;
+}
+
+/** Live snapshot of the dispatch settings plus the bundled capability table.
+ *  Each lane carries its manual-order flag: manual=true lanes dispatch in
+ *  stored array order, auto lanes use the modelRank+capability ordering;
+ *  `efforts` holds the lane's manually pinned reasoning efforts. */
+function readDispatchState(ctx, config) {
+	const lanePools = LANES.map((lane) => ({
+		lane,
+		routes: readList(config[laneField(lane)]).filter(isModelRoute),
+		manual: readBool(config[laneManualField(lane)]),
+		efforts: readList(config[laneEffortsField(lane)]).filter(isEffortEntry),
+	}));
+	return {
+		lanePools,
+		modelRank: readList(config.modelRank).filter(isModelRoute),
+		enforce: readField(config.dispatchEnforce),
+		defaults: loadCapabilityDefaults(ctx?.logger),
+	};
+}
+
+/** Render `provider/model(T)` for one ordered pool entry, with a `@effort`
+ *  suffix when the route carries a manually pinned reasoning effort (tier
+ *  omitted when unknown). */
+function renderRoute(entry, effort = null) {
+	const base = entry.tier === null ? `${entry.provider}/${entry.model}` : `${entry.provider}/${entry.model}(${entry.tier})`;
+	return effort === null ? base : `${base}@${effort}`;
+}
+
+/** Key → pinned effort for one lane (first entry wins on duplicate keys). */
+function effortMapOf(pool) {
+	const effortOf = new Map();
+	for (const pin of pool.efforts) {
+		const key = normalizeModelKey(pin.provider, pin.model);
+		if (key !== "" && !effortOf.has(key)) effortOf.set(key, pin.effort);
+	}
+	return effortOf;
+}
+
+/** The `[SWITCHMAN:POOLS]` block: anchor line, one line per configured lane,
+ *  then the guidance lines (byte-stable for a given configuration). */
+function renderPoolsBlock(state) {
+	const configured = state.lanePools.filter((pool) => pool.routes.length > 0);
+	const lines = [`[SWITCHMAN:POOLS] configured=${configured.length}/6 enforce=${state.enforce}`];
+	for (const pool of state.lanePools) {
+		if (pool.routes.length === 0) continue;
+		const effortOf = effortMapOf(pool);
+		const routes = orderedPool(pool.routes, state.modelRank, state.defaults, pool.manual)
+			.map((entry) => renderRoute(entry, effortOf.get(normalizeModelKey(entry.provider, entry.model)) ?? null))
+			.join(", ");
+		lines.push(`${pool.lane}${pool.manual ? "*" : ""}: ${routes}`);
+	}
+	lines.push(
+		`When delegating via subagent/workflow, pick a model from the lane matching the task category; spawn_teammate takes no model argument (lanes do not apply to it).`,
+		`Lanes marked * are in manual order: dispatch follows the listed order exactly (the head is the first choice).`,
+		`effort: economy=medium mechanical=medium main=medium (high for complex tasks) hard=high vision=multimodal-capable model review=high; an unconfigured lane uses the system default model.`,
+		`A route suffixed @effort has a manually pinned reasoning effort — pass it as reasoning_effort when delegating to that model (it overrides the lane default).`,
+		`Review delegations: prefer a review-pool model different from the main session's when the pool offers one; reusing the same model is allowed (declare DOWNGRADED in the conclusion).`,
+		`This table does not restrict models outside the pools${
+			state.enforce === "enforce"
+				? " (enforce mode: subagent calls naming a provider+model outside the pools or modelRank are denied)"
+				: ""
+		}.`,
+	);
+	return lines.join("\n");
+}
+
+/** The first recommended route right now: the head of the first configured
+ *  lane in display order (already ordered — manual lanes use stored order,
+ *  auto lanes the modelRank+capability ordering), else the modelRank head. */
+function topRecommendation(state) {
+	for (const pool of state.lanePools) {
+		if (pool.routes.length === 0) continue;
+		return orderedPool(pool.routes, state.modelRank, state.defaults, pool.manual)[0] ?? null;
+	}
+	return state.modelRank.length > 0 ? state.modelRank[0] : null;
+}
+
+/** Mount the dispatch-pool layer: dynamic prompt section + enforce gate. */
+function applyDispatch(ctx, config) {
+	ctx.systemPrompt.section({
+		name: "switchman:dispatch",
+		order: 10400,
+		interpolate: false,
+		text: () => {
+			const state = readDispatchState(ctx, config);
+			const anyConfigured = state.lanePools.some((pool) => pool.routes.length > 0) || state.modelRank.length > 0;
+			if (!anyConfigured) return "";
+			return renderPoolsBlock(state);
+		},
+	});
+
+	// Enforce gate (tools/pre-execute waterfall): deny decisions are returned
+	// directly WITHOUT calling next() — { kind: "deny", reason } — while every
+	// other path must call and return next(). Only subagent calls that name
+	// both provider and model are checked; model-less calls use the system
+	// default and pass through untouched.
+	ctx.on("tools/pre-execute", (exec, next) => {
+		try {
+			if (readField(config.dispatchEnforce) !== "enforce") return next();
+			if (exec?.name !== "subagent") return next();
+			const args = exec.arguments;
+			if (typeof args?.provider !== "string" || args.provider === "") return next();
+			if (typeof args?.model !== "string" || args.model === "") return next();
+			const key = normalizeModelKey(args.provider, args.model);
+			if (key === "") return next();
+
+			const allowed = new Set();
+			for (const lane of LANES) {
+				for (const route of readList(config[laneField(lane)])) {
+					if (!isModelRoute(route)) continue;
+					const routeKey = normalizeModelKey(route.provider, route.model);
+					if (routeKey !== "") allowed.add(routeKey);
+				}
+			}
+			for (const entry of readList(config.modelRank)) {
+				if (!isModelRoute(entry)) continue;
+				const rankKey = normalizeModelKey(entry.provider, entry.model);
+				if (rankKey !== "") allowed.add(rankKey);
+			}
+			if (allowed.size === 0 || allowed.has(key)) return next();
+
+			const state = readDispatchState(ctx, config);
+			const recommendation = topRecommendation(state);
+			const recommended =
+				recommendation === null
+					? ""
+					: ` Recommended instead: ${recommendation.provider}/${recommendation.model}.`;
+			return {
+				kind: "deny",
+				reason:
+					`[SWITCHMAN:POOLS] enforce: route "${args.provider}/${args.model}" is outside every configured pool and modelRank.` +
+					`${recommended} Adjust the dispatch pools in the dsh-switchman settings page,` +
+					` or delegate without naming provider+model to use the system default.`,
+			};
+		} catch (error) {
+			ctx.logger.warn(`dsh-switchman: dispatch enforce gate failed open: ${error?.message ?? error}`);
+			return next();
+		}
+	});
+}
+
+export { applyDispatch };

package/host/lang.js

@@ -0,0 +1,182 @@
+/** dsh-switchman language-preference layer (Phase 1).
+ *
+ * Ported from opencode-switchman's project language preference
+ * (oc/src/lang-config.ts, oc/src/index.ts:1594-1604) onto DSH services:
+ * the on-disk settings.json / AGENTS.md marker pair becomes this plugin's
+ * volatile settings fields (live references — re-read at every assembly),
+ * the per-model-request system transform becomes one dynamic systemPrompt
+ * section (order 10300, after the persona suffix at 10200), and the
+ * tool.execute.after capture becomes a `tools/post-execute` waterfall
+ * listener.
+ *
+ * Model-facing protocol text is English and byte-stable: the
+ * `[SWITCHMAN:LANG]` anchor line is a function of the settings values only
+ * and never varies with UI locale, so bundled skills can match it
+ * textually. All parsing is defensive — any unexpected shape abandons
+ * silently (fail-open) and never disturbs the tool result flowing through
+ * the waterfall. Zero new dependencies.
+ */
+
+/** Marker embedded in the ask's question texts and matched on capture. */
+const LANG_ASK_MARKER = "switchman-lang";
+
+/** Longest stored/displayed language value (defensive bound, not truncated). */
+const MAX_LANG_LEN = 48;
+
+/** Anchor-line value shown for an empty comments/docs field (= follow conversation). */
+const SAME = "same";
+
+/** Normalize one language value: trim and bound the length; anything else → null. */
+function normalizeLangValue(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	if (trimmed.length === 0 || trimmed.length > MAX_LANG_LEN) return null;
+	return trimmed;
+}
+
+/** Read one volatile settings field as a plain string (live `.get()` reference). */
+function readField(field) {
+	if (field !== null && typeof field === "object" && typeof field.get === "function") {
+		try {
+			const value = field.get();
+			return typeof value === "string" ? value : "";
+		} catch {
+			return "";
+		}
+	}
+	return typeof field === "string" ? field : "";
+}
+
+/** Current language-preference snapshot from the live plugin config. */
+function readLangPref(config) {
+	return {
+		conversation: normalizeLangValue(readField(config?.langConversation)) ?? "",
+		comments: normalizeLangValue(readField(config?.langComments)) ?? "",
+		docs: normalizeLangValue(readField(config?.langDocs)) ?? "",
+	};
+}
+
+/** Configured block: byte-stable anchor line + English iron rules. */
+function renderLangBlock(pref) {
+	const anchor = (value) => (value === "" ? SAME : value);
+	const rule = (value) => (value === "" ? `${pref.conversation} (same as conversation)` : value);
+	return [
+		`[SWITCHMAN:LANG] conversation=${anchor(pref.conversation)} comments=${anchor(pref.comments)} docs=${anchor(pref.docs)}`,
+		`IRON RULE — project language preferences:`,
+		`- Replies and reasoning: ${pref.conversation}.`,
+		`- Code comments and commit messages: ${rule(pref.comments)}.`,
+		`- Documents you author (plans, PRDs, design docs, reports): ${rule(pref.docs)}.`,
+		`This line overrides any bundled skill's English-by-default. Ad-hoc user language requests are`,
+		`single-turn exceptions: honor that one reply, then revert to these preferences.`,
+	].join("\n");
+}
+
+/** Unconfigured block: gentle one-shot ask guidance (English, ≤6 lines, never blocking). */
+function renderAskGuidance() {
+	return [
+		`[SWITCHMAN:LANG] not configured for this project yet.`,
+		`Optionally, ask the user ONCE via a single ask_user_question call with exactly three questions —`,
+		`conversation language, code-comments language, generated-documents language — and include the marker`,
+		`"${LANG_ASK_MARKER}" in each question text so the answers are captured and persisted for you.`,
+		`If the user declines or skips, infer the language from their current message and do not ask again.`,
+		`Never block or delay any tool call on this preference; proceed with useful work regardless.`,
+	].join("\n");
+}
+
+/** True when one ask_user_question question entry carries the capture marker. */
+function carriesMarker(question) {
+	if (question === null || typeof question !== "object") return false;
+	for (const field of [question.question, question.header, question.id]) {
+		if (typeof field === "string" && field.includes(LANG_ASK_MARKER)) return true;
+	}
+	return false;
+}
+
+/** Marker-carrying questions from a (defensively checked) arguments object. */
+function markerQuestions(args) {
+	if (args === null || typeof args !== "object" || !Array.isArray(args.questions)) return [];
+	return args.questions.filter(carriesMarker);
+}
+
+/** Resolve the three answers positionally: 1st conversation, 2nd comments, 3rd docs.
+ *  A skipped or unusable comments/docs slot follows the conversation language;
+ *  no usable conversation answer at all → null (persist abandoned).
+ *  The success value of ask_user_question is `{ answers: [{ id, selected:
+ *  string[], custom?: string }] }` (dsh-tool-ask-user lib/index.js execute). */
+function parseLangAnswers(questions, value) {
+	const slots = questions.slice(0, 3);
+	if (slots.length < 3 || value === null || typeof value !== "object" || !Array.isArray(value.answers))
+		return null;
+	const byId = new Map();
+	for (const answer of value.answers) {
+		if (answer !== null && typeof answer === "object" && typeof answer.id === "string")
+			byId.set(answer.id, answer);
+	}
+	const rawAnswer = (question) => {
+		const answer = byId.get(typeof question.id === "string" ? question.id : "");
+		if (answer === undefined) return "";
+		if (typeof answer.custom === "string" && answer.custom.trim() !== "") return answer.custom;
+		if (Array.isArray(answer.selected) && typeof answer.selected[0] === "string") return answer.selected[0];
+		return "";
+	};
+	const conversation = normalizeLangValue(rawAnswer(slots[0]));
+	if (conversation === null) return null;
+	const follow = (raw) => normalizeLangValue(raw) ?? conversation;
+	return { conversation, comments: follow(rawAnswer(slots[1])), docs: follow(rawAnswer(slots[2])) };
+}
+
+/** Mount the language-preference layer: dynamic prompt section + answer capture.
+ *  `exec` here is the prepared ToolExecution ({ name, arguments, ... }) and
+ *  `result` the ToolExecutionResult ({ isError, value?, content, ... }); the
+ *  waterfall contract requires the listener to call and return next(). */
+function applyLanguage(ctx, config) {
+	/** Latched once any marker-carrying ask executes, so the ask guidance never nags
+	 *  (a declined, pending, or unparsable ask still counts — fail-open, no re-ask). */
+	let asked = false;
+
+	ctx.systemPrompt.section({
+		name: "switchman:lang",
+		order: 10300,
+		interpolate: false,
+		text: () => {
+			const pref = readLangPref(config);
+			if (pref.conversation !== "") return renderLangBlock(pref);
+			return asked ? "" : renderAskGuidance();
+		},
+	});
+
+	ctx.on("tools/post-execute", (exec, result, next) => {
+		try {
+			if (exec?.name === "ask_user_question") {
+				const questions = markerQuestions(exec.arguments);
+				if (questions.length > 0) {
+					asked = true;
+					const pref = parseLangAnswers(questions, result?.isError ? null : result?.value);
+					if (pref !== null) {
+						void ctx.settings
+							.update("dsh-switchman-host", {
+								langConversation: pref.conversation,
+								langComments: pref.comments,
+								langDocs: pref.docs,
+							})
+							.then(() => {
+								ctx.logger.info(
+									`dsh-switchman: language preferences saved (conversation=${pref.conversation} comments=${pref.comments} docs=${pref.docs})`,
+								);
+							})
+							.catch((error) => {
+								ctx.logger.warn(
+									`dsh-switchman: failed to save language preferences: ${error?.message ?? error}`,
+								);
+							});
+					}
+				}
+			}
+		} catch (error) {
+			ctx.logger.warn(`dsh-switchman: language answer capture failed: ${error?.message ?? error}`);
+		}
+		return next();
+	});
+}
+
+export { applyLanguage };

package/host/lib/rank.js

@@ -0,0 +1,187 @@
+/** dsh-switchman capability ranking (Phase 2), pure functions + one cached
+ * bundled-data read.
+ *
+ * Ported from opencode-switchman src/capability.ts (normalizeModelKey:68-74,
+ * tierOfScore:81-86, apiMatch:382-391) and the pool-lane ordering of
+ * scoring.rankCandidates, reduced to what DSH needs: normalize model
+ * references onto the bundled capability snapshot's keys, grade them into
+ * S/A/B/C tiers, and order one dispatch pool (modelRank-anchored entries
+ * first, then default capability score descending, input order as the
+ * stable fallback). All functions are defensive — malformed input degrades
+ * to a lower-information result, never throws.
+ */
+
+import { readFileSync } from "node:fs";
+
+/** Minimum length for a prefix match (avoids false hits on short keys). */
+const MIN_PREFIX_LEN = 4;
+
+/** Absolute index thresholds; a spec that is not S>A>B falls back to these. */
+const DEFAULT_THRESHOLDS = { S: 62, A: 55, B: 45 };
+
+/** Valid tier letters (RankEntrySchema's enum). */
+const TIERS = ["S", "A", "B", "C"];
+
+/** Normalize one model reference to its capability-table key: lowercase,
+ *  strip a `provider/model` / `provider:model` prefix, drop `(...)`/`[...]`
+ *  variant segments, fold illegal chars into "-" (capability.ts:68-74).
+ *  Accepts (provider, model) routes or a single combined string; the model
+ *  part wins when both are given. The `:` form is stripped only when the
+ *  prefix looks like a bare provider word (no "-"), so dated variants such
+ *  as `gpt-4o:latest` survive intact. */
+function normalizeModelKey(provider, model) {
+	let s = typeof model === "string" ? model : typeof provider === "string" ? provider : "";
+	s = s.toLowerCase().trim();
+	if (s.includes("/")) s = s.slice(s.lastIndexOf("/") + 1);
+	else if (s.includes(":")) {
+		const cut = s.lastIndexOf(":");
+		if (!s.slice(0, cut).includes("-")) s = s.slice(cut + 1);
+	}
+	s = s.replace(/\([^)]*\)/g, " ").replace(/\[[^\]]*\]/g, " ");
+	s = s.replace(/[^a-z0-9.]+/g, "-");
+	return s.replace(/-+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+}
+
+/** True for a plain `{ provider, model }` route shape. */
+function isModelRoute(value) {
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		typeof value.provider === "string" &&
+		value.provider !== "" &&
+		typeof value.model === "string" &&
+		value.model !== ""
+	);
+}
+
+/** Resolve the snapshot's thresholds: finite numbers with S>A>B, else defaults. */
+function resolveThresholds(spec) {
+	const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+	const t = {
+		S: num(spec?.S) ?? DEFAULT_THRESHOLDS.S,
+		A: num(spec?.A) ?? DEFAULT_THRESHOLDS.A,
+		B: num(spec?.B) ?? DEFAULT_THRESHOLDS.B,
+	};
+	return t.S > t.A && t.A > t.B ? t : { ...DEFAULT_THRESHOLDS };
+}
+
+/** Index → tier (S/A/B/C; score ≥ threshold takes the higher tier). */
+function tierOfScore(score, thresholds) {
+	if (score >= thresholds.S) return "S";
+	if (score >= thresholds.A) return "A";
+	if (score >= thresholds.B) return "B";
+	return "C";
+}
+
+/** Build the Map<key, {score, tier}> capability table from a parsed
+ *  capability-default.json (keys are pre-normalized by the generator).
+ *  Anything unexpected yields a smaller table, never an error. */
+function defaultTiers(data) {
+	const table = new Map();
+	if (data === null || typeof data !== "object") return table;
+	const models = data.models;
+	if (models === null || typeof models !== "object" || Array.isArray(models)) return table;
+	const thresholds = resolveThresholds(data.thresholds);
+	for (const [key, entry] of Object.entries(models)) {
+		if (typeof entry !== "object" || entry === null || !Number.isFinite(entry.score)) continue;
+		table.set(key, { score: entry.score, tier: tierOfScore(entry.score, thresholds) });
+	}
+	return table;
+}
+
+/** Exact → longest-prefix (≥ MIN_PREFIX_LEN) match against a capability
+ *  table; null when nothing matches (apiMatch:382-391). */
+function matchKey(table, normKey) {
+	if (typeof normKey !== "string" || normKey === "") return null;
+	const exact = table.get(normKey);
+	if (exact !== undefined) return { score: exact.score, tier: exact.tier, matchedAs: normKey };
+	let bestKey = null;
+	for (const [key] of table) {
+		if (key.length >= MIN_PREFIX_LEN && normKey.startsWith(key) && (bestKey === null || key.length > bestKey.length))
+			bestKey = key;
+	}
+	if (bestKey === null) return null;
+	const entry = table.get(bestKey);
+	return { score: entry.score, tier: entry.tier, matchedAs: bestKey };
+}
+
+/** Look one route (or combined string) up in a capability table. */
+function capabilityOf(table, provider, model) {
+	if (!(table instanceof Map)) return null;
+	return matchKey(table, normalizeModelKey(provider, model));
+}
+
+/** Order one dispatch pool's routes. With manual=false (default): entries
+ *  anchored in modelRank keep the array order and come first (their anchored
+ *  tier is display-only); the rest fall back to default capability score
+ *  descending, input order as the final tiebreak. With manual=true: the
+ *  stored input order IS the dispatch priority — no re-sorting, tiers are
+ *  still resolved for display. Each returned entry carries
+ *  { provider, model, tier } with tier = anchored ?? capability ?? null. */
+function orderedPool(poolRoutes, modelRank, table, manual = false) {
+	const routes = (Array.isArray(poolRoutes) ? poolRoutes : []).filter(isModelRoute);
+	const rank = (Array.isArray(modelRank) ? modelRank : []).filter(isModelRoute);
+	const anchorTier = new Map();
+	rank.forEach((entry) => {
+		const key = normalizeModelKey(entry.provider, entry.model);
+		if (key === "" || anchorTier.has(key)) return;
+		if (TIERS.includes(entry.tier)) anchorTier.set(key, entry.tier);
+	});
+	const resolveTier = (key) => anchorTier.get(key) ?? matchKey(table instanceof Map ? table : new Map(), key)?.tier ?? null;
+	if (manual) return routes.map((route) => ({ provider: route.provider, model: route.model, tier: resolveTier(normalizeModelKey(route.provider, route.model)) }));
+	const anchorIndex = new Map();
+	rank.forEach((entry, index) => {
+		const key = normalizeModelKey(entry.provider, entry.model);
+		if (key === "" || anchorIndex.has(key)) return;
+		anchorIndex.set(key, index);
+	});
+	const decorated = routes.map((route, index) => {
+		const key = normalizeModelKey(route.provider, route.model);
+		const anchor = anchorIndex.get(key) ?? Number.POSITIVE_INFINITY;
+		const capability = matchKey(table instanceof Map ? table : new Map(), key);
+		return {
+			provider: route.provider,
+			model: route.model,
+			tier: anchorTier.get(key) ?? capability?.tier ?? null,
+			anchor,
+			score: capability?.score ?? Number.NEGATIVE_INFINITY,
+			fallback: index,
+		};
+	});
+	decorated.sort((a, b) => a.anchor - b.anchor || b.score - a.score || a.fallback - b.fallback);
+	return decorated.map(({ provider, model, tier }) => ({ provider, model, tier }));
+}
+
+/** Module-level cache for the bundled snapshot (undefined = not loaded yet). */
+let defaultsCache;
+
+/** Whether the load-failure warning already fired (warn once). */
+let defaultsWarned = false;
+
+/** Read host/data/capability-default.json into a capability table (cached).
+ *  On any read/parse failure the failure is cached as an empty table, the
+ *  warning fires once, and pool ordering degrades gracefully. */
+function loadCapabilityDefaults(logger) {
+	if (defaultsCache !== undefined) return defaultsCache;
+	try {
+		const raw = readFileSync(new URL("../data/capability-default.json", import.meta.url), "utf8");
+		defaultsCache = defaultTiers(JSON.parse(raw));
+	} catch (error) {
+		defaultsCache = new Map();
+		if (!defaultsWarned) {
+			defaultsWarned = true;
+			const warn = typeof logger?.warn === "function" ? logger.warn.bind(logger) : console.warn;
+			warn(`dsh-switchman: capability defaults unavailable (${error?.message ?? error}); pools fall back to configured order`);
+		}
+	}
+	return defaultsCache;
+}
+
+export {
+	capabilityOf,
+	defaultTiers,
+	isModelRoute,
+	loadCapabilityDefaults,
+	normalizeModelKey,
+	orderedPool,
+};