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

package/README.i18n.yaml

@@ -1,6 +1,61 @@
-# 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/test-support/session-snapshot/README.md
-README.md: 2bc7b9eaf9ebd8e7a2fa357e60eddd594d21d9a7
-README.zh.md: ea26aa50d9dc835c8f234ad224afff9f5a33483e
+/:
+  en: 35f64a68381efbd0
+  zh: dd2c508ba263d788
+/deepseek-ai-dsh-session-snapshot:
+  en: b184b97e2d1e1fa7
+  zh: 7d4b4cc8d73446af
+/deepseek-ai-dsh-session-snapshot/summary:
+  en: 71cd3441e7189ac4
+  zh: 874ae7ac5fd231c9
+/deepseek-ai-dsh-session-snapshot/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-session-snapshot/use-this-package:
+  en: 594ad1f3e6f02054
+  zh: 7ca4f565976704be
+/deepseek-ai-dsh-session-snapshot/use-this-package/writing-a-snapshot-suite:
+  en: b753e44790d4df99
+  zh: 5547c21757797d9b
+/deepseek-ai-dsh-session-snapshot/use-this-package/record-replay-and-refresh:
+  en: 4c4b1d6a459d2dc6
+  zh: 10c1bb216c50fea8
+/deepseek-ai-dsh-session-snapshot/use-this-package/pinning-request-headers-and-system-prompts:
+  en: 6b11d5111e1a3222
+  zh: de4d3889b1a5ebb4
+/deepseek-ai-dsh-session-snapshot/use-this-package/platform-and-composition-variants:
+  en: 64666ea2894acc4a
+  zh: 0e78df32bcfd3633
+/deepseek-ai-dsh-session-snapshot/use-this-package/what-can-go-wrong:
+  en: f9dc0b285401e01e
+  zh: e2b365b082dbaa82
+/deepseek-ai-dsh-session-snapshot/understand-the-implementation:
+  en: 18ff76b440fe40da
+  zh: 4dbf2eb5f9ee98a2
+/deepseek-ai-dsh-session-snapshot/understand-the-implementation/design:
+  en: 8771607f15c4f4e1
+  zh: 7c2cf395f704717c
+/deepseek-ai-dsh-session-snapshot/understand-the-implementation/source-map:
+  en: 4c3ff235ca8fe261
+  zh: 0f03425b926721cc
+/deepseek-ai-dsh-session-snapshot/understand-the-implementation/data-flow:
+  en: a71c8ab2e78798c5
+  zh: 419cebed1c023fbf
+/deepseek-ai-dsh-session-snapshot/further-exploration:
+  en: 84279d50373a156a
+  zh: fcd600bf386f6efe
+/deepseek-ai-dsh-session-snapshot/model-experience:
+  en: 9f12d94ab5e31ade
+  zh: 7c75a17565caca1c
+/deepseek-ai-dsh-session-snapshot/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: f57cc48a1b5cbfa9
+/deepseek-ai-dsh-session-snapshot/known-limitations-and-deferred-work:
+  en: 42e871839dddaf6d
+  zh: b7ab1d313527612b
+/deepseek-ai-dsh-session-snapshot/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -84,7 +84,7 @@ Headless/ACP and SDK adapters compare raw catalog child-creation times with harv
 
 ### Pinning request headers and system prompts
 
-A pin owns its generated `system-prompt.expected.md` or `tool-schemas.expected.json` sidecar by default; `systemPromptSource` and `toolSchemasSource` name another pin when the complete corresponding sequence is identical, so each distinct version is committed once. The system prompt is surface node 0, logged as a `system/message` event before the step's first `request/header`; every fixture stores its text block as `"text":"{{system}}"` and the prompt sidecar keeps the full text. The pin's `request/header` events store `"tools":"{{tools}}"` while retaining config and reason, and the structured schema sidecar keeps the full catalogs. A child Session whose own scope composes a different request declares it per fixture index with `pinsChildToolSchemas` and `pinsChildSystemPrompts`. A scenario that changes the request header mid-run declares `expectedHeaderChanges`; a scenario whose prompt changes mid-run — replacing node 0, or appending after the cached history on an `in-history` route — declares `expectedPromptChanges`, and each change adds a `<!-- system/message change N -->` section to the prompt sidecar. The manifest spells these `header.changes` and `header.promptChanges`.
+A pin owns its generated `system-prompt.expected.md` or `tool-schemas.expected.json` sidecar by default; `systemPromptSource` and `toolSchemasSource` name another pin when the complete corresponding sequence is identical, so each distinct version is committed once. The system prompt is surface node 0, logged as a `system/message` event before the step's first `request/header`; every fixture stores its text block as `"text":"{{system}}"` and the prompt sidecar keeps the full text. The pin's `request/header` events store `"tools":"{{tools}}"` while retaining config and reason, and the structured schema sidecar keeps the full catalogs. Logs containing developer messages retain ordered tool names in each header instead of the token so historical addition references remain verifiable. A child Session whose own scope composes a different request declares it per fixture index with `pinsChildToolSchemas` and `pinsChildSystemPrompts`. A scenario that changes the request header mid-run declares `expectedHeaderChanges`; a scenario whose prompt changes mid-run — replacing node 0, or appending after the cached history on an `in-history` route — declares `expectedPromptChanges`, and each change adds a `<!-- system/message change N -->` section to the prompt sidecar. The manifest spells these `header.changes` and `header.promptChanges`.
 
 ### Platform and composition variants
 

