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

package/README.i18n.yaml

@@ -1,6 +1,103 @@
-# 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/core/session/README.md
-README.md: 06c4f1806995c2fdff78515f88a60c6e449e3a26
-README.zh.md: c52eee96af19bcd6f5a76f950026d2c191002732
+/:
+  en: 54dedea99ec5492c
+  zh: 23b29cb5d738dadb
+/deepseek-ai-dsh-session:
+  en: c019c0e8c7f9cba0
+  zh: 151e150825fda310
+/deepseek-ai-dsh-session/summary:
+  en: 311239677afd230a
+  zh: f2c575945baaa2a2
+/deepseek-ai-dsh-session/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-session/use-this-package:
+  en: 0882d4056c45aa75
+  zh: fcee78e9845b78b3
+/deepseek-ai-dsh-session/use-this-package/create-and-inspect-sessions:
+  en: f80dab583fa3939d
+  zh: 5a9a79ebcef86119
+/deepseek-ai-dsh-session/use-this-package/append-and-derive:
+  en: aa5f1951ecf3ac0c
+  zh: 62a599ace8f2bf15
+/deepseek-ai-dsh-session/use-this-package/read-the-log:
+  en: 2b29cfeac7a2baa8
+  zh: b535b04dcbc29d3d
+/deepseek-ai-dsh-session/use-this-package/fork-a-session:
+  en: 1c40d17a786059d3
+  zh: 81320ce118977c65
+/deepseek-ai-dsh-session/use-this-package/flush-durable-state:
+  en: 70a7673145c851ad
+  zh: 0dd1667d9518993d
+/deepseek-ai-dsh-session/understand-the-implementation:
+  en: ce7e776e9d516bdb
+  zh: 59d2751743db7795
+/deepseek-ai-dsh-session/understand-the-implementation/design-concept:
+  en: dabbe938e288c55a
+  zh: 31c7ac2bee2a2846
+/deepseek-ai-dsh-session/understand-the-implementation/request-headers:
+  en: bbfb53c50100ab13
+  zh: 303a8ee47f4f656a
+/deepseek-ai-dsh-session/understand-the-implementation/source-map:
+  en: e87f7ef34effbad2
+  zh: 774a98d23611f5f5
+/deepseek-ai-dsh-session/understand-the-implementation/append-validation:
+  en: 5c09583bc8e1ffc6
+  zh: 3b25552de2d1f9b6
+/deepseek-ai-dsh-session/understand-the-implementation/derived-history:
+  en: 0cc7a06f76bd7eca
+  zh: 1db25185b15cad23
+/deepseek-ai-dsh-session/understand-the-implementation/the-request-header:
+  en: 1349f47bea4dab00
+  zh: 20cc03f2c87ec492
+/deepseek-ai-dsh-session/further-exploration:
+  en: e23d6c8b31295044
+  zh: 5105ac9ce8c5d90d
+/deepseek-ai-dsh-session/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-session/model-experience/derived-message-history:
+  en: 3005f28ded3b28ea
+  zh: daaddc6df470b396
+/deepseek-ai-dsh-session/model-experience/derived-message-history/what-the-model-sees:
+  en: 30ccd8296306b132
+  zh: 19efa5a43745585c
+/deepseek-ai-dsh-session/model-experience/derived-message-history/token-effect:
+  en: 05e088199dac7f98
+  zh: 35868b5fb768e240
+/deepseek-ai-dsh-session/model-experience/derived-message-history/kv-cache-effect:
+  en: 6c8079c7de029ed4
+  zh: 634d6f93ce6373c4
+/deepseek-ai-dsh-session/model-experience/crash-repair-and-fork-results:
+  en: 4aa585f38846e017
+  zh: ef28f54125a9021d
+/deepseek-ai-dsh-session/model-experience/crash-repair-and-fork-results/what-the-model-sees:
+  en: b2ae41b23519cdc6
+  zh: 05ce1c9a8b8c3283
+/deepseek-ai-dsh-session/model-experience/crash-repair-and-fork-results/token-effect:
+  en: ac63e0f30175f72d
+  zh: 20f63deeffa249f2
+/deepseek-ai-dsh-session/model-experience/crash-repair-and-fork-results/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: b84ef7f75f2e25d0
+/deepseek-ai-dsh-session/model-experience/logged-request-header:
+  en: 5397f067293a55cd
+  zh: 1dcc30d0c214f175
+/deepseek-ai-dsh-session/model-experience/logged-request-header/what-the-model-sees:
+  en: cfb4fd90e1982948
+  zh: fefc01118b2a5c07
+/deepseek-ai-dsh-session/model-experience/logged-request-header/token-effect:
+  en: 310b8f36a86443e5
+  zh: 906c4da8d03c5966
+/deepseek-ai-dsh-session/model-experience/logged-request-header/kv-cache-effect:
+  en: 5eb30cfb410d52c0
+  zh: da56365b8ab896da
+/deepseek-ai-dsh-session/known-limitations-and-deferred-work:
+  en: daaf56dda2bcaff1
+  zh: 7d24de2deb1c5dc5
+/deepseek-ai-dsh-session/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -167,7 +167,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-The session reconstructs the tool schemas and call config that the loop actually sent; the system prompt is part of `deriveMessages()` as surface node 0 and, after an in-history update, as the latest system node. Header events add no message to history and hold no copy of the prompt.
+The session reconstructs active tool schemas and call config from request headers; provider-specific deferred and retained declarations are derived at dispatch. `toolHistory()` caches a stateful fold over committed headers and developer messages, consuming only unseen events on subsequent reads. It resolves additions through their historical `headerSeq`, returns immutable snapshots, and restarts declarations on an explicit request series or a changed retained definition. Restoring a retained name with an unchanged definition continues the series; the recorded addition re-offers it. Both loop requests and compaction calls use this state. Headers lacking matching update records use complete active declarations. Same-name schema changes are allowed and invalidate prefix reuse even on `in-history` routes; registration-time rejection against historical tools is deferred ([rationale](../../../.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.md)). The system prompt remains part of `deriveMessages()`; header events add no message or prompt copy.
 
 #### Token effect
 

