dsh-switchman 1.3.0 → 1.5.0

package/host/dispatch.js

@@ -62,10 +62,87 @@ function readBool(field) {
 	return field === true;
 }
 
+/** The rank.js model-segment extraction, verbatim (rank.js's
+ *  normalizeModelKey ~lines 32-44): lowercase/trim, strip a `provider/` or
+ *  bare-provider `provider:` prefix, drop `(...)`/`[...]` variant segments,
+ *  fold illegal chars into "-" and trim edge punctuation. */
+function modelSegment(model) {
+	let s = typeof model === "string" ? model : "";
+	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, "");
+}
+
+/** Provider-exact identity of one (provider, model) route for the drift
+ *  comparison ONLY. normalizeModelKey builds capability-table keys: it
+ *  folds away the provider and keeps just the model's last segment, so an
+ *  authorized `b/m` would falsely clear pool entry `a/m` — but DSH
+ *  authorizes exact (provider, model) pairs. Returns
+ *  `provider + "\u0000" + modelSegment`, or "" when either side is empty
+ *  ("" never matches an authorized key). */
+function routeIdentity(provider, model) {
+	const p = typeof provider === "string" ? provider.trim() : "";
+	const m = modelSegment(model);
+	return p === "" || m === "" ? "" : `${p}\u0000${m}`;
+}
+
+/** The session's child-model authorization snapshot, read from the DSH
+ *  host's `subagentModelSelection` service WITHOUT declaring inject (the
+ *  same fail-open pattern routes.js's modelCatalogOf uses). The persisted
+ *  shape names the list `allowedModels` while the inspect contract says
+ *  `routes` — both are accepted. Keys are provider-exact route identities
+ *  (routeIdentity), NOT capability-table keys: DSH authorizes exact
+ *  (provider, model) pairs. Any missing service, error, or malformed
+ *  value degrades to null: unknown means "render nothing", and this file
+ *  family never throws on degraded capability. When enabled === false no
+ *  explicit child model selection is allowed at all, so every pool route
+ *  counts as unauthorized. */
+function authorizedChildRoutes(ctx) {
+	let service;
+	try {
+		service = typeof ctx?.get === "function" ? ctx.get("subagentModelSelection", false) : undefined;
+	} catch {
+		return null;
+	}
+	if (service === undefined || service === null || typeof service.current !== "function") return null;
+	try {
+		const snapshot = service.current();
+		if (snapshot === null || typeof snapshot !== "object" || typeof snapshot.enabled !== "boolean") return null;
+		const listed = Array.isArray(snapshot.routes)
+			? snapshot.routes
+			: Array.isArray(snapshot.allowedModels)
+				? snapshot.allowedModels
+				: [];
+		const routes = [];
+		const keys = new Set();
+		for (const entry of listed) {
+			if (!isModelRoute(entry)) continue;
+			const key = routeIdentity(entry.provider, entry.model);
+			if (key === "") continue;
+			keys.add(key);
+			routes.push({ provider: entry.provider, model: entry.model });
+		}
+		return { enabled: snapshot.enabled, keys, routes };
+	} catch {
+		return null;
+	}
+}
+
 /** 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. */