package/README.zh.md

@@ -84,7 +84,7 @@ Headless/ACP 与 SDK 适配器在规范化之前，将原始目录中的子创
 
 ### 固定请求 header 与系统提示
 
-每个 pin 默认拥有其生成的 `system-prompt.expected.md` 或 `tool-schemas.expected.json` 伴随文件；当完整的对应序列相同时，`systemPromptSource` 与 `toolSchemasSource` 指定另一个 pin 作为来源，因此每个不同版本只提交一次。系统提示是 surface 节点 0，作为 `system/message` 事件记录在该步骤第一个 `request/header` 之前；每个 fixture 把其文本块存储为 `"text":"{{system}}"`，提示词伴随文件保留完整文本。该 pin 的 `request/header` 事件存储 `"tools":"{{tools}}"`，同时保留配置与原因，结构化 schema 伴随文件保留完整目录。自身作用域组合出不同请求的 child Session 按 fixture 索引以 `pinsChildToolSchemas` 与 `pinsChildSystemPrompts` 单独声明。运行中改变请求 header 的场景声明 `expectedHeaderChanges`；运行中提示词发生变化的场景——替换节点 0，或在 `in-history` 路由上追加到已缓存历史之后——声明 `expectedPromptChanges`，每次变化在提示词伴随文件中增加一个 `<!-- system/message change N -->` 小节。manifest 中对应字段为 `header.changes` 与 `header.promptChanges`。
+每个 pin 默认拥有其生成的 `system-prompt.expected.md` 或 `tool-schemas.expected.json` 伴随文件；当完整的对应序列相同时，`systemPromptSource` 与 `toolSchemasSource` 指定另一个 pin 作为来源，因此每个不同版本只提交一次。系统提示是 surface 节点 0，作为 `system/message` 事件记录在该步骤第一个 `request/header` 之前；每个 fixture 把其文本块存储为 `"text":"{{system}}"`，提示词伴随文件保留完整文本。该 pin 的 `request/header` 事件存储 `"tools":"{{tools}}"`，同时保留配置与原因，结构化 schema 伴随文件保留完整目录。包含 developer 消息的日志会在各 header 中保留有序工具名，而不使用 token，以便继续校验历史工具添加引用。自身作用域组合出不同请求的 child Session 按 fixture 索引以 `pinsChildToolSchemas` 与 `pinsChildSystemPrompts` 单独声明。运行中改变请求 header 的场景声明 `expectedHeaderChanges`；运行中提示词发生变化的场景——替换节点 0，或在 `in-history` 路由上追加到已缓存历史之后——声明 `expectedPromptChanges`，每次变化在提示词伴随文件中增加一个 `<!-- system/message change N -->` 小节。manifest 中对应字段为 `header.changes` 与 `header.promptChanges`。
 
 ### 平台与组合变体
 

package/lib/index.js

