dsh-switchman 1.3.1 → 1.5.0

package/host/routes.js

@@ -7,13 +7,28 @@
  * plugin established). This module owns that route family:
  *
  *   GET  /api/dsh-switchman/health   — liveness probe for the client page.
- *   GET  /api/dsh-switchman/config   — current settings values snapshot.
+ *   GET  /api/dsh-switchman/config   — current settings values snapshot plus
+ *                                      `whitelistSync` (null unless teamsMode
+ *                                      && syncWhitelist, else the teams
+ *                                      layer's last replace-sync outcome).
  *   POST /api/dsh-switchman/config   — { expected, values } fenced write
  *                                      through ctx.settings.update; a stale
  *                                      `expected` answers 409 + fresh values.
+ *                                      A successful write schedules the teams
+ *                                      orchestration (fire-and-forget).
  *   GET  /api/dsh-switchman/models   — model-catalog pass-through from the
  *                                      host sessionController (degrades to
  *                                      llm.listProviders, then []).
+ *   GET  /api/dsh-switchman/authorized — the session's DSH-authorized child
+ *                                      models ({enabled, routes}; both null
+ *                                      when the host service is unreadable).
+ *   GET  /api/dsh-switchman/vision-state — composer-dock hint; the optional
+ *                                      `session` query parameter judges image
+ *                                      capability against THAT session's
+ *                                      model (unknown/missing → root model).
+ *   POST /api/dsh-switchman/ui-locale — the client half reports its active
+ *                                      UI locale (feeds the ask guidance's
+ *                                      question language; no settings write).
  *
  * Every route carries the shared trust fence (loopback + same-origin browser
  * markers; a live remoteWebUiPairing cookie is an extra allow path), mirroring
@@ -21,17 +36,30 @@
  * settings, so unpaired LAN clients must not reach it.
  */
 
+import { authorizedChildRoutes } from "./dispatch.js";
+import { handoverSnapshot } from "./handover-state.js";
+import { pumpTeamsOrchestration, scheduleTeamsOrchestration, SWITCHMAN_SETTINGS_NS, teamsBundleState, teamsSyncSnapshot } from "./teams.js";
+import { reportedUiLocale, setReportedUiLocale } from "./ui-locale.js";
+import { visionStateOf } from "./vision.js";
+
 /** Route paths (client.js mirrors these literals). */
 const ROUTES = {
 	health: "/api/dsh-switchman/health",
 	config: "/api/dsh-switchman/config",
 	models: "/api/dsh-switchman/models",
+	authorized: "/api/dsh-switchman/authorized",
+	handoverState: "/api/dsh-switchman/handover-state",
+	visionState: "/api/dsh-switchman/vision-state",
+	uiLocale: "/api/dsh-switchman/ui-locale",
 };
 
 /** Settings namespace this plugin's writes target: the LOADER ENTRY id from
  * cordis.patch.yml (`- id: dsh-switchman-host`), not the plugin's `name`
- * export — dsh-settings' write() looks entries up by entry.options.id. */
-const NS = "dsh-switchman-host";
+ * export — dsh-settings' write() looks entries up by entry.options.id.
+ * Single-sourced as SWITCHMAN_SETTINGS_NS in host/teams.js (whose
+ * settings/document-updated listener keys on it); aliased here for the
+ * write call sites below. */
+const NS = SWITCHMAN_SETTINGS_NS;
 
 /** All settings field names, grouped for coercion (mirrors host/config.js). */
 const STRING_FIELDS = ["langConversation", "langComments", "langDocs"];
@@ -60,6 +88,9 @@ const BOOLEAN_FIELDS = [
 	"poolHardManual",
 	"poolVisionManual",
 	"poolReviewManual",
+	// teams 开关（mirrors host/config.js 的 teams* 组）
+	"teamsMode",
+	"syncWhitelist",
 ];
 /** Per-pool effort-route lists (mirrors host/config.js pool*Efforts). */
 const EFFORTS_FIELDS = [
@@ -71,6 +102,7 @@ const EFFORTS_FIELDS = [
 	"poolReviewEfforts",
 ];
 const ENUM_FIELDS = {
+	langScope: ["global", "project"],
 	dispatchEnforce: ["off", "advice", "enforce"],
 	wmDenyMode: ["cap", "deny"],
 };
@@ -156,9 +188,17 @@ function isAllowed(ctx, request) {
 	);
 }
 
-/** Read one volatile settings field's raw value (live `.get()` reference). */
+/** Read one volatile settings field's raw value (live `.get()` reference;
+ * undefined when the getter itself throws — same guard as teams.js's
+ * readValue, kept on this GET-config hot path). */
 function rawOf(field) {
-	if (field !== null && typeof field === "object" && typeof field.get === "function") return field.get();
+	if (field !== null && typeof field === "object" && typeof field.get === "function") {
+		try {
+			return field.get();
+		} catch {
+			return undefined;
+		}
+	}
 	return field;
 }
 
@@ -206,6 +246,7 @@ export function snapshotOf(config) {
 		values[field] = Array.isArray(rawOf(config?.[field]))
 			? rawOf(config[field]).map(cleanEffortEntry).filter(Boolean)
 			: [];
+	values.langScope = ENUM_FIELDS.langScope.includes(rawOf(config?.langScope)) ? rawOf(config.langScope) : "global";
 	values.dispatchEnforce = ENUM_FIELDS.dispatchEnforce.includes(rawOf(config?.dispatchEnforce))
 		? rawOf(config.dispatchEnforce)
 		: "advice";
@@ -220,6 +261,15 @@ export function snapshotOf(config) {
 	return values;
 }
 
+/** The whitelistSync status for config responses: null unless syncWhitelist
+ *  is ON (an INDEPENDENT switch — teamsMode is not required), else the teams
+ *  layer's last replace-sync outcome ({ ok, count, at, error? } — itself
+ *  null before the first sync). */
+function whitelistSyncOf(config) {
+	if (rawOf(config?.syncWhitelist) !== true) return null;
+	return teamsSyncSnapshot();
+}
+
 /** Coerce and validate a client-submitted values object; null when invalid. */
 function coerceValues(input) {
 	if (input === null || typeof input !== "object" || Array.isArray(input)) return null;
@@ -244,6 +294,8 @@ function coerceValues(input) {
 		if (efforts.some((entry) => entry === null)) return null;
 		values[field] = efforts;
 	}
+	if (!ENUM_FIELDS.langScope.includes(input.langScope)) return null;
+	values.langScope = input.langScope;
 	if (!ENUM_FIELDS.dispatchEnforce.includes(input.dispatchEnforce)) return null;
 	values.dispatchEnforce = input.dispatchEnforce;
 	for (const field of NUMBER_FIELDS) {
@@ -327,7 +379,11 @@ export function makeRoutes(ctx, config) {
 					return;
 				}
 				if (req.method === "GET") {
-					writeJson(res, 200, { values: snapshotOf(config) });
+					// Clean-context retry pump: HTTP handlers never run inside an
+					// HMR transaction, so an orchestration deferred by the nested
+					// rejection re-runs here (no-op when nothing is pending).
+					pumpTeamsOrchestration(ctx, config);
+					writeJson(res, 200, { values: snapshotOf(config), whitelistSync: whitelistSyncOf(config), teamsBundle: teamsBundleState() });
 					return;
 				}
 				if (req.method !== "POST") {
@@ -363,7 +419,14 @@ export function makeRoutes(ctx, config) {
 					writeJson(res, 500, { error: error?.message ?? String(error) });
 					return;
 				}
-				writeJson(res, 200, { values: snapshotOf(config) });
+				// Teams orchestration hook (fire-and-forget: the teams layer defers
+				// the real work to a setImmediate turn, so the bundle enable +
+				// optional whitelist replace-sync never block this response; a
+				// nested-HMR rejection is retried from the next clean trigger —
+				// see host/teams.js). Runs when EITHER switch is on (they are
+				// independent); each half gates itself inside the orchestration.
+				scheduleTeamsOrchestration(ctx, config);
+				writeJson(res, 200, { values: snapshotOf(config), whitelistSync: whitelistSyncOf(config), teamsBundle: teamsBundleState() });
 			},
 		},
 		{
@@ -379,6 +442,74 @@ export function makeRoutes(ctx, config) {
 				}
 			},
 		},
+		{
+			kind: "exact",
+			path: ROUTES.authorized,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				try {
+					const snapshot = authorizedChildRoutes(ctx);
+					writeJson(
+						res,
+						200,
+						snapshot === null
+							? { enabled: null, routes: null }
+							: { enabled: snapshot.enabled, routes: snapshot.routes },
+					);
+				} catch (error) {
+					ctx.logger.warn(`dsh-switchman: authorized-models read failed: ${error?.message ?? error}`);
+					writeJson(res, 500, { error: error?.message ?? String(error) });
+				}
+			},
+		},
+		{
+			kind: "exact",
+			path: ROUTES.handoverState,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				// Read-only live registry: the client badge polls this during
+				// the otherwise-silent fork+compact window ({count, handovers}),
+				// so the GUI shows an animated "handover in progress" cue.
+				const handovers = handoverSnapshot();
+				writeJson(res, 200, { count: handovers.length, handovers });
+			},
+		},
+		{
+			kind: "exact",
+			path: ROUTES.visionState,
+			handler: async (req, res) => {
+				if (!guard(req, res, "GET")) return;
+				pumpTeamsOrchestration(ctx, config); // clean-context retry pump (see GET config)
+				try {
+					// Optional `session` query parameter (a child session id):
+					// judge image capability against THAT session's model
+					// instead of the root's (the root verdict misreported for
+					// children on a different route). A missing or unknown
+					// session falls back to the root verdict.
+					const session = new URL(req.url ?? "/", "http://localhost").searchParams.get("session");
+					writeJson(res, 200, await visionStateOf(ctx, config, typeof session === "string" && session !== "" ? session : null));
+				} catch (error) {
+					ctx.logger.warn(`dsh-switchman: vision-state read failed: ${error?.message ?? error}`);
+					writeJson(res, 500, { error: error?.message ?? String(error) });
+				}
+			},
+		},
+		{
+			kind: "exact",
+			path: ROUTES.uiLocale,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				let body;
+				try {
+					body = await readJsonBody(req);
+				} catch (error) {
+					writeJson(res, 400, { error: error?.message ?? String(error) });
+					return;
+				}
+				setReportedUiLocale(body?.locale);
+				writeJson(res, 200, { ok: true, locale: reportedUiLocale() });
+			},
+		},
 	];
 }
 

