@deepseek-ai/dsh-api-session-controller 0.1.7-rc.1 → 0.2.0-rc.1

package/README.i18n.yaml

@@ -1,6 +1,40 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/session-controller/README.md
-README.md: 728d98b90aa96829a878b071c03af3ec961c839e
-README.zh.md: 9a2c54b6865302e69daa5f67ec9baa17255f8100
+/:
+  en: 82789442228fc62a
+  zh: f1d511ad838187de
+/session-controller:
+  en: c7a4c58ea6d3437b
+  zh: 45c2b472a074bb1b
+/session-controller/summary:
+  en: 4914824c347fdab5
+  zh: 684a7b7fa970c39f
+/session-controller/table-of-contents:
+  en: 1fdf707322fb6996
+  zh: 0204f7e9d4aa3cce
+/session-controller/use-this-package:
+  en: b1a66e01de414924
+  zh: 7c01f66b94b01ff9
+/session-controller/client-references:
+  en: 41bdda1ac32df558
+  zh: aa5d0e325924066b
+/session-controller/session-media-references:
+  en: 266ab2b1e2fec542
+  zh: b3450ae28a1e0baf
+/session-controller/configuration:
+  en: 5c4c4224074e38a8
+  zh: e0b0edac65c88ff4
+/session-controller/model-experience:
+  en: 30b917bf822bb4df
+  zh: b0b023b5b526c317
+/session-controller/model-experience/kv-cache-effect:
+  en: 22fc0c9dbedd3bb6
+  zh: fad040ca55fd0e0a
+/session-controller/known-limitations-and-deferred-work:
+  en: e896bfcaf38b4f6c
+  zh: 55a4eba838f166de
+/session-controller/known-limitations-and-deferred-work/dev-note:
+  en: 68e0dfe4588c5b88
+  zh: db51b435611bded1

package/README.md

@@ -6,6 +6,8 @@ kind: "package-reference"
 
 English | [中文](README.zh.md)
 
+Desktop analytics follows the [product collection policy](../../client/product-analytics/README.md), including its launch-time switch. Web usage is excluded.
+
 ## Summary
 
 `@deepseek-ai/dsh-api-session-controller` owns the Host `ctx.sessionController` service and the generated Client `session`, `skills`, and `fileReferences` Remote namespaces. It serves Session lifecycle and history, the Host-generation model catalog, human background-job kill, workspace-path opening, user-invocable skill discovery, and Agent-scoped file references. Use it through API Gateway when a Client needs operations addressed by a Session.
