@deepseek-ai/dsh-session-persistence-jsonl 0.1.7-alpha.2 → 0.1.7-rc.2

package/README.i18n.yaml

@@ -1,6 +1,70 @@
-# 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/session/session-persistence-jsonl/README.md
-README.md: 5846404961caaef7a91fb4dda562655d15fd2be9
-README.zh.md: b7dd646e57b75fe47f3683d2b230dace628f8eee
+/:
+  en: cc97ed79d262bf09
+  zh: 90a141669dc844f3
+/deepseek-ai-dsh-session-persistence-jsonl:
+  en: 719697c849e36229
+  zh: 466ab1b89c10020c
+/deepseek-ai-dsh-session-persistence-jsonl/summary:
+  en: 4821bd83813408c7
+  zh: 2e5c721a19f549e7
+/deepseek-ai-dsh-session-persistence-jsonl/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-session-persistence-jsonl/use-this-package:
+  en: d6112142a705ec43
+  zh: f0914d9e37216f97
+/deepseek-ai-dsh-session-persistence-jsonl/use-this-package/when-to-choose-it:
+  en: 37c10302bbbde268
+  zh: 3d5c027bac868efd
+/deepseek-ai-dsh-session-persistence-jsonl/use-this-package/minimal-configuration:
+  en: 22e8c3b2da45edff
+  zh: d9effd892b514520
+/deepseek-ai-dsh-session-persistence-jsonl/use-this-package/on-disk-layout:
+  en: e20cf32540d7c785
+  zh: 67e182529e9211ca
+/deepseek-ai-dsh-session-persistence-jsonl/use-this-package/durability-and-crash-semantics:
+  en: 1eaa87736cac029b
+  zh: 26224e8889786d69
+/deepseek-ai-dsh-session-persistence-jsonl/use-this-package/reading-the-logs:
+  en: c06983c4a73bebe1
+  zh: 7319f8f44223685f
+/deepseek-ai-dsh-session-persistence-jsonl/understand-the-implementation:
+  en: a35407bb25671e7e
+  zh: 6a00f9510c85adcb
+/deepseek-ai-dsh-session-persistence-jsonl/understand-the-implementation/design-concept:
+  en: b69d4565a11b6f02
+  zh: c8309690fc931f8d
+/deepseek-ai-dsh-session-persistence-jsonl/understand-the-implementation/physical-encoding:
+  en: 011d56563b81acd9
+  zh: 69122dbade603fe9
+/deepseek-ai-dsh-session-persistence-jsonl/understand-the-implementation/source-map:
+  en: 3bdb0f1dd4d69fba
+  zh: 8198d655d73d42e3
+/deepseek-ai-dsh-session-persistence-jsonl/further-exploration:
+  en: 827c04be7cd01514
+  zh: 5e87603b3463db38
+/deepseek-ai-dsh-session-persistence-jsonl/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-session-persistence-jsonl/model-experience/resumed-conversation-history:
+  en: 062875aab7f3f138
+  zh: c7285918227e6f5c
+/deepseek-ai-dsh-session-persistence-jsonl/model-experience/resumed-conversation-history/what-the-model-sees:
+  en: 2a3b5c6e3860eef6
+  zh: 82afe0f0359581b6
+/deepseek-ai-dsh-session-persistence-jsonl/model-experience/resumed-conversation-history/token-effect:
+  en: 8fb2f7cdba1ff320
+  zh: e130ec2a92a53a5c
+/deepseek-ai-dsh-session-persistence-jsonl/model-experience/resumed-conversation-history/kv-cache-effect:
+  en: 53ce4da7ce68d21c
+  zh: 10f40bc354100f77
+/deepseek-ai-dsh-session-persistence-jsonl/known-limitations-and-deferred-work:
+  en: e6343e8ad3f6fb71
+  zh: fe632c9711e7921b
+/deepseek-ai-dsh-session-persistence-jsonl/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/lib/worker.cjs

@@ -4136,6 +4136,89 @@ function projectImagesForTextModel(messages) {
 		};
 	});
 }
+function withoutDeveloperMessages(messages) {
+	const retained = messages.filter((message) => message.role !== "developer");
+	return retained.length === messages.length ? messages : retained;
+}
+function toolDeclarations(tools, mode, history) {
+	const declarations = new Map(history.tools.map((tool) => [tool.name, tool]));
+	for (const update of history.updates) for (const tool of update.additions) if (!declarations.has(tool.name)) declarations.set(tool.name, {
+		...tool,
+		deferLoading: true
+	});
+	switch (mode) {
+		case "in-history": return declarations;
+		case "addition-only": {
+			const activeNames = new Set(tools?.map((tool) => tool.name));
+			for (const name of declarations.keys()) if (!activeNames.has(name)) declarations.delete(name);
+			return declarations;
+		}
+		/* v8 ignore next 2 -- closed-union exhaustiveness guard */
+		default: return assertNever(mode);
+	}
+}
+/**
+* Construct provider declarations from session-folded history without changing logged active tools.
+* Unsupported routes and incomplete history use current declarations without developer updates.
+* Explicitly deferred baseline tools become available only after their first retained addition.
+* @param messages - complete request inputs, or the prefix selected for an auxiliary call.
+* @param tools - currently active tool schemas.
+* @param toolUpdate - the resolved route's update mode.
+* @param history - immutable state folded from committed headers and developer messages.
+* @returns provider declarations and the corresponding filtered history.
+*/
+function projectToolUpdates(messages, tools, toolUpdate, history) {
+	if (toolUpdate === void 0) {
+		let immediateTools = tools;
+		if (tools?.some((tool) => tool.deferLoading === true)) immediateTools = tools.map(({ deferLoading: _loading, ...tool }) => tool);
+		return {
+			messages: withoutDeveloperMessages(messages),
+			tools: immediateTools
+		};
+	}
+	if (history === void 0) return {
+		messages: withoutDeveloperMessages(messages),
+		tools
+	};
+	const messageIds = new Set(messages.flatMap((message) => message.role === "developer" ? [message.id] : []));
+	if (history.updates.some((update) => !messageIds.has(update.messageId))) return {
+		messages: withoutDeveloperMessages(messages),
+		tools
+	};
+	const declarations = toolDeclarations(tools, toolUpdate, history);
+	const updateIds = new Set(history.updates.map((update) => update.messageId));
+	const offered = new Set(history.tools.filter((tool) => !tool.deferLoading).map((tool) => tool.name));
+	const projectedMessages = [];
+	for (const message of messages) {
+		if (message.role !== "developer") {
+			projectedMessages.push(message);
+			continue;
+		}
+		if (!updateIds.has(message.id)) continue;
+		const content = message.content.filter((block) => {
+			switch (block.type) {
+				case "tool-addition":
+					if (!declarations.has(block.toolName) || offered.has(block.toolName)) return false;
+					offered.add(block.toolName);
+					return true;
+				case "tool-removal":
+					if (toolUpdate !== "in-history") return false;
+					return offered.delete(block.toolName);
+				default: return true;
+			}
+		});
+		if (content.length === 0) continue;
+		if (content.length === message.content.length) projectedMessages.push(message);
+		else projectedMessages.push({
+			...message,
+			content
+		});
+	}
+	return {
+		messages: projectedMessages.length === messages.length && projectedMessages.every((message, index) => message === messages[index]) ? messages : projectedMessages,
+		tools: [...declarations.values()]
+	};
+}
 //#endregion
 //#region ../../llm/llm/src/attribution.ts
 /**
@@ -4995,7 +5078,8 @@ var LlmError = class extends HarnessError {
 		}
 		/**
 		* Discover models advertised by one registered provider. Catalog membership
-		* is advisory and never changes routing or request validation.
+		* does not constrain core routing. Catalog-driven entry points may restrict
+		* selection and submission to the advertised models.
 		* @param provider - registered provider route to inspect.
 		* @returns detached model metadata in adapter-preferred order.
 		*/