package/host/subagent-model.js

@@ -0,0 +1,147 @@
+/** dsh-switchman subagent model-visibility layer.
+ *
+ * Parent-side model annotation for delegation results: a `tools/post-execute`
+ * waterfall listener (registered exactly like host/lang.js's capture) watches
+ * the `subagent` / `subagent_fork` tools and, when the call succeeded, reads
+ * the child session's `modelSelection` projection through the `sessionQuery`
+ * service (`observeSession` — cold sessions resolve without activating the
+ * child) and appends one `model: provider/model@effort` line to the accepted
+ * result content. DSH's own UI shows a child's model nowhere, so this line is
+ * the only place the parent learns which model actually runs each child.
+ *
+ * Shapes verified against dsh 0.2.1-alpha.1 sources:
+ * - Tool result values: `{kind:"continuable", subagentId}` (background
+ *   continuable — subagentId IS the durable child session id,
+ *   subagents.startContinuable's childId), `{kind:"foreground", runId,
+ *   output}` (SubagentRun.id equals the published child session id for local
+ *   providers; remote providers mint parent-namespaced ids, which simply fail
+ *   the cold read and pass through unannotated), and `{kind:"background",
+ *   jobId}` (a jobs id, not a session id — skipped).
+ * - `PostToolDecision` accept: `content` replaces the model-visible content
+ *   and cannot coexist with a `value` replacement (the runtime throws on
+ *   both), so only value-less accepts gain the line. `next()` is always
+ *   awaited first and its decision passed through untouched otherwise —
+ *   best-effort fail-open: an unreadable child projection means no
+ *   annotation, never an altered result.
+ */
+
+/** Child session id out of one subagent tool result value; null for shapes
+ *  without a session id (one-shot background jobs) or malformed values. */
+function childSessionIdOf(value) {
+	if (value === null || typeof value !== "object") return null;
+	if (value.kind === "continuable" && typeof value.subagentId === "string" && value.subagentId !== "")
+		return value.subagentId;
+	if (value.kind === "foreground" && typeof value.runId === "string" && value.runId !== "")
+		return value.runId;
+	return null;
+}
+
+/** Release one observation lease (explicit-resource-management protocol; both
+ *  the native Symbol.dispose and the TS-downlevel Symbol.for key are tried).
+ *  Prepared cuts pin an LRU cache entry, so a dropped lease would leak. */
+function disposeObservation(observation) {
+	if (observation === null || observation === undefined) return;
+	for (const key of [Symbol.dispose, Symbol.for("Symbol.dispose")]) {
+		const dispose = key === undefined ? undefined : observation[key];
+		if (typeof dispose === "function") {
+			try {
+				dispose.call(observation);
+			} catch {
+				/* lease release is best-effort */
+			}
+			return;
+		}
+	}
+}
+
+/**
+ * The effective model selection of one session, via the session-query
+ * observeSession channel (shared with host/vision.js's per-session verdict).
+ * @param {import("@deepseek-ai/cordis").Context} ctx - host plugin context.
+ * @param {string} sessionId - session id (live or persisted).
+ * @returns {Promise<{provider: string, model: string, reasoningEffort?: string} | null>}
+ *          null when the session is unknown, unreadable, or unselected yet.
+ */
+async function sessionModelSelectionOf(ctx, sessionId) {
+	if (typeof sessionId !== "string" || sessionId === "") return null;
+	let query;
+	try {
+		query = ctx.get?.("sessionQuery", false);
+	} catch {
+		return null;
+	}
+	if (query === undefined || query === null || typeof query.observeSession !== "function") return null;
+	let observation = null;
+	try {
+		observation = await query.observeSession(sessionId);
+		const selection = observation?.projections?.values?.modelSelection;
+		const route = selection?.next ?? selection?.lastUsed; // next already falls back to lastUsed
+		if (route === null || typeof route !== "object") return null;
+		if (typeof route.provider !== "string" || route.provider === "" || typeof route.model !== "string" || route.model === "")
+			return null;
+		return typeof route.reasoningEffort === "string" && route.reasoningEffort !== ""
+			? { provider: route.provider, model: route.model, reasoningEffort: route.reasoningEffort }
+			: { provider: route.provider, model: route.model };
+	} catch {
+		return null;
+	} finally {
+		disposeObservation(observation);
+	}
+}
+
+/** The appended annotation line, or null when the child's model is unknown. */
+function modelLineOf(selection) {
+	if (selection === null || typeof selection !== "object") return null;
+	const effort =
+		typeof selection.reasoningEffort === "string" && selection.reasoningEffort !== ""
+			? `@${selection.reasoningEffort}`
+			: "";
+	return `model: ${selection.provider}/${selection.model}${effort}`;
+}
+
+/** Await the downstream decision, then append the annotation line to a
+ *  value-less accept decision only. A next() rejection propagates (the
+ *  pipeline's own containment turns it into an error result); a failure in
+ *  the annotation logic after next() settled degrades to the untouched
+ *  decision — never a lost or re-run outcome. */
+async function annotate(ctx, exec, result, next, warn) {
+	const downstream = await next();
+	try {
+		if (downstream === null || typeof downstream !== "object" || downstream.kind !== "accept") return downstream;
+		// A value-replacing accept cannot also carry content (the runtime
+		// throws "cannot replace both value and content").
+		if (Object.hasOwn(downstream, "value")) return downstream;
+		const sessionId = childSessionIdOf(result?.value);
+		if (sessionId === null) return downstream;
+		const line = modelLineOf(await sessionModelSelectionOf(ctx, sessionId));
+		if (line === null) return downstream; // projection not ready/known — passthrough
+		const base = Array.isArray(downstream.content)
+			? downstream.content
+			: Array.isArray(result?.content)
+				? result.content
+				: [];
+		if (base.length === 0) return downstream; // nothing rendered to append to — never fabricate content
+		return { ...downstream, content: [...base, { type: "text", text: line }] };
+	} catch (error) {
+		// next() already settled — pass its decision through untouched (a
+		// failed annotation must never alter or fabricate an outcome).
+		warn(`subagent model annotation failed: ${error?.message ?? error}`);
+		return downstream;
+	}
+}
+
+/**
+ * Mount the subagent model-visibility layer (one post-execute listener).
+ * @param {import("@deepseek-ai/cordis").Context} ctx - host plugin context.
+ */
+function applySubagentModel(ctx) {
+	const warn = (message) => ctx.logger?.warn?.(`dsh-switchman: ${message}`);
+	ctx.on("tools/post-execute", (exec, result, next) => {
+		// Fast path: every non-subagent tool and every failed call stays
+		// exactly on the current pipeline (promise pass-through).
+		if ((exec?.name !== "subagent" && exec?.name !== "subagent_fork") || result?.isError === true) return next();
+		return annotate(ctx, exec, result, next, warn);
+	});
+}
+
+export { applySubagentModel, sessionModelSelectionOf };