@@ -78,7 +80,9 @@ References keep local Session data, scoped Contexts, and history streams alive,
 
 `SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when `connection`, `fs`, and `attachments` are composed. It reads ordinary files through `ctx.fs`, including temporary paths outside registered workspaces and files in remote providers. Neither directory containment nor MIME categories restrict access; `mime-types` supplies the response type, with `application/octet-stream` for unknown extensions. GET reuses `readBytes` for preflight and ongoing byte limits; HEAD reads metadata only. All files use `ctx.attachments.imageLimits.maxImageBytes` (normally 20 MiB); exceeding this limit returns 413. Responses contain the complete file, ignore Range, and carry `private, no-store`, `nosniff`, and a sandbox CSP so directly opened HTML/SVG cannot execute with the API origin. The Client rewrite lives in `ui-chat` (`AssistantMarkdown`); audio/video responses are available, while Markdown audio/video player nodes remain separate work.
 
-`workspacePathApplications({ path })` returns the serving desktop’s file handlers after the same filesystem mapping check used by `openWorkspacePath`. An optional `application` in the open request selects a currently registered handler without changing the system default. Application names, default selection, icons, and platform coverage come from [native-command](../../util/native-command/README.md). These operations do not activate an Agent or append Session events. Native failures return bounded messages; original command errors remain Host-side causes.
+GUI model selection requires the exact provider/model pair in the available catalog; unavailable choices reject with `session/model-unavailable`. Prompt admission retains the saved route without a catalog availability gate, so request execution reports missing credentials or unavailable models. `initializeDefaultModel()` saves the first available account model after login when no other provider has a configured API key; credential checks use configured references independently of model availability. A provider with no available models rejects initialization with `session/provider-models-unavailable`. Availability never substitutes another model or rewrites a Session selection.
+
+A successful `selectModel` response acknowledges the Session-local selection without waiting for the default profile setting to save. Default saves run in the background in submission order; a failure logs a warning and leaves the Session selection intact. New Sessions read the last successfully saved default.
 
 -----
 

package/README.zh.md

@@ -6,6 +6,8 @@ kind: "package-reference"
 
 [English](README.md) | 中文
 
+桌面埋点遵循[产品采集策略](../../client/product-analytics/README.zh.md)及其启动时开关，不包含 Web 使用情况。
+
 ## 概述
 
 `@deepseek-ai/dsh-api-session-controller` 拥有 Host 的 `ctx.sessionController` 服务，以及生成的 Client `session`、`skills` 和 `fileReferences` Remote namespace。它提供 Session 生命周期与历史、Host generation 模型目录、人工后台任务终止、工作区路径打开、用户可调用 skill（技能）发现和 Agent（智能体）范围的文件引用。当 Client 需要按 Session 寻址的操作时，请通过 API Gateway 使用它。
@@ -78,7 +80,9 @@ Client 的首次 `follow`、重连首屏与 `loadOlder()` 至少请求 50 条以
 
 当 `connection`、`fs` 与 `attachments` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`。它通过 `ctx.fs` 读取普通文件，包括已注册工作区之外的临时路径与远程提供方中的文件。目录包含关系与 MIME 类别均不限制访问；`mime-types` 提供响应类型，未知扩展名使用 `application/octet-stream`。GET 复用 `readBytes` 执行读取前及读取中的字节限制；HEAD 只读取元数据。所有文件均使用 `ctx.attachments.imageLimits.maxImageBytes`（通常为 20 MiB）；超过此上限返回 413。响应包含完整文件，忽略 Range，并携带 `private, no-store`、`nosniff` 与沙箱 CSP，使直接打开的 HTML/SVG 无法以 API 源身份执行脚本。客户端重写位于 `ui-chat`（`AssistantMarkdown`）；音视频文件响应已可用，Markdown 音视频播放器节点仍是独立工作。
 
-`workspacePathApplications({ path })` 使用与 `openWorkspacePath` 相同的文件系统映射校验，返回服务端桌面上该文件的关联应用。打开请求中的可选 `application` 指定当前关联的应用，不修改系统默认应用。应用名称、默认项、图标和平台支持范围由 [native-command](../../util/native-command/README.zh.md) 提供。这些操作不激活 Agent，也不追加会话事件。原生操作失败时返回简短消息，原始命令异常作为 Host 端原因保留。
+GUI 模型选择要求确切提供方／模型对出现在可用目录中；不可用的选择以 `session/model-unavailable` 拒绝。提示词准入保留已保存的路由，不按目录可用性阻断发送，由请求执行报告凭据缺失或模型不可用。`initializeDefaultModel()` 在账号登录后、其他提供方均未配置 API key 时，将第一个可用账号模型保存为默认模型；凭据检查使用已配置的引用，不依赖模型是否可用。提供方没有可用模型时，初始化以 `session/provider-models-unavailable` 拒绝。可用性变化不会替换模型或改写会话选择。
+
+`selectModel` 成功返回表示会话级模型选择已生效，不等待默认 profile 设置保存。默认设置在后台按提交顺序保存；保存失败会记录警告，并保留会话选择。新会话读取最近一次成功保存的默认值。
 
 -----
 

package/lib/client.js

