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

package/README.i18n.yaml

@@ -1,6 +1,106 @@
-# 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: 1268738282846f1d
+  zh: 75a9fe0d5088ea09
+/deepseek-ai-dsh-session/understand-the-implementation/append-validation:
+  en: 5c09583bc8e1ffc6
+  zh: 3b25552de2d1f9b6
+/deepseek-ai-dsh-session/understand-the-implementation/shared-recovery:
+  en: 76bb076736b2dd0f
+  zh: de8306afc1e5faa1
+/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/tool-result-recovery-and-fork-results:
+  en: 9c2efc3e9064e3c4
+  zh: 9a7783991b322750
+/deepseek-ai-dsh-session/model-experience/tool-result-recovery-and-fork-results/what-the-model-sees:
+  en: b2ae41b23519cdc6
+  zh: 0e80c34e3267d098
+/deepseek-ai-dsh-session/model-experience/tool-result-recovery-and-fork-results/token-effect:
+  en: 1339facbd3d7cee0
+  zh: 9d392a053ef90032
+/deepseek-ai-dsh-session/model-experience/tool-result-recovery-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

@@ -100,13 +100,17 @@ The package is built on event sourcing: a `Session` is an append-only log of typ
 | [`src/surface.ts`](src/surface.ts) | Ordered surface projection, replacement validation, `deriveEventMessage` |
 | [`src/request-header.ts`](src/request-header.ts) | `request/header` folding and reconstruction |
 | [`dsh-util-values`](../../util/values/README.md) | Shared lossless JSON validation and detached snapshots |
-| [`src/repair.ts`](src/repair.ts) | Cold repair of crash-orphaned logs |
+| [`src/repair.ts`](src/repair.ts) | Shared tool-result recovery for failed steps, interrupted logs, and fork seeds |
 | [`src/invariant.ts`](src/invariant.ts) | Invariant companion: seq, turn/step enclosure, tool call/result pairing |
 
 ### Append validation
 
 Every append uses the shared iterative `snapshotJsonValue()` pass, which reads, validates, and copies each nested value once, so a stateful getter cannot supply one value to validation and another to storage. Non-lossless-JSON payloads (BigInt, cycles, sparse arrays, `-0`, exotic prototypes) are rejected at the append site, before any backend flush. The append path constructs each `SessionSeq`; surface events additionally validate marker shape, cited source-event sequences, and complete shadowed-node coverage for replacements.
 
+### Shared recovery
+
+`ToolCallRecovery` tracks unanswered requests from committed events without retaining event history. AgentLoop observes live steps; crash recovery and fork-seed construction replay their prefixes through `openTurnClosers`. Live failures and crash recovery use interrupted-result wording by default; fork construction passes the fork cause to select its distinct retry guidance. The caller appends recovery results before closing the step ([decision](../../../.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.md)).
+
 ### Derived history
 
 `deriveMessages()` caches deep-frozen projections and returns a fresh array per call. The surface event types (`system/message`, `developer/message`, `user/message`, `assistant/message`, `tool/result`) supply their recorded message identities and content; empty-content system and developer nodes project to no message. Plugin-owned projections change derived content without mutating recorded messages. Replacements and projection decisions invalidate the cache. Embedded Assistant streams and `assistant/attempt` events remain replay and diagnostic data only.
@@ -149,7 +153,7 @@ Appended surface entries are resent on later steps. A `replace` surface operatio
 
 Appended surface entries preserve reusable prefixes. A `replace` operation invalidates reuse from the first shadowed message even though the underlying event log stays append-only.
 
-### Crash-repair and fork results
+### Tool-result recovery and fork results
 
 #### What the model sees
 
@@ -157,7 +161,7 @@ If recovery finds an assistant tool request with no durable `tool/call`, its syn
 
 #### Token effect
 
-Zero tokens in an intact session. Each repaired call adds its retained risk-specific error text on resume.
+Zero tokens in an intact session. Each repaired call adds its retained risk-specific error text to later requests.
 
 #### KV Cache effect
 
@@ -167,7 +171,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

@@ -100,13 +100,17 @@ session.deriveMessages()         // the derived model history
 | [`src/surface.ts`](src/surface.ts) | 有序 surface 投影、替换校验、`deriveEventMessage` |
 | [`src/request-header.ts`](src/request-header.ts) | `request/header` 折叠与重建 |
 | [`dsh-util-values`](../../util/values/README.zh.md) | 共享无损 JSON 校验与分离式快照 |
-| [`src/repair.ts`](src/repair.ts) | 崩溃遗留日志的冷修复 |
+| [`src/repair.ts`](src/repair.ts) | 失败步骤、中断日志与 fork 种子共享的工具结果恢复 |
 | [`src/invariant.ts`](src/invariant.ts) | 不变式配套：序号、轮次／步骤闭合、工具调用／结果配对 |
 
 ### 追加校验
 
 每次追加都会使用共享的迭代式 `snapshotJsonValue()` 流程，对每个嵌套值只读取、校验并复制一次，因此有状态的 getter 无法给校验提供一个值、给存储提供另一个值。非无损 JSON 载荷（BigInt、循环、稀疏数组、`-0`、特殊原型）会在追加位置被拒绝，先于任何后端刷新。追加路径会构造每个 `SessionSeq`；surface 事件还会校验标记形态、被引用的源事件序号，以及替换的完整遮蔽节点覆盖。
 
+### 共享恢复逻辑
+
+`ToolCallRecovery` 从已提交事件中跟踪尚无结果的请求，不保留事件历史。AgentLoop 观察实时步骤；崩溃恢复与 fork 种子构造通过 `openTurnClosers` 回放各自的前缀。实时失败与崩溃恢复默认使用中断结果文案；fork 构造传入 fork 原因，以选择其专用的重试指引。调用方在关闭步骤之前追加恢复结果（[决策](../../../.agents/notes/implemented/bug-fix/2026-09-19-failed-step-tool-results.zh.md)）。
+
 ### 派生历史
 
 `deriveMessages()` 缓存深度冻结的派生消息，每次调用返回新数组。surface 事件类型（`system/message`、`developer/message`、`user/message`、`assistant/message`、`tool/result`）提供记录的消息身份和内容，空内容的 system 和 developer 节点不派生消息。插件拥有的投影修改派生内容，不修改记录的消息。替换和投影决策使缓存失效。嵌入式 Assistant stream 与 `assistant/attempt` 事件只保留回放和诊断数据。
@@ -149,17 +153,15 @@ session.deriveMessages()         // the derived model history
 
 追加的 surface 条目会保留可复用前缀。即使底层事件日志保持仅追加，`replace` 操作也会从首条被遮蔽消息起使缓存复用失效。
 
-### 崩溃修复结果
+### 工具结果恢复与 fork 结果
 
 #### 模型看到什么
 
-如果恢复发现 assistant 工具请求没有持久 `tool/call`，其合成 `TOOL_NOT_STARTED` 结果内容为 `The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed.`。如果持久 `tool/call` 没有结果，其 `TOOL_OUTCOME_UNKNOWN` 结果内容为 `The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.`。
-
-Fork 生成的结果只描述继承记录：父会话可能已经在所选事件之后启动或完成调用。`TOOL_NOT_STARTED` 表示前缀中没有启动记录；`TOOL_OUTCOME_UNKNOWN` 表示有启动记录但没有结果。两者都要求模型仅对只读或幂等操作直接重试；有副作用的操作需要先验证外部状态或询问用户。参见 [fork 决策](../../../.agents/notes/implemented/feature/2026-08-18-arbitrary-seq-session-fork.zh.md)。
+如果恢复发现 assistant 工具请求没有持久 `tool/call`，其合成 `TOOL_NOT_STARTED` 结果内容为 `The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed.`。如果持久 `tool/call` 没有结果，其 `TOOL_OUTCOME_UNKNOWN` 结果内容为 `The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.`。 Fork 生成的结果只描述继承记录：父会话可能已经在所选事件之后启动或完成调用。`TOOL_NOT_STARTED` 表示前缀中没有启动记录；`TOOL_OUTCOME_UNKNOWN` 表示有启动记录但没有结果。两者都要求模型仅对只读或幂等操作直接重试；有副作用的操作需要先验证外部状态或询问用户。参见 [fork 决策](../../../.agents/notes/implemented/feature/2026-08-18-arbitrary-seq-session-fork.zh.md)。
 
 #### Token 影响
 
-未受损会话的 token 增量为零。恢复时，每个修复后的调用都会添加保留的、针对具体风险的错误文本。
+未受损会话的 token 增量为零。每个修复后的调用都会向后续请求添加保留的、针对具体风险的错误文本。
 
 #### KV Cache 影响
 
@@ -169,7 +171,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,14 +637,86 @@ 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.
-* Two producers share the mechanism: crash recovery closes an interrupted
-* persisted log on reload, and fork-seed construction closes a prefix cut
-* inside the source's open turn. Both preserve every fully written event and
-* close the unfinished step and turn. Calls in already closed steps remain
-* unchanged, including any missing results.
+* Pending tool-result recovery shared by failed live steps, interrupted logs,
+* and fork seeds. Tail repair preserves closed steps and supplies only missing
+* tool results and lifecycle boundaries, with cause-specific retry guidance.
 * @module @deepseek-ai/dsh-session/repair
 */
 /** Recovery code for an assistant tool request that never reached a recorded call start. */
@@ -664,99 +736,43 @@ const CLOSER_TEXT = {
 };
 /**
 * Return deterministic synthetic events that close an open tail turn. Unmatched
-* calls in its open step receive error results, followed by `step/end` and a
-* `turn/end` carrying the cause's reason. Calls in closed steps remain unchanged.
-* Sequences continue the log and timestamps reuse the last real event. A balanced or empty log returns no
-* events.
-*
-* Package-internal: each cause has exactly one owner, so external callers go
-* through {@link interruptedTurnClosers} (persistence crash recovery) or
-* `buildForkSeed` in `./fork.ts` (fork seeds) instead of selecting a cause.
+* calls receive error results first, followed by an open `step/end` and a
+* cause-specific `turn/end`; sequences continue the log and timestamps reuse the
+* last real event. A balanced or empty log returns no events.
 *
-* @param events - the log to scan: a valid committed prefix, possibly ending
-*   inside an open turn (a crash tail or a mid-turn fork cut).
-* @param cause - why the turn is being closed; selects the `turn/end` reason
-*   and the model-visible wording of synthetic error tool results.
+* @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+* @param cause - the owning close operation: selects result wording and the turn-ending reason.
 * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
 */
 function openTurnClosers(events, cause) {
 	let openTurn = null;
 	let openStep = null;
-	const pendingCalls = /* @__PURE__ */ new Map();
-	for (const event of events) switch (event.type) {
-		case "turn/start":
-			openTurn = event.data.turn;
-			openStep = null;
-			pendingCalls.clear();
-			break;
-		case "turn/end":
-			openTurn = null;
-			openStep = null;
-			pendingCalls.clear();
-			break;
-		case "step/start":
-			openStep = event.data.step;
-			break;
-		case "step/end":
-			pendingCalls.clear();
-			openStep = null;
-			break;
-		case "assistant/message":
-			for (const block of event.data.message.content) if (block.type === "tool-call") pendingCalls.set(block.id, { step: event.data.step });
-			break;
-		case "tool/call":
-			{
-				const entry = pendingCalls.get(event.data.callId);
-				if (entry) entry.callSeq = event.seq;
-			}
-			break;
-		case "tool/result":
-			pendingCalls.delete(event.data.message.source.callId);
-			break;
-		default: break;
+	const recovery = new ToolCallRecovery(cause);
+	for (const event of events) {
+		recovery.observe(event);
+		switch (event.type) {
+			case "turn/start":
+				openTurn = event.data.turn;
+				openStep = null;
+				break;
+			case "turn/end":
+				openTurn = null;
+				openStep = null;
+				break;
+			case "step/start":
+				openStep = event.data.step;
+				break;
+			case "step/end":
+				openStep = null;
+				break;
+			default: break;
+		}
 	}
 	const last = events.at(-1);
 	if (openTurn === null || last === void 0) return [];
-	let seq = last.seq + 1;
+	const closers = recovery.results();
+	let seq = last.seq + closers.length + 1;
 	const time = last.time;
-	const closers = [];
-	const text = CLOSER_TEXT[cause.kind];
-	for (const [callId, { step, callSeq }] of pendingCalls) {
-		const started = callSeq !== void 0;
-		const message = deepFreeze({
-			id: brandString(`${cause.kind}-tool-result-${callId}-${seq}`),
-			role: "tool",
-			toolCallId: callId,
-			isError: true,
-			source: {
-				kind: "tool",
-				callId
-			},
-			content: [{
-				type: "text",
-				text: started ? text.started : text.notStarted
-			}]
-		});
-		closers.push({
-			type: "tool/result",
-			seq: SessionSeq(seq++),
-			time,
-			data: {
-				turn: openTurn,
-				step,
-				message,
-				error: started ? {
-					name: "ToolOutcomeUnknownError",
-					code: TOOL_OUTCOME_UNKNOWN
-				} : {
-					name: "ToolNotStartedError",
-					code: TOOL_NOT_STARTED
-				}
-			},
-			surfaceOp: "append",
-			...started ? { sourceEventSeqs: [callSeq] } : {}
-		});
-	}
 	if (openStep !== null) closers.push({
 		type: "step/end",
 		seq: SessionSeq(seq++),
@@ -778,10 +794,109 @@ function openTurnClosers(events, cause) {
 	return closers;
 }
 /**
+* Track unanswered assistant tool requests from one Session's committed events.
+* Observe from the start of the owned step or replay prefix, and recover before
+* its step closes. This state retains pending identities, not event history.
+*/
+var ToolCallRecovery = class {
+	cause;
+	pendingCalls = /* @__PURE__ */ new Map();
+	last;
+	/** @param cause - defaults to interrupted live/crash recovery; fork-seed construction supplies its own cause. */
+	constructor(cause = { kind: "interrupted" }) {
+		this.cause = cause;
+	}
+	/**
+	* Consume the next committed event; closed steps and turn boundaries discard pending requests.
+	* @param event - the next event from the same Session, in sequence order.
+	*/
+	observe(event) {
+		this.last = {
+			seq: event.seq,
+			time: event.time
+		};
+		switch (event.type) {
+			case "turn/start":
+			case "turn/end":
+			case "step/end":
+				this.pendingCalls.clear();
+				break;
+			case "assistant/message":
+				for (const block of event.data.message.content) if (block.type === "tool-call") this.pendingCalls.set(block.id, {
+					turn: event.data.turn,
+					step: event.data.step
+				});
+				break;
+			case "tool/call": {
+				const entry = this.pendingCalls.get(event.data.callId);
+				if (entry) entry.callSeq = event.seq;
+				break;
+			}
+			case "tool/result": {
+				const callId = event.data.message.source.callId;
+				const entry = this.pendingCalls.get(callId);
+				if (event.surfaceOp === "append" && entry !== void 0 && entry.turn === event.data.turn && entry.step === event.data.step) this.pendingCalls.delete(callId);
+				break;
+			}
+			default: break;
+		}
+	}
+	/**
+	* Build conservative error results in assistant order without changing tracked state.
+	* Sequences follow the latest observed event and timestamps reuse its time.
+	* Callers commit the results and observe those commits before recovering again.
+	* @returns pending tool-result events, empty when no request remains unanswered.
+	*/
+	results() {
+		if (this.last === void 0) return [];
+		let seq = this.last.seq + 1;
+		const time = this.last.time;
+		const results = [];
+		const text = CLOSER_TEXT[this.cause.kind];
+		for (const [callId, { turn, step, callSeq }] of this.pendingCalls) {
+			const started = callSeq !== void 0;
+			const message = deepFreeze({
+				id: brandString(`${this.cause.kind}-tool-result-${callId}-${seq}`),
+				role: "tool",
+				toolCallId: callId,
+				isError: true,
+				source: {
+					kind: "tool",
+					callId
+				},
+				content: [{
+					type: "text",
+					text: started ? text.started : text.notStarted
+				}]
+			});
+			results.push({
+				type: "tool/result",
+				seq: SessionSeq(seq++),
+				time,
+				data: {
+					turn,
+					step,
+					message,
+					error: started ? {
+						name: "ToolOutcomeUnknownError",
+						code: TOOL_OUTCOME_UNKNOWN
+					} : {
+						name: "ToolNotStartedError",
+						code: TOOL_NOT_STARTED
+					}
+				},
+				surfaceOp: "append",
+				...started ? { sourceEventSeqs: [callSeq] } : {}
+			});
+		}
+		return results;
+	}
+};
+/**
 * Crash-recovery entry point: synthetic closers that balance a persisted log
 * whose tail turn was interrupted. Used by crash-recovery callers; fork
 * seeds receive their `forked`-cause closers through `buildForkSeed` in
-* `./fork.ts`, and cause selection stays internal to those two owners.
+* `./fork.ts`.
 *
 * @param events - the persisted log to scan, possibly ending inside an open turn.
 * @returns the synthetic `interrupted` closer events to append after `events`; empty when the log is already balanced.
@@ -1398,6 +1513,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. */
@@ -1801,4 +1930,4 @@ var SessionStore = class extends Service {
 	}
 };
 //#endregion
-export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionLogOffset, SessionPreparation, SessionSeq, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, adoptSessionEvent, buildForkSeed, canonicalHeader, decodeSeqRanges, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, snapshotSessionEvent };
+export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionLogOffset, SessionPreparation, SessionSeq, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, ToolCallRecovery, adoptSessionEvent, buildForkSeed, canonicalHeader, decodeSeqRanges, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, snapshotSessionEvent };

package/lib/types/index.d.ts

@@ -12,12 +12,13 @@ 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';
 export type { SessionPreparationOptions } from './preparation.ts';
 export type { AssistantMessage, DeveloperMessage, SystemMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm';
-export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts';
+export { interruptedTurnClosers, ToolCallRecovery, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts';
 export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult, SessionMessageProjection, SessionMessageProjectionContext } from './surface.ts';
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts';
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.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,11 +13,12 @@ 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";
 export { SessionPreparation } from "./preparation.js";
-export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from "./repair.js";
+export { interruptedTurnClosers, ToolCallRecovery, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from "./repair.js";
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from "./surface.js";
 export { canonicalHeader, foldRequestHeader, headerEquals } from "./request-header.js";
 export { KNOWN_SESSION_EVENT_TYPES } from "./known-event-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/repair.d.ts

@@ -1,10 +1,7 @@
 /**
- * Synthetic closer events that balance a session log whose tail turn is open.
- * Two producers share the mechanism: crash recovery closes an interrupted
- * persisted log on reload, and fork-seed construction closes a prefix cut
- * inside the source's open turn. Both preserve every fully written event and
- * close the unfinished step and turn. Calls in already closed steps remain
- * unchanged, including any missing results.
+ * Pending tool-result recovery shared by failed live steps, interrupted logs,
+ * and fork seeds. Tail repair preserves closed steps and supplies only missing
+ * tool results and lifecycle boundaries, with cause-specific retry guidance.
  * @module @deepseek-ai/dsh-session/repair
  */
 import type { SessionEvent } from './types.ts';
@@ -28,27 +25,44 @@ export type OpenTurnCloseCause = {
 };
 /**
  * Return deterministic synthetic events that close an open tail turn. Unmatched
- * calls in its open step receive error results, followed by `step/end` and a
- * `turn/end` carrying the cause's reason. Calls in closed steps remain unchanged.
- * Sequences continue the log and timestamps reuse the last real event. A balanced or empty log returns no
- * events.
+ * calls receive error results first, followed by an open `step/end` and a
+ * cause-specific `turn/end`; sequences continue the log and timestamps reuse the
+ * last real event. A balanced or empty log returns no events.
  *
- * Package-internal: each cause has exactly one owner, so external callers go
- * through {@link interruptedTurnClosers} (persistence crash recovery) or
- * `buildForkSeed` in `./fork.ts` (fork seeds) instead of selecting a cause.
- *
- * @param events - the log to scan: a valid committed prefix, possibly ending
- *   inside an open turn (a crash tail or a mid-turn fork cut).
- * @param cause - why the turn is being closed; selects the `turn/end` reason
- *   and the model-visible wording of synthetic error tool results.
+ * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+ * @param cause - the owning close operation: selects result wording and the turn-ending reason.
  * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
  */
 export declare function openTurnClosers(events: readonly SessionEvent[], cause: OpenTurnCloseCause): SessionEvent[];
+/**
+ * Track unanswered assistant tool requests from one Session's committed events.
+ * Observe from the start of the owned step or replay prefix, and recover before
+ * its step closes. This state retains pending identities, not event history.
+ */
+export declare class ToolCallRecovery {
+    private readonly cause;
+    private readonly pendingCalls;
+    private last;
+    /** @param cause - defaults to interrupted live/crash recovery; fork-seed construction supplies its own cause. */
+    constructor(cause?: OpenTurnCloseCause);
+    /**
+     * Consume the next committed event; closed steps and turn boundaries discard pending requests.
+     * @param event - the next event from the same Session, in sequence order.
+     */
+    observe(event: SessionEvent): void;
+    /**
+     * Build conservative error results in assistant order without changing tracked state.
+     * Sequences follow the latest observed event and timestamps reuse its time.
+     * Callers commit the results and observe those commits before recovering again.
+     * @returns pending tool-result events, empty when no request remains unanswered.
+     */
+    results(): SessionEvent<'tool/result'>[];
+}
 /**
  * Crash-recovery entry point: synthetic closers that balance a persisted log
  * whose tail turn was interrupted. Used by crash-recovery callers; fork
  * seeds receive their `forked`-cause closers through `buildForkSeed` in
- * `./fork.ts`, and cause selection stays internal to those two owners.
+ * `./fork.ts`.
  *
  * @param events - the persisted log to scan, possibly ending inside an open turn.
  * @returns the synthetic `interrupted` closer events to append after `events`; empty when the log is already balanced.

package/lib/types/repair.js

@@ -1,10 +1,7 @@
 /**
- * Synthetic closer events that balance a session log whose tail turn is open.
- * Two producers share the mechanism: crash recovery closes an interrupted
- * persisted log on reload, and fork-seed construction closes a prefix cut
- * inside the source's open turn. Both preserve every fully written event and
- * close the unfinished step and turn. Calls in already closed steps remain
- * unchanged, including any missing results.
+ * Pending tool-result recovery shared by failed live steps, interrupted logs,
+ * and fork seeds. Tail repair preserves closed steps and supplies only missing
+ * tool results and lifecycle boundaries, with cause-specific retry guidance.
  * @module @deepseek-ai/dsh-session/repair
  */
 import { brandString } from '@deepseek-ai/dsh-brand';
@@ -27,66 +24,35 @@ const CLOSER_TEXT = {
 };
 /**
  * Return deterministic synthetic events that close an open tail turn. Unmatched
- * calls in its open step receive error results, followed by `step/end` and a
- * `turn/end` carrying the cause's reason. Calls in closed steps remain unchanged.
- * Sequences continue the log and timestamps reuse the last real event. A balanced or empty log returns no
- * events.
+ * calls receive error results first, followed by an open `step/end` and a
+ * cause-specific `turn/end`; sequences continue the log and timestamps reuse the
+ * last real event. A balanced or empty log returns no events.
  *
- * Package-internal: each cause has exactly one owner, so external callers go
- * through {@link interruptedTurnClosers} (persistence crash recovery) or
- * `buildForkSeed` in `./fork.ts` (fork seeds) instead of selecting a cause.
- *
- * @param events - the log to scan: a valid committed prefix, possibly ending
- *   inside an open turn (a crash tail or a mid-turn fork cut).
- * @param cause - why the turn is being closed; selects the `turn/end` reason
- *   and the model-visible wording of synthetic error tool results.
+ * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
+ * @param cause - the owning close operation: selects result wording and the turn-ending reason.
  * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
  */
 export function openTurnClosers(events, cause) {
     let openTurn = null;
     let openStep = null;
-    // Reset at each turn boundary so earlier calls cannot leak into tail repair.
-    // Assistant blocks register calls; later `tool/call` events add their seqs to `sourceEventSeqs`.
-    const pendingCalls = new Map();
+    const recovery = new ToolCallRecovery(cause);
     for (const event of events) {
+        recovery.observe(event);
         switch (event.type) {
             case 'turn/start':
                 openTurn = event.data.turn;
                 openStep = null;
-                pendingCalls.clear();
                 break;
             case 'turn/end':
                 openTurn = null;
                 openStep = null;
-                pendingCalls.clear();
                 break;
             case 'step/start':
                 openStep = event.data.step;
                 break;
             case 'step/end':
-                pendingCalls.clear();
                 openStep = null;
                 break;
-            case 'assistant/message':
-                // The assistant message carries the tool-call blocks; each is pending
-                // until a tool/result event with the same callId is logged.
-                for (const block of event.data.message.content) {
-                    if (block.type === 'tool-call')
-                        pendingCalls.set(block.id, { step: event.data.step });
-                }
-                break;
-            case 'tool/call':
-                // Cite the `tool/call` seq from the synthetic result.
-                {
-                    const entry = pendingCalls.get(event.data.callId);
-                    if (entry) {
-                        entry.callSeq = event.seq;
-                    }
-                }
-                break;
-            case 'tool/result':
-                pendingCalls.delete(event.data.message.source.callId);
-                break;
             // Other event types do not move the turn/step boundary cursor.
             default:
                 break;
@@ -100,53 +66,120 @@ export function openTurnClosers(events, cause) {
     // The last real event supplies the seq base and the timestamp for the
     // synthetic closers (reusing the last timestamp keeps them deterministic and
     // never invents a "future" time).
-    let seq = last.seq + 1;
+    const closers = recovery.results();
+    let seq = last.seq + closers.length + 1;
     const time = last.time;
-    const closers = [];
-    // Close calls before their step; Map insertion order preserves transcript order.
-    const text = CLOSER_TEXT[cause.kind];
-    for (const [callId, { step, callSeq }] of pendingCalls) {
-        const started = callSeq !== undefined;
-        const message = deepFreeze({
-            id: brandString(`${cause.kind}-tool-result-${callId}-${seq}`),
-            role: 'tool',
-            toolCallId: callId,
-            isError: true,
-            source: { kind: 'tool', callId },
-            content: [{
-                    type: 'text',
-                    text: started ? text.started : text.notStarted,
-                }],
-        });
-        closers.push({
-            type: 'tool/result',
-            seq: SessionSeq(seq++),
-            time,
-            data: {
-                turn: openTurn,
-                step,
-                message,
-                error: started
-                    ? { name: 'ToolOutcomeUnknownError', code: TOOL_OUTCOME_UNKNOWN }
-                    : { name: 'ToolNotStartedError', code: TOOL_NOT_STARTED },
-            },
-            surfaceOp: 'append',
-            ...started ? { sourceEventSeqs: [callSeq] } : {},
-        });
-    }
-    // Close an open step next — a turn/end while a step is open is an invariant
-    // violation, so the step's boundary must be synthesized before the turn's.
+    // Close an open step before its turn.
     if (openStep !== null) {
         closers.push({ type: 'step/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, step: openStep } });
     }
     closers.push({ type: 'turn/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, reason: { kind: cause.kind } } });
     return closers;
 }
+/**
+ * Track unanswered assistant tool requests from one Session's committed events.
+ * Observe from the start of the owned step or replay prefix, and recover before
+ * its step closes. This state retains pending identities, not event history.
+ */
+export class ToolCallRecovery {
+    cause;
+    pendingCalls = new Map();
+    last;
+    /** @param cause - defaults to interrupted live/crash recovery; fork-seed construction supplies its own cause. */
+    constructor(cause = { kind: 'interrupted' }) {
+        this.cause = cause;
+    }
+    /**
+     * Consume the next committed event; closed steps and turn boundaries discard pending requests.
+     * @param event - the next event from the same Session, in sequence order.
+     */
+    observe(event) {
+        this.last = { seq: event.seq, time: event.time };
+        switch (event.type) {
+            case 'turn/start':
+            case 'turn/end':
+            case 'step/end':
+                this.pendingCalls.clear();
+                break;
+            case 'assistant/message':
+                for (const block of event.data.message.content) {
+                    if (block.type === 'tool-call') {
+                        this.pendingCalls.set(block.id, { turn: event.data.turn, step: event.data.step });
+                    }
+                }
+                break;
+            case 'tool/call': {
+                const entry = this.pendingCalls.get(event.data.callId);
+                if (entry)
+                    entry.callSeq = event.seq;
+                break;
+            }
+            case 'tool/result': {
+                const callId = event.data.message.source.callId;
+                const entry = this.pendingCalls.get(callId);
+                if (event.surfaceOp === 'append' && entry !== undefined
+                    && entry.turn === event.data.turn && entry.step === event.data.step) {
+                    this.pendingCalls.delete(callId);
+                }
+                break;
+            }
+            // SessionEvent is merge-extensible; unrelated events retain pending requests.
+            default:
+                break;
+        }
+    }
+    /**
+     * Build conservative error results in assistant order without changing tracked state.
+     * Sequences follow the latest observed event and timestamps reuse its time.
+     * Callers commit the results and observe those commits before recovering again.
+     * @returns pending tool-result events, empty when no request remains unanswered.
+     */
+    results() {
+        if (this.last === undefined)
+            return [];
+        let seq = this.last.seq + 1;
+        const time = this.last.time;
+        const results = [];
+        const text = CLOSER_TEXT[this.cause.kind];
+        // Close calls before their step: providers reject dangling assistant calls,
+        // and Map insertion order preserves their transcript order.
+        for (const [callId, { turn, step, callSeq }] of this.pendingCalls) {
+            const started = callSeq !== undefined;
+            const message = deepFreeze({
+                id: brandString(`${this.cause.kind}-tool-result-${callId}-${seq}`),
+                role: 'tool',
+                toolCallId: callId,
+                isError: true,
+                source: { kind: 'tool', callId },
+                content: [{
+                        type: 'text',
+                        text: started ? text.started : text.notStarted,
+                    }],
+            });
+            results.push({
+                type: 'tool/result',
+                seq: SessionSeq(seq++),
+                time,
+                data: {
+                    turn,
+                    step,
+                    message,
+                    error: started
+                        ? { name: 'ToolOutcomeUnknownError', code: TOOL_OUTCOME_UNKNOWN }
+                        : { name: 'ToolNotStartedError', code: TOOL_NOT_STARTED },
+                },
+                surfaceOp: 'append',
+                ...started ? { sourceEventSeqs: [callSeq] } : {},
+            });
+        }
+        return results;
+    }
+}
 /**
  * Crash-recovery entry point: synthetic closers that balance a persisted log
  * whose tail turn was interrupted. Used by crash-recovery callers; fork
  * seeds receive their `forked`-cause closers through `buildForkSeed` in
- * `./fork.ts`, and cause selection stays internal to those two owners.
+ * `./fork.ts`.
  *
  * @param events - the persisted log to scan, possibly ending inside an open turn.
  * @returns the synthetic `interrupted` closer events to append after `events`; empty when the log is already balanced.

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-rc.1",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -45,19 +45,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-scope": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.1",
     "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-scope": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-typert-registry": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-invariants": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "0.2.0-rc.1",
     "@deepseek-ai/cordis": "~4.0.4"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-brand": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.1.7-rc.1"
+    "@deepseek-ai/dsh-brand": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-util-values": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.1"
   }
 }