@@ -1512,7 +1512,9 @@ function scrubSystemPrompts(rawLog) {
 }
 /**
 * Replace tool schemas in full request-header snapshots with `{{tools}}`
-* tokens while retaining field presence. System-prompt text stays verbatim so
+* tokens while retaining field presence. Logs containing developer messages
+* retain tool names so historical addition references remain verifiable.
+* System-prompt text stays verbatim so
 * pinning fixtures can move only schema bulk into their dedicated JSON
 * sidecar. Lines without a tool payload pass through byte-for-byte; the
 * transform is idempotent.
@@ -1583,9 +1585,12 @@ function systemPromptBlock(data) {
 }
 /** Transform the selected model-request payloads. */
 function scrubModelRequestContent(rawLog, options) {
-	return rawLog.split("\n").map((line) => {
-		if (line.trim().length === 0) return line;
-		const record = JSON.parse(line);
+	const lines = rawLog.split("\n");
+	const records = lines.map((line) => line.trim().length === 0 ? void 0 : JSON.parse(line));
+	const retainToolNames = records.some((record) => record?.type === "developer/message");
+	return lines.map((line, index) => {
+		const record = records[index];
+		if (record === void 0) return line;
 		const data = record.data;
 		if (data === null || typeof data !== "object") return line;
 		if (options.system === true && record.type === "system/message") {
@@ -1597,7 +1602,7 @@ function scrubModelRequestContent(rawLog, options) {
 		if (options.tools === true && record.type === "request/header") {
 			const header = data.header;
 			if (header === null || typeof header !== "object" || !("tools" in header)) return line;
-			header.tools = TOOLS;
+			header.tools = retainToolNames && Array.isArray(header.tools) ? header.tools.map((tool) => typeof tool === "string" ? tool : tool.name) : TOOLS;
 			return JSON.stringify(record);
 		}
 		return line;
@@ -2105,13 +2110,18 @@ function parseToolSchemasSnapshot(snapshot) {
 /**
 * Restore one sidecar schema set into a tokenized pinned header.
 *
-* @param header The parsed request header carrying `tools: "{{tools}}"`.
+* @param header The parsed request header carrying a tools token or ordered tool names matching the sidecar.
 * @param schemas The complete schemas for this full header snapshot.
 * @returns A copy of the header with its complete schemas restored.
 */
 function restorePinnedToolSchemas(header, schemas) {
 	if (header === null || typeof header !== "object" || Array.isArray(header)) throw new Error("acp-snapshot: pinned request header must be an object");
-	if (header.tools !== TOOLS_TOKEN) throw new Error(`acp-snapshot: pinned request header tools must equal ${TOOLS_TOKEN}`);
+	const tools = header.tools;
+	const namesMatch = Array.isArray(tools) && tools.length === schemas.length && tools.every((name, index) => {
+		const schema = schemas[index];
+		return typeof name === "string" && schema !== null && typeof schema === "object" && "name" in schema && schema.name === name;
+	});
+	if (tools !== TOOLS_TOKEN && !namesMatch) throw new Error(`acp-snapshot: pinned request header tools must equal ${TOOLS_TOKEN} or the ordered sidecar tool names`);
 	return {
 		...header,
 		tools: schemas

package/lib/types/normalize.d.ts

@@ -119,7 +119,9 @@ export declare function normalizeSessionFormatMetadata(rawLog: string, sourceVer
 export declare function scrubSystemPrompts(rawLog: string): string;
 /**
  * Replace tool schemas in full request-header snapshots with `{{tools}}`
- * tokens while retaining field presence. System-prompt text stays verbatim so
+ * tokens while retaining field presence. Logs containing developer messages
+ * retain tool names so historical addition references remain verifiable.
+ * System-prompt text stays verbatim so
  * pinning fixtures can move only schema bulk into their dedicated JSON
  * sidecar. Lines without a tool payload pass through byte-for-byte; the
  * transform is idempotent.

package/lib/types/suite.d.ts

@@ -312,7 +312,7 @@ export declare function parseToolSchemasSnapshot(snapshot: string): ToolSchemasS
 /**
  * Restore one sidecar schema set into a tokenized pinned header.
  *
- * @param header The parsed request header carrying `tools: "{{tools}}"`.
+ * @param header The parsed request header carrying a tools token or ordered tool names matching the sidecar.
  * @param schemas The complete schemas for this full header snapshot.
  * @returns A copy of the header with its complete schemas restored.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-snapshot",
   "description": "Session-log snapshot core with an ACP protocol adapter, expected-output normalization, and fixture invariants",
-  "version": "0.1.7-alpha.2",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -30,29 +30,29 @@
     "@agentclientprotocol/sdk": "1.4.0",
     "js-yaml": "^4.2.0",
     "vitest": "^4.1.8",
-    "@deepseek-ai/dsh-session-format": "0.1.7-alpha.2",
     "@deepseek-ai/cordis-plugin-include": "~1.0.9",
-    "@deepseek-ai/dsh-llm-replay": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-loader-smoke": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-llm-replay": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-loader-smoke": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-format": "0.1.7-rc.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-http-proxy": "0.1.7-alpha.2",
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-http-proxy": "0.1.7-rc.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-agent": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-compaction": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-subagent": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-user-questions": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-http-proxy": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2"
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-compaction": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-user-questions": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-http-proxy": "0.1.7-rc.2"
   }
 }