+ *  `efforts` holds the lane's manually pinned reasoning efforts.
+ *  `authorized` is the DSH-side child-model whitelist snapshot (null when
+ *  unreadable — drift markers are then omitted). The detection only runs
+ *  while teamsMode is ON: OFF removes it entirely (authorized stays null, so
+ *  the ⚠not-authorized markers and their guidance never render), while the
+ *  dispatchEnforce pool gate below is untouched. */
 function readDispatchState(ctx, config) {
 	const lanePools = LANES.map((lane) => ({
 		lane,
@@ -78,6 +155,7 @@ function readDispatchState(ctx, config) {
 		modelRank: readList(config.modelRank).filter(isModelRoute),
 		enforce: readField(config.dispatchEnforce),
 		defaults: loadCapabilityDefaults(ctx?.logger),
+		authorized: readBool(config.teamsMode) === true ? authorizedChildRoutes(ctx) : null,
 	};
 }
 
@@ -100,15 +178,28 @@ function effortMapOf(pool) {
 }
 
 /** The `[SWITCHMAN:POOLS]` block: anchor line, one line per configured lane,
- *  then the guidance lines (byte-stable for a given configuration). */
+ *  then the guidance lines (byte-stable for a given configuration). Routes
+ *  outside the session's DSH-authorized child models carry a ⚠not-authorized
+ *  marker (after any @effort suffix) — teams mode only: with teamsMode OFF
+ *  the whitelist is never read, `state.authorized` stays null, and neither
+ *  the markers nor the drift guidance lines render. */
 function renderPoolsBlock(state) {
 	const configured = state.lanePools.filter((pool) => pool.routes.length > 0);
 	const lines = [`[SWITCHMAN:POOLS] configured=${configured.length}/6 enforce=${state.enforce}`];
+	let anyUnauthorized = false;
 	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))
+			.map((entry) => {
+				const rendered = renderRoute(entry, effortOf.get(normalizeModelKey(entry.provider, entry.model)) ?? null);
+				if (state.authorized === null) return rendered;
+				if (state.authorized.enabled === false || !state.authorized.keys.has(routeIdentity(entry.provider, entry.model))) {
+					anyUnauthorized = true;
+					return `${rendered} ⚠not-authorized`;
+				}
+				return rendered;
+			})
 			.join(", ");
 		lines.push(`${pool.lane}${pool.manual ? "*" : ""}: ${routes}`);
 	}
@@ -117,10 +208,20 @@ function renderPoolsBlock(state) {
 		`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).`,
+		`Review delegations: anchor independence on the code AUTHOR's model, not the main session's (author = the agent that produced the diff: its explicit dispatch route, or the inherited session model when unspecified). Prefer a reviewer model different from the author's; also avoiding the session model is a bonus (its integration pass already covers that angle). If no pool entry differs from the author, same-model review is allowed — declare DOWNGRADED and state whether it is relative to the author or the session.`,
+		`Explicit provider/model/effort on subagent/workflow calls is validated against this session's DSH-authorized child models (DSH Settings: allow agents to choose subagent models) — NOT against this table; when denied, discover allowed routes via list_subagent_models, or dispatch implicitly by omitting all three fields (the child then uses configured defaults or inherits the parent route).`,
+	);
+	if (anyUnauthorized) {
+		lines.push(
+			state.authorized.enabled === false
+				? `All routes above are marked ⚠not-authorized because explicit child model selection is currently disabled in DSH Settings (subagents: model selection) — every explicit provider/model/effort dispatch is denied; dispatch implicitly by omitting those fields until it is re-enabled.`
+				: `Routes marked ⚠not-authorized are pool entries outside this session's DSH-authorized child models — authorize them in DSH Settings (subagents: model selection), or dispatch them implicitly by omitting provider/model/effort.`,
+		);
+	}
+	lines.push(
 		`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)"
+				? ". In addition, in enforce mode: subagent calls naming a provider+model outside the pools or modelRank are denied"
 				: ""
 		}.`,
 	);
@@ -202,4 +303,4 @@ function applyDispatch(ctx, config) {
 	});
 }
 
-export { applyDispatch };
+export { applyDispatch, authorizedChildRoutes };

package/host/handover-state.js

@@ -0,0 +1,38 @@
+/**
+ * Shared in-flight handover registry (process-lifetime, never persisted).
+ *
+ * context-watch.js records phase transitions from the first synchronous
+ * line of runHandover (t=0, before the fork even starts); routes.js
+ * exposes the read-only snapshot behind GET /api/dsh-switchman/
+ * handover-state so the client badge can show a live "handover in
+ * progress" cue during the otherwise-silent fork+compact window.
+ */
+
+/** sessionId -> { sessionId, phase, source?, attempt?, at }. */
+const inflight = new Map();
+
+/**
+ * Record (or overwrite) the live phase of one session's handover.
+ * @param {string} sessionId - the root session being handed over.
+ * @param {object} info - { phase: "backup"|"compacting"|"continuation",
+ *   source?: "manual"|"tool"|"auto", attempt?: number, at: number }.
+ */
+export function recordHandover(sessionId, info) {
+	if (sessionId === null || sessionId === undefined) return;
+	inflight.set(sessionId, { ...info, sessionId });
+}
+
+/** Drop the record once the handover settles (success or failure). */
+export function clearHandover(sessionId) {
+	inflight.delete(sessionId);
+}
+
+/** Live record for one session, or undefined. */
+export function handoverOf(sessionId) {
+	return inflight.get(sessionId);
+}
+
+/** Read-only array snapshot of every in-flight handover. */
+export function handoverSnapshot() {
+	return [...inflight.values()];
+}

