@khorsheed/dsh-local-agent-dsh 0.1.0-rc.6

package/lib/dsh-cli-provider.js

@@ -0,0 +1,3 @@
+import "./provision.js";
+import { a as MEMBER_BRIDGE_ENTRY_ENV, c as dshTextTask, d as startDshCliRun, i as DshCliProvider, l as registerMemberRun, n as DEFAULT_DISPOSE_GRACE_MS, o as dshCliVersion, r as DEFAULT_LIVE_MIRROR_INTERVAL_MS, s as dshLaunchArgv, t as CONTAINER_NODE_OPTIONS, u as resolveApiKey } from "./dsh-cli-provider-UhWvivte.js";
+export { CONTAINER_NODE_OPTIONS, DEFAULT_DISPOSE_GRACE_MS, DEFAULT_LIVE_MIRROR_INTERVAL_MS, DshCliProvider, MEMBER_BRIDGE_ENTRY_ENV, dshCliVersion, dshLaunchArgv, dshTextTask, registerMemberRun, resolveApiKey, startDshCliRun };

package/lib/index.js

@@ -0,0 +1,624 @@
+import { DEFAULT_SUB_PROFILE_NAME, USER_PRESET_DIR, defaultPresetRoot, provisionDshScope } from "./provision.js";
+import { f as DEFAULT_LIVE_IDLE_MS, i as DshCliProvider, o as dshCliVersion, p as DshLiveDriver, t as CONTAINER_NODE_OPTIONS } from "./dsh-cli-provider-UhWvivte.js";
+import { listDshSessions } from "./records.js";
+import { join } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { ModelDirectoryCache, extendModelDirectory, settingsFace, vol } from "@khorsheed/dsh-local-agent";
+import * as toolModule from "@khorsheed/dsh-local-agent-tool-subagent";
+//#region lib/types/live-switch.js
+/**
+* The settings-driven live-driver switch: owns the active driver generation
+* and retires old ones on a settings change, without a plugin reload.
+*
+* Toggle OFF (or the enabled generation unloading): the retiring generation
+* is DRAINED, not killed — new rounds are refused (the provider's catch falls
+* back to exec), in-flight rounds finish on their runtime, idle runtimes are
+* reclaimed at once. Toggling ON builds the next generation lazily (no
+* process until the first round). Legacy granularity settings are ignored.
+*
+* Composition with the `enabled` toggle: the switch lives INSIDE one enabled
+* generation (index.ts constructs it only while the harness/provider/tool are
+* registered, and disposes it with them). `enabled` gates EXISTENCE — its
+* teardown keeps the historical hard semantics (`dispose()` → disposeAll,
+* which may interrupt); `live` gates the MODE of an enabled generation and
+* never interrupts (drain). While `enabled` is off the live value is inert
+* and applies when the toggle turns on again.
+*
+* @module @khorsheed/dsh-local-agent-dsh — internal, unit-tested directly.
+*/
+var LiveDriverSwitch = class {
+	ctx;
+	config;
+	extras;
+	liveOn = false;
+	active;
+	/** Retiring generations still draining their in-flight rounds. */
+	draining = /* @__PURE__ */ new Set();
+	unwatch;
+	constructor(ctx, face, config, extras = {}) {
+		this.ctx = ctx;
+		this.config = config;
+		this.extras = extras;
+		this.apply(face.get());
+		this.unwatch = face.watch((next) => {
+			this.apply(next);
+		});
+	}
+	/**
+	* Resolve the live driver for one round's member (the provider's call
+	* site). A retiring generation still hosting the member gates the new one —
+	* the round falls back to exec rather than double-loading the same sub-dsh
+	* session into two processes.
+	*/
+	resolve = (childSessionId) => {
+		if (this.active === void 0) return void 0;
+		for (const retiring of this.draining) if (retiring.hasRuntime(childSessionId)) return void 0;
+		return this.active;
+	};
+	/**
+	* The model the member's live runtime bound at spawn (the broker's switch
+	* check): the identifier, undefined for "bound to no model", null for "no
+	* live runtime". Consults only the ACTIVE generation — a draining one is on
+	* its way out anyway.
+	*/
+	boundModel(childSessionId) {
+		return this.active?.boundModelOf(childSessionId) ?? null;
+	}
+	/**
+	* Retire the member's resident runtime in the active generation so the next
+	* round respawns onto the member's new effective model (the composer's
+	* model switch path; the sub-dsh session itself carries over via the
+	* on-disk resume).
+	*/
+	async retireRuntime(childSessionId) {
+		await this.active?.retireRuntime(childSessionId);
+	}
+	/** Mirror the resolved settings into the driver generation. */
+	apply(next) {
+		if (next.live === this.liveOn) return;
+		this.liveOn = next.live;
+		const retiring = this.active;
+		this.active = next.live ? new DshLiveDriver(this.ctx, {
+			...this.config,
+			...this.extras.modelFor === void 0 ? {} : { modelFor: this.extras.modelFor }
+		}) : void 0;
+		if (retiring !== void 0) {
+			this.draining.add(retiring);
+			retiring.drain().then(() => {
+				this.draining.delete(retiring);
+			}, (error) => {
+				this.draining.delete(retiring);
+				this.ctx.logger.warn(`local-agent-dsh: live driver drain failed: ${error instanceof Error ? error.message : String(error)}`);
+			});
+		}
+	}
+	/** Enabled-generation unload: interrupt whatever survives (disposeAll, not drain). */
+	dispose() {
+		this.unwatch();
+		this.active?.disposeAll();
+		for (const retiring of this.draining) retiring.disposeAll();
+		this.draining.clear();
+	}
+};
+//#endregion
+//#region lib/types/model-catalog.js
+/** The public host adapter catalog used by sub-DSH provisioning. No generation request. */
+var DshModelCatalog = class {
+	deps;
+	cache;
+	constructor(deps) {
+		this.deps = deps;
+		this.cache = new ModelDirectoryCache({ load: async (_key, signal) => {
+			const controller = new AbortController();
+			const abort = () => controller.abort();
+			signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted) abort();
+			let timer;
+			try {
+				return await Promise.race([this.discover(controller.signal), new Promise((_, reject) => {
+					timer = setTimeout(() => {
+						controller.abort();
+						reject(/* @__PURE__ */ new Error("DSH model directory timed out"));
+					}, deps.timeoutMs ?? 5e3);
+					timer.unref();
+				})]);
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+				signal.removeEventListener("abort", abort);
+			}
+		} });
+	}
+	key() {
+		return JSON.stringify({ defaultModel: this.deps.defaultModel() });
+	}
+	read() {
+		return this.cache.read(this.key());
+	}
+	refresh() {
+		return this.cache.refresh(this.key());
+	}
+	follow(signal) {
+		return this.cache.follow(() => this.key(), signal);
+	}
+	invalidate() {
+		this.cache.invalidate(this.key());
+	}
+	dispose() {
+		this.cache.dispose();
+	}
+	async discover(signal) {
+		const llm = this.deps.llm();
+		if (llm === void 0 || typeof llm.listProviders !== "function" || typeof llm.listModels !== "function") return {
+			entries: [],
+			complete: false,
+			customInput: true,
+			unsupported: true,
+			reason: "The host exposes no adapter model directory"
+		};
+		const providers = llm.listProviders();
+		const groups = await Promise.allSettled(providers.map(async (provider) => Promise.all((await llm.listModels(provider.id)).map(async (model) => {
+			let resolved;
+			try {
+				resolved = await llm.resolveModelInfo?.(provider.id, model.id, signal);
+			} catch {}
+			return {
+				value: `${provider.id}/${model.id}`,
+				label: model.name ?? model.id,
+				source: "native",
+				...model.description === void 0 ? {} : { description: model.description },
+				...resolved === void 0 ? {} : { resolvedModel: `${resolved.provider}/${resolved.id}` },
+				...resolved?.reasoning === void 0 ? {} : { reasoning: {
+					options: resolved.reasoning.efforts.map((effort) => ({
+						value: String(effort.id),
+						label: effort.name,
+						...effort.description === void 0 ? {} : { description: effort.description }
+					})),
+					...resolved.reasoning.defaultEffort === void 0 ? {} : { default: String(resolved.reasoning.defaultEffort) }
+				} }
+			};
+		}))));
+		const failed = groups.filter((group) => group.status === "rejected").length;
+		if (failed > 0 && failed === groups.length) throw new Error("DSH adapters could not list models");
+		const entries = groups.flatMap((group) => group.status === "fulfilled" ? group.value : []);
+		const defaultModel = this.deps.defaultModel();
+		return {
+			entries,
+			complete: failed === 0,
+			customInput: true,
+			...defaultModel === void 0 ? {} : { defaultModel },
+			...failed === 0 ? {} : { reason: `${failed} adapter model list(s) unavailable` }
+		};
+	}
+};
+//#endregion
+//#region lib/types/model-broker.js
+/**
+* The dsh harness's model broker: the member-aware model surface the core
+* gateway routes to (`harnessModel` for the settings card, `memberModel` /
+* `setMemberModel` for the composer picker). It owns the session-level
+* override map — shared with the exec provider (which consults it per round)
+* and the live driver (which binds it at runtime spawn) — and retires a
+* member's resident serve process when a switch leaves it bound to a
+* different model, so the NEXT round respawns onto the new one while the
+* sub-dsh session itself carries over via the on-disk resume.
+*
+* Resolution order is the family's fixed one (first match wins): override →
+* the delegation's recorded model → the plugin-config `model` (settings) →
+* the host instance's default model selection spelled `provider/model`
+* (cliDefault — the selection a sub-dsh with no `--model` inherits) → the
+* CLI's built-in default, which names nothing. The pickable vocabulary is
+* settings + cliDefault + the host's own adapter enumeration (the public
+* `ctx.llm` surface — `listProviders` × `listModels`, spelled `provider/model`
+* exactly as the sub-dsh's `--model` expects; the same trio the host's model
+* picker is built on) + the card's recent-model memory.
+* @module @khorsheed/dsh-local-agent-dsh/model-broker
+*/
+/** Dedupe the choice vocabulary, dropping unset layers and blanks. */
+function dedupeChoices(layers) {
+	const seen = /* @__PURE__ */ new Set();
+	const choices = [];
+	for (const layer of layers) {
+		const value = layer?.trim();
+		if (value === void 0 || value === "" || seen.has(value)) continue;
+		seen.add(value);
+		choices.push(value);
+	}
+	return choices;
+}
+var DshModelBroker = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	configurationAdapter(binding) {
+		const resolve = async (selection) => {
+			let directory = this.deps.catalog?.read();
+			if (directory?.status === "loading") directory = await this.deps.catalog?.refresh();
+			const model = selection.model.mode === "value" ? selection.model.value : (selection.model.mode === "inherit" ? binding.model : void 0) ?? this.deps.settingsModel() ?? this.deps.cliDefault();
+			const entry = directory?.entries.find((entry) => entry.value === model);
+			const effort = (selection.effort.mode === "value" ? selection.effort.value : selection.effort.mode === "inherit" ? binding.effort : void 0) ?? this.deps.defaultEffort?.() ?? entry?.reasoning?.default;
+			if (effort !== void 0 && !entry?.reasoning?.options.some((option) => option.value === effort)) throw new Error("DSH has not advertised this reasoning effort for the selected model");
+			return {
+				...model === void 0 ? {} : { model },
+				...effort === void 0 ? {} : { effort }
+			};
+		};
+		return {
+			validate: async (selection) => {
+				await resolve(selection);
+			},
+			prepare: resolve,
+			apply: async (selection) => {
+				const resolved = await resolve(selection);
+				await this.deps.retireRuntime(binding.childSessionId);
+				return resolved;
+			},
+			reconcile: async (state) => {
+				if (this.activeDelegations().includes(binding.childSessionId)) return {
+					active: true,
+					matches: "unknown",
+					resolved: {}
+				};
+				await this.deps.retireRuntime(binding.childSessionId);
+				return {
+					active: false,
+					matches: "current",
+					resolved: await resolve(state.current.selection)
+				};
+			}
+		};
+	}
+	async modelDirectory(childSessionId, refresh = false) {
+		if (refresh) await this.deps.catalog?.refresh();
+		return this.modelInfo(childSessionId).directory ?? {
+			entries: [],
+			complete: false,
+			customInput: true,
+			status: "unsupported",
+			refreshing: false,
+			revision: 0
+		};
+	}
+	async *followModelDirectory(childSessionId, signal) {
+		if (this.deps.catalog === void 0) {
+			yield await this.modelDirectory(childSessionId);
+			return;
+		}
+		for await (const _snapshot of this.deps.catalog.follow(signal)) yield await this.modelDirectory(childSessionId);
+	}
+	/** The member's in-flight rounds (an empty answer on a core that predates the read). */
+	activeDelegations() {
+		const registry = this.deps.ctx.localAgent;
+		return typeof registry.activeDelegations === "function" ? registry.activeDelegations() : [];
+	}
+	/** The model the member's NEXT spawn binds explicitly: override → recorded → settings. */
+	boundLayer(childSessionId) {
+		const override = this.deps.overrides.get(childSessionId);
+		if (override !== void 0) return override;
+		const recorded = this.deps.ctx.localAgent.getDelegation(childSessionId)?.model?.trim();
+		if (recorded !== void 0 && recorded !== "") return recorded;
+		return this.deps.settingsModel();
+	}
+	/** Read the model surface; every layer reports its own value so a UI can explain the effective one. */
+	modelInfo(childSessionId, delegationModel) {
+		const settings = this.deps.settingsModel();
+		const cliDefault = this.deps.cliDefault();
+		const directory = this.deps.catalog?.read();
+		const override = childSessionId === void 0 ? void 0 : this.deps.overrides.get(childSessionId);
+		const delegation = delegationModel?.trim() === "" ? void 0 : delegationModel;
+		const effective = override ?? delegation ?? settings ?? cliDefault;
+		const source = override !== void 0 ? "override" : delegation !== void 0 ? "delegation" : settings !== void 0 ? "settings" : cliDefault !== void 0 ? "cli-config" : "cli-builtin";
+		const inFlight = childSessionId !== void 0 && this.activeDelegations().includes(childSessionId);
+		return {
+			...effective === void 0 ? {} : { effective },
+			source,
+			...override === void 0 ? {} : { override },
+			...delegation === void 0 ? {} : { delegation },
+			...settings === void 0 ? {} : { settings },
+			...cliDefault === void 0 ? {} : { cliDefault },
+			...directory === void 0 ? {} : { directory: extendModelDirectory(directory, [settings, cliDefault], this.deps.recentModels()) },
+			choices: dedupeChoices([
+				settings,
+				cliDefault,
+				...this.deps.discovered(),
+				...this.deps.recentModels()
+			]),
+			live: this.deps.live(),
+			switchable: !inFlight,
+			...inFlight ? { reason: "成员有进行中的委派轮次，等其完成后再切换模型" } : {}
+		};
+	}
+	/**
+	* Set (or clear) the member's session-level override. Same-model is a
+	* no-op; a different model with a live runtime bound elsewhere retires the
+	* runtime so the next round respawns (the sub-dsh session resumes from
+	* disk). Throws while a round is in flight — retiring mid-round would kill
+	* the run.
+	*/
+	async setMemberModel(childSessionId, model) {
+		if (typeof this.deps.ctx.localAgent.setMemberModel === "function") return this.deps.ctx.localAgent.setMemberModel(childSessionId, model);
+		if (this.activeDelegations().includes(childSessionId)) throw new Error(`subagent-dsh: 成员有进行中的委派轮次，等其完成后再切换模型 (child session ${childSessionId})`);
+		const trimmed = model?.trim();
+		const next = trimmed === void 0 || trimmed === "" ? void 0 : trimmed;
+		if (this.deps.overrides.get(childSessionId) === next) return;
+		if (next === void 0) this.deps.overrides.delete(childSessionId);
+		else this.deps.overrides.set(childSessionId, next);
+		const bound = this.deps.liveBoundModel(childSessionId);
+		if (bound !== null && bound !== this.boundLayer(childSessionId)) await this.deps.retireRuntime(childSessionId);
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* dsh harness instantiation of the local-agent family, plus the DeepSeek
+* settings toggle that gates it. Registers the `local-agent-dsh` settings
+* namespace (default off); while ON, the controller registers the `dsh`
+* harness into the core registry (scoped home under the shared homes root,
+* `$DSH_HOME`), the `dsh-cli` delegation provider (sub-dsh headless runs with
+* the parent's resolved DeepSeek key), and the family delegation tool for it.
+* While OFF — the default — nothing model-visible mounts, so the instance
+* keeps exactly the current behavior (official in-process subagent tools) and
+* the model never sees two overlapping delegation tools at once.
+*
+* The same namespace carries the resident-mode preferences (`live`,
+* `liveMirrorGranularity`): the YAML config is the composition base, the
+* settings card's writes are user-layer overrides, and a LiveDriverSwitch
+* inside each enabled generation hot-swaps driver generations on a change —
+* no reload, in-flight rounds never interrupted.
+*
+* The sub-dsh half lives in the sibling bundle
+* `@khorsheed/dsh-local-agent-dsh-headless`: a headless profile under the
+* scoped home that the provider spawns with `--session-id <uuid>` (fresh) or
+* `--resume <uuid>` (continuation).
+*
+* @module @khorsheed/dsh-local-agent-dsh
+*/
+/** Stable Cordis plugin name; the bundle patch row id. */
+const name = "local-agent-dsh";
+/** Services required before the toggle controller can mount. */
+const inject = [
+	"localAgent",
+	"subagents",
+	"subprocess",
+	"credentials",
+	"settings"
+];
+/**
+* Runtime schema so the Loader always passes an object, never undefined.
+* The settings fields (`enabled`, `live`, `liveMirrorGranularity`, `model`,
+* `recentModels`) ride the same schema, marked `.volatile()` where the host's
+* schemastery has it (3.18.4+, the rc.1 line — probed, never sniffed): there
+* the SettingsForms writes hot-track the running fiber's Volatile references
+* without a remount, and the official one-shot import moves an old
+* settings.yaml section into this row's config. On 0.1.5 the call is absent,
+* the fields stay plain config keys (a semantic superset — the profile row
+* can now preset them too), and the legacy settings namespace below carries
+* the user layer exactly as before.
+*
+* Bare `z` annotation: `z<LocalAgentDshConfig>` fails schemastery 3.18.4's
+* variance under exactOptionalPropertyTypes (TS2375) and dropping the
+* annotation trips TS2742; the interface stays the apply signature's contract.
+*/
+const SETTINGS_FIELDS = {
+	enabled: z.boolean().default(false),
+	live: z.boolean().default(false),
+	liveMirrorGranularity: z.union([z.const("event"), z.const("token")]).default("token"),
+	model: z.string(),
+	recentModels: z.array(z.string()).default([])
+};
+/** Mark one schema field volatile when the host's schemastery has the method (rc.1), pass it through plain when not (0.1.5). */
+function volatilize(field) {
+	return typeof field.volatile === "function" ? field.volatile() : field;
+}
+const Config = z.object({
+	profileName: z.string().default(DEFAULT_SUB_PROFILE_NAME),
+	apiKeyRef: z.string().default("DEEPSEEK_API_KEY"),
+	cliLaunch: z.array(z.string()),
+	headlessBundleDir: z.string(),
+	permissions: z.union([
+		z.const("read-only"),
+		z.const("workspace-write"),
+		z.const("danger-full-access")
+	]),
+	model: volatilize(SETTINGS_FIELDS.model),
+	live: volatilize(SETTINGS_FIELDS.live),
+	liveIdleMs: z.number().default(DEFAULT_LIVE_IDLE_MS),
+	liveMirrorGranularity: volatilize(SETTINGS_FIELDS.liveMirrorGranularity),
+	enabled: volatilize(SETTINGS_FIELDS.enabled),
+	recentModels: volatilize(SETTINGS_FIELDS.recentModels)
+});
+/**
+* Settings namespace owning the DeepSeek toggle and the live preferences. On
+* 0.1.5 the Cordis config feeds the namespace's composition `base` layer, so
+* a field absent from the user layer inherits the YAML value — the settings
+* card only ever stores deliberate overrides. On rc.1 the namespace is the
+* plugin row id itself: the row config IS the document, and the settings
+* form's user layer rides the profile patch.
+*/
+const DSH_SETTINGS_NAMESPACE = "local-agent-dsh";
+/**
+* The card's 0.1.5 schema: `enabled` OFF (default) means the official
+* in-process subagent stays the only delegation path; the live fields mirror
+* the YAML config's deployment defaults through the composition base.
+*/
+const DSH_SETTINGS_SCHEMA = z.object(SETTINGS_FIELDS);
+/** The delegation tool the toggle mounts while ON. */
+const DSH_TOOL_NAME = "subagent_dsh";
+/** Resolve the sub-dsh credential or report unconfigured. */
+async function resolveApiKey(ctx, config) {
+	return ctx.credentials.resolve(credentialRef(config.apiKeyRef ?? "DEEPSEEK_API_KEY"));
+}
+/**
+* Mount the toggle controller: register the settings namespace, then mirror
+* its value into harness/provider/tool registrations, live.
+* @param ctx - plugin context carrying the family registry, subagents,
+*   subprocess, credentials, and settings services.
+* @param config - validated plugin config.
+*/
+function apply(ctx, config) {
+	ctx.effect(() => {
+		const readSettings = () => ({
+			enabled: vol(config.enabled) ?? false,
+			live: vol(config.live) ?? false,
+			liveMirrorGranularity: vol(config.liveMirrorGranularity) ?? "token",
+			model: vol(config.model),
+			recentModels: vol(config.recentModels) ?? []
+		});
+		const legacyBase = {};
+		for (const field of [
+			"enabled",
+			"live",
+			"liveMirrorGranularity",
+			"model"
+		]) {
+			const value = vol(config[field]);
+			if (value !== void 0) legacyBase[field] = value;
+		}
+		const face = settingsFace(ctx, {
+			namespace: DSH_SETTINGS_NAMESPACE,
+			legacySchema: DSH_SETTINGS_SCHEMA,
+			legacyBase,
+			read: readSettings
+		});
+		const resolveModel = () => {
+			const model = face.get().model?.trim();
+			return model === void 0 || model === "" ? void 0 : model;
+		};
+		const hostDefaultModel = () => {
+			try {
+				const selection = ctx.get("agentDefaultModel")?.currentSelection?.();
+				if (typeof selection?.model === "string" && selection.model !== "") return typeof selection.provider === "string" && selection.provider !== "" ? `${selection.provider}/${selection.model}` : selection.model;
+			} catch {}
+		};
+		const modelCatalog = new DshModelCatalog({
+			llm: () => ctx.get("llm"),
+			defaultModel: hostDefaultModel
+		});
+		modelCatalog.read();
+		ctx.on("llm/adapters-updated", () => {
+			modelCatalog.invalidate();
+		});
+		const memberModelOverrides = /* @__PURE__ */ new Map();
+		let currentLiveSwitch;
+		const modelBroker = new DshModelBroker({
+			ctx,
+			settingsModel: resolveModel,
+			cliDefault: hostDefaultModel,
+			defaultEffort: () => ctx.get("agentDefaultModel")?.currentSelection().reasoningEffort,
+			discovered: () => modelCatalog.read().entries.filter((entry) => !entry.hidden).map((entry) => entry.value),
+			catalog: modelCatalog,
+			recentModels: () => face.get().recentModels ?? [],
+			live: () => face.get().live,
+			overrides: memberModelOverrides,
+			liveBoundModel: (childSessionId) => currentLiveSwitch?.boundModel(childSessionId) ?? null,
+			retireRuntime: (childSessionId) => currentLiveSwitch?.retireRuntime(childSessionId) ?? Promise.resolve()
+		});
+		/**
+		* This deployment's preset root — where a person or a pack installed the
+		* presets this instance offers, and the SOURCE every scope's own copy is
+		* taken from. Derived the way the roster derives it, from the settings
+		* service's harness home when there is one.
+		*/
+		const instancePresetRoot = () => {
+			const home = ctx.get?.("settings")?.home;
+			return home === void 0 ? defaultPresetRoot() : join(home, USER_PRESET_DIR);
+		};
+		const harness = {
+			prepareMember: async ({ binding, childSession, configuration, signal }) => {
+				const driver = currentLiveSwitch?.resolve(binding.childSessionId);
+				if (driver === void 0 || driver.disabled) throw new Error("Enable the native live harness before preparing a coordinator");
+				await driver.prepare({
+					cwd: binding.cwd,
+					homeDir: ctx.localAgent.homeDir("dsh", binding.scope),
+					childSession,
+					parentSessionId: binding.parentSessionId,
+					configuration: configuration.resolved,
+					sessionId: binding.childSessionId
+				}, signal);
+			},
+			name: "dsh",
+			displayName: "dsh",
+			homeEnvVar: "DSH_HOME",
+			delegationProvider: "dsh-cli",
+			modelBroker,
+			records: { listSessions: (homeDir) => listDshSessions(homeDir) },
+			provision: (scopedHome, options) => {
+				const provisioned = provisionDshScope(scopedHome, config, {
+					...options?.preset === void 0 ? {} : { preset: options.preset },
+					presetRoot: instancePresetRoot()
+				});
+				return {
+					...provisioned.preset === void 0 ? {} : { preset: provisioned.preset },
+					...provisioned.presetSnapshot === void 0 ? {} : { presetSnapshot: provisioned.presetSnapshot }
+				};
+			},
+			isAuthenticated: async () => {
+				try {
+					return await resolveApiKey(ctx, config) !== void 0;
+				} catch {
+					return false;
+				}
+			},
+			effectiveSettings: async (scopedHome) => {
+				const cliVersion = await dshCliVersion(ctx, config, scopedHome).catch(() => void 0);
+				const model = resolveModel() ?? hostDefaultModel();
+				return {
+					drive: face.get().live ? "live" : "exec",
+					baseUrlSet: false,
+					containerNodeOptions: CONTAINER_NODE_OPTIONS,
+					...config.permissions !== void 0 ? { sandbox: config.permissions } : {},
+					...model !== void 0 ? { model } : {},
+					...cliVersion !== void 0 ? { cliVersion } : {}
+				};
+			}
+		};
+		const homeDir = ctx.localAgent.homeDir("dsh");
+		let generation = 0;
+		let currentEnabled;
+		const disposers = [];
+		const sync = (enabled) => {
+			if (enabled === currentEnabled) return;
+			currentEnabled = enabled;
+			generation += 1;
+			const gen = generation;
+			for (const dispose of disposers.splice(0)) dispose();
+			if (!enabled) return;
+			provisionDshScope(homeDir, config, { presetRoot: instancePresetRoot() });
+			disposers.push(ctx.localAgent.register(harness));
+			const liveSwitch = new LiveDriverSwitch(ctx, face, config, { modelFor: (childSessionId) => memberModelOverrides.get(childSessionId) ?? resolveModel() });
+			currentLiveSwitch = liveSwitch;
+			disposers.push(ctx.subagents.registerProvider(new DshCliProvider(ctx, config, liveSwitch.resolve, resolveModel, (childSessionId) => memberModelOverrides.get(childSessionId))));
+			disposers.push(() => {
+				if (currentLiveSwitch === liveSwitch) currentLiveSwitch = void 0;
+				liveSwitch.dispose();
+			});
+			ctx.plugin(toolModule, {
+				provider: "dsh-cli",
+				toolName: DSH_TOOL_NAME
+			}).then((fiber) => {
+				if (gen !== generation) {
+					fiber.dispose();
+					return;
+				}
+				disposers.push(() => {
+					fiber.dispose();
+				});
+			}, (error) => {
+				ctx.logger.warn(`local-agent-dsh: delegation tool mount failed: ${error instanceof Error ? error.message : String(error)}`);
+			});
+		};
+		sync(face.get().enabled);
+		const unwatch = face.watch((next) => {
+			sync(next.enabled);
+		});
+		return () => {
+			modelCatalog.dispose();
+			unwatch();
+			generation += 1;
+			for (const dispose of disposers.splice(0)) dispose();
+		};
+	}, "local-agent-dsh: toggle controller");
+}
+//#endregion
+export { Config, DSH_SETTINGS_NAMESPACE, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,33 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@khorsheed/dsh-local-agent-dsh`.
+* @module @khorsheed/dsh-local-agent-dsh/invariant
+*/
+const PACKAGE_NAME = "@khorsheed/dsh-local-agent-dsh";
+/** Cordis companion plugin name. */
+const name = "local-agent-dsh-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* The dsh harness definition is this bundle's contract with the core
+* registry: whenever a `dsh` harness registers, its scoped-home variable must
+* be the one this bundle pins, and it must delegate through the `dsh-cli`
+* provider this bundle mounts.
+*/
+const install = (ctx, fail) => {
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "localAgent/harness-added") return;
+		const harness = args[0];
+		if (harness.name !== "dsh") return;
+		if (harness.homeEnvVar !== "DSH_HOME") fail("dsh harness registered with a home env other than the local-agent-dsh contract");
+		if (harness.delegationProvider !== "dsh-cli") fail("dsh harness registered with a delegation provider other than the local-agent-dsh contract");
+	}, { global: true });
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - plugin context carrying the invariant registry.
+* @returns the installed registration's disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };