dsh-llm-fallbacks 0.4.2 → 0.4.3

package/dist/index.js

@@ -618,18 +618,25 @@ function hasWildcardEntry(roles, rootChain, role) {
 	} catch {}
 	return false;
 }
+function fitsContextWindow(candidate, minContextWindow, contextWindowOf) {
+	if (minContextWindow === void 0 || contextWindowOf === void 0) return true;
+	if (candidate.model === void 0) return true;
+	const candidateWindow = contextWindowOf(candidate.provider, candidate.model);
+	return candidateWindow === void 0 || candidateWindow > minContextWindow;
+}
 function createCandidateFilter(options) {
-	const { current, cooldown, failed, modelExists } = options;
+	const { current, cooldown, failed, modelExists, minContextWindow, contextWindowOf } = options;
 	return (candidate) => {
 		if (candidate.provider === current.provider && candidate.model === current.model) return false;
 		if (cooldown.isSuppressed(selectorKey(candidate.provider, candidate.model))) return false;
 		if (failed.has(selectorKey(candidate.provider, candidate.model))) return false;
+		if (!fitsContextWindow(candidate, minContextWindow, contextWindowOf)) return false;
 		if (modelExists && candidate.model !== void 0 && !modelExists(candidate.provider, candidate.model)) return false;
 		return true;
 	};
 }
 function annotateCandidates(candidates, surviving, options) {
-	const { current, cooldown, failed } = options;
+	const { current, cooldown, failed, minContextWindow, contextWindowOf } = options;
 	const usable = new Set(surviving.map((candidate) => selectorKey(candidate.provider, candidate.model)));
 	return candidates.map((candidate) => {
 		if (candidate.provider === current.provider && candidate.model === current.model) return {
@@ -646,6 +653,10 @@ function annotateCandidates(candidates, surviving, options) {
 			candidate,
 			skip: "step-failed"
 		};
+		if (!fitsContextWindow(candidate, minContextWindow, contextWindowOf)) return {
+			candidate,
+			skip: "context-window"
+		};
 		return {
 			candidate,
 			skip: "missing-id"
@@ -954,6 +965,7 @@ function overrideConfigWithRouteRule(seed, to, explicitEffort) {
 //#endregion
 //#region .build/host/gateway.js
 const FALLBACKS_SETTINGS_NAMESPACE = "fallbacks";
+const SUBAGENT_ROLES_MAX_IDS = 256;
 const CONFIG_KEYS = {
 	enabled: true,
 	triggerCodes: true,
@@ -988,11 +1000,13 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 	seeds;
 	settings;
 	subagentPolicy;
-	constructor(ctx, bridge, seeds, subagentPolicy) {
+	subagentRolesSnapshot;
+	constructor(ctx, bridge, seeds, subagentPolicy, subagentRoles) {
 		super(ctx, "fallbacks");
 		this.bridge = bridge;
 		this.seeds = seeds;
 		this.subagentPolicy = subagentPolicy;
+		this.subagentRolesSnapshot = subagentRoles;
 		ctx.inject(["settings"], (sctx) => {
 			this.settings = sctx.settings;
 			return () => {
@@ -1027,6 +1041,23 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 			outcome
 		};
 	}
+	subagentRoles(ids) {
+		if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string")) throw new TypeError("dsh-llm-fallbacks: subagent-roles ids must be an array of strings");
+		if (ids.length > SUBAGENT_ROLES_MAX_IDS) throw new TypeError(`dsh-llm-fallbacks: subagent-roles ids batch exceeds ${SUBAGENT_ROLES_MAX_IDS} entries`);
+		if (this.subagentRolesSnapshot === void 0) return {};
+		let records;
+		try {
+			records = this.subagentRolesSnapshot();
+		} catch {
+			return {};
+		}
+		const projected = new Map();
+		for (const id of ids) {
+			const record = records.get(id);
+			if (record !== void 0) projected.set(id, projectSubagentRoleRecord(record));
+		}
+		return Object.fromEntries(projected);
+	}
 	readConfig(source = this.bridge.source()) {
 		const wire = {};
 		for (const key of Object.keys(CONFIG_KEYS)) {
@@ -1093,6 +1124,17 @@ function projectSubagentPolicy(snapshot) {
 	};
 	return wire;
 }
+function projectSubagentRoleRecord(record) {
+	const wire = {
+		role: record.role,
+		at: record.at
+	};
+	if (record.model !== void 0) wire.model = {
+		provider: record.model.provider,
+		model: record.model.model
+	};
+	return wire;
+}
 function normalizeRoles(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
 	const roles = {};
@@ -1207,6 +1249,21 @@ function fallbacksTypertContribution() {
 					codec: { mode: "src-json" }
 				}],
 				result: { mode: "src-json" }
+			},
+			{
+				id: "dsh-llm-fallbacks#fallbacks/subagent-roles",
+				service: "fallbacks",
+				namespace: "fallbacks",
+				method: "subagent-roles",
+				implementation: "subagentRoles",
+				invocation: { kind: "direct" },
+				parameters: [{
+					name: "ids",
+					wire: "ids",
+					source: "json",
+					codec: { mode: "src-json" }
+				}],
+				result: { mode: "src-json" }
 			}
 		]
 	};
@@ -1544,13 +1601,14 @@ var FallbacksSeedManager = class {
 	constructor(logger) {
 		this.logger = logger;
 	}
-	async declare(seeds, io) {
+	async declare(seeds, io, options) {
 		const outcome = {
 			applied: [],
 			skipped: [],
 			conflicts: []
 		};
-		const registry = new Map();
+		const source = resolveSource(options, this.logger);
+		const entries = new Map();
 		for (const seed of seeds) {
 			if (typeof seed.id !== "string" || !ROLE_ID_PATTERN.test(seed.id)) {
 				outcome.skipped.push({
@@ -1568,7 +1626,7 @@ var FallbacksSeedManager = class {
 				this.warnSkip(seed.id, "reserved-id");
 				continue;
 			}
-			if (registry.has(seed.id)) {
+			if (entries.has(seed.id)) {
 				outcome.skipped.push({
 					id: seed.id,
 					reason: "duplicate-in-batch"
@@ -1576,33 +1634,37 @@ var FallbacksSeedManager = class {
 				this.warnSkip(seed.id, "duplicate-in-batch");
 				continue;
 			}
-			registry.set(seed.id, seed.persona);
+			entries.set(seed.id, {
+				persona: seed.persona,
+				set: source
+			});
 			outcome.applied.push(seed.id);
 		}
 		const config = io.read();
 		const currentList = roleRows(config);
 		const currentRules = roleRules(config);
-		const newList = materialize(currentList, registry, this.registry, outcome.conflicts);
+		const newList = materialize(currentList, personaView(entries), personaView(this.registry), outcome.conflicts);
 		for (const conflict of outcome.conflicts) this.logger.warn(`llm-fallbacks: seeds: persona-source conflict for seed id ${JSON.stringify(conflict.id)} — operator row persona kept (never overwritten)`);
 		const computed = {
 			list: newList,
 			rules: currentRules
 		};
 		if (!deepEqual(newList, currentList)) await io.writeRoles(computed);
-		this.registry = registry;
+		this.registry = entries;
 		return outcome;
 	}
 	effectiveRoles(io) {
 		return { roles: roleRows(io.read()).map((row) => {
-			const seedPersona = this.registry.get(row.id.trim());
-			const seeded = seedPersona !== void 0;
+			const entry = this.registry.get(row.id.trim());
+			const seeded = entry !== void 0;
 			const effective = {
 				id: row.id,
 				persona: row.persona,
 				seeded,
-				personaOverridden: seeded && row.persona !== seedPersona
+				personaOverridden: seeded && row.persona !== entry.persona,
+				source: seeded ? entry.set : "user"
 			};
-			if (seeded) effective.seedPersona = seedPersona;
+			if (seeded) effective.seedPersona = entry.persona;
 			if (row.chain !== void 0) effective.chain = row.chain;
 			if (row.fallback !== void 0) effective.fallback = row.fallback;
 			return effective;
@@ -1611,19 +1673,20 @@ var FallbacksSeedManager = class {
 	wireStatus(io) {
 		const status = [];
 		for (const row of roleRows(io.read())) {
-			const seedPersona = this.registry.get(row.id.trim());
-			if (seedPersona === void 0) continue;
+			const entry = this.registry.get(row.id.trim());
+			if (entry === void 0) continue;
 			status.push({
 				id: row.id,
-				overridden: row.persona !== seedPersona
+				overridden: row.persona !== entry.persona,
+				source: entry.set
 			});
 		}
 		return status;
 	}
 	async revert(id, io) {
 		const seedId = id.trim();
-		const seedPersona = this.registry.get(seedId);
-		if (seedPersona === void 0) return {
+		const entry = this.registry.get(seedId);
+		if (entry === void 0) return {
 			reverted: false,
 			reason: "not-seeded"
 		};
@@ -1635,13 +1698,13 @@ var FallbacksSeedManager = class {
 			reverted: false,
 			reason: "row-absent"
 		};
-		if (rows[index].persona === seedPersona) return {
+		if (rows[index].persona === entry.persona) return {
 			reverted: true,
-			persona: seedPersona
+			persona: entry.persona
 		};
 		const nextList = rows.map((row, i) => i === index ? {
 			...row,
-			persona: seedPersona
+			persona: entry.persona
 		} : row);
 		await io.writeRoles({
 			list: nextList,
@@ -1649,7 +1712,7 @@ var FallbacksSeedManager = class {
 		});
 		return {
 			reverted: true,
-			persona: seedPersona
+			persona: entry.persona
 		};
 	}
 	warnSkip(id, reason) {
@@ -1659,6 +1722,26 @@ var FallbacksSeedManager = class {
 		else this.logger.warn(`llm-fallbacks: seeds: skipping seed id ${shown} — duplicate-in-batch (first wins)`);
 	}
 };
+const RESERVED_SET_NAMES = [
+	"bundled",
+	"user",
+	"external"
+];
+function resolveSource(options, logger) {
+	if (options?.bundled === true) return "bundled";
+	const raw = options?.set;
+	if (raw === void 0) return "external";
+	if (typeof raw === "string" && raw.trim() !== "" && !RESERVED_SET_NAMES.includes(raw.trim())) return raw.trim();
+	const shown = typeof raw === "string" ? JSON.stringify(raw) : String(raw);
+	const reserved = RESERVED_SET_NAMES.map((name) => JSON.stringify(name)).join(" / ");
+	logger.warn(`llm-fallbacks: seeds: ignoring declare set name ${shown} — invalid (empty after trim, non-string, or a reserved label ${reserved}); provenance degrades to "external", the seeds still apply`);
+	return "external";
+}
+function personaView(entries) {
+	const personas = new Map();
+	for (const [id, entry] of entries) personas.set(id, entry.persona);
+	return personas;
+}
 function materialize(rows, registry, previous, conflicts) {
 	const next = [];
 	for (const row of rows) {
@@ -1733,14 +1816,6 @@ const presetRoles = [
 		id: "scout",
 		persona: "Read-only scout for exploratory codebase research, rapid analysis, and broad pattern search. Return compressed, structured findings another agent can reuse without re-reading the tree. Run searches in parallel; if a search is empty, try at least one alternate strategy before concluding the target is absent. Infer thoroughness from the task (quick, medium, or thorough; default medium); never write, edit, or run state-changing commands."
 	},
-	{
-		id: "designer",
-		persona: "UI/UX specialist for design implementation, review, and visual refinement. Analyze the existing design system first (tokens, theme, and primitives) and compose with it; if none exists, define a minimal system before implementing. Cover loading, empty, error, disabled, hover, and focus states; verify accessibility (contrast, focus rings, semantic HTML) and responsive layout. Avoid generic AI-slop patterns; in review, cite file and line with a concrete issue and a specific fix."
-	},
-	{
-		id: "librarian",
-		persona: "Research specialist for external libraries and APIs who returns definitive, source-verified answers. Treat source as truth, documentation as aspiration, and training data as history; prefer locally installed packages, then official docs. Cross-check at least two locations; copy API signatures verbatim and report the investigated version. Stay read-only on the user's project; if a lookup is empty, try at least two fallback strategies before concluding nothing exists."
-	},
 	{
 		id: "reviewer",
 		persona: "Code-review specialist for quality and security analysis of a patch before merge. Anchor every finding to the assigned diff; report only issues that are provable, actionable, unintentional, and introduced by the patch. For any new type, variant, or value that crosses a module boundary, inspect the consuming-side dispatch point. Rank findings P0 (blocks release) through P3 (nice to have); do not edit files or trigger builds."
@@ -2097,7 +2172,13 @@ function installTuiSettingsSection(ctx, opts) {
 	ctx.inject(["tuiSettingsSections"], (tctx) => {
 		const registry = tctx.tuiSettingsSections;
 		if (registry === void 0) return;
-		return registry.register(buildFallbacksTuiSection());
+		try {
+			return registry.register(buildFallbacksTuiSection());
+		} catch (error) {
+			if (!(error instanceof Error) || !error.message.includes("already registered")) throw error;
+			tctx.logger("llm-fallbacks").debug("llm-fallbacks: tui settings section already registered — no section on this fiber");
+			return () => {};
+		}
 	});
 }
 //#endregion
@@ -2259,6 +2340,8 @@ function installFallbacksAdapter(ctx, readConfig) {
 const name = "llm-fallbacks";
 const provide = ["llm-fallbacks"];
 const { version } = createRequire(import.meta.url)("../package.json");
+const CONTEXT_WINDOW_EXCEEDED_CODE = "CONTEXT_WINDOW_EXCEEDED";
+const REQUEST_SCOPED_CODES = new Set([CONTEXT_WINDOW_EXCEEDED_CODE]);
 const stateStores = new WeakMap();
 function stateStore(ctx) {
 	return stateStores.get(ctx);
@@ -2271,6 +2354,10 @@ const chainHeadStores = new WeakMap();
 function chainHeads(ctx) {
 	return chainHeadStores.get(ctx);
 }
+const subagentRoleRecordStores = new WeakMap();
+function subagentRoleRecords(ctx) {
+	return subagentRoleRecordStores.get(ctx);
+}
 function latestByAt(map) {
 	let latest;
 	for (const value of map.values()) if (latest === void 0 || value.at >= latest.at) latest = value;
@@ -2290,6 +2377,26 @@ async function makeModelExists(ctx, providers) {
 	}));
 	return (provider, model) => catalog.get(provider)?.has(model) ?? false;
 }
+async function makeContextWindowOf(ctx, routes) {
+	const llm = ctx.get("llm");
+	if (llm === void 0) return () => void 0;
+	const windows = new Map();
+	if (typeof llm.listModels === "function") await Promise.all([...new Set(routes.map((route) => route.provider))].map(async (provider) => {
+		try {
+			for (const model of await llm.listModels(provider)) if (typeof model.contextWindow === "number") windows.set(selectorKey(provider, model.id), model.contextWindow);
+		} catch {}
+	}));
+	const resolveModelInfo = llm.resolveModelInfo?.bind(llm);
+	if (resolveModelInfo !== void 0) await Promise.all(routes.map(async (route) => {
+		const key = selectorKey(route.provider, route.model);
+		if (windows.has(key)) return;
+		try {
+			const window = (await resolveModelInfo(route.provider, route.model))?.context?.contextWindow;
+			if (typeof window === "number") windows.set(key, window);
+		} catch {}
+	}));
+	return (provider, model) => windows.get(selectorKey(provider, model));
+}
 function countRetryEvents(session, turn, step, provider) {
 	let count = 0;
 	const events = session.snapshotEvents();
@@ -2367,6 +2474,24 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	};
 	ctx.inject(["settings"], (sctx) => {
 		writeRoles = (roles) => sctx.settings.update(FALLBACKS_SETTINGS_NAMESPACE, { roles });
+		try {
+			sctx.provide("llm-fallbacks", {
+				name: "llm-fallbacks",
+				version,
+				resolveRole,
+				resolveChain,
+				validateFallbacksConfig,
+				detectLegacyKeys,
+				declareSeeds: (declarations, options) => seeds.declare(declarations, seedsIo, options?.set === void 0 ? void 0 : { set: options.set }),
+				getEffectiveRoles: () => seeds.effectiveRoles(seedsIo),
+				revertSeededPersona: (id) => seeds.revert(id, seedsIo)
+			});
+			serviceOwned = true;
+		} catch (error) {
+			serviceOwned = false;
+			if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
+			ctx.logger("llm-fallbacks").debug("fallbacks service already registered — no service on this fiber (multi-fiber dedupe)");
+		}
 		return () => {
 			writeRoles = () => {
 				throw new Error(seedsSettingsUnavailable);
@@ -2377,25 +2502,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		read: () => source(),
 		writeRoles: (roles) => writeRoles(roles)
 	};
-	let serviceOwned = false;
-	try {
-		ctx.provide("llm-fallbacks", {
-			name: "llm-fallbacks",
-			version,
-			resolveRole,
-			resolveChain,
-			validateFallbacksConfig,
-			detectLegacyKeys,
-			declareSeeds: (declarations) => seeds.declare(declarations, seedsIo),
-			getEffectiveRoles: () => seeds.effectiveRoles(seedsIo),
-			revertSeededPersona: (id) => seeds.revert(id, seedsIo)
-		});
-		serviceOwned = true;
-	} catch (error) {
-		if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
-		serviceOwned = false;
-		ctx.logger("llm-fallbacks").debug("fallbacks service already registered — no service on this fiber (multi-fiber dedupe)");
-	}
+	let serviceOwned = ctx.get("llm-fallbacks") === void 0;
 	let source = () => entry;
 	const reconcileFallbacksAdapter = installFallbacksAdapter(ctx, () => source());
 	validateFallbacksConfig(entry, logger);
@@ -2422,6 +2529,8 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	chainHeadStores.set(ctx, chainHeadMap);
 	const blockedAttemptMap = new Map();
 	blockedAttemptStores.set(ctx, blockedAttemptMap);
+	const subagentRoleRecordMap = new Map();
+	subagentRoleRecordStores.set(ctx, subagentRoleRecordMap);
 	try {
 		new FallbacksConfigGateway(ctx, bridge, seeds, () => {
 			try {
@@ -2436,7 +2545,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 			} catch {
 				return { policy: { state: "unprovable" } };
 			}
-		});
+		}, () => subagentRoleRecordMap);
 	} catch (error) {
 		if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
 		ctx.logger("llm-fallbacks").debug("fallbacks gateway already registered — no gateway on this fiber (multi-fiber dedupe)");
@@ -2455,7 +2564,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	const dispatchInjected = new Set();
 	const slotWinners = new Map();
 	const lastKnownPolicySettings = new Map();
-	async function decide(agent, turn, step, current, reason, state) {
+	async function decide(agent, turn, step, current, reason, state, failureCode) {
 		const config = source();
 		if (state !== void 0) {
 			states.syncStep(state, turn, step);
@@ -2468,10 +2577,17 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		const modelExists = hasWildcardEntry(config.roles.list, rootTail, role) ? await makeModelExists(ctx, [...new Set(all.map((candidate) => candidate.provider))]) : void 0;
 		const cooldown = { isSuppressed: (key) => state !== void 0 && states.isSuppressed(state, key, Date.now(), source().recovery ?? "timer") };
 		const failed = { has: (key) => state !== void 0 && state.stepFailures.failed.has(key) };
+		const contextWindowOf = failureCode === CONTEXT_WINDOW_EXCEEDED_CODE ? await makeContextWindowOf(ctx, [current, ...all.flatMap((candidate) => candidate.model === void 0 ? [] : [{
+			provider: candidate.provider,
+			model: candidate.model
+		}])]) : void 0;
+		const minContextWindow = contextWindowOf?.(current.provider, current.model);
 		const surviving = selectCandidates(all, wildcard, createCandidateFilter({
 			current,
 			cooldown,
-			failed
+			failed,
+			minContextWindow,
+			contextWindowOf
 		}), modelExists);
 		const first = surviving[0];
 		let target;
@@ -2511,7 +2627,9 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		logger.info("llm-fallbacks: agent \"%s\" fallback switch (降级切换) %s/%s -> %s/%s (role=%s, reason=%s, candidates=%o)", agent.id, current.provider, current.model, target.provider, target.model, role, reason, annotateCandidates(all, surviving, {
 			current,
 			cooldown,
-			failed
+			failed,
+			minContextWindow,
+			contextWindowOf
 		}).map(({ candidate, skip }) => skip === void 0 ? `${candidate.provider}/${candidate.model}` : `${candidate.provider}/${candidate.model} (skipped: ${skip})`));
 		return {
 			from: {
@@ -2529,10 +2647,12 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	function commit(state, pending, turn, step) {
 		const config = source();
 		const fromKey = selectorKey(pending.from.provider, pending.from.model);
-		const until = config.revertPolicy === "never" ? Number.POSITIVE_INFINITY : config.recovery === "half-open" ? Date.now() + escalatedCooldownMs(config.cooldownMs, state.recovery.recordFailure(fromKey)) : Date.now() + config.cooldownMs;
 		states.syncStep(state, turn, step);
 		states.writePending(state, pending);
-		states.suppress(state, fromKey, until);
+		if ((pending.scope ?? "route") === "route") {
+			const until = config.revertPolicy === "never" ? Number.POSITIVE_INFINITY : config.recovery === "half-open" ? Date.now() + escalatedCooldownMs(config.cooldownMs, state.recovery.recordFailure(fromKey)) : Date.now() + config.cooldownMs;
+			states.suppress(state, fromKey, until);
+		}
 		states.recordFailure(state, fromKey);
 		states.recordSwitch(state);
 	}
@@ -2551,12 +2671,16 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		const current = currentModel(agent, provider);
 		if (!current.model) return next();
 		try {
-			const pending = await decide(agent, turn, step, current, "trigger-code", states.peek(agent.id));
+			const pending = await decide(agent, turn, step, current, "trigger-code", states.peek(agent.id), failure.code);
 			if (pending === null) {
 				failHalfOpenProbe(agent.id, current);
 				return next();
 			}
-			commit(states.get(agent.id), pending, turn, step);
+			const scope = REQUEST_SCOPED_CODES.has(failure.code) ? "request" : void 0;
+			commit(states.get(agent.id), scope === void 0 ? pending : {
+				...pending,
+				scope
+			}, turn, step);
 			return { kind: "retry" };
 		} catch (error) {
 			logger.warn("llm-fallbacks: decision path failed, passing the original failure through: %s", error?.message ?? String(error));
@@ -2628,6 +2752,14 @@ function apply(ctx, config = defaultFallbacksConfig) {
 									model: head.model
 								};
 							}
+							subagentRoleRecordMap.set(agent.id, {
+								role,
+								model: to ?? {
+									provider: seed.provider,
+									model: seed.model
+								},
+								at: Date.now()
+							});
 							if (to !== void 0 && !(to.provider === seed.provider && to.model === seed.model)) {
 								if (policy.state === "enabled") chainHeadMap.set(agent.id, {
 									at: Date.now(),
@@ -2676,6 +2808,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		slotWinners.delete(agent.id);
 		blockedAttemptMap.delete(agent.id);
 		chainHeadMap.delete(agent.id);
+		subagentRoleRecordMap.delete(agent.id);
 		lastKnownPolicySettings.delete(agent.id);
 	});
 	ctx.on("session/event", (session, event) => {
@@ -2694,6 +2827,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		slotWinners.clear();
 		blockedAttemptMap.clear();
 		chainHeadMap.clear();
+		subagentRoleRecordMap.clear();
 		lastKnownPolicySettings.clear();
 	}, "llm-fallbacks: clear per-agent state");
 	const fallbacksCommandController = {
@@ -2766,10 +2900,10 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	ctx.inject(["settings"], () => {
 		if (!serviceOwned) return;
 		if (seedsIo.read().presets === "none") return;
-		seeds.declare(presetRoles, seedsIo).catch((error) => {
+		seeds.declare(presetRoles, seedsIo, { bundled: true }).catch((error) => {
 			logger.error("llm-fallbacks: seeds: preset role declaration failed — %s", error?.message ?? String(error));
 		});
 	});
 }
 //#endregion
-export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, blockedAttempts, chainHeads, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };
+export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, blockedAttempts, chainHeads, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, subagentRoleRecords, validateFallbacksConfig };

package/dist/presets.d.ts

@@ -1,17 +1,20 @@
 /**
- * Bundled preset role declarations (plan fallbacks-preset-roles Task 1).
+ * Bundled preset role declarations (plan fallbacks-preset-roles Task 1;
+ * trimmed 7 → 5 by the seed-source-provenance plan, D4).
  *
  * Derivation: distilled from the omp bundled agent prompts —
- * `packages/coding-agent/src/prompts/agents/{scout,designer,librarian,reviewer,security-reviewer}.md`
+ * `packages/coding-agent/src/prompts/agents/{scout,reviewer,security-reviewer}.md`
  * and `task.md` (task/sonic share the body; frontmatter injected in
  * `src/task/agents.ts`) — snapshot date 2026-08-16. Each persona is a
  * concise distillation (frontmatter description + core directives), NOT a
  * verbatim copy of the full prompt; the frozen text lives in spec
- * `fallbacks-preset-roles-spec.md` §9.2 (implementer SSOT).
+ * `fallbacks-preset-roles-spec.md` §9.2 (implementer SSOT). `designer` and
+ * `librarian` were removed from the bundled set; rows persisted by earlier
+ * versions survive untouched (they read back with source `user`).
  *
  * Pure data module: no io, no side effects, no classes. Types import only
  * `./seeds.ts` — no `@deepseek-ai/*` imports (bundle purity gate).
  */
 import type { SeedDeclaration } from './seeds.ts';
-/** The 7 bundled omp-style preset roles (spec §9.1 shape, §9.2 personas). */
+/** The 5 bundled omp-style preset roles (spec §9.1 shape, §9.2 personas). */
 export declare const presetRoles: readonly SeedDeclaration[];

package/dist/seeds.d.ts

@@ -11,10 +11,13 @@
  * State model (spec §9.2) — two stores, strictly separated:
  * 1. operator config rows (persisted; a seeded role is a plain
  *    `roles.list` row `{ id, persona }`), and
- * 2. an in-memory per-apply seed registry (`Map<id, seedPersona>`),
- *    declare = replacement (the batch is the companion's full current set).
- * `seeded` / `personaOverridden` are DERIVED at read time, never stored —
- * a config round-trip cannot orphan an override (AC-3).
+ * 2. an in-memory per-apply seed registry (`Map<id, { persona, set }>` —
+ *    the declared default persona plus its provenance label), declare =
+ *    replacement (the batch is the companion's full current set).
+ * `seeded` / `personaOverridden` / `source` are DERIVED at read time, never
+ * stored — a config round-trip cannot orphan an override (AC-3), and
+ * provenance rides the in-memory registry only, so it can never churn a
+ * settings write.
  *
  * Materialization (spec §9.2): append `{ id, persona }` (two keys only,
  * R4) / attach row untouched / at-default tracking / override preserved +
@@ -31,6 +34,41 @@ export interface SeedDeclaration {
     id: string;
     persona: string;
 }
+/**
+ * Per-row provenance label (spec §2). The fixed labels: `bundled` (the
+ * plugin's own bundled preset self-declare), `external` (a companion
+ * declare without a set name — or with an invalid one, degraded), `user`
+ * (no live declaration). Any other value is a declared set name; the
+ * reserved names can never be declared as a set, so the fixed labels are
+ * unambiguous.
+ */
+export type SeedSource = 'bundled' | 'external' | 'user' | (string & {});
+/**
+ * Optional provenance for one `declare()` call (spec §2) — the PUBLIC
+ * options face (a companion's registered set name). This is also the type
+ * of the `FallbacksService.declareSeeds` second parameter: consumers can
+ * never label a declare `bundled` (reserved).
+ */
+export interface SeedsDeclareOptions {
+    /**
+     * Registered set name — trimmed. Empty after trim, non-string, or a
+     * reserved value (`bundled` / `user` / `external`) warns once and
+     * degrades the batch to the unnamed `external` source; the seeds still
+     * apply (a bad label must never drop roles).
+     */
+    set?: string;
+}
+/**
+ * The manager-level declare options — the public face plus the INTERNAL
+ * bundled marker for the plugin's own preset self-declare. Module-internal
+ * (never exported, never re-exported from the package root): only the
+ * preset child call site passes `bundled`, and only a structurally-checked
+ * object literal at that — the type itself is not nameable by consumers.
+ */
+interface SeedsInternalDeclareOptions extends SeedsDeclareOptions {
+    /** INTERNAL — bundled preset self-declare provenance. Not a consumer option. */
+    bundled?: true;
+}
 /**
  * Why one declared id was skipped (spec §9.1). Per-id skip + warn, never
  * coercion — valid siblings in the same batch still apply (AC-5).
@@ -68,6 +106,8 @@ export interface EffectiveRole {
     seeded: boolean;
     /** `seeded` && row persona !== current seed default. */
     personaOverridden: boolean;
+    /** Where the row's seed state comes from (read-time derived, never persisted) — `user` iff not seeded. */
+    source: SeedSource;
     /** Present iff seeded. */
     seedPersona?: string;
 }
@@ -86,6 +126,12 @@ export interface SeedRevertOutcome {
 export interface SeedsWireStatus {
     id: string;
     overridden: boolean;
+    /**
+     * Provenance label (spec §2) — additive and OPTIONAL on the wire: a
+     * gateway predating the field (version skew) sends entries without it;
+     * consumers treat a missing label as "no badge".
+     */
+    source?: SeedSource;
 }
 /**
  * The narrow IO seam this module writes through — keeps `src/seeds.ts`
@@ -105,6 +151,7 @@ export interface SeedsIo {
  */
 export declare class FallbacksSeedManager {
     private readonly logger;
+    /** Per-apply declaration registry: declared default persona + provenance label. */
     private registry;
     constructor(logger: FallbacksConfigLogger);
     /**
@@ -112,6 +159,10 @@ export declare class FallbacksSeedManager {
      * companion's FULL current declaration set; ids omitted from the batch
      * drop out of the registry while their rows remain (R2).
      *
+     * `options` labels the whole batch's provenance (spec §2), resolved once
+     * per call: an invalid set name warns once and degrades to the unnamed
+     * `external` case — the seeds still apply.
+     *
      * Per-id validation AS DECLARED (spec §9.3): non-string / pattern miss /
      * reserved `inherit` / duplicate-in-batch → skip + warn; valid siblings
      * still apply (AC-5). Materializes per spec §9.2, writes only when the
@@ -119,15 +170,17 @@ export declare class FallbacksSeedManager {
      * (idempotent, AC-1), and commits the registry only after a successful
      * write (compute → write → commit; retry-safe).
      */
-    declare(seeds: readonly SeedDeclaration[], io: SeedsIo): Promise<SeedDeclareOutcome>;
+    declare(seeds: readonly SeedDeclaration[], io: SeedsIo, options?: SeedsInternalDeclareOptions): Promise<SeedDeclareOutcome>;
     /**
      * Readback (b) — sync, derived: every config row annotated with
      * `seeded` / `personaOverridden` / `seedPersona` (trimmed row-id
-     * membership in the live declaration set; persona inequality). Nothing
+     * membership in the live declaration set; persona inequality) plus the
+     * row's provenance `source` (spec §2): the declaring set's label, or
+     * `user` when no live declaration covers the row. Nothing
      * override-shaped is stored, so a config round-trip cannot orphan state.
      */
     effectiveRoles(io: SeedsIo): EffectiveRolesReadback;
-    /** Card badge state (spec §9.4): seeded rows, with the override flag. */
+    /** Card badge state (spec §9.4): seeded rows, with the override flag and the provenance label. */
     wireStatus(io: SeedsIo): SeedsWireStatus[];
     /**
      * Revert one id to the CURRENT declared seed default (AC-3). Writes
@@ -139,3 +192,4 @@ export declare class FallbacksSeedManager {
     revert(id: string, io: SeedsIo): Promise<SeedRevertOutcome>;
     private warnSkip;
 }
+export {};