@@ -5040,6 +5124,8 @@ var LlmError = class extends HarnessError {
 			const inputModalities = this.detachedModalities(resolved.inputModalities);
 			const systemPromptUpdate = resolved.systemPromptUpdate;
 			if (systemPromptUpdate !== void 0 && systemPromptUpdate !== "in-history") throw new LlmError(`adapter returned invalid system prompt update mode for provider "${provider}" model "${model}"`, "INVALID_MODEL_INFO");
+			const toolUpdate = resolved.toolUpdate;
+			if (toolUpdate !== void 0 && toolUpdate !== "in-history" && toolUpdate !== "addition-only") throw new LlmError(`adapter returned invalid tool update mode for provider "${provider}" model "${model}"`, "INVALID_MODEL_INFO");
 			const defaultMaxTokens = resolved.defaultMaxTokens;
 			if (defaultMaxTokens !== void 0 && (!Number.isSafeInteger(defaultMaxTokens) || defaultMaxTokens <= 0)) throw new LlmError(`adapter returned invalid default maxTokens for provider "${provider}" model "${model}"`, "INVALID_MODEL_MAX_TOKENS");
 			const info = {
@@ -5050,7 +5136,8 @@ var LlmError = class extends HarnessError {
 				...inputModalities === void 0 ? {} : { inputModalities },
 				...context === void 0 ? {} : { context: { contextWindow: context.contextWindow } },
 				...defaultMaxTokens === void 0 ? {} : { defaultMaxTokens },
-				...resolved.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: resolved.systemPromptUpdate }
+				...resolved.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: resolved.systemPromptUpdate },
+				...resolved.toolUpdate === void 0 ? {} : { toolUpdate: resolved.toolUpdate }
 			};
 			const reasoning = resolved.reasoning;
 			if (reasoning === void 0) return info;
@@ -5145,6 +5232,7 @@ var LlmError = class extends HarnessError {
 				...context === void 0 ? {} : { context },
 				...modelInfo.inputModalities === void 0 ? {} : { inputModalities: Object.freeze([...modelInfo.inputModalities]) },
 				...modelInfo.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: modelInfo.systemPromptUpdate },
