@klarkxy/dsh-plugin-kit 0.4.0 → 0.6.0

package/lib/auxiliary-model.js

@@ -0,0 +1,354 @@
+import { AUXILIARY_MODEL_CHANGES_IDENTITY, AUXILIARY_MODEL_CHANNEL, AUXILIARY_MODEL_NS, AUXILIARY_MODEL_SERVICE, getAuxiliaryModel } from "./contracts.js";
+import { registerHostRpc } from "./host-rpc.js";
+import { notifyModelSettingsChanged, registerModelSettings } from "./model-settings.js";
+import { createModelSettingsChanges } from "./model-settings-changes.js";
+import { modelRouteOverride, normalizeModelRoute } from "@klarkxy/dsh-model-route";
+//#region src/auxiliary-model.ts
+const DOMAIN_NAME = "dsh_auxiliary";
+const DOMAIN_VERSION = 1;
+const TABLE = "settings";
+const KEY = "defaults";
+const INJECT = [
+	"storageDomain",
+	"webServer",
+	"connection"
+];
+/** Marker on the benign "released while the domain was still opening" error. */
+const RECOVERABLE = Symbol.for("klarkxy.dsh.auxiliary-model.recoverable");
+function recoverable(error) {
+	error[RECOVERABLE] = true;
+	return error;
+}
+async function openSharedDomain(scope) {
+	const [{ defineDomain, domainTable }, { z }] = await Promise.all([import("@deepseek-ai/dsh-storage-domain"), import("./zod.js")]);
+	const identifier = z.string().min(1).max(250).refine((value) => value === value.trim() && !/[\x00-\x1f\x7f]/.test(value), "model route identifiers must be non-blank, trimmed and control-free");
+	const model = z.union([z.object({
+		provider: identifier,
+		model: identifier,
+		reasoningEffort: identifier.max(80).optional()
+	}).strict(), z.null()]);
+	return scope.storageDomain.open(defineDomain({
+		name: DOMAIN_NAME,
+		version: DOMAIN_VERSION,
+		tables: { [TABLE]: domainTable(z.object({
+			revision: z.number().int().nonnegative(),
+			model
+		}).strict()) }
+	}));
+}
+/** Marks an optimistic-lock conflict so the RPC envelope can carry 'conflict'. */
+function conflictError(message) {
+	return Object.assign(new Error(message), { conflict: true });
+}
+/** RPC-visible error classification; storage failures stay sanitized. */
+function rpcFailure(error) {
+	if (error && typeof error === "object" && "conflict" in error) return {
+		ok: false,
+		error: {
+			code: "auxiliary-model/conflict",
+			message: error instanceof Error ? error.message : "Revision conflict"
+		}
+	};
+	if (error instanceof Error && /Invalid model route|valid expected revision|Unknown auxiliary model setting/.test(error.message)) return {
+		ok: false,
+		error: {
+			code: "auxiliary-model/rejected",
+			message: error.message
+		}
+	};
+	return {
+		ok: false,
+		error: {
+			code: "auxiliary-model/store",
+			message: "Auxiliary model store request failed"
+		}
+	};
+}
+/**
+* Serialized optimistic-lock write; resolves after the durable put commits.
+* Revision verification happens inside the queue: two writers carrying the
+* same expectedRevision race for one slot and only the first commits.
+* Notification fires only after commit, so a failed observer can never turn
+* an already committed write into an apparent save failure.
+*/
+function setSharedModel(state, ctx, input, expectedRevision) {
+	if (!Number.isSafeInteger(expectedRevision)) return Promise.reject(conflictError("A valid expected revision is required; reload and retry"));
+	const row = input && typeof input === "object" && !Array.isArray(input) ? input : void 0;
+	const validField = (value) => typeof value === "string" && value === value.trim() && !/[\x00-\x1f\x7f]/.test(value);
+	if (!row || [
+		"provider",
+		"model",
+		"reasoningEffort"
+	].some((key) => row[key] !== void 0 && !validField(row[key]))) return Promise.reject(/* @__PURE__ */ new Error("Invalid model route"));
+	const normalized = normalizeModelRoute(row);
+	if ((Boolean(row.provider) || Boolean(row.model)) && !modelRouteOverride(normalized)) return Promise.reject(/* @__PURE__ */ new Error("Invalid model route"));
+	const commit = state.tail.then(async () => {
+		if (state.closed || !state.domain) throw new Error("Auxiliary model settings are unloading; retry in a moment");
+		if (expectedRevision !== state.data.revision) throw conflictError("Auxiliary model settings changed; reload and retry");
+		const next = {
+			revision: state.data.revision + 1,
+			model: modelRouteOverride(normalized) ?? null
+		};
+		await state.domain.table(TABLE).put(KEY, {
+			revision: next.revision,
+			model: next.model
+		});
+		state.data = next;
+		notifyModelSettingsChanged(ctx.root, AUXILIARY_MODEL_NS, next.revision);
+		return next;
+	});
+	state.tail = commit.then(() => {}, () => {});
+	return commit;
+}
+function initScope(state, ctx, scope) {
+	const generation = ++state.generation;
+	let disposed = false;
+	scope.effect(() => () => {
+		disposed = true;
+	});
+	const stale = () => state.closed || disposed || state.generation !== generation;
+	const run = (async () => {
+		state.available = false;
+		const domain = await openSharedDomain(scope);
+		if (stale()) {
+			await domain.close();
+			throw recoverable(/* @__PURE__ */ new Error("Auxiliary model store released during open"));
+		}
+		state.domain = domain;
+		try {
+			scope.effect(() => () => domain.close());
+		} catch (error) {
+			await domain.close();
+			throw error;
+		}
+		const stored = domain.table(TABLE).get(KEY);
+		if (stale()) {
+			await domain.close();
+			throw recoverable(/* @__PURE__ */ new Error("Auxiliary model store superseded during open"));
+		}
+		state.data = {
+			revision: stored?.revision ?? 0,
+			model: stored?.model ?? null
+		};
+		state.error = void 0;
+		state.available = true;
+		scope.effect(() => registerModelSettings(scope, {
+			ns: AUXILIARY_MODEL_NS,
+			title: {
+				zh: "辅助模型",
+				en: "Auxiliary model"
+			},
+			read(signal) {
+				signal.throwIfAborted();
+				const { revision, model } = state.data;
+				return {
+					revision,
+					fields: [{
+						path: ["model"],
+						label: {
+							zh: "全局辅助模型",
+							en: "Global auxiliary model"
+						},
+						current: model ?? void 0,
+						allowFollow: true,
+						followLabel: {
+							zh: "当前会话模型",
+							en: "Current conversation model"
+						}
+					}]
+				};
+			},
+			async write(path, route, expectedRevision, signal) {
+				signal.throwIfAborted();
+				if (path.length !== 1 || path[0] !== "model") throw new Error("Unknown auxiliary model setting");
+				return setSharedModel(state, ctx, route, expectedRevision);
+			}
+		}));
+		scope.effect(() => registerHostRpc(scope, AUXILIARY_MODEL_CHANNEL, async (endpoint, payload, signal) => {
+			signal.throwIfAborted();
+			if (state.closed) return {
+				ok: false,
+				error: {
+					code: "auxiliary-model/unloading",
+					message: "Auxiliary model settings are unloading; retry in a moment"
+				}
+			};
+			if (!state.available) return state.error ? {
+				ok: false,
+				error: {
+					code: "auxiliary-model/store",
+					message: "Auxiliary model store request failed"
+				}
+			} : {
+				ok: false,
+				error: {
+					code: "auxiliary-model/unavailable",
+					message: "Auxiliary model settings are unavailable; retry in a moment"
+				}
+			};
+			if (endpoint === "defaults.get") {
+				const { revision, model } = state.data;
+				return {
+					ok: true,
+					value: {
+						revision,
+						model
+					}
+				};
+			}
+			if (endpoint === "defaults.set") try {
+				const body = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+				const value = await setSharedModel(state, ctx, body.model, body.expectedRevision);
+				signal.throwIfAborted();
+				return {
+					ok: true,
+					value
+				};
+			} catch (error) {
+				if (signal.aborted) throw error;
+				return rpcFailure(error);
+			}
+			return {
+				ok: false,
+				error: {
+					code: "auxiliary-model/unknown-endpoint",
+					message: `Unknown endpoint: ${endpoint}`
+				}
+			};
+		}, { isEndpoint: (endpoint) => /^[a-z.]+$/.test(endpoint) }));
+		createModelSettingsChanges(scope, AUXILIARY_MODEL_CHANGES_IDENTITY, AUXILIARY_MODEL_NS);
+		scope.effect(() => () => {
+			if (state.generation === generation) {
+				state.available = false;
+				state.domain = void 0;
+			}
+		});
+	})().catch((error) => {
+		if (error && typeof error === "object") error.auxGeneration = generation;
+		if (state.generation === generation) {
+			state.available = false;
+			state.error = error;
+		}
+		throw error;
+	});
+	run.catch(() => {});
+	const armed = run.then(() => {});
+	armed.catch(() => {});
+	state.ready = armed;
+	return run;
+}
+function teardown(state, ctx) {
+	if (!state.closing) {
+		state.closed = true;
+		const root = ctx.root;
+		state.closing = (async () => {
+			await state.scopeInit?.catch(() => {});
+			await state.tail.catch(() => {});
+			try {
+				await state.fiber?.dispose();
+			} catch (error) {
+				try {
+					ctx.logger?.warn("auxiliary-model: fiber dispose failed", error);
+				} catch {}
+			}
+			try {
+				if (root.get("dshAuxiliaryModel", false) === state) state.stopUnprovide?.();
+			} catch {}
+			state.stopUnprovide = void 0;
+		})();
+	}
+	return state.closing;
+}
+function createSharedState(ctx) {
+	const root = ctx.root;
+	const state = {
+		users: 0,
+		closed: false,
+		available: false,
+		generation: 0,
+		tail: Promise.resolve(),
+		data: {
+			revision: 0,
+			model: null
+		},
+		snapshot() {
+			if (this.error) throw this.error;
+			if (!this.available) throw new Error("Auxiliary model store is unavailable; retry in a moment");
+			return this.data;
+		},
+		ready: Promise.resolve(),
+		teardown() {
+			return teardown(this, ctx);
+		}
+	};
+	const inactive = INJECT.filter((service) => {
+		try {
+			return root.get(service, true) === void 0;
+		} catch {
+			return true;
+		}
+	});
+	if (inactive.length) throw new Error(`retainAuxiliaryModel requires active ${inactive.join(", ")}; declare them in inject`);
+	state.fiber = root.inject(INJECT, (scope) => {
+		state.scopeInit = initScope(state, ctx, scope);
+	});
+	state.ready = Promise.resolve(state.fiber).then(() => {
+		if (!state.scopeInit) throw recoverable(/* @__PURE__ */ new Error("Auxiliary model owner fiber settled without initializing its scope"));
+		return state.scopeInit;
+	});
+	state.ready.catch((error) => {
+		const tag = error.auxGeneration;
+		if (tag !== void 0 && tag !== state.generation) return;
+		state.error = state.error ?? error;
+		state.closed = true;
+		state.teardown();
+	});
+	state.stopUnprovide = root.provide(AUXILIARY_MODEL_SERVICE, state);
+	return state;
+}
+async function obtainShared(ctx) {
+	const root = ctx.root;
+	for (;;) {
+		const existing = root.get(AUXILIARY_MODEL_SERVICE, false);
+		if (existing) {
+			if (!existing.closed) return existing;
+			await existing.closing;
+			continue;
+		}
+		return createSharedState(ctx);
+	}
+}
+/**
+* Retain the shared auxiliary-model store for the calling plugin.
+*
+* Resolves once storage is open and the read/write surfaces are live, with a
+* release function; register it as `ctx.effect(() => release)` so the store
+* unloads with the plugin. The first participant opens the shared owner
+* fiber; `await release()` drains pending writes and fully tears the owner
+* down when the last participant leaves. Requires `storageDomain`,
+* `webServer` and `connection` to exist on the host.
+*
+* Concurrent retainers share one owner; a retain arriving during teardown
+* waits for the closing owner and then reinstalls — it never inherits a
+* half-torn-down state.
+*/
+async function retainAuxiliaryModel(ctx) {
+	for (;;) {
+		const state = await obtainShared(ctx);
+		await state.ready;
+		if (state.closed) continue;
+		state.users += 1;
+		let released = false;
+		return async () => {
+			if (released) return;
+			released = true;
+			state.users -= 1;
+			if (state.users <= 0) await state.teardown();
+			else await state.tail.catch(() => {});
+		};
+	}
+}
+//#endregion
+export { getAuxiliaryModel, retainAuxiliaryModel };
+
+//# sourceMappingURL=auxiliary-model.js.map