package/README.zh.md

@@ -169,7 +169,7 @@ Fork 生成的结果只描述继承记录：父会话可能已经在所选事件
 
 #### 模型看到什么
 
-会话会重建循环实际发送的工具 schema 与调用配置；系统提示词作为 surface 第 0 号节点、并在历史内更新之后作为最新的系统节点，属于 `deriveMessages()` 的一部分。请求头事件不向历史加入任何消息，也不持有提示词的副本。
+会话从请求头重建有效工具模式和调用配置；提供方专用的延迟声明与保留声明在分发时派生。`toolHistory()` 缓存对已提交请求头和 developer 消息的有状态归约，后续读取仅处理新增事件。它通过历史 `headerSeq` 解析添加定义，返回不可变快照，并在显式新请求序列或保留定义发生变化时重新建立声明。以未变化的定义恢复保留名称时序列继续，由记录的添加重新提供该工具。循环请求和压缩调用均使用此状态。 请求头缺少对应更新记录时，使用完整有效声明。 允许同名工具的 schema 变化，即使在 `in-history` 路由上也会使前缀复用失效；注册时对照历史工具进行拒绝检查留待后续实现（[原因](../../../.agents/notes/implemented/architecture/2026-09-20-dynamic-tool-updates.zh.md)）。系统提示词仍属于 `deriveMessages()`；请求头事件不添加消息或提示词副本。
 
 #### Token 影响
 

package/lib/index.js

@@ -637,6 +637,81 @@ function foldRequestHeader(events, from) {
 	return state;
 }
 //#endregion
+//#region lib/types/tool-history.js
+/** Stateful reconstruction of historical tool definitions for request projection. */
+/** 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 lib/types/repair.js
 /**
 * Synthetic closer events that balance a session log whose tail turn is open.
@@ -1398,6 +1473,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/lib/types/index.d.ts

@@ -12,6 +12,7 @@ import { SessionLogOffset, SessionSeq } from './types.ts';
 import type { TypertLookup } from '@deepseek-ai/dsh-typert-protocol';
 import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SessionSeedEventState, SurfaceIntent, SurfaceEventType } from './types.ts';
 import type { SessionSurface, SessionMessageProjection } from './surface.ts';
+import type { ToolHistory } from '@deepseek-ai/dsh-llm';
 export { buildForkSeed } from './fork.ts';
 export * from './types.ts';
 export { SessionPreparation } from './preparation.ts';
@@ -265,6 +266,16 @@ export declare class Session {
      * @returns the latest immutable route metadata.
      */
     requestContext(): RequestContext | undefined;
+    /** Cached historical tool definitions and updates for request projection. */
+    private readonly toolHistoryProjection;
+    /** Index of the next committed event not yet consumed by the tool-history fold. */
+    private toolHistorySeq;
+    /**
+     * 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(): ToolHistory;
     /** The derived-message cache: frozen projections, extended per unseen node. */
     private derived;
     /** Surface position (nodes projected) the cache has reached. */