package/host/lang.js

@@ -1,22 +1,44 @@
 /** 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
+ * (oc/src/lang-config.ts, oc/src/index.ts:1594-1604) onto DSH services.
+ * Two storage scopes for the three language slots (conversation / comments /
+ * docs), selected by the `langScope` setting:
+ *
+ *  - "global"  — this plugin's profile-level volatile settings fields (live
+ *    references, re-read at every assembly; ask-once latch per process);
+ *  - "project" — a per-project `<cwd>/.switchman/lang.json`, resolved from
+ *    each session's own working directory (`context.agent.session.header.
+ *    cwd`, the same source the watermark handover and dsh-agent-loop's
+ *    "cwd" variable use). A session without a usable file is
+ *    "unconfigured": it gets the one-shot ask guidance (latched per
+ *    session, so every new session asks again until the file exists) and
+ *    the captured answers are written into that file. A session whose
+ *    header carries no cwd falls back to the global fields (fail-open).
+ *
+ * The per-model-request system transform becomes one dynamic systemPrompt
+ * section (order 10300, after the persona suffix at 10200); the
  * tool.execute.after capture becomes a `tools/post-execute` waterfall
- * listener.
+ * listener. The text callback must stay synchronous (dsh-system-prompt
+ * calls it without await), so project files are read with readFileSync —
+ * a sub-100-byte JSON once per step per session.
  *
- * 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
+ * Model-facing protocol text is English and byte-stable: the configured
+ * `[SWITCHMAN:LANG]` anchor line is a function of the effective values
+ * only and never varies with UI locale, so bundled skills can match it
+ * textually. The unconfigured ask guidance additionally names the language
+ * to phrase the three questions in — the DSH UI language when known
+ * (explicit settings preference, else the client-reported active locale,
+ * else English). All parsing is defensive — any unexpected shape abandons
  * silently (fail-open) and never disturbs the tool result flowing through
  * the waterfall. Zero new dependencies.
  */
 
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { reportedUiLocale } from "./ui-locale.js";
+
 /** Marker embedded in the ask's question texts and matched on capture. */
 const LANG_ASK_MARKER = "switchman-lang";
 
@@ -26,6 +48,13 @@ const MAX_LANG_LEN = 48;
 /** Anchor-line value shown for an empty comments/docs field (= follow conversation). */
 const SAME = "same";
 
