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

package/README.i18n.yaml

@@ -42,11 +42,14 @@
   en: bbfb53c50100ab13
   zh: 303a8ee47f4f656a
 /deepseek-ai-dsh-session/understand-the-implementation/source-map:
-  en: e87f7ef34effbad2
-  zh: 774a98d23611f5f5
+  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
@@ -71,16 +74,16 @@
 /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:
+/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: 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:
+  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:

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
 

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 影响
 

package/lib/index.js

@@ -714,12 +714,9 @@ var ToolHistoryProjection = class {
 //#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. */
@@ -739,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.
+* 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.
 */
 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++),
@@ -853,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.
@@ -1890,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

@@ -18,7 +18,7 @@ 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';

package/lib/types/index.js

@@ -18,7 +18,7 @@ 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";

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