package/lib/types/index.js

@@ -13,6 +13,7 @@ import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope';
 import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from "./types.js";
 import { SurfaceManager, validateSessionEventData, validateSurfaceMetadata } from "./surface.js";
 import { foldRequestHeader } from "./request-header.js";
+import { ToolHistoryProjection } from "./tool-history.js";
 import { buildForkSeed } from "./fork.js";
 export { buildForkSeed } from "./fork.js";
 export * from "./types.js";
@@ -654,6 +655,21 @@ export 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/lib/types/tool-history.d.ts

@@ -0,0 +1,29 @@
+/** Stateful reconstruction of historical tool definitions for request projection. */
+import type { ToolHistory } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent } from './types.ts';
+/** Folds committed headers and developer messages independently of model capability. */
+export declare class ToolHistoryProjection {
+    /** Historical declarations indexed by the header sequence referenced by additions. */
+    private readonly headers;
+    /** Definitions retained in the current declaration series, including removed tools. */
+    private declared;
+    /** Active definitions from the latest request header. */
+    private active;
+    /** Active names reconstructed from the baseline and recorded updates. */
+    private available;
+    /** Header that starts the current declaration series; absent before the first header. */
+    private baselineSeq;
+    /** Immutable request snapshot of the current baseline and resolved updates. */
+    private history;
+    /**
+     * Consume the next committed event in log order.
+     * @param event - a session event, including inherited events during restoration.
+     */
+    apply(event: SessionEvent): void;
+    /**
+     * Read an immutable snapshot; subsequent events do not mutate it.
+     * @returns initial declarations and historically resolved additions for the current series.
+     */
+    snapshot(): ToolHistory;
+}
+//# sourceMappingURL=tool-history.d.ts.map

package/lib/types/tool-history.js

@@ -0,0 +1,76 @@
+/** Stateful reconstruction of historical tool definitions for request projection. */
+import { deepFreeze } from '@deepseek-ai/dsh-util-values';
+/** Folds committed headers and developer messages independently of model capability. */
+export class ToolHistoryProjection {
+    /** Historical declarations indexed by the header sequence referenced by additions. */
+    headers = new Map();
+    /** Definitions retained in the current declaration series, including removed tools. */
+    declared = new Map();
+    /** Active definitions from the latest request header. */
+    active = [];
+    /** Active names reconstructed from the baseline and recorded updates. */
+    available = 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);
+            // A retained name cannot acquire a different definition without losing
+            // prefix reuse; an unchanged restored name is re-offered by its recorded addition.
+            const redeclared = tools.some((tool) => {
+                const before = this.declared.get(tool.name);
+                return before !== undefined && JSON.stringify(before) !== JSON.stringify(tool);
+            });
+            if (this.baselineSeq === undefined || 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 === undefined ? [] : 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 === undefined)
+                    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() {
+        // Sessions written before tool-update emission have headers without matching updates.
+        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;
+    }
+}
+//# sourceMappingURL=tool-history.js.map

package/lib/types/types.d.ts

@@ -241,9 +241,9 @@ export interface RequestContext {
  * Why a `request/header` snapshot was appended: `'initial'` — the log's first
  * header (a new conversation); `'resume'` — a loop instance's first request
  * over a log that already has header events (process restart, fork seed);
- * `'change'` — a later request used a different header, with `startsSeries`
- * preserving a coincident series boundary; `'series'` — an unchanged header
- * began an explicitly distinct message series or followed a surface replacement.
+ * `'change'` — a later request used a different header; `'series'` — an unchanged
+ * header began an explicitly distinct message series or followed a surface
+ * replacement. Other reasons carry `startsSeries` when a new series coincides.
  */
 export type RequestHeaderReason = 'initial' | 'resume' | 'change' | 'series';
 /**
@@ -393,7 +393,7 @@ export interface SessionEventMap {
     'request/header': {
         header: EpochHeader;
         reason: RequestHeaderReason;
-        /** A changed header also begins a distinct model-message series. */
+        /** This request begins a distinct model-message series, independently of the header reason. */
         startsSeries?: true;
     };
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.1.7-alpha.2",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -45,19 +45,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-scope": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-scope": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-typert-registry": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "0.1.7-rc.2",
     "@deepseek-ai/cordis": "~4.0.4"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-brand": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-util-values": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-brand": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-rc.2"
   }
 }