@@ -591,12 +591,12 @@ window.__ModuleLoader__.load({
 			const rendered = JSON.stringify(value) ?? String(value);
 			throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
 		}
-		/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
+		/** Whether a realm-owned intrinsic prototype has a native constructor matching this engine's representation. */
 		function hasIntrinsicConstructor(prototype, name) {
 			const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
 			if (typeof constructor !== "function") return false;
 			try {
-				return constructor.name === name && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`;
+				return constructor.name === name && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === Function.prototype.toString.call(name === "Array" ? Array : Object);
 			} catch {
 				return false;
 			}
@@ -3349,6 +3349,7 @@ window.__ModuleLoader__.load({
 				if (!result.ok) throw new SessionForkError(result.error, opts.sessionId);
 				this.projectList();
 				const childId = result.value.sessionId;
+				opts.onCreated?.(childId);
 				if (sourceTitle !== void 0) {
 					const renamed = await this.manager.rename(childId, increasedForkTitle(sourceTitle));
 					if (!renamed.ok) throw new Error(`fork child rename failed: ${renamed.error.code}: ${renamed.error.message}`);

package/lib/index.js

@@ -7,6 +7,7 @@ import { SessionQueryError } from "@deepseek-ai/dsh-session-query";
 import { Remote, RemoteError, TypertRemoteService, remoteErrorOf } from "@deepseek-ai/dsh-typert-protocol";
 import { mkdir } from "node:fs/promises";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { randomUUID } from "node:crypto";
 import { brandString } from "@deepseek-ai/dsh-brand";
 import { AttachmentError } from "@deepseek-ai/dsh-attachment";
@@ -488,6 +489,103 @@ function agentModelSelection(selection) {
 	};
 }
 //#endregion
+//#region lib/types/catalog.js
+/** Shared projection of the live LLM registry into the browser model catalog. */
+/**
+* Build the browser model catalog without requiring a Session.
+* @param ctx - Host context carrying the live LLM registry.
+* @param defaultSelection - deployment default used before a Session selects a model.
+* @returns successful non-empty provider groups and isolated provider failures.
+*/
+async function buildModelCatalog(ctx, defaultSelection = ctx.agentDefaultModel.currentSelection()) {
+	const providers = ctx.llm.listProviders();
+	const catalog = await Promise.all(providers.map(async (provider) => {
+		try {
+			const models = await ctx.llm.listModels(provider.id);
+			const entries = await Promise.all(models.map(async (model) => {
+				const resolved = await ctx.llm.resolveModelInfo(provider.id, model.id);
+				const reasoning = resolved.reasoning === void 0 ? void 0 : {
+					efforts: resolved.reasoning.efforts.map((effort) => ({
+						id: effort.id,
+						name: effort.name,
+						...effort.description === void 0 ? {} : { description: effort.description }
+					})),
+					...resolved.reasoning.defaultEffort === void 0 ? {} : { defaultEffort: resolved.reasoning.defaultEffort }
+				};
+				return {
+					id: model.id,
+					name: model.name,
+					...model.description === void 0 ? {} : { description: model.description },
+					...reasoning === void 0 ? {} : { reasoning }
+				};
+			}));
+			return {
+				kind: "group",
+				group: {
+					id: provider.id,
+					name: provider.name,
+					models: entries
+				}
+			};
+		} catch (error) {
+			return {
+				kind: "failure",
+				failure: {
+					id: provider.id,
+					name: provider.name,
+					message: error instanceof Error ? error.message : String(error)
+				}
+			};
+		}
+	}));
+	const groups = catalog.flatMap((item) => item.kind === "group" ? [item.group] : []).filter((group) => group.models.length > 0);
+	return {
+		default: { ...defaultSelection },
+		routableProviders: groups.map((group) => group.id),
+		groups,
+		failures: catalog.flatMap((item) => item.kind === "failure" ? [item.failure] : [])
+	};
+}
+/**
+* Check a GUI selection against the current available provider catalog.
+* @param ctx - Host LLM registry.
+* @param selection - stored or explicitly requested selection.
+* @returns whether the exact model is currently advertised as available.
+*/
+async function modelAvailable(ctx, selection) {
+	if (!ctx.llm.listProviders().some((provider) => provider.id === selection.provider)) return false;
+	let models;
+	try {
+		models = await ctx.llm.listModels(selection.provider);
+	} catch (error) {
+		throw new RemoteError("session/model-unavailable", error instanceof Error ? error.message : String(error), {
+			provider: selection.provider,
+			model: selection.model
+		});
+	}
+	return models.some((model) => model.id === selection.model);
+}
+/**
+* Check configured provider API-key references independently of model availability.
+* @param ctx - Host registry, settings, and credential services.
+* @returns whether any API-key provider has a configured credential.
+*/
+async function hasProviderApiKey(ctx) {
+	const settings = ctx.get("settings");
+	const credentials = ctx.get("credentials");
+	if (settings === void 0 || credentials === void 0) throw new RemoteError("session/provider-credentials-unavailable", "provider credentials are unavailable", {});
+	const namespaces = settings.describe({ redactSecrets: true });
+	for (const provider of ctx.llm.listConfigurableProviders()) {
+		if (provider.provider === "deepseek-account") continue;
+		let profile = namespaces.find((namespace) => namespace.ns === provider.settingsNs)?.value;
+		for (const key of provider.settingsPath) profile = typeof profile === "object" && profile !== null ? Reflect.get(profile, key) : void 0;
+		if (typeof profile !== "object" || profile === null) continue;
+		const ref = Reflect.get(profile, "apiKeyEnv");
+		if (typeof ref === "string" && ref.length > 0 && (await credentials.describe(credentialRef(ref))).configured) return true;
+	}
+	return false;
+}
+//#endregion
 //#region lib/types/commands.js
 /** Session commands whose activation policy is explicit at each Remote method. */
 var __addDisposableResource$3 = function(env, value, async) {
@@ -615,14 +713,15 @@ var SessionCommandController = class {
 		};
 	}
 	/**
-	* Validate and install one Session-local model selection.
+	* Validate and install one Session-local model selection; save the default in the background.
 	* @param request - Session identity and requested model selection.
-	* @returns the normalized selection installed for the Session.
+	* @returns the normalized selection installed for the Session, without waiting for default persistence.
 	*/
 	async selectModel(request) {
 		const agent = await this.resolveAgent(request.sessionId);
 		return this.agents.serializeImageAdmission(agent, async () => {
 			try {
+				await this.requireModel(request);
 				const resolved = await this.ctx.llm.resolveCallConfig({
 					provider: request.provider,
 					model: request.model,
@@ -634,11 +733,9 @@ var SessionCommandController = class {
 					...resolved.reasoningEffort === void 0 ? {} : { reasoningEffort: resolved.reasoningEffort }
 				};
 				this.agents.selectForNextRequest(agent, selected);
-				try {
-					await this.ctx.agentDefaultModel.saveSelection(selected);
-				} catch (error) {
+				this.ctx.agentDefaultModel.saveSelection(selected).catch((error) => {
 					this.ctx.logger.warn(`session-controller: model selection changed for the Session but the default was not saved: ${String(error)}`);
-				}
+				});
 				return { selected: { ...selected } };
 			} catch (error) {
 				if (remoteErrorOf(error) !== void 0) throw error;
@@ -756,11 +853,6 @@ var SessionCommandController = class {
 		if (request.clientTimeZone !== void 0 && clientTimeZone === void 0) throw new RemoteError("session/invalid-time-zone", "clientTimeZone must be UTC or a valid IANA Area/Location name", { value: request.clientTimeZone });
 		const agent = await this.resolveAgent(request.sessionId);
 		if (hasPromptRequest(agent, request.requestId)) return { accepted: true };
-		const selection = this.agents.selectionFor(agent).current;
-		if (!routeServed(this.ctx, selection.provider)) throw new RemoteError("session/model-unavailable", `no adapter serves provider "${selection.provider}"; select a model for this session`, {
-			provider: selection.provider,
-			model: selection.model
-		});
 		const source = {
 			kind: "user",
 			rpcId: request.requestId,
@@ -805,6 +897,12 @@ var SessionCommandController = class {
 		};
 		return hasImage ? this.agents.serializeImageAdmission(agent, admit) : admit();
 	}
+	async requireModel(selection) {
+		if (!await modelAvailable(this.ctx, selection)) throw new RemoteError("session/model-unavailable", "Select an available model before sending a message.", {
+			provider: selection.provider,
+			model: selection.model
+		});
+	}
 	/**
 	* Read one durable image after proving the Session log references it.
 	* @param request - Session and attachment identities used for authorization.
@@ -1026,9 +1124,6 @@ function referencedImage(events, attachmentId) {
 		if (found !== void 0) return found;
 	}
 }
-function routeServed(ctx, provider) {
-	return ctx.llm.listProviders().some((entry) => entry.id === provider);
-}
 //#endregion
 //#region lib/types/control.js
 /** Live Session projection state with reconnect baselines. */
@@ -1953,63 +2048,6 @@ function listFields(header) {
 	};
 }
 //#endregion
-//#region lib/types/catalog.js
-/** Shared projection of the live LLM registry into the browser model catalog. */
-/**
-* Build the browser model catalog without requiring a Session.
-* @param ctx - Host context carrying the live LLM registry.
-* @param defaultSelection - deployment default used before a Session selects a model.
-* @returns successful non-empty provider groups and isolated provider failures.
-*/
-async function buildModelCatalog(ctx, defaultSelection = ctx.agentDefaultModel.currentSelection()) {
-	const providers = ctx.llm.listProviders();
-	const catalog = await Promise.all(providers.map(async (provider) => {
-		try {
-			const models = await ctx.llm.listModels(provider.id);
-			const entries = await Promise.all(models.map(async (model) => {
-				const resolved = await ctx.llm.resolveModelInfo(provider.id, model.id);
-				const reasoning = resolved.reasoning === void 0 ? void 0 : {
-					efforts: resolved.reasoning.efforts.map((effort) => ({
-						id: effort.id,
-						name: effort.name,
-						...effort.description === void 0 ? {} : { description: effort.description }
-					})),
-					...resolved.reasoning.defaultEffort === void 0 ? {} : { defaultEffort: resolved.reasoning.defaultEffort }
-				};
-				return {
-					id: model.id,
-					name: model.name,
-					...model.description === void 0 ? {} : { description: model.description },
-					...reasoning === void 0 ? {} : { reasoning }
-				};
-			}));
-			return {
-				kind: "group",
-				group: {
-					id: provider.id,
-					name: provider.name,
-					models: entries
-				}
-			};
-		} catch (error) {
-			return {
-				kind: "failure",
-				failure: {
-					id: provider.id,
-					name: provider.name,
-					message: error instanceof Error ? error.message : String(error)
-				}
-			};
-		}
-	}));
-	return {
-		default: { ...defaultSelection },
-		routableProviders: providers.map((provider) => provider.id),
-		groups: catalog.flatMap((item) => item.kind === "group" ? [item.group] : []).filter((group) => group.models.length > 0),
-		failures: catalog.flatMap((item) => item.kind === "failure" ? [item.failure] : [])
-	};
-}
-//#endregion
 //#region lib/types/model-selection-projection.js
 /** Durable model-selection intent and request-use projection. */
 const modelSelectionSchema = z$1.object({
@@ -2522,6 +2560,7 @@ let SessionController = (() => {
 	let _search_decorators;
 	let _create_decorators;
 	let _selectModel_decorators;
+	let _initializeDefaultModel_decorators;
 	let _modelCatalog_decorators;
 	let _canOpenWorkspacePath_decorators;
 	let _openWorkspacePath_decorators;
@@ -2543,6 +2582,7 @@ let SessionController = (() => {
 			_search_decorators = [Remote("search")];
 			_create_decorators = [Remote("create")];
 			_selectModel_decorators = [Remote("selectModel")];
+			_initializeDefaultModel_decorators = [Remote];
 			_modelCatalog_decorators = [Remote("modelCatalog")];
 			_canOpenWorkspacePath_decorators = [Remote];
 			_openWorkspacePath_decorators = [Remote("openWorkspacePath")];
@@ -2601,6 +2641,17 @@ let SessionController = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _initializeDefaultModel_decorators, {
+				kind: "method",
+				name: "initializeDefaultModel",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "initializeDefaultModel" in obj,
+					get: (obj) => obj.initializeDefaultModel
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _modelCatalog_decorators, {
 				kind: "method",
 				name: "modelCatalog",
@@ -2921,14 +2972,30 @@ let SessionController = (() => {
 			return this.commands.create(request);
 		}
 		/**
-		* Select one Session-local model after explicitly resuming the Session.
+		* Select one Session-local model after explicitly resuming the Session; save the default in the background.
 		* @param request - Session identity and requested model selection.
-		* @returns the normalized selection installed for the Session.
+		* @returns the normalized selection installed for the Session, without waiting for default persistence.
 		*/
 		selectModel(request) {
 			return this.commands.selectModel(request);
 		}
 		/**
+		* Select the first available account model after login when no provider API key is configured.
+		* @returns after saving the first available model or retaining the existing default.
+		*/
+		async initializeDefaultModel() {
+			const provider = "deepseek-account";
+			if (await hasProviderApiKey(this.ctx)) return;
+			const model = (await buildModelCatalog(this.ctx)).groups.find((group) => group.id === provider)?.models[0];
+			if (model === void 0) throw new RemoteError("session/provider-models-unavailable", `provider "${provider}" has no available models`, { provider });
+			const selection = {
+				provider,
+				model: model.id,
+				...model.reasoning?.defaultEffort === void 0 ? {} : { reasoningEffort: ReasoningEffortId(model.reasoning.defaultEffort) }
+			};
+			await this.ctx.agentDefaultModel.saveSelection(selection);
+		}
+		/**
 		* Describe every currently routable model for Host-generation selectors.
 		* @returns provider-grouped models, the deployment default, and isolated provider failures.
 		*/