package/lib/auxiliary-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auxiliary-model.js","names":[],"sources":["../src/auxiliary-model.ts"],"sourcesContent":["/**\n * Shared auxiliary-model default: host-side lifecycle.\n *\n * The default model is repository-shared infrastructure, not one plugin's\n * business state. Its owner is a dedicated Cordis fiber started on the root\n * context by the first participant and disposed by the last release, so the\n * storage domain, the Typert change stream, the RPC channel and the\n * model-settings provider all live and die with the shared owner — never\n * with a business plugin's fiber. Every bundler's own copy of this module\n * rendezvous through `ctx.root`, so no participant depends on another being\n * enabled.\n *\n * Concurrency:\n * - Writes serialize on `state.tail`; the revision check and the bump both\n *   happen inside the queued commit, so two callers carrying the same\n *   expectedRevision cannot both succeed.\n * - `state.closing` is the single teardown promise: it settles init, drains\n *   queued writes, disposes the owner fiber (route, stream, provider,\n *   domain) and only then unprovides the state, so a re-entrant retain can\n *   always await it and reinstall cleanly.\n * - Initialization and stored-row failures are sticky (`state.error`) and\n *   rethrow from `snapshot()`: a storage error must never read as \"no\n *   default\" and silently fall back to another model.\n */\nimport type { Context } from '@deepseek-ai/cordis'\nimport { modelRouteOverride, normalizeModelRoute, type ModelRoute } from '@klarkxy/dsh-model-route'\nimport {\n  AUXILIARY_MODEL_CHANNEL, AUXILIARY_MODEL_CHANGES_IDENTITY, AUXILIARY_MODEL_NS,\n  AUXILIARY_MODEL_SERVICE, type AuxiliaryModelDefaults, type AuxiliaryModelShared, type RpcResult,\n} from './contracts.ts'\nimport { registerHostRpc, type HostRpcContext } from './host-rpc.ts'\nimport { createModelSettingsChanges } from './model-settings-changes.ts'\nimport { registerModelSettings, notifyModelSettingsChanged, type ModelSettingsEvents } from './model-settings.ts'\n\nconst DOMAIN_NAME = 'dsh_auxiliary'\nconst DOMAIN_VERSION = 1\nconst TABLE = 'settings'\nconst KEY = 'defaults'\nconst INJECT = ['storageDomain', 'webServer', 'connection'] as const\n\ninterface DomainHandle {\n  table(name: string): {\n    get(key: string): { revision: number; model: ModelRoute | null } | undefined\n    put(key: string, value: unknown): Promise<void>\n  }\n  close(): Promise<void>\n}\n\ninterface Scope extends HostRpcContext, ModelSettingsEvents {\n  storageDomain: { open(spec: unknown): Promise<DomainHandle> }\n  effect(callback: () => (() => void) | Promise<(() => void) | void>): unknown\n}\n\ninterface RootLike {\n  get(name: string, strict?: boolean): unknown\n  provide(name: string, value: unknown): () => void\n  inject(deps: readonly string[], callback: (scope: Scope) => void): { dispose(): Promise<void> } & PromiseLike<unknown>\n}\n\ninterface SharedState extends AuxiliaryModelShared {\n  ready: Promise<void>\n  users: number\n  closed: boolean\n  /** True only while the owner fiber's domain is open; snapshot() gates on it. */\n  available: boolean\n  /** Generation of the latest scope init; a stale run must not win. */\n  generation: number\n  /** Sticky init/storage failure; snapshot() rethrows it. */\n  error?: unknown\n  closing?: Promise<void>\n  domain?: DomainHandle\n  data: AuxiliaryModelDefaults\n  tail: Promise<void>\n  fiber?: { dispose(): Promise<void> }\n  scopeInit?: Promise<void>\n  stopUnprovide?: () => void\n  teardown(): Promise<void>\n}\n\n/** Marker on the benign \"released while the domain was still opening\" error. */\nconst RECOVERABLE = Symbol.for('klarkxy.dsh.auxiliary-model.recoverable')\nfunction recoverable<T extends object>(error: T): T & { [RECOVERABLE]?: boolean } {\n  (error as Record<symbol, unknown>)[RECOVERABLE] = true\n  return error as T & { [RECOVERABLE]?: boolean }\n}\n\nasync function openSharedDomain(scope: Scope): Promise<DomainHandle> {\n  const [{ defineDomain, domainTable }, { z }] = await Promise.all([\n    import('@deepseek-ai/dsh-storage-domain'), import('zod'),\n  ])\n  // Strict, write-side semantics at the durable boundary: identifiers must be\n  // non-blank, already trimmed and control-free, or the row is rejected —\n  // a malformed stored route must never normalize into \"no default\".\n  const identifier = z.string().min(1).max(250).refine(\n    value => value === value.trim() && !/[\\x00-\\x1f\\x7f]/.test(value),\n    'model route identifiers must be non-blank, trimmed and control-free',\n  )\n  const model = z.union([\n    z.object({\n      provider: identifier,\n      model: identifier,\n      reasoningEffort: identifier.max(80).optional(),\n    }).strict(),\n    z.null(),\n  ])\n  return scope.storageDomain.open(defineDomain({\n    name: DOMAIN_NAME, version: DOMAIN_VERSION,\n    tables: {\n      [TABLE]: domainTable(z.object({\n        revision: z.number().int().nonnegative(),\n        model,\n      }).strict()),\n    },\n  }))\n}\n\n/** Marks an optimistic-lock conflict so the RPC envelope can carry 'conflict'. */\nfunction conflictError(message: string): Error & { conflict: true } {\n  return Object.assign(new Error(message), { conflict: true as const })\n}\n\n/** RPC-visible error classification; storage failures stay sanitized. */\nfunction rpcFailure(error: unknown): RpcResult {\n  if (error && typeof error === 'object' && 'conflict' in error) {\n    return { ok: false, error: { code: 'auxiliary-model/conflict', message: error instanceof Error ? error.message : 'Revision conflict' } }\n  }\n  if (error instanceof Error && /Invalid model route|valid expected revision|Unknown auxiliary model setting/.test(error.message)) {\n    return { ok: false, error: { code: 'auxiliary-model/rejected', message: error.message } }\n  }\n  return { ok: false, error: { code: 'auxiliary-model/store', message: 'Auxiliary model store request failed' } }\n}\n\n/**\n * Serialized optimistic-lock write; resolves after the durable put commits.\n * Revision verification happens inside the queue: two writers carrying the\n * same expectedRevision race for one slot and only the first commits.\n * Notification fires only after commit, so a failed observer can never turn\n * an already committed write into an apparent save failure.\n */\nfunction setSharedModel(state: SharedState, ctx: Context, input: unknown, expectedRevision: unknown): Promise<AuxiliaryModelDefaults> {\n  if (!Number.isSafeInteger(expectedRevision)) return Promise.reject(conflictError('A valid expected revision is required; reload and retry'))\n  const row = input && typeof input === 'object' && !Array.isArray(input) ? input as Record<string, unknown> : undefined\n  const validField = (value: unknown): value is string =>\n    typeof value === 'string' && value === value.trim() && !/[\\x00-\\x1f\\x7f]/.test(value)\n  if (!row || ['provider', 'model', 'reasoningEffort'].some(key => row[key] !== undefined && !validField(row[key]))) {\n    return Promise.reject(new Error('Invalid model route'))\n  }\n  const normalized = normalizeModelRoute(row)\n  if ((Boolean(row.provider) || Boolean(row.model)) && !modelRouteOverride(normalized)) {\n    return Promise.reject(new Error('Invalid model route'))\n  }\n  const commit = state.tail.then(async (): Promise<AuxiliaryModelDefaults> => {\n    if (state.closed || !state.domain) throw new Error('Auxiliary model settings are unloading; retry in a moment')\n    if (expectedRevision !== state.data.revision) throw conflictError('Auxiliary model settings changed; reload and retry')\n    const next: AuxiliaryModelDefaults = { revision: state.data.revision + 1, model: modelRouteOverride(normalized) ?? null }\n    await state.domain.table(TABLE).put(KEY, { revision: next.revision, model: next.model })\n    state.data = next\n    notifyModelSettingsChanged(ctx.root, AUXILIARY_MODEL_NS, next.revision)\n    return next\n  })\n  // The tail itself never rejects: a failed commit must not poison later writes.\n  state.tail = commit.then(() => {}, () => {})\n  return commit\n}\n\nfunction initScope(state: SharedState, ctx: Context, scope: Scope): Promise<void> {\n  // A dependency loss unloads this fiber (running its disposers) and a\n  // remount re-runs the callback (bumping state.generation), so an init that\n  // was still opening always detects its own supersession through these two\n  // public signals. Service identity is intentionally NOT compared anywhere:\n  // `ctx.<service>` reads hand out a fresh traceable proxy per access for\n  // every tracker'd impl (all Service subclasses — storageDomain, webServer,\n  // connection), so identity comparisons reported a fake dep swap after each\n  // await and aborted every open with 'released during open'.\n  const generation = ++state.generation\n  let disposed = false\n  // Registered synchronously while the callback runs; a throw means the\n  // fiber is already inactive and this init must not open anything.\n  scope.effect(() => () => { disposed = true })\n  const stale = () => state.closed || disposed || state.generation !== generation\n  const run = (async () => {\n    // Reads must stay unavailable until this init completes.\n    state.available = false\n    const domain = await openSharedDomain(scope)\n    if (stale()) { await domain.close(); throw recoverable(new Error('Auxiliary model store released during open')) }\n    state.domain = domain\n    // scope.effect throws on an inactive fiber (disposed mid-open): close the\n    // domain directly so it is never leaked, then rethrow — a store that\n    // cannot register its own cleanup must not publish data.\n    try { scope.effect(() => () => domain.close()) } catch (error) { await domain.close(); throw error }\n    // Strict schema: a malformed stored row fails the open path instead of\n    // silently collapsing to \"no default\".\n    const stored = domain.table(TABLE).get(KEY)\n    if (stale()) { await domain.close(); throw recoverable(new Error('Auxiliary model store superseded during open')) }\n    state.data = { revision: stored?.revision ?? 0, model: stored?.model ?? null }\n    state.error = undefined\n    state.available = true\n    scope.effect(() => registerModelSettings(scope, {\n      ns: AUXILIARY_MODEL_NS,\n      title: { zh: '辅助模型', en: 'Auxiliary model' },\n      read(signal) {\n        signal.throwIfAborted()\n        const { revision, model } = state.data\n        return {\n          revision,\n          fields: [{\n            path: ['model'],\n            label: { zh: '全局辅助模型', en: 'Global auxiliary model' },\n            current: model ?? undefined,\n            allowFollow: true,\n            followLabel: { zh: '当前会话模型', en: 'Current conversation model' },\n          }],\n        }\n      },\n      async write(path, route, expectedRevision, signal) {\n        signal.throwIfAborted()\n        if (path.length !== 1 || path[0] !== 'model') throw new Error('Unknown auxiliary model setting')\n        return setSharedModel(state, ctx, route, expectedRevision)\n      },\n    }))\n    scope.effect(() => registerHostRpc(scope, AUXILIARY_MODEL_CHANNEL, async (endpoint, payload, signal) => {\n      signal.throwIfAborted()\n      if (state.closed) return { ok: false, error: { code: 'auxiliary-model/unloading', message: 'Auxiliary model settings are unloading; retry in a moment' } } satisfies RpcResult\n      if (!state.available) {\n        return state.error\n          ? { ok: false, error: { code: 'auxiliary-model/store', message: 'Auxiliary model store request failed' } } satisfies RpcResult\n          : { ok: false, error: { code: 'auxiliary-model/unavailable', message: 'Auxiliary model settings are unavailable; retry in a moment' } } satisfies RpcResult\n      }\n      if (endpoint === 'defaults.get') {\n        const { revision, model } = state.data\n        return { ok: true, value: { revision, model } } satisfies RpcResult\n      }\n      if (endpoint === 'defaults.set') {\n        try {\n          const body = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload as Record<string, unknown> : {}\n          const value = await setSharedModel(state, ctx, body.model, body.expectedRevision)\n          signal.throwIfAborted()\n          return { ok: true, value } satisfies RpcResult\n        } catch (error) {\n          if (signal.aborted) throw error\n          return rpcFailure(error)\n        }\n      }\n      return { ok: false, error: { code: 'auxiliary-model/unknown-endpoint', message: `Unknown endpoint: ${endpoint}` } } satisfies RpcResult\n    }, { isEndpoint: endpoint => /^[a-z.]+$/.test(endpoint) }))\n    // The change stream lives and dies with this shared fiber.\n    createModelSettingsChanges(scope as unknown as Context, AUXILIARY_MODEL_CHANGES_IDENTITY, AUXILIARY_MODEL_NS)\n    // Disposers run LIFO on unload: registered last, this runs FIRST when a\n    // dependency remount tears the scope down — reads go unavailable before\n    // the domain closes, so no stale default ever leaks. Gated on generation\n    // alone: the same generation's unload must clear state even when its dep\n    // impl just changed; only a superseded scope's teardown stays out.\n    scope.effect(() => () => { if (state.generation === generation) { state.available = false; state.domain = undefined } })\n  })().catch(error => {\n    // Tag the failure with its generation so ready.catch can distinguish a\n    // superseded init's rejection from the live scope's.\n    if (error && typeof error === 'object') (error as Record<string, unknown>).auxGeneration = generation\n    // Only THIS generation's failure poisons the store: a superseded init's\n    // rejection must not clear a newer scope's available state.\n    if (state.generation === generation) {\n      state.available = false\n      state.error = error\n    }\n    throw error\n  })\n  // Retainers always await the CURRENT init: re-arm state.ready so nobody is\n  // left waiting on a superseded generation's settled promise. Both promises\n  // get a handled branch so a rejected init never surfaces as an unhandled\n  // rejection while awaiters still see it.\n  run.catch(() => {})\n  const armed = run.then(() => {})\n  armed.catch(() => {})\n  state.ready = armed\n  return run\n}\n\nfunction teardown(state: SharedState, ctx: Context): Promise<void> {\n  if (!state.closing) {\n    state.closed = true\n    const root = ctx.root as unknown as RootLike\n    state.closing = (async () => {\n      // A still-opening init settles here so its domain/fiber are disposed.\n      await state.scopeInit?.catch(() => {})\n      await state.tail.catch(() => {})\n      try { await state.fiber?.dispose() } catch (error) {\n        // A failed dispose may leave the domain open; log loudly so the next\n        // open's 'already open' error is attributable instead of mysterious.\n        try { (ctx as unknown as { logger?: { warn(...args: unknown[]): void } }).logger?.warn('auxiliary-model: fiber dispose failed', error) }\n        catch { /* no logger */ }\n      }\n      try {\n        if (root.get(AUXILIARY_MODEL_SERVICE, false) === state) state.stopUnprovide?.()\n      } catch { /* root already gone */ }\n      state.stopUnprovide = undefined\n    })()\n  }\n  return state.closing\n}\n\nfunction createSharedState(ctx: Context): SharedState {\n  const root = ctx.root as unknown as RootLike\n  const state: SharedState = {\n    users: 0, closed: false, available: false, generation: 0, tail: Promise.resolve(),\n    data: { revision: 0, model: null },\n    snapshot() {\n      // A persisted-open failure propagates: falling back to another model\n      // after a storage error would silently switch what the user pays for.\n      if (this.error) throw this.error\n      // While the owner fiber re-initializes after a dependency remount, the\n      // stored default is unreadable: reads fail instead of serving stale data.\n      if (!this.available) throw new Error('Auxiliary model store is unavailable; retry in a moment')\n      return this.data\n    },\n    ready: Promise.resolve(),\n    teardown() { return teardown(this, ctx) },\n  }\n  // Strict requirement: every service must already be ACTIVE. Callers are\n  // plugins declaring these in inject — Cordis only runs their apply once the\n  // deps are active, so a missing or still-pending service is a hard error,\n  // not something to wait on. Retry is the caller's Cordis lifecycle, not ours.\n  const inactive = INJECT.filter(service => {\n    try { return root.get(service, true) === undefined } catch { return true }\n  })\n  if (inactive.length) {\n    throw new Error(`retainAuxiliaryModel requires active ${inactive.join(', ')}; declare them in inject`)\n  }\n  state.fiber = root.inject(INJECT, scope => { state.scopeInit = initScope(state, ctx, scope) })\n  state.ready = Promise.resolve(state.fiber).then(() => {\n    // The owner fiber ran to settle: its scope must have started init, and\n    // that init must complete before the store reads as ready. A dep dropping\n    // between the strict check and inject leaves the fiber PENDING; Cordis\n    // re-runs it when the dep returns — never a silent half-initialized read.\n    if (!state.scopeInit) throw recoverable(new Error('Auxiliary model owner fiber settled without initializing its scope'))\n    return state.scopeInit\n  })\n  // A failed open must not leave a live-looking state behind: mark it\n  // closed and tear it down so the next retain reinstalls. A rejection\n  // tagged with a superseded generation describes a scope this state has\n  // already moved past — it must not tear down a newer, live scope.\n  state.ready.catch(error => {\n    const tag = (error as { auxGeneration?: number }).auxGeneration\n    if (tag !== undefined && tag !== state.generation) return\n    state.error = state.error ?? error\n    state.closed = true\n    void state.teardown()\n  })\n  // Publish only after construction completes: another retainer can now\n  // either reuse this state or watch its closed flag.\n  state.stopUnprovide = root.provide(AUXILIARY_MODEL_SERVICE, state)\n  return state\n}\n\nasync function obtainShared(ctx: Context): Promise<SharedState> {\n  const root = ctx.root as unknown as RootLike\n  for (;;) {\n    const existing = root.get(AUXILIARY_MODEL_SERVICE, false) as SharedState | undefined\n    if (existing) {\n      if (!existing.closed) return existing\n      // closing always settles; wait for it, then re-lookup.\n      await existing.closing\n      continue\n    }\n    return createSharedState(ctx)\n  }\n}\n\n/**\n * Retain the shared auxiliary-model store for the calling plugin.\n *\n * Resolves once storage is open and the read/write surfaces are live, with a\n * release function; register it as `ctx.effect(() => release)` so the store\n * unloads with the plugin. The first participant opens the shared owner\n * fiber; `await release()` drains pending writes and fully tears the owner\n * down when the last participant leaves. Requires `storageDomain`,\n * `webServer` and `connection` to exist on the host.\n *\n * Concurrent retainers share one owner; a retain arriving during teardown\n * waits for the closing owner and then reinstalls — it never inherits a\n * half-torn-down state.\n */\nexport async function retainAuxiliaryModel(ctx: Context): Promise<() => Promise<void>> {\n  for (;;) {\n    const state = await obtainShared(ctx)\n    // One await, one answer: a failed or superseded init rejects the retainer\n    // once. The caller's plugin lifecycle (inject refresh) drives any retry —\n    // no same-state spin here.\n    await state.ready\n    if (state.closed) continue\n    state.users += 1\n    let released = false\n    return async () => {\n      if (released) return\n      released = true\n      state.users -= 1\n      if (state.users <= 0) await state.teardown()\n      else await state.tail.catch(() => {})\n    }\n  }\n}\n\n/**\n * Re-exported here so consumers reading the shared default use the same\n * subpath as the store lifecycle: '@klarkxy/dsh-plugin-kit/auxiliary-model'.\n */\nexport { getAuxiliaryModel } from './contracts.ts'\n"],"mappings":"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"}

package/lib/client-utils.d.ts

@@ -1,3 +1,5 @@
+import { ReactNode } from "react";
+import { Context } from "@deepseek-ai/cordis";
 //#region src/client-utils.d.ts
 /** Fixed pause for failing background reads; manual work is never replayed. */
 declare function createPluginReadGate(now?: () => number): {
@@ -53,6 +55,48 @@ declare function useNativeSeat(client: NativeSurfaceClient, props?: unknown): {
 };
 /** Refresh on native log boundaries/reconnect/focus. Read-only settling is bounded to an observed job. */
 declare function useFeatureRefresh(client: NativeSurfaceClient, sessionId: string, refresh: () => void, working?: boolean, enabled?: boolean): void;
+/** A row contributed into the shared Session Management page. */
+interface SessionSettingsItemSpec {
+  readonly id: string;
+  readonly order: number;
+}
+/** Owner props the host's `settings.section.icon` seat hands to its cell. */
+interface SettingsSectionIconProps {
+  readonly size?: number;
+  /** Selection state; the nav styles active icons through color, not geometry. */
+  readonly active?: boolean;
+}
+/** Chat bubble for the shared Session Management section. */
+declare const IconSessionSettings: (props: SettingsSectionIconProps) => ReactNode;
+/** Serif-flavoured letter A for the Font section. */
+declare const IconFontSettings: (props: SettingsSectionIconProps) => ReactNode;
+/** Keyboard for the Shortcuts section. */
+declare const IconKeyboardSettings: (props: SettingsSectionIconProps) => ReactNode;
+/** Linked model nodes for the Model Management section. */
+declare const IconModelNetworkSettings: (props: SettingsSectionIconProps) => ReactNode;
+/**
+ * Contribute the nav icon of a `settings.section` entry. The `settings
+ * .section.icon` seat is declared by the host independently of the section
+ * list, so the wait runs in parallel: the icon appears as soon as both seats
+ * exist and unloading removes it again, restoring the host's default glyph.
+ * The `id` must equal the section id; `order`/`priority` mirror `order` so the
+ * icon cell sorts like its section and, for shared sections, several
+ * contributors can register the same icon id under different priorities
+ * without duplicating nav entries.
+ */
+declare function registerSettingsSectionIcon(ctx: Context, sectionId: string, order: number, component: (props: SettingsSectionIconProps) => ReactNode): () => void;
+/**
+ * Contribute one row to the shared Session Management settings page.
+ *
+ * `ctx` is the plugin's own context: the row's slot wait unloads with the
+ * plugin, while the page itself is retained on the shared root context for as
+ * long as any contributor lives. There is no fallback seat — when every
+ * contributor is gone the section disappears with the page. Returns a disposer.
+ * Shared root-owned infrastructure (the auxiliary-model card) calls this on
+ * `ctx.root` so its row, icon and page share are owned by the root lifetime
+ * and released by the returned disposer, not by any plugin fiber.
+ */
+declare function registerSessionSettingsItem(ctx: Context, item: SessionSettingsItemSpec, component: (props: never) => ReactNode): () => void;
 //#endregion
-export { NativeSurfaceClient, createPluginReadGate, selectedSessionId, useFeatureRefresh, useNativeSeat };
+export { IconFontSettings, IconKeyboardSettings, IconModelNetworkSettings, IconSessionSettings, NativeSurfaceClient, SessionSettingsItemSpec, SettingsSectionIconProps, createPluginReadGate, registerSessionSettingsItem, registerSettingsSectionIcon, selectedSessionId, useFeatureRefresh, useNativeSeat };
 //# sourceMappingURL=client-utils.d.ts.map

package/lib/client-utils.js

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { SESSION_SETTINGS_ITEM_SLOT, SESSION_SETTINGS_SECTION_ID, SETTINGS_SECTION_ICON_SLOT } from "./contracts.js";
+import { createElement, useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 //#region src/client-utils.ts
 /** Fixed pause for failing background reads; manual work is never replayed. */
 function createPluginReadGate(now = Date.now) {
@@ -112,7 +113,191 @@ function useFeatureRefresh(client, sessionId, refresh, working = false, enabled
 		enabled
 	]);
 }
+/** One `<svg>` with the shared icon chrome; children are plain elements. */
+function lineIcon(children) {
+	return function SettingsSectionIcon(props) {
+		return createElement("svg", {
+			"aria-hidden": "true",
+			width: props.size ?? 16,
+			height: props.size ?? 16,
+			viewBox: "0 0 16 16",
+			fill: "none",
+			stroke: "currentColor",
+			strokeWidth: 1,
+			strokeLinecap: "round",
+			strokeLinejoin: "round"
+		}, ...children.map(([tag, attrs], index) => createElement(tag, {
+			key: index,
+			...attrs
+		})));
+	};
+}
+/** Chat bubble for the shared Session Management section. */
+const IconSessionSettings = lineIcon([["path", { d: "M8.5 13a5.5 5.5 0 0 0 5.5-5.5A5.5 5.5 0 0 0 8.5 2 5.5 5.5 0 0 0 3 7.5a5.48 5.48 0 0 0 .9 3L2.8 12.6a.5.5 0 0 0 .62.62l2.9-.98a5.48 5.48 0 0 0 2.18.76Z" }]]);
+/** Serif-flavoured letter A for the Font section. */
+const IconFontSettings = lineIcon([
+	["path", { d: "M3.3 12.6 7.9 3.1a.5.5 0 0 1 .9 0l4.6 9.5" }],
+	["path", { d: "M5.2 9.4h6.3" }],
+	["path", { d: "M2.4 12.6h2.4" }],
+	["path", { d: "M11.9 12.6h2.4" }]
+]);
+/** Keyboard for the Shortcuts section. */
+const IconKeyboardSettings = lineIcon([
+	["rect", {
+		x: 1.75,
+		y: 4.75,
+		width: 12.5,
+		height: 7.5,
+		rx: 1.2
+	}],
+	["path", { d: "M4.5 7.25h0" }],
+	["path", { d: "M8 7.25h0" }],
+	["path", { d: "M11.5 7.25h0" }],
+	["path", { d: "M5.25 9.75h5.5" }]
+]);
+/** Linked model nodes for the Model Management section. */
+const IconModelNetworkSettings = lineIcon([
+	["line", {
+		x1: 10.6,
+		y1: 5.3,
+		x2: 8.8,
+		y2: 7.1
+	}],
+	["line", {
+		x1: 7.2,
+		y1: 8.9,
+		x2: 5.4,
+		y2: 10.7
+	}],
+	["circle", {
+		cx: 12,
+		cy: 4,
+		r: 1.9
+	}],
+	["circle", {
+		cx: 4,
+		cy: 12,
+		r: 1.9
+	}],
+	["circle", {
+		cx: 8,
+		cy: 8,
+		r: 1.5
+	}]
+]);
+/**
+* Contribute the nav icon of a `settings.section` entry. The `settings
+* .section.icon` seat is declared by the host independently of the section
+* list, so the wait runs in parallel: the icon appears as soon as both seats
+* exist and unloading removes it again, restoring the host's default glyph.
+* The `id` must equal the section id; `order`/`priority` mirror `order` so the
+* icon cell sorts like its section and, for shared sections, several
+* contributors can register the same icon id under different priorities
+* without duplicating nav entries.
+*/
+function registerSettingsSectionIcon(ctx, sectionId, order, component) {
+	const slots = ctx.slots;
+	return slots.inject(SETTINGS_SECTION_ICON_SLOT, () => slots.register({
+		name: SETTINGS_SECTION_ICON_SLOT,
+		id: sectionId,
+		order,
+		priority: order
+	}, component));
+}
+/** Private Cordis rendezvous; every bundled copy of this helper resolves the same root service. */
+const SESSION_SETTINGS_PAGE_SERVICE = "dshSessionSettingsPage";
+/** The page component renders only its declared child list: items paint their own titles and styles. */
+function SessionSettingsPageView(props) {
+	return props.renderSlot(SESSION_SETTINGS_ITEM_SLOT, {});
+}
+/**
+* Acquire the root-owned page service, creating and providing it on first use.
+* One counter covers participants, the section wait and the provider: the last
+* release removes the wait and then the provider synchronously (Cordis deletes
+* the impl before its async disposer awaits), so a later acquire sees a clean
+* get() miss and can re-establish the page.
+*/
+function acquireSessionSettingsPage(root) {
+	const existing = root.get(SESSION_SETTINGS_PAGE_SERVICE, false);
+	if (existing) return existing;
+	const slots = root.slots;
+	let users = 0;
+	let stopPage;
+	let unprovide;
+	const page = {
+		retain() {
+			users += 1;
+			if (!stopPage) stopPage = slots.inject("settings.section", () => slots.register({
+				name: "settings.section",
+				id: SESSION_SETTINGS_SECTION_ID,
+				order: 30,
+				label: () => {
+					const locale = root.get("locale", false);
+					return String(locale?.getSnapshot?.().active ?? "").startsWith("zh") ? "会话管理" : "Session Management";
+				},
+				children: { [SESSION_SETTINGS_ITEM_SLOT]: {
+					kind: "list",
+					scope: "root"
+				} }
+			}, SessionSettingsPageView));
+		},
+		release() {
+			if (users <= 0) return;
+			users -= 1;
+			if (users > 0) return;
+			stopPage?.();
+			stopPage = void 0;
+			unprovide?.();
+		}
+	};
+	unprovide = root.provide(SESSION_SETTINGS_PAGE_SERVICE, page);
+	return page;
+}
+/**
+* Contribute one row to the shared Session Management settings page.
+*
+* `ctx` is the plugin's own context: the row's slot wait unloads with the
+* plugin, while the page itself is retained on the shared root context for as
+* long as any contributor lives. There is no fallback seat — when every
+* contributor is gone the section disappears with the page. Returns a disposer.
+* Shared root-owned infrastructure (the auxiliary-model card) calls this on
+* `ctx.root` so its row, icon and page share are owned by the root lifetime
+* and released by the returned disposer, not by any plugin fiber.
+*/
+function registerSessionSettingsItem(ctx, item, component) {
+	const slots = ctx.slots;
+	const root = ctx.root;
+	const page = acquireSessionSettingsPage(root);
+	let stopItem;
+	let stopIcon;
+	try {
+		page.retain();
+		stopItem = slots.inject(SESSION_SETTINGS_ITEM_SLOT, () => slots.register({
+			name: SESSION_SETTINGS_ITEM_SLOT,
+			...item
+		}, component));
+		stopIcon = slots.inject(SETTINGS_SECTION_ICON_SLOT, () => slots.register({
+			name: SETTINGS_SECTION_ICON_SLOT,
+			id: SESSION_SETTINGS_SECTION_ID,
+			order: item.order,
+			priority: item.order
+		}, IconSessionSettings));
+	} catch (error) {
+		stopIcon?.();
+		stopItem?.();
+		page.release();
+		throw error;
+	}
+	let disposed = false;
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		stopIcon?.();
+		stopItem?.();
+		page.release();
+	};
+}
 //#endregion
-export { createPluginReadGate, selectedSessionId, useFeatureRefresh, useNativeSeat };
+export { IconFontSettings, IconKeyboardSettings, IconModelNetworkSettings, IconSessionSettings, createPluginReadGate, registerSessionSettingsItem, registerSettingsSectionIcon, selectedSessionId, useFeatureRefresh, useNativeSeat };
 
 //# sourceMappingURL=client-utils.js.map