+				...modelInfo.toolUpdate === void 0 ? {} : { toolUpdate: modelInfo.toolUpdate },
 				stream: (options) => {
 					if (dispatched) throw new LlmError("a prepared LLM call can only be dispatched once", "INVALID_PREPARED_CALL");
 					if (!callConfigEquals(options, resolvedConfig)) throw new LlmError("prepared LLM call config changed before adapter dispatch", "INVALID_PREPARED_CALL");
@@ -5234,13 +5322,17 @@ var LlmError = class extends HarnessError {
 				let projectedMessages = resolvedOptions.messages;
 				if (projectedMessages.some((message) => contentHasFile(message.content))) projectedMessages = projectFilesToText(projectedMessages, (ref) => this.fileReadPath(ref));
 				if (modelInfo.inputModalities !== void 0 && !modelInfo.inputModalities.includes("image") && projectedMessages.some((message) => contentHasImage(message.content))) projectedMessages = projectImagesForTextModel(projectedMessages);
-				const projectedOptions = projectedMessages === resolvedOptions.messages ? resolvedOptions : Object.isFrozen(resolvedOptions) ? deepFreeze({
-					...resolvedOptions,
-					messages: projectedMessages
-				}) : {
-					...resolvedOptions,
-					messages: projectedMessages
-				};
+				const projectedTools = projectToolUpdates(projectedMessages, resolvedOptions.tools, modelInfo.toolUpdate, resolvedOptions.toolHistory);
+				projectedMessages = projectedTools.messages;
+				let projectedOptions = resolvedOptions;
+				if (projectedMessages !== resolvedOptions.messages || projectedTools.tools !== resolvedOptions.tools) {
+					projectedOptions = {
+						...resolvedOptions,
+						messages: projectedMessages,
+						...projectedTools.tools === void 0 ? {} : { tools: projectedTools.tools }
+					};
+					if (Object.isFrozen(resolvedOptions)) deepFreeze(projectedOptions);
+				}
 				iterator = dispatch(this.forAdapter(projectedOptions, adapter))[Symbol.asyncIterator]();
 			} catch (error) {
 				yield adapterFailureChunk(error, options.signal);
@@ -5339,6 +5431,80 @@ function foldRequestHeader(events, from) {
 	return state;
 }
 //#endregion
+//#region ../../core/session/src/tool-history.ts
+/** Folds committed headers and developer messages independently of model capability. */
+var ToolHistoryProjection = class {
+	/** Historical declarations indexed by the header sequence referenced by additions. */
+	headers = /* @__PURE__ */ new Map();
+	/** Definitions retained in the current declaration series, including removed tools. */
+	declared = /* @__PURE__ */ new Map();
+	/** Active definitions from the latest request header. */
+	active = [];
+	/** Active names reconstructed from the baseline and recorded updates. */
+	available = /* @__PURE__ */ new Set();
+	/** Header that starts the current declaration series; absent before the first header. */
+	baselineSeq;
+	/** Immutable request snapshot of the current baseline and resolved updates. */
+	history = deepFreeze({
+		tools: [],
+		updates: []
+	});
+	/**
+	* Consume the next committed event in log order.
+	* @param event - a session event, including inherited events during restoration.
+	*/
+	apply(event) {
+		if (event.type === "request/header") {
+			const tools = event.data.header.tools ?? [];
+			this.headers.set(event.seq, tools);
+			const redeclared = tools.some((tool) => {
+				const before = this.declared.get(tool.name);
+				return before !== void 0 && JSON.stringify(before) !== JSON.stringify(tool);
+			});
+			if (this.baselineSeq === void 0 || event.data.reason === "series" || event.data.startsSeries || redeclared) {
+				this.baselineSeq = event.seq;
+				this.declared = new Map(tools.map((tool) => [tool.name, tool]));
+				this.history = deepFreeze({
+					tools,
+					updates: []
+				});
+				this.available = new Set(tools.map((tool) => tool.name));
+			}
+			this.active = tools;
+		} else if (event.type === "developer/message") {
+			const { message, headerSeq } = event.data;
+			const definitions = headerSeq === void 0 ? [] : this.headers.get(headerSeq);
+			const additions = message.content.flatMap((block) => {
+				if (block.type !== "tool-addition") return [];
+				const tool = definitions?.find((tool) => tool.name === block.toolName);
+				if (tool === void 0) throw new Error(`tool history: missing definition for ${block.toolName}`);
+				return [tool];
+			});
+			for (const tool of additions) this.declared.set(tool.name, tool);
+			for (const block of message.content) if (block.type === "tool-addition") this.available.add(block.toolName);
+			else if (block.type === "tool-removal") this.available.delete(block.toolName);
+			this.history = deepFreeze({
+				tools: this.history.tools,
+				updates: [...this.history.updates, {
+					messageId: message.id,
+					additions
+				}]
+			});
+		}
+	}
+	/**
+	* Read an immutable snapshot; subsequent events do not mutate it.
+	* @returns initial declarations and historically resolved additions for the current series.
+	*/
+	snapshot() {
+		if (this.active.length !== this.available.size || this.active.some((tool) => !this.available.has(tool.name))) return deepFreeze({
+			tools: this.active,
+			updates: []
+		});
+		return this.history;
+	}
+};
+//#endregion
 //#region ../../core/session/src/index.ts
 /** Validate and freeze one detached creation header in place. */
 function validateSessionHeader(id, input) {
@@ -5812,6 +5978,20 @@ var Session = class Session {
 		}
 		return this.contextFold;
 	}
+	/** Cached historical tool definitions and updates for request projection. */
+	toolHistoryProjection = new ToolHistoryProjection();
+	/** Index of the next committed event not yet consumed by the tool-history fold. */
+	toolHistorySeq = 0;
+	/**
+	* Fold unseen committed events into capability-independent tool history.
+	* Initial access reconstructs inherited history; later reads consume only new events.
+	* @returns an immutable snapshot for LLM request projection, including historical addition definitions.
+	*/
+	toolHistory() {
+		for (const event of this.log.slice(this.toolHistorySeq)) this.toolHistoryProjection.apply(event);
+		this.toolHistorySeq = this.log.length;
+		return this.toolHistoryProjection.snapshot();
+	}
 	/** The derived-message cache: frozen projections, extended per unseen node. */
 	derived = [];
 	/** Surface position (nodes projected) the cache has reached. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-persistence-jsonl",
   "description": "JSONL durable session persistence backend for the DeepSeek Harness",
-  "version": "0.1.7-alpha.2",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -28,23 +28,23 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.7-rc.2",
     "@deepseek-ai/cordis": "~4.0.4"
   },
   "dependencies": {
     "koffi": "^3.1.0",
-    "@deepseek-ai/dsh-session-format": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-format-catalog": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-format-v3-to-v4": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session-format": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-format-catalog": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-format-v3-to-v4": "0.1.7-rc.2",
     "@deepseek-ai/node-addon-system": "~0.1.2",
     "@deepseek-ai/schemastery": "~3.18.4",
-    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-format-v0-to-v1": "0.1.7-rc.2",
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-session-format-v0-to-v1": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-session-persistence": "0.1.7-rc.2"
   }
 }