package/host/subagents.js

@@ -0,0 +1,144 @@
+/** Enumeration of this session's still-running background subagents.
+ *
+ * Why this exists: a context handover (compaction) preserves dispatched
+ * background subagents — they keep running — but the compacted parent
+ * loses every handle (job registries do not list them, send_message
+ * cannot address them mid-run). The post-handover agent then wrongly
+ * concludes the work is lost and double-dispatches. Recording the live
+ * children into the handover document closes that gap.
+ *
+ * Disk format (verified against a packaged host's live records under
+ * <DSH_HOME>/storages/session_projcache/sessions/):
+ *
+ * - Parent record `<sessionId>.json` (sessionId carries the `session-`
+ *   prefix) -> { record: { rows: { subagentCatalog: { val: { head:
+ *   { values: [{ childId, childCreatedAt, mode, label }, ...] } } } } } }
+ *   — the append-only catalog of every subagent dispatched from the
+ *   session (labels are the dispatch `description`).
+ * - Child record `<childId>.json` (bare UUID) — running iff
+ *   rows.sessionStats.val.openStep !== null; a settled child has
+ *   openStep === null and rows.turnBoundary.val.lastStepBoundary
+ *   === { kind: "end" } while a running one shows { kind: "start" }.
+ *
+ * Every failure mode is fail-open to [] — enumeration is advisory
+ * context for the handover document, never a blocker. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { dshHome } from "./lib/dsh-home.js";
+
+/** Parse one session-projcache record into its rows map, or null on any
+ * structural surprise (missing file, bad JSON, unexpected shape). */
+function readRows(path) {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		const rows = parsed?.record?.rows;
+		return rows !== null && typeof rows === "object" ? rows : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Directory holding the session-projcache records (advisory text). */
+export function sessionRecordsDir() {
+	return join(dshHome(), "storages", "session_projcache", "sessions");
+}
+
+/** Absolute path of one session's projcache record — advisory text for
+ * handover documents, so recorded collection paths honor DSH_HOME the
+ * same way the enumeration lookups do. */
+export function sessionRecordPath(id) {
+	return join(sessionRecordsDir(), `${id}.json`);
+}
+
+/** Candidate file names for a session record: the observed convention is
+ * `session-<uuid>.json` for conversation sessions and `<uuid>.json` for
+ * subagent children, but probing both keeps the lookup robust. */
+function recordPaths(directory, id) {
+	const names = new Set([`${id}.json`]);
+	const bare = id.replace(/^session-/u, "");
+	if (bare !== id) names.add(`${bare}.json`);
+	else names.add(`session-${id}.json`);
+	return [...names].map((name) => join(directory, name));
+}
+
+/** This session's still-running background subagents as
+ * [{ id, label, mode }], empty when none are detected (or on any error).
+ * Reads only; never throws. Disk fallback for enumerateRunningSubagents:
+ * the projcache snapshot lags live state slightly (and a crashed child
+ * can leave a stale open step), but it survives every service hiccup. */
+export function runningSubagentsOf(sessionId) {
+	if (typeof sessionId !== "string" || sessionId === "") return [];
+	const directory = sessionRecordsDir();
+	const parentRows = recordPaths(directory, sessionId)
+		.map((path) => readRows(path))
+		.find((rows) => rows !== null);
+	const catalog = parentRows?.subagentCatalog?.val;
+	const entries = catalog?.head?.values;
+	if (!Array.isArray(entries)) return [];
+	const running = [];
+	for (const entry of entries) {
+		if (entry === null || typeof entry !== "object") continue;
+		const childId = entry.childId;
+		if (typeof childId !== "string" || childId === "") continue;
+		const childRows = recordPaths(directory, childId)
+			.map((path) => readRows(path))
+			.find((rows) => rows !== null);
+		if (childRows === null) continue; // never created, or pruned: not live work
+		if (childRows.sessionStats?.val?.openStep == null) continue; // settled
+		running.push({
+			id: childId,
+			label: typeof entry.label === "string" ? entry.label : "",
+			mode: typeof entry.mode === "string" ? entry.mode : "",
+		});
+	}
+	return running;
+}
+
+/** Sanctioned enumeration (preferred over the disk scan): the live
+ * subagent catalog service plus the in-memory agent registry — no flush
+ * lag, no stale-after-crash heuristic. `listChildren` accepts the session
+ * id; both id forms (with/without the `session-` prefix) are probed
+ * because the wire form is not contractual. Falls back to the disk scan
+ * whenever the services are absent, disagree with the shapes above, or
+ * throw. Never throws. */
+export async function enumerateRunningSubagents(ctx, sessionId) {
+	if (typeof sessionId !== "string" || sessionId === "") return [];
+	try {
+		const subagents = typeof ctx?.get === "function" ? ctx.get("subagents") : null;
+		const agents = typeof ctx?.get === "function" ? ctx.get("agents") : null;
+		if (
+			subagents !== null &&
+			typeof subagents.listChildren === "function" &&
+			agents !== null &&
+			typeof agents.get === "function"
+		) {
+			const candidates = new Set([sessionId]);
+			const bare = sessionId.replace(/^session-/u, "");
+			if (bare !== sessionId) candidates.add(bare);
+			for (const id of candidates) {
+				let children;
+				try {
+					children = await subagents.listChildren(id);
+				} catch {
+					continue; // this id form is unusable — probe the next one
+				}
+				if (!Array.isArray(children)) continue;
+				const running = [];
+				for (const child of children) {
+					if (child === null || typeof child !== "object") continue;
+					if (typeof child.id !== "string" || child.id === "") continue;
+					if (agents.get(child.id)?.status !== "running") continue;
+					running.push({
+						id: child.id,
+						label: typeof child.label === "string" ? child.label : "",
+						mode: typeof child.mode === "string" ? child.mode : "",
+					});
+				}
+				return running; // first id form that answers wins, even when empty
+			}
+		}
+	} catch {
+		/* fall through to the disk scan */
+	}
+	return runningSubagentsOf(sessionId);
+}