+/** Project-scope config directory and file name (inside the session cwd). */
+const PROJECT_DIR = ".switchman";
+const PROJECT_FILE = "lang.json";
+
+/** How long a cached settings-describe locale stays fresh (ms). */
+const LOCALE_CACHE_MS = 10_000;
+
 /** Normalize one language value: trim and bound the length; anything else → null. */
 function normalizeLangValue(value) {
 	if (typeof value !== "string") return null;
@@ -47,6 +76,11 @@ function readField(field) {
 	return typeof field === "string" ? field : "";
 }
 
+/** Current scope setting: "project" when explicitly chosen, else "global". */
+function readScope(config) {
+	return readField(config?.langScope) === "project" ? "project" : "global";
+}
+
 /** Current language-preference snapshot from the live plugin config. */
 function readLangPref(config) {
 	return {
@@ -56,6 +90,52 @@ function readLangPref(config) {
 	};
 }
 
+/** Parse the project file's three slots; null when missing/broken/empty-file.
+ *  Same semantics as the global fields: comments/docs "" = follow conversation. */
+function readProjectPref(cwd) {
+	let raw;
+	try {
+		raw = readFileSync(join(cwd, PROJECT_DIR, PROJECT_FILE), "utf8");
+	} catch {
+		return null;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+	const conversation = normalizeLangValue(parsed.langConversation);
+	if (conversation === null) return null;
+	return {
+		conversation,
+		comments: normalizeLangValue(parsed.langComments) ?? "",
+		docs: normalizeLangValue(parsed.langDocs) ?? "",
+	};
+}
+
+/** Persist a captured preference as the project's `<cwd>/.switchman/lang.json`. */
+function writeProjectPref(cwd, pref) {
+	const directory = join(cwd, PROJECT_DIR);
+	const path = join(directory, PROJECT_FILE);
+	mkdirSync(directory, { recursive: true });
+	writeFileSync(
+		path,
+		`${JSON.stringify(
+			{
+				langConversation: pref.conversation,
+				langComments: pref.comments,
+				langDocs: pref.docs,
+			},
+			null,
+			"\t",
+		)}\n`,
+		"utf8",
+	);
+	return path;
+}
+
 /** Configured block: byte-stable anchor line + English iron rules. */
 function renderLangBlock(pref) {
 	const anchor = (value) => (value === "" ? SAME : value);
@@ -71,13 +151,15 @@ function renderLangBlock(pref) {
 	].join("\n");
 }
 
-/** Unconfigured block: gentle one-shot ask guidance (English, ≤6 lines, never blocking). */
-function renderAskGuidance() {
+/** Unconfigured block: gentle one-shot ask guidance (English, ≤7 lines, never
+ *  blocking). `askLanguage` names the language to phrase the questions in. */
+function renderAskGuidance(askLanguage) {
 	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.`,
+		`Phrase the three questions and their answer options in ${askLanguage} (the user's UI language).`,
 		`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");
@@ -125,23 +207,94 @@ function parseLangAnswers(questions, value) {
 	return { conversation, comments: follow(rawAnswer(slots[1])), docs: follow(rawAnswer(slots[2])) };
 }
 
+/** Session id off an agent (shared agent/session id; null when unusable). */
+function sessionIdOf(agent) {
+	const id = agent?.session?.id ?? agent?.id;
+	return typeof id === "string" && id !== "" ? id : null;
+}
+
+/** True when the agent is a runtime root (owner-less); unknown registries
+ *  count as root. Subagents cannot reach the user, so only roots may ask. */
+function isRoot(ctx, agent) {
+	try {
+		const roots = ctx.agents?.roots?.();
+		return !Array.isArray(roots) || roots.includes(agent);
+	} catch {
+		return true;
+	}
+}
+
+/** Read the explicit DSH UI-language preference (settings ns "locale", field
+ *  "preference"; "" when unset/unreadable). Cached — describe() serializes
+ *  every settings schema, and the section text runs once per step. */
+function readLocalePreference(ctx, cache) {
+	const now = Date.now();
+	if (cache.tag !== null && now - cache.at < LOCALE_CACHE_MS) return cache.tag;
+	cache.at = now;
+	try {
+		const described = ctx.settings?.describe?.();
+		if (Array.isArray(described)) {
+			const row = described.find((entry) => entry?.ns === "locale");
+			const preference = row?.value?.preference;
+			cache.tag = typeof preference === "string" ? preference.trim().toLowerCase() : "";
+			return cache.tag;
+		}
+	} catch {
+		// fall through
+	}
+	cache.tag = "";
+	return cache.tag;
+}
+
+/** Language name the ask guidance tells the agent to phrase questions in. */
+function askLanguageOf(ctx, cache) {
+	const tag = readLocalePreference(ctx, cache) || reportedUiLocale();
+	return tag.startsWith("zh") ? "Chinese (简体中文)" : "English";
+}
+
 /** 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(). */
+ *  `exec` here is the prepared ToolExecution ({ name, arguments, agent, ... })
+ *  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). */
+	/** Global-scope ask latch (one ask per process, declined counts). */
 	let asked = false;
+	/** Project-scope ask latches, per session id (each new session may ask). */
+	const askedSessions = new Set();
+	/** Cached locale-preference read (see readLocalePreference). */
+	const localeCache = { at: 0, tag: null };
+
+	/** Effective preference for one assembly: project scope reads the
+	 *  session's project file only (a missing file counts as unconfigured
+	 *  and asks — global fields never shadow it); a session without a
+	 *  usable cwd degrades to the global fields (fail-open). */
+	const effectivePref = (context) => {
+		if (readScope(config) !== "project") return readLangPref(config);
+		const cwd = context?.agent?.session?.header?.cwd;
+		if (typeof cwd !== "string" || cwd === "") return readLangPref(config);
+		return readProjectPref(cwd) ?? { conversation: "", comments: "", docs: "" };
+	};
 
 	ctx.systemPrompt.section({
 		name: "switchman:lang",
 		order: 10300,
 		interpolate: false,
-		text: () => {
-			const pref = readLangPref(config);
-			if (pref.conversation !== "") return renderLangBlock(pref);
-			return asked ? "" : renderAskGuidance();
+		text: (context) => {
+			try {
+				const agent = context?.agent;
+				const pref = effectivePref(context);
+				if (pref.conversation !== "") return renderLangBlock(pref);
+				// Unconfigured: one ask per process (global) or per session
+				// (project); subagents never see the ask guidance.
+				if (readScope(config) === "project") {
+					const sessionId = sessionIdOf(agent);
+					if (sessionId !== null ? askedSessions.has(sessionId) : asked) return "";
+				} else if (asked) return "";
+				if (!isRoot(ctx, agent)) return "";
+				return renderAskGuidance(askLanguageOf(ctx, localeCache));
+			} catch {
+				return "";
+			}
 		},
 	});
 
@@ -150,25 +303,47 @@ function applyLanguage(ctx, config) {
 			if (exec?.name === "ask_user_question") {
 				const questions = markerQuestions(exec.arguments);
 				if (questions.length > 0) {
-					asked = true;
+					// Latch before parsing: a declined, pending, or unparsable
+					// ask still counts — fail-open, no re-ask.
+					const sessionId = sessionIdOf(exec?.agent);
+					if (readScope(config) === "project" && sessionId !== null) askedSessions.add(sessionId);
+					else 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})`,
+						const cwd = exec?.agent?.session?.header?.cwd;
+						if (readScope(config) === "project" && typeof cwd === "string" && cwd !== "") {
+							// Project scope: persist into the project file
+							// (a failed write logs and drops — the answer is
+							// re-asked in the next session, never leaked into
+							// the inert global fields).
+							try {
+								const path = writeProjectPref(cwd, pref);
+								ctx.logger?.info?.(
+									`dsh-switchman: language preferences saved to ${path} (conversation=${pref.conversation} comments=${pref.comments || SAME} docs=${pref.docs || SAME})`,
 								);
-							})
-							.catch((error) => {
-								ctx.logger.warn(
-									`dsh-switchman: failed to save language preferences: ${error?.message ?? error}`,
+							} catch (error) {
+								ctx.logger?.warn?.(
+									`dsh-switchman: failed to write project language preferences: ${error?.message ?? error}`,
 								);
-							});
+							}
+						} else {
+							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}`,
+									);
+								});
+						}
 					}
 				}
 			}

package/host/lib/dsh-home.js

@@ -0,0 +1,18 @@
+/** Shared <DSH_HOME> derivation. Explicit env override wins (with ~
+ * expansion), else the per-user default. Mirrors the host's own
+ * resolution order (dsh-home-paths' resolveDshHome), so plugin-side file
+ * lookups (attachments store, session projcache records) land on the same
+ * directories the host reads and writes. */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** Best-effort <DSH_HOME> derivation: explicit env override wins, else
+ * the per-user default. */
+export function dshHome() {
+	const env = process.env.DSH_HOME;
+	if (typeof env === "string" && env.trim() !== "") {
+		const expanded = env.startsWith("~") ? join(homedir(), env.slice(1)) : env;
+		return resolve(expanded);
+	}
+	return join(homedir(), ".dsh");
+}